summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2012-01-17 15:17:21 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2012-01-17 15:17:21 (GMT)
commit39c48e8c29a2e3955bb342c100298c8a27b31372 (patch)
tree5d7e9bdbdfdf8d4df03f21596c538e2b8d25bb1a
parent6cd986d9ff37f90c342c96d2c86a8ce77119852f (diff)
downloadtcl-39c48e8c29a2e3955bb342c100298c8a27b31372.zip
tcl-39c48e8c29a2e3955bb342c100298c8a27b31372.tar.gz
tcl-39c48e8c29a2e3955bb342c100298c8a27b31372.tar.bz2
* doc/dict.n (dict with): [Bug 3474512]: Explain better what is going on when a dictionary key and the dictionary variable collide.
-rw-r--r--ChangeLog5
-rw-r--r--doc/dict.n19
2 files changed, 24 insertions, 0 deletions
diff --git a/ChangeLog b/ChangeLog
index e3086b7..0f19ea4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2012-01-17 Donal K. Fellows <dkf@users.sf.net>
+
+ * doc/dict.n (dict with): [Bug 3474512]: Explain better what is going
+ on when a dictionary key and the dictionary variable collide.
+
2012-01-17 Don Porter <dgp@users.sourceforge.net>
* library/http/http.tcl: Bump to version 2.7.8
diff --git a/doc/dict.n b/doc/dict.n
index c54a990..28c4f7c 100644
--- a/doc/dict.n
+++ b/doc/dict.n
@@ -227,6 +227,15 @@ exist after the command finishes (unless explicitly \fBunset\fR).
Note that the mapping of values to variables does not use
traces; changes to the \fIdictionaryVariable\fR's contents only happen
when \fIbody\fR terminates.
+.PP
+If the \fIdictionaryVariable\fR contains a value that is not a dictionary at
+the point when the \fIbody\fR terminates (which can easily happen if the name
+is the same as any of the keys in dictionary) then an error occurs at that
+point. This command is thus not recommended for use when the keys in the
+dictionary are expected to clash with the \fIdictionaryVariable\fR name
+itself. Where the contained key does map to a dictionary, the net effect is to
+combine that inner dictionary into the outer dictionary; see the
+\fBEXAMPLES\fR below for an illustration of this.
.RE
.SH "DICTIONARY VALUES"
.PP
@@ -364,6 +373,16 @@ sumDictionary myDict
puts "dictionary is now \\"$myDict\\""
# prints: \fIdictionary is now "a {total 6} b {total 15}"\fR
.CE
+.PP
+When \fBdict with\fR is used with a key that clashes with the name of the
+dictionary variable:
+.PP
+.CS
+set foo {foo {a b} bar 2 baz 3}
+\fBdict with\fR foo {}
+puts $foo
+# prints: \fIa b foo {a b} bar 2 baz 3\fR
+.CE
.SH "SEE ALSO"
append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)
.SH KEYWORDS