1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
'\"
'\" Copyright (c) 2003 Donal K. Fellows
'\"
'\" 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.3 2004/09/06 09:44:56 dkf Exp $
'\"
.so man.macros
.TH Tcl_DictObj 3 8.5 Tcl "Tcl Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList \- manipulate Tcl objects as dictionaries
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewDictObj\fR()
.sp
int
\fBTcl_DictObjGet\fR(\fIinterp, dictPtr, keyPtr, valuePtrPtr\fR)
.sp
int
\fBTcl_DictObjPut\fR(\fIinterp, dictPtr, keyPtr, valuePtr\fR)
.sp
int
\fBTcl_DictObjRemove\fR(\fIinterp, dictPtr, keyPtr\fR)
.sp
int
\fBTcl_DictObjSize\fR(\fIinterp, dictPtr, sizePtr\fR)
.sp
int
\fBTcl_DictObjFirst\fR(\fIinterp, dictPtr, searchPtr, keyPtrPtr, valuePtrPtr, donePtr\fR)
.sp
void
\fBTcl_DictObjNext\fR(\fIsearchPtr, keyPtrPtr, valuePtrPtr, donePtr\fR)
.sp
void
\fBTcl_DictObjDone\fR(\fIsearchPtr\fR)
.sp
int
\fBTcl_DictObjPutKeyList\fR(\fIinterp, dictPtr, keyc, keyv, valuePtr\fR)
.sp
int
\fBTcl_DictObjRemoveKeyList\fR(\fIinterp, dictPtr, keyc, keyv\fR)
.SH ARGUMENTS
.AS Tcl_DictSearch "**valuePtrPtr" out
.AP Tcl_Interp *interp in
If an error occurs while converting an object to be a dictionary object,
an error message is left in the interpreter's result object
unless \fIinterp\fR is NULL.
.AP Tcl_Obj *dictPtr in/out
Points to the dictionary object to be manipulated.
If \fIdictPtr\fR does not already point to a dictionary object,
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
\fBTcl_DictObjPutKeyList\fR.)
.AP Tcl_Obj **valuePtrPtr out
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 int *sizePtr out
Points to a variable that will have the number of key/value pairs
contained within the dictionary placed within it.
.AP Tcl_DictSearch *searchPtr in/out
Pointer to record to use to keep track of progress in enumerating all
key/value pairs in a dictionary. The contents of the record will be
initialized by the call to \fBTcl_DictObjFirst\fR. If the enumerating
is to be terminated before all values in the dictionary have been
returned, the search record \fImust\fR be passed to
\fBTcl_DictObjDone\fR to enable the internal locks to be released.
.AP int *donePtr out
Points to a variable that will have a non-zero value written into it
when the enumeration of the key/value pairs in a dictionary has
completed, and a zero otherwise.
.AP int keyc in
Indicates the number of keys that will be supplied in the \fIkeyv\fR
array.
.AP "Tcl_Obj *CONST" *keyv in
Array of \fIkeyc\fR pointers to objects that
\fBTcl_DictObjPutKeyList\fR and \fBTcl_DictObjRemoveKeyList\fR will
use to locate the key/value pair to manipulate within the
sub-dictionaries of the main dictionary object passed to them.
.BE
.SH DESCRIPTION
.PP
Tcl dictionary objects have an internal representation that supports
efficient mapping from keys to values and which does not guarantee any
particular ordering of keys within the dictionary.
The procedures described in this man page are used to
create, modify, index, and iterate over dictionary objects from C code.
.PP
\fBTcl_NewDictObj\fR creates a new, empty dictionary object. The
string representation of the object will be invalid, and the reference
count of the object will be zero.
.PP
\fBTcl_DictObjGet\fR looks up the given key within the given
dictionary and writes a pointer to the value associated with that key
into the variable pointed to by \fIvaluePtrPtr\fR, or a NULL if the
key has no mapping within the dictionary. The result of this
procedure is TCL_OK, or TCL_ERROR if the \fIdictPtr\fR cannot be
converted to a dictionary.
.PP
\fBTcl_DictObjPut\fR updates the given dictionary so that the given
key maps to the given value; any key may exist at most once in any
particular dictionary. The dictionary must not be shared, but the key
and value may be. This procedure may increase the reference count of
both key and value if it proves necessary to store them. Neither key
nor value should be NULL. The result of this procedure is TCL_OK, or
TCL_ERROR if the \fIdictPtr\fR cannot be converted to a dictionary.
.PP
\fBTcl_DictObjRemove\fR updates the given dictionary so that the given
key has no mapping to any value. The dictionary must not be shared,
but the key may be. The key actually stored in the dictionary will
have its reference count decremented if it was present. It is not an
error if the key did not previously exist. The result of this
procedure is TCL_OK, or TCL_ERROR if the \fIdictPtr\fR cannot be
converted to a dictionary.
.PP
\fBTcl_DictObjSize\fR updates the given variable with the number of
key/value pairs currently in the given dictionary. The result of this
procedure is TCL_OK, or TCL_ERROR if the \fIdictPtr\fR cannot be
converted to a dictionary.
.PP
\fBTcl_DictObjFirst\fR commences an iteration across all the key/value
pairs in the given dictionary, placing the key and value in the
variables pointed to by the \fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR
arguments (which may be NULL to indicate that the caller is
uninterested in they key or variable respectively.) The next
key/value pair in the dictionary may be retrieved with
\fBTcl_DictObjNext\fR. Concurrent updates of the dictionary's
internal representation will not modify the iteration processing
unless the dictionary is unshared, when this will trigger premature
termination of the iteration instead (which Tcl scripts cannot trigger
via the \fBdict\fR command.) The \fIsearchPtr\fR argument points to a
piece of context that is used to identify which particular iteration
is being performed, and is initialized by the call to
\fBTcl_DictObjFirst\fR. The \fIdonePtr\fR argument points to a
variable that is updated to be zero of there are further key/value
pairs to be iterated over, or non-zero if the iteration is complete.
The order of iteration is implementation-defined. If the
\fIdictPtr\fR argument cannot be converted to a dictionary,
\fBTcl_DictObjFirst\fR returns TCL_ERROR and the iteration is not
commenced, and otherwise it returns TCL_OK.
.PP
If the last call to \fBTcl_DictObjFirst\fR or \fBTcl_DictObjNext\fR
(for a particular \fIsearchPtr\fR) set the variable indicated by the
\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.
.PP
The procedures \fBTcl_DictObjPutKeyList\fR and
\fBTcl_DictObjRemoveKeyList\fR are the close analogues of
\fBTcl_DictObjPut\fR and \fBTcl_DictObjRemove\fR respectively, except
that instead of working with a single dictionary, they are designed to
operate on a nested tree of dictionaries, with inner dictionaries
stored as values inside outer dictionaries. The \fIkeyc\fR and
\fIkeyv\fR arguments specify a list of keys (with outermost keys
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)) {
/*
* 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, dictionary object, hash table, iteration, object
|
