diff options
Diffstat (limited to 'doc/go_spec.html')
| -rw-r--r-- | doc/go_spec.html | 899 |
1 files changed, 505 insertions, 394 deletions
diff --git a/doc/go_spec.html b/doc/go_spec.html index 660c8535e..ca0deb56a 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1,6 +1,6 @@ <!--{ "Title": "The Go Programming Language Specification", - "Subtitle": "Version of May 28, 2014", + "Subtitle": "Version of November 11, 2014", "Path": "/ref/spec" }--> @@ -479,7 +479,7 @@ Interpreted string literals are character sequences between double quotes <code>""</code>. The text between the quotes, which may not contain newlines, forms the value of the literal, with backslash escapes interpreted as they -are in rune literals (except that <code>\'</code> is illegal and +are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and <code>\"</code> is legal), with the same restrictions. The three-digit octal (<code>\</code><i>nnn</i>) and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual @@ -577,7 +577,7 @@ Numeric constants represent values of arbitrary precision and do not overflow. </p> <p> -Constants may be <a href="#Types">typed</a> or untyped. +Constants may be <a href="#Types">typed</a> or <i>untyped</i>. Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>, and certain <a href="#Constant_expressions">constant expressions</a> containing only untyped constant operands are untyped. @@ -598,6 +598,17 @@ not <code>int32</code> or <code>string</code>. </p> <p> +An untyped constant has a <i>default type</i> which is the type to which the +constant is implicitly converted in contexts where a typed value is required, +for instance, in a <a href="#Short_variable_declarations">short variable declaration</a> +such as <code>i := 0</code> where there is no explicit type. +The default type of an untyped constant is <code>bool</code>, <code>rune</code>, +<code>int</code>, <code>float64</code>, <code>complex128</code> or <code>string</code> +respectively, depending on whether it is a boolean, rune, integer, floating-point, +complex, or string constant. +</p> + +<p> 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>, @@ -636,6 +647,65 @@ of evaluating <a href="#Constant_expressions">constant expressions</a>. </p> +<h2 id="Variables">Variables</h2> + +<p> +A variable is a storage location for holding a <i>value</i>. +The set of permissible values is determined by the +variable's <i><a href="#Types">type</a></i>. +</p> + +<p> +A <a href="#Variable_declarations">variable declaration</a> +or, for function parameters and results, the signature +of a <a href="#Function_declarations">function declaration</a> +or <a href="#Function_literals">function literal</a> reserves +storage for a named variable. + +Calling the built-in function <a href="#Allocation"><code>new</code></a> +or taking the address of a <a href="#Composite_literals">composite literal</a> +allocates storage for a variable at run time. +Such an anonymous variable is referred to via a (possibly implicit) +<a href="#Address_operators">pointer indirection</a>. +</p> + +<p> +<i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>, +and <a href="#Struct_types">struct</a> types have elements and fields that may +be <a href="#Address_operators">addressed</a> individually. Each such element +acts like a variable. +</p> + +<p> +The <i>static type</i> (or just <i>type</i>) of a variable is the +type given in its declaration, the type provided in the +<code>new</code> call or composite literal, or the type of +an element of a structured variable. +Variables of interface type also have a distinct <i>dynamic type</i>, +which is the concrete type of the value assigned to the variable at run time +(unless the value is the predeclared identifier <code>nil</code>, +which has no type). +The dynamic type may vary during execution but values stored in interface +variables are always <a href="#Assignability">assignable</a> +to the static type of the variable. +</p> + +<pre> +var x interface{} // x is nil and has static type interface{} +var v *T // v has value nil, static type *T +x = 42 // x has value 42 and dynamic type int +x = v // x has value (*T)(nil) and dynamic type *T +</pre> + +<p> +A variable's value is retrieved by referring to the variable in an +<a href="#Expressions">expression</a>; it is the most recent value +<a href="#Assignments">assigned</a> to the variable. +If a variable has not yet been assigned a value, its value is the +<a href="#The_zero_value">zero value</a> for its type. +</p> + + <h2 id="Types">Types</h2> <p> @@ -662,17 +732,6 @@ 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 one of the predeclared boolean, numeric, or string types, or a type literal, the corresponding underlying @@ -1027,14 +1086,14 @@ struct { <h3 id="Pointer_types">Pointer types</h3> <p> -A pointer type denotes the set of all pointers to variables of a given +A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given type, called the <i>base type</i> of the pointer. The value of an uninitialized pointer is <code>nil</code>. </p> <pre class="ebnf"> PointerType = "*" BaseType . -BaseType = Type . +BaseType = Type . </pre> <pre> @@ -1154,11 +1213,11 @@ interface{} <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>: +to define an interface called <code>Locker</code>: </p> <pre> -type Lock interface { +type Locker interface { Lock() Unlock() } @@ -1174,28 +1233,35 @@ func (p T) Unlock() { … } </pre> <p> -they implement the <code>Lock</code> interface as well +they implement the <code>Locker</code> interface as well as the <code>File</code> interface. </p> + <p> -An interface may use an interface type name <code>T</code> -in place of a method specification. -The effect, called embedding an interface, -is equivalent to enumerating the methods of <code>T</code> explicitly -in the interface. +An interface <code>T</code> may use a (possibly qualified) interface type +name <code>E</code> in place of a method specification. This is called +<i>embedding</i> interface <code>E</code> in <code>T</code>; it adds +all (exported and non-exported) methods of <code>E</code> to the interface +<code>T</code>. </p> <pre> -type ReadWrite interface { +type ReadWriter 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 + ReadWriter // same as adding the methods of ReadWriter + Locker // same as adding the methods of Locker Close() } + +type LockedFile interface { + Locker + File // illegal: Lock, Unlock not unique + Lock() // illegal: Lock not unique +} </pre> <p> @@ -1443,7 +1509,7 @@ is different from <code>[]string</code>. <h3 id="Assignability">Assignability</h3> <p> -A value <code>x</code> is <i>assignable</i> to a variable of type <code>T</code> +A value <code>x</code> is <i>assignable</i> to a <a href="#Variables">variable</a> of type <code>T</code> ("<code>x</code> is assignable to <code>T</code>") in any of these cases: </p> @@ -1875,9 +1941,10 @@ func (tz TimeZone) String() string { <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. +A variable declaration creates one or more variables, binds corresponding +identifiers to them, and gives each a type and an initial value. </p> + <pre class="ebnf"> VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) . VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) . @@ -1898,22 +1965,27 @@ var _, found = entries[name] // map lookup; only interested in "found" <p> If a list of expressions is given, the variables are initialized -by <a href="#Assignments">assigning</a> the expressions to the variables -in order; all expressions must be consumed and all variables initialized from them. +with the expressions following the rules for <a href="#Assignments">assignments</a>. Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>. </p> <p> -If the type is present, each variable is given that type. -Otherwise, the types are deduced from the assignment -of the expression list. +If a type is present, each variable is given that type. +Otherwise, each variable is given the type of the corresponding +initialization value in the assignment. +If that value is an untyped constant, it is first +<a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>; +if it is an untyped boolean value, it is first converted to type <code>bool</code>. +The predeclared value <code>nil</code> cannot be used to initialize a variable +with no explicit type. </p> -<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 as described in §<a href="#Assignments">Assignments</a>. -</p> +<pre> +var d = math.Sin(0.5) // d is int64 +var i = 42 // i is int +var t, ok = x.(T) // t is T, ok is bool +var n = nil // illegal +</pre> <p> Implementation restriction: A compiler may make it illegal to declare a variable @@ -2029,13 +2101,14 @@ and associates the method with the receiver's <i>base type</i>. <pre class="ebnf"> MethodDecl = "func" Receiver MethodName ( Function | Signature ) . -Receiver = "(" [ identifier ] [ "*" ] BaseTypeName ")" . -BaseTypeName = identifier . +Receiver = Parameters . </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. The type denoted by <code>T</code> is called +The receiver is specified via an extra parameter section preceeding the method +name. That parameter section must declare a single parameter, the receiver. +Its type must be of the form <code>T</code> or <code>*T</code> (possibly using +parentheses) where <code>T</code> is a type name. The type denoted by <code>T</code> is called the receiver <i>base type</i>; it must not be a pointer or interface type and it must be declared in the same package as the method. The method is said to be <i>bound</i> to the base type and the method name @@ -2117,9 +2190,9 @@ operand only on the left-hand side of an <a href="#Assignments">assignment</a>. </p> <pre class="ebnf"> -Operand = Literal | OperandName | MethodExpr | "(" Expression ")" . -Literal = BasicLit | CompositeLit | FunctionLit . -BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit . +Operand = Literal | OperandName | MethodExpr | "(" Expression ")" . +Literal = BasicLit | CompositeLit | FunctionLit . +BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit . OperandName = identifier | QualifiedIdent. </pre> @@ -2241,7 +2314,8 @@ For array and slice literals the following rules apply: <p> <a href="#Address_operators">Taking the address</a> of a composite literal -generates a pointer to a unique instance of the literal's value. +generates a pointer to a unique <a href="#Variables">variable</a> initialized +with the literal's value. </p> <pre> var pointer *Point3D = &Point3D{y: 1000} @@ -2375,12 +2449,11 @@ Primary expressions are the operands for unary and binary expressions. PrimaryExpr = Operand | Conversion | - BuiltinCall | PrimaryExpr Selector | PrimaryExpr Index | PrimaryExpr Slice | PrimaryExpr TypeAssertion | - PrimaryExpr Call . + PrimaryExpr Arguments . Selector = "." identifier . Index = "[" Expression "]" . @@ -2388,8 +2461,7 @@ Slice = "[" ( [ Expression ] ":" [ Expression ] ) | ( [ Expression ] ":" Expression ":" Expression ) "]" . TypeAssertion = "." "(" Type ")" . -Call = "(" [ ArgumentList [ "," ] ] ")" . -ArgumentList = ExpressionList [ "..." ] . +Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" . </pre> @@ -2449,30 +2521,40 @@ The following rules apply to selectors: <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, +where <code>T</code> is not a pointer or interface type, <code>x.f</code> denotes the field or method at the shallowest depth in <code>T</code> where there is such an <code>f</code>. If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a> with shallowest depth, the selector expression is illegal. </li> + <li> -For a variable <code>x</code> of type <code>I</code> where <code>I</code> +For a value <code>x</code> of type <code>I</code> where <code>I</code> is an interface type, <code>x.f</code> denotes the actual method with name -<code>f</code> of the value assigned to <code>x</code>. +<code>f</code> of the dynamic value of <code>x</code>. If there is no method with name <code>f</code> in the <a href="#Method_sets">method set</a> of <code>I</code>, the selector expression is illegal. </li> + +<li> +As an exception, if the type of <code>x</code> is a named pointer type +and <code>(*x).f</code> is a valid selector expression denoting a field +(but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>. +</li> + <li> In all other cases, <code>x.f</code> is illegal. </li> + <li> If <code>x</code> is of pointer type and has the value <code>nil</code> and <code>x.f</code> denotes a struct field, assigning to or evaluating <code>x.f</code> causes a <a href="#Run_time_panics">run-time panic</a>. </li> + <li> If <code>x</code> is of interface type and has the value <code>nil</code>, <a href="#Calls">calling</a> or @@ -2482,18 +2564,6 @@ causes a <a href="#Run_time_panics">run-time panic</a>. </ol> <p> -Selectors automatically <a href="#Address_operators">dereference</a> -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 shorthand for <code>(*x.A).f</code>. -</p> - -<p> For example, given the declarations: </p> @@ -2502,13 +2572,13 @@ type T0 struct { x int } -func (recv *T0) M0() +func (*T0) M0() type T1 struct { y int } -func (recv T1) M1() +func (T1) M1() type T2 struct { z int @@ -2516,9 +2586,13 @@ type T2 struct { *T0 } -func (recv *T2) M2() +func (*T2) M2() + +type Q *T2 -var p *T2 // with p != nil and p.T0 != nil +var t T2 // with t.T0 != nil +var p *T2 // with p != nil and (*p).T0 != nil +var q Q = p </pre> <p> @@ -2526,13 +2600,254 @@ one may write: </p> <pre> -p.z // (*p).z -p.y // ((*p).T1).y -p.x // (*(*p).T0).x +t.z // t.z +t.y // t.T1.y +t.x // (*t.TO).x + +p.z // (*p).z +p.y // (*p).T1.y +p.x // (*(*p).T0).x + +q.x // (*(*q).T0).x (*q).x is a valid field selector + +p.M2() // p.M2() M2 expects *T2 receiver +p.M1() // ((*p).T1).M1() M1 expects T1 receiver +p.M0() // ((&(*p).T0)).M0() M0 expects *T0 receiver, see section on Calls +</pre> + +<p> +but the following is invalid: +</p> + +<pre> +q.M0() // (*q).M0 is valid but not a field selector +</pre> + + +<h3 id="Method_expressions">Method expressions</h3> + +<p> +If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, +<code>T.M</code> is a function that is callable as a regular function +with the same arguments as <code>M</code> prefixed by an additional +argument that is the receiver of the method. +</p> + +<pre class="ebnf"> +MethodExpr = ReceiverType "." MethodName . +ReceiverType = TypeName | "(" "*" TypeName ")" | "(" ReceiverType ")" . +</pre> + +<p> +Consider a struct type <code>T</code> with two methods, +<code>Mv</code>, whose receiver is of type <code>T</code>, and +<code>Mp</code>, whose receiver is of type <code>*T</code>. +</p> + +<pre> +type T struct { + a int +} +func (tv T) Mv(a int) int { return 0 } // value receiver +func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver + +var t T +</pre> + +<p> +The expression +</p> + +<pre> +T.Mv +</pre> + +<p> +yields a function equivalent to <code>Mv</code> but +with an explicit receiver as its first argument; it has signature +</p> + +<pre> +func(tv T, a int) int +</pre> + +<p> +That function may be called normally with an explicit receiver, so +these five invocations are equivalent: +</p> + +<pre> +t.Mv(7) +T.Mv(t, 7) +(T).Mv(t, 7) +f1 := T.Mv; f1(t, 7) +f2 := (T).Mv; f2(t, 7) +</pre> + +<p> +Similarly, the expression +</p> + +<pre> +(*T).Mp +</pre> + +<p> +yields a function value representing <code>Mp</code> with signature +</p> + +<pre> +func(tp *T, f float32) float32 +</pre> + +<p> +For a method with a value receiver, one can derive a function +with an explicit pointer receiver, so +</p> + +<pre> +(*T).Mv +</pre> + +<p> +yields a function value representing <code>Mv</code> with signature +</p> + +<pre> +func(tv *T, a int) int +</pre> + +<p> +Such a function indirects through the receiver to create a value +to pass as the receiver to the underlying method; +the method does not overwrite the value whose address is passed in +the function call. +</p> + +<p> +The final case, a value-receiver function for a pointer-receiver method, +is illegal because pointer-receiver methods are not in the method set +of the value type. +</p> + +<p> +Function values derived from methods are called with function call syntax; +the receiver is provided as the first argument to the call. +That is, given <code>f := T.Mv</code>, <code>f</code> is invoked +as <code>f(t, 7)</code> not <code>t.f(7)</code>. +To construct a function that binds the receiver, use a +<a href="#Function_literals">function literal</a> or +<a href="#Method_values">method value</a>. +</p> + +<p> +It is legal to derive a function value from a method of an interface type. +The resulting function takes an explicit receiver of that interface type. +</p> + +<h3 id="Method_values">Method values</h3> + +<p> +If the expression <code>x</code> has static type <code>T</code> and +<code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, +<code>x.M</code> is called a <i>method value</i>. +The method value <code>x.M</code> is a function value that is callable +with the same arguments as a method call of <code>x.M</code>. +The expression <code>x</code> is evaluated and saved during the evaluation of the +method value; the saved copy is then used as the receiver in any calls, +which may be executed later. +</p> + +<p> +The type <code>T</code> may be an interface or non-interface type. +</p> + +<p> +As in the discussion of <a href="#Method_expressions">method expressions</a> above, +consider a struct type <code>T</code> with two methods, +<code>Mv</code>, whose receiver is of type <code>T</code>, and +<code>Mp</code>, whose receiver is of type <code>*T</code>. +</p> + +<pre> +type T struct { + a int +} +func (tv T) Mv(a int) int { return 0 } // value receiver +func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver + +var t T +var pt *T +func makeT() T +</pre> + +<p> +The expression +</p> + +<pre> +t.Mv +</pre> + +<p> +yields a function value of type +</p> + +<pre> +func(int) int +</pre> + +<p> +These two invocations are equivalent: +</p> + +<pre> +t.Mv(7) +f := t.Mv; f(7) +</pre> + +<p> +Similarly, the expression +</p> + +<pre> +pt.Mp +</pre> + +<p> +yields a function value of type +</p> + +<pre> +func(float32) float32 +</pre> + +<p> +As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver +using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>. +</p> + +<p> +As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver +using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>. +</p> + +<pre> +f := t.Mv; f(7) // like t.Mv(7) +f := pt.Mp; f(7) // like pt.Mp(7) +f := pt.Mv; f(7) // like (*pt).Mv(7) +f := t.Mp; f(7) // like (&t).Mp(7) +f := makeT().Mp // invalid: result of makeT() is not addressable +</pre> + +<p> +Although the examples above use non-interface types, it is also legal to create a method value +from a value of interface type. +</p> -p.M2() // (*p).M2() -p.M1() // ((*p).T1).M1() -p.M0() // ((*p).T0).M0() +<pre> +var i interface { M(int) } = myVal +f := i.M; f(7) // like i.M(7) </pre> @@ -2625,7 +2940,7 @@ Otherwise <code>a[x]</code> is illegal. <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 +used in an <a href="#Assignments">assignment</a> or initialization of the special form </p> <pre> @@ -2635,11 +2950,9 @@ 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 +yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code> if the key <code>x</code> is present in the map, and -<code>false</code> otherwise. The value of <code>v</code> is the value -<code>a[x]</code> as in the single-result form. +<code>false</code> otherwise. </p> <p> @@ -2824,7 +3137,7 @@ r := y.(io.Reader) // r has type io.Reader and y must implement both I and i </pre> <p> -If a type assertion is used in an <a href="#Assignments">assignment</a> or initialization of the form +A type assertion used in an <a href="#Assignments">assignment</a> or initialization of the special form </p> <pre> @@ -2834,13 +3147,10 @@ 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>. +yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code> +if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is +the <a href="#The_zero_value">zero value</a> for type <code>T</code>. No run-time panic occurs in this case. -The type assertion in this construct thus acts like a function call -returning a value and a boolean indicating success. </p> @@ -2870,7 +3180,7 @@ the method. <pre> math.Atan2(x, y) // function call var pt *Point -pt.Scale(3.5) // method call with receiver pt +pt.Scale(3.5) // method call with receiver pt </pre> <p> @@ -3375,13 +3685,13 @@ or an array indexing operation of an addressable array. As an exception to the addressability requirement, <code>x</code> may also be a (possibly parenthesized) <a href="#Composite_literals">composite literal</a>. -If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>, +If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>, then the evaluation of <code>&x</code> does too. </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 +indirection <code>*x</code> denotes the <a href="#Variables">variable</a> of type <code>T</code> pointed to by <code>x</code>. If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code> will cause a <a href="#Run_time_panics">run-time panic</a>. @@ -3422,7 +3732,7 @@ f(<-ch) </pre> <p> -A receive expression used in an assignment or initialization of the form +A receive expression used in an <a href="#Assignments">assignment</a> or initialization of the special form </p> <pre> @@ -3432,7 +3742,7 @@ var x, ok = <-ch </pre> <p> -yields an additional result of type <code>bool</code> reporting whether the +yields an additional untyped boolean result reporting whether the communication succeeded. The value of <code>ok</code> is <code>true</code> if the value received was delivered by a successful send operation to the channel, or <code>false</code> if it is a zero value generated because the @@ -3440,232 +3750,6 @@ channel is closed and empty. </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 ")" | "(" ReceiverType ")" . -</pre> - -<p> -Consider a struct type <code>T</code> with two methods, -<code>Mv</code>, whose receiver is of type <code>T</code>, and -<code>Mp</code>, whose receiver is of type <code>*T</code>. -</p> - -<pre> -type T struct { - a int -} -func (tv T) Mv(a int) int { return 0 } // value receiver -func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver - -var t T -</pre> - -<p> -The expression -</p> - -<pre> -T.Mv -</pre> - -<p> -yields a function equivalent to <code>Mv</code> but -with an explicit receiver as its first argument; it has signature -</p> - -<pre> -func(tv T, a int) int -</pre> - -<p> -That function may be called normally with an explicit receiver, so -these five invocations are equivalent: -</p> - -<pre> -t.Mv(7) -T.Mv(t, 7) -(T).Mv(t, 7) -f1 := T.Mv; f1(t, 7) -f2 := (T).Mv; f2(t, 7) -</pre> - -<p> -Similarly, the expression -</p> - -<pre> -(*T).Mp -</pre> - -<p> -yields a function value representing <code>Mp</code> with signature -</p> - -<pre> -func(tp *T, f float32) float32 -</pre> - -<p> -For a method with a value receiver, one can derive a function -with an explicit pointer receiver, so -</p> - -<pre> -(*T).Mv -</pre> - -<p> -yields a function value representing <code>Mv</code> with signature -</p> - -<pre> -func(tv *T, a int) int -</pre> - -<p> -Such a function indirects through the receiver to create a value -to pass as the receiver to the underlying method; -the method does not overwrite the value whose address is passed in -the function call. -</p> - -<p> -The final case, a value-receiver function for a pointer-receiver method, -is illegal because pointer-receiver methods are not in the method set -of the value type. -</p> - -<p> -Function values derived from methods are called with function call syntax; -the receiver is provided as the first argument to the call. -That is, given <code>f := T.Mv</code>, <code>f</code> is invoked -as <code>f(t, 7)</code> not <code>t.f(7)</code>. -To construct a function that binds the receiver, use a -<a href="#Function_literals">function literal</a> or -<a href="#Method_values">method value</a>. -</p> - -<p> -It is legal to derive a function value from a method of an interface type. -The resulting function takes an explicit receiver of that interface type. -</p> - -<h3 id="Method_values">Method values</h3> - -<p> -If the expression <code>x</code> has static type <code>T</code> and -<code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, -<code>x.M</code> is called a <i>method value</i>. -The method value <code>x.M</code> is a function value that is callable -with the same arguments as a method call of <code>x.M</code>. -The expression <code>x</code> is evaluated and saved during the evaluation of the -method value; the saved copy is then used as the receiver in any calls, -which may be executed later. -</p> - -<p> -The type <code>T</code> may be an interface or non-interface type. -</p> - -<p> -As in the discussion of <a href="#Method_expressions">method expressions</a> above, -consider a struct type <code>T</code> with two methods, -<code>Mv</code>, whose receiver is of type <code>T</code>, and -<code>Mp</code>, whose receiver is of type <code>*T</code>. -</p> - -<pre> -type T struct { - a int -} -func (tv T) Mv(a int) int { return 0 } // value receiver -func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver - -var t T -var pt *T -func makeT() T -</pre> - -<p> -The expression -</p> - -<pre> -t.Mv -</pre> - -<p> -yields a function value of type -</p> - -<pre> -func(int) int -</pre> - -<p> -These two invocations are equivalent: -</p> - -<pre> -t.Mv(7) -f := t.Mv; f(7) -</pre> - -<p> -Similarly, the expression -</p> - -<pre> -pt.Mp -</pre> - -<p> -yields a function value of type -</p> - -<pre> -func(float32) float32 -</pre> - -<p> -As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver -using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>. -</p> - -<p> -As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver -using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>. -</p> - -<pre> -f := t.Mv; f(7) // like t.Mv(7) -f := pt.Mp; f(7) // like pt.Mp(7) -f := pt.Mv; f(7) // like (*pt).Mv(7) -f := t.Mp; f(7) // like (&t).Mp(7) -f := makeT().Mp // invalid: result of makeT() is not addressable -</pre> - -<p> -Although the examples above use non-interface types, it is also legal to create a method value -from a value of interface type. -</p> - -<pre> -var i interface { M(int) } = myVal -f := i.M; f(7) // like i.M(7) -</pre> - <h3 id="Conversions">Conversions</h3> <p> @@ -4055,7 +4139,7 @@ n := map[int]int{a: f()} // n may be {2: 3} or {3: 3}: evaluation order bet <p> At package level, initialization dependencies override the left-to-right rule for individual initialization expressions, but not for operands within each -expression: +expression: </p> <pre> @@ -4314,7 +4398,7 @@ a[i] = 23 <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 equivalent +<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. @@ -4332,8 +4416,8 @@ i &^= 1<<n 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>. +such as a function call, a <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, @@ -4407,23 +4491,21 @@ to the type of the operand to which it is assigned, with the following special c </p> <ol> -<li><p> - If an untyped <a href="#Constants">constant</a> +<li> + Any typed value may be assigned to the blank identifier. +</li> + +<li> + If an untyped constant is assigned to a variable of interface type or the blank identifier, - the constant is first <a href="#Conversions">converted</a> to type - <code>bool</code>, <code>rune</code>, <code>int</code>, <code>float64</code>, - <code>complex128</code> or <code>string</code> respectively, depending on - whether the value is a boolean, rune, integer, floating-point, complex, or - string constant. -</p></li> - -<li><p> - <!-- Note that the result of a comparison is an untyped bool that may not be constant. --> - If a left-hand side is the blank identifier, any typed or non-constant - value except for the predeclared identifier - <a href="#Predeclared_identifiers"><code>nil</code></a> - may be assigned to it. -</p></li> + the constant is first <a href="#Conversions">converted</a> to its + <a href="#Constants">default type</a>. +</li> + +<li> + If an untyped boolean value is assigned to a variable of interface type or + the blank identifier, it is first converted to type <code>bool</code>. +</li> </ol> <h3 id="If_statements">If statements</h3> @@ -4678,6 +4760,7 @@ 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. +Variables declared by the init statement are re-used in each iteration. </p> <pre class="ebnf"> @@ -4713,41 +4796,42 @@ for { S() } is the same as for true { S() } 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. +to corresponding <i>iteration variables</i> if present and then executes the block. </p> <pre class="ebnf"> -RangeClause = ( ExpressionList "=" | IdentifierList ":=" ) "range" Expression . +RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "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 permitting <a href="#Receive_operator">receive operations</a>. -As with an assignment, the operands on the left must be +As with an assignment, if present 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. In the latter case, -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. +denote the iteration variables. If the range expression is a channel, at most +one iteration variable is permitted, otherwise there may be up to two. +If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>, +the range clause is equivalent to the same clause without that identifier. </p> <p> The range expression is evaluated once before beginning the loop, -with one exception. If the range expression is an array or a pointer to an array -and only the first iteration value is present, only the range expression's -length is evaluated; if that length is constant -<a href="#Length_and_capacity">by definition</a>, +with one exception: if the range expression is an array or a pointer to an array +and at most one iteration variable is present, only the range expression's +length is evaluated; if that length is constant, +<a href="#Length_and_capacity">by definition</a> the range expression itself will not be evaluated. </p> <p> Function calls on the left are evaluated once per iteration. -For each iteration, iteration values are produced as follows: +For each iteration, iteration values are produced as follows +if the respective iteration variables are present: </p> <pre class="grammar"> -Range expression 1st value 2nd value (if 2nd variable is present) +Range expression 1st value 2nd value 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 rune @@ -4759,7 +4843,7 @@ channel c chan E, <-chan E element e E <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. -If only the first iteration variable is present, the range loop produces +If at most one iteration variable is present, the range loop produces iteration values from 0 up to <code>len(a)-1</code> and does not index into the array or slice itself. For a <code>nil</code> slice, the number of iterations is 0. </li> @@ -4803,7 +4887,7 @@ The iteration variables may be declared by the "range" clause using a form of <a href="#Short_variable_declarations">short variable declaration</a> (<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" +and their <a href="#Declarations_and_scope">scope</a> is the block 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. @@ -4840,6 +4924,9 @@ var ch chan Work = producer() for w := range ch { doWork(w) } + +// empty a channel +for range ch {} </pre> @@ -5242,13 +5329,16 @@ Calls of built-in functions are restricted as for </p> <p> -Each time the "defer" statement +Each time a "defer" statement executes, the function value and parameters to the call are <a href="#Calls">evaluated as usual</a> -and saved anew but the actual function body is not executed. -Instead, deferred functions are executed immediately before +and saved anew but the actual function is not invoked. +Instead, deferred functions are invoked immediately before the surrounding function returns, in the reverse order they were deferred. +If a deferred function value evaluates +to <code>nil</code>, execution <a href="#Handling_panics">panics</a> +when the function is invoked, not when the "defer" statement is executed. </p> <p> @@ -5295,11 +5385,6 @@ 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 [ "," ArgumentList ] | ArgumentList . -</pre> - <h3 id="Close">Close</h3> <p> @@ -5378,9 +5463,11 @@ var z complex128 <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 +The built-in function <code>new</code> takes a type <code>T</code>, +allocates storage for a <a href="#Variables">variable</a> of that type +at run time, and returns a value of type <code>*T</code> +<a href="#Pointer_types">pointing</a> to it. +The variable is initialized as described in the section on <a href="#The_zero_value">initial values</a>. </p> @@ -5398,10 +5485,10 @@ new(S) </pre> <p> -dynamically allocates memory for a variable of type <code>S</code>, +allocates storage 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. +of the location. </p> <h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3> @@ -5868,10 +5955,12 @@ func main() { <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 +When storage is allocated for a <a href="#Variables">variable</a>, +either through a declaration or a call of <code>new</code>, or when +a new value is created, either through a composite literal or a call +of <code>make</code>, +and no explicit initialization is provided, the variable or value is +given a default value. Each element of such a variable or 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. @@ -5915,20 +6004,42 @@ var t T </pre> <h3 id="Package_initialization">Package initialization</h3> + <p> -Within a package, package-level variables are initialized according -to their <i>dependencies</i>: if a variable <code>x</code> depends on -a variable <code>y</code>, <code>x</code> will be initialized after -<code>y</code>. +Within a package, package-level variables are initialized in +<i>declaration order</i> but after any of the variables +they <i>depend</i> on. +</p> + +<p> +More precisely, a package-level variable is considered <i>ready for +initialization</i> if it is not yet initialized and either has +no <a href="#Variable_declarations">initialization expression</a> or +its initialization expression has no dependencies on uninitialized variables. +Initialization proceeds by repeatedly initializing the next package-level +variable that is earliest in declaration order and ready for initialization, +until there are no variables ready for initialization. +</p> + +<p> +If any variables are still uninitialized when this +process ends, those variables are part of one or more initialization cycles, +and the program is not valid. +</p> + +<p> +The declaration order of variables declared in multiple files is determined +by the order in which the files are presented to the compiler: Variables +declared in the first file are declared before any of the variables declared +in the second file, and so on. </p> <p> Dependency analysis does not rely on the actual values of the variables, only on lexical <i>references</i> to them in the source, -analyzed transitively. For instance, a variable <code>x</code>'s -<a href="#Variable_declarations">initialization expression</a> -may refer to a function whose body refers to variable <code>y</code>; -if so, <code>x</code> depends on <code>y</code>. +analyzed transitively. For instance, if a variable <code>x</code>'s +initialization expression refers to a function whose body refers to +variable <code>y</code> then <code>x</code> depends on <code>y</code>. Specifically: </p> @@ -5941,7 +6052,7 @@ variable or function. <li> A reference to a method <code>m</code> is a <a href="#Method_values">method value</a> or -<a href="#Method_expressions">method expression</a> of the form +<a href="#Method_expressions">method expression</a> of the form <code>t.m</code>, where the (static) type of <code>t</code> is not an interface type, and the method <code>m</code> is in the <a href="#Method_sets">method set</a> of <code>t</code>. @@ -5950,7 +6061,7 @@ It is immaterial whether the resulting function value </li> <li> -A variable, function, or method <code>x</code> depends on a variable +A variable, function, or method <code>x</code> depends on a variable <code>y</code> if <code>x</code>'s initialization expression or body (for functions and methods) contains a reference to <code>y</code> or to a function or method that depends on <code>y</code>. @@ -5961,11 +6072,6 @@ or to a function or method that depends on <code>y</code>. Dependency analysis is performed per package; only references referring to variables, functions, and methods declared in the current package are considered. -It is an error if variable dependencies form a cycle -(but dependency cycles containing no variables are permitted). -If two variables are independent of each other, -they are initialized in the order they are declared -in the source, possibly in multiple files, as presented to the compiler. </p> <p> @@ -5988,8 +6094,6 @@ func f() int { <p> the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>. -Since <code>b</code> and <code>c</code> are independent of each other, they are -initialized in declaration order (<code>b</code> before <code>c</code>). </p> <p> @@ -6002,7 +6106,7 @@ func init() { … } </pre> <p> -Multiple such functions may be defined, even within a single +Multiple such functions may be defined, even within a single source file. The <code>init</code> identifier is not <a href="#Declarations_and_scope">declared</a> and thus <code>init</code> functions cannot be referred to from anywhere @@ -6032,6 +6136,12 @@ the <code>init</code> functions: it will not invoke the next one until the previous one has returned. </p> +<p> +To ensure reproducible initialization behavior, build systems are encouraged +to present multiple files belonging to the same package in lexical file name +order to a compiler. +</p> + <h3 id="Program_execution">Program execution</h3> <p> @@ -6106,8 +6216,8 @@ type Error interface { 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: +must be vetted manually for type safety and may not be portable. +The package provides the following interface: </p> <pre class="grammar"> @@ -6122,10 +6232,11 @@ func Sizeof(variable ArbitraryType) uintptr </pre> <p> -Any pointer or value of <a href="#Types">underlying type</a> <code>uintptr</code> can be converted to -a <code>Pointer</code> type and vice versa. A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code> value may not be <a href="#Address_operators">dereferenced</a>. +Any pointer or value of <a href="#Types">underlying type</a> <code>uintptr</code> can be converted to +a <code>Pointer</code> type and vice versa. +The effect of converting between <code>Pointer</code> and <code>uintptr</code> is implementation-defined. </p> <pre> |