code review 7100046: doc/go_spec.html: clarification about insertion during ...

doc/go_spec.html

 <!--{
         "Title": "The Go Programming Language Specification",
-        "Subtitle": "Version of January 9, 2013",
+        "Subtitle": "Version of January 11, 2013",

[gri, 2013/01/12 22:31:34]

up-date

         "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 4361 matching lines @@
 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  rune
 map             m  map[K]V                key      k  K      m[k]       V
-channel         c  chan E, <-chan E       element  e  E
+channel         c  chan E, &lt;-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>rune</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
 and is not guaranteed to be the same from one iteration to the next.
-If map entries that have not yet been reached are deleted during iteration,
+If map entries that have not yet been reached are removed during iteration,

[gri, 2013/01/12 22:31:34]

I may have missed the prev. discussion but I don't understand why this was
changed. "delete" is an operation defined on maps, but "remove" is not.

[gri, 2013/01/12 22:35:11]

Ok. 'remove' is fine.

 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.
+added during iteration, it is implementation dependent whether they will be

[gri, 2013/01/12 22:31:34]

same: inserted seemed better than 'added'.

[gri, 2013/01/12 22:35:11]

'added' is fine.

+produced in the iteration.  Each newly added entry will be produced not at

[gri, 2013/01/12 22:31:34]

s/./:/

[mdempsky, 2013/01/13 02:19:19]

Is it worth stating somehow that the decision of whether a newly added entry
will produce an iteration value can be made independently for each entry and
each execution?  I can imagine this wording being construed as limiting
implementations to either "new entries always produce iteration values" or "new
entries never produce iteration values".

I'm also curious if the intention is to allow the same key to produce multiple
iteration values if it's removed and re-added during iteration.  E.g., is this
code guaranteed to terminate or is it allowed to infinite loop?

  m := make(map[int]int)
  m[0] = 0
  for k, v := range m {
    delete(m, k)
    m[k] = v
  }

+all or exactly once.If the map is <code>nil</code>, the number of iterations

[iant, 2013/01/12 22:27:31]

Two spaces after "once."

+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>
@@ skipping 1246 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>