| <!--{ |
| "Title": "The Go Programming Language Specification", |
| "Subtitle": "Version of May 9, 2018", |
| "Path": "/ref/spec" |
| }--> |
| |
| <h2 id="Introduction">Introduction</h2> |
| |
| <p> |
| This is a reference manual for the Go programming language. For |
| more information and other documents, see <a href="/">golang.org</a>. |
| </p> |
| |
| <p> |
| Go is a general-purpose language designed with systems programming |
| in mind. It is strongly typed and garbage-collected and has explicit |
| support for concurrent programming. Programs are constructed from |
| <i>packages</i>, whose properties allow efficient management of |
| dependencies. |
| </p> |
| |
| <p> |
| The grammar is compact and regular, allowing for easy analysis by |
| automatic tools such as integrated development environments. |
| </p> |
| |
| <h2 id="Notation">Notation</h2> |
| <p> |
| The syntax is specified using Extended Backus-Naur Form (EBNF): |
| </p> |
| |
| <pre class="grammar"> |
| Production = production_name "=" [ Expression ] "." . |
| Expression = Alternative { "|" Alternative } . |
| Alternative = Term { Term } . |
| Term = production_name | token [ "…" token ] | Group | Option | Repetition . |
| Group = "(" Expression ")" . |
| Option = "[" Expression "]" . |
| Repetition = "{" Expression "}" . |
| </pre> |
| |
| <p> |
| Productions are expressions constructed from terms and the following |
| operators, in increasing precedence: |
| </p> |
| <pre class="grammar"> |
| | alternation |
| () grouping |
| [] option (0 or 1 times) |
| {} repetition (0 to n times) |
| </pre> |
| |
| <p> |
| Lower-case production names are used to identify lexical tokens. |
| Non-terminals are in CamelCase. Lexical tokens are enclosed in |
| double quotes <code>""</code> or back quotes <code>``</code>. |
| </p> |
| |
| <p> |
| The form <code>a … b</code> represents the set of characters from |
| <code>a</code> through <code>b</code> as alternatives. The horizontal |
| ellipsis <code>…</code> is also used elsewhere in the spec to informally denote various |
| enumerations or code snippets that are not further specified. The character <code>…</code> |
| (as opposed to the three characters <code>...</code>) is not a token of the Go |
| language. |
| </p> |
| |
| <h2 id="Source_code_representation">Source code representation</h2> |
| |
| <p> |
| Source code is Unicode text encoded in |
| <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>. The text is not |
| canonicalized, so a single accented code point is distinct from the |
| same character constructed from combining an accent and a letter; |
| those are treated as two code points. For simplicity, this document |
| will use the unqualified term <i>character</i> to refer to a Unicode code point |
| in the source text. |
| </p> |
| <p> |
| Each code point is distinct; for instance, upper and lower case letters |
| are different characters. |
| </p> |
| <p> |
| Implementation restriction: For compatibility with other tools, a |
| compiler may disallow the NUL character (U+0000) in the source text. |
| </p> |
| <p> |
| Implementation restriction: For compatibility with other tools, a |
| compiler may ignore a UTF-8-encoded byte order mark |
| (U+FEFF) if it is the first Unicode code point in the source text. |
| A byte order mark may be disallowed anywhere else in the source. |
| </p> |
| |
| <h3 id="Characters">Characters</h3> |
| |
| <p> |
| The following terms are used to denote specific Unicode character classes: |
| </p> |
| <pre class="ebnf"> |
| newline = /* the Unicode code point U+000A */ . |
| unicode_char = /* an arbitrary Unicode code point except newline */ . |
| unicode_letter = /* a Unicode code point classified as "Letter" */ . |
| unicode_digit = /* a Unicode code point classified as "Number, decimal digit" */ . |
| </pre> |
| |
| <p> |
| In <a href="https://www.unicode.org/versions/Unicode8.0.0/">The Unicode Standard 8.0</a>, |
| Section 4.5 "General Category" defines a set of character categories. |
| Go treats all characters in any of the Letter categories Lu, Ll, Lt, Lm, or Lo |
| as Unicode letters, and those in the Number category Nd as Unicode digits. |
| </p> |
| |
| <h3 id="Letters_and_digits">Letters and digits</h3> |
| |
| <p> |
| The underscore character <code>_</code> (U+005F) is considered a letter. |
| </p> |
| <pre class="ebnf"> |
| letter = unicode_letter | "_" . |
| decimal_digit = "0" … "9" . |
| octal_digit = "0" … "7" . |
| hex_digit = "0" … "9" | "A" … "F" | "a" … "f" . |
| </pre> |
| |
| <h2 id="Lexical_elements">Lexical elements</h2> |
| |
| <h3 id="Comments">Comments</h3> |
| |
| <p> |
| Comments serve as program documentation. There are two forms: |
| </p> |
| |
| <ol> |
| <li> |
| <i>Line comments</i> start with the character sequence <code>//</code> |
| and stop at the end of the line. |
| </li> |
| <li> |
| <i>General comments</i> start with the character sequence <code>/*</code> |
| and stop with the first subsequent character sequence <code>*/</code>. |
| </li> |
| </ol> |
| |
| <p> |
| A comment cannot start inside a <a href="#Rune_literals">rune</a> or |
| <a href="#String_literals">string literal</a>, or inside a comment. |
| A general comment containing no newlines acts like a space. |
| Any other comment acts like a newline. |
| </p> |
| |
| <h3 id="Tokens">Tokens</h3> |
| |
| <p> |
| Tokens form the vocabulary of the Go language. |
| There are four classes: <i>identifiers</i>, <i>keywords</i>, <i>operators |
| and punctuation</i>, and <i>literals</i>. <i>White space</i>, formed from |
| spaces (U+0020), horizontal tabs (U+0009), |
| carriage returns (U+000D), and newlines (U+000A), |
| is ignored except as it separates tokens |
| that would otherwise combine into a single token. Also, a newline or end of file |
| may trigger the insertion of a <a href="#Semicolons">semicolon</a>. |
| While breaking the input into tokens, |
| the next token is the longest sequence of characters that form a |
| valid token. |
| </p> |
| |
| <h3 id="Semicolons">Semicolons</h3> |
| |
| <p> |
| The formal grammar uses semicolons <code>";"</code> as terminators in |
| a number of productions. Go programs may omit most of these semicolons |
| using the following two rules: |
| </p> |
| |
| <ol> |
| <li> |
| When the input is broken into tokens, a semicolon is automatically inserted |
| into the token stream immediately after a line's final token if that token is |
| <ul> |
| <li>an |
| <a href="#Identifiers">identifier</a> |
| </li> |
| |
| <li>an |
| <a href="#Integer_literals">integer</a>, |
| <a href="#Floating-point_literals">floating-point</a>, |
| <a href="#Imaginary_literals">imaginary</a>, |
| <a href="#Rune_literals">rune</a>, or |
| <a href="#String_literals">string</a> literal |
| </li> |
| |
| <li>one of the <a href="#Keywords">keywords</a> |
| <code>break</code>, |
| <code>continue</code>, |
| <code>fallthrough</code>, or |
| <code>return</code> |
| </li> |
| |
| <li>one of the <a href="#Operators_and_punctuation">operators and punctuation</a> |
| <code>++</code>, |
| <code>--</code>, |
| <code>)</code>, |
| <code>]</code>, or |
| <code>}</code> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| To allow complex statements to occupy a single line, a semicolon |
| may be omitted before a closing <code>")"</code> or <code>"}"</code>. |
| </li> |
| </ol> |
| |
| <p> |
| To reflect idiomatic use, code examples in this document elide semicolons |
| using these rules. |
| </p> |
| |
| |
| <h3 id="Identifiers">Identifiers</h3> |
| |
| <p> |
| Identifiers name program entities such as variables and types. |
| An identifier is a sequence of one or more letters and digits. |
| The first character in an identifier must be a letter. |
| </p> |
| <pre class="ebnf"> |
| identifier = letter { letter | unicode_digit } . |
| </pre> |
| <pre> |
| a |
| _x9 |
| ThisVariableIsExported |
| αβ |
| </pre> |
| |
| <p> |
| Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>. |
| </p> |
| |
| |
| <h3 id="Keywords">Keywords</h3> |
| |
| <p> |
| The following keywords are reserved and may not be used as identifiers. |
| </p> |
| <pre class="grammar"> |
| break default func interface select |
| case defer go map struct |
| chan else goto package switch |
| const fallthrough if range type |
| continue for import return var |
| </pre> |
| |
| <h3 id="Operators_and_punctuation">Operators and punctuation</h3> |
| |
| <p> |
| The following character sequences represent <a href="#Operators">operators</a> |
| (including <a href="#assign_op">assignment operators</a>) and punctuation: |
| </p> |
| <pre class="grammar"> |
| + & += &= && == != ( ) |
| - | -= |= || < <= [ ] |
| * ^ *= ^= <- > >= { } |
| / << /= <<= ++ = := , ; |
| % >> %= >>= -- ! ... . : |
| &^ &^= |
| </pre> |
| |
| <h3 id="Integer_literals">Integer literals</h3> |
| |
| <p> |
| An integer literal is a sequence of digits representing an |
| <a href="#Constants">integer constant</a>. |
| An optional prefix sets a non-decimal base: <code>0</code> for octal, <code>0x</code> or |
| <code>0X</code> for hexadecimal. In hexadecimal literals, letters |
| <code>a-f</code> and <code>A-F</code> represent values 10 through 15. |
| </p> |
| <pre class="ebnf"> |
| int_lit = decimal_lit | octal_lit | hex_lit . |
| decimal_lit = ( "1" … "9" ) { decimal_digit } . |
| octal_lit = "0" { octal_digit } . |
| hex_lit = "0" ( "x" | "X" ) hex_digit { hex_digit } . |
| </pre> |
| |
| <pre> |
| 42 |
| 0600 |
| 0xBadFace |
| 170141183460469231731687303715884105727 |
| </pre> |
| |
| <h3 id="Floating-point_literals">Floating-point literals</h3> |
| <p> |
| A floating-point literal is a decimal representation of a |
| <a href="#Constants">floating-point constant</a>. |
| It has an integer part, a decimal point, a fractional part, |
| and an exponent part. The integer and fractional part comprise |
| decimal digits; the exponent part is an <code>e</code> or <code>E</code> |
| followed by an optionally signed decimal exponent. One of the |
| integer part or the fractional part may be elided; one of the decimal |
| point or the exponent may be elided. |
| </p> |
| <pre class="ebnf"> |
| float_lit = decimals "." [ decimals ] [ exponent ] | |
| decimals exponent | |
| "." decimals [ exponent ] . |
| decimals = decimal_digit { decimal_digit } . |
| exponent = ( "e" | "E" ) [ "+" | "-" ] decimals . |
| </pre> |
| |
| <pre> |
| 0. |
| 72.40 |
| 072.40 // == 72.40 |
| 2.71828 |
| 1.e+0 |
| 6.67428e-11 |
| 1E6 |
| .25 |
| .12345E+5 |
| </pre> |
| |
| <h3 id="Imaginary_literals">Imaginary literals</h3> |
| <p> |
| An imaginary literal is a decimal representation of the imaginary part of a |
| <a href="#Constants">complex constant</a>. |
| It consists of a |
| <a href="#Floating-point_literals">floating-point literal</a> |
| or decimal integer followed |
| by the lower-case letter <code>i</code>. |
| </p> |
| <pre class="ebnf"> |
| imaginary_lit = (decimals | float_lit) "i" . |
| </pre> |
| |
| <pre> |
| 0i |
| 011i // == 11i |
| 0.i |
| 2.71828i |
| 1.e+0i |
| 6.67428e-11i |
| 1E6i |
| .25i |
| .12345E+5i |
| </pre> |
| |
| |
| <h3 id="Rune_literals">Rune literals</h3> |
| |
| <p> |
| A rune literal represents a <a href="#Constants">rune constant</a>, |
| an integer value identifying a Unicode code point. |
| A rune literal is expressed as one or more characters enclosed in single quotes, |
| as in <code>'x'</code> or <code>'\n'</code>. |
| Within the quotes, any character may appear except newline and unescaped single |
| quote. A single quoted character represents the Unicode value |
| of the character itself, |
| while multi-character sequences beginning with a backslash encode |
| values in various formats. |
| </p> |
| <p> |
| The simplest form represents the single character within the quotes; |
| since Go source text is Unicode characters encoded in UTF-8, multiple |
| UTF-8-encoded bytes may represent a single integer value. For |
| instance, the literal <code>'a'</code> holds a single byte representing |
| a literal <code>a</code>, Unicode U+0061, value <code>0x61</code>, while |
| <code>'ä'</code> holds two bytes (<code>0xc3</code> <code>0xa4</code>) representing |
| a literal <code>a</code>-dieresis, U+00E4, value <code>0xe4</code>. |
| </p> |
| <p> |
| Several backslash escapes allow arbitrary values to be encoded as |
| ASCII text. There are four ways to represent the integer value |
| as a numeric constant: <code>\x</code> followed by exactly two hexadecimal |
| digits; <code>\u</code> followed by exactly four hexadecimal digits; |
| <code>\U</code> followed by exactly eight hexadecimal digits, and a |
| plain backslash <code>\</code> followed by exactly three octal digits. |
| In each case the value of the literal is the value represented by |
| the digits in the corresponding base. |
| </p> |
| <p> |
| Although these representations all result in an integer, they have |
| different valid ranges. Octal escapes must represent a value between |
| 0 and 255 inclusive. Hexadecimal escapes satisfy this condition |
| by construction. The escapes <code>\u</code> and <code>\U</code> |
| represent Unicode code points so within them some values are illegal, |
| in particular those above <code>0x10FFFF</code> and surrogate halves. |
| </p> |
| <p> |
| After a backslash, certain single-character escapes represent special values: |
| </p> |
| <pre class="grammar"> |
| \a U+0007 alert or bell |
| \b U+0008 backspace |
| \f U+000C form feed |
| \n U+000A line feed or newline |
| \r U+000D carriage return |
| \t U+0009 horizontal tab |
| \v U+000b vertical tab |
| \\ U+005c backslash |
| \' U+0027 single quote (valid escape only within rune literals) |
| \" U+0022 double quote (valid escape only within string literals) |
| </pre> |
| <p> |
| All other sequences starting with a backslash are illegal inside rune literals. |
| </p> |
| <pre class="ebnf"> |
| rune_lit = "'" ( unicode_value | byte_value ) "'" . |
| unicode_value = unicode_char | little_u_value | big_u_value | escaped_char . |
| byte_value = octal_byte_value | hex_byte_value . |
| octal_byte_value = `\` octal_digit octal_digit octal_digit . |
| hex_byte_value = `\` "x" hex_digit hex_digit . |
| little_u_value = `\` "u" hex_digit hex_digit hex_digit hex_digit . |
| big_u_value = `\` "U" hex_digit hex_digit hex_digit hex_digit |
| hex_digit hex_digit hex_digit hex_digit . |
| escaped_char = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) . |
| </pre> |
| |
| <pre> |
| 'a' |
| 'ä' |
| '本' |
| '\t' |
| '\000' |
| '\007' |
| '\377' |
| '\x07' |
| '\xff' |
| '\u12e4' |
| '\U00101234' |
| '\'' // rune literal containing single quote character |
| 'aa' // illegal: too many characters |
| '\xa' // illegal: too few hexadecimal digits |
| '\0' // illegal: too few octal digits |
| '\uDFFF' // illegal: surrogate half |
| '\U00110000' // illegal: invalid Unicode code point |
| </pre> |
| |
| |
| <h3 id="String_literals">String literals</h3> |
| |
| <p> |
| A string literal represents a <a href="#Constants">string constant</a> |
| obtained from concatenating a sequence of characters. There are two forms: |
| raw string literals and interpreted string literals. |
| </p> |
| <p> |
| Raw string literals are character sequences between back quotes, as in |
| <code>`foo`</code>. Within the quotes, any character may appear except |
| back quote. The value of a raw string literal is the |
| string composed of the uninterpreted (implicitly UTF-8-encoded) characters |
| between the quotes; |
| in particular, backslashes have no special meaning and the string may |
| contain newlines. |
| Carriage return characters ('\r') inside raw string literals |
| are discarded from the raw string value. |
| </p> |
| <p> |
| Interpreted string literals are character sequences between double |
| quotes, as in <code>"bar"</code>. |
| Within the quotes, any character may appear except newline and unescaped double quote. |
| The text between the quotes forms the |
| value of the literal, with backslash escapes interpreted as they |
| are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and |
| <code>\"</code> is legal), with the same restrictions. |
| The three-digit octal (<code>\</code><i>nnn</i>) |
| and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual |
| <i>bytes</i> of the resulting string; all other escapes represent |
| the (possibly multi-byte) UTF-8 encoding of individual <i>characters</i>. |
| Thus inside a string literal <code>\377</code> and <code>\xFF</code> represent |
| a single byte of value <code>0xFF</code>=255, while <code>ÿ</code>, |
| <code>\u00FF</code>, <code>\U000000FF</code> and <code>\xc3\xbf</code> represent |
| the two bytes <code>0xc3</code> <code>0xbf</code> of the UTF-8 encoding of character |
| U+00FF. |
| </p> |
| |
| <pre class="ebnf"> |
| string_lit = raw_string_lit | interpreted_string_lit . |
| raw_string_lit = "`" { unicode_char | newline } "`" . |
| interpreted_string_lit = `"` { unicode_value | byte_value } `"` . |
| </pre> |
| |
| <pre> |
| `abc` // same as "abc" |
| `\n |
| \n` // same as "\\n\n\\n" |
| "\n" |
| "\"" // same as `"` |
| "Hello, world!\n" |
| "日本語" |
| "\u65e5本\U00008a9e" |
| "\xff\u00FF" |
| "\uD800" // illegal: surrogate half |
| "\U00110000" // illegal: invalid Unicode code point |
| </pre> |
| |
| <p> |
| These examples all represent the same string: |
| </p> |
| |
| <pre> |
| "日本語" // UTF-8 input text |
| `日本語` // UTF-8 input text as a raw literal |
| "\u65e5\u672c\u8a9e" // the explicit Unicode code points |
| "\U000065e5\U0000672c\U00008a9e" // the explicit Unicode code points |
| "\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e" // the explicit UTF-8 bytes |
| </pre> |
| |
| <p> |
| If the source code represents a character as two code points, such as |
| a combining form involving an accent and a letter, the result will be |
| an error if placed in a rune literal (it is not a single code |
| point), and will appear as two code points if placed in a string |
| literal. |
| </p> |
| |
| |
| <h2 id="Constants">Constants</h2> |
| |
| <p>There are <i>boolean constants</i>, |
| <i>rune constants</i>, |
| <i>integer constants</i>, |
| <i>floating-point constants</i>, <i>complex constants</i>, |
| and <i>string constants</i>. Rune, integer, floating-point, |
| and complex constants are |
| collectively called <i>numeric constants</i>. |
| </p> |
| |
| <p> |
| A constant value is represented by a |
| <a href="#Rune_literals">rune</a>, |
| <a href="#Integer_literals">integer</a>, |
| <a href="#Floating-point_literals">floating-point</a>, |
| <a href="#Imaginary_literals">imaginary</a>, |
| or |
| <a href="#String_literals">string</a> literal, |
| an identifier denoting a constant, |
| a <a href="#Constant_expressions">constant expression</a>, |
| a <a href="#Conversions">conversion</a> with a result that is a constant, or |
| the result value of some built-in functions such as |
| <code>unsafe.Sizeof</code> applied to any value, |
| <code>cap</code> or <code>len</code> applied to |
| <a href="#Length_and_capacity">some expressions</a>, |
| <code>real</code> and <code>imag</code> applied to a complex constant |
| and <code>complex</code> applied to numeric constants. |
| The boolean truth values are represented by the predeclared constants |
| <code>true</code> and <code>false</code>. The predeclared identifier |
| <a href="#Iota">iota</a> denotes an integer constant. |
| </p> |
| |
| <p> |
| In general, complex constants are a form of |
| <a href="#Constant_expressions">constant expression</a> |
| and are discussed in that section. |
| </p> |
| |
| <p> |
| Numeric constants represent exact values of arbitrary precision and do not overflow. |
| Consequently, there are no constants denoting the IEEE-754 negative zero, infinity, |
| and not-a-number values. |
| </p> |
| |
| <p> |
| Constants may be <a href="#Types">typed</a> or <i>untyped</i>. |
| Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>, |
| and certain <a href="#Constant_expressions">constant expressions</a> |
| containing only untyped constant operands are untyped. |
| </p> |
| |
| <p> |
| A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a> |
| or <a href="#Conversions">conversion</a>, or implicitly when used in a |
| <a href="#Variable_declarations">variable declaration</a> or an |
| <a href="#Assignments">assignment</a> or as an |
| operand in an <a href="#Expressions">expression</a>. |
| It is an error if the constant value |
| cannot be <a href="#Representability">represented</a> as a value of the respective type. |
| </p> |
| |
| <p> |
| An untyped constant has a <i>default type</i> which is the type to which the |
| constant is implicitly converted in contexts where a typed value is required, |
| for instance, in a <a href="#Short_variable_declarations">short variable declaration</a> |
| such as <code>i := 0</code> where there is no explicit type. |
| The default type of an untyped constant is <code>bool</code>, <code>rune</code>, |
| <code>int</code>, <code>float64</code>, <code>complex128</code> or <code>string</code> |
| respectively, depending on whether it is a boolean, rune, integer, floating-point, |
| complex, or string constant. |
| </p> |
| |
| <p> |
| Implementation restriction: Although numeric constants have arbitrary |
| precision in the language, a compiler may implement them using an |
| internal representation with limited precision. That said, every |
| implementation must: |
| </p> |
| <ul> |
| <li>Represent integer constants with at least 256 bits.</li> |
| |
| <li>Represent floating-point constants, including the parts of |
| a complex constant, with a mantissa of at least 256 bits |
| and a signed binary exponent of at least 16 bits.</li> |
| |
| <li>Give an error if unable to represent an integer constant |
| precisely.</li> |
| |
| <li>Give an error if unable to represent a floating-point or |
| complex constant due to overflow.</li> |
| |
| <li>Round to the nearest representable constant if unable to |
| represent a floating-point or complex constant due to limits |
| on precision.</li> |
| </ul> |
| <p> |
| These requirements apply both to literal constants and to the result |
| of evaluating <a href="#Constant_expressions">constant |
| expressions</a>. |
| </p> |
| |
| <h2 id="Variables">Variables</h2> |
| |
| <p> |
| A variable is a storage location for holding a <i>value</i>. |
| The set of permissible values is determined by the |
| variable's <i><a href="#Types">type</a></i>. |
| </p> |
| |
| <p> |
| A <a href="#Variable_declarations">variable declaration</a> |
| or, for function parameters and results, the signature |
| of a <a href="#Function_declarations">function declaration</a> |
| or <a href="#Function_literals">function literal</a> reserves |
| storage for a named variable. |
| |
| Calling the built-in function <a href="#Allocation"><code>new</code></a> |
| or taking the address of a <a href="#Composite_literals">composite literal</a> |
| allocates storage for a variable at run time. |
| Such an anonymous variable is referred to via a (possibly implicit) |
| <a href="#Address_operators">pointer indirection</a>. |
| </p> |
| |
| <p> |
| <i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>, |
| and <a href="#Struct_types">struct</a> types have elements and fields that may |
| be <a href="#Address_operators">addressed</a> individually. Each such element |
| acts like a variable. |
| </p> |
| |
| <p> |
| The <i>static type</i> (or just <i>type</i>) of a variable is the |
| type given in its declaration, the type provided in the |
| <code>new</code> call or composite literal, or the type of |
| an element of a structured variable. |
| Variables of interface type also have a distinct <i>dynamic type</i>, |
| which is the concrete type of the value assigned to the variable at run time |
| (unless the value is the predeclared identifier <code>nil</code>, |
| which has no type). |
| The dynamic type may vary during execution but values stored in interface |
| variables are always <a href="#Assignability">assignable</a> |
| to the static type of the variable. |
| </p> |
| |
| <pre> |
| var x interface{} // x is nil and has static type interface{} |
| var v *T // v has value nil, static type *T |
| x = 42 // x has value 42 and dynamic type int |
| x = v // x has value (*T)(nil) and dynamic type *T |
| </pre> |
| |
| <p> |
| A variable's value is retrieved by referring to the variable in an |
| <a href="#Expressions">expression</a>; it is the most recent value |
| <a href="#Assignments">assigned</a> to the variable. |
| If a variable has not yet been assigned a value, its value is the |
| <a href="#The_zero_value">zero value</a> for its type. |
| </p> |
| |
| |
| <h2 id="Types">Types</h2> |
| |
| <p> |
| A type determines a set of values together with operations and methods specific |
| to those values. A type may be denoted by a <i>type name</i>, if it has one, |
| or specified using a <i>type literal</i>, which composes a type from existing types. |
| </p> |
| |
| <pre class="ebnf"> |
| Type = TypeName | TypeLit | "(" Type ")" . |
| TypeName = identifier | QualifiedIdent . |
| TypeLit = ArrayType | StructType | PointerType | FunctionType | InterfaceType | |
| SliceType | MapType | ChannelType . |
| </pre> |
| |
| <p> |
| The language <a href="#Predeclared_identifiers">predeclares</a> certain type names. |
| Others are introduced with <a href="#Type_declarations">type declarations</a>. |
| <i>Composite types</i>—array, struct, pointer, function, |
| interface, slice, map, and channel types—may be constructed using |
| type literals. |
| </p> |
| |
| <p> |
| Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code> |
| is one of the predeclared boolean, numeric, or string types, or a type literal, |
| the corresponding underlying |
| type is <code>T</code> itself. Otherwise, <code>T</code>'s underlying type |
| is the underlying type of the type to which <code>T</code> refers in its |
| <a href="#Type_declarations">type declaration</a>. |
| </p> |
| |
| <pre> |
| type ( |
| A1 = string |
| A2 = A1 |
| ) |
| |
| type ( |
| B1 string |
| B2 B1 |
| B3 []B1 |
| B4 B3 |
| ) |
| </pre> |
| |
| <p> |
| The underlying type of <code>string</code>, <code>A1</code>, <code>A2</code>, <code>B1</code>, |
| and <code>B2</code> is <code>string</code>. |
| The underlying type of <code>[]B1</code>, <code>B3</code>, and <code>B4</code> is <code>[]B1</code>. |
| </p> |
| |
| <h3 id="Method_sets">Method sets</h3> |
| <p> |
| A type may have a <i>method set</i> associated with it. |
| The method set of an <a href="#Interface_types">interface type</a> is its interface. |
| The method set of any other type <code>T</code> consists of all |
| <a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>. |
| The method set of the corresponding <a href="#Pointer_types">pointer type</a> <code>*T</code> |
| is the set of all methods declared with receiver <code>*T</code> or <code>T</code> |
| (that is, it also contains the method set of <code>T</code>). |
| Further rules apply to structs containing embedded fields, as described |
| in the section on <a href="#Struct_types">struct types</a>. |
| Any other type has an empty method set. |
| In a method set, each method must have a |
| <a href="#Uniqueness_of_identifiers">unique</a> |
| non-<a href="#Blank_identifier">blank</a> <a href="#MethodName">method name</a>. |
| </p> |
| |
| <p> |
| The method set of a type determines the interfaces that the |
| type <a href="#Interface_types">implements</a> |
| and the methods that can be <a href="#Calls">called</a> |
| using a receiver of that type. |
| </p> |
| |
| <h3 id="Boolean_types">Boolean types</h3> |
| |
| <p> |
| A <i>boolean type</i> represents the set of Boolean truth values |
| denoted by the predeclared constants <code>true</code> |
| and <code>false</code>. The predeclared boolean type is <code>bool</code>; |
| it is a <a href="#Type_definitions">defined type</a>. |
| </p> |
| |
| <h3 id="Numeric_types">Numeric types</h3> |
| |
| <p> |
| A <i>numeric type</i> represents sets of integer or floating-point values. |
| The predeclared architecture-independent numeric types are: |
| </p> |
| |
| <pre class="grammar"> |
| uint8 the set of all unsigned 8-bit integers (0 to 255) |
| uint16 the set of all unsigned 16-bit integers (0 to 65535) |
| uint32 the set of all unsigned 32-bit integers (0 to 4294967295) |
| uint64 the set of all unsigned 64-bit integers (0 to 18446744073709551615) |
| |
| int8 the set of all signed 8-bit integers (-128 to 127) |
| int16 the set of all signed 16-bit integers (-32768 to 32767) |
| int32 the set of all signed 32-bit integers (-2147483648 to 2147483647) |
| int64 the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807) |
| |
| float32 the set of all IEEE-754 32-bit floating-point numbers |
| float64 the set of all IEEE-754 64-bit floating-point numbers |
| |
| complex64 the set of all complex numbers with float32 real and imaginary parts |
| complex128 the set of all complex numbers with float64 real and imaginary parts |
| |
| byte alias for uint8 |
| rune alias for int32 |
| </pre> |
| |
| <p> |
| The value of an <i>n</i>-bit integer is <i>n</i> bits wide and represented using |
| <a href="https://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>. |
| </p> |
| |
| <p> |
| There is also a set of predeclared numeric types with implementation-specific sizes: |
| </p> |
| |
| <pre class="grammar"> |
| uint either 32 or 64 bits |
| int same size as uint |
| uintptr an unsigned integer large enough to store the uninterpreted bits of a pointer value |
| </pre> |
| |
| <p> |
| To avoid portability issues all numeric types are <a href="#Type_definitions">defined |
| types</a> and thus distinct except |
| <code>byte</code>, which is an <a href="#Alias_declarations">alias</a> for <code>uint8</code>, and |
| <code>rune</code>, which is an alias for <code>int32</code>. |
| Conversions |
| are required when different numeric types are mixed in an expression |
| or assignment. For instance, <code>int32</code> and <code>int</code> |
| are not the same type even though they may have the same size on a |
| particular architecture. |
| |
| |
| <h3 id="String_types">String types</h3> |
| |
| <p> |
| A <i>string type</i> represents the set of string values. |
| A string value is a (possibly empty) sequence of bytes. |
| Strings are immutable: once created, |
| it is impossible to change the contents of a string. |
| The predeclared string type is <code>string</code>; |
| it is a <a href="#Type_definitions">defined type</a>. |
| </p> |
| |
| <p> |
| The length of a string <code>s</code> (its size in bytes) can be discovered using |
| the built-in function <a href="#Length_and_capacity"><code>len</code></a>. |
| The length is a compile-time constant if the string is a constant. |
| A string's bytes can be accessed by integer <a href="#Index_expressions">indices</a> |
| 0 through <code>len(s)-1</code>. |
| It is illegal to take the address of such an element; if |
| <code>s[i]</code> is the <code>i</code>'th byte of a |
| string, <code>&s[i]</code> is invalid. |
| </p> |
| |
| |
| <h3 id="Array_types">Array types</h3> |
| |
| <p> |
| An array is a numbered sequence of elements of a single |
| type, called the element type. |
| The number of elements is called the length and is never |
| negative. |
| </p> |
| |
| <pre class="ebnf"> |
| ArrayType = "[" ArrayLength "]" ElementType . |
| ArrayLength = Expression . |
| ElementType = Type . |
| </pre> |
| |
| <p> |
| The length is part of the array's type; it must evaluate to a |
| non-negative <a href="#Constants">constant</a> |
| <a href="#Representability">representable</a> by a value |
| of type <code>int</code>. |
| The length of array <code>a</code> can be discovered |
| using the built-in function <a href="#Length_and_capacity"><code>len</code></a>. |
| The elements can be addressed by integer <a href="#Index_expressions">indices</a> |
| 0 through <code>len(a)-1</code>. |
| Array types are always one-dimensional but may be composed to form |
| multi-dimensional types. |
| </p> |
| |
| <pre> |
| [32]byte |
| [2*N] struct { x, y int32 } |
| [1000]*float64 |
| [3][5]int |
| [2][2][2]float64 // same as [2]([2]([2]float64)) |
| </pre> |
| |
| <h3 id="Slice_types">Slice types</h3> |
| |
| <p> |
| A slice is a descriptor for a contiguous segment of an <i>underlying array</i> and |
| provides access to a numbered sequence of elements from that array. |
| A slice type denotes the set of all slices of arrays of its element type. |
| The value of an uninitialized slice is <code>nil</code>. |
| </p> |
| |
| <pre class="ebnf"> |
| SliceType = "[" "]" ElementType . |
| </pre> |
| |
| <p> |
| Like arrays, slices are indexable and have a length. The length of a |
| slice <code>s</code> can be discovered by the built-in function |
| <a href="#Length_and_capacity"><code>len</code></a>; unlike with arrays it may change during |
| execution. The elements can be addressed by integer <a href="#Index_expressions">indices</a> |
| 0 through <code>len(s)-1</code>. The slice index of a |
| given element may be less than the index of the same element in the |
| underlying array. |
| </p> |
| <p> |
| A slice, once initialized, is always associated with an underlying |
| array that holds its elements. A slice therefore shares storage |
| with its array and with other slices of the same array; by contrast, |
| distinct arrays always represent distinct storage. |
| </p> |
| <p> |
| The array underlying a slice may extend past the end of the slice. |
| The <i>capacity</i> is a measure of that extent: it is the sum of |
| the length of the slice and the length of the array beyond the slice; |
| a slice of length up to that capacity can be created by |
| <a href="#Slice_expressions"><i>slicing</i></a> a new one from the original slice. |
| The capacity of a slice <code>a</code> can be discovered using the |
| built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>. |
| </p> |
| |
| <p> |
| A new, initialized slice value for a given element type <code>T</code> is |
| made using the built-in function |
| <a href="#Making_slices_maps_and_channels"><code>make</code></a>, |
| which takes a slice type |
| and parameters specifying the length and optionally the capacity. |
| A slice created with <code>make</code> always allocates a new, hidden array |
| to which the returned slice value refers. That is, executing |
| </p> |
| |
| <pre> |
| make([]T, length, capacity) |
| </pre> |
| |
| <p> |
| produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a> |
| it, so these two expressions are equivalent: |
| </p> |
| |
| <pre> |
| make([]int, 50, 100) |
| new([100]int)[0:50] |
| </pre> |
| |
| <p> |
| Like arrays, slices are always one-dimensional but may be composed to construct |
| higher-dimensional objects. |
| With arrays of arrays, the inner arrays are, by construction, always the same length; |
| however with slices of slices (or arrays of slices), the inner lengths may vary dynamically. |
| Moreover, the inner slices must be initialized individually. |
| </p> |
| |
| <h3 id="Struct_types">Struct types</h3> |
| |
| <p> |
| A struct is a sequence of named elements, called fields, each of which has a |
| name and a type. Field names may be specified explicitly (IdentifierList) or |
| implicitly (EmbeddedField). |
| Within a struct, non-<a href="#Blank_identifier">blank</a> field names must |
| be <a href="#Uniqueness_of_identifiers">unique</a>. |
| </p> |
| |
| <pre class="ebnf"> |
| StructType = "struct" "{" { FieldDecl ";" } "}" . |
| FieldDecl = (IdentifierList Type | EmbeddedField) [ Tag ] . |
| EmbeddedField = [ "*" ] TypeName . |
| Tag = string_lit . |
| </pre> |
| |
| <pre> |
| // An empty struct. |
| struct {} |
| |
| // A struct with 6 fields. |
| struct { |
| x, y int |
| u float32 |
| _ float32 // padding |
| A *[]int |
| F func() |
| } |
| </pre> |
| |
| <p> |
| A field declared with a type but no explicit field name is called an <i>embedded field</i>. |
| An embedded field must be specified as |
| a type name <code>T</code> or as a pointer to a non-interface type name <code>*T</code>, |
| and <code>T</code> itself may not be |
| a pointer type. The unqualified type name acts as the field name. |
| </p> |
| |
| <pre> |
| // A struct with four embedded fields of types T1, *T2, P.T3 and *P.T4 |
| struct { |
| T1 // field name is T1 |
| *T2 // field name is T2 |
| P.T3 // field name is T3 |
| *P.T4 // field name is T4 |
| x, y int // field names are x and y |
| } |
| </pre> |
| |
| <p> |
| The following declaration is illegal because field names must be unique |
| in a struct type: |
| </p> |
| |
| <pre> |
| struct { |
| T // conflicts with embedded field *T and *P.T |
| *T // conflicts with embedded field T and *P.T |
| *P.T // conflicts with embedded field T and *T |
| } |
| </pre> |
| |
| <p> |
| A field or <a href="#Method_declarations">method</a> <code>f</code> of an |
| embedded field in a struct <code>x</code> is called <i>promoted</i> if |
| <code>x.f</code> is a legal <a href="#Selectors">selector</a> that denotes |
| that field or method <code>f</code>. |
| </p> |
| |
| <p> |
| Promoted fields act like ordinary fields |
| of a struct except that they cannot be used as field names in |
| <a href="#Composite_literals">composite literals</a> of the struct. |
| </p> |
| |
| <p> |
| Given a struct type <code>S</code> and a <a href="#Type_definitions">defined type</a> |
| <code>T</code>, promoted methods are included in the method set of the struct as follows: |
| </p> |
| <ul> |
| <li> |
| If <code>S</code> contains an embedded field <code>T</code>, |
| the <a href="#Method_sets">method sets</a> of <code>S</code> |
| and <code>*S</code> both include promoted methods with receiver |
| <code>T</code>. The method set of <code>*S</code> also |
| includes promoted methods with receiver <code>*T</code>. |
| </li> |
| |
| <li> |
| If <code>S</code> contains an embedded field <code>*T</code>, |
| the method sets of <code>S</code> and <code>*S</code> both |
| include promoted methods with receiver <code>T</code> or |
| <code>*T</code>. |
| </li> |
| </ul> |
| |
| <p> |
| A field declaration may be followed by an optional string literal <i>tag</i>, |
| which becomes an attribute for all the fields in the corresponding |
| field declaration. An empty tag string is equivalent to an absent tag. |
| The tags are made visible through a <a href="/pkg/reflect/#StructTag">reflection interface</a> |
| and take part in <a href="#Type_identity">type identity</a> for structs |
| but are otherwise ignored. |
| </p> |
| |
| <pre> |
| struct { |
| x, y float64 "" // an empty tag string is like an absent tag |
| name string "any string is permitted as a tag" |
| _ [4]byte "ceci n'est pas un champ de structure" |
| } |
| |
| // A struct corresponding to a TimeStamp protocol buffer. |
| // The tag strings define the protocol buffer field numbers; |
| // they follow the convention outlined by the reflect package. |
| struct { |
| microsec uint64 `protobuf:"1"` |
| serverIP6 uint64 `protobuf:"2"` |
| } |
| </pre> |
| |
| <h3 id="Pointer_types">Pointer types</h3> |
| |
| <p> |
| A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given |
| type, called the <i>base type</i> of the pointer. |
| The value of an uninitialized pointer is <code>nil</code>. |
| </p> |
| |
| <pre class="ebnf"> |
| PointerType = "*" BaseType . |
| BaseType = Type . |
| </pre> |
| |
| <pre> |
| *Point |
| *[4]int |
| </pre> |
| |
| <h3 id="Function_types">Function types</h3> |
| |
| <p> |
| A function type denotes the set of all functions with the same parameter |
| and result types. The value of an uninitialized variable of function type |
| is <code>nil</code>. |
| </p> |
| |
| <pre class="ebnf"> |
| FunctionType = "func" Signature . |
| Signature = Parameters [ Result ] . |
| Result = Parameters | Type . |
| Parameters = "(" [ ParameterList [ "," ] ] ")" . |
| ParameterList = ParameterDecl { "," ParameterDecl } . |
| ParameterDecl = [ IdentifierList ] [ "..." ] Type . |
| </pre> |
| |
| <p> |
| Within a list of parameters or results, the names (IdentifierList) |
| must either all be present or all be absent. If present, each name |
| stands for one item (parameter or result) of the specified type and |
| all non-<a href="#Blank_identifier">blank</a> names in the signature |
| must be <a href="#Uniqueness_of_identifiers">unique</a>. |
| If absent, each type stands for one item of that type. |
| Parameter and result |
| lists are always parenthesized except that if there is exactly |
| one unnamed result it may be written as an unparenthesized type. |
| </p> |
| |
| <p> |
| The final incoming parameter in a function signature may have |
| a type prefixed with <code>...</code>. |
| A function with such a parameter is called <i>variadic</i> and |
| may be invoked with zero or more arguments for that parameter. |
| </p> |
| |
| <pre> |
| func() |
| func(x int) int |
| func(a, _ int, z float32) bool |
| func(a, b int, z float32) (bool) |
| func(prefix string, values ...int) |
| func(a, b int, z float64, opt ...interface{}) (success bool) |
| func(int, int, float64) (float64, *[]int) |
| func(n int) func(p *T) |
| </pre> |
| |
| |
| <h3 id="Interface_types">Interface types</h3> |
| |
| <p> |
| An interface type specifies a <a href="#Method_sets">method set</a> called its <i>interface</i>. |
| A variable of interface type can store a value of any type with a method set |
| that is any superset of the interface. Such a type is said to |
| <i>implement the interface</i>. |
| The value of an uninitialized variable of interface type is <code>nil</code>. |
| </p> |
| |
| <pre class="ebnf"> |
| InterfaceType = "interface" "{" { MethodSpec ";" } "}" . |
| MethodSpec = MethodName Signature | InterfaceTypeName . |
| MethodName = identifier . |
| InterfaceTypeName = TypeName . |
| </pre> |
| |
| <p> |
| As with all method sets, in an interface type, each method must have a |
| <a href="#Uniqueness_of_identifiers">unique</a> |
| non-<a href="#Blank_identifier">blank</a> name. |
| </p> |
| |
| <pre> |
| // A simple File interface |
| interface { |
| Read(b Buffer) bool |
| Write(b Buffer) bool |
| Close() |
| } |
| </pre> |
| |
| <p> |
| More than one type may implement an interface. |
| For instance, if two types <code>S1</code> and <code>S2</code> |
| have the method set |
| </p> |
| |
| <pre> |
| func (p T) Read(b Buffer) bool { return … } |
| func (p T) Write(b Buffer) bool { return … } |
| func (p T) Close() { … } |
| </pre> |
| |
| <p> |
| (where <code>T</code> stands for either <code>S1</code> or <code>S2</code>) |
| then the <code>File</code> interface is implemented by both <code>S1</code> and |
| <code>S2</code>, regardless of what other methods |
| <code>S1</code> and <code>S2</code> may have or share. |
| </p> |
| |
| <p> |
| A type implements any interface comprising any subset of its methods |
| and may therefore implement several distinct interfaces. For |
| instance, all types implement the <i>empty interface</i>: |
| </p> |
| |
| <pre> |
| interface{} |
| </pre> |
| |
| <p> |
| Similarly, consider this interface specification, |
| which appears within a <a href="#Type_declarations">type declaration</a> |
| to define an interface called <code>Locker</code>: |
| </p> |
| |
| <pre> |
| type Locker interface { |
| Lock() |
| Unlock() |
| } |
| </pre> |
| |
| <p> |
| If <code>S1</code> and <code>S2</code> also implement |
| </p> |
| |
| <pre> |
| func (p T) Lock() { … } |
| func (p T) Unlock() { … } |
| </pre> |
| |
| <p> |
| they implement the <code>Locker</code> interface as well |
| as the <code>File</code> interface. |
| </p> |
| |
| <p> |
| An interface <code>T</code> may use a (possibly qualified) interface type |
| name <code>E</code> in place of a method specification. This is called |
| <i>embedding</i> interface <code>E</code> in <code>T</code>; it adds |
| all (exported and non-exported) methods of <code>E</code> to the interface |
| <code>T</code>. |
| </p> |
| |
| <pre> |
| type ReadWriter interface { |
| Read(b Buffer) bool |
| Write(b Buffer) bool |
| } |
| |
| type File interface { |
| ReadWriter // same as adding the methods of ReadWriter |
| Locker // same as adding the methods of Locker |
| Close() |
| } |
| |
| type LockedFile interface { |
| Locker |
| File // illegal: Lock, Unlock not unique |
| Lock() // illegal: Lock not unique |
| } |
| </pre> |
| |
| <p> |
| An interface type <code>T</code> may not embed itself |
| or any interface type that embeds <code>T</code>, recursively. |
| </p> |
| |
| <pre> |
| // illegal: Bad cannot embed itself |
| type Bad interface { |
| Bad |
| } |
| |
| // illegal: Bad1 cannot embed itself using Bad2 |
| type Bad1 interface { |
| Bad2 |
| } |
| type Bad2 interface { |
| Bad1 |
| } |
| </pre> |
| |
| <h3 id="Map_types">Map types</h3> |
| |
| <p> |
| A map is an unordered group of elements of one type, called the |
| element type, indexed by a set of unique <i>keys</i> of another type, |
| called the key type. |
| The value of an uninitialized map is <code>nil</code>. |
| </p> |
| |
| <pre class="ebnf"> |
| MapType = "map" "[" KeyType "]" ElementType . |
| KeyType = Type . |
| </pre> |
| |
| <p> |
| The <a href="#Comparison_operators">comparison operators</a> |
| <code>==</code> and <code>!=</code> must be fully defined |
| for operands of the key type; thus the key type must not be a function, map, or |
| slice. |
| If the key type is an interface type, these |
| comparison operators must be defined for the dynamic key values; |
| failure will cause a <a href="#Run_time_panics">run-time panic</a>. |
| |
| </p> |
| |
| <pre> |
| map[string]int |
| map[*T]struct{ x, y float64 } |
| map[string]interface{} |
| </pre> |
| |
| <p> |
| The number of map elements is called its length. |
| For a map <code>m</code>, it can be discovered using the |
| built-in function <a href="#Length_and_capacity"><code>len</code></a> |
| and may change during execution. Elements may be added during execution |
| using <a href="#Assignments">assignments</a> and retrieved with |
| <a href="#Index_expressions">index expressions</a>; they may be removed with the |
| <a href="#Deletion_of_map_elements"><code>delete</code></a> built-in function. |
| </p> |
| <p> |
| A new, empty map value is made using the built-in |
| function <a href="#Making_slices_maps_and_channels"><code>make</code></a>, |
| which takes the map type and an optional capacity hint as arguments: |
| </p> |
| |
| <pre> |
| make(map[string]int) |
| make(map[string]int, 100) |
| </pre> |
| |
| <p> |
| The initial capacity does not bound its size: |
| maps grow to accommodate the number of items |
| stored in them, with the exception of <code>nil</code> maps. |
| A <code>nil</code> map is equivalent to an empty map except that no elements |
| may be added. |
| |
| <h3 id="Channel_types">Channel types</h3> |
| |
| <p> |
| A channel provides a mechanism for |
| <a href="#Go_statements">concurrently executing functions</a> |
| to communicate by |
| <a href="#Send_statements">sending</a> and |
| <a href="#Receive_operator">receiving</a> |
| values of a specified element type. |
| The value of an uninitialized channel is <code>nil</code>. |
| </p> |
| |
| <pre class="ebnf"> |
| ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType . |
| </pre> |
| |
| <p> |
| The optional <code><-</code> operator specifies the channel <i>direction</i>, |
| <i>send</i> or <i>receive</i>. If no direction is given, the channel is |
| <i>bidirectional</i>. |
| A channel may be constrained only to send or only to receive by |
| <a href="#Conversions">conversion</a> or <a href="#Assignments">assignment</a>. |
| </p> |
| |
| <pre> |
| chan T // can be used to send and receive values of type T |
| chan<- float64 // can only be used to send float64s |
| <-chan int // can only be used to receive ints |
| </pre> |
| |
| <p> |
| The <code><-</code> operator associates with the leftmost <code>chan</code> |
| possible: |
| </p> |
| |
| <pre> |
| chan<- chan int // same as chan<- (chan int) |
| chan<- <-chan int // same as chan<- (<-chan int) |
| <-chan <-chan int // same as <-chan (<-chan int) |
| chan (<-chan int) |
| </pre> |
| |
| <p> |
| A new, initialized channel |
| value can be made using the built-in function |
| <a href="#Making_slices_maps_and_channels"><code>make</code></a>, |
| which takes the channel type and an optional <i>capacity</i> as arguments: |
| </p> |
| |
| <pre> |
| make(chan int, 100) |
| </pre> |
| |
| <p> |
| The capacity, in number of elements, sets the size of the buffer in the channel. |
| If the capacity is zero or absent, the channel is unbuffered and communication |
| succeeds only when both a sender and receiver are ready. Otherwise, the channel |
| is buffered and communication succeeds without blocking if the buffer |
| is not full (sends) or not empty (receives). |
| A <code>nil</code> channel is never ready for communication. |
| </p> |
| |
| <p> |
| A channel may be closed with the built-in function |
| <a href="#Close"><code>close</code></a>. |
| The multi-valued assignment form of the |
| <a href="#Receive_operator">receive operator</a> |
| reports whether a received value was sent before |
| the channel was closed. |
| </p> |
| |
| <p> |
| A single channel may be used in |
| <a href="#Send_statements">send statements</a>, |
| <a href="#Receive_operator">receive operations</a>, |
| and calls to the built-in functions |
| <a href="#Length_and_capacity"><code>cap</code></a> and |
| <a href="#Length_and_capacity"><code>len</code></a> |
| by any number of goroutines without further synchronization. |
| Channels act as first-in-first-out queues. |
| For example, if one goroutine sends values on a channel |
| and a second goroutine receives them, the values are |
| received in the order sent. |
| </p> |
| |
| <h2 id="Properties_of_types_and_values">Properties of types and values</h2> |
| |
| <h3 id="Type_identity">Type identity</h3> |
| |
| <p> |
| Two types are either <i>identical</i> or <i>different</i>. |
| </p> |
| |
| <p> |
| A <a href="#Type_definitions">defined type</a> is always different from any other type. |
| Otherwise, two types are identical if their <a href="#Types">underlying</a> type literals are |
| structurally equivalent; that is, they have the same literal structure and corresponding |
| components have identical types. In detail: |
| </p> |
| |
| <ul> |
| <li>Two array types are identical if they have identical element types and |
| the same array length.</li> |
| |
| <li>Two slice types are identical if they have identical element types.</li> |
| |
| <li>Two struct types are identical if they have the same sequence of fields, |
| and if corresponding fields have the same names, and identical types, |
| and identical tags. |
| <a href="#Exported_identifiers">Non-exported</a> field names from different |
| packages are always different.</li> |
| |
| <li>Two pointer types are identical if they have identical base types.</li> |
| |
| <li>Two function types are identical if they have the same number of parameters |
| and result values, corresponding parameter and result types are |
| identical, and either both functions are variadic or neither is. |
| Parameter and result names are not required to match.</li> |
| |
| <li>Two interface types are identical if they have the same set of methods |
| with the same names and identical function types. |
| <a href="#Exported_identifiers">Non-exported</a> method names from different |
| packages are always different. The order of the methods is irrelevant.</li> |
| |
| <li>Two map types are identical if they have identical key and element types.</li> |
| |
| <li>Two channel types are identical if they have identical element types and |
| the same direction.</li> |
| </ul> |
| |
| <p> |
| Given the declarations |
| </p> |
| |
| <pre> |
| type ( |
| A0 = []string |
| A1 = A0 |
| A2 = struct{ a, b int } |
| A3 = int |
| A4 = func(A3, float64) *A0 |
| A5 = func(x int, _ float64) *[]string |
| ) |
| |
| type ( |
| B0 A0 |
| B1 []string |
| B2 struct{ a, b int } |
| B3 struct{ a, c int } |
| B4 func(int, float64) *B0 |
| B5 func(x int, y float64) *A1 |
| ) |
| |
| type C0 = B0 |
| </pre> |
| |
| <p> |
| these types are identical: |
| </p> |
| |
| <pre> |
| A0, A1, and []string |
| A2 and struct{ a, b int } |
| A3 and int |
| A4, func(int, float64) *[]string, and A5 |
| |
| B0 and C0 |
| []int and []int |
| struct{ a, b *T5 } and struct{ a, b *T5 } |
| func(x int, y float64) *[]string, func(int, float64) (result *[]string), and A5 |
| </pre> |
| |
| <p> |
| <code>B0</code> and <code>B1</code> are different because they are new types |
| created by distinct <a href="#Type_definitions">type definitions</a>; |
| <code>func(int, float64) *B0</code> and <code>func(x int, y float64) *[]string</code> |
| are different because <code>B0</code> is different from <code>[]string</code>. |
| </p> |
| |
| |
| <h3 id="Assignability">Assignability</h3> |
| |
| <p> |
| A value <code>x</code> is <i>assignable</i> to a <a href="#Variables">variable</a> of type <code>T</code> |
| ("<code>x</code> is assignable to <code>T</code>") if one of the following conditions applies: |
| </p> |
| |
| <ul> |
| <li> |
| <code>x</code>'s type is identical to <code>T</code>. |
| </li> |
| <li> |
| <code>x</code>'s type <code>V</code> and <code>T</code> have identical |
| <a href="#Types">underlying types</a> and at least one of <code>V</code> |
| or <code>T</code> is not a <a href="#Type_definitions">defined</a> type. |
| </li> |
| <li> |
| <code>T</code> is an interface type and |
| <code>x</code> <a href="#Interface_types">implements</a> <code>T</code>. |
| </li> |
| <li> |
| <code>x</code> is a bidirectional channel value, <code>T</code> is a channel type, |
| <code>x</code>'s type <code>V</code> and <code>T</code> have identical element types, |
| and at least one of <code>V</code> or <code>T</code> is not a defined type. |
| </li> |
| <li> |
| <code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code> |
| is a pointer, function, slice, map, channel, or interface type. |
| </li> |
| <li> |
| <code>x</code> is an untyped <a href="#Constants">constant</a> |
| <a href="#Representability">representable</a> |
| by a value of type <code>T</code>. |
| </li> |
| </ul> |
| |
| |
| <h3 id="Representability">Representability</h3> |
| |
| <p> |
| A <a href="#Constants">constant</a> <code>x</code> is <i>representable</i> |
| by a value of type <code>T</code> if one of the following conditions applies: |
| </p> |
| |
| <ul> |
| <li> |
| <code>x</code> is in the set of values <a href="#Types">determined</a> by <code>T</code>. |
| </li> |
| |
| <li> |
| <code>T</code> is a floating-point type and <code>x</code> can be rounded to <code>T</code>'s |
| precision without overflow. Rounding uses IEEE 754 round-to-even rules but with an IEEE |
| negative zero further simplified to an unsigned zero. Note that constant values never result |
| in an IEEE negative zero, NaN, or infinity. |
| </li> |
| |
| <li> |
| <code>T</code> is a complex type, and <code>x</code>'s |
| <a href="#Complex_numbers">components</a> <code>real(x)</code> and <code>imag(x)</code> |
| are representable by values of <code>T</code>'s component type (<code>float32</code> or |
| <code>float64</code>). |
| </li> |
| </ul> |
| |
| <pre> |
| x T x is representable by a value of T because |
| |
| 'a' byte 97 is in the set of byte values |
| 97 rune rune is an alias for int32, and 97 is in the set of 32-bit integers |
| "foo" string "foo" is in the set of string values |
| 1024 int16 1024 is in the set of 16-bit integers |
| 42.0 byte 42 is in the set of unsigned 8-bit integers |
| 1e10 uint64 10000000000 is in the set of unsigned 64-bit integers |
| 2.718281828459045 float32 2.718281828459045 rounds to 2.7182817 which is in the set of float32 values |
| -1e-1000 float64 -1e-1000 rounds to IEEE -0.0 which is further simplified to 0.0 |
| 0i int 0 is an integer value |
| (42 + 0i) float32 42.0 (with zero imaginary part) is in the set of float32 values |
| </pre> |
| |
| <pre> |
| x T x is not representable by a value of T because |
| |
| 0 bool 0 is not in the set of boolean values |
| 'a' string 'a' is a rune, it is not in the set of string values |
| 1024 byte 1024 is not in the set of unsigned 8-bit integers |
| -1 uint16 -1 is not in the set of unsigned 16-bit integers |
| 1.1 int 1.1 is not an integer value |
| 42i float32 (0 + 42i) is not in the set of float32 values |
| 1e1000 float64 1e1000 overflows to IEEE +Inf after rounding |
| </pre> |
| |
| |
| <h2 id="Blocks">Blocks</h2> |
| |
| <p> |
| A <i>block</i> is a possibly empty sequence of declarations and statements |
| within matching brace brackets. |
| </p> |
| |
| <pre class="ebnf"> |
| Block = "{" StatementList "}" . |
| StatementList = { Statement ";" } . |
| </pre> |
| |
| <p> |
| In addition to explicit blocks in the source code, there are implicit blocks: |
| </p> |
| |
| <ol> |
| <li>The <i>universe block</i> encompasses all Go source text.</li> |
| |
| <li>Each <a href="#Packages">package</a> has a <i>package block</i> containing all |
| Go source text for that package.</li> |
| |
| <li>Each file has a <i>file block</i> containing all Go source text |
| in that file.</li> |
| |
| <li>Each <a href="#If_statements">"if"</a>, |
| <a href="#For_statements">"for"</a>, and |
| <a href="#Switch_statements">"switch"</a> |
| statement is considered to be in its own implicit block.</li> |
| |
| <li>Each clause in a <a href="#Switch_statements">"switch"</a> |
| or <a href="#Select_statements">"select"</a> statement |
| acts as an implicit block.</li> |
| </ol> |
| |
| <p> |
| Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>. |
| </p> |
| |
| |
| <h2 id="Declarations_and_scope">Declarations and scope</h2> |
| |
| <p> |
| A <i>declaration</i> binds a non-<a href="#Blank_identifier">blank</a> identifier to a |
| <a href="#Constant_declarations">constant</a>, |
| <a href="#Type_declarations">type</a>, |
| <a href="#Variable_declarations">variable</a>, |
| <a href="#Function_declarations">function</a>, |
| <a href="#Labeled_statements">label</a>, or |
| <a href="#Import_declarations">package</a>. |
| Every identifier in a program must be declared. |
| No identifier may be declared twice in the same block, and |
| no identifier may be declared in both the file and package block. |
| </p> |
| |
| <p> |
| The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier |
| in a declaration, but it does not introduce a binding and thus is not declared. |
| In the package block, the identifier <code>init</code> may only be used for |
| <a href="#Package_initialization"><code>init</code> function</a> declarations, |
| and like the blank identifier it does not introduce a new binding. |
| </p> |
| |
| <pre class="ebnf"> |
| Declaration = ConstDecl | TypeDecl | VarDecl . |
| TopLevelDecl = Declaration | FunctionDecl | MethodDecl . |
| </pre> |
| |
| <p> |
| The <i>scope</i> of a declared identifier is the extent of source text in which |
| the identifier denotes the specified constant, type, variable, function, label, or package. |
| </p> |
| |
| <p> |
| Go is lexically scoped using <a href="#Blocks">blocks</a>: |
| </p> |
| |
| <ol> |
| <li>The scope of a <a href="#Predeclared_identifiers">predeclared identifier</a> is the universe block.</li> |
| |
| <li>The scope of an identifier denoting a constant, type, variable, |
| or function (but not method) declared at top level (outside any |
| function) is the package block.</li> |
| |
| <li>The scope of the package name of an imported package is the file block |
| of the file containing the import declaration.</li> |
| |
| <li>The scope of an identifier denoting a method receiver, function parameter, |
| or result variable is the function body.</li> |
| |
| <li>The scope of a constant or variable identifier declared |
| inside a function begins at the end of the ConstSpec or VarSpec |
| (ShortVarDecl for short variable declarations) |
| and ends at the end of the innermost containing block.</li> |
| |
| <li>The scope of a type identifier declared inside a function |
| begins at the identifier in the TypeSpec |
| and ends at the end of the innermost containing block.</li> |
| </ol> |
| |
| <p> |
| An identifier declared in a block may be redeclared in an inner block. |
| While the identifier of the inner declaration is in scope, it denotes |
| the entity declared by the inner declaration. |
| </p> |
| |
| <p> |
| The <a href="#Package_clause">package clause</a> is not a declaration; the package name |
| does not appear in any scope. Its purpose is to identify the files belonging |
| to the same <a href="#Packages">package</a> and to specify the default package name for import |
| declarations. |
| </p> |
| |
| |
| <h3 id="Label_scopes">Label scopes</h3> |
| |
| <p> |
| Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are |
| used in the <a href="#Break_statements">"break"</a>, |
| <a href="#Continue_statements">"continue"</a>, and |
| <a href="#Goto_statements">"goto"</a> statements. |
| It is illegal to define a label that is never used. |
| In contrast to other identifiers, labels are not block scoped and do |
| not conflict with identifiers that are not labels. The scope of a label |
| is the body of the function in which it is declared and excludes |
| the body of any nested function. |
| </p> |
| |
| |
| <h3 id="Blank_identifier">Blank identifier</h3> |
| |
| <p> |
| The <i>blank identifier</i> is represented by the underscore character <code>_</code>. |
| It serves as an anonymous placeholder instead of a regular (non-blank) |
| identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>, |
| as an <a href="#Operands">operand</a>, and in <a href="#Assignments">assignments</a>. |
| </p> |
| |
| |
| <h3 id="Predeclared_identifiers">Predeclared identifiers</h3> |
| |
| <p> |
| The following identifiers are implicitly declared in the |
| <a href="#Blocks">universe block</a>: |
| </p> |
| <pre class="grammar"> |
| Types: |
| bool byte complex64 complex128 error float32 float64 |
| int int8 int16 int32 int64 rune string |
| uint uint8 uint16 uint32 uint64 uintptr |
| |
| Constants: |
| true false iota |
| |
| Zero value: |
| nil |
| |
| Functions: |
| append cap close complex copy delete imag len |
| make new panic print println real recover |
| </pre> |
| |
| |
| <h3 id="Exported_identifiers">Exported identifiers</h3> |
| |
| <p> |
| An identifier may be <i>exported</i> to permit access to it from another package. |
| An identifier is exported if both: |
| </p> |
| <ol> |
| <li>the first character of the identifier's name is a Unicode upper case |
| letter (Unicode class "Lu"); and</li> |
| <li>the identifier is declared in the <a href="#Blocks">package block</a> |
| or it is a <a href="#Struct_types">field name</a> or |
| <a href="#MethodName">method name</a>.</li> |
| </ol> |
| <p> |
| All other identifiers are not exported. |
| </p> |
| |
| |
| <h3 id="Uniqueness_of_identifiers">Uniqueness of identifiers</h3> |
| |
| <p> |
| Given a set of identifiers, an identifier is called <i>unique</i> if it is |
| <i>different</i> from every other in the set. |
| Two identifiers are different if they are spelled differently, or if they |
| appear in different <a href="#Packages">packages</a> and are not |
| <a href="#Exported_identifiers">exported</a>. Otherwise, they are the same. |
| </p> |
| |
| <h3 id="Constant_declarations">Constant declarations</h3> |
| |
| <p> |
| A constant declaration binds a list of identifiers (the names of |
| the constants) to the values of a list of <a href="#Constant_expressions">constant expressions</a>. |
| The number of identifiers must be equal |
| to the number of expressions, and the <i>n</i>th identifier on |
| the left is bound to the value of the <i>n</i>th expression on the |
| right. |
| </p> |
| |
| <pre class="ebnf"> |
| ConstDecl = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) . |
| ConstSpec = IdentifierList [ [ Type ] "=" ExpressionList ] . |
| |
| IdentifierList = identifier { "," identifier } . |
| ExpressionList = Expression { "," Expression } . |
| </pre> |
| |
| <p> |
| If the type is present, all constants take the type specified, and |
| the expressions must be <a href="#Assignability">assignable</a> to that type. |
| If the type is omitted, the constants take the |
| individual types of the corresponding expressions. |
| If the expression values are untyped <a href="#Constants">constants</a>, |
| the declared constants remain untyped and the constant identifiers |
| denote the constant values. For instance, if the expression is a |
| floating-point literal, the constant identifier denotes a floating-point |
| constant, even if the literal's fractional part is zero. |
| </p> |
| |
| <pre> |
| const Pi float64 = 3.14159265358979323846 |
| const zero = 0.0 // untyped floating-point constant |
| const ( |
| size int64 = 1024 |
| eof = -1 // untyped integer constant |
| ) |
| const a, b, c = 3, 4, "foo" // a = 3, b = 4, c = "foo", untyped integer and string constants |
| const u, v float32 = 0, 3 // u = 0.0, v = 3.0 |
| </pre> |
| |
| <p> |
| Within a parenthesized <code>const</code> declaration list the |
| expression list may be omitted from any but the first ConstSpec. |
| Such an empty list is equivalent to the textual substitution of the |
| first preceding non-empty expression list and its type if any. |
| Omitting the list of expressions is therefore equivalent to |
| repeating the previous list. The number of identifiers must be equal |
| to the number of expressions in the previous list. |
| Together with the <a href="#Iota"><code>iota</code> constant generator</a> |
| this mechanism permits light-weight declaration of sequential values: |
| </p> |
| |
| <pre> |
| const ( |
| Sunday = iota |
| Monday |
| Tuesday |
| Wednesday |
| Thursday |
| Friday |
| Partyday |
| numberOfDays // this constant is not exported |
| ) |
| </pre> |
| |
| |
| <h3 id="Iota">Iota</h3> |
| |
| <p> |
| Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier |
| <code>iota</code> represents successive untyped integer <a href="#Constants"> |
| constants</a>. Its value is the index of the respective <a href="#ConstSpec">ConstSpec</a> |
| in that constant declaration, starting at zero. |
| It can be used to construct a set of related constants: |
| </p> |
| |
| <pre> |
| const ( |
| c0 = iota // c0 == 0 |
| c1 = iota // c1 == 1 |
| c2 = iota // c2 == 2 |
| ) |
| |
| const ( |
| a = 1 << iota // a == 1 (iota == 0) |
| b = 1 << iota // b == 2 (iota == 1) |
| c = 3 // c == 3 (iota == 2, unused) |
| d = 1 << iota // d == 8 (iota == 3) |
| ) |
| |
| const ( |
| u = iota * 42 // u == 0 (untyped integer constant) |
| v float64 = iota * 42 // v == 42.0 (float64 constant) |
| w = iota * 42 // w == 84 (untyped integer constant) |
| ) |
| |
| const x = iota // x == 0 |
| const y = iota // y == 0 |
| </pre> |
| |
| <p> |
| By definition, multiple uses of <code>iota</code> in the same ConstSpec all have the same value: |
| </p> |
| |
| <pre> |
| const ( |
| bit0, mask0 = 1 << iota, 1<<iota - 1 // bit0 == 1, mask0 == 0 (iota == 0) |
| bit1, mask1 // bit1 == 2, mask1 == 1 (iota == 1) |
| _, _ // (iota == 2, unused) |
| bit3, mask3 // bit3 == 8, mask3 == 7 (iota == 3) |
| ) |
| </pre> |
| |
| <p> |
| This last example exploits the <a href="#Constant_declarations">implicit repetition</a> |
| of the last non-empty expression list. |
| </p> |
| |
| |
| <h3 id="Type_declarations">Type declarations</h3> |
| |
| <p> |
| A type declaration binds an identifier, the <i>type name</i>, to a <a href="#Types">type</a>. |
| Type declarations come in two forms: alias declarations and type definitions. |
| <p> |
| |
| <pre class="ebnf"> |
| TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) . |
| TypeSpec = AliasDecl | TypeDef . |
| </pre> |
| |
| <h4 id="Alias_declarations">Alias declarations</h4> |
| |
| <p> |
| An alias declaration binds an identifier to the given type. |
| </p> |
| |
| <pre class="ebnf"> |
| AliasDecl = identifier "=" Type . |
| </pre> |
| |
| <p> |
| Within the <a href="#Declarations_and_scope">scope</a> of |
| the identifier, it serves as an <i>alias</i> for the type. |
| </p> |
| |
| <pre> |
| type ( |
| nodeList = []*Node // nodeList and []*Node are identical types |
| Polar = polar // Polar and polar denote identical types |
| ) |
| </pre> |
| |
| |
| <h4 id="Type_definitions">Type definitions</h4> |
| |
| <p> |
| A type definition creates a new, distinct type with the same |
| <a href="#Types">underlying type</a> and operations as the given type, |
| and binds an identifier to it. |
| </p> |
| |
| <pre class="ebnf"> |
| TypeDef = identifier Type . |
| </pre> |
| |
| <p> |
| The new type is called a <i>defined type</i>. |
| It is <a href="#Type_identity">different</a> from any other type, |
| including the type it is created from. |
| </p> |
| |
| <pre> |
| type ( |
| Point struct{ x, y float64 } // Point and struct{ x, y float64 } are different types |
| polar Point // polar and Point denote different types |
| ) |
| |
| type TreeNode struct { |
| left, right *TreeNode |
| value *Comparable |
| } |
| |
| type Block interface { |
| BlockSize() int |
| Encrypt(src, dst []byte) |
| Decrypt(src, dst []byte) |
| } |
| </pre> |
| |
| <p> |
| A defined type may have <a href="#Method_declarations">methods</a> associated with it. |
| It does not inherit any methods bound to the given type, |
| but the <a href="#Method_sets">method set</a> |
| of an interface type or of elements of a composite type remains unchanged: |
| </p> |
| |
| <pre> |
| // A Mutex is a data type with two methods, Lock and Unlock. |
| type Mutex struct { /* Mutex fields */ } |
| func (m *Mutex) Lock() { /* Lock implementation */ } |
| func (m *Mutex) Unlock() { /* Unlock implementation */ } |
| |
| // NewMutex has the same composition as Mutex but its method set is empty. |
| type NewMutex Mutex |
| |
| // The method set of PtrMutex's underlying type *Mutex remains unchanged, |
| // but the method set of PtrMutex is empty. |
| type PtrMutex *Mutex |
| |
| // The method set of *PrintableMutex contains the methods |
| // Lock and Unlock bound to its embedded field Mutex. |
| type PrintableMutex struct { |
| Mutex |
| } |
| |
| // MyBlock is an interface type that has the same method set as Block. |
| type MyBlock Block |
| </pre> |
| |
| <p> |
| Type definitions may be used to define different boolean, numeric, |
| or string types and associate methods with them: |
| </p> |
| |
| <pre> |
| type TimeZone int |
| |
| const ( |
| EST TimeZone = -(5 + iota) |
| CST |
| MST |
| PST |
| ) |
| |
| func (tz TimeZone) String() string { |
| return fmt.Sprintf("GMT%+dh", tz) |
| } |
| </pre> |
| |
| |
| <h3 id="Variable_declarations">Variable declarations</h3> |
| |
| <p> |
| A variable declaration creates one or more <a href="#Variables">variables</a>, |
| binds corresponding identifiers to them, and gives each a type and an initial value. |
| </p> |
| |
| <pre class="ebnf"> |
| VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) . |
| VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) . |
| </pre> |
| |
| <pre> |
| var i int |
| var U, V, W float64 |
| var k = 0 |
| var x, y float32 = -1, -2 |
| var ( |
| i int |
| u, v, s = 2.0, 3.0, "bar" |
| ) |
| var re, im = complexSqrt(-1) |
| var _, found = entries[name] // map lookup; only interested in "found" |
| </pre> |
| |
| <p> |
| If a list of expressions is given, the variables are initialized |
| with the expressions following the rules for <a href="#Assignments">assignments</a>. |
| Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>. |
| </p> |
| |
| <p> |
| If a type is present, each variable is given that type. |
| Otherwise, each variable is given the type of the corresponding |
| initialization value in the assignment. |
| If that value is an untyped constant, it is first |
| <a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>; |
| if it is an untyped boolean value, it is first converted to type <code>bool</code>. |
| The predeclared value <code>nil</code> cannot be used to initialize a variable |
| with no explicit type. |
| </p> |
| |
| <pre> |
| var d = math.Sin(0.5) // d is float64 |
| var i = 42 // i is int |
| var t, ok = x.(T) // t is T, ok is bool |
| var n = nil // illegal |
| </pre> |
| |
| <p> |
| Implementation restriction: A compiler may make it illegal to declare a variable |
| inside a <a href="#Function_declarations">function body</a> if the variable is |
| never used. |
| </p> |
| |
| <h3 id="Short_variable_declarations">Short variable declarations</h3> |
| |
| <p> |
| A <i>short variable declaration</i> uses the syntax: |
| </p> |
| |
| <pre class="ebnf"> |
| ShortVarDecl = IdentifierList ":=" ExpressionList . |
| </pre> |
| |
| <p> |
| It is shorthand for a regular <a href="#Variable_declarations">variable declaration</a> |
| with initializer expressions but no types: |
| </p> |
| |
| <pre class="grammar"> |
| "var" IdentifierList = ExpressionList . |
| </pre> |
| |
| <pre> |
| i, j := 0, 10 |
| f := func() int { return 7 } |
| ch := make(chan int) |
| r, w := os.Pipe(fd) // os.Pipe() returns two values |
| _, y, _ := coord(p) // coord() returns three values; only interested in y coordinate |
| </pre> |
| |
| <p> |
| Unlike regular variable declarations, a short variable declaration may <i>redeclare</i> |
| variables provided they were originally declared earlier in the same block |
| (or the parameter lists if the block is the function body) with the same type, |
| and at least one of the non-<a href="#Blank_identifier">blank</a> variables is new. |
| As a consequence, redeclaration can only appear in a multi-variable short declaration. |
| Redeclaration does not introduce a new variable; it just assigns a new value to the original. |
| </p> |
| |
| <pre> |
| field1, offset := nextField(str, 0) |
| field2, offset := nextField(str, offset) // redeclares offset |
| a, a := 1, 2 // illegal: double declaration of a or no new variable if a was declared elsewhere |
| </pre> |
| |
| <p> |
| Short variable declarations may appear only inside functions. |
| In some contexts such as the initializers for |
| <a href="#If_statements">"if"</a>, |
| <a href="#For_statements">"for"</a>, or |
| <a href="#Switch_statements">"switch"</a> statements, |
| they can be used to declare local temporary variables. |
| </p> |
| |
| <h3 id="Function_declarations">Function declarations</h3> |
| |
| <p> |
| A function declaration binds an identifier, the <i>function name</i>, |
| to a function. |
| </p> |
| |
| <pre class="ebnf"> |
| FunctionDecl = "func" FunctionName Signature [ FunctionBody ] . |
| FunctionName = identifier . |
| FunctionBody = Block . |
| </pre> |
| |
| <p> |
| If the function's <a href="#Function_types">signature</a> declares |
| result parameters, the function body's statement list must end in |
| a <a href="#Terminating_statements">terminating statement</a>. |
| </p> |
| |
| <pre> |
| func IndexRune(s string, r rune) int { |
| for i, c := range s { |
| if c == r { |
| return i |
| } |
| } |
| // invalid: missing return statement |
| } |
| </pre> |
| |
| <p> |
| A function declaration may omit the body. Such a declaration provides the |
| signature for a function implemented outside Go, such as an assembly routine. |
| </p> |
| |
| <pre> |
| func min(x int, y int) int { |
| if x < y { |
| return x |
| } |
| return y |
| } |
| |
| func flushICache(begin, end uintptr) // implemented externally |
| </pre> |
| |
| <h3 id="Method_declarations">Method declarations</h3> |
| |
| <p> |
| A method is a <a href="#Function_declarations">function</a> with a <i>receiver</i>. |
| A method declaration binds an identifier, the <i>method name</i>, to a method, |
| and associates the method with the receiver's <i>base type</i>. |
| </p> |
| |
| <pre class="ebnf"> |
| MethodDecl = "func" Receiver MethodName Signature [ FunctionBody ] . |
| Receiver = Parameters . |
| </pre> |
| |
| <p> |
| The receiver is specified via an extra parameter section preceding the method |
| name. That parameter section must declare a single non-variadic parameter, the receiver. |
| Its type must be of the form <code>T</code> or <code>*T</code> (possibly using |
| parentheses) where <code>T</code> is a type name. The type denoted by <code>T</code> is called |
| the receiver <i>base type</i>; it must not be a pointer or interface type and |
| it must be <a href="#Type_definitions">defined</a> in the same package as the method. |
| The method is said to be <i>bound</i> to the base type and the method name |
| is visible only within <a href="#Selectors">selectors</a> for type <code>T</code> |
| or <code>*T</code>. |
| </p> |
| |
| <p> |
| A non-<a href="#Blank_identifier">blank</a> receiver identifier must be |
| <a href="#Uniqueness_of_identifiers">unique</a> in the method signature. |
| If the receiver's value is not referenced inside the body of the method, |
| its identifier may be omitted in the declaration. The same applies in |
| general to parameters of functions and methods. |
| </p> |
| |
| <p> |
| For a base type, the non-blank names of methods bound to it must be unique. |
| If the base type is a <a href="#Struct_types">struct type</a>, |
| the non-blank method and field names must be distinct. |
| </p> |
| |
| <p> |
| Given type <code>Point</code>, the declarations |
| </p> |
| |
| <pre> |
| func (p *Point) Length() float64 { |
| return math.Sqrt(p.x * p.x + p.y * p.y) |
| } |
| |
| func (p *Point) Scale(factor float64) { |
| p.x *= factor |
| p.y *= factor |
| } |
| </pre> |
| |
| <p> |
| bind the methods <code>Length</code> and <code>Scale</code>, |
| with receiver type <code>*Point</code>, |
| to the base type <code>Point</code>. |
| </p> |
| |
| <p> |
| The type of a method is the type of a function with the receiver as first |
| argument. For instance, the method <code>Scale</code> has type |
| </p> |
| |
| <pre> |
| func(p *Point, factor float64) |
| </pre> |
| |
| <p> |
| However, a function declared this way is not a method. |
| </p> |
| |
| |
| <h2 id="Expressions">Expressions</h2> |
| |
| <p> |
| An expression specifies the computation of a value by applying |
| operators and functions to operands. |
| </p> |
| |
| <h3 id="Operands">Operands</h3> |
| |
| <p> |
| Operands denote the elementary values in an expression. An operand may be a |
| literal, a (possibly <a href="#Qualified_identifiers">qualified</a>) |
| non-<a href="#Blank_identifier">blank</a> identifier denoting a |
| <a href="#Constant_declarations">constant</a>, |
| <a href="#Variable_declarations">variable</a>, or |
| <a href="#Function_declarations">function</a>, |
| or a parenthesized expression. |
| </p> |
| |
| <p> |
| The <a href="#Blank_identifier">blank identifier</a> may appear as an |
| operand only on the left-hand side of an <a href="#Assignments">assignment</a>. |
| </p> |
| |
| <pre class="ebnf"> |
| Operand = Literal | OperandName | "(" Expression ")" . |
| Literal = BasicLit | CompositeLit | FunctionLit . |
| BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit . |
| OperandName = identifier | QualifiedIdent. |
| </pre> |
| |
| <h3 id="Qualified_identifiers">Qualified identifiers</h3> |
| |
| <p> |
| A qualified identifier is an identifier qualified with a package name prefix. |
| Both the package name and the identifier must not be |
| <a href="#Blank_identifier">blank</a>. |
| </p> |
| |
| <pre class="ebnf"> |
| QualifiedIdent = PackageName "." identifier . |
| </pre> |
| |
| <p> |
| A qualified identifier accesses an identifier in a different package, which |
| must be <a href="#Import_declarations">imported</a>. |
| The identifier must be <a href="#Exported_identifiers">exported</a> and |
| declared in the <a href="#Blocks">package block</a> of that package. |
| </p> |
| |
| <pre> |
| math.Sin // denotes the Sin function in package math |
| </pre> |
| |
| <h3 id="Composite_literals">Composite literals</h3> |
| |
| <p> |
| Composite literals construct values for structs, arrays, slices, and maps |
| and create a new value each time they are evaluated. |
| They consist of the type of the literal followed by a brace-bound list of elements. |
| Each element may optionally be preceded by a corresponding key. |
| </p> |
| |
| <pre class="ebnf"> |
| CompositeLit = LiteralType LiteralValue . |
| LiteralType = StructType | ArrayType | "[" "..." "]" ElementType | |
| SliceType | MapType | TypeName . |
| LiteralValue = "{" [ ElementList [ "," ] ] "}" . |
| ElementList = KeyedElement { "," KeyedElement } . |
| KeyedElement = [ Key ":" ] Element . |
| Key = FieldName | Expression | LiteralValue . |
| FieldName = identifier . |
| Element = Expression | LiteralValue . |
| </pre> |
| |
| <p> |
| The LiteralType's underlying type must be a struct, array, slice, or map type |
| (the grammar enforces this constraint except when the type is given |
| as a TypeName). |
| The types of the elements and keys must be <a href="#Assignability">assignable</a> |
| to the respective field, element, and key types of the literal type; |
| there is no additional conversion. |
| The key is interpreted as a field name for struct literals, |
| an index for array and slice literals, and a key for map literals. |
| For map literals, all elements must have a key. It is an error |
| to specify multiple elements with the same field name or |
| constant key value. For non-constant map keys, see the section on |
| <a href="#Order_of_evaluation">evaluation order</a>. |
| </p> |
| |
| <p> |
| For struct literals the following rules apply: |
| </p> |
| <ul> |
| <li>A key must be a field name declared in the struct type. |
| </li> |
| <li>An element list that does not contain any keys must |
| list an element for each struct field in the |
| order in which the fields are declared. |
| </li> |
| <li>If any element has a key, every element must have a key. |
| </li> |
| <li>An element list that contains keys does not need to |
| have an element for each struct field. Omitted fields |
| get the zero value for that field. |
| </li> |
| <li>A literal may omit the element list; such a literal evaluates |
| to the zero value for its type. |
| </li> |
| <li>It is an error to specify an element for a non-exported |
| field of a struct belonging to a different package. |
| </li> |
| </ul> |
| |
| <p> |
| Given the declarations |
| </p> |
| <pre> |
| type Point3D struct { x, y, z float64 } |
| type Line struct { p, q Point3D } |
| </pre> |
| |
| <p> |
| one may write |
| </p> |
| |
| <pre> |
| origin := Point3D{} // zero value for Point3D |
| line := Line{origin, Point3D{y: -4, z: 12.3}} // zero value for line.q.x |
| </pre> |
| |
| <p> |
| For array and slice literals the following rules apply: |
| </p> |
| <ul> |
| <li>Each element has an associated integer index marking |
| its position in the array. |
| </li> |
| <li>An element with a key uses the key as its index. The |
| key must be a non-negative constant |
| <a href="#Representability">representable</a> by |
| a value of type <code>int</code>; and if it is typed |
| it must be of integer type. |
| </li> |
| <li>An element without a key uses the previous element's index plus one. |
| If the first element has no key, its index is zero. |
| </li> |
| </ul> |
| |
| <p> |
| <a href="#Address_operators">Taking the address</a> of a composite literal |
| generates a pointer to a unique <a href="#Variables">variable</a> initialized |
| with the literal's value. |
| </p> |
| <pre> |
| var pointer *Point3D = &Point3D{y: 1000} |
| </pre> |
| |
| <p> |
| The length of an array literal is the length specified in the literal type. |
| If fewer elements than the length are provided in the literal, the missing |
| elements are set to the zero value for the array element type. |
| It is an error to provide elements with index values outside the index range |
| of the array. The notation <code>...</code> specifies an array length equal |
| to the maximum element index plus one. |
| </p> |
| |
| <pre> |
| buffer := [10]string{} // len(buffer) == 10 |
| intSet := [6]int{1, 2, 3, 5} // len(intSet) == 6 |
| days := [...]string{"Sat", "Sun"} // len(days) == 2 |
| </pre> |
| |
| <p> |
| A slice literal describes the entire underlying array literal. |
| Thus the length and capacity of a slice literal are the maximum |
| element index plus one. A slice literal has the form |
| </p> |
| |
| <pre> |
| []T{x1, x2, … xn} |
| </pre> |
| |
| <p> |
| and is shorthand for a slice operation applied to an array: |
| </p> |
| |
| <pre> |
| tmp := [n]T{x1, x2, … xn} |
| tmp[0 : n] |
| </pre> |
| |
| <p> |
| Within a composite literal of array, slice, or map type <code>T</code>, |
| elements or map keys that are themselves composite literals may elide the respective |
| literal type if it is identical to the element or key type of <code>T</code>. |
| Similarly, elements or keys that are addresses of composite literals may elide |
| the <code>&T</code> when the element or key type is <code>*T</code>. |
| </p> |
| |
| <pre> |
| [...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}} |
| [][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}} |
| [][]Point{{{0, 1}, {1, 2}}} // same as [][]Point{[]Point{Point{0, 1}, Point{1, 2}}} |
| map[string]Point{"orig": {0, 0}} // same as map[string]Point{"orig": Point{0, 0}} |
| map[Point]string{{0, 0}: "orig"} // same as map[Point]string{Point{0, 0}: "orig"} |
| |
| type PPoint *Point |
| [2]*Point{{1.5, -3.5}, {}} // same as [2]*Point{&Point{1.5, -3.5}, &Point{}} |
| [2]PPoint{{1.5, -3.5}, {}} // same as [2]PPoint{PPoint(&Point{1.5, -3.5}), PPoint(&Point{})} |
| </pre> |
| |
| <p> |
| A parsing ambiguity arises when a composite literal using the |
| TypeName form of the LiteralType appears as an operand between the |
| <a href="#Keywords">keyword</a> and the opening brace of the block |
| of an "if", "for", or "switch" statement, and the composite literal |
| is not enclosed in parentheses, square brackets, or curly braces. |
| In this rare case, the opening brace of the literal is erroneously parsed |
| as the one introducing the block of statements. To resolve the ambiguity, |
| the composite literal must appear within parentheses. |
| </p> |
| |
| <pre> |
| if x == (T{a,b,c}[i]) { … } |
| if (x == T{a,b,c}[i]) { … } |
| </pre> |
| |
| <p> |
| Examples of valid array, slice, and map literals: |
| </p> |
| |
| <pre> |
| // list of prime numbers |
| primes := []int{2, 3, 5, 7, 9, 2147483647} |
| |
| // vowels[ch] is true if ch is a vowel |
| vowels := [128]bool{'a': true, 'e': true, 'i': true, 'o': true, 'u': true, 'y': true} |
| |
| // the array [10]float32{-1, 0, 0, 0, -0.1, -0.1, 0, 0, 0, -1} |
| filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1} |
| |
| // frequencies in Hz for equal-tempered scale (A4 = 440Hz) |
| noteFrequency := map[string]float32{ |
| "C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83, |
| "G0": 24.50, "A0": 27.50, "B0": 30.87, |
| } |
| </pre> |
| |
| |
| <h3 id="Function_literals">Function literals</h3> |
| |
| <p> |
| A function literal represents an anonymous <a href="#Function_declarations">function</a>. |
| </p> |
| |
| <pre class="ebnf"> |
| FunctionLit = "func" Signature FunctionBody . |
| </pre> |
| |
| <pre> |
| func(a, b int, z float64) bool { return a*b < int(z) } |
| </pre> |
| |
| <p> |
| A function literal can be assigned to a variable or invoked directly. |
| </p> |
| |
| <pre> |
| f := func(x, y int) int { return x + y } |
| func(ch chan int) { ch <- ACK }(replyChan) |
| </pre> |
| |
| <p> |
| Function literals are <i>closures</i>: they may refer to variables |
| defined in a surrounding function. Those variables are then shared between |
| the surrounding function and the function literal, and they survive as long |
| as they are accessible. |
| </p> |
| |
| |
| <h3 id="Primary_expressions">Primary expressions</h3> |
| |
| <p> |
| Primary expressions are the operands for unary and binary expressions. |
| </p> |
| |
| <pre class="ebnf"> |
| PrimaryExpr = |
| Operand | |
| Conversion | |
| MethodExpr | |
| PrimaryExpr Selector | |
| PrimaryExpr Index | |
| PrimaryExpr Slice | |
| PrimaryExpr TypeAssertion | |
| PrimaryExpr Arguments . |
| |
| Selector = "." identifier . |
| Index = "[" Expression "]" . |
| Slice = "[" [ Expression ] ":" [ Expression ] "]" | |
| "[" [ Expression ] ":" Expression ":" Expression "]" . |
| TypeAssertion = "." "(" Type ")" . |
| Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" . |
| </pre> |
| |
| |
| <pre> |
| x |
| 2 |
| (s + ".txt") |
| f(3.1415, true) |
| Point{1, 2} |
| m["foo"] |
| s[i : j + 1] |
| obj.color |
| f.p[i].x() |
| </pre> |
| |
| |
| <h3 id="Selectors">Selectors</h3> |
| |
| <p> |
| For a <a href="#Primary_expressions">primary expression</a> <code>x</code> |
| that is not a <a href="#Package_clause">package name</a>, the |
| <i>selector expression</i> |
| </p> |
| |
| <pre> |
| x.f |
| </pre> |
| |
| <p> |
| denotes the field or method <code>f</code> of the value <code>x</code> |
| (or sometimes <code>*x</code>; see below). |
| The identifier <code>f</code> is called the (field or method) <i>selector</i>; |
| it must not be the <a href="#Blank_identifier">blank identifier</a>. |
| The type of the selector expression is the type of <code>f</code>. |
| If <code>x</code> is a package name, see the section on |
| <a href="#Qualified_identifiers">qualified identifiers</a>. |
| </p> |
| |
| <p> |
| A selector <code>f</code> may denote a field or method <code>f</code> of |
| a type <code>T</code>, or it may refer |
| to a field or method <code>f</code> of a nested |
| <a href="#Struct_types">embedded field</a> of <code>T</code>. |
| The number of embedded fields traversed |
| to reach <code>f</code> is called its <i>depth</i> in <code>T</code>. |
| The depth of a field or method <code>f</code> |
| declared in <code>T</code> is zero. |
| The depth of a field or method <code>f</code> declared in |
| an embedded field <code>A</code> in <code>T</code> is the |
| depth of <code>f</code> in <code>A</code> plus one. |
| </p> |
| |
| <p> |
| The following rules apply to selectors: |
| </p> |
| |
| <ol> |
| <li> |
| For a value <code>x</code> of type <code>T</code> or <code>*T</code> |
| where <code>T</code> is not a pointer or interface type, |
| <code>x.f</code> denotes the field or method at the shallowest depth |
| in <code>T</code> where there |
| is such an <code>f</code>. |
| If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a> |
| with shallowest depth, the selector expression is illegal. |
| </li> |
| |
| <li> |
| For a value <code>x</code> of type <code>I</code> where <code>I</code> |
| is an interface type, <code>x.f</code> denotes the actual method with name |
| <code>f</code> of the dynamic value of <code>x</code>. |
| If there is no method with name <code>f</code> in the |
| <a href="#Method_sets">method set</a> of <code>I</code>, the selector |
| expression is illegal. |
| </li> |
| |
| <li> |
| As an exception, if the type of <code>x</code> is a <a href="#Type_definitions">defined</a> |
| pointer type and <code>(*x).f</code> is a valid selector expression denoting a field |
| (but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>. |
| </li> |
| |
| <li> |
| In all other cases, <code>x.f</code> is illegal. |
| </li> |
| |
| <li> |
| If <code>x</code> is of pointer type and has the value |
| <code>nil</code> and <code>x.f</code> denotes a struct field, |
| assigning to or evaluating <code>x.f</code> |
| causes a <a href="#Run_time_panics">run-time panic</a>. |
| </li> |
| |
| <li> |
| If <code>x</code> is of interface type and has the value |
| <code>nil</code>, <a href="#Calls">calling</a> or |
| <a href="#Method_values">evaluating</a> the method <code>x.f</code> |
| causes a <a href="#Run_time_panics">run-time panic</a>. |
| </li> |
| </ol> |
| |
| <p> |
| For example, given the declarations: |
| </p> |
| |
| <pre> |
| type T0 struct { |
| x int |
| } |
| |
| func (*T0) M0() |
| |
| type T1 struct { |
| y int |
| } |
| |
| func (T1) M1() |
| |
| type T2 struct { |
| z int |
| T1 |
| *T0 |
| } |
| |
| func (*T2) M2() |
| |
| type Q *T2 |
| |
| var t T2 // with t.T0 != nil |
| var p *T2 // with p != nil and (*p).T0 != nil |
| var q Q = p |
| </pre> |
| |
| <p> |
| one may write: |
| </p> |
| |
| <pre> |
| t.z // t.z |
| t.y // t.T1.y |
| t.x // (*t.T0).x |
| |
| p.z // (*p).z |
| p.y // (*p).T1.y |
| p.x // (*(*p).T0).x |
| |
| q.x // (*(*q).T0).x (*q).x is a valid field selector |
| |
| p.M0() // ((*p).T0).M0() M0 expects *T0 receiver |
| p.M1() // ((*p).T1).M1() M1 expects T1 receiver |
| p.M2() // p.M2() M2 expects *T2 receiver |
| t.M2() // (&t).M2() M2 expects *T2 receiver, see section on Calls |
| </pre> |
| |
| <p> |
| but the following is invalid: |
| </p> |
| |
| <pre> |
| q.M0() // (*q).M0 is valid but not a field selector |
| </pre> |
| |
| |
| <h3 id="Method_expressions">Method expressions</h3> |
| |
| <p> |
| If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, |
| <code>T.M</code> is a function that is callable as a regular function |
| with the same arguments as <code>M</code> prefixed by an additional |
| argument that is the receiver of the method. |
| </p> |
| |
| <pre class="ebnf"> |
| MethodExpr = ReceiverType "." MethodName . |
| ReceiverType = Type . |
| </pre> |
| |
| <p> |
| Consider a struct type <code>T</code> with two methods, |
| <code>Mv</code>, whose receiver is of type <code>T</code>, and |
| <code>Mp</code>, whose receiver is of type <code>*T</code>. |
| </p> |
| |
| <pre> |
| type T struct { |
| a int |
| } |
| func (tv T) Mv(a int) int { return 0 } // value receiver |
| func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver |
| |
| var t T |
| </pre> |
| |
| <p> |
| The expression |
| </p> |
| |
| <pre> |
| T.Mv |
| </pre> |
| |
| <p> |
| yields a function equivalent to <code>Mv</code> but |
| with an explicit receiver as its first argument; it has signature |
| </p> |
| |
| <pre> |
| func(tv T, a int) int |
| </pre> |
| |
| <p> |
| That function may be called normally with an explicit receiver, so |
| these five invocations are equivalent: |
| </p> |
| |
| <pre> |
| t.Mv(7) |
| T.Mv(t, 7) |
| (T).Mv(t, 7) |
| f1 := T.Mv; f1(t, 7) |
| f2 := (T).Mv; f2(t, 7) |
| </pre> |
| |
| <p> |
| Similarly, the expression |
| </p> |
| |
| <pre> |
| (*T).Mp |
| </pre> |
| |
| <p> |
| yields a function value representing <code>Mp</code> with signature |
| </p> |
| |
| <pre> |
| func(tp *T, f float32) float32 |
| </pre> |
| |
| <p> |
| For a method with a value receiver, one can derive a function |
| with an explicit pointer receiver, so |
| </p> |
| |
| <pre> |
| (*T).Mv |
| </pre> |
| |
| <p> |
| yields a function value representing <code>Mv</code> with signature |
| </p> |
| |
| <pre> |
| func(tv *T, a int) int |
| </pre> |
| |
| <p> |
| Such a function indirects through the receiver to create a value |
| to pass as the receiver to the underlying method; |
| the method does not overwrite the value whose address is passed in |
| the function call. |
| </p> |
| |
| <p> |
| The final case, a value-receiver function for a pointer-receiver method, |
| is illegal because pointer-receiver methods are not in the method set |
| of the value type. |
| </p> |
| |
| <p> |
| Function values derived from methods are called with function call syntax; |
| the receiver is provided as the first argument to the call. |
| That is, given <code>f := T.Mv</code>, <code>f</code> is invoked |
| as <code>f(t, 7)</code> not <code>t.f(7)</code>. |
| To construct a function that binds the receiver, use a |
| <a href="#Function_literals">function literal</a> or |
| <a href="#Method_values">method value</a>. |
| </p> |
| |
| <p> |
| It is legal to derive a function value from a method of an interface type. |
| The resulting function takes an explicit receiver of that interface type. |
| </p> |
| |
| <h3 id="Method_values">Method values</h3> |
| |
| <p> |
| If the expression <code>x</code> has static type <code>T</code> and |
| <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, |
| <code>x.M</code> is called a <i>method value</i>. |
| The method value <code>x.M</code> is a function value that is callable |
| with the same arguments as a method call of <code>x.M</code>. |
| The expression <code>x</code> is evaluated and saved during the evaluation of the |
| method value; the saved copy is then used as the receiver in any calls, |
| which may be executed later. |
| </p> |
| |
| <p> |
| The type <code>T</code> may be an interface or non-interface type. |
| </p> |
| |
| <p> |
| As in the discussion of <a href="#Method_expressions">method expressions</a> above, |
| consider a struct type <code>T</code> with two methods, |
| <code>Mv</code>, whose receiver is of type <code>T</code>, and |
| <code>Mp</code>, whose receiver is of type <code>*T</code>. |
| </p> |
| |
| <pre> |
| type T struct { |
| a int |
| } |
| func (tv T) Mv(a int) int { return 0 } // value receiver |
| func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver |
| |
| var t T |
| var pt *T |
| func makeT() T |
| </pre> |
| |
| <p> |
| The expression |
| </p> |
| |
| <pre> |
| t.Mv |
| </pre> |
| |
| <p> |
| yields a function value of type |
| </p> |
| |
| <pre> |
| func(int) int |
| </pre> |
| |
| <p> |
| These two invocations are equivalent: |
| </p> |
| |
| <pre> |
| t.Mv(7) |
| f := t.Mv; f(7) |
| </pre> |
| |
| <p> |
| Similarly, the expression |
| </p> |
| |
| <pre> |
| pt.Mp |
| </pre> |
| |
| <p> |
| yields a function value of type |
| </p> |
| |
| <pre> |
| func(float32) float32 |
| </pre> |
| |
| <p> |
| As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver |
| using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>. |
| </p> |
| |
| <p> |
| As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver |
| using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>. |
| </p> |
| |
| <pre> |
| f := t.Mv; f(7) // like t.Mv(7) |
| f := pt.Mp; f(7) // like pt.Mp(7) |
| f := pt.Mv; f(7) // like (*pt).Mv(7) |
| f := t.Mp; f(7) // like (&t).Mp(7) |
| f := makeT().Mp // invalid: result of makeT() is not addressable |
| </pre> |
| |
| <p> |
| Although the examples above use non-interface types, it is also legal to create a method value |
| from a value of interface type. |
| </p> |
| |
| <pre> |
| var i interface { M(int) } = myVal |
| f := i.M; f(7) // like i.M(7) |
| </pre> |
| |
| |
| <h3 id="Index_expressions">Index expressions</h3> |
| |
| <p> |
| A primary expression of the form |
| </p> |
| |
| <pre> |
| a[x] |
| </pre> |
| |
| <p> |
| denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>. |
| The value <code>x</code> is called the <i>index</i> or <i>map key</i>, respectively. |
| The following rules apply: |
| </p> |
| |
| <p> |
| If <code>a</code> is not a map: |
| </p> |
| <ul> |
| <li>the index <code>x</code> must be of integer type or an untyped constant</li> |
| <li>a constant index must be non-negative and |
| <a href="#Representability">representable</a> by a value of type <code>int</code></li> |
| <li>a constant index that is untyped is given type <code>int</code></li> |
| <li>the index <code>x</code> is <i>in range</i> if <code>0 <= x < len(a)</code>, |
| otherwise it is <i>out of range</i></li> |
| </ul> |
| |
| <p> |
| For <code>a</code> of <a href="#Array_types">array type</a> <code>A</code>: |
| </p> |
| <ul> |
| <li>a <a href="#Constants">constant</a> index must be in range</li> |
| <li>if <code>x</code> is out of range at run time, |
| a <a href="#Run_time_panics">run-time panic</a> occurs</li> |
| <li><code>a[x]</code> is the array element at index <code>x</code> and the type of |
| <code>a[x]</code> is the element type of <code>A</code></li> |
| </ul> |
| |
| <p> |
| For <code>a</code> of <a href="#Pointer_types">pointer</a> to array type: |
| </p> |
| <ul> |
| <li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li> |
| </ul> |
| |
| <p> |
| For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>: |
| </p> |
| <ul> |
| <li>if <code>x</code> is out of range at run time, |
| a <a href="#Run_time_panics">run-time panic</a> occurs</li> |
| <li><code>a[x]</code> is the slice element at index <code>x</code> and the type of |
| <code>a[x]</code> is the element type of <code>S</code></li> |
| </ul> |
| |
| <p> |
| For <code>a</code> of <a href="#String_types">string type</a>: |
| </p> |
| <ul> |
| <li>a <a href="#Constants">constant</a> index must be in range |
| if the string <code>a</code> is also constant</li> |
| <li>if <code>x</code> is out of range at run time, |
| a <a href="#Run_time_panics">run-time panic</a> occurs</li> |
| <li><code>a[x]</code> is the non-constant byte value at index <code>x</code> and the type of |
| <code>a[x]</code> is <code>byte</code></li> |
| <li><code>a[x]</code> may not be assigned to</li> |
| </ul> |
| |
| <p> |
| For <code>a</code> of <a href="#Map_types">map type</a> <code>M</code>: |
| </p> |
| <ul> |
| <li><code>x</code>'s type must be |
| <a href="#Assignability">assignable</a> |
| to the key type of <code>M</code></li> |
| <li>if the map contains an entry with key <code>x</code>, |
| <code>a[x]</code> is the map element with key <code>x</code> |
| and the type of <code>a[x]</code> is the element type of <code>M</code></li> |
| <li>if the map is <code>nil</code> or does not contain such an entry, |
| <code>a[x]</code> is the <a href="#The_zero_value">zero value</a> |
| for the element type of <code>M</code></li> |
| </ul> |
| |
| <p> |
| Otherwise <code>a[x]</code> is illegal. |
| </p> |
| |
| <p> |
| An index expression on a map <code>a</code> of type <code>map[K]V</code> |
| used in an <a href="#Assignments">assignment</a> or initialization of the special form |
| </p> |
| |
| <pre> |
| v, ok = a[x] |
| v, ok := a[x] |
| var v, ok = a[x] |
| </pre> |
| |
| <p> |
| yields an additional untyped boolean value. The value of <code>ok</code> is |
| <code>true</code> if the key <code>x</code> is present in the map, and |
| <code>false</code> otherwise. |
| </p> |
| |
| <p> |
| Assigning to an element of a <code>nil</code> map causes a |
| <a href="#Run_time_panics">run-time panic</a>. |
| </p> |
| |
| |
| <h3 id="Slice_expressions">Slice expressions</h3> |
| |
| <p> |
| Slice expressions construct a substring or slice from a string, array, pointer |
| to array, or slice. There are two variants: a simple form that specifies a low |
| and high bound, and a full form that also specifies a bound on the capacity. |
| </p> |
| |
| <h4>Simple slice expressions</h4> |
| |
| <p> |
| For a string, array, pointer to array, or slice <code>a</code>, the primary expression |
| </p> |
| |
| <pre> |
| a[low : high] |
| </pre> |
| |
| <p> |
| constructs a substring or slice. The <i>indices</i> <code>low</code> and |
| <code>high</code> select which elements of operand <code>a</code> appear |
| in the result. The result has indices starting at 0 and length equal to |
| <code>high</code> - <code>low</code>. |
| After slicing the array <code>a</code> |
| </p> |
| |
| <pre> |
| a := [5]int{1, 2, 3, 4, 5} |
| s := a[1:4] |
| </pre> |
| |
| <p> |
| the slice <code>s</code> has type <code>[]int</code>, length 3, capacity 4, and elements |
| </p> |
| |
| <pre> |
| s[0] == 2 |
| s[1] == 3 |
| s[2] == 4 |
| </pre> |
| |
| <p> |
| For convenience, any of the indices may be omitted. A missing <code>low</code> |
| index defaults to zero; a missing <code>high</code> index defaults to the length of the |
| sliced operand: |
| </p> |
| |
| <pre> |
| a[2:] // same as a[2 : len(a)] |
| a[:3] // same as a[0 : 3] |
| a[:] // same as a[0 : len(a)] |
| </pre> |
| |
| <p> |
| If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for |
| <code>(*a)[low : high]</code>. |
| </p> |
| |
| <p> |
| For arrays or strings, the indices are <i>in range</i> if |
| <code>0</code> <= <code>low</code> <= <code>high</code> <= <code>len(a)</code>, |
| otherwise they are <i>out of range</i>. |
| For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length. |
| A <a href="#Constants">constant</a> index must be non-negative and |
| <a href="#Representability">representable</a> by a value of type |
| <code>int</code>; for arrays or constant strings, constant indices must also be in range. |
| If both indices are constant, they must satisfy <code>low <= high</code>. |
| If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. |
| </p> |
| |
| <p> |
| Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice, |
| the result of the slice operation is a non-constant value of the same type as the operand. |
| For untyped string operands the result is a non-constant value of type <code>string</code>. |
| If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a> |
| and the result of the slice operation is a slice with the same element type as the array. |
| </p> |
| |
| <p> |
| If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result |
| is a <code>nil</code> slice. Otherwise, if the result is a slice, it shares its underlying |
| array with the operand. |
| </p> |
| |
| <h4>Full slice expressions</h4> |
| |
| <p> |
| For an array, pointer to array, or slice <code>a</code> (but not a string), the primary expression |
| </p> |
| |
| <pre> |
| a[low : high : max] |
| </pre> |
| |
| <p> |
| constructs a slice of the same type, and with the same length and elements as the simple slice |
| expression <code>a[low : high]</code>. Additionally, it controls the resulting slice's capacity |
| by setting it to <code>max - low</code>. Only the first index may be omitted; it defaults to 0. |
| After slicing the array <code>a</code> |
| </p> |
| |
| <pre> |
| a := [5]int{1, 2, 3, 4, 5} |
| t := a[1:3:5] |
| </pre> |
| |
| <p> |
| the slice <code>t</code> has type <code>[]int</code>, length 2, capacity 4, and elements |
| </p> |
| |
| <pre> |
| t[0] == 2 |
| t[1] == 3 |
| </pre> |
| |
| <p> |
| As for simple slice expressions, if <code>a</code> is a pointer to an array, |
| <code>a[low : high : max]</code> is shorthand for <code>(*a)[low : high : max]</code>. |
| If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>. |
| </p> |
| |
| <p> |
| The indices are <i>in range</i> if <code>0 <= low <= high <= max <= cap(a)</code>, |
| otherwise they are <i>out of range</i>. |
| A <a href="#Constants">constant</a> index must be non-negative and |
| <a href="#Representability">representable</a> by a value of type |
| <code>int</code>; for arrays, constant indices must also be in range. |
| If multiple indices are constant, the constants that are present must be in range relative to each |
| other. |
| If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. |
| </p> |
| |
| <h3 id="Type_assertions">Type assertions</h3> |
| |
| <p> |
| For an expression <code>x</code> of <a href="#Interface_types">interface type</a> |
| and a type <code>T</code>, the primary expression |
| </p> |
| |
| <pre> |
| x.(T) |
| </pre> |
| |
| <p> |
| asserts that <code>x</code> is not <code>nil</code> |
| and that the value stored in <code>x</code> is of type <code>T</code>. |
| The notation <code>x.(T)</code> is called a <i>type assertion</i>. |
| </p> |
| <p> |
| More precisely, if <code>T</code> is not an interface type, <code>x.(T)</code> asserts |
| that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a> |
| to the type <code>T</code>. |
| In this case, <code>T</code> must <a href="#Method_sets">implement</a> the (interface) type of <code>x</code>; |
| otherwise the type assertion is invalid since it is not possible for <code>x</code> |
| to store a value of type <code>T</code>. |
| If <code>T</code> is an interface type, <code>x.(T)</code> asserts that the dynamic type |
| of <code>x</code> implements the interface <code>T</code>. |
| </p> |
| <p> |
| If the type assertion holds, the value of the expression is the value |
| stored in <code>x</code> and its type is <code>T</code>. If the type assertion is false, |
| a <a href="#Run_time_panics">run-time panic</a> occurs. |
| In other words, even though the dynamic type of <code>x</code> |
| is known only at run time, the type of <code>x.(T)</code> is |
| known to be <code>T</code> in a correct program. |
| </p> |
| |
| <pre> |
| var x interface{} = 7 // x has dynamic type int and value 7 |
| i := x.(int) // i has type int and value 7 |
| |
| type I interface { m() } |
| |
| func f(y I) { |
| s := y.(string) // illegal: string does not implement I (missing method m) |
| r := y.(io.Reader) // r has type io.Reader and the dynamic type of y must implement both I and io.Reader |
| … |
| } |
| </pre> |
| |
| <p> |
| A type assertion used in an <a href="#Assignments">assignment</a> or initialization of the special form |
| </p> |
| |
| <pre> |
| v, ok = x.(T) |
| v, ok := x.(T) |
| var v, ok = x.(T) |
| var v, ok T1 = x.(T) |
| </pre> |
| |
| <p> |
| yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code> |
| if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is |
| the <a href="#The_zero_value">zero value</a> for type <code>T</code>. |
| No run-time panic occurs in this case. |
| </p> |
| |
| |
| <h3 id="Calls">Calls</h3> |
| |
| <p> |
| Given an expression <code>f</code> of function type |
| <code>F</code>, |
| </p> |
| |
| <pre> |
| f(a1, a2, … an) |
| </pre> |
| |
| <p> |
| calls <code>f</code> with arguments <code>a1, a2, … an</code>. |
| Except for one special case, arguments must be single-valued expressions |
| <a href="#Assignability">assignable</a> to the parameter types of |
| <code>F</code> and are evaluated before the function is called. |
| The type of the expression is the result type |
| of <code>F</code>. |
| A method invocation is similar but the method itself |
| is specified as a selector upon a value of the receiver type for |
| the method. |
| </p> |
| |
| <pre> |
| math.Atan2(x, y) // function call |
| var pt *Point |
| pt.Scale(3.5) // method call with receiver pt |
| </pre> |
| |
| <p> |
| In a function call, the function value and arguments are evaluated in |
| <a href="#Order_of_evaluation">the usual order</a>. |
| After they are evaluated, the parameters of the call are passed by value to the function |
| and the called function begins execution. |
| The return parameters of the function are passed by value |
| back to the calling function when the function returns. |
| </p> |
| |
| <p> |
| Calling a <code>nil</code> function value |
| causes a <a href="#Run_time_panics">run-time panic</a>. |
| </p> |
| |
| <p> |
| As a special case, if the return values of a function or method |
| <code>g</code> are equal in number and individually |
| assignable to the parameters of another function or method |
| <code>f</code>, then the call <code>f(g(<i>parameters_of_g</i>))</code> |
| will invoke <code>f</code> after binding the return values of |
| <code>g</code> to the parameters of <code>f</code> in order. The call |
| of <code>f</code> must contain no parameters other than the call of <code>g</code>, |
| and <code>g</code> must have at least one return value. |
| If <code>f</code> has a final <code>...</code> parameter, it is |
| assigned the return values of <code>g</code> that remain after |
| assignment of regular parameters. |
| </p> |
| |
| <pre> |
| func Split(s string, pos int) (string, string) { |
| return s[0:pos], s[pos:] |
| } |
| |
| func Join(s, t string) string { |
| return s + t |
| } |
| |
| if Join(Split(value, len(value)/2)) != value { |
| log.Panic("test fails") |
| } |
| </pre> |
| |
| <p> |
| A method call <code>x.m()</code> is valid if the <a href="#Method_sets">method set</a> |
| of (the type of) <code>x</code> contains <code>m</code> and the |
| argument list can be assigned to the parameter list of <code>m</code>. |
| If <code>x</code> is <a href="#Address_operators">addressable</a> and <code>&x</code>'s method |
| set contains <code>m</code>, <code>x.m()</code> is shorthand |
| for <code>(&x).m()</code>: |
| </p> |
| |
| <pre> |
| var p Point |
| p.Scale(3.5) |
| </pre> |
| |
| <p> |
| There is no distinct method type and there are no method literals. |
| </p> |
| |
| <h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3> |
| |
| <p> |
| If <code>f</code> is <a href="#Function_types">variadic</a> with a final |
| parameter <code>p</code> of type <code>...T</code>, then within <code>f</code> |
| the type of <code>p</code> is equivalent to type <code>[]T</code>. |
| If <code>f</code> is invoked with no actual arguments for <code>p</code>, |
| the value passed to <code>p</code> is <code>nil</code>. |
| Otherwise, the value passed is a new slice |
| of type <code>[]T</code> with a new underlying array whose successive elements |
| are the actual arguments, which all must be <a href="#Assignability">assignable</a> |
| to <code>T</code>. The length and capacity of the slice is therefore |
| the number of arguments bound to <code>p</code> and may differ for each |
| call site. |
| </p> |
| |
| <p> |
| Given the function and calls |
| </p> |
| <pre> |
| func Greeting(prefix string, who ...string) |
| Greeting("nobody") |
| Greeting("hello:", "Joe", "Anna", "Eileen") |
| </pre> |
| |
| <p> |
| within <code>Greeting</code>, <code>who</code> will have the value |
| <code>nil</code> in the first call, and |
| <code>[]string{"Joe", "Anna", "Eileen"}</code> in the second. |
| </p> |
| |
| <p> |
| If the final argument is assignable to a slice type <code>[]T</code>, it may be |
| passed unchanged as the value for a <code>...T</code> parameter if the argument |
| is followed by <code>...</code>. In this case no new slice is created. |
| </p> |
| |
| <p> |
| Given the slice <code>s</code> and call |
| </p> |
| |
| <pre> |
| s := []string{"James", "Jasmine"} |
| Greeting("goodbye:", s...) |
| </pre> |
| |
| <p> |
| within <code>Greeting</code>, <code>who</code> will have the same value as <code>s</code> |
| with the same underlying array. |
| </p> |
| |
| |
| <h3 id="Operators">Operators</h3> |
| |
| <p> |
| Operators combine operands into expressions. |
| </p> |
| |
| <pre class="ebnf"> |
| Expression = UnaryExpr | Expression binary_op Expression . |
| UnaryExpr = PrimaryExpr | unary_op UnaryExpr . |
| |
| binary_op = "||" | "&&" | rel_op | add_op | mul_op . |
| rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" . |
| add_op = "+" | "-" | "|" | "^" . |
| mul_op = "*" | "/" | "%" | "<<" | ">>" | "&" | "&^" . |
| |
| unary_op = "+" | "-" | "!" | "^" | "*" | "&" | "<-" . |
| </pre> |
| |
| <p> |
| Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>. |
| For other binary operators, the operand types must be <a href="#Type_identity">identical</a> |
| unless the operation involves shifts or untyped <a href="#Constants">constants</a>. |
| For operations involving constants only, see the section on |
| <a href="#Constant_expressions">constant expressions</a>. |
| </p> |
| |
| <p> |
| Except for shift operations, if one operand is an untyped <a href="#Constants">constant</a> |
| and the other operand is not, the constant is <a href="#Conversions">converted</a> |
| to the type of the other operand. |
| </p> |
| |
| <p> |
| The right operand in a shift expression must have unsigned integer type |
| or be an untyped constant <a href="#Representability">representable</a> by a |
| value of type <code>uint</code>. |
| If the left operand of a non-constant shift expression is an untyped constant, |
| it is first converted to the type it would assume if the shift expression were |
| replaced by its left operand alone. |
| </p> |
| |
| <pre> |
| var s uint = 33 |
| var i = 1<<s // 1 has type int |
| var j int32 = 1<<s // 1 has type int32; j == 0 |
| var k = uint64(1<<s) // 1 has type uint64; k == 1<<33 |
| var m int = 1.0<<s // 1.0 has type int; m == 0 if ints are 32bits in size |
| var n = 1.0<<s == j // 1.0 has type int32; n == true |
| var o = 1<<s == 2<<s // 1 and 2 have type int; o == true if ints are 32bits in size |
| var p = 1<<s == 1<<33 // illegal if ints are 32bits in size: 1 has type int, but 1<<33 overflows int |
| var u = 1.0<<s // illegal: 1.0 has type float64, cannot shift |
| var u1 = 1.0<<s != 0 // illegal: 1.0 has type float64, cannot shift |
| var u2 = 1<<s != 1.0 // illegal: 1 has type float64, cannot shift |
| var v float32 = 1<<s // illegal: 1 has type float32, cannot shift |
| var w int64 = 1.0<<33 // 1.0<<33 is a constant shift expression |
| var x = a[1.0<<s] // 1.0 has type int; x == a[0] if ints are 32bits in size |
| var a = make([]byte, 1.0<<s) // 1.0 has type int; len(a) == 0 if ints are 32bits in size |
| </pre> |
| |
| |
| <h4 id="Operator_precedence">Operator precedence</h4> |
| <p> |
| Unary operators have the highest precedence. |
| As the <code>++</code> and <code>--</code> operators form |
| statements, not expressions, they fall |
| outside the operator hierarchy. |
| As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>. |
| <p> |
| There are five precedence levels for binary operators. |
| Multiplication operators bind strongest, followed by addition |
| operators, comparison operators, <code>&&</code> (logical AND), |
| and finally <code>||</code> (logical OR): |
| </p> |
| |
| <pre class="grammar"> |
| Precedence Operator |
| 5 * / % << >> & &^ |
| 4 + - | ^ |
| 3 == != < <= > >= |
| 2 && |
| 1 || |
| </pre> |
| |
| <p> |
| Binary operators of the same precedence associate from left to right. |
| For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>. |
| </p> |
| |
| <pre> |
| +x |
| 23 + 3*x[i] |
| x <= f() |
| ^a >> b |
| f() || g() |
| x == y+1 && <-chanPtr > 0 |
| </pre> |
| |
| |
| <h3 id="Arithmetic_operators">Arithmetic operators</h3> |
| <p> |
| Arithmetic operators apply to numeric values and yield a result of the same |
| type as the first operand. The four standard arithmetic operators (<code>+</code>, |
| <code>-</code>, <code>*</code>, <code>/</code>) apply to integer, |
| floating-point, and complex types; <code>+</code> also applies to strings. |
| The bitwise logical and shift operators apply to integers only. |
| </p> |
| |
| <pre class="grammar"> |
| + sum integers, floats, complex values, strings |
| - difference integers, floats, complex values |
| * product integers, floats, complex values |
| / quotient integers, floats, complex values |
| % remainder integers |
| |
| & bitwise AND integers |
| | bitwise OR integers |
| ^ bitwise XOR integers |
| &^ bit clear (AND NOT) integers |
| |
| << left shift integer << unsigned integer |
| >> right shift integer >> unsigned integer |
| </pre> |
| |
| |
| <h4 id="Integer_operators">Integer operators</h4> |
| |
| <p> |
| For two integer values <code>x</code> and <code>y</code>, the integer quotient |
| <code>q = x / y</code> and remainder <code>r = x % y</code> satisfy the following |
| relationships: |
| </p> |
| |
| <pre> |
| x = q*y + r and |r| < |y| |
| </pre> |
| |
| <p> |
| with <code>x / y</code> truncated towards zero |
| (<a href="https://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>). |
| </p> |
| |
| <pre> |
| x y x / y x % y |
| 5 3 1 2 |
| -5 3 -1 -2 |
| 5 -3 -1 2 |
| -5 -3 1 -2 |
| </pre> |
| |
| <p> |
| The one exception to this rule is that if the dividend <code>x</code> is |
| the most negative value for the int type of <code>x</code>, the quotient |
| <code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>) |
| due to two's-complement <a href="#Integer_overflow">integer overflow</a>: |
| </p> |
| |
| <pre> |
| x, q |
| int8 -128 |
| int16 -32768 |
| int32 -2147483648 |
| int64 -9223372036854775808 |
| </pre> |
| |
| <p> |
| If the divisor is a <a href="#Constants">constant</a>, it must not be zero. |
| If the divisor is zero at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. |
| If the dividend is non-negative and the divisor is a constant power of 2, |
| the division may be replaced by a right shift, and computing the remainder may |
| be replaced by a bitwise AND operation: |
| </p> |
| |
| <pre> |
| x x / 4 x % 4 x >> 2 x & 3 |
| 11 2 3 2 3 |
| -11 -2 -3 -3 1 |
| </pre> |
| |
| <p> |
| The shift operators shift the left operand by the shift count specified by the |
| right operand. They implement arithmetic shifts if the left operand is a signed |
| integer and logical shifts if it is an unsigned integer. |
| There is no upper limit on the shift count. Shifts behave |
| as if the left operand is shifted <code>n</code> times by 1 for a shift |
| count of <code>n</code>. |
| As a result, <code>x << 1</code> is the same as <code>x*2</code> |
| and <code>x >> 1</code> is the same as |
| <code>x/2</code> but truncated towards negative infinity. |
| </p> |
| |
| <p> |
| For integer operands, the unary operators |
| <code>+</code>, <code>-</code>, and <code>^</code> are defined as |
| follows: |
| </p> |
| |
| <pre class="grammar"> |
| +x is 0 + x |
| -x negation is 0 - x |
| ^x bitwise complement is m ^ x with m = "all bits set to 1" for unsigned x |
| and m = -1 for signed x |
| </pre> |
| |
| |
| <h4 id="Integer_overflow">Integer overflow</h4> |
| |
| <p> |
| For unsigned integer values, the operations <code>+</code>, |
| <code>-</code>, <code>*</code>, and <code><<</code> are |
| computed modulo 2<sup><i>n</i></sup>, where <i>n</i> is the bit width of |
| the <a href="#Numeric_types">unsigned integer</a>'s type. |
| Loosely speaking, these unsigned integer operations |
| discard high bits upon overflow, and programs may rely on "wrap around". |
| </p> |
| <p> |
| For signed integers, the operations <code>+</code>, |
| <code>-</code>, <code>*</code>, <code>/</code>, and <code><<</code> may legally |
| overflow and the resulting value exists and is deterministically defined |
| by the signed integer representation, the operation, and its operands. |
| No exception is raised as a result of overflow. |
| A compiler may not optimize code under the assumption that overflow does |
| not occur. For instance, it may not assume that <code>x < x + 1</code> is always true. |
| </p> |
| |
| |
| <h4 id="Floating_point_operators">Floating-point operators</h4> |
| |
| <p> |
| For floating-point and complex numbers, |
| <code>+x</code> is the same as <code>x</code>, |
| while <code>-x</code> is the negation of <code>x</code>. |
| The result of a floating-point or complex division by zero is not specified beyond the |
| IEEE-754 standard; whether a <a href="#Run_time_panics">run-time panic</a> |
| occurs is implementation-specific. |
| </p> |
| |
| <p> |
| An implementation may combine multiple floating-point operations into a single |
| fused operation, possibly across statements, and produce a result that differs |
| from the value obtained by executing and rounding the instructions individually. |