spec: document special cases for floating-point maps

[bcmills]

In #20660 (comment), I noted that there are undocumented special cases in the handling of maps with floating-point keys.

Regardless of what happens with that proposal for Go 2, we should fix the Go 1 spec to properly document those cases.

---

In Map types, add:

Elements may be added during execution using assignments and retrieved with index expressions and range clauses; they may be removed with the delete built-in function.

---

In Index expressions, add:

For a of map type M:

• x's type must be assignable to the key type of M
• if the map contains an entry with key equal to x, a[x] is the map element with key x and the type of a[x] is the element type of M
• if the map is nil or does not contain such an entry and the index expression is not a left-hand side operand of an assignment, a[x] is the zero value for the element type of M

---

In Assignments, add:

The assignment proceeds in two phases. First, the operands of index expressions and pointer indirections (including implicit pointer indirections in selectors) on the left and the expressions on the right are all evaluated in the usual order. Second, the assignments are carried out in left-to-right order.

If the left operand of an assignment is an index expression on a map that does not contain a key equal to the given key, the assignment creates a new entry in the map. If the map is nil, a run-time panic occurs.

---

In For statements with range clause, add:

Range expression                          1st value          2nd value

[…]
map             m  map[K]V                key      k  K      see below  V
[…]

[…]

3. For a map value, the "range" clause iterates over successive entries of the map.
   On successive iterations, the index value will be the key, and the second value will be the element associated with that key. If the key is or contains a NaN value, it may be associated with multiple entries; the elements of those entries can only be retrieved using "range" clauses (not index expressions).

   The iteration order over maps is not specified and is not guaranteed to be the same from one iteration to the next. If a map entry that has not yet been reached is removed during iteration, the corresponding iteration value will not be produced. If a map entry is created during iteration, that entry may be produced during the iteration or may be skipped. The choice may vary for each entry created and from one iteration to the next. If the map is nil, the number of iterations is 0.

---

In Deletion of map elements, add:

The built-in function delete removes the element with key equal to k from a map m.

[cznic]

Let me pick just one example from the list to illustrate the more general principle seen in the proposal:

The built-in function delete removes the element with key equal to k from a map m.

This is true. It was true before this proposal and it will remain true if the proposal is adopted. I don't think it adds something new to the documentation. Just saying that delete(m, k) removes k from m has IMHO exactly and precisely the same meaning. k is not in the map wrt to map indexing when k != k, it can be just discovered by ranging, which in contrast to indexing does not actually rely on keys being comparable at all.

[bcmills]

This is true. It was true before this proposal and it will remain true if the proposal is adopted.

Yes, that is the case for all documentation issues.

k is not in the map wrt to map indexing when k != k, it can be just discovered by ranging,
which in contrast to indexing does not actually rely on keys being comparable at all.

That is the information that is currently missing from the documentation.