Added example (based on TIP)

1 files changed, 30 insertions, 1 deletions

diff --git a/doc/dict.n b/doc/dict.n
index bea4ee8..76ae211 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.3 2004/03/12 23:21:05 dkf Exp $
+'\" RCS: @(#) $Id: dict.n,v 1.4 2004/05/27 23:53:55 dkf Exp $
 '\"
 .so man.macros
 .TH dict n 8.5 Tcl "Tcl Built-In Commands"
@@ -181,6 +181,35 @@ will be in an arbitrary implementation-specific order, though where no
 pattern is supplied the i'th key returned by \fBdict keys\fR will be
 the key for the i'th value returned by \fBdict values\fR applied to
 the same dictionary value.
+.SH "DICTIONARY VALUES"
+Dictionaries are values that contain an efficient mapping from
+arbitrary keys to arbitrary values.  They have a textual format that
+is exactly that of any list with an even number of elements, with each
+mapping in the dictionary being represented as two items in the list.
+When a command takes a dictionary and produces a new dictionary based
+on it (either returning it or writing it back into the variable that
+the starting dictionary was read from) there is no guarantee that the
+new dictionary will have the same ordering of keys.
+.SH EXAMPLE
+A localizable version of \fBstring toupper\fR:
+.CS
+# Set up the basic C locale
+set capital [dict create C [dict create]]
+foreach c {abcdefghijklmnopqrstuvwxyz} {
+    dict set capital C $c [string toupper $c]
+}
+
+# English locales can luckily share the "C" locale
+dict set capital en [dict get $capital C]
+dict set capital en_US [dict get $capital C]
+dict set capital en_GB [dict get $capital C]
+
+# ... and so on for other supported languages ...
+
+# Now get the mapping for the current locale and use it.
+set upperCaseMap [dict get $capital $env(LANG)]
+set upperCase [string map $upperCaseMap $string]
+.CE
 
 .SH "SEE ALSO"
 append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)