summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2004-04-26 09:47:18 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2004-04-26 09:47:18 (GMT)
commitd689d3ec300097edb4ba5cc9999d57a1adb7b35a (patch)
treefdd9135f2ed90fb2fb9de4e03fd8c01d8cd8af26 /doc
parent6747c2f02e6ceb202cdb41d009a8f1ce545bca69 (diff)
downloadtcl-d689d3ec300097edb4ba5cc9999d57a1adb7b35a.zip
tcl-d689d3ec300097edb4ba5cc9999d57a1adb7b35a.tar.gz
tcl-d689d3ec300097edb4ba5cc9999d57a1adb7b35a.tar.bz2
Stronger wording & example. [Bug 940843]
Diffstat (limited to 'doc')
-rw-r--r--doc/DictObj.363
1 files changed, 54 insertions, 9 deletions
diff --git a/doc/DictObj.3 b/doc/DictObj.3
index 24f41dd..fd5da1c 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.1 2003/04/05 01:03:20 dkf Exp $
+'\" RCS: @(#) $Id: DictObj.3,v 1.2 2004/04/26 09:47:18 dkf Exp $
'\"
.so man.macros
.TH Tcl_DictObj 3 8.5 Tcl "Tcl Library Procedures"
@@ -58,6 +58,10 @@ an attempt will be made to convert it to one.
.AP Tcl_Obj *keyPtr in
Points to the key for the key/value pair being manipulated within the
dictionary object.
+.AP Tcl_Obj **keyPtrPtr out
+Points to a variable that will have the key from a key/value pair
+placed within it. May be NULL to indicate that the caller is not
+interested in the key.
.AP Tcl_Obj *valuePtr in
Points to the value for the key/value pair being manipulate within the
dictionary object (or sub-object, in the case of
@@ -67,10 +71,6 @@ Points to a variable that will have the value from a key/value pair
placed within it. For \fBTcl_DictObjFirst\fR and
\fBTcl_DictObjNext\fR, this may be NULL to indicate that the caller is
not interested in the value.
-.AP Tcl_Obj **valuePtrPtr out
-Points to a variable that will have the key from a key/value pair
-placed within it. May be NULL to indicate that the caller is not
-interested in the key.
.AP int *sizePtr out
Points to a variable that will have the number of key/value pairs
contained within the dictionary placed within it.
@@ -160,7 +160,9 @@ 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.
+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.
.PP
The procedures \fBTcl_DictObjPutKeyList\fR and
\fBTcl_DictObjRemoveKeyList\fR are the close analogues of
@@ -173,12 +175,55 @@ 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.
+.SH EXAMPLE
+Using the dictionary iteration interface to search determine if there
+is a key that maps to itself:
+
+.CS
+Tcl_DictSearch search;
+Tcl_Obj *key, *value;
+int done;
+
+/*
+ * Assume interp and objPtr are parameters. This is the
+ * idiomatic way to start an iteration over the dictionary; it
+ * sets a lock on the internal representation that ensures that
+ * there are no concurrent modification issues when normal
+ * 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.
+ */
+if (Tcl_DictObjFirst(interp, objPtr, &search,
+ &key, &value, &done) != TCL_OK) {
+ return TCL_ERROR;
+}
+for (; done ; Tcl_DictObjNext(&search, &key, &value, &done)) {
-'\" TODO: Example of using Tcl_DictObj{First,Next,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_SetObjResult(interp, Tcl_NewBooleanObj(!done));
+return TCL_OK;
+.CE
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable
-
.SH KEYWORDS
dict, dict object, dictionary, hash table, iteration, object
-