Clarified meaning of dictionary values following discussion on comp.lang.tcl.

2 files changed, 26 insertions, 17 deletions

diff --git a/ChangeLog b/ChangeLog
index 1ba3f23..e6e5549 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,18 +1,22 @@
+2007-12-31  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/dict.n: Clarified meaning of dictionary values following
+	discussion on comp.lang.tcl.
+
 2007-12-26  Miguel Sofer  <msofer@users.sf.net>
 
 	* generic/tclCmdIL.c: more [lsort] data handling streamlines. The
-	function MergeSort is gone, essentially inlined into
-	Tcl_LsortObjCmd. It is not a straight inlining, two loops over all
-	lists elements where merged in the process: the linked list
-	elements are now built and merged into the temporary sublists in
-	the same pass.
+	function MergeSort is gone, essentially inlined into Tcl_LsortObjCmd.
+	It is not a straight inlining, two loops over all lists elements where
+	merged in the process: the linked list elements are now built and
+	merged into the temporary sublists in the same pass.
 
 2007-12-25  Miguel Sofer  <msofer@users.sf.net>
 
-	* generic/tclCmdIL.c: more [lsort] data handling streamlines. 
-	Extra mem reqs of latest patches removed, restored to previous mem
-	profile. Improved -unique handling, now eliminating repeated elems
-	immediately instead of marking them to avoid reinsertion at the end.
+	* generic/tclCmdIL.c: more [lsort] data handling streamlines. Extra
+	mem reqs of latest patches removed, restored to previous mem profile.
+	Improved -unique handling, now eliminating repeated elems immediately
+	instead of marking them to avoid reinsertion at the end.
 
 2007-12-23  Jeff Hobbs  <jeffh@ActiveState.com>
 
@@ -32,9 +36,9 @@
 2007-12-21  Miguel Sofer  <msofer@users.sf.net>
 
 	* generic/tclCmdIL.c (Tcl_LsortObjCmd): preallocate a listObj of
-	sufficient length for the sorted list instead of growing
-	it. Second commit replaces calls to Tcl_ListObjAppenElement with
-	direct access to the internal rep.
+	sufficient length for the sorted list instead of growing it. Second
+	commit replaces calls to Tcl_ListObjAppenElement with direct access to
+	the internal rep.
 
 2007-12-19  Don Porter	<dgp@users.sourceforge.net>
 
diff --git a/doc/dict.n b/doc/dict.n
index fc1d237..f2ab912 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.17 2007/12/13 15:22:32 dgp Exp $
+'\" RCS: @(#) $Id: dict.n,v 1.18 2007/12/31 00:17:44 dkf Exp $
 '\"
 .so man.macros
 .TH dict n 8.5 Tcl "Tcl Built-In Commands"
@@ -15,7 +15,6 @@ dict \- Manipulate dictionaries
 .SH SYNOPSIS
 \fBdict \fIoption arg \fR?\fIarg ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
 Performs one of several operations on dictionary values or variables
@@ -214,6 +213,7 @@ when \fIbody\fR terminates.
 .SH "DICTIONARY VALUES"
 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.
 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
@@ -221,6 +221,13 @@ 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) the new dictionary will have the same order of keys,
 modulo any deleted keys and with new keys added on to the end.
+When a string is interpreted as a dictionary and it would otherwise
+have duplicate keys, only the last value for a particular key is used;
+the others are ignored, meaning that,
+.QW "apple banana"
+and
+.QW "apple carrot apple banana"
+are equivalent dictionaries (with different string representations).
 .SH EXAMPLES
 Constructing and using nested dictionaries:
 .CS
@@ -254,7 +261,7 @@ foreach id [\fBdict keys\fR $employeeInfo] {
    puts "Hello, [\fBdict get\fR $employeeInfo $id forenames]!"
 }
 .CE
-
+.PP
 A localizable version of \fBstring toupper\fR:
 .CS
 # Set up the basic C locale
@@ -274,9 +281,7 @@ foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
 set upperCaseMap [\fBdict get\fR $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)
-
 .SH KEYWORDS
 dictionary, create, update, lookup, iterate, filter