summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2010-01-19 09:57:15 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2010-01-19 09:57:15 (GMT)
commit4d4786ddbcfbc51bf7d05c670806ab3f9a045c56 (patch)
treeebe6783de666ed83e488215baa51670bace933dc
parent0de317d573fcb3c53eae3f6e5c8587b36968651c (diff)
downloadtcl-4d4786ddbcfbc51bf7d05c670806ab3f9a045c56.zip
tcl-4d4786ddbcfbc51bf7d05c670806ab3f9a045c56.tar.gz
tcl-4d4786ddbcfbc51bf7d05c670806ab3f9a045c56.tar.bz2
[bug 2929546]: Improve the dict documentation.
-rw-r--r--ChangeLog5
-rw-r--r--doc/dict.n95
2 files changed, 95 insertions, 5 deletions
diff --git a/ChangeLog b/ChangeLog
index 6a68cbd..9ce8e09 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 f2ab912..180fbc4 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.18 2007/12/31 00:17:44 dkf Exp $
+'\" RCS: @(#) $Id: dict.n,v 1.18.2.1 2010/01/19 09:57:15 dkf Exp $
'\"
.so man.macros
.TH dict n 8.5 Tcl "Tcl Built-In Commands"
@@ -90,15 +90,17 @@ supplied, the behaviour of the command shall be as if the result of
subsequent) arguments. This facilitates lookups in nested
dictionaries. For example, the following two commands are equivalent:
.RS
+.PP
.CS
dict get $dict foo bar spong
dict get [dict get [dict get $dict foo] bar] spong
.CE
-If no keys are provided, dict would return a list containing pairs of
+.PP
+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.
-
+.PP
It is an error to attempt to retrieve a value for a key that is not
present in the dictionary.
.RE
@@ -184,9 +186,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 or lambda term for \fBapply\fR). 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?
Return a list of all values in the given dictionary value. If a
@@ -207,10 +218,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 or lambda term for \fBapply\fR). 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.
@@ -228,8 +249,42 @@ 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:
+.PP
+.CS
+# Make a dictionary to map extensions to descriptions
+set filetypes [\fBdict create\fR .txt "Text File" .tcl "Tcl File"]
+
+# Add/update the dictionary
+\fBdict set\fR filetypes .tcl "Tcl Script"
+\fBdict set\fR filetypes .tm "Tcl Module"
+\fBdict set\fR filetypes .gif "GIF Image"
+\fBdict set\fR filetypes .png "PNG Image"
+
+# Simple read from the dictionary
+set ext ".tcl"
+set desc [\fBdict get\fR $filetypes $ext]
+puts "$ext is for a $desc"
+
+# Somewhat more complex, with existence test
+foreach filename [glob *] {
+ set ext [file extension $filename]
+ if {[\fBdict exists\fR $filetypes $ext]} {
+ puts "$filename is a [\fBdict get\fR $filetypes $ext]"
+ }
+}
+.CE
+.PP
Constructing and using nested dictionaries:
+.PP
.CS
# Data for one employee
\fBdict set\fR employeeInfo 12345-A forenames "Joe"
@@ -263,6 +318,7 @@ foreach id [\fBdict keys\fR $employeeInfo] {
.CE
.PP
A localizable version of \fBstring toupper\fR:
+.PP
.CS
# Set up the basic C locale
set capital [\fBdict create\fR C [\fBdict create\fR]]
@@ -281,6 +337,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