From d689d3ec300097edb4ba5cc9999d57a1adb7b35a Mon Sep 17 00:00:00 2001
From: dkf <donal.k.fellows@manchester.ac.uk>
Date: Mon, 26 Apr 2004 09:47:18 +0000
Subject: Stronger wording & example. [Bug 940843]
---
ChangeLog | 3 +++
doc/DictObj.3 | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++---------
2 files changed, 57 insertions(+), 9 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index b862eed..c07ffdd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,8 @@
2004-04-26 Donal K. Fellows <donal.k.fellows@man.ac.uk>
+ * doc/DictObj.3: Added warning about the use of Tcl_DictObjDone and an
+ example of use of iteration. [Bug 940843]
+
* doc/Thread.3: Reworked to remove references to testing interfaces
and instead promote the use of the Thread package. [Patch 932527]
Also reworked and reordered the page for better readability.
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
-
--
cgit v0.12