Andrew Gerrand | 7cb21a7 | 2012-01-19 11:24:54 +1100 | [diff] [blame] | 1 | <!--{ |
| 2 | "Title": "The Go Programming Language Specification", |
Russ Cox | b7ba523 | 2018-11-13 10:23:01 -0500 | [diff] [blame] | 3 | "Subtitle": "Version of November 16, 2018", |
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> |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 23 | The grammar is compact and regular, allowing for easy analysis by |
| 24 | automatic tools such as integrated development environments. |
| 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" . |
| 121 | octal_digit = "0" … "7" . |
| 122 | hex_digit = "0" … "9" | "A" … "F" | "a" … "f" . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 123 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 124 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 125 | <h2 id="Lexical_elements">Lexical elements</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 126 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 127 | <h3 id="Comments">Comments</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 128 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 129 | <p> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 130 | Comments serve as program documentation. There are two forms: |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 131 | </p> |
| 132 | |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 133 | <ol> |
| 134 | <li> |
| 135 | <i>Line comments</i> start with the character sequence <code>//</code> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 136 | and stop at the end of the line. |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 137 | </li> |
| 138 | <li> |
| 139 | <i>General comments</i> start with the character sequence <code>/*</code> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 140 | and stop with the first subsequent character sequence <code>*/</code>. |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 141 | </li> |
| 142 | </ol> |
| 143 | |
| 144 | <p> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 145 | A comment cannot start inside a <a href="#Rune_literals">rune</a> or |
| 146 | <a href="#String_literals">string literal</a>, or inside a comment. |
| 147 | A general comment containing no newlines acts like a space. |
| 148 | Any other comment acts like a newline. |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 149 | </p> |
| 150 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 151 | <h3 id="Tokens">Tokens</h3> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 152 | |
| 153 | <p> |
| 154 | Tokens form the vocabulary of the Go language. |
Robert Griesemer | eb109a7 | 2009-12-28 14:40:42 -0800 | [diff] [blame] | 155 | There are four classes: <i>identifiers</i>, <i>keywords</i>, <i>operators |
Robert Griesemer | 26e726c | 2017-03-10 17:17:23 -0800 | [diff] [blame] | 156 | 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] | 157 | spaces (U+0020), horizontal tabs (U+0009), |
| 158 | carriage returns (U+000D), and newlines (U+000A), |
| 159 | is ignored except as it separates tokens |
Robert Griesemer | 0e66a13 | 2010-09-27 18:59:11 -0700 | [diff] [blame] | 160 | 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] | 161 | may trigger the insertion of a <a href="#Semicolons">semicolon</a>. |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 162 | While breaking the input into tokens, |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 163 | the next token is the longest sequence of characters that form a |
| 164 | valid token. |
| 165 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 166 | |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 167 | <h3 id="Semicolons">Semicolons</h3> |
| 168 | |
| 169 | <p> |
| 170 | The formal grammar uses semicolons <code>";"</code> as terminators in |
| 171 | a number of productions. Go programs may omit most of these semicolons |
| 172 | using the following two rules: |
| 173 | </p> |
| 174 | |
| 175 | <ol> |
| 176 | <li> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 177 | When the input is broken into tokens, a semicolon is automatically inserted |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 178 | 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] | 179 | <ul> |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 180 | <li>an |
| 181 | <a href="#Identifiers">identifier</a> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 182 | </li> |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 183 | |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 184 | <li>an |
| 185 | <a href="#Integer_literals">integer</a>, |
| 186 | <a href="#Floating-point_literals">floating-point</a>, |
| 187 | <a href="#Imaginary_literals">imaginary</a>, |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 188 | <a href="#Rune_literals">rune</a>, or |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 189 | <a href="#String_literals">string</a> literal |
| 190 | </li> |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 191 | |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 192 | <li>one of the <a href="#Keywords">keywords</a> |
| 193 | <code>break</code>, |
| 194 | <code>continue</code>, |
| 195 | <code>fallthrough</code>, or |
| 196 | <code>return</code> |
| 197 | </li> |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 198 | |
Robert Griesemer | 26e726c | 2017-03-10 17:17:23 -0800 | [diff] [blame] | 199 | <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] | 200 | <code>++</code>, |
| 201 | <code>--</code>, |
| 202 | <code>)</code>, |
| 203 | <code>]</code>, or |
| 204 | <code>}</code> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 205 | </li> |
| 206 | </ul> |
| 207 | </li> |
| 208 | |
| 209 | <li> |
| 210 | To allow complex statements to occupy a single line, a semicolon |
| 211 | may be omitted before a closing <code>")"</code> or <code>"}"</code>. |
| 212 | </li> |
| 213 | </ol> |
| 214 | |
| 215 | <p> |
| 216 | To reflect idiomatic use, code examples in this document elide semicolons |
| 217 | using these rules. |
| 218 | </p> |
| 219 | |
| 220 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 221 | <h3 id="Identifiers">Identifiers</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 222 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 223 | <p> |
| 224 | Identifiers name program entities such as variables and types. |
| 225 | An identifier is a sequence of one or more letters and digits. |
| 226 | The first character in an identifier must be a letter. |
| 227 | </p> |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 228 | <pre class="ebnf"> |
Robert Griesemer | d36d191 | 2009-09-18 11:58:35 -0700 | [diff] [blame] | 229 | identifier = letter { letter | unicode_digit } . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 230 | </pre> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 231 | <pre> |
| 232 | a |
| 233 | _x9 |
| 234 | ThisVariableIsExported |
| 235 | αβ |
| 236 | </pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 237 | |
| 238 | <p> |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 239 | Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>. |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 240 | </p> |
| 241 | |
Robert Griesemer | 7a4ed4f | 2008-09-03 15:15:51 -0700 | [diff] [blame] | 242 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 243 | <h3 id="Keywords">Keywords</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 244 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 245 | <p> |
| 246 | The following keywords are reserved and may not be used as identifiers. |
| 247 | </p> |
| 248 | <pre class="grammar"> |
| 249 | break default func interface select |
| 250 | case defer go map struct |
| 251 | chan else goto package switch |
| 252 | const fallthrough if range type |
| 253 | continue for import return var |
| 254 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 255 | |
Robert Griesemer | 26e726c | 2017-03-10 17:17:23 -0800 | [diff] [blame] | 256 | <h3 id="Operators_and_punctuation">Operators and punctuation</h3> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 257 | |
| 258 | <p> |
Robert Griesemer | 26e726c | 2017-03-10 17:17:23 -0800 | [diff] [blame] | 259 | The following character sequences represent <a href="#Operators">operators</a> |
| 260 | (including <a href="#assign_op">assignment operators</a>) and punctuation: |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 261 | </p> |
| 262 | <pre class="grammar"> |
| 263 | + & += &= && == != ( ) |
| 264 | - | -= |= || < <= [ ] |
| 265 | * ^ *= ^= <- > >= { } |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 266 | / << /= <<= ++ = := , ; |
| 267 | % >> %= >>= -- ! ... . : |
Robert Griesemer | 0eb26fa | 2016-11-18 09:27:18 -0800 | [diff] [blame] | 268 | &^ &^= |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 269 | </pre> |
| 270 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 271 | <h3 id="Integer_literals">Integer literals</h3> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 272 | |
| 273 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 274 | An integer literal is a sequence of digits representing an |
| 275 | <a href="#Constants">integer constant</a>. |
| 276 | An optional prefix sets a non-decimal base: <code>0</code> for octal, <code>0x</code> or |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 277 | <code>0X</code> for hexadecimal. In hexadecimal literals, letters |
| 278 | <code>a-f</code> and <code>A-F</code> represent values 10 through 15. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 279 | </p> |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 280 | <pre class="ebnf"> |
Robert Griesemer | d36d191 | 2009-09-18 11:58:35 -0700 | [diff] [blame] | 281 | int_lit = decimal_lit | octal_lit | hex_lit . |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 282 | decimal_lit = ( "1" … "9" ) { decimal_digit } . |
Robert Griesemer | d36d191 | 2009-09-18 11:58:35 -0700 | [diff] [blame] | 283 | octal_lit = "0" { octal_digit } . |
| 284 | hex_lit = "0" ( "x" | "X" ) hex_digit { hex_digit } . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 285 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 286 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 287 | <pre> |
| 288 | 42 |
| 289 | 0600 |
| 290 | 0xBadFace |
| 291 | 170141183460469231731687303715884105727 |
| 292 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 293 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 294 | <h3 id="Floating-point_literals">Floating-point literals</h3> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 295 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 296 | A floating-point literal is a decimal representation of a |
| 297 | <a href="#Constants">floating-point constant</a>. |
| 298 | It has an integer part, a decimal point, a fractional part, |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 299 | and an exponent part. The integer and fractional part comprise |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 300 | decimal digits; the exponent part is an <code>e</code> or <code>E</code> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 301 | followed by an optionally signed decimal exponent. One of the |
| 302 | integer part or the fractional part may be elided; one of the decimal |
| 303 | point or the exponent may be elided. |
| 304 | </p> |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 305 | <pre class="ebnf"> |
Robert Griesemer | d36d191 | 2009-09-18 11:58:35 -0700 | [diff] [blame] | 306 | float_lit = decimals "." [ decimals ] [ exponent ] | |
| 307 | decimals exponent | |
| 308 | "." decimals [ exponent ] . |
| 309 | decimals = decimal_digit { decimal_digit } . |
| 310 | exponent = ( "e" | "E" ) [ "+" | "-" ] decimals . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 311 | </pre> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 312 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 313 | <pre> |
| 314 | 0. |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 315 | 72.40 |
| 316 | 072.40 // == 72.40 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 317 | 2.71828 |
| 318 | 1.e+0 |
| 319 | 6.67428e-11 |
| 320 | 1E6 |
| 321 | .25 |
| 322 | .12345E+5 |
| 323 | </pre> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 324 | |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 325 | <h3 id="Imaginary_literals">Imaginary literals</h3> |
| 326 | <p> |
| 327 | An imaginary literal is a decimal representation of the imaginary part of a |
| 328 | <a href="#Constants">complex constant</a>. |
| 329 | It consists of a |
| 330 | <a href="#Floating-point_literals">floating-point literal</a> |
| 331 | or decimal integer followed |
| 332 | by the lower-case letter <code>i</code>. |
| 333 | </p> |
| 334 | <pre class="ebnf"> |
| 335 | imaginary_lit = (decimals | float_lit) "i" . |
| 336 | </pre> |
| 337 | |
| 338 | <pre> |
| 339 | 0i |
| 340 | 011i // == 11i |
| 341 | 0.i |
| 342 | 2.71828i |
| 343 | 1.e+0i |
| 344 | 6.67428e-11i |
| 345 | 1E6i |
| 346 | .25i |
| 347 | .12345E+5i |
| 348 | </pre> |
| 349 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 350 | |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 351 | <h3 id="Rune_literals">Rune literals</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 352 | |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 353 | <p> |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 354 | A rune literal represents a <a href="#Constants">rune constant</a>, |
| 355 | an integer value identifying a Unicode code point. |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 356 | A rune literal is expressed as one or more characters enclosed in single quotes, |
| 357 | as in <code>'x'</code> or <code>'\n'</code>. |
| 358 | Within the quotes, any character may appear except newline and unescaped single |
| 359 | quote. A single quoted character represents the Unicode value |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 360 | of the character itself, |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 361 | while multi-character sequences beginning with a backslash encode |
| 362 | values in various formats. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 363 | </p> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 364 | <p> |
| 365 | The simplest form represents the single character within the quotes; |
| 366 | since Go source text is Unicode characters encoded in UTF-8, multiple |
| 367 | UTF-8-encoded bytes may represent a single integer value. For |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 368 | instance, the literal <code>'a'</code> holds a single byte representing |
| 369 | a literal <code>a</code>, Unicode U+0061, value <code>0x61</code>, while |
| 370 | <code>'ä'</code> holds two bytes (<code>0xc3</code> <code>0xa4</code>) representing |
| 371 | a literal <code>a</code>-dieresis, U+00E4, value <code>0xe4</code>. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 372 | </p> |
| 373 | <p> |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 374 | Several backslash escapes allow arbitrary values to be encoded as |
Oling Cat | 845f4d6 | 2012-09-05 14:53:13 +1000 | [diff] [blame] | 375 | ASCII text. There are four ways to represent the integer value |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 376 | as a numeric constant: <code>\x</code> followed by exactly two hexadecimal |
| 377 | digits; <code>\u</code> followed by exactly four hexadecimal digits; |
| 378 | <code>\U</code> followed by exactly eight hexadecimal digits, and a |
| 379 | plain backslash <code>\</code> followed by exactly three octal digits. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 380 | In each case the value of the literal is the value represented by |
| 381 | the digits in the corresponding base. |
| 382 | </p> |
| 383 | <p> |
| 384 | Although these representations all result in an integer, they have |
| 385 | different valid ranges. Octal escapes must represent a value between |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 386 | 0 and 255 inclusive. Hexadecimal escapes satisfy this condition |
| 387 | by construction. The escapes <code>\u</code> and <code>\U</code> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 388 | represent Unicode code points so within them some values are illegal, |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 389 | in particular those above <code>0x10FFFF</code> and surrogate halves. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 390 | </p> |
| 391 | <p> |
| 392 | After a backslash, certain single-character escapes represent special values: |
| 393 | </p> |
| 394 | <pre class="grammar"> |
| 395 | \a U+0007 alert or bell |
| 396 | \b U+0008 backspace |
| 397 | \f U+000C form feed |
| 398 | \n U+000A line feed or newline |
| 399 | \r U+000D carriage return |
| 400 | \t U+0009 horizontal tab |
| 401 | \v U+000b vertical tab |
| 402 | \\ U+005c backslash |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 403 | \' U+0027 single quote (valid escape only within rune literals) |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 404 | \" U+0022 double quote (valid escape only within string literals) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 405 | </pre> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 406 | <p> |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 407 | All other sequences starting with a backslash are illegal inside rune literals. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 408 | </p> |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 409 | <pre class="ebnf"> |
Robert Griesemer | c863db4 | 2013-01-07 18:02:58 -0800 | [diff] [blame] | 410 | rune_lit = "'" ( unicode_value | byte_value ) "'" . |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 411 | unicode_value = unicode_char | little_u_value | big_u_value | escaped_char . |
| 412 | byte_value = octal_byte_value | hex_byte_value . |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 413 | octal_byte_value = `\` octal_digit octal_digit octal_digit . |
| 414 | hex_byte_value = `\` "x" hex_digit hex_digit . |
| 415 | little_u_value = `\` "u" hex_digit hex_digit hex_digit hex_digit . |
| 416 | big_u_value = `\` "U" hex_digit hex_digit hex_digit hex_digit |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 417 | hex_digit hex_digit hex_digit hex_digit . |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 418 | escaped_char = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) . |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 419 | </pre> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 420 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 421 | <pre> |
| 422 | 'a' |
| 423 | 'ä' |
| 424 | '本' |
| 425 | '\t' |
| 426 | '\000' |
| 427 | '\007' |
| 428 | '\377' |
| 429 | '\x07' |
| 430 | '\xff' |
| 431 | '\u12e4' |
| 432 | '\U00101234' |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 433 | '\'' // rune literal containing single quote character |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 434 | 'aa' // illegal: too many characters |
| 435 | '\xa' // illegal: too few hexadecimal digits |
| 436 | '\0' // illegal: too few octal digits |
| 437 | '\uDFFF' // illegal: surrogate half |
| 438 | '\U00110000' // illegal: invalid Unicode code point |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 439 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 440 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 441 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 442 | <h3 id="String_literals">String literals</h3> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 443 | |
| 444 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 445 | A string literal represents a <a href="#Constants">string constant</a> |
| 446 | obtained from concatenating a sequence of characters. There are two forms: |
| 447 | raw string literals and interpreted string literals. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 448 | </p> |
| 449 | <p> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 450 | Raw string literals are character sequences between back quotes, as in |
| 451 | <code>`foo`</code>. Within the quotes, any character may appear except |
Robert Griesemer | db7a622 | 2009-06-18 13:51:14 -0700 | [diff] [blame] | 452 | back quote. The value of a raw string literal is the |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 453 | string composed of the uninterpreted (implicitly UTF-8-encoded) characters |
| 454 | between the quotes; |
Robert Griesemer | db7a622 | 2009-06-18 13:51:14 -0700 | [diff] [blame] | 455 | in particular, backslashes have no special meaning and the string may |
Robert Griesemer | 11b7c89 | 2011-12-15 10:51:51 -0800 | [diff] [blame] | 456 | contain newlines. |
Ian Lance Taylor | 2a627da | 2014-05-16 12:20:03 -0700 | [diff] [blame] | 457 | Carriage return characters ('\r') inside raw string literals |
Rob Pike | c26ca91 | 2011-12-14 21:52:41 -0800 | [diff] [blame] | 458 | are discarded from the raw string value. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 459 | </p> |
| 460 | <p> |
| 461 | Interpreted string literals are character sequences between double |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 462 | quotes, as in <code>"bar"</code>. |
| 463 | Within the quotes, any character may appear except newline and unescaped double quote. |
| 464 | The text between the quotes forms the |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 465 | value of the literal, with backslash escapes interpreted as they |
Robin Eklind | f82097f | 2014-09-03 10:44:33 -0700 | [diff] [blame] | 466 | 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] | 467 | <code>\"</code> is legal), with the same restrictions. |
| 468 | The three-digit octal (<code>\</code><i>nnn</i>) |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 469 | 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] | 470 | <i>bytes</i> of the resulting string; all other escapes represent |
| 471 | the (possibly multi-byte) UTF-8 encoding of individual <i>characters</i>. |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 472 | Thus inside a string literal <code>\377</code> and <code>\xFF</code> represent |
| 473 | a single byte of value <code>0xFF</code>=255, while <code>ÿ</code>, |
| 474 | <code>\u00FF</code>, <code>\U000000FF</code> and <code>\xc3\xbf</code> represent |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 475 | 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] | 476 | U+00FF. |
| 477 | </p> |
| 478 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 479 | <pre class="ebnf"> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 480 | string_lit = raw_string_lit | interpreted_string_lit . |
Robert Griesemer | 0e8032c | 2011-05-05 09:03:00 -0700 | [diff] [blame] | 481 | raw_string_lit = "`" { unicode_char | newline } "`" . |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 482 | interpreted_string_lit = `"` { unicode_value | byte_value } `"` . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 483 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 484 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 485 | <pre> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 486 | `abc` // same as "abc" |
Robert Griesemer | db7a622 | 2009-06-18 13:51:14 -0700 | [diff] [blame] | 487 | `\n |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 488 | \n` // same as "\\n\n\\n" |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 489 | "\n" |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 490 | "\"" // same as `"` |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 491 | "Hello, world!\n" |
| 492 | "日本語" |
| 493 | "\u65e5本\U00008a9e" |
| 494 | "\xff\u00FF" |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 495 | "\uD800" // illegal: surrogate half |
| 496 | "\U00110000" // illegal: invalid Unicode code point |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 497 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 498 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 499 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 500 | These examples all represent the same string: |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 501 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 502 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 503 | <pre> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 504 | "日本語" // UTF-8 input text |
| 505 | `日本語` // UTF-8 input text as a raw literal |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 506 | "\u65e5\u672c\u8a9e" // the explicit Unicode code points |
| 507 | "\U000065e5\U0000672c\U00008a9e" // the explicit Unicode code points |
| 508 | "\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e" // the explicit UTF-8 bytes |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 509 | </pre> |
Robert Griesemer | cd49927 | 2008-09-29 12:09:00 -0700 | [diff] [blame] | 510 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 511 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 512 | If the source code represents a character as two code points, such as |
| 513 | 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] | 514 | 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] | 515 | point), and will appear as two code points if placed in a string |
| 516 | literal. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 517 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 518 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 519 | |
| 520 | <h2 id="Constants">Constants</h2> |
| 521 | |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 522 | <p>There are <i>boolean constants</i>, |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 523 | <i>rune constants</i>, |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 524 | <i>integer constants</i>, |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 525 | <i>floating-point constants</i>, <i>complex constants</i>, |
Robert Griesemer | f331012 | 2013-07-25 09:35:55 -0700 | [diff] [blame] | 526 | and <i>string constants</i>. Rune, integer, floating-point, |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 527 | and complex constants are |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 528 | collectively called <i>numeric constants</i>. |
| 529 | </p> |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 530 | |
| 531 | <p> |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 532 | A constant value is represented by a |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 533 | <a href="#Rune_literals">rune</a>, |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 534 | <a href="#Integer_literals">integer</a>, |
| 535 | <a href="#Floating-point_literals">floating-point</a>, |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 536 | <a href="#Imaginary_literals">imaginary</a>, |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 537 | or |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 538 | <a href="#String_literals">string</a> literal, |
| 539 | an identifier denoting a constant, |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 540 | a <a href="#Constant_expressions">constant expression</a>, |
| 541 | 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] | 542 | the result value of some built-in functions such as |
| 543 | <code>unsafe.Sizeof</code> applied to any value, |
| 544 | <code>cap</code> or <code>len</code> applied to |
| 545 | <a href="#Length_and_capacity">some expressions</a>, |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 546 | <code>real</code> and <code>imag</code> applied to a complex constant |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 547 | and <code>complex</code> applied to numeric constants. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 548 | The boolean truth values are represented by the predeclared constants |
| 549 | <code>true</code> and <code>false</code>. The predeclared identifier |
| 550 | <a href="#Iota">iota</a> denotes an integer constant. |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 551 | </p> |
| 552 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 553 | <p> |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 554 | In general, complex constants are a form of |
| 555 | <a href="#Constant_expressions">constant expression</a> |
| 556 | and are discussed in that section. |
| 557 | </p> |
| 558 | |
| 559 | <p> |
Robert Griesemer | 55ecda4 | 2015-09-17 18:10:20 -0700 | [diff] [blame] | 560 | Numeric constants represent exact values of arbitrary precision and do not overflow. |
| 561 | Consequently, there are no constants denoting the IEEE-754 negative zero, infinity, |
| 562 | and not-a-number values. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 563 | </p> |
| 564 | |
| 565 | <p> |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 566 | Constants may be <a href="#Types">typed</a> or <i>untyped</i>. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 567 | Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>, |
| 568 | and certain <a href="#Constant_expressions">constant expressions</a> |
| 569 | containing only untyped constant operands are untyped. |
| 570 | </p> |
| 571 | |
| 572 | <p> |
| 573 | A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a> |
| 574 | or <a href="#Conversions">conversion</a>, or implicitly when used in a |
| 575 | <a href="#Variable_declarations">variable declaration</a> or an |
| 576 | <a href="#Assignments">assignment</a> or as an |
| 577 | operand in an <a href="#Expressions">expression</a>. |
| 578 | It is an error if the constant value |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 579 | 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] | 580 | </p> |
| 581 | |
| 582 | <p> |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 583 | An untyped constant has a <i>default type</i> which is the type to which the |
| 584 | constant is implicitly converted in contexts where a typed value is required, |
| 585 | for instance, in a <a href="#Short_variable_declarations">short variable declaration</a> |
| 586 | such as <code>i := 0</code> where there is no explicit type. |
| 587 | The default type of an untyped constant is <code>bool</code>, <code>rune</code>, |
| 588 | <code>int</code>, <code>float64</code>, <code>complex128</code> or <code>string</code> |
| 589 | respectively, depending on whether it is a boolean, rune, integer, floating-point, |
| 590 | complex, or string constant. |
| 591 | </p> |
| 592 | |
| 593 | <p> |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 594 | Implementation restriction: Although numeric constants have arbitrary |
| 595 | precision in the language, a compiler may implement them using an |
| 596 | internal representation with limited precision. That said, every |
| 597 | implementation must: |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 598 | </p> |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 599 | <ul> |
| 600 | <li>Represent integer constants with at least 256 bits.</li> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 601 | |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 602 | <li>Represent floating-point constants, including the parts of |
| 603 | a complex constant, with a mantissa of at least 256 bits |
Robert Griesemer | 8fbfdad | 2015-12-10 11:18:41 -0800 | [diff] [blame] | 604 | and a signed binary exponent of at least 16 bits.</li> |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 605 | |
| 606 | <li>Give an error if unable to represent an integer constant |
| 607 | precisely.</li> |
| 608 | |
| 609 | <li>Give an error if unable to represent a floating-point or |
| 610 | complex constant due to overflow.</li> |
| 611 | |
| 612 | <li>Round to the nearest representable constant if unable to |
| 613 | represent a floating-point or complex constant due to limits |
| 614 | on precision.</li> |
| 615 | </ul> |
| 616 | <p> |
| 617 | These requirements apply both to literal constants and to the result |
| 618 | of evaluating <a href="#Constant_expressions">constant |
| 619 | expressions</a>. |
| 620 | </p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 621 | |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 622 | <h2 id="Variables">Variables</h2> |
| 623 | |
| 624 | <p> |
| 625 | A variable is a storage location for holding a <i>value</i>. |
| 626 | The set of permissible values is determined by the |
| 627 | variable's <i><a href="#Types">type</a></i>. |
| 628 | </p> |
| 629 | |
| 630 | <p> |
| 631 | A <a href="#Variable_declarations">variable declaration</a> |
| 632 | or, for function parameters and results, the signature |
| 633 | of a <a href="#Function_declarations">function declaration</a> |
| 634 | or <a href="#Function_literals">function literal</a> reserves |
| 635 | storage for a named variable. |
| 636 | |
| 637 | Calling the built-in function <a href="#Allocation"><code>new</code></a> |
| 638 | or taking the address of a <a href="#Composite_literals">composite literal</a> |
| 639 | allocates storage for a variable at run time. |
| 640 | Such an anonymous variable is referred to via a (possibly implicit) |
| 641 | <a href="#Address_operators">pointer indirection</a>. |
| 642 | </p> |
| 643 | |
| 644 | <p> |
| 645 | <i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>, |
| 646 | and <a href="#Struct_types">struct</a> types have elements and fields that may |
| 647 | be <a href="#Address_operators">addressed</a> individually. Each such element |
| 648 | acts like a variable. |
| 649 | </p> |
| 650 | |
| 651 | <p> |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 652 | 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] | 653 | type given in its declaration, the type provided in the |
| 654 | <code>new</code> call or composite literal, or the type of |
| 655 | an element of a structured variable. |
| 656 | Variables of interface type also have a distinct <i>dynamic type</i>, |
| 657 | which is the concrete type of the value assigned to the variable at run time |
| 658 | (unless the value is the predeclared identifier <code>nil</code>, |
| 659 | which has no type). |
| 660 | The dynamic type may vary during execution but values stored in interface |
| 661 | variables are always <a href="#Assignability">assignable</a> |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 662 | to the static type of the variable. |
| 663 | </p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 664 | |
| 665 | <pre> |
| 666 | var x interface{} // x is nil and has static type interface{} |
| 667 | var v *T // v has value nil, static type *T |
| 668 | x = 42 // x has value 42 and dynamic type int |
| 669 | x = v // x has value (*T)(nil) and dynamic type *T |
| 670 | </pre> |
| 671 | |
| 672 | <p> |
| 673 | A variable's value is retrieved by referring to the variable in an |
| 674 | <a href="#Expressions">expression</a>; it is the most recent value |
| 675 | <a href="#Assignments">assigned</a> to the variable. |
| 676 | If a variable has not yet been assigned a value, its value is the |
| 677 | <a href="#The_zero_value">zero value</a> for its type. |
| 678 | </p> |
| 679 | |
| 680 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 681 | <h2 id="Types">Types</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 682 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 683 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 684 | A type determines a set of values together with operations and methods specific |
| 685 | to those values. A type may be denoted by a <i>type name</i>, if it has one, |
| 686 | 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] | 687 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 688 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 689 | <pre class="ebnf"> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 690 | Type = TypeName | TypeLit | "(" Type ")" . |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 691 | TypeName = identifier | QualifiedIdent . |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 692 | TypeLit = ArrayType | StructType | PointerType | FunctionType | InterfaceType | |
| 693 | SliceType | MapType | ChannelType . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 694 | </pre> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 695 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 696 | <p> |
Robert Griesemer | 9b49ac0 | 2018-01-22 16:20:01 -0800 | [diff] [blame] | 697 | The language <a href="#Predeclared_identifiers">predeclares</a> certain type names. |
| 698 | Others are introduced with <a href="#Type_declarations">type declarations</a>. |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 699 | <i>Composite types</i>—array, struct, pointer, function, |
| 700 | interface, slice, map, and channel types—may be constructed using |
| 701 | type literals. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 702 | </p> |
Robert Griesemer | 7abfcd9 | 2008-10-07 17:14:30 -0700 | [diff] [blame] | 703 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 704 | <p> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 705 | 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] | 706 | is one of the predeclared boolean, numeric, or string types, or a type literal, |
| 707 | the corresponding underlying |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 708 | type is <code>T</code> itself. Otherwise, <code>T</code>'s underlying type |
| 709 | is the underlying type of the type to which <code>T</code> refers in its |
| 710 | <a href="#Type_declarations">type declaration</a>. |
| 711 | </p> |
| 712 | |
| 713 | <pre> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 714 | type ( |
| 715 | A1 = string |
| 716 | A2 = A1 |
| 717 | ) |
| 718 | |
| 719 | type ( |
| 720 | B1 string |
| 721 | B2 B1 |
| 722 | B3 []B1 |
| 723 | B4 B3 |
| 724 | ) |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 725 | </pre> |
| 726 | |
| 727 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 728 | The underlying type of <code>string</code>, <code>A1</code>, <code>A2</code>, <code>B1</code>, |
| 729 | and <code>B2</code> is <code>string</code>. |
| 730 | 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] | 731 | </p> |
| 732 | |
Robert Griesemer | 2a838d6 | 2011-02-08 13:31:01 -0800 | [diff] [blame] | 733 | <h3 id="Method_sets">Method sets</h3> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 734 | <p> |
Robert Griesemer | 2c83f1e | 2014-05-22 12:23:25 -0700 | [diff] [blame] | 735 | A type may have a <i>method set</i> associated with it. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 736 | 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] | 737 | The method set of any other type <code>T</code> consists of all |
| 738 | <a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>. |
| 739 | The method set of the corresponding <a href="#Pointer_types">pointer type</a> <code>*T</code> |
| 740 | 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] | 741 | (that is, it also contains the method set of <code>T</code>). |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 742 | Further rules apply to structs containing embedded fields, as described |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 743 | in the section on <a href="#Struct_types">struct types</a>. |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 744 | Any other type has an empty method set. |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 745 | In a method set, each method must have a |
Robert Griesemer | 2c83f1e | 2014-05-22 12:23:25 -0700 | [diff] [blame] | 746 | <a href="#Uniqueness_of_identifiers">unique</a> |
| 747 | 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] | 748 | </p> |
Robert Griesemer | 1f3e842 | 2008-09-29 18:41:30 -0700 | [diff] [blame] | 749 | |
Russ Cox | fd2a511 | 2012-02-08 14:28:51 -0500 | [diff] [blame] | 750 | <p> |
| 751 | The method set of a type determines the interfaces that the |
| 752 | type <a href="#Interface_types">implements</a> |
| 753 | and the methods that can be <a href="#Calls">called</a> |
| 754 | using a receiver of that type. |
| 755 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 756 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 757 | <h3 id="Boolean_types">Boolean types</h3> |
| 758 | |
Stefan Nilsson | c50074e | 2012-02-29 15:07:52 -0800 | [diff] [blame] | 759 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 760 | A <i>boolean type</i> represents the set of Boolean truth values |
| 761 | denoted by the predeclared constants <code>true</code> |
griesemer | 4a2391e | 2017-09-19 14:35:15 +0200 | [diff] [blame] | 762 | and <code>false</code>. The predeclared boolean type is <code>bool</code>; |
| 763 | it is a <a href="#Type_definitions">defined type</a>. |
Stefan Nilsson | c50074e | 2012-02-29 15:07:52 -0800 | [diff] [blame] | 764 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 765 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 766 | <h3 id="Numeric_types">Numeric types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 767 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 768 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 769 | A <i>numeric type</i> represents sets of integer or floating-point values. |
| 770 | The predeclared architecture-independent numeric types are: |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 771 | </p> |
Robert Griesemer | ebf14c6 | 2008-10-30 14:50:23 -0700 | [diff] [blame] | 772 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 773 | <pre class="grammar"> |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 774 | uint8 the set of all unsigned 8-bit integers (0 to 255) |
| 775 | uint16 the set of all unsigned 16-bit integers (0 to 65535) |
| 776 | uint32 the set of all unsigned 32-bit integers (0 to 4294967295) |
| 777 | uint64 the set of all unsigned 64-bit integers (0 to 18446744073709551615) |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 778 | |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 779 | int8 the set of all signed 8-bit integers (-128 to 127) |
| 780 | int16 the set of all signed 16-bit integers (-32768 to 32767) |
| 781 | int32 the set of all signed 32-bit integers (-2147483648 to 2147483647) |
| 782 | int64 the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807) |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 783 | |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 784 | float32 the set of all IEEE-754 32-bit floating-point numbers |
| 785 | float64 the set of all IEEE-754 64-bit floating-point numbers |
| 786 | |
| 787 | complex64 the set of all complex numbers with float32 real and imaginary parts |
| 788 | 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] | 789 | |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 790 | byte alias for uint8 |
Russ Cox | d7f050a | 2011-12-09 00:11:43 -0500 | [diff] [blame] | 791 | rune alias for int32 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 792 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 793 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 794 | <p> |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 795 | 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] | 796 | <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] | 797 | </p> |
Robert Griesemer | 9dfb2ea | 2008-12-12 10:30:10 -0800 | [diff] [blame] | 798 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 799 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 800 | 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] | 801 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 802 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 803 | <pre class="grammar"> |
Robert Griesemer | cfe9211 | 2009-06-18 13:29:40 -0700 | [diff] [blame] | 804 | uint either 32 or 64 bits |
Robert Griesemer | 97025eb | 2011-01-13 10:24:04 -0800 | [diff] [blame] | 805 | int same size as uint |
Robert Griesemer | cfe9211 | 2009-06-18 13:29:40 -0700 | [diff] [blame] | 806 | 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] | 807 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 808 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 809 | <p> |
griesemer | 4a2391e | 2017-09-19 14:35:15 +0200 | [diff] [blame] | 810 | To avoid portability issues all numeric types are <a href="#Type_definitions">defined |
| 811 | types</a> and thus distinct except |
| 812 | <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] | 813 | <code>rune</code>, which is an alias for <code>int32</code>. |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 814 | Explicit conversions |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 815 | are required when different numeric types are mixed in an expression |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 816 | or assignment. For instance, <code>int32</code> and <code>int</code> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 817 | 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] | 818 | particular architecture. |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 819 | |
| 820 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 821 | <h3 id="String_types">String types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 822 | |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 823 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 824 | A <i>string type</i> represents the set of string values. |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 825 | A string value is a (possibly empty) sequence of bytes. |
Robert Griesemer | de578dc | 2018-11-12 11:25:58 -0800 | [diff] [blame] | 826 | 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] | 827 | Strings are immutable: once created, |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 828 | it is impossible to change the contents of a string. |
griesemer | 4a2391e | 2017-09-19 14:35:15 +0200 | [diff] [blame] | 829 | The predeclared string type is <code>string</code>; |
| 830 | it is a <a href="#Type_definitions">defined type</a>. |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 831 | </p> |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 832 | |
| 833 | <p> |
Robert Griesemer | de578dc | 2018-11-12 11:25:58 -0800 | [diff] [blame] | 834 | The length of a string <code>s</code> can be discovered using |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 835 | the built-in function <a href="#Length_and_capacity"><code>len</code></a>. |
| 836 | 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] | 837 | A string's bytes can be accessed by integer <a href="#Index_expressions">indices</a> |
| 838 | 0 through <code>len(s)-1</code>. |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 839 | It is illegal to take the address of such an element; if |
| 840 | <code>s[i]</code> is the <code>i</code>'th byte of a |
| 841 | string, <code>&s[i]</code> is invalid. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 842 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 843 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 844 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 845 | <h3 id="Array_types">Array types</h3> |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 846 | |
| 847 | <p> |
| 848 | An array is a numbered sequence of elements of a single |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 849 | type, called the element type. |
Robert Griesemer | de578dc | 2018-11-12 11:25:58 -0800 | [diff] [blame] | 850 | 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] | 851 | </p> |
| 852 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 853 | <pre class="ebnf"> |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 854 | ArrayType = "[" ArrayLength "]" ElementType . |
| 855 | ArrayLength = Expression . |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 856 | ElementType = Type . |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 857 | </pre> |
| 858 | |
| 859 | <p> |
Robert Griesemer | 2c83f1e | 2014-05-22 12:23:25 -0700 | [diff] [blame] | 860 | 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] | 861 | non-negative <a href="#Constants">constant</a> |
| 862 | <a href="#Representability">representable</a> by a value |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 863 | of type <code>int</code>. |
| 864 | The length of array <code>a</code> can be discovered |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 865 | 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] | 866 | 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] | 867 | 0 through <code>len(a)-1</code>. |
Rob Pike | ff6a8fd | 2009-11-20 15:47:15 -0800 | [diff] [blame] | 868 | Array types are always one-dimensional but may be composed to form |
| 869 | multi-dimensional types. |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 870 | </p> |
| 871 | |
| 872 | <pre> |
| 873 | [32]byte |
| 874 | [2*N] struct { x, y int32 } |
| 875 | [1000]*float64 |
Rob Pike | ff6a8fd | 2009-11-20 15:47:15 -0800 | [diff] [blame] | 876 | [3][5]int |
| 877 | [2][2][2]float64 // same as [2]([2]([2]float64)) |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 878 | </pre> |
| 879 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 880 | <h3 id="Slice_types">Slice types</h3> |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 881 | |
| 882 | <p> |
Robert Griesemer | 15da997 | 2013-10-16 16:16:54 -0700 | [diff] [blame] | 883 | 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] | 884 | provides access to a numbered sequence of elements from that array. |
| 885 | 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] | 886 | 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] | 887 | The value of an uninitialized slice is <code>nil</code>. |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 888 | </p> |
| 889 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 890 | <pre class="ebnf"> |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 891 | SliceType = "[" "]" ElementType . |
| 892 | </pre> |
| 893 | |
| 894 | <p> |
Robert Griesemer | de578dc | 2018-11-12 11:25:58 -0800 | [diff] [blame] | 895 | 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] | 896 | <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] | 897 | execution. The elements can be addressed by integer <a href="#Index_expressions">indices</a> |
| 898 | 0 through <code>len(s)-1</code>. The slice index of a |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 899 | given element may be less than the index of the same element in the |
| 900 | underlying array. |
| 901 | </p> |
| 902 | <p> |
| 903 | A slice, once initialized, is always associated with an underlying |
Rob Pike | 7ec0856 | 2010-01-09 07:32:26 +1100 | [diff] [blame] | 904 | array that holds its elements. A slice therefore shares storage |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 905 | with its array and with other slices of the same array; by contrast, |
| 906 | distinct arrays always represent distinct storage. |
| 907 | </p> |
| 908 | <p> |
| 909 | 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] | 910 | 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] | 911 | 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] | 912 | a slice of length up to that capacity can be created by |
Robert Griesemer | e333b96 | 2013-09-11 17:18:52 -0700 | [diff] [blame] | 913 | <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] | 914 | 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] | 915 | 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] | 916 | </p> |
| 917 | |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 918 | <p> |
Robert Griesemer | 0c2e6b3 | 2010-07-13 11:54:57 -0700 | [diff] [blame] | 919 | A new, initialized slice value for a given element type <code>T</code> is |
| 920 | made using the built-in function |
| 921 | <a href="#Making_slices_maps_and_channels"><code>make</code></a>, |
| 922 | which takes a slice type |
Robert Griesemer | 15da997 | 2013-10-16 16:16:54 -0700 | [diff] [blame] | 923 | and parameters specifying the length and optionally the capacity. |
| 924 | A slice created with <code>make</code> always allocates a new, hidden array |
| 925 | to which the returned slice value refers. That is, executing |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 926 | </p> |
| 927 | |
| 928 | <pre> |
| 929 | make([]T, length, capacity) |
| 930 | </pre> |
| 931 | |
| 932 | <p> |
Robert Griesemer | 15da997 | 2013-10-16 16:16:54 -0700 | [diff] [blame] | 933 | produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a> |
| 934 | it, so these two expressions are equivalent: |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 935 | </p> |
| 936 | |
| 937 | <pre> |
| 938 | make([]int, 50, 100) |
| 939 | new([100]int)[0:50] |
| 940 | </pre> |
| 941 | |
Rob Pike | ff6a8fd | 2009-11-20 15:47:15 -0800 | [diff] [blame] | 942 | <p> |
| 943 | Like arrays, slices are always one-dimensional but may be composed to construct |
| 944 | higher-dimensional objects. |
| 945 | 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] | 946 | however with slices of slices (or arrays of slices), the inner lengths may vary dynamically. |
| 947 | Moreover, the inner slices must be initialized individually. |
Rob Pike | ff6a8fd | 2009-11-20 15:47:15 -0800 | [diff] [blame] | 948 | </p> |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 949 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 950 | <h3 id="Struct_types">Struct types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 951 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 952 | <p> |
Robert Griesemer | d3b1565 | 2009-11-16 08:58:55 -0800 | [diff] [blame] | 953 | A struct is a sequence of named elements, called fields, each of which has a |
| 954 | name and a type. Field names may be specified explicitly (IdentifierList) or |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 955 | implicitly (EmbeddedField). |
Robert Griesemer | d3b1565 | 2009-11-16 08:58:55 -0800 | [diff] [blame] | 956 | 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] | 957 | be <a href="#Uniqueness_of_identifiers">unique</a>. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 958 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 959 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 960 | <pre class="ebnf"> |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 961 | StructType = "struct" "{" { FieldDecl ";" } "}" . |
| 962 | FieldDecl = (IdentifierList Type | EmbeddedField) [ Tag ] . |
| 963 | EmbeddedField = [ "*" ] TypeName . |
| 964 | Tag = string_lit . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 965 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 966 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 967 | <pre> |
| 968 | // An empty struct. |
| 969 | struct {} |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 970 | |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 971 | // A struct with 6 fields. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 972 | struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 973 | x, y int |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 974 | u float32 |
| 975 | _ float32 // padding |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 976 | A *[]int |
| 977 | F func() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 978 | } |
| 979 | </pre> |
Robert Griesemer | 1f3e842 | 2008-09-29 18:41:30 -0700 | [diff] [blame] | 980 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 981 | <p> |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 982 | A field declared with a type but no explicit field name is called an <i>embedded field</i>. |
| 983 | An embedded field must be specified as |
Russ Cox | bee2d5b | 2010-09-30 14:59:41 -0400 | [diff] [blame] | 984 | 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] | 985 | and <code>T</code> itself may not be |
Robert Griesemer | d3b1565 | 2009-11-16 08:58:55 -0800 | [diff] [blame] | 986 | a pointer type. The unqualified type name acts as the field name. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 987 | </p> |
Robert Griesemer | 1f3e842 | 2008-09-29 18:41:30 -0700 | [diff] [blame] | 988 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 989 | <pre> |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 990 | // 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] | 991 | struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 992 | T1 // field name is T1 |
| 993 | *T2 // field name is T2 |
| 994 | P.T3 // field name is T3 |
| 995 | *P.T4 // field name is T4 |
| 996 | x, y int // field names are x and y |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 997 | } |
| 998 | </pre> |
Robert Griesemer | 1f3e842 | 2008-09-29 18:41:30 -0700 | [diff] [blame] | 999 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1000 | <p> |
Robert Griesemer | d3b1565 | 2009-11-16 08:58:55 -0800 | [diff] [blame] | 1001 | The following declaration is illegal because field names must be unique |
| 1002 | in a struct type: |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1003 | </p> |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 1004 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1005 | <pre> |
| 1006 | struct { |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1007 | T // conflicts with embedded field *T and *P.T |
| 1008 | *T // conflicts with embedded field T and *P.T |
| 1009 | *P.T // conflicts with embedded field T and *T |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1010 | } |
| 1011 | </pre> |
Robert Griesemer | 1f3e842 | 2008-09-29 18:41:30 -0700 | [diff] [blame] | 1012 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1013 | <p> |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1014 | 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] | 1015 | 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] | 1016 | <code>x.f</code> is a legal <a href="#Selectors">selector</a> that denotes |
| 1017 | that field or method <code>f</code>. |
| 1018 | </p> |
| 1019 | |
| 1020 | <p> |
| 1021 | Promoted fields act like ordinary fields |
| 1022 | of a struct except that they cannot be used as field names in |
| 1023 | <a href="#Composite_literals">composite literals</a> of the struct. |
| 1024 | </p> |
| 1025 | |
| 1026 | <p> |
Robert Griesemer | 9b49ac0 | 2018-01-22 16:20:01 -0800 | [diff] [blame] | 1027 | Given a struct type <code>S</code> and a <a href="#Type_definitions">defined type</a> |
| 1028 | <code>T</code>, promoted methods are included in the method set of the struct as follows: |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1029 | </p> |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1030 | <ul> |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1031 | <li> |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1032 | If <code>S</code> contains an embedded field <code>T</code>, |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1033 | the <a href="#Method_sets">method sets</a> of <code>S</code> |
| 1034 | and <code>*S</code> both include promoted methods with receiver |
| 1035 | <code>T</code>. The method set of <code>*S</code> also |
| 1036 | includes promoted methods with receiver <code>*T</code>. |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1037 | </li> |
Robin Eklind | 1d46fc4 | 2012-12-11 12:17:53 -0500 | [diff] [blame] | 1038 | |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1039 | <li> |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1040 | If <code>S</code> contains an embedded field <code>*T</code>, |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1041 | the method sets of <code>S</code> and <code>*S</code> both |
| 1042 | include promoted methods with receiver <code>T</code> or |
| 1043 | <code>*T</code>. |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1044 | </li> |
| 1045 | </ul> |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1046 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1047 | <p> |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1048 | 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] | 1049 | which becomes an attribute for all the fields in the corresponding |
Robert Griesemer | 0436a89 | 2016-04-22 16:35:29 -0700 | [diff] [blame] | 1050 | field declaration. An empty tag string is equivalent to an absent tag. |
| 1051 | 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] | 1052 | 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] | 1053 | but are otherwise ignored. |
| 1054 | </p> |
Robert Griesemer | 2e90e54 | 2008-10-30 15:52:37 -0700 | [diff] [blame] | 1055 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1056 | <pre> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1057 | struct { |
Robert Griesemer | 7305b55 | 2015-11-30 14:18:09 -0800 | [diff] [blame] | 1058 | x, y float64 "" // an empty tag string is like an absent tag |
| 1059 | name string "any string is permitted as a tag" |
| 1060 | _ [4]byte "ceci n'est pas un champ de structure" |
| 1061 | } |
| 1062 | |
| 1063 | // A struct corresponding to a TimeStamp protocol buffer. |
| 1064 | // The tag strings define the protocol buffer field numbers; |
| 1065 | // they follow the convention outlined by the reflect package. |
| 1066 | struct { |
| 1067 | microsec uint64 `protobuf:"1"` |
| 1068 | serverIP6 uint64 `protobuf:"2"` |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1069 | } |
| 1070 | </pre> |
Robert Griesemer | 2e90e54 | 2008-10-30 15:52:37 -0700 | [diff] [blame] | 1071 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1072 | <h3 id="Pointer_types">Pointer types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1073 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1074 | <p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 1075 | 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] | 1076 | type, called the <i>base type</i> of the pointer. |
Peter Mundy | 5928e1d | 2010-11-09 10:10:57 -0800 | [diff] [blame] | 1077 | The value of an uninitialized pointer is <code>nil</code>. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1078 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1079 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1080 | <pre class="ebnf"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1081 | PointerType = "*" BaseType . |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 1082 | BaseType = Type . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1083 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1084 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1085 | <pre> |
Robert Griesemer | 953f2de | 2012-03-01 10:35:15 -0800 | [diff] [blame] | 1086 | *Point |
| 1087 | *[4]int |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1088 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1089 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1090 | <h3 id="Function_types">Function types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1091 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1092 | <p> |
Robert Griesemer | 7231ceb | 2008-09-08 15:01:04 -0700 | [diff] [blame] | 1093 | 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] | 1094 | and result types. The value of an uninitialized variable of function type |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1095 | is <code>nil</code>. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1096 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1097 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1098 | <pre class="ebnf"> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1099 | FunctionType = "func" Signature . |
| 1100 | Signature = Parameters [ Result ] . |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 1101 | Result = Parameters | Type . |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1102 | Parameters = "(" [ ParameterList [ "," ] ] ")" . |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1103 | ParameterList = ParameterDecl { "," ParameterDecl } . |
Russ Cox | 9562592 | 2010-06-12 11:37:13 -0700 | [diff] [blame] | 1104 | ParameterDecl = [ IdentifierList ] [ "..." ] Type . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1105 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1106 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1107 | <p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1108 | Within a list of parameters or results, the names (IdentifierList) |
| 1109 | 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] | 1110 | stands for one item (parameter or result) of the specified type and |
| 1111 | all non-<a href="#Blank_identifier">blank</a> names in the signature |
| 1112 | must be <a href="#Uniqueness_of_identifiers">unique</a>. |
| 1113 | If absent, each type stands for one item of that type. |
| 1114 | Parameter and result |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1115 | lists are always parenthesized except that if there is exactly |
Robert Griesemer | 73ca127 | 2010-07-09 13:02:54 -0700 | [diff] [blame] | 1116 | one unnamed result it may be written as an unparenthesized type. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1117 | </p> |
Russ Cox | 9562592 | 2010-06-12 11:37:13 -0700 | [diff] [blame] | 1118 | |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 1119 | <p> |
Robert Griesemer | 57c81ef | 2015-12-15 13:13:38 -0800 | [diff] [blame] | 1120 | The final incoming parameter in a function signature may have |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 1121 | a type prefixed with <code>...</code>. |
| 1122 | A function with such a parameter is called <i>variadic</i> and |
| 1123 | may be invoked with zero or more arguments for that parameter. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1124 | </p> |
Robert Griesemer | 2bfa957 | 2008-10-24 13:13:12 -0700 | [diff] [blame] | 1125 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1126 | <pre> |
Russ Cox | 4687169 | 2010-01-26 10:25:56 -0800 | [diff] [blame] | 1127 | func() |
Robert Griesemer | 953f2de | 2012-03-01 10:35:15 -0800 | [diff] [blame] | 1128 | func(x int) int |
| 1129 | func(a, _ int, z float32) bool |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 1130 | func(a, b int, z float32) (bool) |
Robert Griesemer | 953f2de | 2012-03-01 10:35:15 -0800 | [diff] [blame] | 1131 | func(prefix string, values ...int) |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 1132 | func(a, b int, z float64, opt ...interface{}) (success bool) |
| 1133 | func(int, int, float64) (float64, *[]int) |
Russ Cox | 4687169 | 2010-01-26 10:25:56 -0800 | [diff] [blame] | 1134 | func(n int) func(p *T) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1135 | </pre> |
Robert Griesemer | 2b9fe0e | 2009-01-30 14:48:29 -0800 | [diff] [blame] | 1136 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1137 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1138 | <h3 id="Interface_types">Interface types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1139 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1140 | <p> |
Robert Griesemer | 2a838d6 | 2011-02-08 13:31:01 -0800 | [diff] [blame] | 1141 | 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] | 1142 | A variable of interface type can store a value of any type with a method set |
| 1143 | 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] | 1144 | <i>implement the interface</i>. |
Peter Mundy | 5928e1d | 2010-11-09 10:10:57 -0800 | [diff] [blame] | 1145 | 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] | 1146 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1147 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1148 | <pre class="ebnf"> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1149 | InterfaceType = "interface" "{" { MethodSpec ";" } "}" . |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 1150 | MethodSpec = MethodName Signature | InterfaceTypeName . |
| 1151 | MethodName = identifier . |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1152 | InterfaceTypeName = TypeName . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1153 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1154 | |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 1155 | <p> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1156 | As with all method sets, in an interface type, each method must have a |
Robert Griesemer | 2c83f1e | 2014-05-22 12:23:25 -0700 | [diff] [blame] | 1157 | <a href="#Uniqueness_of_identifiers">unique</a> |
| 1158 | non-<a href="#Blank_identifier">blank</a> name. |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 1159 | </p> |
| 1160 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1161 | <pre> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1162 | // A simple File interface |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1163 | interface { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1164 | Read(b Buffer) bool |
| 1165 | Write(b Buffer) bool |
| 1166 | Close() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1167 | } |
| 1168 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1169 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1170 | <p> |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1171 | More than one type may implement an interface. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1172 | For instance, if two types <code>S1</code> and <code>S2</code> |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1173 | have the method set |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1174 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1175 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1176 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 1177 | func (p T) Read(b Buffer) bool { return … } |
| 1178 | func (p T) Write(b Buffer) bool { return … } |
| 1179 | func (p T) Close() { … } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1180 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1181 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1182 | <p> |
| 1183 | (where <code>T</code> stands for either <code>S1</code> or <code>S2</code>) |
| 1184 | then the <code>File</code> interface is implemented by both <code>S1</code> and |
| 1185 | <code>S2</code>, regardless of what other methods |
| 1186 | <code>S1</code> and <code>S2</code> may have or share. |
| 1187 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1188 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1189 | <p> |
| 1190 | A type implements any interface comprising any subset of its methods |
| 1191 | and may therefore implement several distinct interfaces. For |
| 1192 | instance, all types implement the <i>empty interface</i>: |
| 1193 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1194 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1195 | <pre> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1196 | interface{} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1197 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1198 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1199 | <p> |
| 1200 | Similarly, consider this interface specification, |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 1201 | which appears within a <a href="#Type_declarations">type declaration</a> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1202 | to define an interface called <code>Locker</code>: |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1203 | </p> |
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 | <pre> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1206 | type Locker interface { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1207 | Lock() |
| 1208 | Unlock() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1209 | } |
| 1210 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1211 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1212 | <p> |
| 1213 | If <code>S1</code> and <code>S2</code> also implement |
| 1214 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1215 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1216 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 1217 | func (p T) Lock() { … } |
| 1218 | func (p T) Unlock() { … } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1219 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1220 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1221 | <p> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1222 | they implement the <code>Locker</code> interface as well |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1223 | as the <code>File</code> interface. |
| 1224 | </p> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1225 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1226 | <p> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1227 | An interface <code>T</code> may use a (possibly qualified) interface type |
| 1228 | name <code>E</code> in place of a method specification. This is called |
| 1229 | <i>embedding</i> interface <code>E</code> in <code>T</code>; it adds |
| 1230 | all (exported and non-exported) methods of <code>E</code> to the interface |
| 1231 | <code>T</code>. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1232 | </p> |
Robert Griesemer | 38c232f | 2009-02-11 15:09:15 -0800 | [diff] [blame] | 1233 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1234 | <pre> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1235 | type ReadWriter interface { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1236 | Read(b Buffer) bool |
| 1237 | Write(b Buffer) bool |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1238 | } |
Robert Griesemer | 38c232f | 2009-02-11 15:09:15 -0800 | [diff] [blame] | 1239 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1240 | type File interface { |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1241 | ReadWriter // same as adding the methods of ReadWriter |
| 1242 | Locker // same as adding the methods of Locker |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1243 | Close() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1244 | } |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1245 | |
| 1246 | type LockedFile interface { |
| 1247 | Locker |
| 1248 | File // illegal: Lock, Unlock not unique |
| 1249 | Lock() // illegal: Lock not unique |
| 1250 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1251 | </pre> |
Robert Griesemer | 38c232f | 2009-02-11 15:09:15 -0800 | [diff] [blame] | 1252 | |
Russ Cox | 388816a | 2012-02-08 14:35:00 -0500 | [diff] [blame] | 1253 | <p> |
Russ Cox | 7c5d640 | 2012-02-08 15:37:58 -0500 | [diff] [blame] | 1254 | An interface type <code>T</code> may not embed itself |
| 1255 | or any interface type that embeds <code>T</code>, recursively. |
Russ Cox | 388816a | 2012-02-08 14:35:00 -0500 | [diff] [blame] | 1256 | </p> |
| 1257 | |
| 1258 | <pre> |
| 1259 | // illegal: Bad cannot embed itself |
| 1260 | type Bad interface { |
| 1261 | Bad |
| 1262 | } |
| 1263 | |
| 1264 | // illegal: Bad1 cannot embed itself using Bad2 |
| 1265 | type Bad1 interface { |
| 1266 | Bad2 |
| 1267 | } |
| 1268 | type Bad2 interface { |
| 1269 | Bad1 |
| 1270 | } |
| 1271 | </pre> |
| 1272 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1273 | <h3 id="Map_types">Map types</h3> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1274 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1275 | <p> |
| 1276 | 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] | 1277 | 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] | 1278 | called the key type. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1279 | The value of an uninitialized map is <code>nil</code>. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1280 | </p> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1281 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1282 | <pre class="ebnf"> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1283 | MapType = "map" "[" KeyType "]" ElementType . |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 1284 | KeyType = Type . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1285 | </pre> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1286 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1287 | <p> |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 1288 | The <a href="#Comparison_operators">comparison operators</a> |
| 1289 | <code>==</code> and <code>!=</code> must be fully defined |
Robert Griesemer | 9c3d876 | 2012-01-30 15:31:33 -0800 | [diff] [blame] | 1290 | for operands of the key type; thus the key type must not be a function, map, or |
| 1291 | slice. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 1292 | If the key type is an interface type, these |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1293 | comparison operators must be defined for the dynamic key values; |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 1294 | 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] | 1295 | |
| 1296 | </p> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1297 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1298 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1299 | map[string]int |
| 1300 | map[*T]struct{ x, y float64 } |
| 1301 | map[string]interface{} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1302 | </pre> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1303 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1304 | <p> |
Robert Griesemer | 0c2e6b3 | 2010-07-13 11:54:57 -0700 | [diff] [blame] | 1305 | The number of map elements is called its length. |
| 1306 | For a map <code>m</code>, it can be discovered using the |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 1307 | built-in function <a href="#Length_and_capacity"><code>len</code></a> |
Robert Griesemer | 3e0c0a8 | 2011-10-17 12:53:10 -0700 | [diff] [blame] | 1308 | and may change during execution. Elements may be added during execution |
| 1309 | using <a href="#Assignments">assignments</a> and retrieved with |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 1310 | <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] | 1311 | <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] | 1312 | </p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1313 | <p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1314 | A new, empty map value is made using the built-in |
Robert Griesemer | 0c2e6b3 | 2010-07-13 11:54:57 -0700 | [diff] [blame] | 1315 | function <a href="#Making_slices_maps_and_channels"><code>make</code></a>, |
| 1316 | which takes the map type and an optional capacity hint as arguments: |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1317 | </p> |
| 1318 | |
| 1319 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1320 | make(map[string]int) |
| 1321 | make(map[string]int, 100) |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1322 | </pre> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1323 | |
Rob Pike | da38974 | 2009-03-02 19:13:40 -0800 | [diff] [blame] | 1324 | <p> |
| 1325 | The initial capacity does not bound its size: |
| 1326 | maps grow to accommodate the number of items |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 1327 | stored in them, with the exception of <code>nil</code> maps. |
| 1328 | A <code>nil</code> map is equivalent to an empty map except that no elements |
| 1329 | may be added. |
Rob Pike | da38974 | 2009-03-02 19:13:40 -0800 | [diff] [blame] | 1330 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1331 | <h3 id="Channel_types">Channel types</h3> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1332 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1333 | <p> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1334 | A channel provides a mechanism for |
| 1335 | <a href="#Go_statements">concurrently executing functions</a> |
| 1336 | to communicate by |
| 1337 | <a href="#Send_statements">sending</a> and |
| 1338 | <a href="#Receive_operator">receiving</a> |
| 1339 | values of a specified element type. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1340 | The value of an uninitialized channel is <code>nil</code>. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1341 | </p> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1342 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1343 | <pre class="ebnf"> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1344 | ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1345 | </pre> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1346 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1347 | <p> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1348 | The optional <code><-</code> operator specifies the channel <i>direction</i>, |
Robert Griesemer | 56ca697 | 2010-05-07 18:22:40 -0700 | [diff] [blame] | 1349 | <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] | 1350 | <i>bidirectional</i>. |
Russ Cox | b7ba523 | 2018-11-13 10:23:01 -0500 | [diff] [blame] | 1351 | A channel may be constrained only to send or only to receive by |
| 1352 | <a href="#Assignments">assignment</a> or |
| 1353 | explicit <a href="#Conversions">conversion</a>. |
Robert Griesemer | 56ca697 | 2010-05-07 18:22:40 -0700 | [diff] [blame] | 1354 | </p> |
| 1355 | |
| 1356 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1357 | chan T // can be used to send and receive values of type T |
| 1358 | chan<- float64 // can only be used to send float64s |
| 1359 | <-chan int // can only be used to receive ints |
Robert Griesemer | 56ca697 | 2010-05-07 18:22:40 -0700 | [diff] [blame] | 1360 | </pre> |
| 1361 | |
| 1362 | <p> |
| 1363 | The <code><-</code> operator associates with the leftmost <code>chan</code> |
| 1364 | possible: |
Robert Griesemer | 1c369bd | 2010-01-27 09:35:39 -0800 | [diff] [blame] | 1365 | </p> |
| 1366 | |
| 1367 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1368 | chan<- chan int // same as chan<- (chan int) |
| 1369 | chan<- <-chan int // same as chan<- (<-chan int) |
| 1370 | <-chan <-chan int // same as <-chan (<-chan int) |
Robert Griesemer | 1c369bd | 2010-01-27 09:35:39 -0800 | [diff] [blame] | 1371 | chan (<-chan int) |
| 1372 | </pre> |
| 1373 | |
| 1374 | <p> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1375 | A new, initialized channel |
Robert Griesemer | 56ca697 | 2010-05-07 18:22:40 -0700 | [diff] [blame] | 1376 | value can be made using the built-in function |
| 1377 | <a href="#Making_slices_maps_and_channels"><code>make</code></a>, |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1378 | 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] | 1379 | </p> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1380 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1381 | <pre> |
Rob Pike | da38974 | 2009-03-02 19:13:40 -0800 | [diff] [blame] | 1382 | make(chan int, 100) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1383 | </pre> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1384 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1385 | <p> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1386 | The capacity, in number of elements, sets the size of the buffer in the channel. |
| 1387 | 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] | 1388 | succeeds only when both a sender and receiver are ready. Otherwise, the channel |
| 1389 | is buffered and communication succeeds without blocking if the buffer |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1390 | is not full (sends) or not empty (receives). |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 1391 | A <code>nil</code> channel is never ready for communication. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1392 | </p> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1393 | |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 1394 | <p> |
Russ Cox | 9f2cb86 | 2011-03-11 14:47:02 -0500 | [diff] [blame] | 1395 | A channel may be closed with the built-in function |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1396 | <a href="#Close"><code>close</code></a>. |
| 1397 | The multi-valued assignment form of the |
Russ Cox | 9f2cb86 | 2011-03-11 14:47:02 -0500 | [diff] [blame] | 1398 | <a href="#Receive_operator">receive operator</a> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1399 | reports whether a received value was sent before |
| 1400 | the channel was closed. |
| 1401 | </p> |
| 1402 | |
| 1403 | <p> |
| 1404 | A single channel may be used in |
| 1405 | <a href="#Send_statements">send statements</a>, |
| 1406 | <a href="#Receive_operator">receive operations</a>, |
| 1407 | and calls to the built-in functions |
| 1408 | <a href="#Length_and_capacity"><code>cap</code></a> and |
| 1409 | <a href="#Length_and_capacity"><code>len</code></a> |
| 1410 | by any number of goroutines without further synchronization. |
| 1411 | Channels act as first-in-first-out queues. |
| 1412 | For example, if one goroutine sends values on a channel |
| 1413 | and a second goroutine receives them, the values are |
| 1414 | received in the order sent. |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 1415 | </p> |
| 1416 | |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 1417 | <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] | 1418 | |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1419 | <h3 id="Type_identity">Type identity</h3> |
| 1420 | |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 1421 | <p> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1422 | Two types are either <i>identical</i> or <i>different</i>. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1423 | </p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1424 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1425 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1426 | A <a href="#Type_definitions">defined type</a> is always different from any other type. |
| 1427 | Otherwise, two types are identical if their <a href="#Types">underlying</a> type literals are |
| 1428 | structurally equivalent; that is, they have the same literal structure and corresponding |
| 1429 | components have identical types. In detail: |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 1430 | </p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1431 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1432 | <ul> |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1433 | <li>Two array types are identical if they have identical element types and |
| 1434 | the same array length.</li> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1435 | |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1436 | <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] | 1437 | |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1438 | <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] | 1439 | and if corresponding fields have the same names, and identical types, |
| 1440 | and identical tags. |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1441 | <a href="#Exported_identifiers">Non-exported</a> field names from different |
| 1442 | packages are always different.</li> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1443 | |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1444 | <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] | 1445 | |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1446 | <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] | 1447 | and result values, corresponding parameter and result types are |
| 1448 | identical, and either both functions are variadic or neither is. |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1449 | Parameter and result names are not required to match.</li> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1450 | |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1451 | <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] | 1452 | with the same names and identical function types. |
| 1453 | <a href="#Exported_identifiers">Non-exported</a> method names from different |
| 1454 | packages are always different. The order of the methods is irrelevant.</li> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1455 | |
Robert Griesemer | 4de1d1d | 2018-01-03 10:33:11 -0800 | [diff] [blame] | 1456 | <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] | 1457 | |
Robert Griesemer | 4de1d1d | 2018-01-03 10:33:11 -0800 | [diff] [blame] | 1458 | <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] | 1459 | the same direction.</li> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1460 | </ul> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1461 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1462 | <p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1463 | Given the declarations |
| 1464 | </p> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1465 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1466 | <pre> |
| 1467 | type ( |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1468 | A0 = []string |
| 1469 | A1 = A0 |
| 1470 | A2 = struct{ a, b int } |
| 1471 | A3 = int |
| 1472 | A4 = func(A3, float64) *A0 |
| 1473 | A5 = func(x int, _ float64) *[]string |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1474 | ) |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1475 | |
| 1476 | type ( |
| 1477 | B0 A0 |
| 1478 | B1 []string |
| 1479 | B2 struct{ a, b int } |
| 1480 | B3 struct{ a, c int } |
| 1481 | B4 func(int, float64) *B0 |
| 1482 | B5 func(x int, y float64) *A1 |
| 1483 | ) |
| 1484 | |
| 1485 | type C0 = B0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1486 | </pre> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1487 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1488 | <p> |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1489 | these types are identical: |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1490 | </p> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1491 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1492 | <pre> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1493 | A0, A1, and []string |
| 1494 | A2 and struct{ a, b int } |
| 1495 | A3 and int |
| 1496 | A4, func(int, float64) *[]string, and A5 |
| 1497 | |
Robert Griesemer | c13e0e8 | 2018-01-11 10:41:03 -0800 | [diff] [blame] | 1498 | B0 and C0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1499 | []int and []int |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1500 | struct{ a, b *T5 } and struct{ a, b *T5 } |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1501 | 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] | 1502 | </pre> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1503 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1504 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1505 | <code>B0</code> and <code>B1</code> are different because they are new types |
| 1506 | created by distinct <a href="#Type_definitions">type definitions</a>; |
| 1507 | <code>func(int, float64) *B0</code> and <code>func(x int, y float64) *[]string</code> |
| 1508 | are different because <code>B0</code> is different from <code>[]string</code>. |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1509 | </p> |
| 1510 | |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1511 | |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 1512 | <h3 id="Assignability">Assignability</h3> |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1513 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1514 | <p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 1515 | 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] | 1516 | ("<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] | 1517 | </p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1518 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1519 | <ul> |
| 1520 | <li> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1521 | <code>x</code>'s type is identical to <code>T</code>. |
| 1522 | </li> |
| 1523 | <li> |
Rob Pike | 68f1609 | 2010-09-01 10:40:50 +1000 | [diff] [blame] | 1524 | <code>x</code>'s type <code>V</code> and <code>T</code> have identical |
| 1525 | <a href="#Types">underlying types</a> and at least one of <code>V</code> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1526 | 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] | 1527 | </li> |
| 1528 | <li> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1529 | <code>T</code> is an interface type and |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1530 | <code>x</code> <a href="#Interface_types">implements</a> <code>T</code>. |
Robert Griesemer | e2cb60b | 2009-06-19 13:03:01 -0700 | [diff] [blame] | 1531 | </li> |
| 1532 | <li> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1533 | <code>x</code> is a bidirectional channel value, <code>T</code> is a channel type, |
| 1534 | <code>x</code>'s type <code>V</code> and <code>T</code> have identical element types, |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1535 | 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] | 1536 | </li> |
| 1537 | <li> |
| 1538 | <code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code> |
| 1539 | is a pointer, function, slice, map, channel, or interface type. |
| 1540 | </li> |
| 1541 | <li> |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 1542 | <code>x</code> is an untyped <a href="#Constants">constant</a> |
| 1543 | <a href="#Representability">representable</a> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1544 | by a value of type <code>T</code>. |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 1545 | </li> |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1546 | </ul> |
| 1547 | |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1548 | |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 1549 | <h3 id="Representability">Representability</h3> |
| 1550 | |
| 1551 | <p> |
| 1552 | A <a href="#Constants">constant</a> <code>x</code> is <i>representable</i> |
| 1553 | by a value of type <code>T</code> if one of the following conditions applies: |
| 1554 | </p> |
| 1555 | |
| 1556 | <ul> |
| 1557 | <li> |
| 1558 | <code>x</code> is in the set of values <a href="#Types">determined</a> by <code>T</code>. |
| 1559 | </li> |
| 1560 | |
| 1561 | <li> |
| 1562 | <code>T</code> is a floating-point type and <code>x</code> can be rounded to <code>T</code>'s |
| 1563 | precision without overflow. Rounding uses IEEE 754 round-to-even rules but with an IEEE |
| 1564 | negative zero further simplified to an unsigned zero. Note that constant values never result |
| 1565 | in an IEEE negative zero, NaN, or infinity. |
| 1566 | </li> |
| 1567 | |
| 1568 | <li> |
| 1569 | <code>T</code> is a complex type, and <code>x</code>'s |
| 1570 | <a href="#Complex_numbers">components</a> <code>real(x)</code> and <code>imag(x)</code> |
| 1571 | are representable by values of <code>T</code>'s component type (<code>float32</code> or |
| 1572 | <code>float64</code>). |
| 1573 | </li> |
| 1574 | </ul> |
| 1575 | |
| 1576 | <pre> |
| 1577 | x T x is representable by a value of T because |
| 1578 | |
| 1579 | 'a' byte 97 is in the set of byte values |
| 1580 | 97 rune rune is an alias for int32, and 97 is in the set of 32-bit integers |
| 1581 | "foo" string "foo" is in the set of string values |
| 1582 | 1024 int16 1024 is in the set of 16-bit integers |
| 1583 | 42.0 byte 42 is in the set of unsigned 8-bit integers |
| 1584 | 1e10 uint64 10000000000 is in the set of unsigned 64-bit integers |
| 1585 | 2.718281828459045 float32 2.718281828459045 rounds to 2.7182817 which is in the set of float32 values |
| 1586 | -1e-1000 float64 -1e-1000 rounds to IEEE -0.0 which is further simplified to 0.0 |
| 1587 | 0i int 0 is an integer value |
| 1588 | (42 + 0i) float32 42.0 (with zero imaginary part) is in the set of float32 values |
| 1589 | </pre> |
| 1590 | |
| 1591 | <pre> |
| 1592 | x T x is not representable by a value of T because |
| 1593 | |
| 1594 | 0 bool 0 is not in the set of boolean values |
| 1595 | 'a' string 'a' is a rune, it is not in the set of string values |
| 1596 | 1024 byte 1024 is not in the set of unsigned 8-bit integers |
| 1597 | -1 uint16 -1 is not in the set of unsigned 16-bit integers |
| 1598 | 1.1 int 1.1 is not an integer value |
| 1599 | 42i float32 (0 + 42i) is not in the set of float32 values |
| 1600 | 1e1000 float64 1e1000 overflows to IEEE +Inf after rounding |
| 1601 | </pre> |
| 1602 | |
| 1603 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1604 | <h2 id="Blocks">Blocks</h2> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1605 | |
| 1606 | <p> |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 1607 | A <i>block</i> is a possibly empty sequence of declarations and statements |
| 1608 | within matching brace brackets. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1609 | </p> |
| 1610 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1611 | <pre class="ebnf"> |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 1612 | Block = "{" StatementList "}" . |
| 1613 | StatementList = { Statement ";" } . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1614 | </pre> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 1615 | |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1616 | <p> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1617 | 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] | 1618 | </p> |
| 1619 | |
| 1620 | <ol> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1621 | <li>The <i>universe block</i> encompasses all Go source text.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1622 | |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 1623 | <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] | 1624 | Go source text for that package.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1625 | |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1626 | <li>Each file has a <i>file block</i> containing all Go source text |
| 1627 | in that file.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1628 | |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 1629 | <li>Each <a href="#If_statements">"if"</a>, |
| 1630 | <a href="#For_statements">"for"</a>, and |
| 1631 | <a href="#Switch_statements">"switch"</a> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1632 | statement is considered to be in its own implicit block.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1633 | |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 1634 | <li>Each clause in a <a href="#Switch_statements">"switch"</a> |
| 1635 | or <a href="#Select_statements">"select"</a> statement |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1636 | acts as an implicit block.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1637 | </ol> |
| 1638 | |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1639 | <p> |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 1640 | Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>. |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1641 | </p> |
| 1642 | |
| 1643 | |
Robert Griesemer | aeaab59 | 2009-08-31 17:30:55 -0700 | [diff] [blame] | 1644 | <h2 id="Declarations_and_scope">Declarations and scope</h2> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1645 | |
| 1646 | <p> |
Robert Griesemer | 4cc71e3 | 2013-10-03 16:38:22 -0700 | [diff] [blame] | 1647 | A <i>declaration</i> binds a non-<a href="#Blank_identifier">blank</a> identifier to a |
| 1648 | <a href="#Constant_declarations">constant</a>, |
| 1649 | <a href="#Type_declarations">type</a>, |
| 1650 | <a href="#Variable_declarations">variable</a>, |
| 1651 | <a href="#Function_declarations">function</a>, |
| 1652 | <a href="#Labeled_statements">label</a>, or |
| 1653 | <a href="#Import_declarations">package</a>. |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1654 | Every identifier in a program must be declared. |
| 1655 | No identifier may be declared twice in the same block, and |
| 1656 | no identifier may be declared in both the file and package block. |
| 1657 | </p> |
| 1658 | |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 1659 | <p> |
| 1660 | The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier |
| 1661 | 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] | 1662 | In the package block, the identifier <code>init</code> may only be used for |
| 1663 | <a href="#Package_initialization"><code>init</code> function</a> declarations, |
| 1664 | and like the blank identifier it does not introduce a new binding. |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 1665 | </p> |
| 1666 | |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1667 | <pre class="ebnf"> |
| 1668 | Declaration = ConstDecl | TypeDecl | VarDecl . |
| 1669 | TopLevelDecl = Declaration | FunctionDecl | MethodDecl . |
| 1670 | </pre> |
| 1671 | |
| 1672 | <p> |
| 1673 | 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] | 1674 | the identifier denotes the specified constant, type, variable, function, label, or package. |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1675 | </p> |
| 1676 | |
| 1677 | <p> |
Robert Griesemer | 4cc71e3 | 2013-10-03 16:38:22 -0700 | [diff] [blame] | 1678 | Go is lexically scoped using <a href="#Blocks">blocks</a>: |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1679 | </p> |
| 1680 | |
| 1681 | <ol> |
Robert Griesemer | 4cc71e3 | 2013-10-03 16:38:22 -0700 | [diff] [blame] | 1682 | <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] | 1683 | |
| 1684 | <li>The scope of an identifier denoting a constant, type, variable, |
Robert Griesemer | 967a2b3 | 2011-03-03 15:24:28 -0800 | [diff] [blame] | 1685 | or function (but not method) declared at top level (outside any |
| 1686 | function) is the package block.</li> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1687 | |
Robert Griesemer | e126763 | 2012-11-21 14:40:50 -0800 | [diff] [blame] | 1688 | <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] | 1689 | of the file containing the import declaration.</li> |
| 1690 | |
Robert Griesemer | 85e451e | 2012-11-29 14:47:47 -0800 | [diff] [blame] | 1691 | <li>The scope of an identifier denoting a method receiver, function parameter, |
| 1692 | or result variable is the function body.</li> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1693 | |
| 1694 | <li>The scope of a constant or variable identifier declared |
| 1695 | inside a function begins at the end of the ConstSpec or VarSpec |
Robert Griesemer | 95b8137 | 2011-06-12 12:09:50 -0700 | [diff] [blame] | 1696 | (ShortVarDecl for short variable declarations) |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1697 | and ends at the end of the innermost containing block.</li> |
| 1698 | |
| 1699 | <li>The scope of a type identifier declared inside a function |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 1700 | begins at the identifier in the TypeSpec |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1701 | and ends at the end of the innermost containing block.</li> |
| 1702 | </ol> |
| 1703 | |
| 1704 | <p> |
| 1705 | An identifier declared in a block may be redeclared in an inner block. |
| 1706 | While the identifier of the inner declaration is in scope, it denotes |
| 1707 | the entity declared by the inner declaration. |
| 1708 | </p> |
| 1709 | |
| 1710 | <p> |
Robert Griesemer | 506c008 | 2009-09-08 15:41:14 -0700 | [diff] [blame] | 1711 | 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] | 1712 | 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] | 1713 | 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] | 1714 | declarations. |
| 1715 | </p> |
| 1716 | |
| 1717 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1718 | <h3 id="Label_scopes">Label scopes</h3> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1719 | |
| 1720 | <p> |
Robert Griesemer | 506c008 | 2009-09-08 15:41:14 -0700 | [diff] [blame] | 1721 | 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] | 1722 | used in the <a href="#Break_statements">"break"</a>, |
| 1723 | <a href="#Continue_statements">"continue"</a>, and |
| 1724 | <a href="#Goto_statements">"goto"</a> statements. |
Russ Cox | 108564d | 2011-03-15 13:51:24 -0400 | [diff] [blame] | 1725 | It is illegal to define a label that is never used. |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1726 | In contrast to other identifiers, labels are not block scoped and do |
| 1727 | not conflict with identifiers that are not labels. The scope of a label |
| 1728 | is the body of the function in which it is declared and excludes |
| 1729 | the body of any nested function. |
| 1730 | </p> |
| 1731 | |
| 1732 | |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1733 | <h3 id="Blank_identifier">Blank identifier</h3> |
| 1734 | |
| 1735 | <p> |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 1736 | The <i>blank identifier</i> is represented by the underscore character <code>_</code>. |
| 1737 | It serves as an anonymous placeholder instead of a regular (non-blank) |
| 1738 | identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>, |
| 1739 | 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] | 1740 | </p> |
| 1741 | |
| 1742 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1743 | <h3 id="Predeclared_identifiers">Predeclared identifiers</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1744 | |
| 1745 | <p> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1746 | The following identifiers are implicitly declared in the |
| 1747 | <a href="#Blocks">universe block</a>: |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1748 | </p> |
| 1749 | <pre class="grammar"> |
Russ Cox | d9877e2 | 2011-11-01 21:45:02 -0400 | [diff] [blame] | 1750 | Types: |
| 1751 | bool byte complex64 complex128 error float32 float64 |
| 1752 | int int8 int16 int32 int64 rune string |
| 1753 | uint uint8 uint16 uint32 uint64 uintptr |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1754 | |
| 1755 | Constants: |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1756 | true false iota |
| 1757 | |
| 1758 | Zero value: |
| 1759 | nil |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1760 | |
| 1761 | Functions: |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 1762 | append cap close complex copy delete imag len |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 1763 | make new panic print println real recover |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1764 | </pre> |
| 1765 | |
Robert Griesemer | aeaab59 | 2009-08-31 17:30:55 -0700 | [diff] [blame] | 1766 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1767 | <h3 id="Exported_identifiers">Exported identifiers</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1768 | |
| 1769 | <p> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1770 | An identifier may be <i>exported</i> to permit access to it from another package. |
| 1771 | An identifier is exported if both: |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1772 | </p> |
| 1773 | <ol> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1774 | <li>the first character of the identifier's name is a Unicode upper case |
| 1775 | letter (Unicode class "Lu"); and</li> |
| 1776 | <li>the identifier is declared in the <a href="#Blocks">package block</a> |
| 1777 | or it is a <a href="#Struct_types">field name</a> or |
| 1778 | <a href="#MethodName">method name</a>.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1779 | </ol> |
| 1780 | <p> |
Robert Griesemer | aeaab59 | 2009-08-31 17:30:55 -0700 | [diff] [blame] | 1781 | All other identifiers are not exported. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1782 | </p> |
| 1783 | |
Robert Griesemer | aeaab59 | 2009-08-31 17:30:55 -0700 | [diff] [blame] | 1784 | |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1785 | <h3 id="Uniqueness_of_identifiers">Uniqueness of identifiers</h3> |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 1786 | |
| 1787 | <p> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1788 | Given a set of identifiers, an identifier is called <i>unique</i> if it is |
| 1789 | <i>different</i> from every other in the set. |
| 1790 | Two identifiers are different if they are spelled differently, or if they |
| 1791 | appear in different <a href="#Packages">packages</a> and are not |
Shenghou Ma | 2195f1a | 2012-03-30 14:04:03 +0800 | [diff] [blame] | 1792 | <a href="#Exported_identifiers">exported</a>. Otherwise, they are the same. |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 1793 | </p> |
| 1794 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1795 | <h3 id="Constant_declarations">Constant declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1796 | |
| 1797 | <p> |
| 1798 | A constant declaration binds a list of identifiers (the names of |
Robert Griesemer | 506c008 | 2009-09-08 15:41:14 -0700 | [diff] [blame] | 1799 | the constants) to the values of a list of <a href="#Constant_expressions">constant expressions</a>. |
| 1800 | The number of identifiers must be equal |
| 1801 | to the number of expressions, and the <i>n</i>th identifier on |
| 1802 | 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] | 1803 | right. |
| 1804 | </p> |
| 1805 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1806 | <pre class="ebnf"> |
Robert Griesemer | 87f4e36 | 2016-11-04 12:38:53 -0700 | [diff] [blame] | 1807 | ConstDecl = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) . |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 1808 | ConstSpec = IdentifierList [ [ Type ] "=" ExpressionList ] . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1809 | |
| 1810 | IdentifierList = identifier { "," identifier } . |
| 1811 | ExpressionList = Expression { "," Expression } . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1812 | </pre> |
| 1813 | |
| 1814 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1815 | If the type is present, all constants take the type specified, and |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 1816 | the expressions must be <a href="#Assignability">assignable</a> to that type. |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 1817 | If the type is omitted, the constants take the |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1818 | individual types of the corresponding expressions. |
| 1819 | If the expression values are untyped <a href="#Constants">constants</a>, |
| 1820 | the declared constants remain untyped and the constant identifiers |
| 1821 | denote the constant values. For instance, if the expression is a |
| 1822 | floating-point literal, the constant identifier denotes a floating-point |
| 1823 | constant, even if the literal's fractional part is zero. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1824 | </p> |
| 1825 | |
| 1826 | <pre> |
| 1827 | const Pi float64 = 3.14159265358979323846 |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1828 | const zero = 0.0 // untyped floating-point constant |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1829 | const ( |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1830 | size int64 = 1024 |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1831 | eof = -1 // untyped integer constant |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1832 | ) |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1833 | 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] | 1834 | const u, v float32 = 0, 3 // u = 0.0, v = 3.0 |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1835 | </pre> |
| 1836 | |
| 1837 | <p> |
| 1838 | Within a parenthesized <code>const</code> declaration list the |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 1839 | expression list may be omitted from any but the first ConstSpec. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1840 | Such an empty list is equivalent to the textual substitution of the |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 1841 | first preceding non-empty expression list and its type if any. |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 1842 | Omitting the list of expressions is therefore equivalent to |
| 1843 | repeating the previous list. The number of identifiers must be equal |
| 1844 | to the number of expressions in the previous list. |
Robert Griesemer | 506c008 | 2009-09-08 15:41:14 -0700 | [diff] [blame] | 1845 | Together with the <a href="#Iota"><code>iota</code> constant generator</a> |
| 1846 | this mechanism permits light-weight declaration of sequential values: |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1847 | </p> |
| 1848 | |
| 1849 | <pre> |
| 1850 | const ( |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1851 | Sunday = iota |
| 1852 | Monday |
| 1853 | Tuesday |
| 1854 | Wednesday |
| 1855 | Thursday |
| 1856 | Friday |
| 1857 | Partyday |
| 1858 | numberOfDays // this constant is not exported |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1859 | ) |
| 1860 | </pre> |
| 1861 | |
| 1862 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1863 | <h3 id="Iota">Iota</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1864 | |
| 1865 | <p> |
Robert Griesemer | 39f009c | 2010-04-29 10:57:27 -0700 | [diff] [blame] | 1866 | Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1867 | <code>iota</code> represents successive untyped integer <a href="#Constants"> |
griesemer | 52dd399 | 2017-10-18 15:31:42 -0700 | [diff] [blame] | 1868 | constants</a>. Its value is the index of the respective <a href="#ConstSpec">ConstSpec</a> |
| 1869 | in that constant declaration, starting at zero. |
Robert Griesemer | 39f009c | 2010-04-29 10:57:27 -0700 | [diff] [blame] | 1870 | It can be used to construct a set of related constants: |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1871 | </p> |
| 1872 | |
| 1873 | <pre> |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 1874 | const ( |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1875 | c0 = iota // c0 == 0 |
| 1876 | c1 = iota // c1 == 1 |
| 1877 | c2 = iota // c2 == 2 |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1878 | ) |
| 1879 | |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 1880 | const ( |
| 1881 | a = 1 << iota // a == 1 (iota == 0) |
| 1882 | b = 1 << iota // b == 2 (iota == 1) |
| 1883 | c = 3 // c == 3 (iota == 2, unused) |
| 1884 | d = 1 << iota // d == 8 (iota == 3) |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1885 | ) |
| 1886 | |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 1887 | const ( |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 1888 | u = iota * 42 // u == 0 (untyped integer constant) |
| 1889 | v float64 = iota * 42 // v == 42.0 (float64 constant) |
| 1890 | w = iota * 42 // w == 84 (untyped integer constant) |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1891 | ) |
| 1892 | |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 1893 | const x = iota // x == 0 |
| 1894 | const y = iota // y == 0 |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1895 | </pre> |
| 1896 | |
| 1897 | <p> |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 1898 | 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] | 1899 | </p> |
| 1900 | |
| 1901 | <pre> |
| 1902 | const ( |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 1903 | bit0, mask0 = 1 << iota, 1<<iota - 1 // bit0 == 1, mask0 == 0 (iota == 0) |
| 1904 | bit1, mask1 // bit1 == 2, mask1 == 1 (iota == 1) |
| 1905 | _, _ // (iota == 2, unused) |
| 1906 | bit3, mask3 // bit3 == 8, mask3 == 7 (iota == 3) |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1907 | ) |
| 1908 | </pre> |
| 1909 | |
| 1910 | <p> |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 1911 | This last example exploits the <a href="#Constant_declarations">implicit repetition</a> |
| 1912 | of the last non-empty expression list. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1913 | </p> |
| 1914 | |
| 1915 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1916 | <h3 id="Type_declarations">Type declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1917 | |
| 1918 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1919 | 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] | 1920 | Type declarations come in two forms: alias declarations and type definitions. |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1921 | <p> |
| 1922 | |
| 1923 | <pre class="ebnf"> |
| 1924 | TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) . |
| 1925 | TypeSpec = AliasDecl | TypeDef . |
| 1926 | </pre> |
| 1927 | |
| 1928 | <h4 id="Alias_declarations">Alias declarations</h4> |
| 1929 | |
| 1930 | <p> |
| 1931 | An alias declaration binds an identifier to the given type. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1932 | </p> |
| 1933 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1934 | <pre class="ebnf"> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1935 | AliasDecl = identifier "=" Type . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1936 | </pre> |
| 1937 | |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1938 | <p> |
| 1939 | Within the <a href="#Declarations_and_scope">scope</a> of |
| 1940 | the identifier, it serves as an <i>alias</i> for the type. |
| 1941 | </p> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1942 | |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1943 | <pre> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1944 | type ( |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1945 | nodeList = []*Node // nodeList and []*Node are identical types |
| 1946 | Polar = polar // Polar and polar denote identical types |
| 1947 | ) |
| 1948 | </pre> |
| 1949 | |
| 1950 | |
| 1951 | <h4 id="Type_definitions">Type definitions</h4> |
| 1952 | |
| 1953 | <p> |
Robert Griesemer | c0bd4f3 | 2017-02-06 15:57:00 -0800 | [diff] [blame] | 1954 | A type definition creates a new, distinct type with the same |
| 1955 | <a href="#Types">underlying type</a> and operations as the given type, |
| 1956 | and binds an identifier to it. |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1957 | </p> |
| 1958 | |
| 1959 | <pre class="ebnf"> |
| 1960 | TypeDef = identifier Type . |
| 1961 | </pre> |
| 1962 | |
| 1963 | <p> |
| 1964 | The new type is called a <i>defined type</i>. |
| 1965 | It is <a href="#Type_identity">different</a> from any other type, |
| 1966 | including the type it is created from. |
| 1967 | </p> |
| 1968 | |
| 1969 | <pre> |
| 1970 | type ( |
| 1971 | Point struct{ x, y float64 } // Point and struct{ x, y float64 } are different types |
| 1972 | polar Point // polar and Point denote different types |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1973 | ) |
| 1974 | |
| 1975 | type TreeNode struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1976 | left, right *TreeNode |
| 1977 | value *Comparable |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1978 | } |
| 1979 | |
Rob Pike | 217408a | 2011-11-09 14:22:44 -0800 | [diff] [blame] | 1980 | type Block interface { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1981 | BlockSize() int |
| 1982 | Encrypt(src, dst []byte) |
| 1983 | Decrypt(src, dst []byte) |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1984 | } |
| 1985 | </pre> |
| 1986 | |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 1987 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1988 | A defined type may have <a href="#Method_declarations">methods</a> associated with it. |
| 1989 | It does not inherit any methods bound to the given type, |
| 1990 | but the <a href="#Method_sets">method set</a> |
Robert Griesemer | d4a1619 | 2010-04-01 12:48:34 -0700 | [diff] [blame] | 1991 | 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] | 1992 | </p> |
| 1993 | |
| 1994 | <pre> |
Rob Pike | bdbe0de | 2011-05-25 06:00:07 +1000 | [diff] [blame] | 1995 | // A Mutex is a data type with two methods, Lock and Unlock. |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 1996 | type Mutex struct { /* Mutex fields */ } |
| 1997 | func (m *Mutex) Lock() { /* Lock implementation */ } |
| 1998 | func (m *Mutex) Unlock() { /* Unlock implementation */ } |
| 1999 | |
| 2000 | // NewMutex has the same composition as Mutex but its method set is empty. |
| 2001 | type NewMutex Mutex |
| 2002 | |
griesemer | 5abc8c89 | 2017-08-11 16:51:40 +0200 | [diff] [blame] | 2003 | // The method set of PtrMutex's underlying type *Mutex remains unchanged, |
Robert Griesemer | 2a838d6 | 2011-02-08 13:31:01 -0800 | [diff] [blame] | 2004 | // but the method set of PtrMutex is empty. |
| 2005 | type PtrMutex *Mutex |
| 2006 | |
Robert Griesemer | f5b3c14 | 2010-04-27 17:52:44 -0700 | [diff] [blame] | 2007 | // The method set of *PrintableMutex contains the methods |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 2008 | // Lock and Unlock bound to its embedded field Mutex. |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2009 | type PrintableMutex struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2010 | Mutex |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2011 | } |
Robert Griesemer | 735e00d | 2010-03-31 16:37:22 -0700 | [diff] [blame] | 2012 | |
Rob Pike | 217408a | 2011-11-09 14:22:44 -0800 | [diff] [blame] | 2013 | // MyBlock is an interface type that has the same method set as Block. |
| 2014 | type MyBlock Block |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2015 | </pre> |
| 2016 | |
| 2017 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2018 | Type definitions may be used to define different boolean, numeric, |
| 2019 | or string types and associate methods with them: |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2020 | </p> |
| 2021 | |
| 2022 | <pre> |
| 2023 | type TimeZone int |
| 2024 | |
| 2025 | const ( |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2026 | EST TimeZone = -(5 + iota) |
| 2027 | CST |
| 2028 | MST |
| 2029 | PST |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2030 | ) |
| 2031 | |
| 2032 | func (tz TimeZone) String() string { |
Robert Griesemer | 02d7448 | 2015-07-31 11:15:11 -0700 | [diff] [blame] | 2033 | return fmt.Sprintf("GMT%+dh", tz) |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2034 | } |
| 2035 | </pre> |
| 2036 | |
| 2037 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2038 | <h3 id="Variable_declarations">Variable declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2039 | |
| 2040 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2041 | A variable declaration creates one or more <a href="#Variables">variables</a>, |
| 2042 | 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] | 2043 | </p> |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2044 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2045 | <pre class="ebnf"> |
Robert Griesemer | 87f4e36 | 2016-11-04 12:38:53 -0700 | [diff] [blame] | 2046 | VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) . |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 2047 | VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2048 | </pre> |
| 2049 | |
| 2050 | <pre> |
| 2051 | var i int |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 2052 | var U, V, W float64 |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2053 | var k = 0 |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 2054 | var x, y float32 = -1, -2 |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2055 | var ( |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 2056 | i int |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2057 | u, v, s = 2.0, 3.0, "bar" |
| 2058 | ) |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 2059 | var re, im = complexSqrt(-1) |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2060 | var _, found = entries[name] // map lookup; only interested in "found" |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2061 | </pre> |
| 2062 | |
| 2063 | <p> |
Robert Griesemer | ef45e64 | 2009-08-21 11:25:00 -0700 | [diff] [blame] | 2064 | If a list of expressions is given, the variables are initialized |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2065 | with the expressions following the rules for <a href="#Assignments">assignments</a>. |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 2066 | 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] | 2067 | </p> |
Robert Griesemer | ef45e64 | 2009-08-21 11:25:00 -0700 | [diff] [blame] | 2068 | |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2069 | <p> |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2070 | If a type is present, each variable is given that type. |
| 2071 | Otherwise, each variable is given the type of the corresponding |
| 2072 | initialization value in the assignment. |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 2073 | If that value is an untyped constant, it is first implicitly |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2074 | <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] | 2075 | 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] | 2076 | The predeclared value <code>nil</code> cannot be used to initialize a variable |
| 2077 | with no explicit type. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2078 | </p> |
Robert Griesemer | ef45e64 | 2009-08-21 11:25:00 -0700 | [diff] [blame] | 2079 | |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2080 | <pre> |
Brad Fitzpatrick | 5f029de | 2014-12-22 07:58:26 -0800 | [diff] [blame] | 2081 | var d = math.Sin(0.5) // d is float64 |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2082 | var i = 42 // i is int |
| 2083 | var t, ok = x.(T) // t is T, ok is bool |
| 2084 | var n = nil // illegal |
| 2085 | </pre> |
Robert Griesemer | 2c9e163 | 2012-02-28 17:44:24 -0800 | [diff] [blame] | 2086 | |
| 2087 | <p> |
| 2088 | Implementation restriction: A compiler may make it illegal to declare a variable |
| 2089 | inside a <a href="#Function_declarations">function body</a> if the variable is |
| 2090 | never used. |
| 2091 | </p> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2092 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2093 | <h3 id="Short_variable_declarations">Short variable declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2094 | |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2095 | <p> |
Robert Griesemer | ef45e64 | 2009-08-21 11:25:00 -0700 | [diff] [blame] | 2096 | A <i>short variable declaration</i> uses the syntax: |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2097 | </p> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2098 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2099 | <pre class="ebnf"> |
Robert Griesemer | e1b8cb8 | 2009-07-16 20:31:41 -0700 | [diff] [blame] | 2100 | ShortVarDecl = IdentifierList ":=" ExpressionList . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2101 | </pre> |
| 2102 | |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2103 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 2104 | 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] | 2105 | with initializer expressions but no types: |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2106 | </p> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2107 | |
| 2108 | <pre class="grammar"> |
| 2109 | "var" IdentifierList = ExpressionList . |
| 2110 | </pre> |
| 2111 | |
| 2112 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2113 | i, j := 0, 10 |
| 2114 | f := func() int { return 7 } |
| 2115 | ch := make(chan int) |
Dina Garmash | 8a2b5f1 | 2018-08-30 16:59:29 -0400 | [diff] [blame] | 2116 | r, w, _ := os.Pipe() // os.Pipe() returns a connected pair of Files and an error, if any |
| 2117 | _, y, _ := coord(p) // coord() returns three values; only interested in y coordinate |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2118 | </pre> |
| 2119 | |
| 2120 | <p> |
Robert Griesemer | 85789da | 2015-08-04 11:29:28 -0700 | [diff] [blame] | 2121 | Unlike regular variable declarations, a short variable declaration may <i>redeclare</i> |
| 2122 | variables provided they were originally declared earlier in the same block |
Robert Griesemer | 120cf67 | 2016-11-17 16:39:11 -0800 | [diff] [blame] | 2123 | (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] | 2124 | and at least one of the non-<a href="#Blank_identifier">blank</a> variables is new. |
| 2125 | As a consequence, redeclaration can only appear in a multi-variable short declaration. |
| 2126 | 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] | 2127 | </p> |
| 2128 | |
| 2129 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2130 | field1, offset := nextField(str, 0) |
| 2131 | field2, offset := nextField(str, offset) // redeclares offset |
Robert Griesemer | f1cc0f4 | 2013-01-09 11:31:32 -0800 | [diff] [blame] | 2132 | 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] | 2133 | </pre> |
| 2134 | |
| 2135 | <p> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2136 | Short variable declarations may appear only inside functions. |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 2137 | In some contexts such as the initializers for |
| 2138 | <a href="#If_statements">"if"</a>, |
| 2139 | <a href="#For_statements">"for"</a>, or |
| 2140 | <a href="#Switch_statements">"switch"</a> statements, |
| 2141 | they can be used to declare local temporary variables. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2142 | </p> |
| 2143 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2144 | <h3 id="Function_declarations">Function declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2145 | |
| 2146 | <p> |
Robert Griesemer | b1d9ae9 | 2012-02-12 20:03:30 -0800 | [diff] [blame] | 2147 | A function declaration binds an identifier, the <i>function name</i>, |
| 2148 | to a function. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2149 | </p> |
| 2150 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2151 | <pre class="ebnf"> |
Robert Griesemer | 851e98f | 2018-02-01 14:08:45 -0800 | [diff] [blame] | 2152 | FunctionDecl = "func" FunctionName Signature [ FunctionBody ] . |
Robert Griesemer | b1d9ae9 | 2012-02-12 20:03:30 -0800 | [diff] [blame] | 2153 | FunctionName = identifier . |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 2154 | FunctionBody = Block . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2155 | </pre> |
| 2156 | |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 2157 | <p> |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 2158 | If the function's <a href="#Function_types">signature</a> declares |
| 2159 | result parameters, the function body's statement list must end in |
| 2160 | a <a href="#Terminating_statements">terminating statement</a>. |
| 2161 | </p> |
| 2162 | |
Rob Pike | d020891 | 2013-03-22 10:03:55 -0700 | [diff] [blame] | 2163 | <pre> |
Robert Griesemer | 02d7448 | 2015-07-31 11:15:11 -0700 | [diff] [blame] | 2164 | func IndexRune(s string, r rune) int { |
| 2165 | for i, c := range s { |
| 2166 | if c == r { |
| 2167 | return i |
Rob Pike | d020891 | 2013-03-22 10:03:55 -0700 | [diff] [blame] | 2168 | } |
| 2169 | } |
Robert Griesemer | 02d7448 | 2015-07-31 11:15:11 -0700 | [diff] [blame] | 2170 | // invalid: missing return statement |
Rob Pike | d020891 | 2013-03-22 10:03:55 -0700 | [diff] [blame] | 2171 | } |
| 2172 | </pre> |
| 2173 | |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 2174 | <p> |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 2175 | A function declaration may omit the body. Such a declaration provides the |
| 2176 | signature for a function implemented outside Go, such as an assembly routine. |
| 2177 | </p> |
| 2178 | |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2179 | <pre> |
| 2180 | func min(x int, y int) int { |
| 2181 | if x < y { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2182 | return x |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2183 | } |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2184 | return y |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2185 | } |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 2186 | |
| 2187 | func flushICache(begin, end uintptr) // implemented externally |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2188 | </pre> |
| 2189 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2190 | <h3 id="Method_declarations">Method declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2191 | |
| 2192 | <p> |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 2193 | A method is a <a href="#Function_declarations">function</a> with a <i>receiver</i>. |
| 2194 | A method declaration binds an identifier, the <i>method name</i>, to a method, |
| 2195 | and associates the method with the receiver's <i>base type</i>. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2196 | </p> |
Robert Griesemer | b1d9ae9 | 2012-02-12 20:03:30 -0800 | [diff] [blame] | 2197 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2198 | <pre class="ebnf"> |
Robert Griesemer | 851e98f | 2018-02-01 14:08:45 -0800 | [diff] [blame] | 2199 | MethodDecl = "func" Receiver MethodName Signature [ FunctionBody ] . |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2200 | Receiver = Parameters . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2201 | </pre> |
| 2202 | |
| 2203 | <p> |
Paolo Martini | 3549178 | 2015-07-17 17:26:08 +0200 | [diff] [blame] | 2204 | The receiver is specified via an extra parameter section preceding the method |
Robert Griesemer | 57c81ef | 2015-12-15 13:13:38 -0800 | [diff] [blame] | 2205 | 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] | 2206 | Its type must be a <a href="#Type_definitions">defined</a> type <code>T</code> or a |
| 2207 | pointer to a defined type <code>T</code>. <code>T</code> is called the receiver |
| 2208 | <i>base type</i>. A receiver base type cannot be a pointer or interface type and |
| 2209 | it must be defined in the same package as the method. |
| 2210 | 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] | 2211 | is visible only within <a href="#Selectors">selectors</a> for type <code>T</code> |
| 2212 | or <code>*T</code>. |
Robert Griesemer | b1d9ae9 | 2012-02-12 20:03:30 -0800 | [diff] [blame] | 2213 | </p> |
| 2214 | |
| 2215 | <p> |
Robert Griesemer | 85e451e | 2012-11-29 14:47:47 -0800 | [diff] [blame] | 2216 | A non-<a href="#Blank_identifier">blank</a> receiver identifier must be |
| 2217 | <a href="#Uniqueness_of_identifiers">unique</a> in the method signature. |
| 2218 | If the receiver's value is not referenced inside the body of the method, |
| 2219 | its identifier may be omitted in the declaration. The same applies in |
| 2220 | general to parameters of functions and methods. |
| 2221 | </p> |
| 2222 | |
| 2223 | <p> |
| 2224 | 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] | 2225 | If the base type is a <a href="#Struct_types">struct type</a>, |
| 2226 | the non-blank method and field names must be distinct. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2227 | </p> |
| 2228 | |
| 2229 | <p> |
Robert Griesemer | bb3e211 | 2018-10-16 16:50:25 -0700 | [diff] [blame] | 2230 | Given defined type <code>Point</code>, the declarations |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2231 | </p> |
| 2232 | |
| 2233 | <pre> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2234 | func (p *Point) Length() float64 { |
| 2235 | return math.Sqrt(p.x * p.x + p.y * p.y) |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2236 | } |
| 2237 | |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2238 | func (p *Point) Scale(factor float64) { |
| 2239 | p.x *= factor |
| 2240 | p.y *= factor |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2241 | } |
| 2242 | </pre> |
| 2243 | |
| 2244 | <p> |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 2245 | bind the methods <code>Length</code> and <code>Scale</code>, |
| 2246 | with receiver type <code>*Point</code>, |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2247 | to the base type <code>Point</code>. |
| 2248 | </p> |
| 2249 | |
| 2250 | <p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2251 | The type of a method is the type of a function with the receiver as first |
| 2252 | argument. For instance, the method <code>Scale</code> has type |
| 2253 | </p> |
| 2254 | |
| 2255 | <pre> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2256 | func(p *Point, factor float64) |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2257 | </pre> |
| 2258 | |
| 2259 | <p> |
| 2260 | However, a function declared this way is not a method. |
| 2261 | </p> |
| 2262 | |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2263 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2264 | <h2 id="Expressions">Expressions</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2265 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2266 | <p> |
| 2267 | An expression specifies the computation of a value by applying |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 2268 | operators and functions to operands. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2269 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2270 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2271 | <h3 id="Operands">Operands</h3> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2272 | |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2273 | <p> |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 2274 | 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] | 2275 | literal, a (possibly <a href="#Qualified_identifiers">qualified</a>) |
| 2276 | non-<a href="#Blank_identifier">blank</a> identifier denoting a |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 2277 | <a href="#Constant_declarations">constant</a>, |
| 2278 | <a href="#Variable_declarations">variable</a>, or |
| 2279 | <a href="#Function_declarations">function</a>, |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 2280 | or a parenthesized expression. |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2281 | </p> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2282 | |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 2283 | <p> |
| 2284 | The <a href="#Blank_identifier">blank identifier</a> may appear as an |
| 2285 | operand only on the left-hand side of an <a href="#Assignments">assignment</a>. |
| 2286 | </p> |
| 2287 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2288 | <pre class="ebnf"> |
griesemer | f2d5251 | 2017-10-25 11:26:02 -0700 | [diff] [blame] | 2289 | Operand = Literal | OperandName | "(" Expression ")" . |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 2290 | Literal = BasicLit | CompositeLit | FunctionLit . |
| 2291 | BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit . |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 2292 | OperandName = identifier | QualifiedIdent. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2293 | </pre> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2294 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2295 | <h3 id="Qualified_identifiers">Qualified identifiers</h3> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2296 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2297 | <p> |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 2298 | A qualified identifier is an identifier qualified with a package name prefix. |
| 2299 | Both the package name and the identifier must not be |
| 2300 | <a href="#Blank_identifier">blank</a>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2301 | </p> |
Robert Griesemer | 337af31 | 2008-11-17 18:11:36 -0800 | [diff] [blame] | 2302 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2303 | <pre class="ebnf"> |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 2304 | QualifiedIdent = PackageName "." identifier . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2305 | </pre> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2306 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2307 | <p> |
Robert Griesemer | da63371 | 2012-02-29 09:06:05 -0800 | [diff] [blame] | 2308 | A qualified identifier accesses an identifier in a different package, which |
| 2309 | must be <a href="#Import_declarations">imported</a>. |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 2310 | The identifier must be <a href="#Exported_identifiers">exported</a> and |
| 2311 | declared in the <a href="#Blocks">package block</a> of that package. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2312 | </p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2313 | |
| 2314 | <pre> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 2315 | math.Sin // denotes the Sin function in package math |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2316 | </pre> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2317 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2318 | <h3 id="Composite_literals">Composite literals</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2319 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2320 | <p> |
| 2321 | Composite literals construct values for structs, arrays, slices, and maps |
| 2322 | and create a new value each time they are evaluated. |
Robert Griesemer | c720875 | 2015-09-22 17:47:38 -0700 | [diff] [blame] | 2323 | 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] | 2324 | Each element may optionally be preceded by a corresponding key. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2325 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2326 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2327 | <pre class="ebnf"> |
Robert Griesemer | a12141e | 2010-10-22 08:58:52 -0700 | [diff] [blame] | 2328 | CompositeLit = LiteralType LiteralValue . |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2329 | LiteralType = StructType | ArrayType | "[" "..." "]" ElementType | |
Robert Griesemer | 07cc644 | 2010-07-29 18:13:41 -0700 | [diff] [blame] | 2330 | SliceType | MapType | TypeName . |
Robert Griesemer | a12141e | 2010-10-22 08:58:52 -0700 | [diff] [blame] | 2331 | LiteralValue = "{" [ ElementList [ "," ] ] "}" . |
Robert Griesemer | 3b02242 | 2015-09-11 16:20:23 -0700 | [diff] [blame] | 2332 | ElementList = KeyedElement { "," KeyedElement } . |
| 2333 | KeyedElement = [ Key ":" ] Element . |
Robert Griesemer | 7727dee | 2015-01-08 16:01:31 -0800 | [diff] [blame] | 2334 | Key = FieldName | Expression | LiteralValue . |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 2335 | FieldName = identifier . |
Robert Griesemer | 3b02242 | 2015-09-11 16:20:23 -0700 | [diff] [blame] | 2336 | Element = Expression | LiteralValue . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2337 | </pre> |
Robert Griesemer | 0976e34 | 2008-09-03 13:37:44 -0700 | [diff] [blame] | 2338 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2339 | <p> |
Robert Griesemer | c720875 | 2015-09-22 17:47:38 -0700 | [diff] [blame] | 2340 | 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] | 2341 | (the grammar enforces this constraint except when the type is given |
| 2342 | as a TypeName). |
Robert Griesemer | 3b02242 | 2015-09-11 16:20:23 -0700 | [diff] [blame] | 2343 | 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] | 2344 | to the respective field, element, and key types of the literal type; |
Russ Cox | 7a5e97b | 2009-03-03 15:40:30 -0800 | [diff] [blame] | 2345 | there is no additional conversion. |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2346 | The key is interpreted as a field name for struct literals, |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 2347 | 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] | 2348 | For map literals, all elements must have a key. It is an error |
| 2349 | to specify multiple elements with the same field name or |
Robert Griesemer | 369d108 | 2017-03-24 09:19:46 -0700 | [diff] [blame] | 2350 | constant key value. For non-constant map keys, see the section on |
| 2351 | <a href="#Order_of_evaluation">evaluation order</a>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2352 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2353 | |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2354 | <p> |
| 2355 | For struct literals the following rules apply: |
Robert Griesemer | cfe9211 | 2009-06-18 13:29:40 -0700 | [diff] [blame] | 2356 | </p> |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2357 | <ul> |
Robert Griesemer | c720875 | 2015-09-22 17:47:38 -0700 | [diff] [blame] | 2358 | <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] | 2359 | </li> |
Robert Griesemer | 369a974 | 2012-10-31 15:07:25 -0700 | [diff] [blame] | 2360 | <li>An element list that does not contain any keys must |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2361 | list an element for each struct field in the |
| 2362 | order in which the fields are declared. |
| 2363 | </li> |
| 2364 | <li>If any element has a key, every element must have a key. |
| 2365 | </li> |
Robert Griesemer | 369a974 | 2012-10-31 15:07:25 -0700 | [diff] [blame] | 2366 | <li>An element list that contains keys does not need to |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2367 | have an element for each struct field. Omitted fields |
| 2368 | get the zero value for that field. |
| 2369 | </li> |
| 2370 | <li>A literal may omit the element list; such a literal evaluates |
Robert Griesemer | 369a974 | 2012-10-31 15:07:25 -0700 | [diff] [blame] | 2371 | to the zero value for its type. |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2372 | </li> |
| 2373 | <li>It is an error to specify an element for a non-exported |
| 2374 | field of a struct belonging to a different package. |
| 2375 | </li> |
| 2376 | </ul> |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2377 | |
| 2378 | <p> |
| 2379 | Given the declarations |
| 2380 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2381 | <pre> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2382 | type Point3D struct { x, y, z float64 } |
| 2383 | type Line struct { p, q Point3D } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2384 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2385 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2386 | <p> |
| 2387 | one may write |
| 2388 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2389 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2390 | <pre> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2391 | origin := Point3D{} // zero value for Point3D |
| 2392 | 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] | 2393 | </pre> |
| 2394 | |
Robert Griesemer | cfe9211 | 2009-06-18 13:29:40 -0700 | [diff] [blame] | 2395 | <p> |
| 2396 | For array and slice literals the following rules apply: |
| 2397 | </p> |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2398 | <ul> |
| 2399 | <li>Each element has an associated integer index marking |
| 2400 | its position in the array. |
| 2401 | </li> |
Robert Griesemer | a016ecf | 2016-10-05 15:59:09 -0700 | [diff] [blame] | 2402 | <li>An element with a key uses the key as its index. The |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 2403 | key must be a non-negative constant |
| 2404 | <a href="#Representability">representable</a> by |
Robert Griesemer | a016ecf | 2016-10-05 15:59:09 -0700 | [diff] [blame] | 2405 | a value of type <code>int</code>; and if it is typed |
| 2406 | it must be of integer type. |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2407 | </li> |
| 2408 | <li>An element without a key uses the previous element's index plus one. |
| 2409 | If the first element has no key, its index is zero. |
| 2410 | </li> |
| 2411 | </ul> |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2412 | |
Rob Pike | 37ab838 | 2009-03-18 22:58:36 -0700 | [diff] [blame] | 2413 | <p> |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 2414 | <a href="#Address_operators">Taking the address</a> of a composite literal |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 2415 | generates a pointer to a unique <a href="#Variables">variable</a> initialized |
| 2416 | with the literal's value. |
Rob Pike | 37ab838 | 2009-03-18 22:58:36 -0700 | [diff] [blame] | 2417 | </p> |
Rob Pike | 37ab838 | 2009-03-18 22:58:36 -0700 | [diff] [blame] | 2418 | <pre> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2419 | var pointer *Point3D = &Point3D{y: 1000} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2420 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2421 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2422 | <p> |
Robert Griesemer | c720875 | 2015-09-22 17:47:38 -0700 | [diff] [blame] | 2423 | 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] | 2424 | 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] | 2425 | elements are set to the zero value for the array element type. |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2426 | It is an error to provide elements with index values outside the index range |
| 2427 | of the array. The notation <code>...</code> specifies an array length equal |
| 2428 | to the maximum element index plus one. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2429 | </p> |
Robert Griesemer | b90b213 | 2008-09-19 15:49:55 -0700 | [diff] [blame] | 2430 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2431 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 2432 | buffer := [10]string{} // len(buffer) == 10 |
| 2433 | intSet := [6]int{1, 2, 3, 5} // len(intSet) == 6 |
| 2434 | days := [...]string{"Sat", "Sun"} // len(days) == 2 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2435 | </pre> |
Robert Griesemer | 91bbd64 | 2009-01-07 09:31:35 -0800 | [diff] [blame] | 2436 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2437 | <p> |
| 2438 | A slice literal describes the entire underlying array literal. |
Robert Griesemer | a656390 | 2016-08-25 21:01:17 -0700 | [diff] [blame] | 2439 | Thus the length and capacity of a slice literal are the maximum |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2440 | element index plus one. A slice literal has the form |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2441 | </p> |
Robert Griesemer | 91bbd64 | 2009-01-07 09:31:35 -0800 | [diff] [blame] | 2442 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2443 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 2444 | []T{x1, x2, … xn} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2445 | </pre> |
Robert Griesemer | 91bbd64 | 2009-01-07 09:31:35 -0800 | [diff] [blame] | 2446 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2447 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 2448 | and is shorthand for a slice operation applied to an array: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2449 | </p> |
Robert Griesemer | 91bbd64 | 2009-01-07 09:31:35 -0800 | [diff] [blame] | 2450 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2451 | <pre> |
Russ Cox | 4dfe976 | 2011-12-02 12:30:20 -0500 | [diff] [blame] | 2452 | tmp := [n]T{x1, x2, … xn} |
| 2453 | tmp[0 : n] |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2454 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2455 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2456 | <p> |
Robert Griesemer | a12141e | 2010-10-22 08:58:52 -0700 | [diff] [blame] | 2457 | 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] | 2458 | elements or map keys that are themselves composite literals may elide the respective |
| 2459 | literal type if it is identical to the element or key type of <code>T</code>. |
| 2460 | Similarly, elements or keys that are addresses of composite literals may elide |
| 2461 | 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] | 2462 | </p> |
| 2463 | |
| 2464 | <pre> |
Robert Griesemer | 7727dee | 2015-01-08 16:01:31 -0800 | [diff] [blame] | 2465 | [...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}} |
| 2466 | [][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}} |
| 2467 | [][]Point{{{0, 1}, {1, 2}}} // same as [][]Point{[]Point{Point{0, 1}, Point{1, 2}}} |
| 2468 | 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] | 2469 | 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] | 2470 | |
| 2471 | type PPoint *Point |
| 2472 | [2]*Point{{1.5, -3.5}, {}} // same as [2]*Point{&Point{1.5, -3.5}, &Point{}} |
| 2473 | [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] | 2474 | </pre> |
| 2475 | |
| 2476 | <p> |
Russ Cox | 7a5e97b | 2009-03-03 15:40:30 -0800 | [diff] [blame] | 2477 | A parsing ambiguity arises when a composite literal using the |
Robert Griesemer | a36b5b9 | 2014-02-27 08:57:30 -0800 | [diff] [blame] | 2478 | TypeName form of the LiteralType appears as an operand between the |
| 2479 | <a href="#Keywords">keyword</a> and the opening brace of the block |
| 2480 | of an "if", "for", or "switch" statement, and the composite literal |
| 2481 | is not enclosed in parentheses, square brackets, or curly braces. |
| 2482 | In this rare case, the opening brace of the literal is erroneously parsed |
| 2483 | as the one introducing the block of statements. To resolve the ambiguity, |
| 2484 | the composite literal must appear within parentheses. |
Russ Cox | 7a5e97b | 2009-03-03 15:40:30 -0800 | [diff] [blame] | 2485 | </p> |
| 2486 | |
| 2487 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 2488 | if x == (T{a,b,c}[i]) { … } |
| 2489 | if (x == T{a,b,c}[i]) { … } |
Russ Cox | 7a5e97b | 2009-03-03 15:40:30 -0800 | [diff] [blame] | 2490 | </pre> |
| 2491 | |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2492 | <p> |
| 2493 | Examples of valid array, slice, and map literals: |
| 2494 | </p> |
| 2495 | |
| 2496 | <pre> |
| 2497 | // list of prime numbers |
Andrew Bonventre | 7974f08 | 2018-03-19 21:50:42 +0000 | [diff] [blame] | 2498 | primes := []int{2, 3, 5, 7, 9, 2147483647} |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2499 | |
| 2500 | // vowels[ch] is true if ch is a vowel |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2501 | 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] | 2502 | |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 2503 | // the array [10]float32{-1, 0, 0, 0, -0.1, -0.1, 0, 0, 0, -1} |
| 2504 | filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1} |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2505 | |
| 2506 | // frequencies in Hz for equal-tempered scale (A4 = 440Hz) |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 2507 | noteFrequency := map[string]float32{ |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2508 | "C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83, |
| 2509 | "G0": 24.50, "A0": 27.50, "B0": 30.87, |
| 2510 | } |
| 2511 | </pre> |
| 2512 | |
| 2513 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2514 | <h3 id="Function_literals">Function literals</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2515 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2516 | <p> |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 2517 | A function literal represents an anonymous <a href="#Function_declarations">function</a>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2518 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2519 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2520 | <pre class="ebnf"> |
Robert Griesemer | 851e98f | 2018-02-01 14:08:45 -0800 | [diff] [blame] | 2521 | FunctionLit = "func" Signature FunctionBody . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2522 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2523 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2524 | <pre> |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 2525 | func(a, b int, z float64) bool { return a*b < int(z) } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2526 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2527 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2528 | <p> |
| 2529 | A function literal can be assigned to a variable or invoked directly. |
| 2530 | </p> |
Robert Griesemer | 7231ceb | 2008-09-08 15:01:04 -0700 | [diff] [blame] | 2531 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2532 | <pre> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2533 | f := func(x, y int) int { return x + y } |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 2534 | func(ch chan int) { ch <- ACK }(replyChan) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2535 | </pre> |
Robert Griesemer | 7231ceb | 2008-09-08 15:01:04 -0700 | [diff] [blame] | 2536 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2537 | <p> |
| 2538 | Function literals are <i>closures</i>: they may refer to variables |
Robert Griesemer | d8a764c | 2009-02-06 17:01:10 -0800 | [diff] [blame] | 2539 | defined in a surrounding function. Those variables are then shared between |
| 2540 | the surrounding function and the function literal, and they survive as long |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2541 | as they are accessible. |
| 2542 | </p> |
Robert Griesemer | 7231ceb | 2008-09-08 15:01:04 -0700 | [diff] [blame] | 2543 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2544 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2545 | <h3 id="Primary_expressions">Primary expressions</h3> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 2546 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 2547 | <p> |
| 2548 | Primary expressions are the operands for unary and binary expressions. |
| 2549 | </p> |
| 2550 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2551 | <pre class="ebnf"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2552 | PrimaryExpr = |
| 2553 | Operand | |
Robert Griesemer | 5eb3624 | 2009-09-16 11:05:14 -0700 | [diff] [blame] | 2554 | Conversion | |
griesemer | f2d5251 | 2017-10-25 11:26:02 -0700 | [diff] [blame] | 2555 | MethodExpr | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2556 | PrimaryExpr Selector | |
| 2557 | PrimaryExpr Index | |
| 2558 | PrimaryExpr Slice | |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 2559 | PrimaryExpr TypeAssertion | |
Robert Griesemer | ccc713c | 2014-10-27 16:31:15 -0700 | [diff] [blame] | 2560 | PrimaryExpr Arguments . |
Robert Griesemer | 57b3461 | 2008-10-10 12:45:44 -0700 | [diff] [blame] | 2561 | |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 2562 | Selector = "." identifier . |
| 2563 | Index = "[" Expression "]" . |
Robert Griesemer | 5583e8a | 2016-02-23 10:42:06 -0800 | [diff] [blame] | 2564 | Slice = "[" [ Expression ] ":" [ Expression ] "]" | |
| 2565 | "[" [ Expression ] ":" Expression ":" Expression "]" . |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 2566 | TypeAssertion = "." "(" Type ")" . |
Robert Griesemer | ccc713c | 2014-10-27 16:31:15 -0700 | [diff] [blame] | 2567 | Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2568 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2569 | |
| 2570 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2571 | <pre> |
| 2572 | x |
| 2573 | 2 |
| 2574 | (s + ".txt") |
| 2575 | f(3.1415, true) |
Rob Pike | 426335f | 2009-03-02 17:52:52 -0800 | [diff] [blame] | 2576 | Point{1, 2} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2577 | m["foo"] |
| 2578 | s[i : j + 1] |
| 2579 | obj.color |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2580 | f.p[i].x() |
| 2581 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2582 | |
| 2583 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2584 | <h3 id="Selectors">Selectors</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2585 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2586 | <p> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2587 | For a <a href="#Primary_expressions">primary expression</a> <code>x</code> |
| 2588 | that is not a <a href="#Package_clause">package name</a>, the |
| 2589 | <i>selector expression</i> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2590 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2591 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2592 | <pre> |
| 2593 | x.f |
| 2594 | </pre> |
Robert Griesemer | bbfe312 | 2008-10-09 17:12:09 -0700 | [diff] [blame] | 2595 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2596 | <p> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2597 | denotes the field or method <code>f</code> of the value <code>x</code> |
| 2598 | (or sometimes <code>*x</code>; see below). |
| 2599 | The identifier <code>f</code> is called the (field or method) <i>selector</i>; |
| 2600 | it must not be the <a href="#Blank_identifier">blank identifier</a>. |
| 2601 | The type of the selector expression is the type of <code>f</code>. |
| 2602 | If <code>x</code> is a package name, see the section on |
| 2603 | <a href="#Qualified_identifiers">qualified identifiers</a>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2604 | </p> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2605 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2606 | <p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2607 | A selector <code>f</code> may denote a field or method <code>f</code> of |
| 2608 | a type <code>T</code>, or it may refer |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2609 | to a field or method <code>f</code> of a nested |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 2610 | <a href="#Struct_types">embedded field</a> of <code>T</code>. |
| 2611 | The number of embedded fields traversed |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2612 | to reach <code>f</code> is called its <i>depth</i> in <code>T</code>. |
| 2613 | The depth of a field or method <code>f</code> |
| 2614 | declared in <code>T</code> is zero. |
| 2615 | The depth of a field or method <code>f</code> declared in |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 2616 | an embedded field <code>A</code> in <code>T</code> is the |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2617 | depth of <code>f</code> in <code>A</code> plus one. |
| 2618 | </p> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2619 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2620 | <p> |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2621 | The following rules apply to selectors: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2622 | </p> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2623 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2624 | <ol> |
| 2625 | <li> |
| 2626 | 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] | 2627 | where <code>T</code> is not a pointer or interface type, |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2628 | <code>x.f</code> denotes the field or method at the shallowest depth |
| 2629 | in <code>T</code> where there |
| 2630 | is such an <code>f</code>. |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 2631 | If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a> |
| 2632 | with shallowest depth, the selector expression is illegal. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2633 | </li> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2634 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2635 | <li> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2636 | 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] | 2637 | 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] | 2638 | <code>f</code> of the dynamic value of <code>x</code>. |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2639 | If there is no method with name <code>f</code> in the |
| 2640 | <a href="#Method_sets">method set</a> of <code>I</code>, the selector |
| 2641 | expression is illegal. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2642 | </li> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2643 | |
| 2644 | <li> |
Robert Griesemer | 9b49ac0 | 2018-01-22 16:20:01 -0800 | [diff] [blame] | 2645 | As an exception, if the type of <code>x</code> is a <a href="#Type_definitions">defined</a> |
| 2646 | 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] | 2647 | (but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>. |
| 2648 | </li> |
| 2649 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2650 | <li> |
| 2651 | In all other cases, <code>x.f</code> is illegal. |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 2652 | </li> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2653 | |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2654 | <li> |
Russ Cox | 6e15683 | 2013-03-20 16:54:07 -0400 | [diff] [blame] | 2655 | If <code>x</code> is of pointer type and has the value |
| 2656 | <code>nil</code> and <code>x.f</code> denotes a struct field, |
| 2657 | assigning to or evaluating <code>x.f</code> |
| 2658 | causes a <a href="#Run_time_panics">run-time panic</a>. |
| 2659 | </li> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2660 | |
Russ Cox | 6e15683 | 2013-03-20 16:54:07 -0400 | [diff] [blame] | 2661 | <li> |
| 2662 | If <code>x</code> is of interface type and has the value |
| 2663 | <code>nil</code>, <a href="#Calls">calling</a> or |
| 2664 | <a href="#Method_values">evaluating</a> the method <code>x.f</code> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2665 | causes a <a href="#Run_time_panics">run-time panic</a>. |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 2666 | </li> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2667 | </ol> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2668 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2669 | <p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2670 | For example, given the declarations: |
| 2671 | </p> |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2672 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2673 | <pre> |
| 2674 | type T0 struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2675 | x int |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2676 | } |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2677 | |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2678 | func (*T0) M0() |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2679 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2680 | type T1 struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2681 | y int |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2682 | } |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2683 | |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2684 | func (T1) M1() |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2685 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2686 | type T2 struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2687 | z int |
| 2688 | T1 |
| 2689 | *T0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2690 | } |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2691 | |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2692 | func (*T2) M2() |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2693 | |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2694 | type Q *T2 |
| 2695 | |
| 2696 | var t T2 // with t.T0 != nil |
| 2697 | var p *T2 // with p != nil and (*p).T0 != nil |
| 2698 | var q Q = p |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2699 | </pre> |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2700 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2701 | <p> |
| 2702 | one may write: |
| 2703 | </p> |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2704 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2705 | <pre> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2706 | t.z // t.z |
| 2707 | t.y // t.T1.y |
Robert Griesemer | f9ec929 | 2015-05-18 11:18:58 -0700 | [diff] [blame] | 2708 | t.x // (*t.T0).x |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2709 | |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2710 | p.z // (*p).z |
| 2711 | p.y // (*p).T1.y |
| 2712 | p.x // (*(*p).T0).x |
| 2713 | |
| 2714 | q.x // (*(*q).T0).x (*q).x is a valid field selector |
| 2715 | |
Robert Griesemer | 02d7448 | 2015-07-31 11:15:11 -0700 | [diff] [blame] | 2716 | p.M0() // ((*p).T0).M0() M0 expects *T0 receiver |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2717 | p.M1() // ((*p).T1).M1() M1 expects T1 receiver |
Robert Griesemer | 02d7448 | 2015-07-31 11:15:11 -0700 | [diff] [blame] | 2718 | p.M2() // p.M2() M2 expects *T2 receiver |
| 2719 | t.M2() // (&t).M2() M2 expects *T2 receiver, see section on Calls |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2720 | </pre> |
| 2721 | |
| 2722 | <p> |
| 2723 | but the following is invalid: |
| 2724 | </p> |
| 2725 | |
| 2726 | <pre> |
| 2727 | q.M0() // (*q).M0 is valid but not a field selector |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2728 | </pre> |
Robert Griesemer | bbfe312 | 2008-10-09 17:12:09 -0700 | [diff] [blame] | 2729 | |
| 2730 | |
Robert Griesemer | f852034 | 2014-08-28 08:53:25 -0700 | [diff] [blame] | 2731 | <h3 id="Method_expressions">Method expressions</h3> |
| 2732 | |
| 2733 | <p> |
| 2734 | If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, |
| 2735 | <code>T.M</code> is a function that is callable as a regular function |
| 2736 | with the same arguments as <code>M</code> prefixed by an additional |
| 2737 | argument that is the receiver of the method. |
| 2738 | </p> |
| 2739 | |
| 2740 | <pre class="ebnf"> |
| 2741 | MethodExpr = ReceiverType "." MethodName . |
griesemer | f2d5251 | 2017-10-25 11:26:02 -0700 | [diff] [blame] | 2742 | ReceiverType = Type . |
Robert Griesemer | f852034 | 2014-08-28 08:53:25 -0700 | [diff] [blame] | 2743 | </pre> |
| 2744 | |
| 2745 | <p> |
| 2746 | Consider a struct type <code>T</code> with two methods, |
| 2747 | <code>Mv</code>, whose receiver is of type <code>T</code>, and |
| 2748 | <code>Mp</code>, whose receiver is of type <code>*T</code>. |
| 2749 | </p> |
| 2750 | |
| 2751 | <pre> |
| 2752 | type T struct { |
| 2753 | a int |
| 2754 | } |
| 2755 | func (tv T) Mv(a int) int { return 0 } // value receiver |
| 2756 | func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver |
| 2757 | |
| 2758 | var t T |
| 2759 | </pre> |
| 2760 | |
| 2761 | <p> |
| 2762 | The expression |
| 2763 | </p> |
| 2764 | |
| 2765 | <pre> |
| 2766 | T.Mv |
| 2767 | </pre> |
| 2768 | |
| 2769 | <p> |
| 2770 | yields a function equivalent to <code>Mv</code> but |
| 2771 | with an explicit receiver as its first argument; it has signature |
| 2772 | </p> |
| 2773 | |
| 2774 | <pre> |
| 2775 | func(tv T, a int) int |
| 2776 | </pre> |
| 2777 | |
| 2778 | <p> |
| 2779 | That function may be called normally with an explicit receiver, so |
| 2780 | these five invocations are equivalent: |
| 2781 | </p> |
| 2782 | |
| 2783 | <pre> |
| 2784 | t.Mv(7) |
| 2785 | T.Mv(t, 7) |
| 2786 | (T).Mv(t, 7) |
| 2787 | f1 := T.Mv; f1(t, 7) |
| 2788 | f2 := (T).Mv; f2(t, 7) |
| 2789 | </pre> |
| 2790 | |
| 2791 | <p> |
| 2792 | Similarly, the expression |
| 2793 | </p> |
| 2794 | |
| 2795 | <pre> |
| 2796 | (*T).Mp |
| 2797 | </pre> |
| 2798 | |
| 2799 | <p> |
| 2800 | yields a function value representing <code>Mp</code> with signature |
| 2801 | </p> |
| 2802 | |
| 2803 | <pre> |
| 2804 | func(tp *T, f float32) float32 |
| 2805 | </pre> |
| 2806 | |
| 2807 | <p> |
| 2808 | For a method with a value receiver, one can derive a function |
| 2809 | with an explicit pointer receiver, so |
| 2810 | </p> |
| 2811 | |
| 2812 | <pre> |
| 2813 | (*T).Mv |
| 2814 | </pre> |
| 2815 | |
| 2816 | <p> |
| 2817 | yields a function value representing <code>Mv</code> with signature |
| 2818 | </p> |
| 2819 | |
| 2820 | <pre> |
| 2821 | func(tv *T, a int) int |
| 2822 | </pre> |
| 2823 | |
| 2824 | <p> |
| 2825 | Such a function indirects through the receiver to create a value |
| 2826 | to pass as the receiver to the underlying method; |
| 2827 | the method does not overwrite the value whose address is passed in |
| 2828 | the function call. |
| 2829 | </p> |
| 2830 | |
| 2831 | <p> |
| 2832 | The final case, a value-receiver function for a pointer-receiver method, |
| 2833 | is illegal because pointer-receiver methods are not in the method set |
| 2834 | of the value type. |
| 2835 | </p> |
| 2836 | |
| 2837 | <p> |
| 2838 | Function values derived from methods are called with function call syntax; |
| 2839 | the receiver is provided as the first argument to the call. |
| 2840 | That is, given <code>f := T.Mv</code>, <code>f</code> is invoked |
| 2841 | as <code>f(t, 7)</code> not <code>t.f(7)</code>. |
| 2842 | To construct a function that binds the receiver, use a |
| 2843 | <a href="#Function_literals">function literal</a> or |
| 2844 | <a href="#Method_values">method value</a>. |
| 2845 | </p> |
| 2846 | |
| 2847 | <p> |
| 2848 | It is legal to derive a function value from a method of an interface type. |
| 2849 | The resulting function takes an explicit receiver of that interface type. |
| 2850 | </p> |
| 2851 | |
| 2852 | <h3 id="Method_values">Method values</h3> |
| 2853 | |
| 2854 | <p> |
| 2855 | If the expression <code>x</code> has static type <code>T</code> and |
| 2856 | <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, |
| 2857 | <code>x.M</code> is called a <i>method value</i>. |
| 2858 | The method value <code>x.M</code> is a function value that is callable |
| 2859 | with the same arguments as a method call of <code>x.M</code>. |
| 2860 | The expression <code>x</code> is evaluated and saved during the evaluation of the |
| 2861 | method value; the saved copy is then used as the receiver in any calls, |
| 2862 | which may be executed later. |
| 2863 | </p> |
| 2864 | |
| 2865 | <p> |
| 2866 | The type <code>T</code> may be an interface or non-interface type. |
| 2867 | </p> |
| 2868 | |
| 2869 | <p> |
| 2870 | As in the discussion of <a href="#Method_expressions">method expressions</a> above, |
| 2871 | consider a struct type <code>T</code> with two methods, |
| 2872 | <code>Mv</code>, whose receiver is of type <code>T</code>, and |
| 2873 | <code>Mp</code>, whose receiver is of type <code>*T</code>. |
| 2874 | </p> |
| 2875 | |
| 2876 | <pre> |
| 2877 | type T struct { |
| 2878 | a int |
| 2879 | } |
| 2880 | func (tv T) Mv(a int) int { return 0 } // value receiver |
| 2881 | func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver |
| 2882 | |
| 2883 | var t T |
| 2884 | var pt *T |
| 2885 | func makeT() T |
| 2886 | </pre> |
| 2887 | |
| 2888 | <p> |
| 2889 | The expression |
| 2890 | </p> |
| 2891 | |
| 2892 | <pre> |
| 2893 | t.Mv |
| 2894 | </pre> |
| 2895 | |
| 2896 | <p> |
| 2897 | yields a function value of type |
| 2898 | </p> |
| 2899 | |
| 2900 | <pre> |
| 2901 | func(int) int |
| 2902 | </pre> |
| 2903 | |
| 2904 | <p> |
| 2905 | These two invocations are equivalent: |
| 2906 | </p> |
| 2907 | |
| 2908 | <pre> |
| 2909 | t.Mv(7) |
| 2910 | f := t.Mv; f(7) |
| 2911 | </pre> |
| 2912 | |
| 2913 | <p> |
| 2914 | Similarly, the expression |
| 2915 | </p> |
| 2916 | |
| 2917 | <pre> |
| 2918 | pt.Mp |
| 2919 | </pre> |
| 2920 | |
| 2921 | <p> |
| 2922 | yields a function value of type |
| 2923 | </p> |
| 2924 | |
| 2925 | <pre> |
| 2926 | func(float32) float32 |
| 2927 | </pre> |
| 2928 | |
| 2929 | <p> |
| 2930 | As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver |
| 2931 | using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>. |
| 2932 | </p> |
| 2933 | |
| 2934 | <p> |
| 2935 | As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver |
| 2936 | using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>. |
| 2937 | </p> |
| 2938 | |
| 2939 | <pre> |
| 2940 | f := t.Mv; f(7) // like t.Mv(7) |
| 2941 | f := pt.Mp; f(7) // like pt.Mp(7) |
| 2942 | f := pt.Mv; f(7) // like (*pt).Mv(7) |
| 2943 | f := t.Mp; f(7) // like (&t).Mp(7) |
| 2944 | f := makeT().Mp // invalid: result of makeT() is not addressable |
| 2945 | </pre> |
| 2946 | |
| 2947 | <p> |
| 2948 | Although the examples above use non-interface types, it is also legal to create a method value |
| 2949 | from a value of interface type. |
| 2950 | </p> |
| 2951 | |
| 2952 | <pre> |
| 2953 | var i interface { M(int) } = myVal |
| 2954 | f := i.M; f(7) // like i.M(7) |
| 2955 | </pre> |
| 2956 | |
| 2957 | |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 2958 | <h3 id="Index_expressions">Index expressions</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2959 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2960 | <p> |
Robert Griesemer | bbfe312 | 2008-10-09 17:12:09 -0700 | [diff] [blame] | 2961 | A primary expression of the form |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2962 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2963 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2964 | <pre> |
| 2965 | a[x] |
| 2966 | </pre> |
Robert Griesemer | bbfe312 | 2008-10-09 17:12:09 -0700 | [diff] [blame] | 2967 | |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 2968 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 2969 | denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>. |
| 2970 | The value <code>x</code> is called the <i>index</i> or <i>map key</i>, respectively. |
| 2971 | The following rules apply: |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 2972 | </p> |
Russ Cox | eaa92e0 | 2009-06-25 14:43:55 -0700 | [diff] [blame] | 2973 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2974 | <p> |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 2975 | If <code>a</code> is not a map: |
| 2976 | </p> |
| 2977 | <ul> |
griesemer | 9690d24 | 2017-08-30 15:10:12 +0200 | [diff] [blame] | 2978 | <li>the index <code>x</code> must be of integer type or an untyped constant</li> |
| 2979 | <li>a constant index must be non-negative and |
| 2980 | <a href="#Representability">representable</a> by a value of type <code>int</code></li> |
| 2981 | <li>a constant index that is untyped is given type <code>int</code></li> |
| 2982 | <li>the index <code>x</code> is <i>in range</i> if <code>0 <= x < len(a)</code>, |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 2983 | otherwise it is <i>out of range</i></li> |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 2984 | </ul> |
| 2985 | |
| 2986 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 2987 | 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] | 2988 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2989 | <ul> |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 2990 | <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] | 2991 | <li>if <code>x</code> is out of range at run time, |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 2992 | a <a href="#Run_time_panics">run-time panic</a> occurs</li> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2993 | <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] | 2994 | <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] | 2995 | </ul> |
| 2996 | |
| 2997 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 2998 | 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] | 2999 | </p> |
| 3000 | <ul> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3001 | <li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li> |
| 3002 | </ul> |
| 3003 | |
| 3004 | <p> |
| 3005 | For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>: |
| 3006 | </p> |
| 3007 | <ul> |
| 3008 | <li>if <code>x</code> is out of range at run time, |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 3009 | a <a href="#Run_time_panics">run-time panic</a> occurs</li> |
| 3010 | <li><code>a[x]</code> is the slice element at index <code>x</code> and the type of |
Oling Cat | 018e89f | 2013-01-24 20:46:33 +1100 | [diff] [blame] | 3011 | <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] | 3012 | </ul> |
Russ Cox | eaa92e0 | 2009-06-25 14:43:55 -0700 | [diff] [blame] | 3013 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3014 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3015 | For <code>a</code> of <a href="#String_types">string type</a>: |
Russ Cox | eaa92e0 | 2009-06-25 14:43:55 -0700 | [diff] [blame] | 3016 | </p> |
| 3017 | <ul> |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 3018 | <li>a <a href="#Constants">constant</a> index must be in range |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 3019 | if the string <code>a</code> is also constant</li> |
| 3020 | <li>if <code>x</code> is out of range at run time, |
| 3021 | a <a href="#Run_time_panics">run-time panic</a> occurs</li> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3022 | <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] | 3023 | <code>a[x]</code> is <code>byte</code></li> |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 3024 | <li><code>a[x]</code> may not be assigned to</li> |
Russ Cox | eaa92e0 | 2009-06-25 14:43:55 -0700 | [diff] [blame] | 3025 | </ul> |
| 3026 | |
| 3027 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3028 | 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] | 3029 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3030 | <ul> |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3031 | <li><code>x</code>'s type must be |
Oling Cat | 018e89f | 2013-01-24 20:46:33 +1100 | [diff] [blame] | 3032 | <a href="#Assignability">assignable</a> |
| 3033 | to the key type of <code>M</code></li> |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3034 | <li>if the map contains an entry with key <code>x</code>, |
Robert Griesemer | 4de1d1d | 2018-01-03 10:33:11 -0800 | [diff] [blame] | 3035 | <code>a[x]</code> is the map element with key <code>x</code> |
| 3036 | and the type of <code>a[x]</code> is the element type of <code>M</code></li> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 3037 | <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] | 3038 | <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] | 3039 | for the element type of <code>M</code></li> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3040 | </ul> |
Robert Griesemer | bbfe312 | 2008-10-09 17:12:09 -0700 | [diff] [blame] | 3041 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3042 | <p> |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3043 | Otherwise <code>a[x]</code> is illegal. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3044 | </p> |
Robert Griesemer | 7abfcd9 | 2008-10-07 17:14:30 -0700 | [diff] [blame] | 3045 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3046 | <p> |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3047 | 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] | 3048 | 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] | 3049 | </p> |
| 3050 | |
| 3051 | <pre> |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3052 | v, ok = a[x] |
| 3053 | v, ok := a[x] |
| 3054 | var v, ok = a[x] |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3055 | </pre> |
| 3056 | |
| 3057 | <p> |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 3058 | 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] | 3059 | <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] | 3060 | <code>false</code> otherwise. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3061 | </p> |
| 3062 | |
| 3063 | <p> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 3064 | Assigning to an element of a <code>nil</code> map causes a |
| 3065 | <a href="#Run_time_panics">run-time panic</a>. |
| 3066 | </p> |
| 3067 | |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3068 | |
Robert Griesemer | e333b96 | 2013-09-11 17:18:52 -0700 | [diff] [blame] | 3069 | <h3 id="Slice_expressions">Slice expressions</h3> |
| 3070 | |
| 3071 | <p> |
| 3072 | Slice expressions construct a substring or slice from a string, array, pointer |
| 3073 | to array, or slice. There are two variants: a simple form that specifies a low |
| 3074 | and high bound, and a full form that also specifies a bound on the capacity. |
| 3075 | </p> |
| 3076 | |
| 3077 | <h4>Simple slice expressions</h4> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3078 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3079 | <p> |
Russ Cox | 8a8445b | 2011-12-02 13:11:30 -0500 | [diff] [blame] | 3080 | 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] | 3081 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3082 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3083 | <pre> |
Robert Griesemer | 9e5bf27 | 2010-09-07 16:32:35 -0700 | [diff] [blame] | 3084 | a[low : high] |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3085 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3086 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3087 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3088 | constructs a substring or slice. The <i>indices</i> <code>low</code> and |
| 3089 | <code>high</code> select which elements of operand <code>a</code> appear |
| 3090 | 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] | 3091 | <code>high</code> - <code>low</code>. |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 3092 | After slicing the array <code>a</code> |
| 3093 | </p> |
| 3094 | |
| 3095 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 3096 | a := [5]int{1, 2, 3, 4, 5} |
| 3097 | s := a[1:4] |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 3098 | </pre> |
| 3099 | |
| 3100 | <p> |
| 3101 | 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] | 3102 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3103 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3104 | <pre> |
| 3105 | s[0] == 2 |
| 3106 | s[1] == 3 |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 3107 | s[2] == 4 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3108 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3109 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3110 | <p> |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 3111 | 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] | 3112 | index defaults to zero; a missing <code>high</code> index defaults to the length of the |
| 3113 | sliced operand: |
Scott Lawrence | 0c1695b | 2010-09-07 14:30:17 -0700 | [diff] [blame] | 3114 | </p> |
| 3115 | |
Robert Griesemer | 9e5bf27 | 2010-09-07 16:32:35 -0700 | [diff] [blame] | 3116 | <pre> |
Robert Hencke | 58d18e2 | 2013-10-03 12:46:02 -0700 | [diff] [blame] | 3117 | a[2:] // same as a[2 : len(a)] |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 3118 | a[:3] // same as a[0 : 3] |
| 3119 | a[:] // same as a[0 : len(a)] |
Robert Griesemer | 9e5bf27 | 2010-09-07 16:32:35 -0700 | [diff] [blame] | 3120 | </pre> |
| 3121 | |
Scott Lawrence | 0c1695b | 2010-09-07 14:30:17 -0700 | [diff] [blame] | 3122 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3123 | If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for |
| 3124 | <code>(*a)[low : high]</code>. |
| 3125 | </p> |
| 3126 | |
| 3127 | <p> |
| 3128 | For arrays or strings, the indices are <i>in range</i> if |
| 3129 | <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] | 3130 | otherwise they are <i>out of range</i>. |
| 3131 | 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] | 3132 | A <a href="#Constants">constant</a> index must be non-negative and |
| 3133 | <a href="#Representability">representable</a> by a value of type |
Robert Griesemer | 6ffd235 | 2014-03-06 17:11:13 -0800 | [diff] [blame] | 3134 | <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] | 3135 | If both indices are constant, they must satisfy <code>low <= high</code>. |
| 3136 | 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] | 3137 | </p> |
| 3138 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3139 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3140 | Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice, |
| 3141 | the result of the slice operation is a non-constant value of the same type as the operand. |
| 3142 | 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] | 3143 | If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a> |
| 3144 | 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] | 3145 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3146 | |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3147 | <p> |
| 3148 | 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] | 3149 | is a <code>nil</code> slice. Otherwise, if the result is a slice, it shares its underlying |
| 3150 | array with the operand. |
Rob Pike | 15e6ce2 | 2013-08-15 13:15:55 +1000 | [diff] [blame] | 3151 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3152 | |
Robert Griesemer | e333b96 | 2013-09-11 17:18:52 -0700 | [diff] [blame] | 3153 | <h4>Full slice expressions</h4> |
| 3154 | |
| 3155 | <p> |
| 3156 | For an array, pointer to array, or slice <code>a</code> (but not a string), the primary expression |
| 3157 | </p> |
| 3158 | |
| 3159 | <pre> |
| 3160 | a[low : high : max] |
| 3161 | </pre> |
| 3162 | |
| 3163 | <p> |
| 3164 | constructs a slice of the same type, and with the same length and elements as the simple slice |
| 3165 | expression <code>a[low : high]</code>. Additionally, it controls the resulting slice's capacity |
| 3166 | by setting it to <code>max - low</code>. Only the first index may be omitted; it defaults to 0. |
| 3167 | After slicing the array <code>a</code> |
| 3168 | </p> |
| 3169 | |
| 3170 | <pre> |
| 3171 | a := [5]int{1, 2, 3, 4, 5} |
| 3172 | t := a[1:3:5] |
| 3173 | </pre> |
| 3174 | |
| 3175 | <p> |
| 3176 | the slice <code>t</code> has type <code>[]int</code>, length 2, capacity 4, and elements |
| 3177 | </p> |
| 3178 | |
| 3179 | <pre> |
| 3180 | t[0] == 2 |
| 3181 | t[1] == 3 |
| 3182 | </pre> |
| 3183 | |
| 3184 | <p> |
| 3185 | As for simple slice expressions, if <code>a</code> is a pointer to an array, |
| 3186 | <code>a[low : high : max]</code> is shorthand for <code>(*a)[low : high : max]</code>. |
| 3187 | If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>. |
| 3188 | </p> |
| 3189 | |
| 3190 | <p> |
| 3191 | The indices are <i>in range</i> if <code>0 <= low <= high <= max <= cap(a)</code>, |
| 3192 | otherwise they are <i>out of range</i>. |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 3193 | A <a href="#Constants">constant</a> index must be non-negative and |
| 3194 | <a href="#Representability">representable</a> by a value of type |
Robert Griesemer | 6ffd235 | 2014-03-06 17:11:13 -0800 | [diff] [blame] | 3195 | <code>int</code>; for arrays, constant indices must also be in range. |
Robert Griesemer | e333b96 | 2013-09-11 17:18:52 -0700 | [diff] [blame] | 3196 | If multiple indices are constant, the constants that are present must be in range relative to each |
| 3197 | other. |
| 3198 | If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. |
| 3199 | </p> |
| 3200 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3201 | <h3 id="Type_assertions">Type assertions</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3202 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3203 | <p> |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 3204 | For an expression <code>x</code> of <a href="#Interface_types">interface type</a> |
| 3205 | and a type <code>T</code>, the primary expression |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3206 | </p> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 3207 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3208 | <pre> |
| 3209 | x.(T) |
| 3210 | </pre> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 3211 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3212 | <p> |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 3213 | asserts that <code>x</code> is not <code>nil</code> |
Russ Cox | b89a54e | 2009-05-20 18:16:04 -0700 | [diff] [blame] | 3214 | 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] | 3215 | 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] | 3216 | </p> |
| 3217 | <p> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 3218 | 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] | 3219 | that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a> |
| 3220 | to the type <code>T</code>. |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 3221 | In this case, <code>T</code> must <a href="#Method_sets">implement</a> the (interface) type of <code>x</code>; |
| 3222 | otherwise the type assertion is invalid since it is not possible for <code>x</code> |
| 3223 | to store a value of type <code>T</code>. |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 3224 | 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] | 3225 | of <code>x</code> implements the interface <code>T</code>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3226 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3227 | <p> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 3228 | 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] | 3229 | stored in <code>x</code> and its type is <code>T</code>. If the type assertion is false, |
| 3230 | a <a href="#Run_time_panics">run-time panic</a> occurs. |
| 3231 | In other words, even though the dynamic type of <code>x</code> |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 3232 | 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] | 3233 | known to be <code>T</code> in a correct program. |
| 3234 | </p> |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 3235 | |
| 3236 | <pre> |
Robert Griesemer | 023bb03 | 2016-10-19 09:56:53 -0700 | [diff] [blame] | 3237 | var x interface{} = 7 // x has dynamic type int and value 7 |
| 3238 | i := x.(int) // i has type int and value 7 |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 3239 | |
| 3240 | type I interface { m() } |
Robert Griesemer | 023bb03 | 2016-10-19 09:56:53 -0700 | [diff] [blame] | 3241 | |
| 3242 | func f(y I) { |
| 3243 | s := y.(string) // illegal: string does not implement I (missing method m) |
| 3244 | r := y.(io.Reader) // r has type io.Reader and the dynamic type of y must implement both I and io.Reader |
| 3245 | … |
| 3246 | } |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 3247 | </pre> |
| 3248 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3249 | <p> |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 3250 | 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] | 3251 | </p> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 3252 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3253 | <pre> |
| 3254 | v, ok = x.(T) |
| 3255 | v, ok := x.(T) |
Rob Pike | d553707 | 2009-08-22 00:04:04 -0700 | [diff] [blame] | 3256 | var v, ok = x.(T) |
Robert Griesemer | 507051d | 2016-08-24 11:33:55 -0700 | [diff] [blame] | 3257 | var v, ok T1 = x.(T) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3258 | </pre> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 3259 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3260 | <p> |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 3261 | yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code> |
| 3262 | if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is |
| 3263 | 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] | 3264 | 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] | 3265 | </p> |
Robert Griesemer | 7a4ed4f | 2008-09-03 15:15:51 -0700 | [diff] [blame] | 3266 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3267 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3268 | <h3 id="Calls">Calls</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3269 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3270 | <p> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 3271 | Given an expression <code>f</code> of function type |
| 3272 | <code>F</code>, |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3273 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3274 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3275 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 3276 | f(a1, a2, … an) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3277 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3278 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3279 | <p> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 3280 | calls <code>f</code> with arguments <code>a1, a2, … an</code>. |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 3281 | Except for one special case, arguments must be single-valued expressions |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 3282 | <a href="#Assignability">assignable</a> to the parameter types of |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3283 | <code>F</code> and are evaluated before the function is called. |
| 3284 | The type of the expression is the result type |
| 3285 | of <code>F</code>. |
| 3286 | A method invocation is similar but the method itself |
| 3287 | is specified as a selector upon a value of the receiver type for |
| 3288 | the method. |
| 3289 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3290 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3291 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 3292 | math.Atan2(x, y) // function call |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 3293 | var pt *Point |
Robert Griesemer | ccc713c | 2014-10-27 16:31:15 -0700 | [diff] [blame] | 3294 | pt.Scale(3.5) // method call with receiver pt |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3295 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3296 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3297 | <p> |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 3298 | In a function call, the function value and arguments are evaluated in |
| 3299 | <a href="#Order_of_evaluation">the usual order</a>. |
| 3300 | After they are evaluated, the parameters of the call are passed by value to the function |
| 3301 | and the called function begins execution. |
| 3302 | The return parameters of the function are passed by value |
| 3303 | back to the calling function when the function returns. |
| 3304 | </p> |
| 3305 | |
| 3306 | <p> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3307 | Calling a <code>nil</code> function value |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 3308 | causes a <a href="#Run_time_panics">run-time panic</a>. |
| 3309 | </p> |
| 3310 | |
| 3311 | <p> |
Russ Cox | 1b3083e | 2013-02-09 14:46:55 -0500 | [diff] [blame] | 3312 | 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] | 3313 | <code>g</code> are equal in number and individually |
| 3314 | assignable to the parameters of another function or method |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 3315 | <code>f</code>, then the call <code>f(g(<i>parameters_of_g</i>))</code> |
| 3316 | will invoke <code>f</code> after binding the return values of |
| 3317 | <code>g</code> to the parameters of <code>f</code> in order. The call |
Russ Cox | 1b3083e | 2013-02-09 14:46:55 -0500 | [diff] [blame] | 3318 | of <code>f</code> must contain no parameters other than the call of <code>g</code>, |
| 3319 | and <code>g</code> must have at least one return value. |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 3320 | If <code>f</code> has a final <code>...</code> parameter, it is |
| 3321 | assigned the return values of <code>g</code> that remain after |
| 3322 | assignment of regular parameters. |
| 3323 | </p> |
| 3324 | |
| 3325 | <pre> |
| 3326 | func Split(s string, pos int) (string, string) { |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 3327 | return s[0:pos], s[pos:] |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 3328 | } |
| 3329 | |
| 3330 | func Join(s, t string) string { |
| 3331 | return s + t |
| 3332 | } |
| 3333 | |
| 3334 | if Join(Split(value, len(value)/2)) != value { |
Robert Griesemer | 7fc4e37 | 2011-02-01 12:51:10 -0800 | [diff] [blame] | 3335 | log.Panic("test fails") |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 3336 | } |
| 3337 | </pre> |
| 3338 | |
| 3339 | <p> |
Robert Griesemer | 2a838d6 | 2011-02-08 13:31:01 -0800 | [diff] [blame] | 3340 | A method call <code>x.m()</code> is valid if the <a href="#Method_sets">method set</a> |
| 3341 | 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] | 3342 | 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] | 3343 | 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] | 3344 | set contains <code>m</code>, <code>x.m()</code> is shorthand |
| 3345 | for <code>(&x).m()</code>: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3346 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3347 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3348 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 3349 | var p Point |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3350 | p.Scale(3.5) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3351 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3352 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3353 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3354 | There is no distinct method type and there are no method literals. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3355 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3356 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3357 | <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] | 3358 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3359 | <p> |
Robert Griesemer | a766277 | 2014-03-06 10:35:05 -0800 | [diff] [blame] | 3360 | If <code>f</code> is <a href="#Function_types">variadic</a> with a final |
| 3361 | parameter <code>p</code> of type <code>...T</code>, then within <code>f</code> |
| 3362 | the type of <code>p</code> is equivalent to type <code>[]T</code>. |
| 3363 | If <code>f</code> is invoked with no actual arguments for <code>p</code>, |
| 3364 | the value passed to <code>p</code> is <code>nil</code>. |
| 3365 | Otherwise, the value passed is a new slice |
| 3366 | of type <code>[]T</code> with a new underlying array whose successive elements |
| 3367 | are the actual arguments, which all must be <a href="#Assignability">assignable</a> |
| 3368 | to <code>T</code>. The length and capacity of the slice is therefore |
| 3369 | the number of arguments bound to <code>p</code> and may differ for each |
| 3370 | call site. |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3371 | </p> |
Robert Griesemer | 69e26bf | 2008-11-04 16:46:45 -0800 | [diff] [blame] | 3372 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3373 | <p> |
Robert Griesemer | a766277 | 2014-03-06 10:35:05 -0800 | [diff] [blame] | 3374 | Given the function and calls |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3375 | </p> |
| 3376 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 3377 | func Greeting(prefix string, who ...string) |
Robert Griesemer | a766277 | 2014-03-06 10:35:05 -0800 | [diff] [blame] | 3378 | Greeting("nobody") |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3379 | Greeting("hello:", "Joe", "Anna", "Eileen") |
| 3380 | </pre> |
| 3381 | |
| 3382 | <p> |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 3383 | within <code>Greeting</code>, <code>who</code> will have the value |
Robert Griesemer | a766277 | 2014-03-06 10:35:05 -0800 | [diff] [blame] | 3384 | <code>nil</code> in the first call, and |
| 3385 | <code>[]string{"Joe", "Anna", "Eileen"}</code> in the second. |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3386 | </p> |
| 3387 | |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 3388 | <p> |
Robert Griesemer | 904adfd | 2010-10-27 10:44:31 -0700 | [diff] [blame] | 3389 | If the final argument is assignable to a slice type <code>[]T</code>, it may be |
| 3390 | passed unchanged as the value for a <code>...T</code> parameter if the argument |
| 3391 | 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] | 3392 | </p> |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3393 | |
| 3394 | <p> |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 3395 | Given the slice <code>s</code> and call |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3396 | </p> |
Robert Griesemer | 69e26bf | 2008-11-04 16:46:45 -0800 | [diff] [blame] | 3397 | |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 3398 | <pre> |
| 3399 | s := []string{"James", "Jasmine"} |
| 3400 | Greeting("goodbye:", s...) |
| 3401 | </pre> |
| 3402 | |
| 3403 | <p> |
| 3404 | within <code>Greeting</code>, <code>who</code> will have the same value as <code>s</code> |
| 3405 | with the same underlying array. |
| 3406 | </p> |
| 3407 | |
| 3408 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3409 | <h3 id="Operators">Operators</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3410 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3411 | <p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3412 | Operators combine operands into expressions. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3413 | </p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3414 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 3415 | <pre class="ebnf"> |
Matthew Dempsky | abb818b | 2015-04-20 17:17:24 -0700 | [diff] [blame] | 3416 | Expression = UnaryExpr | Expression binary_op Expression . |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3417 | UnaryExpr = PrimaryExpr | unary_op UnaryExpr . |
Robert Griesemer | 57b3461 | 2008-10-10 12:45:44 -0700 | [diff] [blame] | 3418 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 3419 | binary_op = "||" | "&&" | rel_op | add_op | mul_op . |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3420 | rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" . |
| 3421 | add_op = "+" | "-" | "|" | "^" . |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 3422 | mul_op = "*" | "/" | "%" | "<<" | ">>" | "&" | "&^" . |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3423 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3424 | unary_op = "+" | "-" | "!" | "^" | "*" | "&" | "<-" . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3425 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3426 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3427 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 3428 | Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 3429 | 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] | 3430 | unless the operation involves shifts or untyped <a href="#Constants">constants</a>. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 3431 | For operations involving constants only, see the section on |
| 3432 | <a href="#Constant_expressions">constant expressions</a>. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 3433 | </p> |
Robert Griesemer | c8e1876 | 2008-09-12 12:26:22 -0700 | [diff] [blame] | 3434 | |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 3435 | <p> |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 3436 | 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] | 3437 | 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] | 3438 | to the type of the other operand. |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 3439 | </p> |
Robert Griesemer | 7539c85 | 2009-07-31 18:05:07 -0700 | [diff] [blame] | 3440 | |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 3441 | <p> |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 3442 | The right operand in a shift expression must have unsigned integer type |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 3443 | or be an untyped constant <a href="#Representability">representable</a> by a |
| 3444 | value of type <code>uint</code>. |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 3445 | 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] | 3446 | 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] | 3447 | replaced by its left operand alone. |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 3448 | </p> |
Robert Griesemer | a6b546f | 2008-10-20 11:46:40 -0700 | [diff] [blame] | 3449 | |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 3450 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 3451 | var s uint = 33 |
griesemer | 9690d24 | 2017-08-30 15:10:12 +0200 | [diff] [blame] | 3452 | var i = 1<<s // 1 has type int |
| 3453 | var j int32 = 1<<s // 1 has type int32; j == 0 |
| 3454 | var k = uint64(1<<s) // 1 has type uint64; k == 1<<33 |
| 3455 | var m int = 1.0<<s // 1.0 has type int; m == 0 if ints are 32bits in size |
| 3456 | var n = 1.0<<s == j // 1.0 has type int32; n == true |
| 3457 | var o = 1<<s == 2<<s // 1 and 2 have type int; o == true if ints are 32bits in size |
| 3458 | var p = 1<<s == 1<<33 // illegal if ints are 32bits in size: 1 has type int, but 1<<33 overflows int |
| 3459 | var u = 1.0<<s // illegal: 1.0 has type float64, cannot shift |
| 3460 | var u1 = 1.0<<s != 0 // illegal: 1.0 has type float64, cannot shift |
| 3461 | var u2 = 1<<s != 1.0 // illegal: 1 has type float64, cannot shift |
| 3462 | var v float32 = 1<<s // illegal: 1 has type float32, cannot shift |
| 3463 | var w int64 = 1.0<<33 // 1.0<<33 is a constant shift expression |
| 3464 | var x = a[1.0<<s] // 1.0 has type int; x == a[0] if ints are 32bits in size |
| 3465 | 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] | 3466 | </pre> |
Robert Griesemer | 18b05c1 | 2009-01-26 09:34:19 -0800 | [diff] [blame] | 3467 | |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3468 | |
| 3469 | <h4 id="Operator_precedence">Operator precedence</h4> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3470 | <p> |
Russ Cox | ec9b042 | 2009-07-09 16:44:13 -0700 | [diff] [blame] | 3471 | Unary operators have the highest precedence. |
| 3472 | As the <code>++</code> and <code>--</code> operators form |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3473 | statements, not expressions, they fall |
Russ Cox | ec9b042 | 2009-07-09 16:44:13 -0700 | [diff] [blame] | 3474 | outside the operator hierarchy. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3475 | As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>. |
| 3476 | <p> |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 3477 | There are five precedence levels for binary operators. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3478 | Multiplication operators bind strongest, followed by addition |
Russ Cox | 1b4e37a | 2012-09-12 12:05:24 -0400 | [diff] [blame] | 3479 | operators, comparison operators, <code>&&</code> (logical AND), |
| 3480 | and finally <code>||</code> (logical OR): |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3481 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3482 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 3483 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3484 | Precedence Operator |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 3485 | 5 * / % << >> & &^ |
| 3486 | 4 + - | ^ |
Robert Griesemer | a1368a6 | 2011-02-22 15:31:57 -0800 | [diff] [blame] | 3487 | 3 == != < <= > >= |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3488 | 2 && |
| 3489 | 1 || |
| 3490 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3491 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3492 | <p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3493 | Binary operators of the same precedence associate from left to right. |
Robert Griesemer | d36d191 | 2009-09-18 11:58:35 -0700 | [diff] [blame] | 3494 | 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] | 3495 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3496 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3497 | <pre> |
| 3498 | +x |
| 3499 | 23 + 3*x[i] |
| 3500 | x <= f() |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 3501 | ^a >> b |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3502 | f() || g() |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 3503 | x == y+1 && <-chanPtr > 0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3504 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3505 | |
| 3506 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3507 | <h3 id="Arithmetic_operators">Arithmetic operators</h3> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3508 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 3509 | 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] | 3510 | type as the first operand. The four standard arithmetic operators (<code>+</code>, |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3511 | <code>-</code>, <code>*</code>, <code>/</code>) apply to integer, |
| 3512 | floating-point, and complex types; <code>+</code> also applies to strings. |
| 3513 | The bitwise logical and shift operators apply to integers only. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3514 | </p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3515 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 3516 | <pre class="grammar"> |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 3517 | + sum integers, floats, complex values, strings |
| 3518 | - difference integers, floats, complex values |
| 3519 | * product integers, floats, complex values |
| 3520 | / quotient integers, floats, complex values |
Rob Pike | 307ec21 | 2009-03-12 15:53:56 -0700 | [diff] [blame] | 3521 | % remainder integers |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3522 | |
Russ Cox | 1b4e37a | 2012-09-12 12:05:24 -0400 | [diff] [blame] | 3523 | & bitwise AND integers |
| 3524 | | bitwise OR integers |
| 3525 | ^ bitwise XOR integers |
| 3526 | &^ bit clear (AND NOT) integers |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3527 | |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 3528 | << left shift integer << unsigned integer |
| 3529 | >> right shift integer >> unsigned integer |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3530 | </pre> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3531 | |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3532 | |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3533 | <h4 id="Integer_operators">Integer operators</h4> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3534 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3535 | <p> |
Robert Griesemer | bb7eb40 | 2011-05-02 17:23:18 -0700 | [diff] [blame] | 3536 | For two integer values <code>x</code> and <code>y</code>, the integer quotient |
| 3537 | <code>q = x / y</code> and remainder <code>r = x % y</code> satisfy the following |
| 3538 | relationships: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3539 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3540 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3541 | <pre> |
Robert Griesemer | bb7eb40 | 2011-05-02 17:23:18 -0700 | [diff] [blame] | 3542 | x = q*y + r and |r| < |y| |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3543 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3544 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3545 | <p> |
Robert Griesemer | bb7eb40 | 2011-05-02 17:23:18 -0700 | [diff] [blame] | 3546 | with <code>x / y</code> truncated towards zero |
Suriyaa Sundararuban | 1041ac8 | 2018-06-13 07:06:04 +0000 | [diff] [blame] | 3547 | (<a href="https://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>). |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3548 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3549 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3550 | <pre> |
| 3551 | x y x / y x % y |
| 3552 | 5 3 1 2 |
| 3553 | -5 3 -1 -2 |
| 3554 | 5 -3 -1 2 |
| 3555 | -5 -3 1 -2 |
| 3556 | </pre> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3557 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3558 | <p> |
Robert Griesemer | 18d527b | 2018-01-16 21:30:46 -0800 | [diff] [blame] | 3559 | The one exception to this rule is that if the dividend <code>x</code> is |
| 3560 | the most negative value for the int type of <code>x</code>, the quotient |
| 3561 | <code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>) |
| 3562 | due to two's-complement <a href="#Integer_overflow">integer overflow</a>: |
Robert Griesemer | bb7eb40 | 2011-05-02 17:23:18 -0700 | [diff] [blame] | 3563 | </p> |
| 3564 | |
| 3565 | <pre> |
| 3566 | x, q |
| 3567 | int8 -128 |
| 3568 | int16 -32768 |
| 3569 | int32 -2147483648 |
| 3570 | int64 -9223372036854775808 |
| 3571 | </pre> |
| 3572 | |
| 3573 | <p> |
Robert Griesemer | ddddd39 | 2012-10-19 10:12:09 -0700 | [diff] [blame] | 3574 | If the divisor is a <a href="#Constants">constant</a>, it must not be zero. |
| 3575 | 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] | 3576 | 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] | 3577 | 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] | 3578 | be replaced by a bitwise AND operation: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3579 | </p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3580 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3581 | <pre> |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 3582 | x x / 4 x % 4 x >> 2 x & 3 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3583 | 11 2 3 2 3 |
| 3584 | -11 -2 -3 -3 1 |
| 3585 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3586 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3587 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3588 | The shift operators shift the left operand by the shift count specified by the |
| 3589 | right operand. They implement arithmetic shifts if the left operand is a signed |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 3590 | integer and logical shifts if it is an unsigned integer. |
| 3591 | There is no upper limit on the shift count. Shifts behave |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3592 | as if the left operand is shifted <code>n</code> times by 1 for a shift |
| 3593 | count of <code>n</code>. |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 3594 | As a result, <code>x << 1</code> is the same as <code>x*2</code> |
| 3595 | and <code>x >> 1</code> is the same as |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 3596 | <code>x/2</code> but truncated towards negative infinity. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3597 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3598 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3599 | <p> |
| 3600 | For integer operands, the unary operators |
| 3601 | <code>+</code>, <code>-</code>, and <code>^</code> are defined as |
Robert Griesemer | 9dfb2ea | 2008-12-12 10:30:10 -0800 | [diff] [blame] | 3602 | follows: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3603 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3604 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 3605 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3606 | +x is 0 + x |
| 3607 | -x negation is 0 - x |
Russ Cox | d83dc4f | 2009-05-29 16:04:16 -0700 | [diff] [blame] | 3608 | ^x bitwise complement is m ^ x with m = "all bits set to 1" for unsigned x |
| 3609 | and m = -1 for signed x |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3610 | </pre> |
Robert Griesemer | 9dfb2ea | 2008-12-12 10:30:10 -0800 | [diff] [blame] | 3611 | |
| 3612 | |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3613 | <h4 id="Integer_overflow">Integer overflow</h4> |
Robert Griesemer | 9dfb2ea | 2008-12-12 10:30:10 -0800 | [diff] [blame] | 3614 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3615 | <p> |
| 3616 | For unsigned integer values, the operations <code>+</code>, |
| 3617 | <code>-</code>, <code>*</code>, and <code><<</code> are |
| 3618 | 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] | 3619 | the <a href="#Numeric_types">unsigned integer</a>'s type. |
| 3620 | Loosely speaking, these unsigned integer operations |
Robert Griesemer | 8c916a2 | 2018-01-09 12:42:28 -0800 | [diff] [blame] | 3621 | discard high bits upon overflow, and programs may rely on "wrap around". |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3622 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3623 | <p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3624 | For signed integers, the operations <code>+</code>, |
Robert Griesemer | 18d527b | 2018-01-16 21:30:46 -0800 | [diff] [blame] | 3625 | <code>-</code>, <code>*</code>, <code>/</code>, and <code><<</code> may legally |
Robert Griesemer | 9dfb2ea | 2008-12-12 10:30:10 -0800 | [diff] [blame] | 3626 | overflow and the resulting value exists and is deterministically defined |
| 3627 | by the signed integer representation, the operation, and its operands. |
Russ Cox | b7ba523 | 2018-11-13 10:23:01 -0500 | [diff] [blame] | 3628 | 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] | 3629 | A compiler may not optimize code under the assumption that overflow does |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3630 | not occur. For instance, it may not assume that <code>x < x + 1</code> is always true. |
| 3631 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3632 | |
| 3633 | |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3634 | <h4 id="Floating_point_operators">Floating-point operators</h4> |
| 3635 | |
| 3636 | <p> |
| 3637 | For floating-point and complex numbers, |
| 3638 | <code>+x</code> is the same as <code>x</code>, |
| 3639 | while <code>-x</code> is the negation of <code>x</code>. |
| 3640 | The result of a floating-point or complex division by zero is not specified beyond the |
| 3641 | IEEE-754 standard; whether a <a href="#Run_time_panics">run-time panic</a> |
| 3642 | occurs is implementation-specific. |
| 3643 | </p> |
| 3644 | |
Robert Griesemer | 94b6011 | 2017-04-11 13:39:24 -0700 | [diff] [blame] | 3645 | <p> |
| 3646 | An implementation may combine multiple floating-point operations into a single |
| 3647 | fused operation, possibly across statements, and produce a result that differs |
| 3648 | from the value obtained by executing and rounding the instructions individually. |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 3649 | An explicit floating-point type <a href="#Conversions">conversion</a> rounds to |
Robert Griesemer | 94b6011 | 2017-04-11 13:39:24 -0700 | [diff] [blame] | 3650 | the precision of the target type, preventing fusion that would discard that rounding. |
| 3651 | </p> |
| 3652 | |
| 3653 | <p> |
| 3654 | For instance, some architectures provide a "fused multiply and add" (FMA) instruction |
| 3655 | that computes <code>x*y + z</code> without rounding the intermediate result <code>x*y</code>. |
| 3656 | These examples show when a Go implementation can use that instruction: |
| 3657 | </p> |
| 3658 | |
| 3659 | <pre> |
| 3660 | // FMA allowed for computing r, because x*y is not explicitly rounded: |
| 3661 | r = x*y + z |
| 3662 | r = z; r += x*y |
| 3663 | t = x*y; r = t + z |
| 3664 | *p = x*y; r = *p + z |
| 3665 | r = x*y + float64(z) |
| 3666 | |
| 3667 | // FMA disallowed for computing r, because it would omit rounding of x*y: |
| 3668 | r = float64(x*y) + z |
| 3669 | r = z; r += float64(x*y) |
| 3670 | t = float64(x*y); r = t + z |
| 3671 | </pre> |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3672 | |
| 3673 | <h4 id="String_concatenation">String concatenation</h4> |
| 3674 | |
| 3675 | <p> |
| 3676 | Strings can be concatenated using the <code>+</code> operator |
| 3677 | or the <code>+=</code> assignment operator: |
| 3678 | </p> |
| 3679 | |
| 3680 | <pre> |
| 3681 | s := "hi" + string(c) |
| 3682 | s += " and good bye" |
| 3683 | </pre> |
| 3684 | |
| 3685 | <p> |
| 3686 | String addition creates a new string by concatenating the operands. |
| 3687 | </p> |
| 3688 | |
| 3689 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3690 | <h3 id="Comparison_operators">Comparison operators</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3691 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 3692 | <p> |
Robert Griesemer | c729ed6 | 2013-03-11 09:16:29 -0700 | [diff] [blame] | 3693 | Comparison operators compare two operands and yield an untyped boolean value. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 3694 | </p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3695 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 3696 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3697 | == equal |
| 3698 | != not equal |
Anthony Martin | 0122a66 | 2011-02-08 14:51:15 -0800 | [diff] [blame] | 3699 | < less |
| 3700 | <= less or equal |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3701 | > greater |
| 3702 | >= greater or equal |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3703 | </pre> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3704 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 3705 | <p> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3706 | In any comparison, the first operand |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 3707 | must be <a href="#Assignability">assignable</a> |
| 3708 | to the type of the second operand, or vice versa. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 3709 | </p> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 3710 | <p> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3711 | The equality operators <code>==</code> and <code>!=</code> apply |
| 3712 | to operands that are <i>comparable</i>. |
| 3713 | The ordering operators <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code> |
| 3714 | apply to operands that are <i>ordered</i>. |
| 3715 | These terms and the result of the comparisons are defined as follows: |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 3716 | </p> |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3717 | |
| 3718 | <ul> |
| 3719 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3720 | Boolean values are comparable. |
| 3721 | Two boolean values are equal if they are either both |
| 3722 | <code>true</code> or both <code>false</code>. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3723 | </li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3724 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3725 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3726 | Integer values are comparable and ordered, in the usual way. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3727 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3728 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3729 | <li> |
Robert Griesemer | 94b6011 | 2017-04-11 13:39:24 -0700 | [diff] [blame] | 3730 | Floating-point values are comparable and ordered, |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3731 | as defined by the IEEE-754 standard. |
| 3732 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3733 | |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3734 | <li> |
| 3735 | Complex values are comparable. |
| 3736 | Two complex values <code>u</code> and <code>v</code> are |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3737 | equal if both <code>real(u) == real(v)</code> and |
| 3738 | <code>imag(u) == imag(v)</code>. |
| 3739 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3740 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3741 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3742 | String values are comparable and ordered, lexically byte-wise. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3743 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3744 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3745 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3746 | Pointer values are comparable. |
Robert Griesemer | 1320ce0 | 2012-01-09 16:54:24 -0800 | [diff] [blame] | 3747 | Two pointer values are equal if they point to the same variable or if both have value <code>nil</code>. |
| 3748 | Pointers to distinct <a href="#Size_and_alignment_guarantees">zero-size</a> variables may or may not be equal. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3749 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3750 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3751 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3752 | Channel values are comparable. |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 3753 | Two channel values are equal if they were created by the same call to |
| 3754 | <a href="#Making_slices_maps_and_channels"><code>make</code></a> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3755 | or if both have value <code>nil</code>. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3756 | </li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3757 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3758 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3759 | Interface values are comparable. |
| 3760 | Two interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types |
| 3761 | and equal dynamic values or if both have value <code>nil</code>. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3762 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3763 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3764 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3765 | A value <code>x</code> of non-interface type <code>X</code> and |
| 3766 | a value <code>t</code> of interface type <code>T</code> are comparable when values |
| 3767 | of type <code>X</code> are comparable and |
| 3768 | <code>X</code> implements <code>T</code>. |
| 3769 | They are equal if <code>t</code>'s dynamic type is identical to <code>X</code> |
| 3770 | and <code>t</code>'s dynamic value is equal to <code>x</code>. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3771 | </li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3772 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3773 | <li> |
Robert Griesemer | 3908467 | 2012-02-16 14:13:17 -0800 | [diff] [blame] | 3774 | Struct values are comparable if all their fields are comparable. |
| 3775 | Two struct values are equal if their corresponding |
| 3776 | non-<a href="#Blank_identifier">blank</a> fields are equal. |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3777 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3778 | |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3779 | <li> |
| 3780 | Array values are comparable if values of the array element type are comparable. |
| 3781 | Two array values are equal if their corresponding elements are equal. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3782 | </li> |
| 3783 | </ul> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 3784 | |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3785 | <p> |
| 3786 | A comparison of two interface values with identical dynamic types |
| 3787 | causes a <a href="#Run_time_panics">run-time panic</a> if values |
| 3788 | of that type are not comparable. This behavior applies not only to direct interface |
| 3789 | value comparisons but also when comparing arrays of interface values |
| 3790 | or structs with interface-valued fields. |
| 3791 | </p> |
| 3792 | |
| 3793 | <p> |
| 3794 | Slice, map, and function values are not comparable. |
| 3795 | However, as a special case, a slice, map, or function value may |
| 3796 | be compared to the predeclared identifier <code>nil</code>. |
| 3797 | Comparison of pointer, channel, and interface values to <code>nil</code> |
| 3798 | is also allowed and follows from the general rules above. |
| 3799 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3800 | |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 3801 | <pre> |
Matthew Dempsky | ff85f86 | 2015-10-20 15:05:22 -0700 | [diff] [blame] | 3802 | const c = 3 < 4 // c is the untyped boolean constant true |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 3803 | |
Robert Griesemer | c729ed6 | 2013-03-11 09:16:29 -0700 | [diff] [blame] | 3804 | type MyBool bool |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 3805 | var x, y int |
| 3806 | var ( |
Matthew Dempsky | ff85f86 | 2015-10-20 15:05:22 -0700 | [diff] [blame] | 3807 | // The result of a comparison is an untyped boolean. |
Robert Griesemer | c729ed6 | 2013-03-11 09:16:29 -0700 | [diff] [blame] | 3808 | // The usual assignment rules apply. |
| 3809 | b3 = x == y // b3 has type bool |
| 3810 | b4 bool = x == y // b4 has type bool |
| 3811 | b5 MyBool = x == y // b5 has type MyBool |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 3812 | ) |
| 3813 | </pre> |
| 3814 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3815 | <h3 id="Logical_operators">Logical operators</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3816 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3817 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 3818 | Logical operators apply to <a href="#Boolean_types">boolean</a> values |
| 3819 | and yield a result of the same type as the operands. |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3820 | The right operand is evaluated conditionally. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3821 | </p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3822 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 3823 | <pre class="grammar"> |
Russ Cox | 1b4e37a | 2012-09-12 12:05:24 -0400 | [diff] [blame] | 3824 | && conditional AND p && q is "if p then q else false" |
| 3825 | || conditional OR p || q is "if p then true else q" |
| 3826 | ! NOT !p is "not p" |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3827 | </pre> |
Robert Griesemer | 7a4ed4f | 2008-09-03 15:15:51 -0700 | [diff] [blame] | 3828 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3829 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3830 | <h3 id="Address_operators">Address operators</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3831 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3832 | <p> |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3833 | For an operand <code>x</code> of type <code>T</code>, the address operation |
| 3834 | <code>&x</code> generates a pointer of type <code>*T</code> to <code>x</code>. |
| 3835 | The operand must be <i>addressable</i>, |
Russ Cox | e7561de | 2010-05-24 14:31:43 -0700 | [diff] [blame] | 3836 | that is, either a variable, pointer indirection, or slice indexing |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3837 | operation; or a field selector of an addressable struct operand; |
Russ Cox | e7561de | 2010-05-24 14:31:43 -0700 | [diff] [blame] | 3838 | or an array indexing operation of an addressable array. |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3839 | 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] | 3840 | (possibly parenthesized) |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3841 | <a href="#Composite_literals">composite literal</a>. |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 3842 | 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] | 3843 | then the evaluation of <code>&x</code> does too. |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3844 | </p> |
Russ Cox | 5ce78b7 | 2013-08-15 14:33:26 -0400 | [diff] [blame] | 3845 | |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3846 | <p> |
| 3847 | 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] | 3848 | 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] | 3849 | to by <code>x</code>. |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 3850 | If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code> |
| 3851 | will cause a <a href="#Run_time_panics">run-time panic</a>. |
Rob Pike | afee1c5 | 2009-03-20 17:41:25 -0700 | [diff] [blame] | 3852 | </p> |
| 3853 | |
| 3854 | <pre> |
| 3855 | &x |
| 3856 | &a[f(2)] |
Robert Griesemer | 614b02d | 2013-01-02 18:11:49 -0800 | [diff] [blame] | 3857 | &Point{2, 3} |
Rob Pike | afee1c5 | 2009-03-20 17:41:25 -0700 | [diff] [blame] | 3858 | *p |
| 3859 | *pf(x) |
Russ Cox | 5ce78b7 | 2013-08-15 14:33:26 -0400 | [diff] [blame] | 3860 | |
| 3861 | var x *int = nil |
| 3862 | *x // causes a run-time panic |
Rob Pike | cec0954 | 2013-09-17 07:41:11 +1000 | [diff] [blame] | 3863 | &*x // causes a run-time panic |
Rob Pike | afee1c5 | 2009-03-20 17:41:25 -0700 | [diff] [blame] | 3864 | </pre> |
| 3865 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 3866 | |
| 3867 | <h3 id="Receive_operator">Receive operator</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3868 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3869 | <p> |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 3870 | For an operand <code>ch</code> of <a href="#Channel_types">channel type</a>, |
| 3871 | 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] | 3872 | from the channel <code>ch</code>. The channel direction must permit receive operations, |
| 3873 | and the type of the receive operation is the element type of the channel. |
| 3874 | The expression blocks until a value is available. |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 3875 | Receiving from a <code>nil</code> channel blocks forever. |
Robert Griesemer | ab5c762 | 2013-05-31 11:21:37 -0700 | [diff] [blame] | 3876 | 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] | 3877 | immediately, yielding the element type's <a href="#The_zero_value">zero value</a> |
| 3878 | after any previously sent values have been received. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3879 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3880 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3881 | <pre> |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 3882 | v1 := <-ch |
| 3883 | v2 = <-ch |
| 3884 | f(<-ch) |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 3885 | <-strobe // wait until clock pulse and discard received value |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3886 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3887 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3888 | <p> |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 3889 | 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] | 3890 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3891 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3892 | <pre> |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 3893 | x, ok = <-ch |
| 3894 | x, ok := <-ch |
| 3895 | var x, ok = <-ch |
Robert Griesemer | 507051d | 2016-08-24 11:33:55 -0700 | [diff] [blame] | 3896 | var x, ok T = <-ch |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3897 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3898 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3899 | <p> |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 3900 | yields an additional untyped boolean result reporting whether the |
Robert Griesemer | 689931c | 2012-06-25 11:28:24 -0700 | [diff] [blame] | 3901 | communication succeeded. The value of <code>ok</code> is <code>true</code> |
| 3902 | if the value received was delivered by a successful send operation to the |
| 3903 | channel, or <code>false</code> if it is a zero value generated because the |
| 3904 | channel is closed and empty. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3905 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3906 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 3907 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 3908 | <h3 id="Conversions">Conversions</h3> |
| 3909 | |
| 3910 | <p> |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 3911 | A conversion changes the <a href="#Types">type</a> of an expression |
| 3912 | to the type specified by the conversion. |
| 3913 | A conversion may appear literally in the source, or it may be <i>implied</i> |
| 3914 | by the context in which an expression appears. |
| 3915 | </p> |
| 3916 | |
| 3917 | <p> |
| 3918 | 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] | 3919 | where <code>T</code> is a type and <code>x</code> is an expression |
| 3920 | that can be converted to type <code>T</code>. |
| 3921 | </p> |
| 3922 | |
| 3923 | <pre class="ebnf"> |
Robert Griesemer | 60a6ae8 | 2012-09-26 10:31:57 -0700 | [diff] [blame] | 3924 | Conversion = Type "(" Expression [ "," ] ")" . |
Robert Griesemer | 934a520 | 2010-05-24 14:58:26 -0700 | [diff] [blame] | 3925 | </pre> |
| 3926 | |
| 3927 | <p> |
Robert Griesemer | 3188ffc | 2012-10-03 13:46:37 -0700 | [diff] [blame] | 3928 | If the type starts with the operator <code>*</code> or <code><-</code>, |
Russ Cox | 71c941b | 2013-02-11 07:48:14 -0500 | [diff] [blame] | 3929 | or if the type starts with the keyword <code>func</code> |
| 3930 | and has no result list, it must be parenthesized when |
| 3931 | necessary to avoid ambiguity: |
Robert Griesemer | 934a520 | 2010-05-24 14:58:26 -0700 | [diff] [blame] | 3932 | </p> |
| 3933 | |
| 3934 | <pre> |
| 3935 | *Point(p) // same as *(Point(p)) |
Russ Cox | 71c941b | 2013-02-11 07:48:14 -0500 | [diff] [blame] | 3936 | (*Point)(p) // p is converted to *Point |
Robert Griesemer | 934a520 | 2010-05-24 14:58:26 -0700 | [diff] [blame] | 3937 | <-chan int(c) // same as <-(chan int(c)) |
Russ Cox | 71c941b | 2013-02-11 07:48:14 -0500 | [diff] [blame] | 3938 | (<-chan int)(c) // c is converted to <-chan int |
Robert Griesemer | 3188ffc | 2012-10-03 13:46:37 -0700 | [diff] [blame] | 3939 | func()(x) // function signature func() x |
Russ Cox | 71c941b | 2013-02-11 07:48:14 -0500 | [diff] [blame] | 3940 | (func())(x) // x is converted to func() |
| 3941 | (func() int)(x) // x is converted to func() int |
| 3942 | func() int(x) // x is converted to func() int (unambiguous) |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 3943 | </pre> |
| 3944 | |
| 3945 | <p> |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 3946 | 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] | 3947 | type <code>T</code> if <code>x</code> is <a href="#Representability">representable</a> |
| 3948 | by a value of <code>T</code>. |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 3949 | 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] | 3950 | <a href="#String_types">string type</a> using the |
| 3951 | <a href="#Conversions_to_and_from_a_string_type">same rule</a> |
| 3952 | as for non-constant <code>x</code>. |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 3953 | </p> |
| 3954 | |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 3955 | <p> |
| 3956 | Converting a constant yields a typed constant as result. |
| 3957 | </p> |
| 3958 | |
| 3959 | <pre> |
| 3960 | uint(iota) // iota value of type uint |
| 3961 | float32(2.718281828) // 2.718281828 of type float32 |
| 3962 | complex128(1) // 1.0 + 0.0i of type complex128 |
Russ Cox | 7576179 | 2013-02-11 07:47:41 -0500 | [diff] [blame] | 3963 | float32(0.49999999) // 0.5 of type float32 |
Robert Griesemer | 55ecda4 | 2015-09-17 18:10:20 -0700 | [diff] [blame] | 3964 | float64(-1e-1000) // 0.0 of type float64 |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 3965 | string('x') // "x" of type string |
| 3966 | string(0x266c) // "♬" of type string |
| 3967 | MyString("foo" + "bar") // "foobar" of type MyString |
| 3968 | string([]byte{'a'}) // not a constant: []byte{'a'} is not a constant |
| 3969 | (*int)(nil) // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type |
| 3970 | int(1.2) // illegal: 1.2 cannot be represented as an int |
| 3971 | string(65.0) // illegal: 65.0 is not an integer constant |
| 3972 | </pre> |
| 3973 | |
| 3974 | <p> |
| 3975 | A non-constant value <code>x</code> can be converted to type <code>T</code> |
| 3976 | in any of these cases: |
Robert Griesemer | 63f0149 | 2010-05-28 14:17:30 -0700 | [diff] [blame] | 3977 | </p> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 3978 | |
| 3979 | <ul> |
| 3980 | <li> |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 3981 | <code>x</code> is <a href="#Assignability">assignable</a> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 3982 | to <code>T</code>. |
| 3983 | </li> |
| 3984 | <li> |
Robert Griesemer | 5c7a005 | 2016-06-03 13:21:55 -0700 | [diff] [blame] | 3985 | ignoring struct tags (see below), |
| 3986 | <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] | 3987 | <a href="#Types">underlying types</a>. |
| 3988 | </li> |
| 3989 | <li> |
Robert Griesemer | 5c7a005 | 2016-06-03 13:21:55 -0700 | [diff] [blame] | 3990 | ignoring struct tags (see below), |
Robert Griesemer | 866f63e | 2017-02-09 13:22:37 -0800 | [diff] [blame] | 3991 | <code>x</code>'s type and <code>T</code> are pointer types |
| 3992 | that are not <a href="#Type_definitions">defined types</a>, |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 3993 | and their pointer base types have identical underlying types. |
| 3994 | </li> |
| 3995 | <li> |
| 3996 | <code>x</code>'s type and <code>T</code> are both integer or floating |
| 3997 | point types. |
| 3998 | </li> |
| 3999 | <li> |
| 4000 | <code>x</code>'s type and <code>T</code> are both complex types. |
| 4001 | </li> |
| 4002 | <li> |
Robert Griesemer | 60a6ae8 | 2012-09-26 10:31:57 -0700 | [diff] [blame] | 4003 | <code>x</code> is an integer or a slice of bytes or runes |
| 4004 | and <code>T</code> is a string type. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4005 | </li> |
| 4006 | <li> |
Robert Griesemer | 60a6ae8 | 2012-09-26 10:31:57 -0700 | [diff] [blame] | 4007 | <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] | 4008 | </li> |
| 4009 | </ul> |
| 4010 | |
| 4011 | <p> |
Robert Griesemer | 5c7a005 | 2016-06-03 13:21:55 -0700 | [diff] [blame] | 4012 | <a href="#Struct_types">Struct tags</a> are ignored when comparing struct types |
| 4013 | for identity for the purpose of conversion: |
| 4014 | </p> |
| 4015 | |
| 4016 | <pre> |
| 4017 | type Person struct { |
| 4018 | Name string |
| 4019 | Address *struct { |
| 4020 | Street string |
| 4021 | City string |
| 4022 | } |
| 4023 | } |
| 4024 | |
| 4025 | var data *struct { |
| 4026 | Name string `json:"name"` |
| 4027 | Address *struct { |
| 4028 | Street string `json:"street"` |
| 4029 | City string `json:"city"` |
| 4030 | } `json:"address"` |
| 4031 | } |
| 4032 | |
| 4033 | var person = (*Person)(data) // ignoring tags, the underlying types are identical |
| 4034 | </pre> |
| 4035 | |
| 4036 | <p> |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4037 | Specific rules apply to (non-constant) conversions between numeric types or |
| 4038 | to and from a string type. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4039 | These conversions may change the representation of <code>x</code> |
| 4040 | and incur a run-time cost. |
| 4041 | All other conversions only change the type but not the representation |
| 4042 | of <code>x</code>. |
| 4043 | </p> |
| 4044 | |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4045 | <p> |
| 4046 | There is no linguistic mechanism to convert between pointers and integers. |
| 4047 | The package <a href="#Package_unsafe"><code>unsafe</code></a> |
| 4048 | implements this functionality under |
| 4049 | restricted circumstances. |
| 4050 | </p> |
| 4051 | |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4052 | <h4>Conversions between numeric types</h4> |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4053 | |
| 4054 | <p> |
| 4055 | For the conversion of non-constant numeric values, the following rules apply: |
| 4056 | </p> |
| 4057 | |
Robert Griesemer | 63f0149 | 2010-05-28 14:17:30 -0700 | [diff] [blame] | 4058 | <ol> |
| 4059 | <li> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4060 | When converting between integer types, if the value is a signed integer, it is |
| 4061 | sign extended to implicit infinite precision; otherwise it is zero extended. |
| 4062 | It is then truncated to fit in the result type's size. |
| 4063 | 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] | 4064 | 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] | 4065 | </li> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4066 | <li> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4067 | When converting a floating-point number to an integer, the fraction is discarded |
| 4068 | (truncation towards zero). |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4069 | </li> |
| 4070 | <li> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4071 | When converting an integer or floating-point number to a floating-point type, |
| 4072 | 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] | 4073 | to the precision specified by the destination type. |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4074 | For instance, the value of a variable <code>x</code> of type <code>float32</code> |
| 4075 | may be stored using additional precision beyond that of an IEEE-754 32-bit number, |
| 4076 | but float32(x) represents the result of rounding <code>x</code>'s value to |
| 4077 | 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] | 4078 | of precision, but <code>float32(x + 0.1)</code> does not. |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4079 | </li> |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4080 | </ol> |
| 4081 | |
| 4082 | <p> |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4083 | In all non-constant conversions involving floating-point or complex values, |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 4084 | if the result type cannot represent the value the conversion |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4085 | succeeds but the result value is implementation-dependent. |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4086 | </p> |
| 4087 | |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4088 | <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] | 4089 | |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4090 | <ol> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4091 | <li> |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4092 | 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] | 4093 | string containing the UTF-8 representation of the integer. Values outside |
| 4094 | 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] | 4095 | |
| 4096 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4097 | string('a') // "a" |
Rémy Oudompheng | 2b4cc6c | 2012-07-11 20:26:51 +0200 | [diff] [blame] | 4098 | string(-1) // "\ufffd" == "\xef\xbf\xbd" |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4099 | string(0xf8) // "\u00f8" == "ø" == "\xc3\xb8" |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4100 | type MyString string |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4101 | MyString(0x65e5) // "\u65e5" == "日" == "\xe6\x97\xa5" |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4102 | </pre> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4103 | </li> |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4104 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4105 | <li> |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4106 | Converting a slice of bytes to a string type yields |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4107 | a string whose successive bytes are the elements of the slice. |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4108 | |
| 4109 | <pre> |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4110 | string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø" |
| 4111 | string([]byte{}) // "" |
| 4112 | string([]byte(nil)) // "" |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4113 | |
| 4114 | type MyBytes []byte |
| 4115 | string(MyBytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø" |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4116 | </pre> |
| 4117 | </li> |
| 4118 | |
| 4119 | <li> |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4120 | Converting a slice of runes to a string type yields |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 4121 | a string that is the concatenation of the individual rune values |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4122 | converted to strings. |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 4123 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4124 | <pre> |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4125 | string([]rune{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔" |
| 4126 | string([]rune{}) // "" |
| 4127 | string([]rune(nil)) // "" |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4128 | |
| 4129 | type MyRunes []rune |
| 4130 | string(MyRunes{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔" |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4131 | </pre> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4132 | </li> |
| 4133 | |
| 4134 | <li> |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4135 | 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] | 4136 | yields a slice whose successive elements are the bytes of the string. |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4137 | |
| 4138 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4139 | []byte("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4140 | []byte("") // []byte{} |
| 4141 | |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4142 | MyBytes("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4143 | </pre> |
| 4144 | </li> |
| 4145 | |
| 4146 | <li> |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4147 | Converting a value of a string type to a slice of runes type |
| 4148 | yields a slice containing the individual Unicode code points of the string. |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4149 | |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4150 | <pre> |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 4151 | []rune(MyString("白鵬翔")) // []rune{0x767d, 0x9d6c, 0x7fd4} |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4152 | []rune("") // []rune{} |
| 4153 | |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4154 | MyRunes("白鵬翔") // []rune{0x767d, 0x9d6c, 0x7fd4} |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4155 | </pre> |
| 4156 | </li> |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4157 | </ol> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4158 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4159 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4160 | <h3 id="Constant_expressions">Constant expressions</h3> |
Robert Griesemer | b90b213 | 2008-09-19 15:49:55 -0700 | [diff] [blame] | 4161 | |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 4162 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4163 | Constant expressions may contain only <a href="#Constants">constant</a> |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 4164 | operands and are evaluated at compile time. |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 4165 | </p> |
| 4166 | |
| 4167 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4168 | Untyped boolean, numeric, and string constants may be used as operands |
| 4169 | 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] | 4170 | respectively. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4171 | </p> |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 4172 | |
| 4173 | <p> |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 4174 | A constant <a href="#Comparison_operators">comparison</a> always yields |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 4175 | an untyped boolean constant. If the left operand of a constant |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 4176 | <a href="#Operators">shift expression</a> is an untyped constant, the |
| 4177 | 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] | 4178 | type as the left operand, which must be of |
| 4179 | <a href="#Numeric_types">integer type</a>. |
Bryan C. Mills | df48003 | 2018-04-13 11:57:13 -0400 | [diff] [blame] | 4180 | </p> |
| 4181 | |
| 4182 | <p> |
| 4183 | Any other operation on untyped constants results in an untyped constant of the |
| 4184 | same kind; that is, a boolean, integer, floating-point, complex, or string |
| 4185 | constant. |
| 4186 | If the untyped operands of a binary operation (other than a shift) are of |
| 4187 | different kinds, the result is of the operand's kind that appears later in this |
| 4188 | list: integer, rune, floating-point, complex. |
| 4189 | For example, an untyped integer constant divided by an |
| 4190 | untyped complex constant yields an untyped complex constant. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4191 | </p> |
| 4192 | |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 4193 | <pre> |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 4194 | const a = 2 + 3.0 // a == 5.0 (untyped floating-point constant) |
| 4195 | const b = 15 / 4 // b == 3 (untyped integer constant) |
| 4196 | const c = 15 / 4.0 // c == 3.75 (untyped floating-point constant) |
Robert Griesemer | 2ae61d5 | 2012-11-17 11:16:07 -0800 | [diff] [blame] | 4197 | const Θ float64 = 3/2 // Θ == 1.0 (type float64, 3/2 is integer division) |
| 4198 | 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] | 4199 | const d = 1 << 3.0 // d == 8 (untyped integer constant) |
| 4200 | const e = 1.0 << 3 // e == 8 (untyped integer constant) |
Robert Griesemer | 2d846f6 | 2013-05-08 10:42:08 -0700 | [diff] [blame] | 4201 | const f = int32(1) << 33 // illegal (constant 8589934592 overflows int32) |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 4202 | 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] | 4203 | const h = "foo" > "bar" // h == true (untyped boolean constant) |
| 4204 | const j = true // j == true (untyped boolean constant) |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 4205 | const k = 'w' + 1 // k == 'x' (untyped rune constant) |
Russ Cox | ef1c535 | 2011-12-09 00:13:19 -0500 | [diff] [blame] | 4206 | const l = "hi" // l == "hi" (untyped string constant) |
| 4207 | const m = string(k) // m == "x" (type string) |
Robert Hencke | 1084ab9 | 2011-12-10 10:04:33 -0800 | [diff] [blame] | 4208 | const Σ = 1 - 0.707i // (untyped complex constant) |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 4209 | const Δ = Σ + 2.0e-4 // (untyped complex constant) |
| 4210 | const Φ = iota*1i - 1/1i // (untyped complex constant) |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 4211 | </pre> |
| 4212 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4213 | <p> |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 4214 | Applying the built-in function <code>complex</code> to untyped |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 4215 | integer, rune, or floating-point constants yields |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 4216 | an untyped complex constant. |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 4217 | </p> |
| 4218 | |
| 4219 | <pre> |
Robert Griesemer | 462860b | 2012-12-12 14:25:40 -0800 | [diff] [blame] | 4220 | const ic = complex(0, c) // ic == 3.75i (untyped complex constant) |
Mihai Borobocea | 8183ed1 | 2013-12-30 13:29:56 -0800 | [diff] [blame] | 4221 | const iΘ = complex(0, Θ) // iΘ == 1i (type complex128) |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 4222 | </pre> |
| 4223 | |
| 4224 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4225 | Constant expressions are always evaluated exactly; intermediate values and the |
| 4226 | constants themselves may require precision significantly larger than supported |
| 4227 | by any predeclared type in the language. The following are legal declarations: |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 4228 | </p> |
| 4229 | |
| 4230 | <pre> |
Robert Griesemer | 462860b | 2012-12-12 14:25:40 -0800 | [diff] [blame] | 4231 | const Huge = 1 << 100 // Huge == 1267650600228229401496703205376 (untyped integer constant) |
| 4232 | const Four int8 = Huge >> 98 // Four == 4 (type int8) |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 4233 | </pre> |
| 4234 | |
| 4235 | <p> |
Robert Griesemer | ddddd39 | 2012-10-19 10:12:09 -0700 | [diff] [blame] | 4236 | The divisor of a constant division or remainder operation must not be zero: |
| 4237 | </p> |
| 4238 | |
| 4239 | <pre> |
| 4240 | 3.14 / 0.0 // illegal: division by zero |
| 4241 | </pre> |
| 4242 | |
| 4243 | <p> |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 4244 | The values of <i>typed</i> constants must always be accurately |
| 4245 | <a href="#Representability">representable</a> by values |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4246 | of the constant type. The following constant expressions are illegal: |
Rob Pike | 21d0349 | 2009-03-24 19:16:42 -0700 | [diff] [blame] | 4247 | </p> |
| 4248 | |
| 4249 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4250 | uint(-1) // -1 cannot be represented as a uint |
| 4251 | int(3.14) // 3.14 cannot be represented as an int |
Robert Griesemer | 462860b | 2012-12-12 14:25:40 -0800 | [diff] [blame] | 4252 | int64(Huge) // 1267650600228229401496703205376 cannot be represented as an int64 |
| 4253 | Four * 300 // operand 300 cannot be represented as an int8 (type of Four) |
| 4254 | 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] | 4255 | </pre> |
| 4256 | |
| 4257 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4258 | The mask used by the unary bitwise complement operator <code>^</code> matches |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 4259 | 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] | 4260 | and -1 for signed and untyped constants. |
Rob Pike | 21d0349 | 2009-03-24 19:16:42 -0700 | [diff] [blame] | 4261 | </p> |
| 4262 | |
| 4263 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4264 | ^1 // untyped integer constant, equal to -2 |
Robert Griesemer | 462860b | 2012-12-12 14:25:40 -0800 | [diff] [blame] | 4265 | 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] | 4266 | ^uint8(1) // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE) |
| 4267 | int8(^1) // same as int8(-2) |
| 4268 | ^int8(1) // same as -1 ^ int8(1) = -2 |
Rob Pike | 21d0349 | 2009-03-24 19:16:42 -0700 | [diff] [blame] | 4269 | </pre> |
| 4270 | |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 4271 | <p> |
| 4272 | Implementation restriction: A compiler may use rounding while |
| 4273 | computing untyped floating-point or complex constant expressions; see |
| 4274 | the implementation restriction in the section |
| 4275 | on <a href="#Constants">constants</a>. This rounding may cause a |
| 4276 | floating-point constant expression to be invalid in an integer |
| 4277 | context, even if it would be integral when calculated using infinite |
Robert Griesemer | d8c6dac | 2015-06-23 14:17:59 -0700 | [diff] [blame] | 4278 | precision, and vice versa. |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 4279 | </p> |
| 4280 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4281 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4282 | <h3 id="Order_of_evaluation">Order of evaluation</h3> |
Rob Pike | c956e90 | 2009-04-14 20:10:49 -0700 | [diff] [blame] | 4283 | |
| 4284 | <p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 4285 | At package level, <a href="#Package_initialization">initialization dependencies</a> |
Robert Griesemer | dbe5f88 | 2014-05-07 08:50:52 -0700 | [diff] [blame] | 4286 | determine the evaluation order of individual initialization expressions in |
| 4287 | <a href="#Variable_declarations">variable declarations</a>. |
| 4288 | Otherwise, when evaluating the <a href="#Operands">operands</a> of an |
| 4289 | expression, assignment, or |
Robert Griesemer | f05a91e | 2012-08-09 11:50:16 -0700 | [diff] [blame] | 4290 | <a href="#Return_statements">return statement</a>, |
| 4291 | all function calls, method calls, and |
Rob Pike | c956e90 | 2009-04-14 20:10:49 -0700 | [diff] [blame] | 4292 | communication operations are evaluated in lexical left-to-right |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4293 | order. |
| 4294 | </p> |
| 4295 | |
| 4296 | <p> |
Robert Griesemer | dbe5f88 | 2014-05-07 08:50:52 -0700 | [diff] [blame] | 4297 | For example, in the (function-local) assignment |
Rob Pike | c956e90 | 2009-04-14 20:10:49 -0700 | [diff] [blame] | 4298 | </p> |
| 4299 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4300 | y[f()], ok = g(h(), i()+x[j()], <-c), k() |
Rob Pike | c956e90 | 2009-04-14 20:10:49 -0700 | [diff] [blame] | 4301 | </pre> |
| 4302 | <p> |
Robert Griesemer | 4f18549 | 2009-05-01 17:00:16 -0700 | [diff] [blame] | 4303 | the function calls and communication happen in the order |
| 4304 | <code>f()</code>, <code>h()</code>, <code>i()</code>, <code>j()</code>, |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 4305 | <code><-c</code>, <code>g()</code>, and <code>k()</code>. |
Robert Griesemer | 4f18549 | 2009-05-01 17:00:16 -0700 | [diff] [blame] | 4306 | However, the order of those events compared to the evaluation |
| 4307 | and indexing of <code>x</code> and the evaluation |
| 4308 | of <code>y</code> is not specified. |
Rob Pike | c956e90 | 2009-04-14 20:10:49 -0700 | [diff] [blame] | 4309 | </p> |
| 4310 | |
Robert Griesemer | f05a91e | 2012-08-09 11:50:16 -0700 | [diff] [blame] | 4311 | <pre> |
| 4312 | a := 1 |
Shenghou Ma | bdac989 | 2013-06-11 02:52:07 +0800 | [diff] [blame] | 4313 | f := func() int { a++; return a } |
Robert Griesemer | dbe5f88 | 2014-05-07 08:50:52 -0700 | [diff] [blame] | 4314 | x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified |
| 4315 | 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 |
| 4316 | 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] | 4317 | </pre> |
| 4318 | |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 4319 | <p> |
Robert Griesemer | dbe5f88 | 2014-05-07 08:50:52 -0700 | [diff] [blame] | 4320 | At package level, initialization dependencies override the left-to-right rule |
| 4321 | for individual initialization expressions, but not for operands within each |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 4322 | expression: |
Robert Griesemer | dbe5f88 | 2014-05-07 08:50:52 -0700 | [diff] [blame] | 4323 | </p> |
| 4324 | |
| 4325 | <pre> |
| 4326 | var a, b, c = f() + v(), g(), sqr(u()) + v() |
| 4327 | |
| 4328 | func f() int { return c } |
| 4329 | func g() int { return a } |
| 4330 | func sqr(x int) int { return x*x } |
| 4331 | |
| 4332 | // functions u and v are independent of all other variables and functions |
| 4333 | </pre> |
| 4334 | |
| 4335 | <p> |
| 4336 | The function calls happen in the order |
| 4337 | <code>u()</code>, <code>sqr()</code>, <code>v()</code>, |
| 4338 | <code>f()</code>, <code>v()</code>, and <code>g()</code>. |
| 4339 | </p> |
| 4340 | |
| 4341 | <p> |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 4342 | Floating-point operations within a single expression are evaluated according to |
| 4343 | the associativity of the operators. Explicit parentheses affect the evaluation |
| 4344 | by overriding the default associativity. |
| 4345 | In the expression <code>x + (y + z)</code> the addition <code>y + z</code> |
| 4346 | is performed before adding <code>x</code>. |
| 4347 | </p> |
| 4348 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4349 | <h2 id="Statements">Statements</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4350 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4351 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4352 | Statements control execution. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4353 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4354 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4355 | <pre class="ebnf"> |
Robert Griesemer | dea4394 | 2009-03-16 17:36:52 -0700 | [diff] [blame] | 4356 | Statement = |
Rob Pike | f3a33bc | 2009-09-14 17:39:17 -0700 | [diff] [blame] | 4357 | Declaration | LabeledStmt | SimpleStmt | |
| 4358 | GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt | |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4359 | FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt | |
| 4360 | DeferStmt . |
Robert Griesemer | 7abfcd9 | 2008-10-07 17:14:30 -0700 | [diff] [blame] | 4361 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4362 | SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4363 | </pre> |
Robert Griesemer | 7271e04 | 2008-10-09 20:05:24 -0700 | [diff] [blame] | 4364 | |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 4365 | <h3 id="Terminating_statements">Terminating statements</h3> |
| 4366 | |
| 4367 | <p> |
Robert Griesemer | f3f507b | 2017-12-21 15:17:35 -0800 | [diff] [blame] | 4368 | A <i>terminating statement</i> prevents execution of all statements that lexically |
| 4369 | appear after it in the same <a href="#Blocks">block</a>. The following statements |
| 4370 | are terminating: |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 4371 | </p> |
| 4372 | |
| 4373 | <ol> |
| 4374 | <li> |
| 4375 | A <a href="#Return_statements">"return"</a> or |
| 4376 | <a href="#Goto_statements">"goto"</a> statement. |
| 4377 | <!-- ul below only for regular layout --> |
| 4378 | <ul> </ul> |
| 4379 | </li> |
| 4380 | |
| 4381 | <li> |
| 4382 | A call to the built-in function |
| 4383 | <a href="#Handling_panics"><code>panic</code></a>. |
| 4384 | <!-- ul below only for regular layout --> |
| 4385 | <ul> </ul> |
| 4386 | </li> |
| 4387 | |
| 4388 | <li> |
| 4389 | A <a href="#Blocks">block</a> in which the statement list ends in a terminating statement. |
| 4390 | <!-- ul below only for regular layout --> |
| 4391 | <ul> </ul> |
| 4392 | </li> |
| 4393 | |
| 4394 | <li> |
| 4395 | An <a href="#If_statements">"if" statement</a> in which: |
| 4396 | <ul> |
| 4397 | <li>the "else" branch is present, and</li> |
| 4398 | <li>both branches are terminating statements.</li> |
| 4399 | </ul> |
| 4400 | </li> |
| 4401 | |
| 4402 | <li> |
| 4403 | A <a href="#For_statements">"for" statement</a> in which: |
| 4404 | <ul> |
| 4405 | <li>there are no "break" statements referring to the "for" statement, and</li> |
| 4406 | <li>the loop condition is absent.</li> |
| 4407 | </ul> |
| 4408 | </li> |
| 4409 | |
| 4410 | <li> |
| 4411 | A <a href="#Switch_statements">"switch" statement</a> in which: |
| 4412 | <ul> |
| 4413 | <li>there are no "break" statements referring to the "switch" statement,</li> |
| 4414 | <li>there is a default case, and</li> |
| 4415 | <li>the statement lists in each case, including the default, end in a terminating |
| 4416 | statement, or a possibly labeled <a href="#Fallthrough_statements">"fallthrough" |
| 4417 | statement</a>.</li> |
| 4418 | </ul> |
| 4419 | </li> |
| 4420 | |
| 4421 | <li> |
| 4422 | A <a href="#Select_statements">"select" statement</a> in which: |
| 4423 | <ul> |
| 4424 | <li>there are no "break" statements referring to the "select" statement, and</li> |
| 4425 | <li>the statement lists in each case, including the default if present, |
| 4426 | end in a terminating statement.</li> |
| 4427 | </ul> |
| 4428 | </li> |
| 4429 | |
| 4430 | <li> |
| 4431 | A <a href="#Labeled_statements">labeled statement</a> labeling |
| 4432 | a terminating statement. |
| 4433 | </li> |
| 4434 | </ol> |
| 4435 | |
| 4436 | <p> |
| 4437 | All other statements are not terminating. |
| 4438 | </p> |
| 4439 | |
| 4440 | <p> |
| 4441 | 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] | 4442 | is not empty and its final non-empty statement is terminating. |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 4443 | </p> |
| 4444 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4445 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4446 | <h3 id="Empty_statements">Empty statements</h3> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 4447 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4448 | <p> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 4449 | The empty statement does nothing. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4450 | </p> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 4451 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4452 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4453 | EmptyStmt = . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4454 | </pre> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 4455 | |
| 4456 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4457 | <h3 id="Labeled_statements">Labeled statements</h3> |
Robert Griesemer | dea4394 | 2009-03-16 17:36:52 -0700 | [diff] [blame] | 4458 | |
| 4459 | <p> |
| 4460 | A labeled statement may be the target of a <code>goto</code>, |
| 4461 | <code>break</code> or <code>continue</code> statement. |
| 4462 | </p> |
| 4463 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4464 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4465 | LabeledStmt = Label ":" Statement . |
Robert Griesemer | dea4394 | 2009-03-16 17:36:52 -0700 | [diff] [blame] | 4466 | Label = identifier . |
| 4467 | </pre> |
| 4468 | |
| 4469 | <pre> |
Robert Griesemer | 7fc4e37 | 2011-02-01 12:51:10 -0800 | [diff] [blame] | 4470 | Error: log.Panic("error encountered") |
Robert Griesemer | dea4394 | 2009-03-16 17:36:52 -0700 | [diff] [blame] | 4471 | </pre> |
| 4472 | |
| 4473 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4474 | <h3 id="Expression_statements">Expression statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4475 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4476 | <p> |
Robert Griesemer | 8c058b3 | 2012-09-18 11:25:53 -0700 | [diff] [blame] | 4477 | With the exception of specific built-in functions, |
| 4478 | function and method <a href="#Calls">calls</a> and |
| 4479 | <a href="#Receive_operator">receive operations</a> |
Robert Griesemer | 6af887e | 2011-05-02 09:16:31 -0700 | [diff] [blame] | 4480 | can appear in statement context. Such statements may be parenthesized. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4481 | </p> |
| 4482 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4483 | <pre class="ebnf"> |
Robert Griesemer | c134718 | 2011-04-29 12:20:31 -0700 | [diff] [blame] | 4484 | ExpressionStmt = Expression . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4485 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4486 | |
Robert Griesemer | 8c058b3 | 2012-09-18 11:25:53 -0700 | [diff] [blame] | 4487 | <p> |
| 4488 | The following built-in functions are not permitted in statement context: |
| 4489 | </p> |
| 4490 | |
| 4491 | <pre> |
| 4492 | append cap complex imag len make new real |
| 4493 | unsafe.Alignof unsafe.Offsetof unsafe.Sizeof |
| 4494 | </pre> |
| 4495 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4496 | <pre> |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4497 | h(x+y) |
| 4498 | f.Close() |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 4499 | <-ch |
Robert Griesemer | 6af887e | 2011-05-02 09:16:31 -0700 | [diff] [blame] | 4500 | (<-ch) |
Robert Griesemer | 8c058b3 | 2012-09-18 11:25:53 -0700 | [diff] [blame] | 4501 | len("foo") // illegal if len is the built-in function |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4502 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4503 | |
| 4504 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4505 | <h3 id="Send_statements">Send statements</h3> |
| 4506 | |
| 4507 | <p> |
| 4508 | A send statement sends a value on a channel. |
Robert Griesemer | cc3f21c | 2012-12-03 14:23:41 -0800 | [diff] [blame] | 4509 | The channel expression must be of <a href="#Channel_types">channel type</a>, |
| 4510 | the channel direction must permit send operations, |
| 4511 | 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] | 4512 | to the channel's element type. |
| 4513 | </p> |
| 4514 | |
| 4515 | <pre class="ebnf"> |
| 4516 | SendStmt = Channel "<-" Expression . |
| 4517 | Channel = Expression . |
| 4518 | </pre> |
| 4519 | |
| 4520 | <p> |
| 4521 | Both the channel and the value expression are evaluated before communication |
Russ Cox | e7a138b | 2012-02-08 15:24:48 -0500 | [diff] [blame] | 4522 | begins. Communication blocks until the send can proceed. |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4523 | A send on an unbuffered channel can proceed if a receiver is ready. |
| 4524 | 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] | 4525 | 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] | 4526 | A send on a <code>nil</code> channel blocks forever. |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4527 | </p> |
| 4528 | |
| 4529 | <pre> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 4530 | ch <- 3 // send value 3 to channel ch |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4531 | </pre> |
| 4532 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4533 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4534 | <h3 id="IncDec_statements">IncDec statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4535 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4536 | <p> |
Robert Griesemer | 52a5480 | 2008-09-30 13:02:50 -0700 | [diff] [blame] | 4537 | The "++" and "--" statements increment or decrement their operands |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4538 | by the untyped <a href="#Constants">constant</a> <code>1</code>. |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 4539 | As with an assignment, the operand must be <a href="#Address_operators">addressable</a> |
| 4540 | or a map index expression. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4541 | </p> |
Robert Griesemer | 52a5480 | 2008-09-30 13:02:50 -0700 | [diff] [blame] | 4542 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4543 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4544 | IncDecStmt = Expression ( "++" | "--" ) . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4545 | </pre> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 4546 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4547 | <p> |
Robert Griesemer | 506c008 | 2009-09-08 15:41:14 -0700 | [diff] [blame] | 4548 | The following <a href="#Assignments">assignment statements</a> are semantically |
Robert Griesemer | 52a5480 | 2008-09-30 13:02:50 -0700 | [diff] [blame] | 4549 | equivalent: |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4550 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4551 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 4552 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4553 | IncDec statement Assignment |
| 4554 | x++ x += 1 |
| 4555 | x-- x -= 1 |
| 4556 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4557 | |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 4558 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4559 | <h3 id="Assignments">Assignments</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4560 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4561 | <pre class="ebnf"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4562 | Assignment = ExpressionList assign_op ExpressionList . |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 4563 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4564 | assign_op = [ add_op | mul_op ] "=" . |
| 4565 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4566 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4567 | <p> |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 4568 | 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] | 4569 | a map index expression, or (for <code>=</code> assignments only) the |
| 4570 | <a href="#Blank_identifier">blank identifier</a>. |
Robert Griesemer | 6af887e | 2011-05-02 09:16:31 -0700 | [diff] [blame] | 4571 | Operands may be parenthesized. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4572 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4573 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4574 | <pre> |
| 4575 | x = 1 |
| 4576 | *p = f() |
| 4577 | a[i] = 23 |
Robert Griesemer | 6af887e | 2011-05-02 09:16:31 -0700 | [diff] [blame] | 4578 | (k) = <-ch // same as: k = <-ch |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4579 | </pre> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4580 | |
| 4581 | <p> |
| 4582 | 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] | 4583 | <code>y</code> where <i>op</i> is a binary <a href="#Arithmetic_operators">arithmetic operator</a> |
| 4584 | 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] | 4585 | <code>(y)</code> but evaluates <code>x</code> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4586 | 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] | 4587 | In assignment operations, both the left- and right-hand expression lists |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4588 | must contain exactly one single-valued expression, and the left-hand |
| 4589 | expression must not be the blank identifier. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4590 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4591 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4592 | <pre> |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 4593 | a[i] <<= 2 |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 4594 | i &^= 1<<n |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4595 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4596 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4597 | <p> |
| 4598 | A tuple assignment assigns the individual elements of a multi-valued |
| 4599 | operation to a list of variables. There are two forms. In the |
| 4600 | first, the right hand operand is a single multi-valued expression |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 4601 | such as a function call, a <a href="#Channel_types">channel</a> or |
| 4602 | <a href="#Map_types">map</a> operation, or a <a href="#Type_assertions">type assertion</a>. |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 4603 | The number of operands on the left |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 4604 | hand side must match the number of values. For instance, if |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4605 | <code>f</code> is a function returning two values, |
| 4606 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4607 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4608 | <pre> |
| 4609 | x, y = f() |
| 4610 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4611 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4612 | <p> |
| 4613 | 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] | 4614 | 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] | 4615 | of expressions on the right, each of which must be single-valued, and the |
| 4616 | <i>n</i>th expression on the right is assigned to the <i>n</i>th |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4617 | operand on the left: |
Robert Griesemer | 2dde4f5 | 2012-05-24 10:59:48 -0700 | [diff] [blame] | 4618 | </p> |
| 4619 | |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4620 | <pre> |
| 4621 | one, two, three = '一', '二', '三' |
| 4622 | </pre> |
| 4623 | |
| 4624 | <p> |
| 4625 | The <a href="#Blank_identifier">blank identifier</a> provides a way to |
| 4626 | ignore right-hand side values in an assignment: |
| 4627 | </p> |
| 4628 | |
| 4629 | <pre> |
| 4630 | _ = x // evaluate x but ignore it |
| 4631 | x, _ = f() // evaluate f() but ignore second result value |
| 4632 | </pre> |
| 4633 | |
Robert Griesemer | 2dde4f5 | 2012-05-24 10:59:48 -0700 | [diff] [blame] | 4634 | <p> |
| 4635 | The assignment proceeds in two phases. |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 4636 | First, the operands of <a href="#Index_expressions">index expressions</a> |
Russ Cox | fa53811 | 2011-10-13 15:44:17 -0400 | [diff] [blame] | 4637 | and <a href="#Address_operators">pointer indirections</a> |
| 4638 | (including implicit pointer indirections in <a href="#Selectors">selectors</a>) |
| 4639 | on the left and the expressions on the right are all |
| 4640 | <a href="#Order_of_evaluation">evaluated in the usual order</a>. |
| 4641 | Second, the assignments are carried out in left-to-right order. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4642 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4643 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4644 | <pre> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4645 | a, b = b, a // exchange a and b |
Russ Cox | fa53811 | 2011-10-13 15:44:17 -0400 | [diff] [blame] | 4646 | |
| 4647 | x := []int{1, 2, 3} |
| 4648 | i := 0 |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4649 | i, x[i] = 1, 2 // set i = 1, x[0] = 2 |
Russ Cox | fa53811 | 2011-10-13 15:44:17 -0400 | [diff] [blame] | 4650 | |
| 4651 | i = 0 |
| 4652 | x[i], i = 2, 1 // set x[0] = 2, i = 1 |
| 4653 | |
Robert Griesemer | 2dde4f5 | 2012-05-24 10:59:48 -0700 | [diff] [blame] | 4654 | 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] | 4655 | |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4656 | 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] | 4657 | |
| 4658 | type Point struct { x, y int } |
| 4659 | var p *Point |
| 4660 | 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] | 4661 | |
| 4662 | i = 2 |
| 4663 | x = []int{3, 5, 7} |
| 4664 | for i, x[i] = range x { // set i, x[2] = 0, x[0] |
| 4665 | break |
| 4666 | } |
| 4667 | // after this loop, i == 0 and x == []int{3, 5, 3} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4668 | </pre> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4669 | |
| 4670 | <p> |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4671 | In assignments, each value must be <a href="#Assignability">assignable</a> |
| 4672 | 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] | 4673 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4674 | |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4675 | <ol> |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 4676 | <li> |
| 4677 | Any typed value may be assigned to the blank identifier. |
| 4678 | </li> |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4679 | |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 4680 | <li> |
| 4681 | If an untyped constant |
| 4682 | is assigned to a variable of interface type or the blank identifier, |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 4683 | the constant is first implicitly <a href="#Conversions">converted</a> to its |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 4684 | <a href="#Constants">default type</a>. |
| 4685 | </li> |
| 4686 | |
| 4687 | <li> |
| 4688 | If an untyped boolean value is assigned to a variable of interface type or |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 4689 | 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] | 4690 | </li> |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4691 | </ol> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4692 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4693 | <h3 id="If_statements">If statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4694 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4695 | <p> |
| 4696 | "If" statements specify the conditional execution of two branches |
| 4697 | according to the value of a boolean expression. If the expression |
| 4698 | evaluates to true, the "if" branch is executed, otherwise, if |
Robert Griesemer | a1368a6 | 2011-02-22 15:31:57 -0800 | [diff] [blame] | 4699 | present, the "else" branch is executed. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4700 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4701 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4702 | <pre class="ebnf"> |
Russ Cox | 58e19aa | 2011-07-14 17:15:52 -0400 | [diff] [blame] | 4703 | IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ( IfStmt | Block ) ] . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4704 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4705 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4706 | <pre> |
Robert Griesemer | a1368a6 | 2011-02-22 15:31:57 -0800 | [diff] [blame] | 4707 | if x > max { |
| 4708 | x = max |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4709 | } |
| 4710 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4711 | |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 4712 | <p> |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 4713 | The expression may be preceded by a simple statement, which |
| 4714 | executes before the expression is evaluated. |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 4715 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4716 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4717 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4718 | if x := f(); x < y { |
| 4719 | return x |
Robert Griesemer | a1368a6 | 2011-02-22 15:31:57 -0800 | [diff] [blame] | 4720 | } else if x > z { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4721 | return z |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4722 | } else { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4723 | return y |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4724 | } |
| 4725 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4726 | |
| 4727 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4728 | <h3 id="Switch_statements">Switch statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4729 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4730 | <p> |
| 4731 | "Switch" statements provide multi-way execution. |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4732 | An expression or type specifier is compared to the "cases" |
| 4733 | inside the "switch" to determine which branch |
| 4734 | to execute. |
Rob Pike | afee1c5 | 2009-03-20 17:41:25 -0700 | [diff] [blame] | 4735 | </p> |
Robert Griesemer | 091cba8 | 2009-03-19 08:39:40 -0700 | [diff] [blame] | 4736 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4737 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4738 | SwitchStmt = ExprSwitchStmt | TypeSwitchStmt . |
Robert Griesemer | 091cba8 | 2009-03-19 08:39:40 -0700 | [diff] [blame] | 4739 | </pre> |
| 4740 | |
Rob Pike | afee1c5 | 2009-03-20 17:41:25 -0700 | [diff] [blame] | 4741 | <p> |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4742 | There are two forms: expression switches and type switches. |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4743 | In an expression switch, the cases contain expressions that are compared |
| 4744 | against the value of the switch expression. |
| 4745 | In a type switch, the cases contain types that are compared against the |
| 4746 | type of a specially annotated switch expression. |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 4747 | The switch expression is evaluated exactly once in a switch statement. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4748 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4749 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4750 | <h4 id="Expression_switches">Expression switches</h4> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4751 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4752 | <p> |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4753 | In an expression switch, |
| 4754 | the switch expression is evaluated and |
| 4755 | the case expressions, which need not be constants, |
Robert Griesemer | 4f18549 | 2009-05-01 17:00:16 -0700 | [diff] [blame] | 4756 | 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] | 4757 | switch expression |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4758 | triggers execution of the statements of the associated case; |
| 4759 | the other cases are skipped. |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4760 | If no case matches and there is a "default" case, |
| 4761 | its statements are executed. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4762 | There can be at most one default case and it may appear anywhere in the |
| 4763 | "switch" statement. |
Robert Griesemer | ab26623 | 2014-02-25 09:13:37 -0800 | [diff] [blame] | 4764 | A missing switch expression is equivalent to the boolean value |
| 4765 | <code>true</code>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4766 | </p> |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4767 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4768 | <pre class="ebnf"> |
Rob Pike | f3a33bc | 2009-09-14 17:39:17 -0700 | [diff] [blame] | 4769 | ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" . |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 4770 | ExprCaseClause = ExprSwitchCase ":" StatementList . |
Robert Griesemer | 091cba8 | 2009-03-19 08:39:40 -0700 | [diff] [blame] | 4771 | ExprSwitchCase = "case" ExpressionList | "default" . |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4772 | </pre> |
| 4773 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4774 | <p> |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 4775 | 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] | 4776 | <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] | 4777 | 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] | 4778 | The predeclared untyped value <code>nil</code> cannot be used as a switch expression. |
| 4779 | </p> |
| 4780 | |
| 4781 | <p> |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 4782 | 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] | 4783 | to the type of the switch expression. |
| 4784 | For each (possibly converted) case expression <code>x</code> and the value <code>t</code> |
| 4785 | of the switch expression, <code>x == t</code> must be a valid <a href="#Comparison_operators">comparison</a>. |
| 4786 | </p> |
| 4787 | |
| 4788 | <p> |
| 4789 | In other words, the switch expression is treated as if it were used to declare and |
| 4790 | initialize a temporary variable <code>t</code> without explicit type; it is that |
| 4791 | value of <code>t</code> against which each case expression <code>x</code> is tested |
| 4792 | for equality. |
| 4793 | </p> |
| 4794 | |
| 4795 | <p> |
Robert Griesemer | 67a6b4f | 2013-03-01 16:45:14 -0800 | [diff] [blame] | 4796 | In a case or default clause, the last non-empty statement |
| 4797 | may be a (possibly <a href="#Labeled_statements">labeled</a>) |
| 4798 | <a href="#Fallthrough_statements">"fallthrough" statement</a> to |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4799 | indicate that control should flow from the end of this clause to |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 4800 | the first statement of the next clause. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4801 | Otherwise control flows to the end of the "switch" statement. |
Robert Griesemer | 67a6b4f | 2013-03-01 16:45:14 -0800 | [diff] [blame] | 4802 | A "fallthrough" statement may appear as the last statement of all |
| 4803 | but the last clause of an expression switch. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4804 | </p> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 4805 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4806 | <p> |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 4807 | The switch expression may be preceded by a simple statement, which |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 4808 | executes before the expression is evaluated. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4809 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4810 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4811 | <pre> |
| 4812 | switch tag { |
Rob Pike | 65ec16b | 2009-05-29 15:46:03 -0700 | [diff] [blame] | 4813 | default: s3() |
| 4814 | case 0, 1, 2, 3: s1() |
| 4815 | case 4, 5, 6, 7: s2() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4816 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4817 | |
Andrew Gerrand | 10b77f7 | 2010-03-29 13:12:08 +1100 | [diff] [blame] | 4818 | switch x := f(); { // missing switch expression means "true" |
Rob Pike | 65ec16b | 2009-05-29 15:46:03 -0700 | [diff] [blame] | 4819 | case x < 0: return -x |
| 4820 | default: return x |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4821 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4822 | |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 4823 | switch { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4824 | case x < y: f1() |
| 4825 | case x < z: f2() |
| 4826 | case x == 4: f3() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4827 | } |
| 4828 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4829 | |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 4830 | <p> |
| 4831 | Implementation restriction: A compiler may disallow multiple case |
| 4832 | expressions evaluating to the same constant. |
| 4833 | For instance, the current compilers disallow duplicate integer, |
| 4834 | floating point, or string constants in case expressions. |
| 4835 | </p> |
| 4836 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4837 | <h4 id="Type_switches">Type switches</h4> |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4838 | |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4839 | <p> |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4840 | A type switch compares types rather than values. It is otherwise similar |
Robert Griesemer | 1f95f0d | 2009-08-27 16:44:17 -0700 | [diff] [blame] | 4841 | 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] | 4842 | has the form of a <a href="#Type_assertions">type assertion</a> |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4843 | using the reserved word <code>type</code> rather than an actual type: |
| 4844 | </p> |
| 4845 | |
| 4846 | <pre> |
| 4847 | switch x.(type) { |
| 4848 | // cases |
| 4849 | } |
| 4850 | </pre> |
| 4851 | |
| 4852 | <p> |
| 4853 | Cases then match actual types <code>T</code> against the dynamic type of the |
| 4854 | expression <code>x</code>. As with type assertions, <code>x</code> must be of |
| 4855 | <a href="#Interface_types">interface type</a>, and each non-interface type |
| 4856 | <code>T</code> listed in a case must implement the type of <code>x</code>. |
Robert Griesemer | 3d81d4a | 2016-05-31 13:32:34 -0700 | [diff] [blame] | 4857 | The types listed in the cases of a type switch must all be |
| 4858 | <a href="#Type_identity">different</a>. |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4859 | </p> |
| 4860 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4861 | <pre class="ebnf"> |
Rob Pike | f3a33bc | 2009-09-14 17:39:17 -0700 | [diff] [blame] | 4862 | TypeSwitchStmt = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" . |
Russ Cox | c1045db | 2009-12-23 13:48:44 -0800 | [diff] [blame] | 4863 | TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" . |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 4864 | TypeCaseClause = TypeSwitchCase ":" StatementList . |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 4865 | TypeSwitchCase = "case" TypeList | "default" . |
| 4866 | TypeList = Type { "," Type } . |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4867 | </pre> |
| 4868 | |
| 4869 | <p> |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 4870 | The TypeSwitchGuard may include a |
| 4871 | <a href="#Short_variable_declarations">short variable declaration</a>. |
Robert Griesemer | f8555ea | 2016-08-18 13:14:30 -0700 | [diff] [blame] | 4872 | When that form is used, the variable is declared at the end of the |
| 4873 | TypeSwitchCase in the <a href="#Blocks">implicit block</a> of each clause. |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 4874 | In clauses with a case listing exactly one type, the variable |
| 4875 | has that type; otherwise, the variable has the type of the expression |
| 4876 | in the TypeSwitchGuard. |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 4877 | </p> |
| 4878 | |
| 4879 | <p> |
griesemer | 84ac90e | 2017-08-24 15:05:53 +0200 | [diff] [blame] | 4880 | Instead of a type, a case may use the predeclared identifier |
| 4881 | <a href="#Predeclared_identifiers"><code>nil</code></a>; |
| 4882 | that case is selected when the expression in the TypeSwitchGuard |
Robert Griesemer | 1f95f0d | 2009-08-27 16:44:17 -0700 | [diff] [blame] | 4883 | is a <code>nil</code> interface value. |
Robert Griesemer | 3d81d4a | 2016-05-31 13:32:34 -0700 | [diff] [blame] | 4884 | There may be at most one <code>nil</code> case. |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 4885 | </p> |
| 4886 | |
| 4887 | <p> |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 4888 | Given an expression <code>x</code> of type <code>interface{}</code>, |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4889 | the following type switch: |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4890 | </p> |
| 4891 | |
| 4892 | <pre> |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 4893 | switch i := x.(type) { |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 4894 | case nil: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4895 | printString("x is nil") // type of i is type of x (interface{}) |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4896 | case int: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4897 | printInt(i) // type of i is int |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 4898 | case float64: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4899 | printFloat64(i) // type of i is float64 |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 4900 | case func(int) float64: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4901 | printFunction(i) // type of i is func(int) float64 |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 4902 | case bool, string: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4903 | 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] | 4904 | default: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4905 | 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] | 4906 | } |
| 4907 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4908 | |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4909 | <p> |
| 4910 | could be rewritten: |
| 4911 | </p> |
| 4912 | |
| 4913 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4914 | v := x // x is evaluated exactly once |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 4915 | if v == nil { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4916 | i := v // type of i is type of x (interface{}) |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4917 | printString("x is nil") |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 4918 | } else if i, isInt := v.(int); isInt { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4919 | printInt(i) // type of i is int |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 4920 | } else if i, isFloat64 := v.(float64); isFloat64 { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4921 | printFloat64(i) // type of i is float64 |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 4922 | } else if i, isFunc := v.(func(int) float64); isFunc { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4923 | printFunction(i) // type of i is func(int) float64 |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4924 | } else { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4925 | _, isBool := v.(bool) |
| 4926 | _, isString := v.(string) |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 4927 | if isBool || isString { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4928 | i := v // type of i is type of x (interface{}) |
| 4929 | printString("type is bool or string") |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 4930 | } else { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4931 | i := v // type of i is type of x (interface{}) |
| 4932 | printString("don't know the type") |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 4933 | } |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4934 | } |
| 4935 | </pre> |
| 4936 | |
Robert Griesemer | aeaab59 | 2009-08-31 17:30:55 -0700 | [diff] [blame] | 4937 | <p> |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 4938 | The type switch guard may be preceded by a simple statement, which |
| 4939 | executes before the guard is evaluated. |
Robert Griesemer | 1f95f0d | 2009-08-27 16:44:17 -0700 | [diff] [blame] | 4940 | </p> |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 4941 | |
| 4942 | <p> |
| 4943 | The "fallthrough" statement is not permitted in a type switch. |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 4944 | </p> |
| 4945 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4946 | <h3 id="For_statements">For statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4947 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4948 | <p> |
Robert Griesemer | b01f612 | 2016-11-18 10:49:29 -0800 | [diff] [blame] | 4949 | A "for" statement specifies repeated execution of a block. There are three forms: |
| 4950 | 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] | 4951 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4952 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4953 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4954 | ForStmt = "for" [ Condition | ForClause | RangeClause ] Block . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4955 | Condition = Expression . |
| 4956 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4957 | |
Robert Griesemer | b01f612 | 2016-11-18 10:49:29 -0800 | [diff] [blame] | 4958 | <h4 id="For_condition">For statements with single condition</h4> |
| 4959 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4960 | <p> |
| 4961 | In its simplest form, a "for" statement specifies the repeated execution of |
| 4962 | a block as long as a boolean condition evaluates to true. |
| 4963 | The condition is evaluated before each iteration. |
Robert Griesemer | ab26623 | 2014-02-25 09:13:37 -0800 | [diff] [blame] | 4964 | If the condition is absent, it is equivalent to the boolean value |
| 4965 | <code>true</code>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4966 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4967 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4968 | <pre> |
| 4969 | for a < b { |
| 4970 | a *= 2 |
| 4971 | } |
| 4972 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4973 | |
Robert Griesemer | b01f612 | 2016-11-18 10:49:29 -0800 | [diff] [blame] | 4974 | <h4 id="For_clause">For statements with <code>for</code> clause</h4> |
| 4975 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4976 | <p> |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 4977 | 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] | 4978 | additionally it may specify an <i>init</i> |
| 4979 | and a <i>post</i> statement, such as an assignment, |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 4980 | an increment or decrement statement. The init statement may be a |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 4981 | <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] | 4982 | Variables declared by the init statement are re-used in each iteration. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4983 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4984 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4985 | <pre class="ebnf"> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4986 | ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] . |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4987 | InitStmt = SimpleStmt . |
| 4988 | PostStmt = SimpleStmt . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4989 | </pre> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 4990 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4991 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4992 | for i := 0; i < 10; i++ { |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4993 | f(i) |
| 4994 | } |
| 4995 | </pre> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 4996 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4997 | <p> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4998 | If non-empty, the init statement is executed once before evaluating the |
| 4999 | condition for the first iteration; |
| 5000 | the post statement is executed after each execution of the block (and |
| 5001 | only if the block was executed). |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5002 | Any element of the ForClause may be empty but the |
| 5003 | <a href="#Semicolons">semicolons</a> are |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5004 | required unless there is only a condition. |
Robert Griesemer | ab26623 | 2014-02-25 09:13:37 -0800 | [diff] [blame] | 5005 | If the condition is absent, it is equivalent to the boolean value |
| 5006 | <code>true</code>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5007 | </p> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 5008 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5009 | <pre> |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 5010 | for cond { S() } is the same as for ; cond ; { S() } |
| 5011 | for { S() } is the same as for true { S() } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5012 | </pre> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 5013 | |
Robert Griesemer | b01f612 | 2016-11-18 10:49:29 -0800 | [diff] [blame] | 5014 | <h4 id="For_range">For statements with <code>range</code> clause</h4> |
| 5015 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5016 | <p> |
| 5017 | A "for" statement with a "range" clause |
Rob Pike | 7aee71b | 2009-04-15 20:28:25 -0700 | [diff] [blame] | 5018 | iterates through all entries of an array, slice, string or map, |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5019 | 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] | 5020 | 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] | 5021 | </p> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 5022 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5023 | <pre class="ebnf"> |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5024 | RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5025 | </pre> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 5026 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5027 | <p> |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5028 | 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] | 5029 | which may be an array, pointer to an array, slice, string, map, or channel permitting |
| 5030 | <a href="#Receive_operator">receive operations</a>. |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5031 | 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] | 5032 | <a href="#Address_operators">addressable</a> or map index expressions; they |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5033 | denote the iteration variables. If the range expression is a channel, at most |
| 5034 | one iteration variable is permitted, otherwise there may be up to two. |
| 5035 | If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>, |
| 5036 | the range clause is equivalent to the same clause without that identifier. |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5037 | </p> |
Rob Pike | 29d0f02 | 2011-01-05 11:39:57 -0800 | [diff] [blame] | 5038 | |
| 5039 | <p> |
griesemer | ada6557 | 2017-10-17 15:30:12 -0700 | [diff] [blame] | 5040 | The range expression <code>x</code> is evaluated once before beginning the loop, |
| 5041 | with one exception: if at most one iteration variable is present and |
| 5042 | <code>len(x)</code> is <a href="#Length_and_capacity">constant</a>, |
| 5043 | the range expression is not evaluated. |
Russ Cox | 61e02ee | 2013-02-15 14:39:28 -0500 | [diff] [blame] | 5044 | </p> |
| 5045 | |
| 5046 | <p> |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5047 | Function calls on the left are evaluated once per iteration. |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5048 | For each iteration, iteration values are produced as follows |
| 5049 | if the respective iteration variables are present: |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5050 | </p> |
| 5051 | |
| 5052 | <pre class="grammar"> |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5053 | Range expression 1st value 2nd value |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5054 | |
| 5055 | 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] | 5056 | string s string type index i int see below rune |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5057 | map m map[K]V key k K m[k] V |
Shenghou Ma | ced5715 | 2013-01-17 23:11:25 +0800 | [diff] [blame] | 5058 | channel c chan E, <-chan E element e E |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5059 | </pre> |
| 5060 | |
| 5061 | <ol> |
| 5062 | <li> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5063 | 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] | 5064 | values are produced in increasing order, starting at element index 0. |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5065 | If at most one iteration variable is present, the range loop produces |
Robert Griesemer | bb3a32e | 2013-05-20 13:27:53 -0700 | [diff] [blame] | 5066 | 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] | 5067 | 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] | 5068 | </li> |
| 5069 | |
| 5070 | <li> |
| 5071 | For a string value, the "range" clause iterates over the Unicode code points |
| 5072 | in the string starting at byte index 0. On successive iterations, the index value will be the |
| 5073 | 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] | 5074 | 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] | 5075 | the corresponding code point. If the iteration encounters an invalid |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5076 | UTF-8 sequence, the second value will be <code>0xFFFD</code>, |
Rob Pike | 7aee71b | 2009-04-15 20:28:25 -0700 | [diff] [blame] | 5077 | the Unicode replacement character, and the next iteration will advance |
| 5078 | a single byte in the string. |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5079 | </li> |
| 5080 | |
| 5081 | <li> |
Russ Cox | e40d6e0 | 2011-10-17 18:49:02 -0400 | [diff] [blame] | 5082 | The iteration order over maps is not specified |
| 5083 | 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] | 5084 | If a map entry that has not yet been reached is removed during iteration, |
| 5085 | 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] | 5086 | created during iteration, that entry may be produced during the iteration or |
| 5087 | may be skipped. The choice may vary for each entry created and from one |
| 5088 | iteration to the next. |
| 5089 | 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] | 5090 | </li> |
| 5091 | |
| 5092 | <li> |
| 5093 | For channels, the iteration values produced are the successive values sent on |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5094 | the channel until the channel is <a href="#Close">closed</a>. If the channel |
| 5095 | is <code>nil</code>, the range expression blocks forever. |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5096 | </li> |
Anthony Martin | 0122a66 | 2011-02-08 14:51:15 -0800 | [diff] [blame] | 5097 | </ol> |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5098 | |
Rob Pike | 7aee71b | 2009-04-15 20:28:25 -0700 | [diff] [blame] | 5099 | <p> |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5100 | The iteration values are assigned to the respective |
| 5101 | iteration variables as in an <a href="#Assignments">assignment statement</a>. |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 5102 | </p> |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5103 | |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 5104 | <p> |
Robert Griesemer | da63371 | 2012-02-29 09:06:05 -0800 | [diff] [blame] | 5105 | 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] | 5106 | <a href="#Short_variable_declarations">short variable declaration</a> |
| 5107 | (<code>:=</code>). |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5108 | 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] | 5109 | 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] | 5110 | statement; they are re-used in each iteration. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5111 | If the iteration variables are declared outside the "for" statement, |
| 5112 | after execution their values will be those of the last iteration. |
| 5113 | </p> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 5114 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5115 | <pre> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5116 | var testdata *struct { |
| 5117 | a *[7]int |
| 5118 | } |
| 5119 | for i, _ := range testdata.a { |
| 5120 | // testdata.a is never evaluated; len(testdata.a) is constant |
| 5121 | // i ranges from 0 to 6 |
| 5122 | f(i) |
| 5123 | } |
| 5124 | |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5125 | var a [10]string |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5126 | for i, s := range a { |
| 5127 | // type of i is int |
| 5128 | // type of s is string |
| 5129 | // s == a[i] |
| 5130 | g(i, s) |
| 5131 | } |
| 5132 | |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5133 | var key string |
Robert Griesemer | 4de1d1d | 2018-01-03 10:33:11 -0800 | [diff] [blame] | 5134 | var val interface {} // element type of m is assignable to val |
Robert Griesemer | 63f54ae | 2013-07-11 14:41:46 -0700 | [diff] [blame] | 5135 | 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] | 5136 | for key, val = range m { |
| 5137 | h(key, val) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5138 | } |
| 5139 | // key == last map key encountered in iteration |
| 5140 | // val == map[key] |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5141 | |
| 5142 | var ch chan Work = producer() |
| 5143 | for w := range ch { |
| 5144 | doWork(w) |
| 5145 | } |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5146 | |
| 5147 | // empty a channel |
| 5148 | for range ch {} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5149 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5150 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5151 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5152 | <h3 id="Go_statements">Go statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5153 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5154 | <p> |
Robert Griesemer | 25dd002 | 2012-11-29 11:46:25 -0800 | [diff] [blame] | 5155 | A "go" statement starts the execution of a function call |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5156 | as an independent concurrent thread of control, or <i>goroutine</i>, |
| 5157 | within the same address space. |
| 5158 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5159 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5160 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5161 | GoStmt = "go" Expression . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5162 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5163 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5164 | <p> |
Robert Griesemer | 25dd002 | 2012-11-29 11:46:25 -0800 | [diff] [blame] | 5165 | The expression must be a function or method call; it cannot be parenthesized. |
| 5166 | Calls of built-in functions are restricted as for |
| 5167 | <a href="#Expression_statements">expression statements</a>. |
| 5168 | </p> |
| 5169 | |
| 5170 | <p> |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 5171 | The function value and parameters are |
| 5172 | <a href="#Calls">evaluated as usual</a> |
| 5173 | in the calling goroutine, but |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5174 | unlike with a regular call, program execution does not wait |
Robert Griesemer | b9f8b9c | 2008-09-26 13:38:38 -0700 | [diff] [blame] | 5175 | for the invoked function to complete. |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 5176 | Instead, the function begins executing independently |
| 5177 | in a new goroutine. |
| 5178 | When the function terminates, its goroutine also terminates. |
| 5179 | If the function has any return values, they are discarded when the |
| 5180 | function completes. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5181 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5182 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5183 | <pre> |
| 5184 | go Server() |
Brad Fitzpatrick | e963510 | 2017-05-04 02:39:56 +0000 | [diff] [blame] | 5185 | go func(ch chan<- bool) { for { sleep(10); ch <- true }} (c) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5186 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5187 | |
| 5188 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5189 | <h3 id="Select_statements">Select statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5190 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5191 | <p> |
Robert Griesemer | 61d8a33 | 2014-05-14 11:47:19 -0700 | [diff] [blame] | 5192 | A "select" statement chooses which of a set of possible |
| 5193 | <a href="#Send_statements">send</a> or |
| 5194 | <a href="#Receive_operator">receive</a> |
| 5195 | operations will proceed. |
| 5196 | It looks similar to a |
| 5197 | <a href="#Switch_statements">"switch"</a> statement but with the |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5198 | cases all referring to communication operations. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5199 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5200 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5201 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5202 | SelectStmt = "select" "{" { CommClause } "}" . |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 5203 | CommClause = CommCase ":" StatementList . |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 5204 | CommCase = "case" ( SendStmt | RecvStmt ) | "default" . |
Robert Griesemer | d367972 | 2013-01-18 13:59:25 -0800 | [diff] [blame] | 5205 | RecvStmt = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr . |
Robert Griesemer | c134718 | 2011-04-29 12:20:31 -0700 | [diff] [blame] | 5206 | RecvExpr = Expression . |
Russ Cox | 6143918 | 2011-01-31 17:42:10 -0500 | [diff] [blame] | 5207 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5208 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5209 | <p> |
Robert Griesemer | 61d8a33 | 2014-05-14 11:47:19 -0700 | [diff] [blame] | 5210 | A case with a RecvStmt may assign the result of a RecvExpr to one or |
| 5211 | two variables, which may be declared using a |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 5212 | <a href="#Short_variable_declarations">short variable declaration</a>. |
Robert Griesemer | 61d8a33 | 2014-05-14 11:47:19 -0700 | [diff] [blame] | 5213 | The RecvExpr must be a (possibly parenthesized) receive operation. |
| 5214 | There can be at most one default case and it may appear anywhere |
| 5215 | in the list of cases. |
| 5216 | </p> |
| 5217 | |
| 5218 | <p> |
| 5219 | Execution of a "select" statement proceeds in several steps: |
| 5220 | </p> |
| 5221 | |
| 5222 | <ol> |
| 5223 | <li> |
| 5224 | For all the cases in the statement, the channel operands of receive operations |
| 5225 | and the channel and right-hand-side expressions of send statements are |
| 5226 | evaluated exactly once, in source order, upon entering the "select" statement. |
| 5227 | The result is a set of channels to receive from or send to, |
| 5228 | and the corresponding values to send. |
| 5229 | Any side effects in that evaluation will occur irrespective of which (if any) |
| 5230 | communication operation is selected to proceed. |
| 5231 | Expressions on the left-hand side of a RecvStmt with a short variable declaration |
| 5232 | or assignment are not yet evaluated. |
| 5233 | </li> |
| 5234 | |
| 5235 | <li> |
| 5236 | If one or more of the communications can proceed, |
| 5237 | a single one that can proceed is chosen via a uniform pseudo-random selection. |
| 5238 | Otherwise, if there is a default case, that case is chosen. |
| 5239 | If there is no default case, the "select" statement blocks until |
| 5240 | at least one of the communications can proceed. |
| 5241 | </li> |
| 5242 | |
| 5243 | <li> |
| 5244 | Unless the selected case is the default case, the respective communication |
| 5245 | operation is executed. |
| 5246 | </li> |
| 5247 | |
| 5248 | <li> |
| 5249 | If the selected case is a RecvStmt with a short variable declaration or |
| 5250 | an assignment, the left-hand side expressions are evaluated and the |
| 5251 | received value (or values) are assigned. |
| 5252 | </li> |
| 5253 | |
| 5254 | <li> |
| 5255 | The statement list of the selected case is executed. |
| 5256 | </li> |
| 5257 | </ol> |
| 5258 | |
| 5259 | <p> |
| 5260 | Since communication on <code>nil</code> channels can never proceed, |
| 5261 | 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] | 5262 | </p> |
Robert Griesemer | 2902a82 | 2008-09-17 13:57:11 -0700 | [diff] [blame] | 5263 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5264 | <pre> |
Robert Griesemer | 61d8a33 | 2014-05-14 11:47:19 -0700 | [diff] [blame] | 5265 | var a []int |
| 5266 | var c, c1, c2, c3, c4 chan int |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5267 | var i1, i2 int |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5268 | select { |
| 5269 | case i1 = <-c1: |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5270 | print("received ", i1, " from c1\n") |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5271 | case c2 <- i2: |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5272 | print("sent ", i2, " to c2\n") |
Robert Griesemer | 6af887e | 2011-05-02 09:16:31 -0700 | [diff] [blame] | 5273 | case i3, ok := (<-c3): // same as: i3, ok := <-c3 |
Russ Cox | 19d9a40 | 2011-01-27 15:34:28 -0500 | [diff] [blame] | 5274 | if ok { |
| 5275 | print("received ", i3, " from c3\n") |
| 5276 | } else { |
| 5277 | print("c3 is closed\n") |
| 5278 | } |
Robert Griesemer | 61d8a33 | 2014-05-14 11:47:19 -0700 | [diff] [blame] | 5279 | case a[f()] = <-c4: |
| 5280 | // same as: |
| 5281 | // case t := <-c4 |
| 5282 | // a[f()] = t |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5283 | default: |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5284 | print("no communication\n") |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5285 | } |
| 5286 | |
| 5287 | for { // send random sequence of bits to c |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5288 | select { |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5289 | case c <- 0: // note: no statement, no fallthrough, no folding of cases |
| 5290 | case c <- 1: |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5291 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5292 | } |
Rob Pike | 041d116 | 2010-07-13 16:23:54 -0700 | [diff] [blame] | 5293 | |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 5294 | select {} // block forever |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5295 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5296 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5297 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5298 | <h3 id="Return_statements">Return statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5299 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5300 | <p> |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 5301 | A "return" statement in a function <code>F</code> terminates the execution |
| 5302 | of <code>F</code>, and optionally provides one or more result values. |
| 5303 | Any functions <a href="#Defer_statements">deferred</a> by <code>F</code> |
| 5304 | are executed before <code>F</code> returns to its caller. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5305 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5306 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5307 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5308 | ReturnStmt = "return" [ ExpressionList ] . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5309 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5310 | |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5311 | <p> |
| 5312 | In a function without a result type, a "return" statement must not |
| 5313 | specify any result values. |
| 5314 | </p> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5315 | <pre> |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5316 | func noResult() { |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5317 | return |
| 5318 | } |
| 5319 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5320 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5321 | <p> |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5322 | There are three ways to return values from a function with a result |
| 5323 | type: |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5324 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5325 | |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5326 | <ol> |
| 5327 | <li>The return value or values may be explicitly listed |
| 5328 | in the "return" statement. Each expression must be single-valued |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 5329 | and <a href="#Assignability">assignable</a> |
| 5330 | to the corresponding element of the function's result type. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5331 | <pre> |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5332 | func simpleF() int { |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5333 | return 2 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5334 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5335 | |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5336 | func complexF1() (re float64, im float64) { |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5337 | return -7.0, -4.0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5338 | } |
| 5339 | </pre> |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5340 | </li> |
| 5341 | <li>The expression list in the "return" statement may be a single |
| 5342 | call to a multi-valued function. The effect is as if each value |
| 5343 | returned from that function were assigned to a temporary |
| 5344 | variable with the type of the respective value, followed by a |
| 5345 | "return" statement listing these variables, at which point the |
| 5346 | rules of the previous case apply. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5347 | <pre> |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5348 | func complexF2() (re float64, im float64) { |
| 5349 | return complexF1() |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5350 | } |
| 5351 | </pre> |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5352 | </li> |
Peter Mundy | 5928e1d | 2010-11-09 10:10:57 -0800 | [diff] [blame] | 5353 | <li>The expression list may be empty if the function's result |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5354 | type specifies names for its <a href="#Function_types">result parameters</a>. |
Rob Pike | db8c2b18 | 2010-06-11 21:30:03 -0700 | [diff] [blame] | 5355 | The result parameters act as ordinary local variables |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5356 | and the function may assign values to them as necessary. |
| 5357 | The "return" statement returns the values of these variables. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5358 | <pre> |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5359 | func complexF3() (re float64, im float64) { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5360 | re = 7.0 |
| 5361 | im = 4.0 |
| 5362 | return |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5363 | } |
Robert Griesemer | fb64e0d | 2011-03-07 16:29:07 -0800 | [diff] [blame] | 5364 | |
Russ Cox | d9877e2 | 2011-11-01 21:45:02 -0400 | [diff] [blame] | 5365 | func (devnull) Write(p []byte) (n int, _ error) { |
Robert Griesemer | fb64e0d | 2011-03-07 16:29:07 -0800 | [diff] [blame] | 5366 | n = len(p) |
| 5367 | return |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 5368 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5369 | </pre> |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5370 | </li> |
| 5371 | </ol> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5372 | |
Rob Pike | db8c2b18 | 2010-06-11 21:30:03 -0700 | [diff] [blame] | 5373 | <p> |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5374 | Regardless of how they are declared, all the result values are initialized to |
| 5375 | 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] | 5376 | function. A "return" statement that specifies results sets the result parameters before |
| 5377 | any deferred functions are executed. |
Rob Pike | db8c2b18 | 2010-06-11 21:30:03 -0700 | [diff] [blame] | 5378 | </p> |
| 5379 | |
Robert Griesemer | c97778f | 2014-03-05 11:59:53 -0800 | [diff] [blame] | 5380 | <p> |
| 5381 | Implementation restriction: A compiler may disallow an empty expression list |
| 5382 | in a "return" statement if a different entity (constant, type, or variable) |
| 5383 | with the same name as a result parameter is in |
| 5384 | <a href="#Declarations_and_scope">scope</a> at the place of the return. |
| 5385 | </p> |
| 5386 | |
| 5387 | <pre> |
| 5388 | func f(n int) (res int, err error) { |
| 5389 | if _, err := f(n-1); err != nil { |
| 5390 | return // invalid return statement: err is shadowed |
| 5391 | } |
| 5392 | return |
| 5393 | } |
| 5394 | </pre> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 5395 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5396 | <h3 id="Break_statements">Break statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5397 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5398 | <p> |
| 5399 | A "break" statement terminates execution of the innermost |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5400 | <a href="#For_statements">"for"</a>, |
| 5401 | <a href="#Switch_statements">"switch"</a>, or |
Robert Griesemer | 94849d5 | 2014-05-28 08:43:47 -0700 | [diff] [blame] | 5402 | <a href="#Select_statements">"select"</a> statement |
| 5403 | within the same function. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5404 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5405 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5406 | <pre class="ebnf"> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5407 | BreakStmt = "break" [ Label ] . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5408 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5409 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5410 | <p> |
| 5411 | If there is a label, it must be that of an enclosing |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5412 | "for", "switch", or "select" statement, |
| 5413 | and that is the one whose execution terminates. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5414 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5415 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5416 | <pre> |
Rob Pike | cec0954 | 2013-09-17 07:41:11 +1000 | [diff] [blame] | 5417 | OuterLoop: |
| 5418 | for i = 0; i < n; i++ { |
| 5419 | for j = 0; j < m; j++ { |
| 5420 | switch a[i][j] { |
| 5421 | case nil: |
| 5422 | state = Error |
| 5423 | break OuterLoop |
| 5424 | case item: |
| 5425 | state = Found |
| 5426 | break OuterLoop |
| 5427 | } |
Russ Cox | 108564d | 2011-03-15 13:51:24 -0400 | [diff] [blame] | 5428 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5429 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5430 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5431 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5432 | <h3 id="Continue_statements">Continue statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5433 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5434 | <p> |
| 5435 | A "continue" statement begins the next iteration of the |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5436 | innermost <a href="#For_statements">"for" loop</a> at its post statement. |
Robert Griesemer | 94849d5 | 2014-05-28 08:43:47 -0700 | [diff] [blame] | 5437 | The "for" loop must be within the same function. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5438 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5439 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5440 | <pre class="ebnf"> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5441 | ContinueStmt = "continue" [ Label ] . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5442 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5443 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5444 | <p> |
Rob Pike | de921996 | 2010-04-28 13:18:40 -0700 | [diff] [blame] | 5445 | If there is a label, it must be that of an enclosing |
| 5446 | "for" statement, and that is the one whose execution |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5447 | advances. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5448 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5449 | |
Rob Pike | cec0954 | 2013-09-17 07:41:11 +1000 | [diff] [blame] | 5450 | <pre> |
| 5451 | RowLoop: |
| 5452 | for y, row := range rows { |
| 5453 | for x, data := range row { |
| 5454 | if data == endOfRow { |
| 5455 | continue RowLoop |
| 5456 | } |
| 5457 | row[x] = data + bias(x, y) |
| 5458 | } |
| 5459 | } |
| 5460 | </pre> |
| 5461 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5462 | <h3 id="Goto_statements">Goto statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5463 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5464 | <p> |
Robert Griesemer | 94849d5 | 2014-05-28 08:43:47 -0700 | [diff] [blame] | 5465 | A "goto" statement transfers control to the statement with the corresponding label |
| 5466 | within the same function. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5467 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5468 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5469 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5470 | GotoStmt = "goto" Label . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5471 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5472 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5473 | <pre> |
| 5474 | goto Error |
| 5475 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5476 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5477 | <p> |
| 5478 | Executing the "goto" statement must not cause any variables to come into |
Russ Cox | f4c7db0 | 2011-06-17 12:49:04 -0400 | [diff] [blame] | 5479 | <a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto. |
| 5480 | For instance, this example: |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5481 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5482 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5483 | <pre> |
Russ Cox | 108564d | 2011-03-15 13:51:24 -0400 | [diff] [blame] | 5484 | goto L // BAD |
| 5485 | v := 3 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5486 | L: |
| 5487 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5488 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5489 | <p> |
| 5490 | is erroneous because the jump to label <code>L</code> skips |
| 5491 | the creation of <code>v</code>. |
Russ Cox | f4c7db0 | 2011-06-17 12:49:04 -0400 | [diff] [blame] | 5492 | </p> |
| 5493 | |
| 5494 | <p> |
| 5495 | A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block. |
| 5496 | For instance, this example: |
| 5497 | </p> |
| 5498 | |
| 5499 | <pre> |
| 5500 | if n%2 == 1 { |
| 5501 | goto L1 |
| 5502 | } |
| 5503 | for n > 0 { |
| 5504 | f() |
| 5505 | n-- |
| 5506 | L1: |
| 5507 | f() |
| 5508 | n-- |
| 5509 | } |
| 5510 | </pre> |
| 5511 | |
| 5512 | <p> |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 5513 | is erroneous because the label <code>L1</code> is inside |
Russ Cox | f4c7db0 | 2011-06-17 12:49:04 -0400 | [diff] [blame] | 5514 | the "for" statement's block but the <code>goto</code> is not. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5515 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5516 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5517 | <h3 id="Fallthrough_statements">Fallthrough statements</h3> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 5518 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5519 | <p> |
| 5520 | A "fallthrough" statement transfers control to the first statement of the |
Shenghou Ma | ca9876d | 2015-12-31 11:25:51 -0500 | [diff] [blame] | 5521 | 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] | 5522 | 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] | 5523 | </p> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 5524 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5525 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5526 | FallthroughStmt = "fallthrough" . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5527 | </pre> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 5528 | |
| 5529 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5530 | <h3 id="Defer_statements">Defer statements</h3> |
Robert Griesemer | 4a903e0 | 2009-01-27 09:29:40 -0800 | [diff] [blame] | 5531 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5532 | <p> |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 5533 | A "defer" statement invokes a function whose execution is deferred |
| 5534 | to the moment the surrounding function returns, either because the |
| 5535 | surrounding function executed a <a href="#Return_statements">return statement</a>, |
| 5536 | reached the end of its <a href="#Function_declarations">function body</a>, |
| 5537 | or because the corresponding goroutine is <a href="#Handling_panics">panicking</a>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5538 | </p> |
Robert Griesemer | 4a903e0 | 2009-01-27 09:29:40 -0800 | [diff] [blame] | 5539 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5540 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5541 | DeferStmt = "defer" Expression . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5542 | </pre> |
Robert Griesemer | 4a903e0 | 2009-01-27 09:29:40 -0800 | [diff] [blame] | 5543 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5544 | <p> |
Robert Griesemer | 25dd002 | 2012-11-29 11:46:25 -0800 | [diff] [blame] | 5545 | The expression must be a function or method call; it cannot be parenthesized. |
| 5546 | Calls of built-in functions are restricted as for |
| 5547 | <a href="#Expression_statements">expression statements</a>. |
| 5548 | </p> |
| 5549 | |
| 5550 | <p> |
Robert Griesemer | b4eb22d | 2014-09-19 13:32:07 -0700 | [diff] [blame] | 5551 | Each time a "defer" statement |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 5552 | executes, the function value and parameters to the call are |
| 5553 | <a href="#Calls">evaluated as usual</a> |
Robert Griesemer | b4eb22d | 2014-09-19 13:32:07 -0700 | [diff] [blame] | 5554 | and saved anew but the actual function is not invoked. |
| 5555 | Instead, deferred functions are invoked immediately before |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 5556 | the surrounding function returns, in the reverse order |
Robert Griesemer | 206fd78 | 2018-09-21 21:03:35 -0700 | [diff] [blame] | 5557 | they were deferred. That is, if the surrounding function |
| 5558 | returns through an explicit <a href="#Return_statements">return statement</a>, |
| 5559 | deferred functions are executed <i>after</i> any result parameters are set |
| 5560 | 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] | 5561 | If a deferred function value evaluates |
| 5562 | to <code>nil</code>, execution <a href="#Handling_panics">panics</a> |
Rob Pike | 651bb8e | 2014-09-19 14:13:51 -0700 | [diff] [blame] | 5563 | when the function is invoked, not when the "defer" statement is executed. |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 5564 | </p> |
| 5565 | |
| 5566 | <p> |
| 5567 | For instance, if the deferred function is |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 5568 | a <a href="#Function_literals">function literal</a> and the surrounding |
Robert Griesemer | 48f0cd2 | 2010-03-23 17:30:14 -0700 | [diff] [blame] | 5569 | function has <a href="#Function_types">named result parameters</a> that |
| 5570 | are in scope within the literal, the deferred function may access and modify |
| 5571 | the result parameters before they are returned. |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 5572 | If the deferred function has any return values, they are discarded when |
| 5573 | the function completes. |
Rob Pike | 15970c8 | 2012-10-16 11:27:20 +1100 | [diff] [blame] | 5574 | (See also the section on <a href="#Handling_panics">handling panics</a>.) |
| 5575 | </p> |
| 5576 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5577 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5578 | lock(l) |
| 5579 | defer unlock(l) // unlocking happens before surrounding function returns |
Robert Griesemer | 4a903e0 | 2009-01-27 09:29:40 -0800 | [diff] [blame] | 5580 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5581 | // prints 3 2 1 0 before surrounding function returns |
| 5582 | for i := 0; i <= 3; i++ { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5583 | defer fmt.Print(i) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5584 | } |
Robert Griesemer | 48f0cd2 | 2010-03-23 17:30:14 -0700 | [diff] [blame] | 5585 | |
Robert Griesemer | 206fd78 | 2018-09-21 21:03:35 -0700 | [diff] [blame] | 5586 | // f returns 42 |
Robert Griesemer | 48f0cd2 | 2010-03-23 17:30:14 -0700 | [diff] [blame] | 5587 | func f() (result int) { |
| 5588 | defer func() { |
Robert Griesemer | 206fd78 | 2018-09-21 21:03:35 -0700 | [diff] [blame] | 5589 | // result is accessed after it was set to 6 by the return statement |
| 5590 | result *= 7 |
Robert Griesemer | 48f0cd2 | 2010-03-23 17:30:14 -0700 | [diff] [blame] | 5591 | }() |
Robert Griesemer | 206fd78 | 2018-09-21 21:03:35 -0700 | [diff] [blame] | 5592 | return 6 |
Robert Griesemer | 48f0cd2 | 2010-03-23 17:30:14 -0700 | [diff] [blame] | 5593 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5594 | </pre> |
Robert Griesemer | 4a903e0 | 2009-01-27 09:29:40 -0800 | [diff] [blame] | 5595 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5596 | <h2 id="Built-in_functions">Built-in functions</h2> |
| 5597 | |
| 5598 | <p> |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 5599 | Built-in functions are |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5600 | <a href="#Predeclared_identifiers">predeclared</a>. |
| 5601 | They are called like any other function but some of them |
| 5602 | accept a type instead of an expression as the first argument. |
| 5603 | </p> |
| 5604 | |
Russ Cox | 2a5f0c6 | 2009-12-04 10:23:12 -0800 | [diff] [blame] | 5605 | <p> |
| 5606 | The built-in functions do not have standard Go types, |
| 5607 | so they can only appear in <a href="#Calls">call expressions</a>; |
| 5608 | they cannot be used as function values. |
| 5609 | </p> |
| 5610 | |
Russ Cox | 9f2cb86 | 2011-03-11 14:47:02 -0500 | [diff] [blame] | 5611 | <h3 id="Close">Close</h3> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5612 | |
| 5613 | <p> |
Robert Griesemer | dc60c5a | 2010-07-14 16:09:22 -0700 | [diff] [blame] | 5614 | 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] | 5615 | records that no more values will be sent on the channel. |
| 5616 | It is an error if <code>c</code> is a receive-only channel. |
| 5617 | Sending to or closing a closed channel causes a <a href="#Run_time_panics">run-time panic</a>. |
| 5618 | 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] | 5619 | After calling <code>close</code>, and after any previously |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5620 | sent values have been received, receive operations will return |
Robert Griesemer | dc60c5a | 2010-07-14 16:09:22 -0700 | [diff] [blame] | 5621 | the zero value for the channel's type without blocking. |
Russ Cox | 9f2cb86 | 2011-03-11 14:47:02 -0500 | [diff] [blame] | 5622 | The multi-valued <a href="#Receive_operator">receive operation</a> |
| 5623 | 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] | 5624 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5625 | |
Robert Griesemer | dc60c5a | 2010-07-14 16:09:22 -0700 | [diff] [blame] | 5626 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5627 | <h3 id="Length_and_capacity">Length and capacity</h3> |
Robert Griesemer | 7a4ed4f | 2008-09-03 15:15:51 -0700 | [diff] [blame] | 5628 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5629 | <p> |
| 5630 | The built-in functions <code>len</code> and <code>cap</code> take arguments |
| 5631 | of various types and return a result of type <code>int</code>. |
| 5632 | The implementation guarantees that the result always fits into an <code>int</code>. |
| 5633 | </p> |
| 5634 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 5635 | <pre class="grammar"> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5636 | Call Argument type Result |
Robert Griesemer | 7a4ed4f | 2008-09-03 15:15:51 -0700 | [diff] [blame] | 5637 | |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5638 | len(s) string type string length in bytes |
| 5639 | [n]T, *[n]T array length (== n) |
| 5640 | []T slice length |
| 5641 | map[K]T map length (number of defined keys) |
| 5642 | chan T number of elements queued in channel buffer |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 5643 | |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5644 | cap(s) [n]T, *[n]T array length (== n) |
| 5645 | []T slice capacity |
| 5646 | chan T channel buffer capacity |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5647 | </pre> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 5648 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5649 | <p> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5650 | The capacity of a slice is the number of elements for which there is |
| 5651 | space allocated in the underlying array. |
| 5652 | At any time the following relationship holds: |
| 5653 | </p> |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5654 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5655 | <pre> |
Anthony Martin | 0122a66 | 2011-02-08 14:51:15 -0800 | [diff] [blame] | 5656 | 0 <= len(s) <= cap(s) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5657 | </pre> |
Robert Griesemer | 667ef6c | 2008-09-10 13:00:32 -0700 | [diff] [blame] | 5658 | |
Russ Cox | f442918 | 2010-07-01 17:49:47 -0700 | [diff] [blame] | 5659 | <p> |
Shenghou Ma | a0b5b46 | 2013-01-22 03:18:20 +0800 | [diff] [blame] | 5660 | 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] | 5661 | The capacity of a <code>nil</code> slice or channel is 0. |
Robert Griesemer | 0c2e6b3 | 2010-07-13 11:54:57 -0700 | [diff] [blame] | 5662 | </p> |
| 5663 | |
| 5664 | <p> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5665 | The expression <code>len(s)</code> is <a href="#Constants">constant</a> if |
| 5666 | <code>s</code> is a string constant. The expressions <code>len(s)</code> and |
| 5667 | <code>cap(s)</code> are constants if the type of <code>s</code> is an array |
| 5668 | 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] | 5669 | <a href="#Receive_operator">channel receives</a> or (non-constant) |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5670 | <a href="#Calls">function calls</a>; in this case <code>s</code> is not evaluated. |
| 5671 | Otherwise, invocations of <code>len</code> and <code>cap</code> are not |
| 5672 | constant and <code>s</code> is evaluated. |
Russ Cox | f442918 | 2010-07-01 17:49:47 -0700 | [diff] [blame] | 5673 | </p> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 5674 | |
Robert Griesemer | 8716981 | 2014-03-03 20:07:34 -0800 | [diff] [blame] | 5675 | <pre> |
| 5676 | const ( |
| 5677 | c1 = imag(2i) // imag(2i) = 2.0 is a constant |
| 5678 | c2 = len([10]float64{2}) // [10]float64{2} contains no function calls |
| 5679 | c3 = len([10]float64{c1}) // [10]float64{c1} contains no function calls |
| 5680 | c4 = len([10]float64{imag(2i)}) // imag(2i) is a constant and no function call is issued |
Shenghou Ma | c0abdd9 | 2014-12-26 02:50:33 -0500 | [diff] [blame] | 5681 | 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] | 5682 | ) |
| 5683 | var z complex128 |
| 5684 | </pre> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5685 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5686 | <h3 id="Allocation">Allocation</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5687 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5688 | <p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 5689 | The built-in function <code>new</code> takes a type <code>T</code>, |
| 5690 | allocates storage for a <a href="#Variables">variable</a> of that type |
| 5691 | at run time, and returns a value of type <code>*T</code> |
| 5692 | <a href="#Pointer_types">pointing</a> to it. |
| 5693 | The variable is initialized as described in the section on |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5694 | <a href="#The_zero_value">initial values</a>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5695 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5696 | |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5697 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5698 | new(T) |
| 5699 | </pre> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 5700 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5701 | <p> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 5702 | For instance |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5703 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5704 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5705 | <pre> |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 5706 | type S struct { a int; b float64 } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5707 | new(S) |
| 5708 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5709 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5710 | <p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 5711 | allocates storage for a variable of type <code>S</code>, |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5712 | initializes it (<code>a=0</code>, <code>b=0.0</code>), |
| 5713 | and returns a value of type <code>*S</code> containing the address |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 5714 | of the location. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5715 | </p> |
| 5716 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5717 | <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] | 5718 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5719 | <p> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5720 | The built-in function <code>make</code> takes a type <code>T</code>, |
| 5721 | which must be a slice, map or channel type, |
| 5722 | optionally followed by a type-specific list of expressions. |
| 5723 | 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] | 5724 | The memory is initialized as described in the section on |
| 5725 | <a href="#The_zero_value">initial values</a>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5726 | </p> |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5727 | |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5728 | <pre class="grammar"> |
Robert Griesemer | df674ff | 2010-05-04 17:31:40 -0700 | [diff] [blame] | 5729 | Call Type T Result |
| 5730 | |
| 5731 | make(T, n) slice slice of type T with length n and capacity n |
| 5732 | make(T, n, m) slice slice of type T with length n and capacity m |
| 5733 | |
| 5734 | make(T) map map of type T |
Robert Griesemer | b0e5a0c | 2017-04-11 16:10:09 -0700 | [diff] [blame] | 5735 | 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] | 5736 | |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 5737 | make(T) channel unbuffered channel of type T |
| 5738 | make(T, n) channel buffered channel of type T, buffer size n |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5739 | </pre> |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5740 | |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5741 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5742 | <p> |
griesemer | 9690d24 | 2017-08-30 15:10:12 +0200 | [diff] [blame] | 5743 | Each of the size arguments <code>n</code> and <code>m</code> must be of integer type |
| 5744 | or an untyped <a href="#Constants">constant</a>. |
| 5745 | A constant size argument must be non-negative and <a href="#Representability">representable</a> |
| 5746 | 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] | 5747 | 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] | 5748 | <code>n</code> must be no larger than <code>m</code>. |
| 5749 | If <code>n</code> is negative or larger than <code>m</code> at run time, |
| 5750 | a <a href="#Run_time_panics">run-time panic</a> occurs. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5751 | </p> |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5752 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5753 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 5754 | 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] | 5755 | s := make([]int, 1e3) // slice with len(s) == cap(s) == 1000 |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 5756 | 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] | 5757 | s := make([]int, 10, 0) // illegal: len(s) > cap(s) |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 5758 | c := make(chan int, 10) // channel with a buffer size of 10 |
Robert Griesemer | b0e5a0c | 2017-04-11 16:10:09 -0700 | [diff] [blame] | 5759 | 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] | 5760 | </pre> |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5761 | |
Robert Griesemer | b0e5a0c | 2017-04-11 16:10:09 -0700 | [diff] [blame] | 5762 | <p> |
| 5763 | Calling <code>make</code> with a map type and size hint <code>n</code> will |
| 5764 | create a map with initial space to hold <code>n</code> map elements. |
| 5765 | The precise behavior is implementation-dependent. |
| 5766 | </p> |
| 5767 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5768 | |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 5769 | <h3 id="Appending_and_copying_slices">Appending to and copying slices</h3> |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5770 | |
| 5771 | <p> |
Robert Griesemer | 0c49471 | 2012-09-28 15:55:38 -0700 | [diff] [blame] | 5772 | The built-in functions <code>append</code> and <code>copy</code> assist in |
| 5773 | common slice operations. |
| 5774 | For both functions, the result is independent of whether the memory referenced |
| 5775 | by the arguments overlaps. |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 5776 | </p> |
| 5777 | |
| 5778 | <p> |
Robert Griesemer | 95b8137 | 2011-06-12 12:09:50 -0700 | [diff] [blame] | 5779 | The <a href="#Function_types">variadic</a> function <code>append</code> |
| 5780 | appends zero or more values <code>x</code> |
Robert Griesemer | 0f7acf1 | 2011-04-19 14:38:49 -0700 | [diff] [blame] | 5781 | to <code>s</code> of type <code>S</code>, which must be a slice type, and |
| 5782 | returns the resulting slice, also of type <code>S</code>. |
Robert Griesemer | 95b8137 | 2011-06-12 12:09:50 -0700 | [diff] [blame] | 5783 | The values <code>x</code> are passed to a parameter of type <code>...T</code> |
| 5784 | where <code>T</code> is the <a href="#Slice_types">element type</a> of |
| 5785 | <code>S</code> and the respective |
| 5786 | <a href="#Passing_arguments_to_..._parameters">parameter passing rules</a> apply. |
Luuk van Dijk | 77fac21 | 2011-10-12 15:59:23 +0200 | [diff] [blame] | 5787 | As a special case, <code>append</code> also accepts a first argument |
| 5788 | assignable to type <code>[]byte</code> with a second argument of |
| 5789 | string type followed by <code>...</code>. This form appends the |
| 5790 | bytes of the string. |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 5791 | </p> |
| 5792 | |
| 5793 | <pre class="grammar"> |
Robert Griesemer | 0f7acf1 | 2011-04-19 14:38:49 -0700 | [diff] [blame] | 5794 | 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] | 5795 | </pre> |
| 5796 | |
| 5797 | <p> |
| 5798 | 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] | 5799 | values, <code>append</code> allocates a new, sufficiently large underlying |
| 5800 | array that fits both the existing slice elements and the additional values. |
| 5801 | Otherwise, <code>append</code> re-uses the underlying array. |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 5802 | </p> |
| 5803 | |
| 5804 | <pre> |
| 5805 | s0 := []int{0, 0} |
Robert Griesemer | 0c49471 | 2012-09-28 15:55:38 -0700 | [diff] [blame] | 5806 | s1 := append(s0, 2) // append a single element s1 == []int{0, 0, 2} |
| 5807 | s2 := append(s1, 3, 5, 7) // append multiple elements s2 == []int{0, 0, 2, 3, 5, 7} |
| 5808 | s3 := append(s2, s0...) // append a slice s3 == []int{0, 0, 2, 3, 5, 7, 0, 0} |
| 5809 | 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] | 5810 | |
| 5811 | var t []interface{} |
David Symonds | 583b29c | 2014-12-04 09:29:29 +1100 | [diff] [blame] | 5812 | 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] | 5813 | |
| 5814 | var b []byte |
Robert Griesemer | 0c49471 | 2012-09-28 15:55:38 -0700 | [diff] [blame] | 5815 | b = append(b, "bar"...) // append string contents b == []byte{'b', 'a', 'r' } |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 5816 | </pre> |
| 5817 | |
| 5818 | <p> |
| 5819 | The function <code>copy</code> copies slice elements from |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5820 | 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] | 5821 | number of elements copied. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 5822 | 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] | 5823 | <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] | 5824 | The number of elements copied is the minimum of |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5825 | <code>len(src)</code> and <code>len(dst)</code>. |
Robert Griesemer | 425bbad | 2010-10-25 16:41:06 -0700 | [diff] [blame] | 5826 | As a special case, <code>copy</code> also accepts a destination argument assignable |
| 5827 | to type <code>[]byte</code> with a source argument of a string type. |
| 5828 | This form copies the bytes from the string into the byte slice. |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5829 | </p> |
| 5830 | |
| 5831 | <pre class="grammar"> |
| 5832 | copy(dst, src []T) int |
Robert Griesemer | 425bbad | 2010-10-25 16:41:06 -0700 | [diff] [blame] | 5833 | copy(dst []byte, src string) int |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5834 | </pre> |
| 5835 | |
| 5836 | <p> |
| 5837 | Examples: |
| 5838 | </p> |
| 5839 | |
| 5840 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5841 | var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7} |
| 5842 | var s = make([]int, 6) |
Robert Griesemer | 425bbad | 2010-10-25 16:41:06 -0700 | [diff] [blame] | 5843 | var b = make([]byte, 5) |
| 5844 | n1 := copy(s, a[0:]) // n1 == 6, s == []int{0, 1, 2, 3, 4, 5} |
| 5845 | n2 := copy(s, s[2:]) // n2 == 4, s == []int{2, 3, 4, 5, 4, 5} |
| 5846 | n3 := copy(b, "Hello, World!") // n3 == 5, b == []byte("Hello") |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5847 | </pre> |
| 5848 | |
Robert Griesemer | 3e0c0a8 | 2011-10-17 12:53:10 -0700 | [diff] [blame] | 5849 | |
| 5850 | <h3 id="Deletion_of_map_elements">Deletion of map elements</h3> |
| 5851 | |
| 5852 | <p> |
| 5853 | The built-in function <code>delete</code> removes the element with key |
| 5854 | <code>k</code> from a <a href="#Map_types">map</a> <code>m</code>. The |
| 5855 | type of <code>k</code> must be <a href="#Assignability">assignable</a> |
| 5856 | to the key type of <code>m</code>. |
| 5857 | </p> |
| 5858 | |
| 5859 | <pre class="grammar"> |
| 5860 | delete(m, k) // remove element m[k] from map m |
| 5861 | </pre> |
| 5862 | |
| 5863 | <p> |
Robert Griesemer | a9a49fe | 2012-12-12 13:08:35 -0800 | [diff] [blame] | 5864 | If the map <code>m</code> is <code>nil</code> or the element <code>m[k]</code> |
| 5865 | does not exist, <code>delete</code> is a no-op. |
Robert Griesemer | 3e0c0a8 | 2011-10-17 12:53:10 -0700 | [diff] [blame] | 5866 | </p> |
| 5867 | |
| 5868 | |
Russ Cox | 0201e37 | 2012-02-29 15:20:11 -0500 | [diff] [blame] | 5869 | <h3 id="Complex_numbers">Manipulating complex numbers</h3> |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 5870 | |
| 5871 | <p> |
| 5872 | Three functions assemble and disassemble complex numbers. |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 5873 | The built-in function <code>complex</code> constructs a complex |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 5874 | value from a floating-point real and imaginary part, while |
| 5875 | <code>real</code> and <code>imag</code> |
| 5876 | extract the real and imaginary parts of a complex value. |
| 5877 | </p> |
| 5878 | |
| 5879 | <pre class="grammar"> |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 5880 | complex(realPart, imaginaryPart floatT) complexT |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 5881 | real(complexT) floatT |
| 5882 | imag(complexT) floatT |
| 5883 | </pre> |
| 5884 | |
| 5885 | <p> |
| 5886 | The type of the arguments and return value correspond. |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 5887 | For <code>complex</code>, the two arguments must be of the same |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 5888 | floating-point type and the return type is the complex type |
| 5889 | with the corresponding floating-point constituents: |
Robert Griesemer | 98aa822 | 2015-07-29 15:42:04 -0700 | [diff] [blame] | 5890 | <code>complex64</code> for <code>float32</code> arguments, and |
| 5891 | <code>complex128</code> for <code>float64</code> arguments. |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 5892 | 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] | 5893 | <a href="#Conversions">converted</a> to the type of the other argument. |
| 5894 | If both arguments evaluate to untyped constants, they must be non-complex |
| 5895 | numbers or their imaginary parts must be zero, and the return value of |
| 5896 | the function is an untyped complex constant. |
| 5897 | </p> |
| 5898 | |
| 5899 | <p> |
| 5900 | For <code>real</code> and <code>imag</code>, the argument must be |
| 5901 | of complex type, and the return type is the corresponding floating-point |
| 5902 | type: <code>float32</code> for a <code>complex64</code> argument, and |
| 5903 | <code>float64</code> for a <code>complex128</code> argument. |
| 5904 | If the argument evaluates to an untyped constant, it must be a number, |
| 5905 | and the return value of the function is an untyped floating-point constant. |
| 5906 | </p> |
| 5907 | |
| 5908 | <p> |
| 5909 | The <code>real</code> and <code>imag</code> functions together form the inverse of |
| 5910 | <code>complex</code>, so for a value <code>z</code> of a complex type <code>Z</code>, |
| 5911 | <code>z == Z(complex(real(z), imag(z)))</code>. |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 5912 | </p> |
| 5913 | |
| 5914 | <p> |
| 5915 | If the operands of these functions are all constants, the return |
| 5916 | value is a constant. |
| 5917 | </p> |
| 5918 | |
| 5919 | <pre> |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 5920 | var a = complex(2, -2) // complex128 |
Robert Griesemer | 98aa822 | 2015-07-29 15:42:04 -0700 | [diff] [blame] | 5921 | 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] | 5922 | x := float32(math.Cos(math.Pi/2)) // float32 |
| 5923 | var c64 = complex(5, -x) // complex64 |
Robert Griesemer | 5567b87 | 2016-10-14 11:27:11 -0700 | [diff] [blame] | 5924 | var s uint = complex(1, 0) // untyped complex constant 1 + 0i can be converted to uint |
| 5925 | _ = complex(1, 2<<s) // illegal: 2 assumes floating-point type, cannot shift |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 5926 | var rl = real(c64) // float32 |
Robert Griesemer | 98aa822 | 2015-07-29 15:42:04 -0700 | [diff] [blame] | 5927 | var im = imag(a) // float64 |
| 5928 | const c = imag(b) // untyped constant -1.4 |
Robert Griesemer | 5567b87 | 2016-10-14 11:27:11 -0700 | [diff] [blame] | 5929 | _ = imag(3 << s) // illegal: 3 assumes complex type, cannot shift |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 5930 | </pre> |
| 5931 | |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 5932 | <h3 id="Handling_panics">Handling panics</h3> |
| 5933 | |
| 5934 | <p> Two built-in functions, <code>panic</code> and <code>recover</code>, |
| 5935 | 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] | 5936 | and program-defined error conditions. |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 5937 | </p> |
| 5938 | |
| 5939 | <pre class="grammar"> |
| 5940 | func panic(interface{}) |
| 5941 | func recover() interface{} |
| 5942 | </pre> |
| 5943 | |
| 5944 | <p> |
Rob Pike | c34050f | 2013-03-12 14:28:16 -0700 | [diff] [blame] | 5945 | While executing a function <code>F</code>, |
| 5946 | an explicit call to <code>panic</code> or a <a href="#Run_time_panics">run-time panic</a> |
| 5947 | terminates the execution of <code>F</code>. |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 5948 | Any functions <a href="#Defer_statements">deferred</a> by <code>F</code> |
Rob Pike | c34050f | 2013-03-12 14:28:16 -0700 | [diff] [blame] | 5949 | are then executed as usual. |
| 5950 | Next, any deferred functions run by <code>F's</code> caller are run, |
| 5951 | and so on up to any deferred by the top-level function in the executing goroutine. |
| 5952 | At that point, the program is terminated and the error |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 5953 | condition is reported, including the value of the argument to <code>panic</code>. |
| 5954 | This termination sequence is called <i>panicking</i>. |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 5955 | </p> |
| 5956 | |
Robert Griesemer | 76f3228 | 2011-02-04 08:43:21 -0800 | [diff] [blame] | 5957 | <pre> |
| 5958 | panic(42) |
| 5959 | panic("unreachable") |
| 5960 | panic(Error("cannot parse")) |
| 5961 | </pre> |
| 5962 | |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 5963 | <p> |
| 5964 | The <code>recover</code> function allows a program to manage behavior |
Rob Pike | c34050f | 2013-03-12 14:28:16 -0700 | [diff] [blame] | 5965 | of a panicking goroutine. |
| 5966 | Suppose a function <code>G</code> defers a function <code>D</code> that calls |
| 5967 | <code>recover</code> and a panic occurs in a function on the same goroutine in which <code>G</code> |
| 5968 | is executing. |
| 5969 | When the running of deferred functions reaches <code>D</code>, |
| 5970 | 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>. |
| 5971 | If <code>D</code> returns normally, without starting a new |
| 5972 | <code>panic</code>, the panicking sequence stops. In that case, |
| 5973 | the state of functions called between <code>G</code> and the call to <code>panic</code> |
| 5974 | is discarded, and normal execution resumes. |
| 5975 | Any functions deferred by <code>G</code> before <code>D</code> are then run and <code>G</code>'s |
| 5976 | execution terminates by returning to its caller. |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 5977 | </p> |
| 5978 | |
| 5979 | <p> |
Rob Pike | c34050f | 2013-03-12 14:28:16 -0700 | [diff] [blame] | 5980 | The return value of <code>recover</code> is <code>nil</code> if any of the following conditions holds: |
| 5981 | </p> |
| 5982 | <ul> |
| 5983 | <li> |
| 5984 | <code>panic</code>'s argument was <code>nil</code>; |
| 5985 | </li> |
| 5986 | <li> |
| 5987 | the goroutine is not panicking; |
| 5988 | </li> |
| 5989 | <li> |
| 5990 | <code>recover</code> was not called directly by a deferred function. |
| 5991 | </li> |
| 5992 | </ul> |
| 5993 | |
| 5994 | <p> |
Robert Griesemer | 76f3228 | 2011-02-04 08:43:21 -0800 | [diff] [blame] | 5995 | The <code>protect</code> function in the example below invokes |
| 5996 | the function argument <code>g</code> and protects callers from |
| 5997 | run-time panics raised by <code>g</code>. |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 5998 | </p> |
| 5999 | |
| 6000 | <pre> |
Robert Griesemer | 76f3228 | 2011-02-04 08:43:21 -0800 | [diff] [blame] | 6001 | func protect(g func()) { |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6002 | defer func() { |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 6003 | log.Println("done") // Println executes normally even if there is a panic |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6004 | if x := recover(); x != nil { |
Rob Pike | 966bf71 | 2011-03-01 13:54:22 -0800 | [diff] [blame] | 6005 | log.Printf("run time panic: %v", x) |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6006 | } |
Rob Pike | e6b1d42 | 2011-04-05 11:01:25 -0700 | [diff] [blame] | 6007 | }() |
Robert Griesemer | 76f3228 | 2011-02-04 08:43:21 -0800 | [diff] [blame] | 6008 | log.Println("start") |
| 6009 | g() |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6010 | } |
| 6011 | </pre> |
| 6012 | |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 6013 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 6014 | <h3 id="Bootstrapping">Bootstrapping</h3> |
| 6015 | |
Robert Griesemer | 5eb3624 | 2009-09-16 11:05:14 -0700 | [diff] [blame] | 6016 | <p> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 6017 | Current implementations provide several built-in functions useful during |
| 6018 | bootstrapping. These functions are documented for completeness but are not |
| 6019 | guaranteed to stay in the language. They do not return a result. |
Robert Griesemer | 5eb3624 | 2009-09-16 11:05:14 -0700 | [diff] [blame] | 6020 | </p> |
| 6021 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 6022 | <pre class="grammar"> |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 6023 | Function Behavior |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 6024 | |
| 6025 | print prints all arguments; formatting of arguments is implementation-specific |
| 6026 | 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] | 6027 | </pre> |
| 6028 | |
Robert Griesemer | 50f67ad | 2017-04-27 17:54:49 -0700 | [diff] [blame] | 6029 | <p> |
| 6030 | Implementation restriction: <code>print</code> and <code>println</code> need not |
| 6031 | accept arbitrary argument types, but printing of boolean, numeric, and string |
Robert Griesemer | 86f5f7f | 2017-04-28 10:32:31 -0700 | [diff] [blame] | 6032 | <a href="#Types">types</a> must be supported. |
Robert Griesemer | 50f67ad | 2017-04-27 17:54:49 -0700 | [diff] [blame] | 6033 | </p> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 6034 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6035 | <h2 id="Packages">Packages</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6036 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6037 | <p> |
| 6038 | Go programs are constructed by linking together <i>packages</i>. |
Robert Griesemer | 326ef13 | 2009-09-28 19:21:15 -0700 | [diff] [blame] | 6039 | A package in turn is constructed from one or more source files |
| 6040 | that together declare constants, types, variables and functions |
| 6041 | belonging to the package and which are accessible in all files |
| 6042 | of the same package. Those elements may be |
| 6043 | <a href="#Exported_identifiers">exported</a> and used in another package. |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6044 | </p> |
| 6045 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6046 | <h3 id="Source_file_organization">Source file organization</h3> |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6047 | |
| 6048 | <p> |
| 6049 | Each source file consists of a package clause defining the package |
| 6050 | to which it belongs, followed by a possibly empty set of import |
| 6051 | declarations that declare packages whose contents it wishes to use, |
| 6052 | followed by a possibly empty set of declarations of functions, |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 6053 | types, variables, and constants. |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6054 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6055 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 6056 | <pre class="ebnf"> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6057 | SourceFile = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6058 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6059 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6060 | <h3 id="Package_clause">Package clause</h3> |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6061 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6062 | <p> |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6063 | A package clause begins each source file and defines the package |
| 6064 | to which the file belongs. |
| 6065 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6066 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 6067 | <pre class="ebnf"> |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 6068 | PackageClause = "package" PackageName . |
| 6069 | PackageName = identifier . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6070 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6071 | |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 6072 | <p> |
| 6073 | The PackageName must not be the <a href="#Blank_identifier">blank identifier</a>. |
| 6074 | </p> |
| 6075 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6076 | <pre> |
| 6077 | package math |
| 6078 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6079 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6080 | <p> |
| 6081 | A set of files sharing the same PackageName form the implementation of a package. |
| 6082 | An implementation may require that all source files for a package inhabit the same directory. |
| 6083 | </p> |
| 6084 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6085 | <h3 id="Import_declarations">Import declarations</h3> |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6086 | |
| 6087 | <p> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 6088 | An import declaration states that the source file containing the declaration |
| 6089 | depends on functionality of the <i>imported</i> package |
| 6090 | (<a href="#Program_initialization_and_execution">§Program initialization and execution</a>) |
Rob Pike | b51ad9c | 2012-09-23 05:03:43 +1000 | [diff] [blame] | 6091 | and enables access to <a href="#Exported_identifiers">exported</a> identifiers |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 6092 | of that package. |
| 6093 | 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] | 6094 | that specifies the package to be imported. |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6095 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6096 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 6097 | <pre class="ebnf"> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6098 | ImportDecl = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) . |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 6099 | ImportSpec = [ "." | PackageName ] ImportPath . |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6100 | ImportPath = string_lit . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6101 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6102 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6103 | <p> |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6104 | The PackageName is used in <a href="#Qualified_identifiers">qualified identifiers</a> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 6105 | to access exported identifiers of the package within the importing source file. |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6106 | It is declared in the <a href="#Blocks">file block</a>. |
| 6107 | 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] | 6108 | <a href="#Package_clause">package clause</a> of the imported package. |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6109 | 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] | 6110 | package's exported identifiers declared in that package's |
| 6111 | <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] | 6112 | file's file block and must be accessed without a qualifier. |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6113 | </p> |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 6114 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6115 | <p> |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6116 | The interpretation of the ImportPath is implementation-dependent but |
| 6117 | it is typically a substring of the full file name of the compiled |
| 6118 | package and may be relative to a repository of installed packages. |
| 6119 | </p> |
| 6120 | |
| 6121 | <p> |
Robert Griesemer | ac4055b | 2012-02-22 23:51:25 -0800 | [diff] [blame] | 6122 | Implementation restriction: A compiler may restrict ImportPaths to |
| 6123 | non-empty strings using only characters belonging to |
Suriyaa Sundararuban | 1041ac8 | 2018-06-13 07:06:04 +0000 | [diff] [blame] | 6124 | <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] | 6125 | L, M, N, P, and S general categories (the Graphic characters without |
Russ Cox | fad10f9 | 2012-02-23 22:46:04 -0500 | [diff] [blame] | 6126 | spaces) and may also exclude the characters |
| 6127 | <code>!"#$%&'()*,:;<=>?[\]^`{|}</code> |
| 6128 | and the Unicode replacement character U+FFFD. |
Robert Griesemer | ac4055b | 2012-02-22 23:51:25 -0800 | [diff] [blame] | 6129 | </p> |
| 6130 | |
| 6131 | <p> |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6132 | Assume we have compiled a package containing the package clause |
| 6133 | <code>package math</code>, which exports function <code>Sin</code>, and |
| 6134 | installed the compiled package in the file identified by |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6135 | <code>"lib/math"</code>. |
Rob Pike | 227fe5f | 2014-01-14 15:16:01 -0800 | [diff] [blame] | 6136 | This table illustrates how <code>Sin</code> is accessed in files |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6137 | that import the package after the |
| 6138 | various types of import declaration. |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6139 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6140 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6141 | <pre class="grammar"> |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 6142 | Import declaration Local name of Sin |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6143 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6144 | import "lib/math" math.Sin |
Rob Pike | b51ad9c | 2012-09-23 05:03:43 +1000 | [diff] [blame] | 6145 | import m "lib/math" m.Sin |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6146 | import . "lib/math" Sin |
| 6147 | </pre> |
| 6148 | |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 6149 | <p> |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6150 | An import declaration declares a dependency relation between |
| 6151 | the importing and imported package. |
Robert Griesemer | 4be38dd | 2013-03-04 12:59:40 -0800 | [diff] [blame] | 6152 | It is illegal for a package to import itself, directly or indirectly, |
| 6153 | or to directly import a package without |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 6154 | referring to any of its exported identifiers. To import a package solely for |
| 6155 | its side-effects (initialization), use the <a href="#Blank_identifier">blank</a> |
| 6156 | identifier as explicit package name: |
| 6157 | </p> |
| 6158 | |
| 6159 | <pre> |
| 6160 | import _ "lib/math" |
| 6161 | </pre> |
| 6162 | |
| 6163 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6164 | <h3 id="An_example_package">An example package</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6165 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6166 | <p> |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6167 | Here is a complete Go package that implements a concurrent prime sieve. |
| 6168 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6169 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6170 | <pre> |
| 6171 | package main |
| 6172 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6173 | import "fmt" |
| 6174 | |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 6175 | // Send the sequence 2, 3, 4, … to channel 'ch'. |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 6176 | func generate(ch chan<- int) { |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6177 | for i := 2; ; i++ { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6178 | ch <- i // Send 'i' to channel 'ch'. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6179 | } |
| 6180 | } |
| 6181 | |
Fazlul Shahriar | 330139e | 2009-11-30 21:23:58 -0800 | [diff] [blame] | 6182 | // Copy the values from channel 'src' to channel 'dst', |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6183 | // removing those divisible by 'prime'. |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 6184 | func filter(src <-chan int, dst chan<- int, prime int) { |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 6185 | for i := range src { // Loop over values received from 'src'. |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 6186 | if i%prime != 0 { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6187 | dst <- i // Send 'i' to channel 'dst'. |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6188 | } |
| 6189 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6190 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6191 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6192 | // The prime sieve: Daisy-chain filter processes together. |
| 6193 | func sieve() { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6194 | ch := make(chan int) // Create a new channel. |
| 6195 | go generate(ch) // Start generate() as a subprocess. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6196 | for { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6197 | prime := <-ch |
| 6198 | fmt.Print(prime, "\n") |
| 6199 | ch1 := make(chan int) |
| 6200 | go filter(ch, ch1, prime) |
| 6201 | ch = ch1 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6202 | } |
| 6203 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6204 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6205 | func main() { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6206 | sieve() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6207 | } |
| 6208 | </pre> |
Robert Griesemer | 6715358 | 2008-12-16 14:45:09 -0800 | [diff] [blame] | 6209 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6210 | <h2 id="Program_initialization_and_execution">Program initialization and execution</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6211 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6212 | <h3 id="The_zero_value">The zero value</h3> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6213 | <p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 6214 | When storage is allocated for a <a href="#Variables">variable</a>, |
| 6215 | either through a declaration or a call of <code>new</code>, or when |
| 6216 | a new value is created, either through a composite literal or a call |
| 6217 | of <code>make</code>, |
| 6218 | and no explicit initialization is provided, the variable or value is |
| 6219 | 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] | 6220 | 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] | 6221 | <code>0</code> for numeric types, <code>""</code> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 6222 | 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] | 6223 | This initialization is done recursively, so for instance each element of an |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6224 | array of structs will have its fields zeroed if no value is specified. |
| 6225 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6226 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6227 | These two simple declarations are equivalent: |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6228 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6229 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6230 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6231 | var i int |
| 6232 | var i int = 0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6233 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6234 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6235 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6236 | After |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6237 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6238 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6239 | <pre> |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 6240 | type T struct { i int; f float64; next *T } |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6241 | t := new(T) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6242 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6243 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6244 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6245 | the following holds: |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6246 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6247 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6248 | <pre> |
| 6249 | t.i == 0 |
| 6250 | t.f == 0.0 |
| 6251 | t.next == nil |
| 6252 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6253 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 6254 | <p> |
| 6255 | The same would also be true after |
| 6256 | </p> |
| 6257 | |
| 6258 | <pre> |
| 6259 | var t T |
| 6260 | </pre> |
| 6261 | |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6262 | <h3 id="Package_initialization">Package initialization</h3> |
Robert Griesemer | 259f0ff | 2014-09-29 12:44:50 -0700 | [diff] [blame] | 6263 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6264 | <p> |
Robert Griesemer | 259f0ff | 2014-09-29 12:44:50 -0700 | [diff] [blame] | 6265 | Within a package, package-level variables are initialized in |
| 6266 | <i>declaration order</i> but after any of the variables |
| 6267 | they <i>depend</i> on. |
| 6268 | </p> |
| 6269 | |
| 6270 | <p> |
| 6271 | More precisely, a package-level variable is considered <i>ready for |
| 6272 | initialization</i> if it is not yet initialized and either has |
| 6273 | no <a href="#Variable_declarations">initialization expression</a> or |
| 6274 | its initialization expression has no dependencies on uninitialized variables. |
| 6275 | Initialization proceeds by repeatedly initializing the next package-level |
| 6276 | variable that is earliest in declaration order and ready for initialization, |
| 6277 | until there are no variables ready for initialization. |
| 6278 | </p> |
| 6279 | |
| 6280 | <p> |
| 6281 | If any variables are still uninitialized when this |
| 6282 | process ends, those variables are part of one or more initialization cycles, |
| 6283 | and the program is not valid. |
| 6284 | </p> |
| 6285 | |
| 6286 | <p> |
| 6287 | The declaration order of variables declared in multiple files is determined |
| 6288 | by the order in which the files are presented to the compiler: Variables |
| 6289 | declared in the first file are declared before any of the variables declared |
| 6290 | in the second file, and so on. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 6291 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6292 | |
| 6293 | <p> |
| 6294 | Dependency analysis does not rely on the actual values of the |
| 6295 | variables, only on lexical <i>references</i> to them in the source, |
Robert Griesemer | 259f0ff | 2014-09-29 12:44:50 -0700 | [diff] [blame] | 6296 | analyzed transitively. For instance, if a variable <code>x</code>'s |
| 6297 | initialization expression refers to a function whose body refers to |
| 6298 | 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] | 6299 | Specifically: |
| 6300 | </p> |
| 6301 | |
| 6302 | <ul> |
| 6303 | <li> |
| 6304 | A reference to a variable or function is an identifier denoting that |
| 6305 | variable or function. |
| 6306 | </li> |
| 6307 | |
| 6308 | <li> |
| 6309 | A reference to a method <code>m</code> is a |
| 6310 | <a href="#Method_values">method value</a> or |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 6311 | <a href="#Method_expressions">method expression</a> of the form |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6312 | <code>t.m</code>, where the (static) type of <code>t</code> is |
| 6313 | not an interface type, and the method <code>m</code> is in the |
| 6314 | <a href="#Method_sets">method set</a> of <code>t</code>. |
| 6315 | It is immaterial whether the resulting function value |
| 6316 | <code>t.m</code> is invoked. |
| 6317 | </li> |
| 6318 | |
| 6319 | <li> |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 6320 | A variable, function, or method <code>x</code> depends on a variable |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6321 | <code>y</code> if <code>x</code>'s initialization expression or body |
| 6322 | (for functions and methods) contains a reference to <code>y</code> |
| 6323 | or to a function or method that depends on <code>y</code>. |
| 6324 | </li> |
| 6325 | </ul> |
| 6326 | |
| 6327 | <p> |
| 6328 | Dependency analysis is performed per package; only references referring |
| 6329 | to variables, functions, and methods declared in the current package |
| 6330 | are considered. |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6331 | </p> |
| 6332 | |
| 6333 | <p> |
| 6334 | For example, given the declarations |
| 6335 | </p> |
| 6336 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 6337 | <pre> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6338 | var ( |
| 6339 | a = c + b |
| 6340 | b = f() |
| 6341 | c = f() |
| 6342 | d = 3 |
| 6343 | ) |
| 6344 | |
| 6345 | func f() int { |
| 6346 | d++ |
| 6347 | return d |
| 6348 | } |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 6349 | </pre> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6350 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 6351 | <p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6352 | the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6353 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6354 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6355 | <p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6356 | Variables may also be initialized using functions named <code>init</code> |
| 6357 | declared in the package block, with no arguments and no result parameters. |
Rob Pike | 8cb9184 | 2009-09-15 11:56:39 -0700 | [diff] [blame] | 6358 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6359 | |
| 6360 | <pre> |
| 6361 | func init() { … } |
| 6362 | </pre> |
| 6363 | |
Rob Pike | 8cb9184 | 2009-09-15 11:56:39 -0700 | [diff] [blame] | 6364 | <p> |
Robert Griesemer | a656390 | 2016-08-25 21:01:17 -0700 | [diff] [blame] | 6365 | Multiple such functions may be defined per package, even within a single |
| 6366 | source file. In the package block, the <code>init</code> identifier can |
| 6367 | be used only to declare <code>init</code> functions, yet the identifier |
| 6368 | itself is not <a href="#Declarations_and_scope">declared</a>. Thus |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6369 | <code>init</code> functions cannot be referred to from anywhere |
| 6370 | in a program. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6371 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6372 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6373 | <p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6374 | A package with no imports is initialized by assigning initial values |
| 6375 | 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] | 6376 | functions in the order they appear in the source, possibly in multiple files, |
| 6377 | as presented to the compiler. |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6378 | If a package has imports, the imported packages are initialized |
Robert Griesemer | 566e3b2 | 2008-09-26 16:41:50 -0700 | [diff] [blame] | 6379 | before initializing the package itself. If multiple packages import |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6380 | a package, the imported package will be initialized only once. |
| 6381 | The importing of packages, by construction, guarantees that there |
| 6382 | can be no cyclic initialization dependencies. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6383 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6384 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6385 | <p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6386 | Package initialization—variable initialization and the invocation of |
| 6387 | <code>init</code> functions—happens in a single goroutine, |
| 6388 | sequentially, one package at a time. |
| 6389 | An <code>init</code> function may launch other goroutines, which can run |
| 6390 | concurrently with the initialization code. However, initialization |
| 6391 | always sequences |
| 6392 | the <code>init</code> functions: it will not invoke the next one |
| 6393 | until the previous one has returned. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6394 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6395 | |
Robert Griesemer | 259f0ff | 2014-09-29 12:44:50 -0700 | [diff] [blame] | 6396 | <p> |
| 6397 | To ensure reproducible initialization behavior, build systems are encouraged |
| 6398 | to present multiple files belonging to the same package in lexical file name |
| 6399 | order to a compiler. |
| 6400 | </p> |
| 6401 | |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6402 | |
| 6403 | <h3 id="Program_execution">Program execution</h3> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6404 | <p> |
Russ Cox | a6736ca | 2011-02-03 13:40:51 -0500 | [diff] [blame] | 6405 | A complete program is created by linking a single, unimported package |
| 6406 | called the <i>main package</i> with all the packages it imports, transitively. |
| 6407 | The main package must |
| 6408 | have package name <code>main</code> and |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 6409 | declare a function <code>main</code> that takes no |
Russ Cox | a6736ca | 2011-02-03 13:40:51 -0500 | [diff] [blame] | 6410 | arguments and returns no value. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6411 | </p> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 6412 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6413 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 6414 | func main() { … } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6415 | </pre> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 6416 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6417 | <p> |
Russ Cox | a6736ca | 2011-02-03 13:40:51 -0500 | [diff] [blame] | 6418 | Program execution begins by initializing the main package and then |
| 6419 | invoking the function <code>main</code>. |
Robert Griesemer | 7f1d62d | 2014-05-19 08:54:19 -0700 | [diff] [blame] | 6420 | When that function invocation returns, the program exits. |
Russ Cox | a6736ca | 2011-02-03 13:40:51 -0500 | [diff] [blame] | 6421 | 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] | 6422 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6423 | |
Russ Cox | d9877e2 | 2011-11-01 21:45:02 -0400 | [diff] [blame] | 6424 | <h2 id="Errors">Errors</h2> |
| 6425 | |
| 6426 | <p> |
| 6427 | The predeclared type <code>error</code> is defined as |
| 6428 | </p> |
| 6429 | |
| 6430 | <pre> |
| 6431 | type error interface { |
| 6432 | Error() string |
| 6433 | } |
| 6434 | </pre> |
| 6435 | |
| 6436 | <p> |
| 6437 | It is the conventional interface for representing an error condition, |
| 6438 | with the nil value representing no error. |
| 6439 | For instance, a function to read data from a file might be defined: |
| 6440 | </p> |
| 6441 | |
| 6442 | <pre> |
| 6443 | func Read(f *File, b []byte) (n int, err error) |
| 6444 | </pre> |
| 6445 | |
Evan Shaw | 21110c7 | 2010-04-22 10:14:53 -0700 | [diff] [blame] | 6446 | <h2 id="Run_time_panics">Run-time panics</h2> |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6447 | |
| 6448 | <p> |
| 6449 | Execution errors such as attempting to index an array out |
| 6450 | of bounds trigger a <i>run-time panic</i> equivalent to a call of |
| 6451 | the built-in function <a href="#Handling_panics"><code>panic</code></a> |
| 6452 | 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] | 6453 | That type satisfies the predeclared interface type |
Russ Cox | d9877e2 | 2011-11-01 21:45:02 -0400 | [diff] [blame] | 6454 | <a href="#Errors"><code>error</code></a>. |
| 6455 | The exact error values that |
| 6456 | represent distinct run-time error conditions are unspecified. |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6457 | </p> |
| 6458 | |
| 6459 | <pre> |
| 6460 | package runtime |
| 6461 | |
| 6462 | type Error interface { |
Russ Cox | d9877e2 | 2011-11-01 21:45:02 -0400 | [diff] [blame] | 6463 | error |
| 6464 | // and perhaps other methods |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6465 | } |
| 6466 | </pre> |
| 6467 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6468 | <h2 id="System_considerations">System considerations</h2> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6469 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6470 | <h3 id="Package_unsafe">Package <code>unsafe</code></h3> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6471 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6472 | <p> |
griesemer | ddc64de | 2017-10-17 13:38:10 -0700 | [diff] [blame] | 6473 | The built-in package <code>unsafe</code>, known to the compiler |
| 6474 | 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] | 6475 | provides facilities for low-level programming including operations |
| 6476 | that violate the type system. A package using <code>unsafe</code> |
Robert Griesemer | 5361b74 | 2014-10-23 09:45:11 -0700 | [diff] [blame] | 6477 | must be vetted manually for type safety and may not be portable. |
| 6478 | The package provides the following interface: |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6479 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6480 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 6481 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6482 | package unsafe |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6483 | |
Robert Griesemer | 98b4f6a | 2009-05-12 21:37:46 -0700 | [diff] [blame] | 6484 | type ArbitraryType int // shorthand for an arbitrary Go type; it is not a real type |
| 6485 | type Pointer *ArbitraryType |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6486 | |
Robert Griesemer | eee70b0 | 2011-06-13 16:46:42 -0700 | [diff] [blame] | 6487 | func Alignof(variable ArbitraryType) uintptr |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 6488 | func Offsetof(selector ArbitraryType) uintptr |
Robert Griesemer | eee70b0 | 2011-06-13 16:46:42 -0700 | [diff] [blame] | 6489 | func Sizeof(variable ArbitraryType) uintptr |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6490 | </pre> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6491 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6492 | <p> |
Robert Griesemer | e121de2 | 2013-10-07 10:43:28 -0700 | [diff] [blame] | 6493 | A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code> |
| 6494 | value may not be <a href="#Address_operators">dereferenced</a>. |
Robert Griesemer | 5361b74 | 2014-10-23 09:45:11 -0700 | [diff] [blame] | 6495 | 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] | 6496 | a type of underlying type <code>Pointer</code> and vice versa. |
Robert Griesemer | 5361b74 | 2014-10-23 09:45:11 -0700 | [diff] [blame] | 6497 | 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] | 6498 | </p> |
Russ Cox | 81eb930 | 2013-02-09 17:36:31 -0500 | [diff] [blame] | 6499 | |
| 6500 | <pre> |
| 6501 | var f float64 |
| 6502 | bits = *(*uint64)(unsafe.Pointer(&f)) |
| 6503 | |
| 6504 | type ptr unsafe.Pointer |
| 6505 | bits = *(*uint64)(ptr(&f)) |
Robert Griesemer | e121de2 | 2013-10-07 10:43:28 -0700 | [diff] [blame] | 6506 | |
| 6507 | var p ptr = nil |
Russ Cox | 81eb930 | 2013-02-09 17:36:31 -0500 | [diff] [blame] | 6508 | </pre> |
| 6509 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6510 | <p> |
Robert Griesemer | c7631f5 | 2012-09-17 12:23:41 -0700 | [diff] [blame] | 6511 | The functions <code>Alignof</code> and <code>Sizeof</code> take an expression <code>x</code> |
| 6512 | of any type and return the alignment or size, respectively, of a hypothetical variable <code>v</code> |
| 6513 | 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] | 6514 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6515 | <p> |
Robert Griesemer | 8c058b3 | 2012-09-18 11:25:53 -0700 | [diff] [blame] | 6516 | 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] | 6517 | <code>s.f</code>, denoting a field <code>f</code> of the struct denoted by <code>s</code> |
| 6518 | or <code>*s</code>, and returns the field offset in bytes relative to the struct's address. |
| 6519 | If <code>f</code> is an <a href="#Struct_types">embedded field</a>, it must be reachable |
| 6520 | without pointer indirections through fields of the struct. |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 6521 | For a struct <code>s</code> with field <code>f</code>: |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6522 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6523 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6524 | <pre> |
Robert Griesemer | eee70b0 | 2011-06-13 16:46:42 -0700 | [diff] [blame] | 6525 | 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] | 6526 | </pre> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6527 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6528 | <p> |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6529 | Computer architectures may require memory addresses to be <i>aligned</i>; |
| 6530 | that is, for addresses of a variable to be a multiple of a factor, |
| 6531 | the variable's type's <i>alignment</i>. The function <code>Alignof</code> |
| 6532 | takes an expression denoting a variable of any type and returns the |
| 6533 | alignment of the (type of the) variable in bytes. For a variable |
| 6534 | <code>x</code>: |
| 6535 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6536 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6537 | <pre> |
Robert Griesemer | eee70b0 | 2011-06-13 16:46:42 -0700 | [diff] [blame] | 6538 | uintptr(unsafe.Pointer(&x)) % unsafe.Alignof(x) == 0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6539 | </pre> |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 6540 | |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6541 | <p> |
| 6542 | Calls to <code>Alignof</code>, <code>Offsetof</code>, and |
Robert Griesemer | eee70b0 | 2011-06-13 16:46:42 -0700 | [diff] [blame] | 6543 | <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] | 6544 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6545 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6546 | <h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6547 | |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 6548 | <p> |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 6549 | 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] | 6550 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6551 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 6552 | <pre class="grammar"> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 6553 | type size in bytes |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6554 | |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 6555 | byte, uint8, int8 1 |
| 6556 | uint16, int16 2 |
| 6557 | uint32, int32, float32 4 |
| 6558 | uint64, int64, float64, complex64 8 |
| 6559 | complex128 16 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6560 | </pre> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6561 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6562 | <p> |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6563 | The following minimal alignment properties are guaranteed: |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 6564 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6565 | <ol> |
Robert Griesemer | dd916be | 2011-01-10 14:25:17 -0800 | [diff] [blame] | 6566 | <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] | 6567 | </li> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6568 | |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6569 | <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] | 6570 | 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] | 6571 | </li> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6572 | |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6573 | <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] | 6574 | the alignment of a variable of the array's element type. |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 6575 | </li> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6576 | </ol> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6577 | |
Robert Griesemer | 1320ce0 | 2012-01-09 16:54:24 -0800 | [diff] [blame] | 6578 | <p> |
| 6579 | 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. |
| 6580 | </p> |