Modify the semantics of [dict set] to be what everyone expected them to be

in a straw poll. Also made T_DODone;T_DONext a non-fatal sequence, leading
to simplified code.

2 files changed, 18 insertions, 22 deletions

diff --git a/doc/DictObj.3 b/doc/DictObj.3
index 93291f7..01e20cf 100644
--- a/doc/DictObj.3
+++ b/doc/DictObj.3
@@ -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: DictObj.3,v 1.4 2004/09/18 17:01:05 dkf Exp $
+'\" RCS: @(#) $Id: DictObj.3,v 1.5 2004/10/02 17:00:38 dkf Exp $
 '\" 
 .so man.macros
 .TH Tcl_DictObj 3 8.5 Tcl "Tcl Library Procedures"
@@ -161,9 +161,11 @@ If the last call to \fBTcl_DictObjFirst\fR or \fBTcl_DictObjNext\fR
 \fIdonePtr\fR argument to zero but no further key/value pairs are
 desired from that particular iteration, the \fIsearchPtr\fR argument
 must be passed to \fBTcl_DictObjDone\fR to release any internal locks
-held by the searching process.  \fBTcl_DictObjDone\fR \fImust not\fR
-be called if either \fBTcl_DictObjFirst\fR or \fBTcl_DictObjNext\fR
-set the variable pointed to by \fIdonePtr\fR to 1.
+held by the searching process.  If \fBTcl_DictObjNext\fR is called on
+a particular \fIsearchPtr\fR after \fBTcl_DictObjDone\fR is called on
+it, the variable pointed to by \fIdonePtr\fR will always be set to 1
+(and nothing else will happen). It is safe to call
+\fBTcl_DictObjDone\fR multiple times on the same \fIsearchPtr\fR.
 .PP
 The procedures \fBTcl_DictObjPutKeyList\fR and
 \fBTcl_DictObjRemoveKeyList\fR are the close analogues of
@@ -175,7 +177,10 @@ stored as values inside outer dictionaries.  The \fIkeyc\fR and
 first) that acts as a path to the key/value pair to be affected.  Note
 that there is no corresponding operation for reading a value for a
 path as this is easy to construct from repeated use of
-\fBTcl_DictObjGet\fR.
+\fBTcl_DictObjGet\fR. With \fBTcl_DictObjPutKeyList\fR, nested
+dictionaries are created for non-terminal keys where they do not
+already exist. With \fBTcl_DictObjRemoveKeyList\fR, all non-terminal
+keys must exist and have dictionaries as their values.
 .SH EXAMPLE
 Using the dictionary iteration interface to search determine if there
 is a key that maps to itself:
@@ -193,37 +198,28 @@ int done;
  * reference count management is also used.  The lock is
  * released automatically when the loop is finished, but must
  * be released manually when an exceptional exit from the loop
- * is performed.
+ * is performed. However it is safe to try to release the lock
+ * even if we've finished iterating over the loop.
  */
 if (Tcl_DictObjFirst(interp, objPtr, &search,
         &key, &value, &done) != TCL_OK) {
     return TCL_ERROR;
 }
 for (; done ; Tcl_DictObjNext(&search, &key, &value, &done)) {
-
     /*
      * Note that strcmp() is not a good way of comparing
      * objects and is just used here for demonstration
      * purposes.
      */
     if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) {
-
-        /*
-         * We jump out of the loop, so we must release the
-         * lock on the object representation that the iterator
-         * is currently holding.
-         */
-        Tcl_DictObjDone(&search);
-
         break;
     }
 }
-/*
- * Note, *no* call to Tcl_DictObjDone() here!
- */
+Tcl_DictObjDone(&search);
 Tcl_SetObjResult(interp, Tcl_NewBooleanObj(!done));
 return TCL_OK;
 .CE
+
 .SH "SEE ALSO"
 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable
 .SH KEYWORDS
diff --git a/doc/dict.n b/doc/dict.n
index 715814d..7950ea1 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.6 2004/09/18 17:01:06 dkf Exp $
+'\" RCS: @(#) $Id: dict.n,v 1.7 2004/10/02 17:00:38 dkf Exp $
 '\"
 .so man.macros
 .TH dict n 8.5 Tcl "Tcl Built-In Commands"
@@ -157,9 +157,9 @@ key but no value.
 \fBdict set \fIdictionaryVariable key \fR?\fIkey ...\fR? \fIvalue\fR
 This operation takes the name of a variable containing a dictionary
 value and places an updated dictionary value in that variable
-containing a mapping from the given key to the given value. In a
-manner analogous to \fBlset\fR, where multiple keys are present, they
-do indexing into nested dictionaries.
+containing a mapping from the given key to the given value. When
+multiple keys are present, this operation creates or updates a chain
+of nested dictionaries.
 .TP
 \fBdict size \fIdictionaryValue\fR
 Return the number of key/value mappings in the given dictionary value.