code review 11884043: spec: clarify index and selector expressions

doc/go_spec.html

 <!--{
         "Title": "The Go Programming Language Specification",
-        "Subtitle": "Version of July 25, 2013",
+        "Subtitle": "Version of July 31, 2013",
         "Path": "/ref/spec"
 }-->
 
 <!--
 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
@@ skipping 1888 matching lines @@
 
 <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 <a href="#Variable_declarations">variable declaration</a>
+It is shorthand for a regular <a href="#Variable_declarations">variable declaration</a>
 with initializer expressions but no types:
 </p>
 
 <pre class="grammar">
 "var" IdentifierList = ExpressionList .
 </pre>
 
 <pre>
 i, j := 0, 10
 f := func() int { return 7 }
@@ skipping 315 matching lines @@
 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:
+and is shorthand for a slice operation applied to an array:
 </p>
 
 <pre>
 tmp := [n]T{x1, x2, … xn}
 tmp[0 : n]
 </pre>
 
 <p>
 Within a composite literal of array, slice, or map type <code>T</code>,
 elements that are themselves composite literals may elide the respective
@@ skipping 196 matching lines @@
 
 <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 a shortcut for <code>(*x.A).f</code>.
+<code>x.f</code> is shorthand for <code>(*x.A).f</code>.
 </p>
 
 <p>
 For example, given the declarations:
 </p>
 
 <pre>
 type T0 struct {
         x int
 }
@@ skipping 36 matching lines @@
 
 <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:
+denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>.
+The value <code>x</code> is called the <i>index</i> or <i>map key</i>, respectively.
+The following rules apply:
 </p>
 
 <p>
 If <code>a</code> is not a map:
 </p>
 <ul>
         <li>the index <code>x</code> must be of integer type or untyped;
             it is <i>in range</i> if <code>0 &lt;= x &lt; len(a)</code>,
             otherwise it is <i>out of range</i></li>
         <li>a <a href="#Constants">constant</a> index must be non-negative
             and representable by a value of type <code>int</code>
 </ul>
 
 <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>:
+For <code>a</code> of <a href="#Array_types">array type</a> <code>A</code>:
 </p>
 <ul>
         <li>a <a href="#Constants">constant</a> index must be in range</li>
-        <li>if <code>a</code> is <code>nil</code> or if <code>x</code> is out of range at run time,
+        <li>if <code>x</code> is out of range at run time,
             a <a href="#Run_time_panics">run-time panic</a> occurs</li>
         <li><code>a[x]</code> is the array element at index <code>x</code> and the type of
             <code>a[x]</code> is the element type of <code>A</code></li>
 </ul>
 
 <p>
-For <code>a</code> of type <code>S</code> where <code>S</code> is a <a href="#Slice_types">slice type</a>:
+For <code>a</code> of <a href="#Pointer_types">pointer</a> to array type:
 </p>
 <ul>
-        <li>if the slice is <code>nil</code> or if <code>x</code> is out of range at run time,
+        <li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li>
+</ul>
+
+<p>
+For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>:
+</p>
+<ul>
+        <li>if <code>x</code> is out of range at run time,
             a <a href="#Run_time_panics">run-time panic</a> occurs</li>
         <li><code>a[x]</code> is the slice element at index <code>x</code> and the type of
             <code>a[x]</code> is the element type of <code>S</code></li>
 </ul>
 
 <p>
-For <code>a</code> of type <code>T</code>
-where <code>T</code> is a <a href="#String_types">string type</a>:
+For <code>a</code> of <a href="#String_types">string type</a>:
 </p>
 <ul>
         <li>a <a href="#Constants">constant</a> index must be in range
             if the string <code>a</code> is also constant</li>
         <li>if <code>x</code> is out of range at run time,
             a <a href="#Run_time_panics">run-time panic</a> occurs</li>
-        <li><code>a[x]</code> is the byte at index <code>x</code> and the type of
+        <li><code>a[x]</code> is the non-constant byte value at index <code>x</code> and the type of
             <code>a[x]</code> is <code>byte</code></li>
         <li><code>a[x]</code> may not be assigned to</li>
 </ul>
 
 <p>
-For <code>a</code> of type <code>M</code>
-where <code>M</code> is a <a href="#Map_types">map type</a>:
+For <code>a</code> of <a href="#Map_types">map type</a> <code>M</code>:
 </p>
 <ul>
         <li><code>x</code>'s type must be
             <a href="#Assignability">assignable</a>
             to the key type of <code>M</code></li>
         <li>if the map contains an entry with key <code>x</code>,
             <code>a[x]</code> is the map 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>
@@ skipping 33 matching lines @@
 
 <p>
 For a string, array, pointer to array, or slice <code>a</code>, the primary expression
 </p>
 
 <pre>
 a[low : high]
 </pre>
 
 <p>
-constructs a substring or slice. The indices <code>low</code> and
-<code>high</code> select which elements appear in the result. The result has
-indices starting at 0 and length equal to
+constructs a substring or slice. The <i>indices</i> <code>low</code> and
+<code>high</code> select which elements of operand <code>a</code> appear
+in the result. The result has indices starting at 0 and length equal to
 <code>high</code>&nbsp;-&nbsp;<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>
@@ skipping 12 matching lines @@
 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 indices <code>low</code> and <code>high</code> are
-<i>in range</i> if <code>0</code> &lt;= <code>low</code> &lt;= <code>high</code> &lt;= <code>len(a)</code>,
+If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for
+<code>(*a)[low : high]</code>.
+</p>
+
+<p>
+For arrays or strings, the indices are <i>in range</i> if
+<code>0</code> &lt;= <code>low</code> &lt;= <code>high</code> &lt;= <code>len(a)</code>,
 otherwise they are <i>out of range</i>.

[r, 2013/07/31 21:09:16]

look at line 2532.

[gri, 2013/07/31 21:23:14]

Line 2532 defines these terms for index expressions, this section defines them
for slice expressions.

But perhaps I am missing something?

Please comment on new CL 12198043.

 For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length.
 A <a href="#Constants">constant</a> index must be non-negative and representable by a value of type
 <code>int</code>.
-If both indices
-are constant, they must satisfy <code>low &lt;= high</code>. If <code>a</code> is <code>nil</code>
-or if the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
-</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 both indices are constant, they must satisfy <code>low &lt;= high</code>.
+If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
+</p>
+
+<p>
+Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice,
+the result of the slice operation is a non-constant value of the same type as the operand.
+For untyped string operands the result is a non-constant value of type <code>string</code>.
 If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>
 and the result of the slice operation is a slice with the same element type as the array.
 </p>
 
+<!-- TODO: should this be an implementation restriction? -->
+<p>
+If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result
+is a <code>nil</code> slice.
+<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)
@@ skipping 3220 matching lines @@
 </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>
 
 <p>
 A struct or array type has size zero if it contains no fields (or elements, respectively) that have a size greater than zero. Two distinct zero-size variables may have the same address in memory.
 </p>