diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/DictObj.3 | 32 | ||||
| -rw-r--r-- | doc/dict.n | 8 |
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 @@ -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. |