summaryrefslogtreecommitdiffstats
path: root/doc/dict.n
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2012-01-17 15:22:55 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2012-01-17 15:22:55 (GMT)
commitbf96173904e2e0d289576e5e1ba2f1dfb1b90194 (patch)
treeeef80d1e1891349659e5548eaa89d006587f0274 /doc/dict.n
parentdda8d01bf91452b66b1e96441fbdf411bbb92a53 (diff)
parent39c48e8c29a2e3955bb342c100298c8a27b31372 (diff)
downloadtcl-bf96173904e2e0d289576e5e1ba2f1dfb1b90194.zip
tcl-bf96173904e2e0d289576e5e1ba2f1dfb1b90194.tar.gz
tcl-bf96173904e2e0d289576e5e1ba2f1dfb1b90194.tar.bz2
* doc/dict.n (dict with): [Bug 3474512]: Explain better what is going on when a dictionary key and the dictionary variable collide.
Diffstat (limited to 'doc/dict.n')
-rw-r--r--doc/dict.n19
1 files changed, 19 insertions, 0 deletions
diff --git a/doc/dict.n b/doc/dict.n
index b8386f2..361a112 100644
--- a/doc/dict.n
+++ b/doc/dict.n
@@ -251,6 +251,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
@@ -388,6 +397,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