From b4f297238cb9c16fdd65f8a56b4f4ee6aad7aa8e Mon Sep 17 00:00:00 2001
From: Rob Pike <r@golang.org>
Date: Tue, 30 Mar 2010 11:21:50 -0700
Subject: Effective Go: update maps description regarding lookup of nonexistent
 entry.

R=rsc, gri, iant
CC=golang-dev
http://codereview.appspot.com/821044
---
 doc/effective_go.html | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

(limited to 'doc')

diff --git a/doc/effective_go.html b/doc/effective_go.html
index 728e07be1..ce5fcb99d 100644
--- a/doc/effective_go.html
+++ b/doc/effective_go.html
@@ -1121,9 +1121,23 @@ var timeZone = map[string] int {
 <p>
 Assigning and fetching map values looks syntactically just like
 doing the same for arrays except that the index doesn't need to
-be an integer.  An attempt to fetch a map value with a key that
-is not present in the map will cause the program to crash, but
-there is a way to do so safely using a multiple assignment.
+be an integer.
+</p>
+<pre>
+offset := timeZone["EST"]
+</pre>
+<p>
+An attempt to fetch a map value with a key that
+is not present in the map will return the zero value for the type
+of the entries
+in the map.  For instance, if the map contains integers, looking
+up a non-existent key will return <code>0</code>.
+</p>
+<p>
+Sometimes you need to distinguish a missing entry from
+a zero value.  Is there an entry for <code>"UTC"</code>
+or is that zero value because it's not in the map at all?
+You can discriminate with a form of multiple assignment.
 </p>
 <pre>
 var seconds int
@@ -1136,7 +1150,7 @@ In this example, if <code>tz</code> is present, <code>seconds</code>
 will be set appropriately and <code>ok</code> will be true; if not,
 <code>seconds</code> will be set to zero and <code>ok</code> will
 be false.
-Here's a function that puts it together:
+Here's a function that puts it together with a nice error report:
 </p>
 <pre>
 func offset(tz string) int {
@@ -1151,7 +1165,7 @@ func offset(tz string) int {
 To test for presence in the map without worrying about the actual value,
 you can use the <em>blank identifier</em>, a simple underscore (<code>_</code>).
 The blank identifier can be assigned or declared with any value of any type, with the
-value discarded harmlessly.  For testing presence in a map, use the blank
+value discarded harmlessly.  For testing just presence in a map, use the blank
 identifier in place of the usual variable for the value.
 </p>
 <pre>
@@ -1166,6 +1180,7 @@ from the map.
 <pre>
 timeZone["PDT"] = 0, false  // Now on Standard Time
 </pre>
+
 <h3 id="printing">Printing</h3>
 
 <p>
-- 
cgit v1.2.3