diff options
Diffstat (limited to 'doc/go_spec.html')
| -rw-r--r-- | doc/go_spec.html | 5272 |
1 files changed, 0 insertions, 5272 deletions
diff --git a/doc/go_spec.html b/doc/go_spec.html deleted file mode 100644 index 489ad4db3..000000000 --- a/doc/go_spec.html +++ /dev/null @@ -1,5272 +0,0 @@ -<!-- title The Go Programming Language Specification --> -<!-- subtitle Version of June 17, 2011 --> - -<!-- -TODO -[ ] need language about function/method calls and parameter passing rules -[ ] last paragraph of #Assignments (constant promotion) should be elsewhere - and mention assignment to empty interface. -[ ] need to say something about "scope" of selectors? -[ ] clarify what a field name is in struct declarations - (struct{T} vs struct {T T} vs struct {t T}) -[ ] need explicit language about the result type of operations -[ ] should probably write something about evaluation order of statements even - though obvious -[ ] review language on implicit dereferencing -[ ] clarify what it means for two functions to be "the same" when comparing them ---> - - -<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="http://golang.org/">http://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. The existing implementations use a traditional -compile/link model to generate executable binaries. -</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 symbols 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 -ellipis … is also used elsewhere in the spec to informally denote various -enumerations or code snippets that are not further specified. The character … -(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="http://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 term <i>character</i> to refer to a Unicode code point. -</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> - -<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 "Decimal Digit" */ . -</pre> - -<p> -In <a href="http://www.unicode.org/versions/Unicode6.0.0/">The Unicode Standard 6.0</a>, -Section 4.5 "General Category" -defines a set of character categories. Go treats -those characters in category Lu, Ll, Lt, Lm, or Lo as Unicode letters, -and those in category Nd as Unicode digits. -</p> - -<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> -There are two forms of comments: -</p> - -<ol> -<li> -<i>Line comments</i> start with the character sequence <code>//</code> -and stop at the end of the line. A line comment acts like a newline. -</li> -<li> -<i>General comments</i> start with the character sequence <code>/*</code> -and continue through the character sequence <code>*/</code>. A general -comment that spans multiple lines acts like a newline, otherwise it acts -like a space. -</li> -</ol> - -<p> -Comments do not nest. -</p> - - -<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 delimiters</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> -<p> -When the input is broken into tokens, a semicolon is automatically inserted -into the token stream at the end of a non-blank line if the line's final -token is -</p> -<ul> - <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="#Character_literals">character</a>, or - <a href="#String_literals">string</a> literal - </li> - - <li>one of the <a href="#Keywords">keywords</a> - <code>break</code>, - <code>continue</code>, - <code>fallthrough</code>, or - <code>return</code> - </li> - - <li>one of the <a href="#Operators_and_Delimiters">operators and delimiters</a> - <code>++</code>, - <code>--</code>, - <code>)</code>, - <code>]</code>, or - <code>}</code> - </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_Delimiters">Operators and Delimiters</h3> - -<p> -The following character sequences represent <a href="#Operators">operators</a>, delimiters, and other special tokens: -</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="Character_literals">Character literals</h3> - -<p> -A character literal represents an <a href="#Constants">integer constant</a>, -typically a Unicode code point, as one or more characters enclosed in single -quotes. Within the quotes, any character may appear except single -quote and newline. A single quoted character represents itself, -while multi-character sequences beginning with a backslash encode -values in various formats. -</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 represented -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 character literals) -\" U+0022 double quote (valid escape only within string literals) -</pre> -<p> -All other sequences starting with a backslash are illegal inside character literals. -</p> -<pre class="ebnf"> -char_lit = "'" ( unicode_value | byte_value ) "'" . -unicode_value = unicode_char | little_u_value | big_u_value | escaped_char . -byte_value = octal_byte_value | hex_byte_value . -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' -</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 -<code>``</code>. Within the quotes, any character is legal except -back quote. The value of a raw string literal is the -string composed of the uninterpreted characters between the quotes; -in particular, backslashes have no special meaning and the string may -span multiple lines. -</p> -<p> -Interpreted string literals are character sequences between double -quotes <code>""</code>. The text between the quotes, -which may not span multiple lines, forms the -value of the literal, with backslash escapes interpreted as they -are in character literals (except that <code>\'</code> is illegal and -<code>\"</code> is legal). The three-digit octal (<code>\</code><i>nnn</i>) -and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual -<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" -"" -"Hello, world!\n" -"日本語" -"\u65e5本\U00008a9e" -"\xff\u00FF" -</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 character 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>integer constants</i>, -<i>floating-point constants</i>, <i>complex constants</i>, -and <i>string constants</i>. Integer, floating-point, -and complex constants are -collectively called <i>numeric constants</i>. -</p> - -<p> -A constant value is represented by an -<a href="#Integer_literals">integer</a>, -<a href="#Floating-point_literals">floating-point</a>, -<a href="#Imaginary_literals">imaginary</a>, -<a href="#Character_literals">character</a>, or -<a href="#String_literals">string</a> literal, -an identifier denoting a constant, -a <a href="#Constant_expressions">constant expression</a>, -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 values of arbitrary precision and do not overflow. -</p> - -<p> -Constants may be <a href="#Types">typed</a> or untyped. -Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>, -and certain <a href="#Constant_expressions">constant expressions</a> -containing only untyped constant operands are untyped. -</p> - -<p> -A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a> -or <a href="#Conversions">conversion</a>, or implicitly when used in a -<a href="#Variable_declarations">variable declaration</a> or an -<a href="#Assignments">assignment</a> or as an -operand in an <a href="#Expressions">expression</a>. -It is an error if the constant value -cannot be represented as a value of the respective type. -For instance, <code>3.0</code> can be given any integer or any -floating-point type, while <code>2147483648.0</code> (equal to <code>1<<31</code>) -can be given the types <code>float32</code>, <code>float64</code>, or <code>uint32</code> but -not <code>int32</code> or <code>string</code>. -</p> - -<p> -There are no constants denoting the IEEE-754 infinity and not-a-number values, -but the <a href="/pkg/math/"><code>math</code> package</a>'s -<a href="/pkg/math/#Inf">Inf</a>, -<a href="/pkg/math/#NaN">NaN</a>, -<a href="/pkg/math/#IsInf">IsInf</a>, and -<a href="/pkg/math/#IsNaN">IsNaN</a> -functions return and test for those values at run time. -</p> - -<p> -Implementation restriction: A compiler may implement numeric constants by choosing -an internal representation with at least twice as many bits as any machine type; -for floating-point values, both the mantissa and exponent must be twice as large. -</p> - - -<h2 id="Types">Types</h2> - -<p> -A type determines the set of values and operations specific to values of that -type. A type may be specified by a (possibly qualified) <i>type name</i> -(§<a href="#Qualified_identifiers">Qualified identifier</a>, §<a href="#Type_declarations">Type declarations</a>) or a <i>type literal</i>, -which composes a new type from previously declared types. -</p> - -<pre class="ebnf"> -Type = TypeName | TypeLit | "(" Type ")" . -TypeName = QualifiedIdent . -TypeLit = ArrayType | StructType | PointerType | FunctionType | InterfaceType | - SliceType | MapType | ChannelType . -</pre> - -<p> -Named instances of the boolean, numeric, and string types are -<a href="#Predeclared_identifiers">predeclared</a>. -<i>Composite types</i>—array, struct, pointer, function, -interface, slice, map, and channel types—may be constructed using -type literals. -</p> - -<p> -The <i>static type</i> (or just <i>type</i>) of a variable is the -type defined by its declaration. Variables of interface type -also have a distinct <i>dynamic type</i>, which -is the actual type of the value stored in the variable at run-time. -The dynamic type may vary during execution but is always -<a href="#Assignability">assignable</a> -to the static type of the interface variable. For non-interface -types, the dynamic type is always the static type. -</p> - -<p> -Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code> -is a predeclared type or a type literal, the corresponding underlying -type is <code>T</code> itself. Otherwise, <code>T</code>'s underlying type -is the underlying type of the type to which <code>T</code> refers in its -<a href="#Type_declarations">type declaration</a>. -</p> - -<pre> - type T1 string - type T2 T1 - type T3 []T1 - type T4 T3 -</pre> - -<p> -The underlying type of <code>string</code>, <code>T1</code>, and <code>T2</code> -is <code>string</code>. The underlying type of <code>[]T1</code>, <code>T3</code>, -and <code>T4</code> is <code>[]T1</code>. -</p> - -<h3 id="Method_sets">Method sets</h3> -<p> -A type may have a <i>method set</i> associated with it -(§<a href="#Interface_types">Interface types</a>, §<a href="#Method_declarations">Method declarations</a>). -The method set of an <a href="#Interface_types">interface type</a> is its interface. -The method set of any other named type <code>T</code> -consists of all methods with receiver type <code>T</code>. -The method set of the corresponding pointer type <code>*T</code> -is the set of all methods with receiver <code>*T</code> or <code>T</code> -(that is, it also contains the method set of <code>T</code>). -Any other type has an empty method set. -In a method set, each method must have a unique name. -</p> - - -<h3 id="Boolean_types">Boolean types</h3> - -A <i>boolean type</i> represents the set of Boolean truth values -denoted by the predeclared constants <code>true</code> -and <code>false</code>. The predeclared boolean type is <code>bool</code>. - - -<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 familiar alias for uint8 -</pre> - -<p> -The value of an <i>n</i>-bit integer is <i>n</i> bits wide and represented using -<a href="http://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>. -</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 distinct except -<code>byte</code>, which is an alias for <code>uint8</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. -Strings behave like arrays of bytes but are immutable: once created, -it is impossible to change the contents of a string. -The predeclared string type is <code>string</code>. - -<p> -The elements of strings have type <code>byte</code> and may be -accessed using the usual <a href="#Indexes">indexing operations</a>. It is -illegal to take the address of such an element; if -<code>s[i]</code> is the <i>i</i>th byte of a -string, <code>&s[i]</code> is invalid. The length of string -<code>s</code> can be discovered using the built-in function -<code>len</code>. The length is a compile-time constant if <code>s</code> -is a string literal. -</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 and must be a -<a href="#Constant_expressions">constant expression</a> that evaluates to a non-negative -integer value. The length of array <code>a</code> can be discovered -using the built-in function <a href="#Length_and_capacity"><code>len(a)</code></a>. -The elements can be indexed by integer -indices 0 through the <code>len(a)-1</code> (§<a href="#Indexes">Indexes</a>). -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 reference to a contiguous segment of an array and -contains a numbered sequence of elements from that array. A slice -type denotes the set of all slices of arrays of its element type. -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(s)</code></a>; unlike with arrays it may change during -execution. The elements can be addressed by integer indices 0 -through <code>len(s)-1</code> (§<a href="#Indexes">Indexes</a>). 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 `slicing' a new -one from the original slice (§<a href="#Slices">Slices</a>). -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: -</p> - -<pre> -make([]T, length) -make([]T, length, capacity) -</pre> - -<p> -A call to <code>make</code> 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 slicing it, so these two examples -result in the same slice: -</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 lengths may vary dynamically. -Moreover, the inner slices must be allocated individually (with <code>make</code>). -</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 (AnonymousField). -Within a struct, non-<a href="#Blank_identifier">blank</a> field names must -be unique. -</p> - -<pre class="ebnf"> -StructType = "struct" "{" { FieldDecl ";" } "}" . -FieldDecl = (IdentifierList Type | AnonymousField) [ Tag ] . -AnonymousField = [ "*" ] 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 an <i>anonymous field</i> -(colloquially called an embedded field). -Such a field type 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 anonymous fields of type 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 anonymous field *T and *P.T - *T // conflicts with anonymous field T and *P.T - *P.T // conflicts with anonymous field T and *T -} -</pre> - -<p> -Fields and methods (§<a href="#Method_declarations">Method declarations</a>) of an anonymous field are -promoted to be ordinary fields and methods of the struct (§<a href="#Selectors">Selectors</a>). -The following rules apply for a struct type named <code>S</code> and -a type named <code>T</code>: -</p> -<ul> - <li>If <code>S</code> contains an anonymous field <code>T</code>, the - <a href="#Method_sets">method set</a> of <code>S</code> includes the - method set of <code>T</code>. - </li> - - <li>If <code>S</code> contains an anonymous field <code>*T</code>, the - method set of <code>S</code> includes the method set of <code>*T</code> - (which itself includes the method set of <code>T</code>). - </li> - - <li>If <code>S</code> contains an anonymous field <code>T</code> or - <code>*T</code>, the method set of <code>*S</code> includes the - method set of <code>*T</code> (which itself includes the method - set of <code>T</code>). - </li> -</ul> -<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. The tags are made -visible through a <a href="#Package_unsafe">reflection interface</a> -but are otherwise ignored. -</p> - -<pre> -// A struct corresponding to the TimeStamp protocol buffer. -// The tag strings define the protocol buffer field numbers. -struct { - microsec uint64 "field 1" - serverIP6 uint64 "field 2" - process string "field 3" -} -</pre> - -<h3 id="Pointer_types">Pointer types</h3> - -<p> -A pointer type denotes the set of all pointers to variables 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> -*int -*map[string] *chan 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; 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 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) -func() int -func(prefix string, values ...int) -func(a, b int, z float32) bool -func(a, b int, z float32) (bool) -func(a, b int, z float64, opt ...interface{}) (success bool) -func(int, int, float64) (float64, *[]int) -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 unique 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>Lock</code>: -</p> - -<pre> -type Lock 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>Lock</code> interface as well -as the <code>File</code> interface. -</p> -<p> -An interface may contain an interface type name <code>T</code> -in place of a method specification. -The effect is equivalent to enumerating the methods of <code>T</code> explicitly -in the interface. -</p> - -<pre> -type ReadWrite interface { - Read(b Buffer) bool - Write(b Buffer) bool -} - -type File interface { - ReadWrite // same as enumerating the methods in ReadWrite - Lock // same as enumerating the methods in Lock - Close() -} -</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 comparison operators <code>==</code> and <code>!=</code> -(§<a href="#Comparison_operators">Comparison operators</a>) must be fully defined -for operands of the key type; thus the key type must not be a struct, array or slice. -If the key type is an interface type, these -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(m)</code></a> -and may change during execution. Elements may be added and removed -during execution using special forms of <a href="#Assignments">assignment</a>; -and they may be accessed with <a href="#Indexes">index</a> expressions. -</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 two concurrently executing functions -to synchronize execution and communicate by passing a value of a -specified element type. -The value of an uninitialized channel is <code>nil</code>. -</p> - -<pre class="ebnf"> -ChannelType = ( "chan" [ "<-" ] | "<-" "chan" ) ElementType . -</pre> - -<p> -The <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>bi-directional</i>. -A channel may be constrained only to send or only to receive by -<a href="#Conversions">conversion</a> or <a href="#Assignments">assignment</a>. -</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 capacity 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 greater than zero, the channel is asynchronous: communication operations -succeed without blocking if the buffer is not full (sends) or not empty (receives), -and elements are received in the order they are sent. -If the capacity is zero or absent, the communication succeeds only when both a sender and -receiver are ready. -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> -tests whether a channel has been closed. -</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> -Two named types are identical if their type names originate in the same -type <a href="#Declarations_and_scope">declaration</a>. -A named and an unnamed type are always different. Two unnamed types are identical -if the corresponding type literals are identical, that is, if 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. - Two anonymous fields are considered to have the same name. Lower-case 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. Lower-case 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 value types.</li> - - <li>Two channel types are identical if they have identical value types and - the same direction.</li> -</ul> - -<p> -Given the declarations -</p> - -<pre> -type ( - T0 []string - T1 []string - T2 struct { a, b int } - T3 struct { a, c int } - T4 func(int, float64) *T0 - T5 func(x int, y float64) *[]string -) -</pre> - -<p> -these types are identical: -</p> - -<pre> -T0 and T0 -[]int and []int -struct { a, b *T5 } and struct { a, b *T5 } -func(x int, y float64) *[]string and func(int, float64) (result *[]string) -</pre> - -<p> -<code>T0</code> and <code>T1</code> are different because they are named types -with distinct declarations; <code>func(int, float64) *T0</code> and -<code>func(x int, y float64) *[]string</code> are different because <code>T0</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 variable of type <code>T</code> -("<code>x</code> is assignable to <code>T</code>") in any of these cases: -</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 named 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 named 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> representable -by a value of type <code>T</code>. -</li> -</ul> - -<p> -If <code>T</code> is a struct type with non-<a href="#Exported_identifiers">exported</a> -fields, the assignment must be in the same package in which <code>T</code> is declared, -or <code>x</code> must be the receiver of a method call. -In other words, a struct value can be assigned to a struct variable only if -every field of the struct may be legally assigned individually by the program, -or if the assignment is initializing the receiver of a method of the struct type. -</p> - -<p> -Any value may be assigned to the <a href="#Blank_identifier">blank identifier</a>. -</p> - - -<h2 id="Blocks">Blocks</h2> - -<p> -A <i>block</i> is a sequence of declarations and statements within matching -brace brackets. -</p> - -<pre class="ebnf"> -Block = "{" { 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 <code>if</code>, <code>for</code>, and <code>switch</code> - statement is considered to be in its own implicit block.</li> - - <li>Each clause in a <code>switch</code> or <code>select</code> 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 declaration binds a non-<a href="#Blank_identifier">blank</a> -identifier to a constant, type, variable, function, or package. -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> - -<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, or package. -</p> - -<p> -Go is lexically scoped using blocks: -</p> - -<ol> - <li>The scope of a predeclared identifier 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 an imported package identifier is the file block - of the file containing the import declaration.</li> - - <li>The scope of an identifier denoting a function parameter or - result variable is the function body.</li> - - <li>The scope of a constant or variable identifier declared - inside a function begins at the end of the ConstSpec or VarSpec - (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 <code>break</code>, <code>continue</code>, and <code>goto</code> -statements (§<a href="#Break_statements">Break statements</a>, §<a href="#Continue_statements">Continue statements</a>, §<a href="#Goto_statements">Goto statements</a>). -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="Predeclared_identifiers">Predeclared identifiers</h3> - -<p> -The following identifiers are implicitly declared in the universe block: -</p> -<pre class="grammar"> -Basic types: - bool byte complex64 complex128 float32 float64 - int8 int16 int32 int64 string uint8 uint16 uint32 uint64 - -Architecture-specific convenience types: - int uint uintptr - -Constants: - true false iota - -Zero value: - nil - -Functions: - append cap close complex copy 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 -using a <a href="#Qualified_identifiers">qualified identifier</a>. 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 denotes a field or method of a type - declared in that block.</li> -</ol> -<p> -All other identifiers are not exported. -</p> - - -<h3 id="Blank_identifier">Blank identifier</h3> - -<p> -The <i>blank identifier</i>, represented by the underscore character <code>_</code>, may be used in a declaration like -any other identifier but the declaration does not introduce a new binding. -</p> - - -<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 declaration. -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>. It is reset to 0 whenever the reserved word <code>const</code> -appears in the source and increments after each <a href="#ConstSpec">ConstSpec</a>. -It can be used to construct a set of related constants: -</p> - -<pre> -const ( // iota is reset to 0 - c0 = iota // c0 == 0 - c1 = iota // c1 == 1 - c2 = iota // c2 == 2 -) - -const ( - a = 1 << iota // a == 1 (iota has been reset) - b = 1 << iota // b == 2 - c = 1 << iota // c == 4 -) - -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 (iota has been reset) -const y = iota // y == 0 (iota has been reset) -</pre> - -<p> -Within an ExpressionList, the value of each <code>iota</code> is the same because -it is only incremented after each ConstSpec: -</p> - -<pre> -const ( - bit0, mask0 = 1 << iota, 1 << iota - 1 // bit0 == 1, mask0 == 0 - bit1, mask1 // bit1 == 2, mask1 == 1 - _, _ // skips iota == 2 - bit3, mask3 // bit3 == 8, mask3 == 7 -) -</pre> - -<p> -This last example exploits the implicit repetition 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 new type -that has the same <a href="#Types">underlying type</a> as -an existing type. The new type is <a href="#Type_identity">different</a> from -the existing type. -</p> - -<pre class="ebnf"> -TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) . -TypeSpec = identifier Type . -</pre> - -<pre> -type IntArray [16]int - -type ( - Point struct { x, y float64 } - Polar Point -) - -type TreeNode struct { - left, right *TreeNode - value *Comparable -} - -type Cipher interface { - BlockSize() int - Encrypt(src, dst []byte) - Decrypt(src, dst []byte) -} -</pre> - -<p> -The declared type does not inherit any <a href="#Method_declarations">methods</a> -bound to the existing 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 the <a href="#Pointer_types">base type</a> of PtrMutex 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 anonymous field Mutex. -type PrintableMutex struct { - Mutex -} - -// MyCipher is an interface type that has the same method set as Cipher. -type MyCipher Cipher -</pre> - -<p> -A type declaration may be used to define a different boolean, numeric, or string -type and attach methods to it: -</p> - -<pre> -type TimeZone int - -const ( - 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 a variable, binds an identifier to it and -gives it a type and optionally 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 -by assigning the expressions to the variables (§<a href="#Assignments">Assignments</a>) -in order; all expressions must be consumed and all variables initialized from them. -Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>. -</p> - -<p> -If the type is present, each variable is given that type. -Otherwise, the types are deduced from the assignment -of the expression list. -</p> - -<p> -If the type is absent and the corresponding expression evaluates to an -untyped <a href="#Constants">constant</a>, the type of the declared variable -is <code>bool</code>, <code>int</code>, <code>float64</code>, or <code>string</code> -respectively, depending on whether the value is a boolean, integer, -floating-point, or string constant: -</p> - -<pre> -var b = true // t has type bool -var i = 0 // i has type int -var f = 3.0 // f has type float64 -var s = "OMDB" // s has type string -</pre> - -<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 a shorthand for a regular variable declaration 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 redeclare variables provided they -were originally declared in the same block 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 -</pre> - -<p> -Short variable declarations may appear only inside functions. -In some contexts such as the initializers for <code>if</code>, -<code>for</code>, or <code>switch</code> statements, -they can be used to declare local temporary variables (§<a href="#Statements">Statements</a>). -</p> - -<h3 id="Function_declarations">Function declarations</h3> - -<p> -A function declaration binds an identifier to a function (§<a href="#Function_types">Function types</a>). -</p> - -<pre class="ebnf"> -FunctionDecl = "func" identifier Signature [ Body ] . -Body = Block . -</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 function with a <i>receiver</i>. -A method declaration binds an identifier to a method. -</p> -<pre class="ebnf"> -MethodDecl = "func" Receiver MethodName Signature [ Body ] . -Receiver = "(" [ identifier ] [ "*" ] BaseTypeName ")" . -BaseTypeName = identifier . -</pre> - -<p> -The receiver type must be of the form <code>T</code> or <code>*T</code> where -<code>T</code> is a type name. <code>T</code> is called the -<i>receiver base type</i> or just <i>base type</i>. -The base type must not be a pointer or interface type and must be -declared in the same package as the method. -The method is said to be <i>bound</i> to the base type -and is visible only within selectors for that type -(§<a href="#Type_declarations">Type declarations</a>, §<a href="#Selectors">Selectors</a>). -</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> -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> -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. -</p> - -<pre class="ebnf"> -Operand = Literal | QualifiedIdent | MethodExpr | "(" Expression ")" . -Literal = BasicLit | CompositeLit | FunctionLit . -BasicLit = int_lit | float_lit | imaginary_lit | char_lit | string_lit . -</pre> - - -<h3 id="Qualified_identifiers">Qualified identifiers</h3> - -<p> -A qualified identifier is a non-<a href="#Blank_identifier">blank</a> identifier qualified by a package name prefix. -</p> - -<pre class="ebnf"> -QualifiedIdent = [ PackageName "." ] identifier . -</pre> - -<p> -A qualified identifier accesses an identifier in a separate package. -The identifier must be <a href="#Exported_identifiers">exported</a> by that -package, which means that it must begin with a Unicode upper case letter. -</p> - -<pre> -math.Sin -</pre> - -<!-- -<p> -<span class="alert">TODO: Unify this section with Selectors - it's the same syntax.</span> -</p> ---> - -<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 value -followed by a brace-bound list of composite elements. An element may be -a single expression or a key-value pair. -</p> - -<pre class="ebnf"> -CompositeLit = LiteralType LiteralValue . -LiteralType = StructType | ArrayType | "[" "..." "]" ElementType | - SliceType | MapType | TypeName . -LiteralValue = "{" [ ElementList [ "," ] ] "}" . -ElementList = Element { "," Element } . -Element = [ Key ":" ] Value . -Key = FieldName | ElementIndex . -FieldName = identifier . -ElementIndex = Expression . -Value = Expression | LiteralValue . -</pre> - -<p> -The LiteralType must be a struct, array, slice, or map type -(the grammar enforces this constraint except when the type is given -as a TypeName). -The types of the expressions must be <a href="#Assignability">assignable</a> -to the respective field, element, and key types of the LiteralType; -there is no additional conversion. -The key is interpreted as a field name for struct literals, -an index expression 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. -</p> - -<p> -For struct literals the following rules apply: -</p> -<ul> - <li>A key must be a field name declared in the LiteralType. - </li> - <li>A literal 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>A literal 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 constant integer expression. - </li> - <li>An element without a key uses the previous element's index plus one. - If the first element has no key, its index is zero. - </li> -</ul> - -<p> -Taking the address of a composite literal (§<a href="#Address_operators">Address operators</a>) -generates a pointer to a unique instance of 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 LiteralType. -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 a shortcut for a slice operation applied to an array literal: -</p> - -<pre> -[n]T{x1, x2, … xn}[0 : n] -</pre> - -<p> -Within a composite literal of array, slice, or map type <code>T</code>, -elements that are themselves composite literals may elide the respective -literal type if it is identical to the element type of <code>T</code>. -</p> - -<pre> -[...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}} -[][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}} -</pre> - -<p> -A parsing ambiguity arises when a composite literal using the -TypeName form of the LiteralType appears between the -<a href="#Keywords">keyword</a> and the opening brace of the block of an -"if", "for", or "switch" statement, because the braces surrounding -the expressions in the literal are confused with those introducing -the block of statements. To resolve the ambiguity in this rare case, -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, 11, 13, 17, 19, 991} - -// 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 function. -It consists of a specification of the function type and a function body. -</p> - -<pre class="ebnf"> -FunctionLit = FunctionType Body . -</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 } (reply_chan) -</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 | - BuiltinCall | - PrimaryExpr Selector | - PrimaryExpr Index | - PrimaryExpr Slice | - PrimaryExpr TypeAssertion | - PrimaryExpr Call . - -Selector = "." identifier . -Index = "[" Expression "]" . -Slice = "[" [ Expression ] ":" [ Expression ] "]" . -TypeAssertion = "." "(" Type ")" . -Call = "(" [ ArgumentList [ "," ] ] ")" . -ArgumentList = ExpressionList [ "..." ] . -</pre> - - -<pre> -x -2 -(s + ".txt") -f(3.1415, true) -Point{1, 2} -m["foo"] -s[i : j + 1] -obj.color -math.Sin -f.p[i].x() -</pre> - - -<h3 id="Selectors">Selectors</h3> - -<p> -A primary expression of the form -</p> - -<pre> -x.f -</pre> - -<p> -denotes the field or method <code>f</code> of the value denoted by <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 expression is the type of <code>f</code>. -</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 anonymous field of -<code>T</code>. -The number of anonymous fields traversed -to reach <code>f</code> is called its <i>depth</i> in <code>T</code>. -The depth of a field or method <code>f</code> -declared in <code>T</code> is zero. -The depth of a field or method <code>f</code> declared in -an anonymous field <code>A</code> in <code>T</code> is the -depth of <code>f</code> in <code>A</code> plus one. -</p> -<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 an interface type, -<code>x.f</code> denotes the field or method at the shallowest depth -in <code>T</code> where there -is such an <code>f</code>. -If there is not exactly one <code>f</code> with shallowest depth, the selector -expression is illegal. -</li> -<li> -For a variable <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 value assigned -to <code>x</code> if there is such a method. -If no value or <code>nil</code> was assigned to <code>x</code>, <code>x.f</code> is illegal. -</li> -<li> -In all other cases, <code>x.f</code> is illegal. -</li> -</ol> -<p> -Selectors automatically dereference pointers to structs. -If <code>x</code> is a pointer to a struct, <code>x.y</code> -is shorthand for <code>(*x).y</code>; if the field <code>y</code> -is also a pointer to a struct, <code>x.y.z</code> is shorthand -for <code>(*(*x).y).z</code>, and so on. -If <code>x</code> contains an anonymous field of type <code>*A</code>, -where <code>A</code> is also a struct type, -<code>x.f</code> is a shortcut for <code>(*x.A).f</code>. -</p> -<p> -For example, given the declarations: -</p> - -<pre> -type T0 struct { - x int -} - -func (recv *T0) M0() - -type T1 struct { - y int -} - -func (recv T1) M1() - -type T2 struct { - z int - T1 - *T0 -} - -func (recv *T2) M2() - -var p *T2 // with p != nil and p.T1 != nil -</pre> - -<p> -one may write: -</p> - -<pre> -p.z // (*p).z -p.y // ((*p).T1).y -p.x // (*(*p).T0).x - -p.M2 // (*p).M2 -p.M1 // ((*p).T1).M1 -p.M0 // ((*p).T0).M0 -</pre> - - -<!-- -<span class="alert"> -TODO: Specify what happens to receivers. -</span> ---> - - -<h3 id="Indexes">Indexes</h3> - -<p> -A primary expression of the form -</p> - -<pre> -a[x] -</pre> - -<p> -denotes the element of the 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> -For <code>a</code> of type <code>A</code> or <code>*A</code> -where <code>A</code> is an <a href="#Array_types">array type</a>, -or for <code>a</code> of type <code>S</code> where <code>S</code> is a <a href="#Slice_types">slice type</a>: -</p> -<ul> - <li><code>x</code> must be an integer value and <code>0 <= x < len(a)</code></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> - <li>if <code>a</code> is <code>nil</code> or if the index <code>x</code> is out of range, - a <a href="#Run_time_panics">run-time panic</a> occurs</li> -</ul> - -<p> -For <code>a</code> of type <code>T</code> -where <code>T</code> is a <a href="#String_types">string type</a>: -</p> -<ul> - <li><code>x</code> must be an integer value and <code>0 <= x < len(a)</code></li> - <li><code>a[x]</code> is the byte 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> - <li>if the index <code>x</code> is out of range, - a <a href="#Run_time_panics">run-time panic</a> occurs</li> -</ul> - -<p> -For <code>a</code> of type <code>M</code> -where <code>M</code> is a <a href="#Map_types">map type</a>: -</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 value with key <code>x</code> - and the type of <code>a[x]</code> is the value 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 value 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> -may be used in an assignment or initialization of the special form -</p> - -<pre> -v, ok = a[x] -v, ok := a[x] -var v, ok = a[x] -</pre> - -<p> -where the result of the index expression is a pair of values with types -<code>(V, bool)</code>. In this form, the value of <code>ok</code> is -<code>true</code> if the key <code>x</code> is present in the map, and -<code>false</code> otherwise. The value of <code>v</code> is the value -<code>a[x]</code> as in the single-result form. -</p> - -<p> -Similarly, if an assignment to a map element has the special form -</p> - -<pre> -a[x] = v, ok -</pre> - -<p> -and boolean <code>ok</code> has the value <code>false</code>, -the entry for key <code>x</code> is deleted from the map; if -<code>ok</code> is <code>true</code>, the construct acts like -a regular assignment to an element of the map. -</p> - -<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="Slices">Slices</h3> - -<p> -For a string, array, or slice <code>a</code>, the primary expression -</p> - -<pre> -a[low : high] -</pre> - -<p> -constructs a substring or slice. The index expressions <code>low</code> and -<code>high</code> select which elements appear in the result. The result has -indexes 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 index expressions may be omitted. A missing <code>low</code> -index defaults to zero; a missing <code>high</code> index defaults to the length of the -sliced operand: -</p> - -<pre> -a[2:] // same a[2 : len(a)] -a[:3] // same as a[0 : 3] -a[:] // same as a[0 : len(a)] -</pre> - -<p> -For arrays or strings, the indexes <code>low</code> and <code>high</code> must -satisfy 0 <= <code>low</code> <= <code>high</code> <= length; for -slices, the upper bound is the capacity rather than the length. -</p> - -<p> -If the sliced operand is a string or slice, the result of the slice operation -is a string or slice of the same type. -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> - - -<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>. -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> (§<a href="#Interface_types">Interface types</a>). -</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> -<p> -If a type assertion is used in an assignment or initialization of the form -</p> - -<pre> -v, ok = x.(T) -v, ok := x.(T) -var v, ok = x.(T) -</pre> - -<p> -the result of the assertion is a pair of values with types <code>(T, bool)</code>. -If the assertion holds, the expression returns the pair <code>(x.(T), true)</code>; -otherwise, the expression returns <code>(Z, false)</code> where <code>Z</code> -is the <a href="#The_zero_value">zero value</a> for type <code>T</code>. -No run-time panic occurs in this case. -The type assertion in this construct thus acts like a function call -returning a value and a boolean indicating success. (§<a href="#Assignments">Assignments</a>) -</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> -As a special case, if the return parameters 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>. -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 variadic with final parameter type <code>...T</code>, -then within the function the argument is equivalent to a parameter of type -<code>[]T</code>. At each call of <code>f</code>, the argument -passed to the final parameter is -a new slice of type <code>[]T</code> whose successive elements are -the actual arguments, which all must be <a href="#Assignability">assignable</a> -to the type <code>T</code>. The length of the slice is therefore the number of -arguments bound to the final parameter and may differ for each call site. -</p> - -<p> -Given the function and call -</p> -<pre> -func Greeting(prefix string, who ...string) -Greeting("hello:", "Joe", "Anna", "Eileen") -</pre> - -<p> -within <code>Greeting</code>, <code>who</code> will have the value -<code>[]string{"Joe", "Anna", "Eileen"}</code> -</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 UnaryExpr . -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 that can be converted to unsigned integer type. -If the left operand of a non-constant shift expression is an untyped constant, -the type of the constant is what it would be if the shift expression were -replaced by its left operand alone; the type is <code>int</code> if it cannot -be determined from the context (for instance, if the shift expression is an -operand in a comparison against an untyped constant). -</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 // legal: 1.0 has type int -var n = 1.0<<s != 0 // legal: 1.0 has type int; n == false if ints are 32bits in size -var o = 1<<s == 2<<s // legal: 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 v float32 = 1<<s // illegal: 1 has type float32, cannot shift -var w int64 = 1.0<<33 // legal: 1.0<<33 is a constant shift expression -</pre> - -<h3 id="Operator_precedence">Operator precedence</h3> -<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 && <-chan_ptr > 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. All other arithmetic 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> - -<p> -Strings can be concatenated using the <code>+</code> operator -or the <code>+=</code> assignment operator: -</p> - -<pre> -s := "hi" + string(c) -s += " and good bye" -</pre> - -<p> -String addition creates a new string by concatenating the operands. -</p> -<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="http://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> -As an exception to this rule, if the dividend <code>x</code> is the most -negative value for the int type of <code>x</code>, the quotient -<code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>). -</p> - -<pre> - x, q -int8 -128 -int16 -32768 -int32 -2147483648 -int64 -9223372036854775808 -</pre> - -<p> -If the divisor is zero, a <a href="#Run_time_panics">run-time panic</a> occurs. -If the dividend is positive 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> - -<p> -For floating-point 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 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> - -<h3 id="Integer_overflow">Integer overflow</h3> - -<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 unsigned integer's type -(§<a href="#Numeric_types">Numeric types</a>). 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>, 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> - - -<h3 id="Comparison_operators">Comparison operators</h3> - -<p> -Comparison operators compare two operands and yield a value of type <code>bool</code>. -</p> - -<pre class="grammar"> -== equal -!= not equal -< less -<= less or equal -> greater ->= greater or equal -</pre> - -<p> -The operands must be <i>comparable</i>; that is, the first operand -must be <a href="#Assignability">assignable</a> -to the type of the second operand, or vice versa. -</p> -<p> -The operators <code>==</code> and <code>!=</code> apply -to operands of all types except arrays and structs. -All other comparison operators apply only to integer, floating-point -and string values. The result of a comparison is defined as follows: -</p> - -<ul> - <li> - Integer values are compared in the usual way. - </li> - <li> - Floating point values are compared as defined by the IEEE-754 - standard. - </li> - <li> - Two complex values <code>u</code>, <code>v</code> are - equal if both <code>real(u) == real(v)</code> and - <code>imag(u) == imag(v)</code>. - </li> - <li> - String values are compared byte-wise (lexically). - </li> - <li> - Boolean values are equal if they are either both - <code>true</code> or both <code>false</code>. - </li> - <li> - Pointer values are equal if they point to the same location - or if both are <code>nil</code>. - </li> - <li> - Function values are equal if they refer to the same function - or if both are <code>nil</code>. - </li> - <li> - A slice value may only be compared to <code>nil</code>. - </li> - <li> - Channel and map values are equal if they were created by the same call to <code>make</code> - (§<a href="#Making_slices_maps_and_channels">Making slices, maps, and channels</a>) - or if both are <code>nil</code>. - </li> - <li> - Interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types and - equal dynamic values or if both are <code>nil</code>. - </li> - <li> - An interface value <code>x</code> is equal to a non-interface value - <code>y</code> if the dynamic type of <code>x</code> is identical to - the static type of <code>y</code> and the dynamic value of <code>x</code> - is equal to <code>y</code>. - </li> - <li> - A pointer, function, slice, channel, map, or interface value is equal - to <code>nil</code> if it has been assigned the explicit value - <code>nil</code>, if it is uninitialized, or if it has been assigned - another value equal to <code>nil</code>. - </li> -</ul> - - -<h3 id="Logical_operators">Logical operators</h3> - -<p> -Logical operators apply to <a href="#Boolean_types">boolean</a> values -and yield a result of the same type as the operands. -The right operand is evaluated conditionally. -</p> - -<pre class="grammar"> -&& conditional and p && q is "if p then q else false" -|| conditional or p || q is "if p then true else q" -! not !p is "not p" -</pre> - - -<h3 id="Address_operators">Address operators</h3> - -<p> -For an operand <code>x</code> of type <code>T</code>, the address operation -<code>&x</code> generates a pointer of type <code>*T</code> to <code>x</code>. -The operand must be <i>addressable</i>, -that is, either a variable, pointer indirection, or slice indexing -operation; or a field selector of an addressable struct operand; -or an array indexing operation of an addressable array. -As an exception to the addressability requirement, <code>x</code> may also be a -<a href="#Composite_literals">composite literal</a>. -</p> -<p> -For an operand <code>x</code> of pointer type <code>*T</code>, the pointer -indirection <code>*x</code> denotes the value of type <code>T</code> pointed -to by <code>x</code>. -</p> - -<pre> -&x -&a[f(2)] -*p -*pf(x) -</pre> - - -<h3 id="Receive_operator">Receive operator</h3> - -<p> -For an operand <code>ch</code> of <a href="#Channel_types">channel type</a>, -the value of the receive operation <code><-ch</code> is the value received -from the channel <code>ch</code>. The type of the value is the element type of -the channel. The expression blocks until a value is available. -Receiving from a <code>nil</code> channel blocks forever. -</p> - -<pre> -v1 := <-ch -v2 = <-ch -f(<-ch) -<-strobe // wait until clock pulse and discard received value -</pre> - -<p> -A receive expression used in an assignment or initialization of the form -</p> - -<pre> -x, ok = <-ch -x, ok := <-ch -var x, ok = <-ch -</pre> - -<p> -yields an additional result. -The boolean variable <code>ok</code> indicates whether -the received value was sent on the channel (<code>true</code>) -or is a <a href="#The_zero_value">zero value</a> returned -because the channel is closed and empty (<code>false</code>). -</p> - -<!-- -<p> -<span class="alert">TODO: Probably in a separate section, communication semantics -need to be presented regarding send, receive, select, and goroutines.</span> -</p> ---> - - -<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 = TypeName | "(" "*" TypeName ")" . -</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 three invocations are equivalent: -</p> - -<pre> -t.Mv(7) -T.Mv(t, 7) -f := T.Mv; f(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">closure</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="Conversions">Conversions</h3> - -<p> -Conversions are expressions of the form <code>T(x)</code> -where <code>T</code> is a type and <code>x</code> is an expression -that can be converted to type <code>T</code>. -</p> - -<pre class="ebnf"> -Conversion = Type "(" Expression ")" . -</pre> - -<p> -If the type starts with an operator it must be parenthesized: -</p> - -<pre> -*Point(p) // same as *(Point(p)) -(*Point)(p) // p is converted to (*Point) -<-chan int(c) // same as <-(chan int(c)) -(<-chan int)(c) // c is converted to (<-chan int) -</pre> - -<p> -A <a href="#Constants">constant</a> value <code>x</code> can be converted to -type <code>T</code> in any of these cases: -</p> - -<ul> - <li> - <code>x</code> is representable by a value of type <code>T</code>. - </li> - <li> - <code>x</code> is an integer constant and <code>T</code> is a - <a href="#String_types">string type</a>. - The same rule as for non-constant <code>x</code> applies in this case - (§<a href="#Conversions_to_and_from_a_string_type">Conversions to and from a string type</a>). - </li> -</ul> - -<p> -Converting a constant yields a typed constant as result. -</p> - -<pre> -uint(iota) // iota value of type uint -float32(2.718281828) // 2.718281828 of type float32 -complex128(1) // 1.0 + 0.0i of type complex128 -string('x') // "x" of type string -string(0x266c) // "♬" of type string -MyString("foo" + "bar") // "foobar" of type MyString -string([]byte{'a'}) // not a constant: []byte{'a'} is not a constant -(*int)(nil) // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type -int(1.2) // illegal: 1.2 cannot be represented as an int -string(65.0) // illegal: 65.0 is not an integer constant -</pre> - -<p> -A non-constant value <code>x</code> can be converted to type <code>T</code> -in any of these cases: -</p> - -<ul> - <li> - <code>x</code> is <a href="#Assignability">assignable</a> - to <code>T</code>. - </li> - <li> - <code>x</code>'s type and <code>T</code> have identical - <a href="#Types">underlying types</a>. - </li> - <li> - <code>x</code>'s type and <code>T</code> are unnamed pointer types - and their pointer base types have identical underlying types. - </li> - <li> - <code>x</code>'s type and <code>T</code> are both integer or floating - point types. - </li> - <li> - <code>x</code>'s type and <code>T</code> are both complex types. - </li> - <li> - <code>x</code> is an integer or has type <code>[]byte</code> or - <code>[]int</code> and <code>T</code> is a string type. - </li> - <li> - <code>x</code> is a string and <code>T</code> is <code>[]byte</code> or - <code>[]int</code>. - </li> -</ul> - -<p> -Specific rules apply to (non-constant) conversions between numeric types or -to and from a string type. -These conversions may change the representation of <code>x</code> -and incur a run-time cost. -All other conversions only change the type but not the representation -of <code>x</code>. -</p> - -<p> -There is no linguistic mechanism to convert between pointers and integers. -The package <a href="#Package_unsafe"><code>unsafe</code></a> -implements this functionality under -restricted circumstances. -</p> - -<h4>Conversions between numeric types</h4> - -<p> -For the conversion of non-constant numeric values, the following rules apply: -</p> - -<ol> -<li> -When converting between integer types, if the value is a signed integer, it is -sign extended to implicit infinite precision; otherwise it is zero extended. -It is then truncated to fit in the result type's size. -For example, if <code>v := uint16(0x10F0)</code>, then <code>uint32(int8(v)) == 0xFFFFFFF0</code>. -The conversion always yields a valid value; there is no indication of overflow. -</li> -<li> -When converting a floating-point number to an integer, the fraction is discarded -(truncation towards zero). -</li> -<li> -When converting an integer or floating-point number to a floating-point type, -or a complex number to another complex type, the result value is rounded -to the precision specified by the destination type. -For instance, the value of a variable <code>x</code> of type <code>float32</code> -may be stored using additional precision beyond that of an IEEE-754 32-bit number, -but float32(x) represents the result of rounding <code>x</code>'s value to -32-bit precision. Similarly, <code>x + 0.1</code> may use more than 32 bits -of precision, but <code>float32(x + 0.1)</code> does not. -</li> -</ol> - -<p> -In all non-constant conversions involving floating-point or complex values, -if the result type cannot represent the value the conversion -succeeds but the result value is implementation-dependent. -</p> - -<h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4> - -<ol> -<li> -Converting a signed or unsigned integer value to a string type yields a -string containing the UTF-8 representation of the integer. Values outside -the range of valid Unicode code points are converted to <code>"\uFFFD"</code>. - -<pre> -string('a') // "a" -string(-1) // "\ufffd" == "\xef\xbf\xbd " -string(0xf8) // "\u00f8" == "ø" == "\xc3\xb8" -type MyString string -MyString(0x65e5) // "\u65e5" == "日" == "\xe6\x97\xa5" -</pre> -</li> - -<li> -Converting a value of type <code>[]byte</code> (or -the equivalent <code>[]uint8</code>) to a string type yields a -string whose successive bytes are the elements of the slice. If -the slice value is <code>nil</code>, the result is the empty string. - -<pre> -string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø" -</pre> -</li> - -<li> -Converting a value of type <code>[]int</code> to a string type yields -a string that is the concatenation of the individual integers -converted to strings. If the slice value is <code>nil</code>, the -result is the empty string. -<pre> -string([]int{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔" -</pre> -</li> - -<li> -Converting a value of a string type to <code>[]byte</code> (or <code>[]uint8</code>) -yields a slice whose successive elements are the bytes of the string. -If the string is empty, the result is <code>[]byte(nil)</code>. - -<pre> -[]byte("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} -</pre> -</li> - -<li> -Converting a value of a string type to <code>[]int</code> yields a -slice containing the individual Unicode code points of the string. -If the string is empty, the result is <code>[]int(nil)</code>. -<pre> -[]int(MyString("白鵬翔")) // []int{0x767d, 0x9d6c, 0x7fd4} -</pre> -</li> -</ol> - - -<h3 id="Constant_expressions">Constant expressions</h3> - -<p> -Constant expressions may contain only <a href="#Constants">constant</a> -operands and are evaluated at compile-time. -</p> - -<p> -Untyped boolean, numeric, and string constants may be used as operands -wherever it is legal to use an operand of boolean, numeric, or string type, -respectively. Except for shift operations, if the operands of a binary operation -are an untyped integer constant and an untyped floating-point constant, -the integer constant is converted to an untyped floating-point constant -(relevant for <code>/</code> and <code>%</code>). -Similarly, untyped integer or floating-point constants may be used as operands -wherever it is legal to use an operand of complex type; -the integer or floating point constant is converted to a -complex constant with a zero imaginary part. -</p> - -<p> -A constant <a href="#Comparison_operators">comparison</a> always yields -a constant of type <code>bool</code>. If the left operand of a constant -<a href="#Operators">shift expression</a> is an untyped constant, the -result is an integer constant; otherwise it is a constant of the same -type as the left operand, which must be of integer type -(§<a href="#Arithmetic_operators">Arithmetic operators</a>). -Applying all other operators to untyped constants results in an untyped -constant of the same kind (that is, a boolean, integer, floating-point, -complex, or string constant). -</p> - -<pre> -const a = 2 + 3.0 // a == 5.0 (floating-point constant) -const b = 15 / 4 // b == 3 (integer constant) -const c = 15 / 4.0 // c == 3.75 (floating-point constant) -const d = 1 << 3.0 // d == 8 (integer constant) -const e = 1.0 << 3 // e == 8 (integer constant) -const f = int32(1) << 33 // f == 0 (type int32) -const g = float64(2) >> 1 // illegal (float64(2) is a typed floating-point constant) -const h = "foo" > "bar" // h == true (type bool) -</pre> - -<p> -Imaginary literals are untyped complex constants (with zero real part) -and may be combined in binary -operations with untyped integer and floating-point constants; the -result is an untyped complex constant. -Complex constants are always constructed from -constant expressions involving imaginary -literals or constants derived from them, or calls of the built-in function -<a href="#Complex_numbers"><code>complex</code></a>. -</p> - -<pre> -const Σ = 1 - 0.707i -const Δ = Σ + 2.0e-4 - 1/1i -const Φ = iota * 1i -const iΓ = complex(0, Γ) -</pre> - -<p> -Constant expressions are always evaluated exactly; intermediate values and the -constants themselves may require precision significantly larger than supported -by any predeclared type in the language. The following are legal declarations: -</p> - -<pre> -const Huge = 1 << 100 -const Four int8 = Huge >> 98 -</pre> - -<p> -The values of <i>typed</i> constants must always be accurately representable as values -of the constant type. The following constant expressions are illegal: -</p> - -<pre> -uint(-1) // -1 cannot be represented as a uint -int(3.14) // 3.14 cannot be represented as an int -int64(Huge) // 1<<100 cannot be represented as an int64 -Four * 300 // 300 cannot be represented as an int8 -Four * 100 // 400 cannot be represented as an int8 -</pre> - -<p> -The mask used by the unary bitwise complement operator <code>^</code> matches -the rule for non-constants: the mask is all 1s for unsigned constants -and -1 for signed and untyped constants. -</p> - -<pre> -^1 // untyped integer constant, equal to -2 -uint8(^1) // error, same as uint8(-2), out of range -^uint8(1) // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE) -int8(^1) // same as int8(-2) -^int8(1) // same as -1 ^ int8(1) = -2 -</pre> - -<!-- -<p> -<span class="alert"> -TODO: perhaps ^ should be disallowed on non-uints instead of assuming twos complement. -Also it may be possible to make typed constants more like variables, at the cost of fewer -overflow etc. errors being caught. -</span> -</p> ---> - -<h3 id="Order_of_evaluation">Order of evaluation</h3> - -<p> -When evaluating the elements of an assignment or expression, -all function calls, method calls and -communication operations are evaluated in lexical left-to-right -order. -</p> - -<p> -For example, in the assignment -</p> -<pre> -y[f()], ok = g(h(), i() + x[j()], <-c), k() -</pre> -<p> -the function calls and communication happen in the order -<code>f()</code>, <code>h()</code>, <code>i()</code>, <code>j()</code>, -<code><-c</code>, <code>g()</code>, and <code>k()</code>. -However, the order of those events compared to the evaluation -and indexing of <code>x</code> and the evaluation -of <code>y</code> is not specified. -</p> - -<p> -Floating-point operations within a single expression are evaluated according to -the associativity of the operators. Explicit parentheses affect the evaluation -by overriding the default associativity. -In the expression <code>x + (y + z)</code> the addition <code>y + z</code> -is performed before adding <code>x</code>. -</p> - -<h2 id="Statements">Statements</h2> - -<p> -Statements control execution. -</p> - -<pre class="ebnf"> -Statement = - Declaration | LabeledStmt | SimpleStmt | - GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt | - FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt | - DeferStmt . - -SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl . -</pre> - - -<h3 id="Empty_statements">Empty statements</h3> - -<p> -The empty statement does nothing. -</p> - -<pre class="ebnf"> -EmptyStmt = . -</pre> - - -<h3 id="Labeled_statements">Labeled statements</h3> - -<p> -A labeled statement may be the target of a <code>goto</code>, -<code>break</code> or <code>continue</code> statement. -</p> - -<pre class="ebnf"> -LabeledStmt = Label ":" Statement . -Label = identifier . -</pre> - -<pre> -Error: log.Panic("error encountered") -</pre> - - -<h3 id="Expression_statements">Expression statements</h3> - -<p> -Function calls, method calls, and receive operations -can appear in statement context. Such statements may be parenthesized. -</p> - -<pre class="ebnf"> -ExpressionStmt = Expression . -</pre> - -<pre> -h(x+y) -f.Close() -<-ch -(<-ch) -</pre> - - -<h3 id="Send_statements">Send statements</h3> - -<p> -A send statement sends a value on a channel. -The channel expression must be of <a href="#Channel_types">channel type</a> -and the type of the value must be <a href="#Assignability">assignable</a> -to the channel's element type. -</p> - -<pre class="ebnf"> -SendStmt = Channel "<-" Expression . -Channel = Expression . -</pre> - -<p> -Both the channel and the value expression are evaluated before communication -begins. Communication blocks until the send can proceed, at which point the -value is transmitted on the channel. -A send on an unbuffered channel can proceed if a receiver is ready. -A send on a buffered channel can proceed if there is room in the buffer. -A send on a <code>nil</code> channel blocks forever. -</p> - -<pre> -ch <- 3 -</pre> - - -<h3 id="IncDec_statements">IncDec statements</h3> - -<p> -The "++" and "--" statements increment or decrement their operands -by the untyped <a href="#Constants">constant</a> <code>1</code>. -As with an assignment, the operand must be <a href="#Address_operators">addressable</a> -or a map index expression. -</p> - -<pre class="ebnf"> -IncDecStmt = Expression ( "++" | "--" ) . -</pre> - -<p> -The following <a href="#Assignments">assignment statements</a> are semantically -equivalent: -</p> - -<pre class="grammar"> -IncDec statement Assignment -x++ x += 1 -x-- x -= 1 -</pre> - - -<h3 id="Assignments">Assignments</h3> - -<pre class="ebnf"> -Assignment = ExpressionList assign_op ExpressionList . - -assign_op = [ add_op | mul_op ] "=" . -</pre> - -<p> -Each left-hand side operand must be <a href="#Address_operators">addressable</a>, -a map index expression, or the <a href="#Blank_identifier">blank identifier</a>. -Operands may be parenthesized. -</p> - -<pre> -x = 1 -*p = f() -a[i] = 23 -(k) = <-ch // same as: k = <-ch -</pre> - -<p> -An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code> -<code>y</code> where <i>op</i> is a binary arithmetic operation is equivalent -to <code>x</code> <code>=</code> <code>x</code> <i>op</i> -<code>y</code> but evaluates <code>x</code> -only once. The <i>op</i><code>=</code> construct is a single token. -In assignment operations, both the left- and right-hand expression lists -must contain exactly one single-valued expression. -</p> - -<pre> -a[i] <<= 2 -i &^= 1<<n -</pre> - -<p> -A tuple assignment assigns the individual elements of a multi-valued -operation to a list of variables. There are two forms. In the -first, the right hand operand is a single multi-valued expression -such as a function evaluation or <a href="#Channel_types">channel</a> or -<a href="#Map_types">map</a> operation or a <a href="#Type_assertions">type assertion</a>. -The number of operands on the left -hand side must match the number of values. For instance, if -<code>f</code> is a function returning two values, -</p> - -<pre> -x, y = f() -</pre> - -<p> -assigns the first value to <code>x</code> and the second to <code>y</code>. -The <a href="#Blank_identifier">blank identifier</a> provides a -way to ignore values returned by a multi-valued expression: -</p> - -<pre> -x, _ = f() // ignore second value returned by f() -</pre> - -<p> -In the second form, the number of operands on the left must equal the number -of expressions on the right, each of which must be single-valued, and the -<i>n</i>th expression on the right is assigned to the <i>n</i>th -operand on the left. -The expressions on the right are evaluated before assigning to -any of the operands on the left, but otherwise the evaluation -order is unspecified beyond <a href="#Order_of_evaluation">the usual rules</a>. -</p> - -<pre> -a, b = b, a // exchange a and b -</pre> - -<p> -In assignments, each value must be -<a href="#Assignability">assignable</a> to the type of the -operand to which it is assigned. If an untyped <a href="#Constants">constant</a> -is assigned to a variable of interface type, the constant is <a href="#Conversions">converted</a> -to type <code>bool</code>, <code>int</code>, <code>float64</code>, -<code>complex128</code> or <code>string</code> -respectively, depending on whether the value is a boolean, integer, floating-point, -complex, or string constant. -</p> - - -<h3 id="If_statements">If statements</h3> - -<p> -"If" statements specify the conditional execution of two branches -according to the value of a boolean expression. If the expression -evaluates to true, the "if" branch is executed, otherwise, if -present, the "else" branch is executed. -</p> - -<pre class="ebnf"> -IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" Statement ] . -</pre> - -<pre> -if x > max { - x = max -} -</pre> - -<p> -The expression may be preceded by a simple statement, which -executes before the expression is evaluated. -</p> - -<pre> -if x := f(); x < y { - return x -} else if x > z { - return z -} else { - return y -} -</pre> - - -<h3 id="Switch_statements">Switch statements</h3> - -<p> -"Switch" statements provide multi-way execution. -An expression or type specifier is compared to the "cases" -inside the "switch" to determine which branch -to execute. -</p> - -<pre class="ebnf"> -SwitchStmt = ExprSwitchStmt | TypeSwitchStmt . -</pre> - -<p> -There are two forms: expression switches and type switches. -In an expression switch, the cases contain expressions that are compared -against the value of the switch expression. -In a type switch, the cases contain types that are compared against the -type of a specially annotated switch expression. -</p> - -<h4 id="Expression_switches">Expression switches</h4> - -<p> -In an expression switch, -the switch expression is evaluated and -the case expressions, which need not be constants, -are evaluated left-to-right and top-to-bottom; the first one that equals the -switch expression -triggers execution of the statements of the associated case; -the other cases are skipped. -If no case matches and there is a "default" case, -its statements are executed. -There can be at most one default case and it may appear anywhere in the -"switch" statement. -A missing switch expression is equivalent to -the expression <code>true</code>. -</p> - -<pre class="ebnf"> -ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" . -ExprCaseClause = ExprSwitchCase ":" { Statement ";" } . -ExprSwitchCase = "case" ExpressionList | "default" . -</pre> - -<p> -In a case or default clause, -the last statement only may be a "fallthrough" statement -(§<a href="#Fallthrough_statements">Fallthrough statement</a>) to -indicate that control should flow from the end of this clause to -the first statement of the next clause. -Otherwise control flows to the end of the "switch" statement. -</p> - -<p> -The expression may be preceded by a simple statement, which -executes before the expression is evaluated. -</p> - -<pre> -switch tag { -default: s3() -case 0, 1, 2, 3: s1() -case 4, 5, 6, 7: s2() -} - -switch x := f(); { // missing switch expression means "true" -case x < 0: return -x -default: return x -} - -switch { -case x < y: f1() -case x < z: f2() -case x == 4: f3() -} -</pre> - -<h4 id="Type_switches">Type switches</h4> - -<p> -A type switch compares types rather than values. It is otherwise similar -to an expression switch. It is marked by a special switch expression that -has the form of a <a href="#Type_assertions">type assertion</a> -using the reserved word <code>type</code> rather than an actual type. -Cases then match literal types against the dynamic type of the expression -in the type assertion. -</p> - -<pre class="ebnf"> -TypeSwitchStmt = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" . -TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" . -TypeCaseClause = TypeSwitchCase ":" { Statement ";" } . -TypeSwitchCase = "case" TypeList | "default" . -TypeList = Type { "," Type } . -</pre> - -<p> -The TypeSwitchGuard may include a -<a href="#Short_variable_declarations">short variable declaration</a>. -When that form is used, the variable is declared in each clause. -In clauses with a case listing exactly one type, the variable -has that type; otherwise, the variable has the type of the expression -in the TypeSwitchGuard. -</p> - -<p> -The type in a case may be <code>nil</code> -(§<a href="#Predeclared_identifiers">Predeclared identifiers</a>); -that case is used when the expression in the TypeSwitchGuard -is a <code>nil</code> interface value. -</p> - -<p> -Given an expression <code>x</code> of type <code>interface{}</code>, -the following type switch: -</p> - -<pre> -switch i := x.(type) { -case nil: - printString("x is nil") -case int: - printInt(i) // i is an int -case float64: - printFloat64(i) // i is a float64 -case func(int) float64: - printFunction(i) // i is a function -case bool, string: - printString("type is bool or string") // i is an interface{} -default: - printString("don't know the type") -} -</pre> - -<p> -could be rewritten: -</p> - -<pre> -v := x // x is evaluated exactly once -if v == nil { - printString("x is nil") -} else if i, is_int := v.(int); is_int { - printInt(i) // i is an int -} else if i, is_float64 := v.(float64); is_float64 { - printFloat64(i) // i is a float64 -} else if i, is_func := v.(func(int) float64); is_func { - printFunction(i) // i is a function -} else { - i1, is_bool := v.(bool) - i2, is_string := v.(string) - if is_bool || is_string { - i := v - printString("type is bool or string") // i is an interface{} - } else { - i := v - printString("don't know the type") // i is an interface{} - } -} -</pre> - -<p> -The type switch guard may be preceded by a simple statement, which -executes before the guard is evaluated. -</p> - -<p> -The "fallthrough" statement is not permitted in a type switch. -</p> - -<h3 id="For_statements">For statements</h3> - -<p> -A "for" statement specifies repeated execution of a block. The iteration is -controlled by a condition, a "for" clause, or a "range" clause. -</p> - -<pre class="ebnf"> -ForStmt = "for" [ Condition | ForClause | RangeClause ] Block . -Condition = Expression . -</pre> - -<p> -In its simplest form, a "for" statement specifies the repeated execution of -a block as long as a boolean condition evaluates to true. -The condition is evaluated before each iteration. -If the condition is absent, it is equivalent to <code>true</code>. -</p> - -<pre> -for a < b { - a *= 2 -} -</pre> - -<p> -A "for" statement with a ForClause is also controlled by its condition, but -additionally it may specify an <i>init</i> -and a <i>post</i> statement, such as an assignment, -an increment or decrement statement. The init statement may be a -<a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not. -</p> - -<pre class="ebnf"> -ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] . -InitStmt = SimpleStmt . -PostStmt = SimpleStmt . -</pre> - -<pre> -for i := 0; i < 10; i++ { - f(i) -} -</pre> - -<p> -If non-empty, the init statement is executed once before evaluating the -condition for the first iteration; -the post statement is executed after each execution of the block (and -only if the block was executed). -Any element of the ForClause may be empty but the -<a href="#Semicolons">semicolons</a> are -required unless there is only a condition. -If the condition is absent, it is equivalent to <code>true</code>. -</p> - -<pre> -for cond { S() } is the same as for ; cond ; { S() } -for { S() } is the same as for true { S() } -</pre> - -<p> -A "for" statement with a "range" clause -iterates through all entries of an array, slice, string or map, -or values received on a channel. For each entry it assigns <i>iteration values</i> -to corresponding <i>iteration variables</i> and then executes the block. -</p> - -<pre class="ebnf"> -RangeClause = Expression [ "," Expression ] ( "=" | ":=" ) "range" Expression . -</pre> - -<p> -The expression on the right in the "range" clause is called the <i>range expression</i>, -which may be an array, pointer to an array, slice, string, map, or channel. -As with an assignment, the operands on the left must be -<a href="#Address_operators">addressable</a> or map index expressions; they -denote the iteration variables. If the range expression is a channel, only -one iteration variable is permitted, otherwise there may be one or two. -If the second iteration variable is the <a href="#Blank_identifier">blank identifier</a>, -the range clause is equivalent to the same clause with only the first variable present. -</p> - -<p> -The range expression is evaluated once before beginning the loop -except if the expression is an array, in which case, depending on -the expression, it might not be evaluated (see below). -Function calls on the left are evaluated once per iteration. -For each iteration, iteration values are produced as follows: -</p> - -<pre class="grammar"> -Range expression 1st value 2nd value (if 2nd variable is present) - -array or slice a [n]E, *[n]E, or []E index i int a[i] E -string s string type index i int see below int -map m map[K]V key k K m[k] V -channel c chan E element e E -</pre> - -<ol> -<li> -For an array, pointer to array, or slice value <code>a</code>, the index iteration -values are produced in increasing order, starting at element index 0. As a special -case, if only the first iteration variable is present, the range loop produces -iteration values from 0 up to <code>len(a)</code> and does not index into the array -or slice itself. For a <code>nil</code> slice, the number of iterations is 0. -</li> - -<li> -For a string value, the "range" clause iterates over the Unicode code points -in the string starting at byte index 0. On successive iterations, the index value will be the -index of the first byte of successive UTF-8-encoded code points in the string, -and the second value, of type <code>int</code>, will be the value of -the corresponding code point. If the iteration encounters an invalid -UTF-8 sequence, the second value will be <code>0xFFFD</code>, -the Unicode replacement character, and the next iteration will advance -a single byte in the string. -</li> - -<li> -The iteration order over maps is not specified. -If map entries that have not yet been reached are deleted during iteration, -the corresponding iteration values will not be produced. If map entries are -inserted during iteration, the behavior is implementation-dependent, but the -iteration values for each entry will be produced at most once. If the map -is <code>nil</code>, the number of iterations is 0. -</li> - -<li> -For channels, the iteration values produced are the successive values sent on -the channel until the channel is <a href="#Close">closed</a>. If the channel -is <code>nil</code>, the range expression blocks forever. -</li> -</ol> - -<p> -The iteration values are assigned to the respective -iteration variables as in an <a href="#Assignments">assignment statement</a>. -</p> - -<p> -The iteration variables may be declared by the "range" clause (<code>:=</code>). -In this case their types are set to the types of the respective iteration values -and their <a href="#Declarations_and_scope">scope</a> ends at the end of the "for" -statement; they are re-used in each iteration. -If the iteration variables are declared outside the "for" statement, -after execution their values will be those of the last iteration. -</p> - -<pre> -var testdata *struct { - a *[7]int -} -for i, _ := range testdata.a { - // testdata.a is never evaluated; len(testdata.a) is constant - // i ranges from 0 to 6 - f(i) -} - -var a [10]string -m := map[string]int{"mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6} -for i, s := range a { - // type of i is int - // type of s is string - // s == a[i] - g(i, s) -} - -var key string -var val interface {} // value type of m is assignable to val -for key, val = range m { - h(key, val) -} -// key == last map key encountered in iteration -// val == map[key] - -var ch chan Work = producer() -for w := range ch { - doWork(w) -} -</pre> - - -<h3 id="Go_statements">Go statements</h3> - -<p> -A "go" statement starts the execution of a function or method call -as an independent concurrent thread of control, or <i>goroutine</i>, -within the same address space. -</p> - -<pre class="ebnf"> -GoStmt = "go" Expression . -</pre> - -<p> -The expression must be a call, and -unlike with a regular call, program execution does not wait -for the invoked function to complete. -</p> - -<pre> -go Server() -go func(ch chan<- bool) { for { sleep(10); ch <- true; }} (c) -</pre> - - -<h3 id="Select_statements">Select statements</h3> - -<p> -A "select" statement chooses which of a set of possible communications -will proceed. It looks similar to a "switch" statement but with the -cases all referring to communication operations. -</p> - -<pre class="ebnf"> -SelectStmt = "select" "{" { CommClause } "}" . -CommClause = CommCase ":" { Statement ";" } . -CommCase = "case" ( SendStmt | RecvStmt ) | "default" . -RecvStmt = [ Expression [ "," Expression ] ( "=" | ":=" ) ] RecvExpr . -RecvExpr = Expression . -</pre> - -<p> -RecvExpr must be a <a href="#Receive_operator">receive operation</a>. -For all the cases in the "select" -statement, the channel expressions are evaluated in top-to-bottom order, along with -any expressions that appear on the right hand side of send statements. -A channel may be <code>nil</code>, -which is equivalent to that case not -being present in the select statement -except, if a send, its expression is still evaluated. -If any of the resulting operations can proceed, one of those is -chosen and the corresponding communication and statements are -evaluated. Otherwise, if there is a default case, that executes; -if there is no default case, the statement blocks until one of the communications can -complete. -If there are no cases with non-<code>nil</code> channels, -the statement blocks forever. -Even if the statement blocks, -the channel and send expressions are evaluated only once, -upon entering the select statement. -</p> -<p> -Since all the channels and send expressions are evaluated, any side -effects in that evaluation will occur for all the communications -in the "select" statement. -</p> -<p> -If multiple cases can proceed, a pseudo-random fair choice is made to decide -which single communication will execute. -<p> -The receive case may declare one or two new variables using a -<a href="#Short_variable_declarations">short variable declaration</a>. -</p> - -<pre> -var c, c1, c2, c3 chan int -var i1, i2 int -select { -case i1 = <-c1: - print("received ", i1, " from c1\n") -case c2 <- i2: - print("sent ", i2, " to c2\n") -case i3, ok := (<-c3): // same as: i3, ok := <-c3 - if ok { - print("received ", i3, " from c3\n") - } else { - print("c3 is closed\n") - } -default: - print("no communication\n") -} - -for { // send random sequence of bits to c - select { - case c <- 0: // note: no statement, no fallthrough, no folding of cases - case c <- 1: - } -} - -select { } // block forever -</pre> - - -<h3 id="Return_statements">Return statements</h3> - -<p> -A "return" statement terminates execution of the containing function -and optionally provides a result value or values to the caller. -</p> - -<pre class="ebnf"> -ReturnStmt = "return" [ ExpressionList ] . -</pre> - -<p> -In a function without a result type, a "return" statement must not -specify any result values. -</p> -<pre> -func no_result() { - return -} -</pre> - -<p> -There are three ways to return values from a function with a result -type: -</p> - -<ol> - <li>The return value or values may be explicitly listed - in the "return" statement. Each expression must be single-valued - and <a href="#Assignability">assignable</a> - to the corresponding element of the function's result type. -<pre> -func simple_f() int { - return 2 -} - -func complex_f1() (re float64, im float64) { - return -7.0, -4.0 -} -</pre> - </li> - <li>The expression list in the "return" statement may be a single - call to a multi-valued function. The effect is as if each value - returned from that function were assigned to a temporary - variable with the type of the respective value, followed by a - "return" statement listing these variables, at which point the - rules of the previous case apply. -<pre> -func complex_f2() (re float64, im float64) { - return complex_f1() -} -</pre> - </li> - <li>The expression list may be empty if the function's result - type specifies names for its result parameters (§<a href="#Function_types">Function Types</a>). - The result parameters act as ordinary local variables - and the function may assign values to them as necessary. - The "return" statement returns the values of these variables. -<pre> -func complex_f3() (re float64, im float64) { - re = 7.0 - im = 4.0 - return -} - -func (devnull) Write(p []byte) (n int, _ os.Error) { - n = len(p) - return -} -</pre> - </li> -</ol> - -<p> -Regardless of how they are declared, all the result values are initialized to the zero values for their type (§<a href="#The_zero_value">The zero value</a>) upon entry to the function. -</p> - -<!-- -<p> -<span class="alert"> -TODO: Define when return is required.<br /> -TODO: Language about result parameters needs to go into a section on - function/method invocation<br /> -</span> -</p> ---> - -<h3 id="Break_statements">Break statements</h3> - -<p> -A "break" statement terminates execution of the innermost -"for", "switch" or "select" statement. -</p> - -<pre class="ebnf"> -BreakStmt = "break" [ Label ] . -</pre> - -<p> -If there is a label, it must be that of an enclosing -"for", "switch" or "select" statement, and that is the one whose execution -terminates -(§<a href="#For_statements">For statements</a>, §<a href="#Switch_statements">Switch statements</a>, §<a href="#Select_statements">Select statements</a>). -</p> - -<pre> -L: - for i < n { - switch i { - case 5: - break L - } - } -</pre> - -<h3 id="Continue_statements">Continue statements</h3> - -<p> -A "continue" statement begins the next iteration of the -innermost "for" loop at its post statement (§<a href="#For_statements">For statements</a>). -</p> - -<pre class="ebnf"> -ContinueStmt = "continue" [ Label ] . -</pre> - -<p> -If there is a label, it must be that of an enclosing -"for" statement, and that is the one whose execution -advances -(§<a href="#For_statements">For statements</a>). -</p> - -<h3 id="Goto_statements">Goto statements</h3> - -<p> -A "goto" statement transfers control to the statement with the corresponding label. -</p> - -<pre class="ebnf"> -GotoStmt = "goto" Label . -</pre> - -<pre> -goto Error -</pre> - -<p> -Executing the "goto" statement must not cause any variables to come into -<a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto. -For instance, this example: -</p> - -<pre> - goto L // BAD - v := 3 -L: -</pre> - -<p> -is erroneous because the jump to label <code>L</code> skips -the creation of <code>v</code>. -</p> - -<p> -A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block. -For instance, this example: -</p> - -<pre> -if n%2 == 1 { - goto L1 -} -for n > 0 { - f() - n-- -L1: - f() - n-- -} -</pre> - -<p> -is erroneous because the label <code>L1</code> is inside -the "for" statement's block but the <code>goto</code> is not. -</p> - -<h3 id="Fallthrough_statements">Fallthrough statements</h3> - -<p> -A "fallthrough" statement transfers control to the first statement of the -next case clause in a expression "switch" statement (§<a href="#Expression_switches">Expression switches</a>). It may -be used only as the final non-empty statement in a case or default clause in an -expression "switch" statement. -</p> - -<pre class="ebnf"> -FallthroughStmt = "fallthrough" . -</pre> - - -<h3 id="Defer_statements">Defer statements</h3> - -<p> -A "defer" statement invokes a function whose execution is deferred to the moment -the surrounding function returns. -</p> - -<pre class="ebnf"> -DeferStmt = "defer" Expression . -</pre> - -<p> -The expression must be a function or method call. -Each time the "defer" statement -executes, the parameters to the function call are evaluated and saved anew but the -function is not invoked. -Deferred function calls are executed in LIFO order -immediately before the surrounding function returns, -after the return values, if any, have been evaluated, but before they -are returned to the caller. For instance, if the deferred function is -a <a href="#Function_literals">function literal</a> and the surrounding -function has <a href="#Function_types">named result parameters</a> that -are in scope within the literal, the deferred function may access and modify -the result parameters before they are returned. -</p> - -<pre> -lock(l) -defer unlock(l) // unlocking happens before surrounding function returns - -// prints 3 2 1 0 before surrounding function returns -for i := 0; i <= 3; i++ { - defer fmt.Print(i) -} - -// f returns 1 -func f() (result int) { - defer func() { - result++ - }() - return 0 -} -</pre> - -<h2 id="Built-in_functions">Built-in functions</h2> - -<p> -Built-in functions are -<a href="#Predeclared_identifiers">predeclared</a>. -They are called like any other function but some of them -accept a type instead of an expression as the first argument. -</p> - -<p> -The built-in functions do not have standard Go types, -so they can only appear in <a href="#Calls">call expressions</a>; -they cannot be used as function values. -</p> - -<pre class="ebnf"> -BuiltinCall = identifier "(" [ BuiltinArgs [ "," ] ] ")" . -BuiltinArgs = Type [ "," ExpressionList ] | ExpressionList . -</pre> - -<h3 id="Close">Close</h3> - -<p> -For a channel <code>c</code>, the built-in function <code>close(c)</code> -marks the channel as unable to accept more values through a send operation; -sending to or closing a closed channel causes a <a href="#Run_time_panics">run-time panic</a>. -After calling <code>close</code>, and after any previously -sent values have been received, receive operations will return -the zero value for the channel's type without blocking. - -The multi-valued <a href="#Receive_operator">receive operation</a> -returns a received value along with an indication of whether the channel is closed. -</p> - - -<h3 id="Length_and_capacity">Length and capacity</h3> - -<p> -The built-in functions <code>len</code> and <code>cap</code> take arguments -of various types and return a result of type <code>int</code>. -The implementation guarantees that the result always fits into an <code>int</code>. -</p> - -<pre class="grammar"> -Call Argument type Result - -len(s) string type string length in bytes - [n]T, *[n]T array length (== n) - []T slice length - map[K]T map length (number of defined keys) - chan T number of elements queued in channel buffer - -cap(s) [n]T, *[n]T array length (== n) - []T slice capacity - chan T channel buffer capacity -</pre> - -<p> -The capacity of a slice is the number of elements for which there is -space allocated in the underlying array. -At any time the following relationship holds: -</p> - -<pre> -0 <= len(s) <= cap(s) -</pre> - -<p> -The length and capacity of a <code>nil</code> slice, map, or channel are 0. -</p> - -<p> -The expression <code>len(s)</code> is <a href="#Constants">constant</a> if -<code>s</code> is a string constant. The expressions <code>len(s)</code> and -<code>cap(s)</code> are constants if the type of <code>s</code> is an array -or pointer to an array and the expression <code>s</code> does not contain -<a href="#Receive_operator">channel receives</a> or -<a href="#Calls">function calls</a>; in this case <code>s</code> is not evaluated. -Otherwise, invocations of <code>len</code> and <code>cap</code> are not -constant and <code>s</code> is evaluated. -</p> - - -<h3 id="Allocation">Allocation</h3> - -<p> -The built-in function <code>new</code> takes a type <code>T</code> and -returns a value of type <code>*T</code>. -The memory is initialized as described in the section on initial values -(§<a href="#The_zero_value">The zero value</a>). -</p> - -<pre class="grammar"> -new(T) -</pre> - -<p> -For instance -</p> - -<pre> -type S struct { a int; b float64 } -new(S) -</pre> - -<p> -dynamically allocates memory for a variable of type <code>S</code>, -initializes it (<code>a=0</code>, <code>b=0.0</code>), -and returns a value of type <code>*S</code> containing the address -of the memory. -</p> - -<h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3> - -<p> -Slices, maps and channels are reference types that do not require the -extra indirection of an allocation with <code>new</code>. -The built-in function <code>make</code> takes a type <code>T</code>, -which must be a slice, map or channel type, -optionally followed by a type-specific list of expressions. -It returns a value of type <code>T</code> (not <code>*T</code>). -The memory is initialized as described in the section on initial values -(§<a href="#The_zero_value">The zero value</a>). -</p> - -<pre class="grammar"> -Call Type T Result - -make(T, n) slice slice of type T with length n and capacity n -make(T, n, m) slice slice of type T with length n and capacity m - -make(T) map map of type T -make(T, n) map map of type T with initial space for n elements - -make(T) channel synchronous channel of type T -make(T, n) channel asynchronous channel of type T, buffer size n -</pre> - - -<p> -The arguments <code>n</code> and <code>m</code> must be of integer type. -A <a href="#Run_time_panics">run-time panic</a> occurs if <code>n</code> -is negative or larger than <code>m</code>, or if <code>n</code> or -<code>m</code> cannot be represented by an <code>int</code>. -</p> - -<pre> -s := make([]int, 10, 100) // slice with len(s) == 10, cap(s) == 100 -s := make([]int, 10) // slice with len(s) == cap(s) == 10 -c := make(chan int, 10) // channel with a buffer size of 10 -m := make(map[string] int, 100) // map with initial space for 100 elements -</pre> - - -<h3 id="Appending_and_copying_slices">Appending to and copying slices</h3> - -<p> -Two built-in functions assist in common slice operations. -</p> - -<p> -The <a href="#Function_types">variadic</a> function <code>append</code> -appends zero or more values <code>x</code> -to <code>s</code> of type <code>S</code>, which must be a slice type, and -returns the resulting slice, also of type <code>S</code>. -The values <code>x</code> are passed to a parameter of type <code>...T</code> -where <code>T</code> is the <a href="#Slice_types">element type</a> of -<code>S</code> and the respective -<a href="#Passing_arguments_to_..._parameters">parameter passing rules</a> apply. -</p> - -<pre class="grammar"> -append(s S, x ...T) S // T is the element type of S -</pre> - -<p> -If the capacity of <code>s</code> is not large enough to fit the additional -values, <code>append</code> allocates a new, sufficiently large slice that fits -both the existing slice elements and the additional values. Thus, the returned -slice may refer to a different underlying array. -</p> - -<pre> -s0 := []int{0, 0} -s1 := append(s0, 2) // append a single element s1 == []int{0, 0, 2} -s2 := append(s1, 3, 5, 7) // append multiple elements s2 == []int{0, 0, 2, 3, 5, 7} -s3 := append(s2, s0...) // append a slice s3 == []int{0, 0, 2, 3, 5, 7, 0, 0} - -var t []interface{} -t = append(t, 42, 3.1415, "foo") t == []interface{}{42, 3.1415, "foo"} -</pre> - -<p> -The function <code>copy</code> copies slice elements from -a source <code>src</code> to a destination <code>dst</code> and returns the -number of elements copied. Source and destination may overlap. -Both arguments must have <a href="#Type_identity">identical</a> element type <code>T</code> and must be -<a href="#Assignability">assignable</a> to a slice of type <code>[]T</code>. -The number of elements copied is the minimum of -<code>len(src)</code> and <code>len(dst)</code>. -As a special case, <code>copy</code> also accepts a destination argument assignable -to type <code>[]byte</code> with a source argument of a string type. -This form copies the bytes from the string into the byte slice. -</p> - -<pre class="grammar"> -copy(dst, src []T) int -copy(dst []byte, src string) int -</pre> - -<p> -Examples: -</p> - -<pre> -var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7} -var s = make([]int, 6) -var b = make([]byte, 5) -n1 := copy(s, a[0:]) // n1 == 6, s == []int{0, 1, 2, 3, 4, 5} -n2 := copy(s, s[2:]) // n2 == 4, s == []int{2, 3, 4, 5, 4, 5} -n3 := copy(b, "Hello, World!") // n3 == 5, b == []byte("Hello") -</pre> - -<h3 id="Complex_numbers">Assembling and disassembling complex numbers</h3> - -<p> -Three functions assemble and disassemble complex numbers. -The built-in function <code>complex</code> constructs a complex -value from a floating-point real and imaginary part, while -<code>real</code> and <code>imag</code> -extract the real and imaginary parts of a complex value. -</p> - -<pre class="grammar"> -complex(realPart, imaginaryPart floatT) complexT -real(complexT) floatT -imag(complexT) floatT -</pre> - -<p> -The type of the arguments and return value correspond. -For <code>complex</code>, the two arguments must be of the same -floating-point type and the return type is the complex type -with the corresponding floating-point constituents: -<code>complex64</code> for <code>float32</code>, -<code>complex128</code> for <code>float64</code>. -The <code>real</code> and <code>imag</code> functions -together form the inverse, so for a complex value <code>z</code>, -<code>z</code> <code>==</code> <code>complex(real(z),</code> <code>imag(z))</code>. -</p> - -<p> -If the operands of these functions are all constants, the return -value is a constant. -</p> - -<pre> -var a = complex(2, -2) // complex128 -var b = complex(1.0, -1.4) // complex128 -x := float32(math.Cos(math.Pi/2)) // float32 -var c64 = complex(5, -x) // complex64 -var im = imag(b) // float64 -var rl = real(c64) // float32 -</pre> - -<h3 id="Handling_panics">Handling panics</h3> - -<p> Two built-in functions, <code>panic</code> and <code>recover</code>, -assist in reporting and handling <a href="#Run_time_panics">run-time panics</a> -and program-defined error conditions. -</p> - -<pre class="grammar"> -func panic(interface{}) -func recover() interface{} -</pre> - -<p> -When a function <code>F</code> calls <code>panic</code>, normal -execution of <code>F</code> stops immediately. Any functions whose -execution was <a href="#Defer_statements">deferred</a> by the -invocation of <code>F</code> are run in the usual way, and then -<code>F</code> returns to its caller. To the caller, <code>F</code> -then behaves like a call to <code>panic</code>, terminating its own -execution and running deferred functions. This continues until all -functions in the goroutine have ceased execution, in reverse order. -At that point, the program is -terminated and the error condition is reported, including the value of -the argument to <code>panic</code>. This termination sequence is -called <i>panicking</i>. -</p> - -<pre> -panic(42) -panic("unreachable") -panic(Error("cannot parse")) -</pre> - -<p> -The <code>recover</code> function allows a program to manage behavior -of a panicking goroutine. Executing a <code>recover</code> call -<i>inside</i> a deferred function (but not any function called by it) stops -the panicking sequence by restoring normal execution, and retrieves -the error value passed to the call of <code>panic</code>. If -<code>recover</code> is called outside the deferred function it will -not stop a panicking sequence. In this case, or when the goroutine -is not panicking, or if the argument supplied to <code>panic</code> -was <code>nil</code>, <code>recover</code> returns <code>nil</code>. -</p> - -<p> -The <code>protect</code> function in the example below invokes -the function argument <code>g</code> and protects callers from -run-time panics raised by <code>g</code>. -</p> - -<pre> -func protect(g func()) { - defer func() { - log.Println("done") // Println executes normally even in there is a panic - if x := recover(); x != nil { - log.Printf("run time panic: %v", x) - } - }() - log.Println("start") - g() -} -</pre> - - -<h3 id="Bootstrapping">Bootstrapping</h3> - -<p> -Current implementations provide several built-in functions useful during -bootstrapping. These functions are documented for completeness but are not -guaranteed to stay in the language. They do not return a result. -</p> - -<pre class="grammar"> -Function Behavior - -print prints all arguments; formatting of arguments is implementation-specific -println like print but prints spaces between arguments and a newline at the end -</pre> - - -<h2 id="Packages">Packages</h2> - -<p> -Go programs are constructed by linking together <i>packages</i>. -A package in turn is constructed from one or more source files -that together declare constants, types, variables and functions -belonging to the package and which are accessible in all files -of the same package. Those elements may be -<a href="#Exported_identifiers">exported</a> and used in another package. -</p> - -<h3 id="Source_file_organization">Source file organization</h3> - -<p> -Each source file consists of a package clause defining the package -to which it belongs, followed by a possibly empty set of import -declarations that declare packages whose contents it wishes to use, -followed by a possibly empty set of declarations of functions, -types, variables, and constants. -</p> - -<pre class="ebnf"> -SourceFile = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } . -</pre> - -<h3 id="Package_clause">Package clause</h3> - -<p> -A package clause begins each source file and defines the package -to which the file belongs. -</p> - -<pre class="ebnf"> -PackageClause = "package" PackageName . -PackageName = identifier . -</pre> - -<p> -The PackageName must not be the <a href="#Blank_identifier">blank identifier</a>. -</p> - -<pre> -package math -</pre> - -<p> -A set of files sharing the same PackageName form the implementation of a package. -An implementation may require that all source files for a package inhabit the same directory. -</p> - -<h3 id="Import_declarations">Import declarations</h3> - -<p> -An import declaration states that the source file containing the -declaration uses identifiers -<a href="#Exported_identifiers">exported</a> by the <i>imported</i> -package and enables access to them. The import names an -identifier (PackageName) to be used for access and an ImportPath -that specifies the package to be imported. -</p> - -<pre class="ebnf"> -ImportDecl = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) . -ImportSpec = [ "." | PackageName ] ImportPath . -ImportPath = string_lit . -</pre> - -<p> -The PackageName is used in <a href="#Qualified_identifiers">qualified identifiers</a> -to access the exported identifiers of the package within the importing source file. -It is declared in the <a href="#Blocks">file block</a>. -If the PackageName is omitted, it defaults to the identifier specified in the -<a href="#Package_clause">package clause</a> of the imported package. -If an explicit period (<code>.</code>) appears instead of a name, all the -package's exported identifiers will be declared in the current file's -file block and can be accessed without a qualifier. -</p> - -<p> -The interpretation of the ImportPath is implementation-dependent but -it is typically a substring of the full file name of the compiled -package and may be relative to a repository of installed packages. -</p> - -<p> -Assume we have compiled a package containing the package clause -<code>package math</code>, which exports function <code>Sin</code>, and -installed the compiled package in the file identified by -<code>"lib/math"</code>. -This table illustrates how <code>Sin</code> may be accessed in files -that import the package after the -various types of import declaration. -</p> - -<pre class="grammar"> -Import declaration Local name of Sin - -import "lib/math" math.Sin -import M "lib/math" M.Sin -import . "lib/math" Sin -</pre> - -<p> -An import declaration declares a dependency relation between -the importing and imported package. -It is illegal for a package to import itself or to import a package without -referring to any of its exported identifiers. To import a package solely for -its side-effects (initialization), use the <a href="#Blank_identifier">blank</a> -identifier as explicit package name: -</p> - -<pre> -import _ "lib/math" -</pre> - - -<h3 id="An_example_package">An example package</h3> - -<p> -Here is a complete Go package that implements a concurrent prime sieve. -</p> - -<pre> -package main - -import "fmt" - -// Send the sequence 2, 3, 4, … to channel 'ch'. -func generate(ch chan<- int) { - for i := 2; ; i++ { - ch <- i // Send 'i' to channel 'ch'. - } -} - -// Copy the values from channel 'src' to channel 'dst', -// removing those divisible by 'prime'. -func filter(src <-chan int, dst chan<- int, prime int) { - for i := range src { // Loop over values received from 'src'. - if i%prime != 0 { - dst <- i // Send 'i' to channel 'dst'. - } - } -} - -// The prime sieve: Daisy-chain filter processes together. -func sieve() { - ch := make(chan int) // Create a new channel. - go generate(ch) // Start generate() as a subprocess. - for { - prime := <-ch - fmt.Print(prime, "\n") - ch1 := make(chan int) - go filter(ch, ch1, prime) - ch = ch1 - } -} - -func main() { - sieve() -} -</pre> - -<h2 id="Program_initialization_and_execution">Program initialization and execution</h2> - -<h3 id="The_zero_value">The zero value</h3> -<p> -When memory is allocated to store a value, either through a declaration -or a call of <code>make</code> or <code>new</code>, -and no explicit initialization is provided, the memory is -given a default initialization. Each element of such a value is -set to the <i>zero value</i> for its type: <code>false</code> for booleans, -<code>0</code> for integers, <code>0.0</code> for floats, <code>""</code> -for strings, and <code>nil</code> for pointers, functions, interfaces, slices, channels, and maps. -This initialization is done recursively, so for instance each element of an -array of structs will have its fields zeroed if no value is specified. -</p> -<p> -These two simple declarations are equivalent: -</p> - -<pre> -var i int -var i int = 0 -</pre> - -<p> -After -</p> - -<pre> -type T struct { i int; f float64; next *T } -t := new(T) -</pre> - -<p> -the following holds: -</p> - -<pre> -t.i == 0 -t.f == 0.0 -t.next == nil -</pre> - -<p> -The same would also be true after -</p> - -<pre> -var t T -</pre> - -<h3 id="Program_execution">Program execution</h3> -<p> -A package with no imports is initialized by assigning initial values to -all its package-level variables -and then calling any -package-level function with the name and signature of -</p> -<pre> -func init() -</pre> -<p> -defined in its source. -A package may contain multiple -<code>init</code> functions, even -within a single source file; they execute -in unspecified order. -</p> -<p> -Within a package, package-level variables are initialized, -and constant values are determined, in -data-dependent order: if the initializer of <code>A</code> -depends on the value of <code>B</code>, <code>A</code> -will be set after <code>B</code>. -It is an error if such dependencies form a cycle. -Dependency analysis is done lexically: <code>A</code> -depends on <code>B</code> if the value of <code>A</code> -contains a mention of <code>B</code>, contains a value -whose initializer -mentions <code>B</code>, or mentions a function that -mentions <code>B</code>, recursively. -If two items are not interdependent, they will be initialized -in the order they appear in the source. -Since the dependency analysis is done per package, it can produce -unspecified results if <code>A</code>'s initializer calls a function defined -in another package that refers to <code>B</code>. -</p> -<p> -Initialization code may contain "go" statements, but the functions -they invoke do not begin execution until initialization of the entire -program is complete. Therefore, all initialization code is run in a single -goroutine. -</p> -<p> -An <code>init</code> function cannot be referred to from anywhere -in a program. In particular, <code>init</code> cannot be called explicitly, -nor can a pointer to <code>init</code> be assigned to a function variable. -</p> -<p> -If a package has imports, the imported packages are initialized -before initializing the package itself. If multiple packages import -a package <code>P</code>, <code>P</code> will be initialized only once. -</p> -<p> -The importing of packages, by construction, guarantees that there can -be no cyclic dependencies in initialization. -</p> -<p> -A complete program is created by linking a single, unimported package -called the <i>main package</i> with all the packages it imports, transitively. -The main package must -have package name <code>main</code> and -declare a function <code>main</code> that takes no -arguments and returns no value. -</p> - -<pre> -func main() { … } -</pre> - -<p> -Program execution begins by initializing the main package and then -invoking the function <code>main</code>. -</p> -<p> -When the function <code>main</code> returns, the program exits. -It does not wait for other (non-<code>main</code>) goroutines to complete. -</p> - -<h2 id="Run_time_panics">Run-time panics</h2> - -<p> -Execution errors such as attempting to index an array out -of bounds trigger a <i>run-time panic</i> equivalent to a call of -the built-in function <a href="#Handling_panics"><code>panic</code></a> -with a value of the implementation-defined interface type <code>runtime.Error</code>. -That type defines at least the method -<code>String() string</code>. The exact error values that -represent distinct run-time error conditions are unspecified, -at least for now. -</p> - -<pre> -package runtime - -type Error interface { - String() string - // and perhaps others -} -</pre> - -<h2 id="System_considerations">System considerations</h2> - -<h3 id="Package_unsafe">Package <code>unsafe</code></h3> - -<p> -The built-in package <code>unsafe</code>, known to the compiler, -provides facilities for low-level programming including operations -that violate the type system. A package using <code>unsafe</code> -must be vetted manually for type safety. The package provides the -following interface: -</p> - -<pre class="grammar"> -package unsafe - -type ArbitraryType int // shorthand for an arbitrary Go type; it is not a real type -type Pointer *ArbitraryType - -func Alignof(variable ArbitraryType) uintptr -func Offsetof(selector ArbitraryType) uinptr -func Sizeof(variable ArbitraryType) uintptr - -func Reflect(val interface{}) (typ runtime.Type, addr uintptr) -func Typeof(val interface{}) (typ interface{}) -func Unreflect(typ runtime.Type, addr uintptr) interface{} -</pre> - -<p> -Any pointer or value of type <code>uintptr</code> can be converted into -a <code>Pointer</code> and vice versa. -</p> -<p> -The function <code>Sizeof</code> takes an expression denoting a -variable of any type and returns the size of the variable in bytes. -</p> -<p> -The function <code>Offsetof</code> takes a selector (§<a href="#Selectors">Selectors</a>) denoting a struct -field of any type and returns the field offset in bytes relative to the -struct's address. -For a struct <code>s</code> with field <code>f</code>: -</p> - -<pre> -uintptr(unsafe.Pointer(&s)) + unsafe.Offsetof(s.f) == uintptr(unsafe.Pointer(&s.f)) -</pre> - -<p> -Computer architectures may require memory addresses to be <i>aligned</i>; -that is, for addresses of a variable to be a multiple of a factor, -the variable's type's <i>alignment</i>. The function <code>Alignof</code> -takes an expression denoting a variable of any type and returns the -alignment of the (type of the) variable in bytes. For a variable -<code>x</code>: -</p> - -<pre> -uintptr(unsafe.Pointer(&x)) % unsafe.Alignof(x) == 0 -</pre> - -<p> -Calls to <code>Alignof</code>, <code>Offsetof</code>, and -<code>Sizeof</code> are compile-time constant expressions of type <code>uintptr</code>. -</p> -<p> -The functions <code>unsafe.Typeof</code>, -<code>unsafe.Reflect</code>, -and <code>unsafe.Unreflect</code> allow access at run time to the dynamic -types and values stored in interfaces. -<code>Typeof</code> returns a representation of -<code>val</code>'s -dynamic type as a <code>runtime.Type</code>. -<code>Reflect</code> allocates a copy of -<code>val</code>'s dynamic -value and returns both the type and the address of the copy. -<code>Unreflect</code> inverts <code>Reflect</code>, -creating an -interface value from a type and address. -The <a href="/pkg/reflect/"><code>reflect</code> package</a> built on these primitives -provides a safe, more convenient way to inspect interface values. -</p> - - -<h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3> - -<p> -For the numeric types (§<a href="#Numeric_types">Numeric types</a>), the following sizes are guaranteed: -</p> - -<pre class="grammar"> -type size in bytes - -byte, uint8, int8 1 -uint16, int16 2 -uint32, int32, float32 4 -uint64, int64, float64, complex64 8 -complex128 16 -</pre> - -<p> -The following minimal alignment properties are guaranteed: -</p> -<ol> -<li>For a variable <code>x</code> of any type: <code>unsafe.Alignof(x)</code> is at least 1. -</li> - -<li>For a variable <code>x</code> of struct type: <code>unsafe.Alignof(x)</code> is the largest of - all the values <code>unsafe.Alignof(x.f)</code> for each field <code>f</code> of <code>x</code>, but at least 1. -</li> - -<li>For a variable <code>x</code> of array type: <code>unsafe.Alignof(x)</code> is the same as - <code>unsafe.Alignof(x[0])</code>, but at least 1. -</li> -</ol> - -<span class="alert"> -<h2 id="Implementation_differences">Implementation differences - TODO</h2> -<ul> - <li><code>len(a)</code> is only a constant if <code>a</code> is a (qualified) identifier denoting an array or pointer to an array.</li> - <li><code>nil</code> maps are not treated like empty maps.</li> - <li>Trying to send/receive from a <code>nil</code> channel causes a run-time panic.</li> - <li><code>unsafe.Alignof</code>, <code>unsafe.Offsetof</code>, and <code>unsafe.Sizeof</code> return an <code>int</code>.</li> -</ul> -</span> |