summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2010-01-19 09:48:57 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2010-01-19 09:48:57 (GMT)
commiteb8c21682b72bee7dd91e034b8f1a1bb773c63bc (patch)
tree7fdaf123c233d1e7f251c589ddf6ede1abfc83f4
parentdd8e1bd7964abd576b6ae32c876f793ae4bbaf9b (diff)
downloadtcl-eb8c21682b72bee7dd91e034b8f1a1bb773c63bc.zip
tcl-eb8c21682b72bee7dd91e034b8f1a1bb773c63bc.tar.gz
tcl-eb8c21682b72bee7dd91e034b8f1a1bb773c63bc.tar.bz2
[Bug 2929546]: Improve the dict documentation.
-rw-r--r--ChangeLog5
-rw-r--r--doc/dict.n62
2 files changed, 63 insertions, 4 deletions
diff --git a/ChangeLog b/ChangeLog
index ba8850b..b846268 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2010-01-19 Donal K. Fellows <dkf@users.sf.net>
+
+ * doc/dict.n: [Bug 2929546]: Clarify just what [dict with] and [dict
+ update] are doing with variables.
+
2010-01-18 Andreas Kupries <andreask@activestate.com>
* generic/tclIO.c (CreateScriptRecord): [Bug 2918110]: Initialize
diff --git a/doc/dict.n b/doc/dict.n
index 2dc4db3..ffb1500 100644
--- a/doc/dict.n
+++ b/doc/dict.n
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: dict.n,v 1.21 2009/01/07 13:50:03 dkf Exp $
+'\" RCS: @(#) $Id: dict.n,v 1.22 2010/01/19 09:48:58 dkf Exp $
'\"
.so man.macros
.TH dict n 8.5 Tcl "Tcl Built-In Commands"
@@ -107,7 +107,7 @@ dict get $dict foo bar spong
dict get [dict get [dict get $dict foo] bar] spong
.CE
.PP
-If no keys are provided, dict would return a list containing pairs of
+If no keys are provided, \fBdict get\fR will return a list containing pairs of
elements in a manner similar to \fBarray get\fR. That is, the first
element of each pair would be the key and the second element would be
the value for that key.
@@ -208,9 +208,18 @@ to the dictionary within \fIdictionaryVariable\fR (unless
are silently discarded), even if the result of \fIbody\fR is an error
or some other kind of exceptional exit. The result of \fBdict
update\fR is (unless some kind of error occurs) the result of the
-evaluation of \fIbody\fR. Note that the mapping of values to variables
+evaluation of \fIbody\fR.
+.RS
+.PP
+Each \fIvarName\fR is mapped in the scope enclosing the \fBdict update\fR;
+it is recommended that this command only be used in a local scope
+(\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of
+this, the variables set by \fBdict update\fR will continue to
+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.
+.RE
.TP
\fBdict values \fIdictionaryValue \fR?\fIglobPattern\fR?
.
@@ -233,10 +242,20 @@ dictionary be discarded, and this also happens if the contents of
\fIdictionaryVariable\fR are adjusted so that the chain of
dictionaries no longer exists. The result of \fBdict with\fR is
(unless some kind of error occurs) the result of the evaluation of
-\fIbody\fR. Note that the mapping of values to variables does not use
+\fIbody\fR.
+.RS
+.PP
+The variables are mapped in the scope enclosing the \fBdict with\fR;
+it is recommended that this command only be used in a local scope
+(\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of
+this, the variables set by \fBdict with\fR will continue to
+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.
+.RE
.SH "DICTIONARY VALUES"
+.PP
Dictionaries are values that contain an efficient, order-preserving
mapping from arbitrary keys to arbitrary values.
Each key in the dictionary maps to a single value.
@@ -254,6 +273,12 @@ the others are ignored, meaning that,
and
.QW "apple carrot apple banana"
are equivalent dictionaries (with different string representations).
+.PP
+Operations that derive a new dictionary from an old one (e.g., updates
+like \fBdict set\fR and \fBdict unset\fR) preserve the order of keys
+in the dictionary. The exceptions to this are for any new keys they
+add, which are appended to the sequence, and any keys that are
+removed, which are excised from the order.
.SH EXAMPLES
.PP
Basic dictionary usage:
@@ -336,6 +361,35 @@ foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
set upperCaseMap [\fBdict get\fR $capital $env(LANG)]
set upperCase [string map $upperCaseMap $string]
.CE
+.PP
+Showing the detail of \fBdict with\fR:
+.PP
+.CS
+proc sumDictionary {varName} {
+ upvar 1 $varName vbl
+ foreach key [\fBdict keys\fR $vbl] {
+ # Manufacture an entry in the subdictionary
+ \fBdict set\fR vbl $key total 0
+ # Add the values and remove the old
+ \fBdict with\fR vbl $key {
+ set total [expr {$x + $y + $z}]
+ unset x y z
+ }
+ }
+ puts "last total was $total, for key $key"
+}
+
+set myDict {
+ a {x 1 y 2 z 3}
+ b {x 6 y 5 z 4}
+}
+
+sumDictionary myDict
+# prints: \fIlast total was 15, for key b\fR
+
+puts "dictionary is now \\"$myDict\\""
+# prints: \fIdictionary is now "a {total 6} b {total 15}"\fR
+.CE
.SH "SEE ALSO"
append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)
.SH KEYWORDS