summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2004-10-02 17:00:36 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2004-10-02 17:00:36 (GMT)
commit88f9d3bd05de49706576568a9f03370565de7f78 (patch)
treedca9d4be230f431a028253edd974a75803f59f91 /doc
parentec917053061e438dba385646ae15104397cd6dfa (diff)
downloadtcl-88f9d3bd05de49706576568a9f03370565de7f78.zip
tcl-88f9d3bd05de49706576568a9f03370565de7f78.tar.gz
tcl-88f9d3bd05de49706576568a9f03370565de7f78.tar.bz2
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.
Diffstat (limited to 'doc')
-rw-r--r--doc/DictObj.332
-rw-r--r--doc/dict.n8
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.