doc/go1: map deletion
This CL is in part a proposal for how to write these sections:
- Brief discussion of change
- No attempt to analyze the thinking about it
- Old code
- New code, runnable if possible
- How to update old programs
R=golang-dev, remyoudompheng, gri, adg
CC=golang-dev
https://golang.org/cl/5454044
diff --git a/doc/go1.html b/doc/go1.html
index 507c96f..3d04545 100644
--- a/doc/go1.html
+++ b/doc/go1.html
@@ -8,11 +8,24 @@
</p>
<p>
-Go 1 is intended to be a stable language and core library set that will form a reliable foundation for people and organizations that want to make a long-term commitment to developing in the Go programming language. Go will continue to develop, but in a way that guarantees code written to the Go 1 specification will continue to work. For instance, Go 1 will be a supported platform on Google App Engine for the next few years. Incompatible changes to the environment, should they arise, will be done in a distinct version.
+Go 1 is intended to be a stable language and core library set that
+will form a reliable foundation for people and organizations that
+want to make a long-term commitment to developing in the Go programming
+language. Go will continue to develop, but in a way that guarantees
+code written to the Go 1 specification will continue to work. For
+instance, Go 1 will be a supported platform on Google App Engine
+for the next few years. Incompatible changes to the environment,
+should they arise, will be done in a distinct version.
</p>
<p>
-This document describes the changes in the language and libraries in Go 1, relative to the previous release, r60 (at the time of writing, tagged as r60.3). It also explains how to update code at r60 to compile and run under Go 1. Finally, it outlines the new <code>go</code> command for building Go programs and the new binary release process being introduced. Most of these topics have more thorough presentations elsewhere; such documents are linked below.
+This document describes the changes in the language and libraries
+in Go 1, relative to the previous release, r60 (at the time of
+writing, tagged as r60.3). It also explains how to update code at
+r60 to compile and run under Go 1. Finally, it outlines the new
+<code>go</code> command for building Go programs and the new binary
+release process being introduced. Most of these topics have more
+thorough presentations elsewhere; such documents are linked below.
<h2 id="language">Changes to the language</h2>
@@ -26,7 +39,41 @@
<h3 id="rune">The rune type</h3>
-<h3 id="delete">Deleting from maps</h3>
+<h3 id="map_deletion">Deleting from maps</h3>
+
+<p>
+The original syntax for deleting an element in a map was:
+</p>
+
+<pre>
+ m[x] = ignored, false
+</pre>
+
+<p>
+This syntax had a number of minor problems and is being replaced.
+As of Go 1, that syntax is gone and in its place is a new built-in
+function, <code>delete</code>. The call
+</p>
+
+<pre><!--{{code "progs/go1.go" `/delete\(m, k\)/`}}
+--> delete(m, k)
+</pre>
+
+<p>
+will delete the map entry retrieved by the expression <code>m[k]</code>.
+There is no return value. Deleting a non-existent entry is a no-op.
+</p>
+
+<p>
+<em>Updating</em>:
+Gofix will convert expressions of the form <code>m[k] = ignored,
+false</code> into <code>delete(m, k)</code> when it is clear that
+the ignored value can be safely discarded from the program and
+<code>false</code> refers to the predefined boolean constant. Gofix
+will flag other uses of the syntax for inspection by the programmer.
+</p>
+
+<h3 id="map_iteration">Iterating in maps</h3>
<h3 id="multiple_assignment">Multiple assignment</h3>
