2 '\" Copyright (c) 2003 Donal K. Fellows
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH Tcl_DictObj 3 8.5 Tcl "Tcl Library Procedures"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
11 .\" .AP type name in/out ?indent?
12 .\" Start paragraph describing an argument to a library procedure.
13 .\" type is type of argument (int, etc.), in/out is either "in", "out",
14 .\" or "in/out" to describe whether procedure reads or modifies arg,
15 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 .\" needed; use .AS below instead)
19 .\" Give maximum sizes of arguments for setting tab stops. Type and
20 .\" name are examples of largest possible arguments that will be passed
21 .\" to .AP later. If args are omitted, default tab stops are used.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
36 .\" .VS ?version? ?br?
37 .\" Begin vertical sidebar, for use in marking newly-changed parts
38 .\" of man pages. The first argument is ignored and used for recording
39 .\" the version when the .VS was added, so that the sidebars can be
40 .\" found and removed when they reach a certain age. If another argument
41 .\" is present, then a line break is forced before starting the sidebar.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
59 .\" End of list of standard options for a Tk widget.
61 .\" .OP cmdName dbName dbClass
62 .\" Start of description of a specific option. cmdName gives the
63 .\" option's name as specified in the class command, dbName gives
64 .\" the option's name in the option database, and dbClass gives
65 .\" the option's class in the option database.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
276 '\" Note: do not modify the .SH NAME line immediately below!
278 Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList \- manipulate Tcl values as dictionaries
281 \fB#include <tcl.h>\fR
284 \fBTcl_NewDictObj\fR()
287 \fBTcl_DictObjGet\fR(\fIinterp, dictPtr, keyPtr, valuePtrPtr\fR)
290 \fBTcl_DictObjPut\fR(\fIinterp, dictPtr, keyPtr, valuePtr\fR)
293 \fBTcl_DictObjRemove\fR(\fIinterp, dictPtr, keyPtr\fR)
296 \fBTcl_DictObjSize\fR(\fIinterp, dictPtr, sizePtr\fR)
299 \fBTcl_DictObjFirst\fR(\fIinterp, dictPtr, searchPtr,
300 keyPtrPtr, valuePtrPtr, donePtr\fR)
303 \fBTcl_DictObjNext\fR(\fIsearchPtr, keyPtrPtr, valuePtrPtr, donePtr\fR)
306 \fBTcl_DictObjDone\fR(\fIsearchPtr\fR)
309 \fBTcl_DictObjPutKeyList\fR(\fIinterp, dictPtr, keyc, keyv, valuePtr\fR)
312 \fBTcl_DictObjRemoveKeyList\fR(\fIinterp, dictPtr, keyc, keyv\fR)
314 .AS Tcl_DictSearch "**valuePtrPtr" in/out
315 .AP Tcl_Interp *interp in
316 If an error occurs while converting a value to be a dictionary value,
317 an error message is left in the interpreter's result value
318 unless \fIinterp\fR is NULL.
319 .AP Tcl_Obj *dictPtr in/out
320 Points to the dictionary value to be manipulated.
321 If \fIdictPtr\fR does not already point to a dictionary value,
322 an attempt will be made to convert it to one.
323 .AP Tcl_Obj *keyPtr in
324 Points to the key for the key/value pair being manipulated within the
326 .AP Tcl_Obj **keyPtrPtr out
327 Points to a variable that will have the key from a key/value pair
328 placed within it. May be NULL to indicate that the caller is not
329 interested in the key.
330 .AP Tcl_Obj *valuePtr in
331 Points to the value for the key/value pair being manipulated within the
332 dictionary value (or sub-value, in the case of
333 \fBTcl_DictObjPutKeyList\fR.)
334 .AP Tcl_Obj **valuePtrPtr out
335 Points to a variable that will have the value from a key/value pair
336 placed within it. For \fBTcl_DictObjFirst\fR and
337 \fBTcl_DictObjNext\fR, this may be NULL to indicate that the caller is
338 not interested in the value.
340 Points to a variable that will have the number of key/value pairs
341 contained within the dictionary placed within it.
342 .AP Tcl_DictSearch *searchPtr in/out
343 Pointer to record to use to keep track of progress in enumerating all
344 key/value pairs in a dictionary. The contents of the record will be
345 initialized by the call to \fBTcl_DictObjFirst\fR. If the enumerating
346 is to be terminated before all values in the dictionary have been
347 returned, the search record \fImust\fR be passed to
348 \fBTcl_DictObjDone\fR to enable the internal locks to be released.
350 Points to a variable that will have a non-zero value written into it
351 when the enumeration of the key/value pairs in a dictionary has
352 completed, and a zero otherwise.
354 Indicates the number of keys that will be supplied in the \fIkeyv\fR
356 .AP "Tcl_Obj *const" *keyv in
357 Array of \fIkeyc\fR pointers to values that
358 \fBTcl_DictObjPutKeyList\fR and \fBTcl_DictObjRemoveKeyList\fR will
359 use to locate the key/value pair to manipulate within the
360 sub-dictionaries of the main dictionary value passed to them.
365 Tcl dictionary values have an internal representation that supports
366 efficient mapping from keys to values and which guarantees that the
367 particular ordering of keys within the dictionary remains the same
368 modulo any keys being deleted (which removes them from the order) or
369 added (which adds them to the end of the order). If reinterpreted as a
370 list, the values at the even-valued indices in the list will be the
371 keys of the dictionary, and each will be followed (in the odd-valued
372 index) by the value associated with that key.
374 The procedures described in this man page are used to
375 create, modify, index, and iterate over dictionary values from C code.
377 \fBTcl_NewDictObj\fR creates a new, empty dictionary value. The
378 string representation of the value will be invalid, and the reference
379 count of the value will be zero.
381 \fBTcl_DictObjGet\fR looks up the given key within the given
382 dictionary and writes a pointer to the value associated with that key
383 into the variable pointed to by \fIvaluePtrPtr\fR, or a NULL if the
384 key has no mapping within the dictionary. The result of this
385 procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be
386 converted to a dictionary.
388 \fBTcl_DictObjPut\fR updates the given dictionary so that the given
389 key maps to the given value; any key may exist at most once in any
390 particular dictionary. The dictionary must not be shared, but the key
391 and value may be. This procedure may increase the reference count of
392 both key and value if it proves necessary to store them. Neither key
393 nor value should be NULL. The result of this procedure is \fBTCL_OK\fR, or
394 \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be converted to a dictionary.
396 \fBTcl_DictObjRemove\fR updates the given dictionary so that the given
397 key has no mapping to any value. The dictionary must not be shared,
398 but the key may be. The key actually stored in the dictionary will
399 have its reference count decremented if it was present. It is not an
400 error if the key did not previously exist. The result of this
401 procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be
402 converted to a dictionary.
404 \fBTcl_DictObjSize\fR updates the given variable with the number of
405 key/value pairs currently in the given dictionary. The result of this
406 procedure is \fBTCL_OK\fR, or \fBTCL_ERROR\fR if the \fIdictPtr\fR cannot be
407 converted to a dictionary.
409 \fBTcl_DictObjFirst\fR commences an iteration across all the key/value
410 pairs in the given dictionary, placing the key and value in the
411 variables pointed to by the \fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR
412 arguments (which may be NULL to indicate that the caller is
413 uninterested in they key or variable respectively.) The next
414 key/value pair in the dictionary may be retrieved with
415 \fBTcl_DictObjNext\fR. Concurrent updates of the dictionary's
416 internal representation will not modify the iteration processing
417 unless the dictionary is unshared, when this will trigger premature
418 termination of the iteration instead (which Tcl scripts cannot trigger
419 via the \fBdict\fR command.) The \fIsearchPtr\fR argument points to a
420 piece of context that is used to identify which particular iteration
421 is being performed, and is initialized by the call to
422 \fBTcl_DictObjFirst\fR. The \fIdonePtr\fR argument points to a
423 variable that is updated to be zero of there are further key/value
424 pairs to be iterated over, or non-zero if the iteration is complete.
425 The order of iteration is implementation-defined. If the
426 \fIdictPtr\fR argument cannot be converted to a dictionary,
427 \fBTcl_DictObjFirst\fR returns \fBTCL_ERROR\fR and the iteration is not
428 commenced, and otherwise it returns \fBTCL_OK\fR.
430 When \fBTcl_DictObjFirst\fR is called upon a dictionary, a lock is placed on
431 the dictionary to enable that dictionary to be iterated over safely without
432 regard for whether the dictionary is modified during the iteration. Because of
433 this, once the iteration over a dictionary's keys has finished (whether
434 because all values have been iterated over as indicated by the variable
435 indicated by the \fIdonePtr\fR argument being set to one, or because no
436 further values are required) the \fBTcl_DictObjDone\fR function must be called
437 with the same \fIsearchPtr\fR as was passed to \fBTcl_DictObjFirst\fR so that
438 the internal locks can be released. Once a particular \fIsearchPtr\fR is
439 passed to \fBTcl_DictObjDone\fR, passing it to \fBTcl_DictObjNext\fR (without
440 first initializing it with \fBTcl_DictObjFirst\fR) will result in no values
441 being produced and the variable pointed to by \fIdonePtr\fR being set to one.
442 It is safe to call \fBTcl_DictObjDone\fR multiple times on the same
443 \fIsearchPtr\fR for each call to \fBTcl_DictObjFirst\fR.
445 The procedures \fBTcl_DictObjPutKeyList\fR and
446 \fBTcl_DictObjRemoveKeyList\fR are the close analogues of
447 \fBTcl_DictObjPut\fR and \fBTcl_DictObjRemove\fR respectively, except
448 that instead of working with a single dictionary, they are designed to
449 operate on a nested tree of dictionaries, with inner dictionaries
450 stored as values inside outer dictionaries. The \fIkeyc\fR and
451 \fIkeyv\fR arguments specify a list of keys (with outermost keys
452 first) that acts as a path to the key/value pair to be affected. Note
453 that there is no corresponding operation for reading a value for a
454 path as this is easy to construct from repeated use of
455 \fBTcl_DictObjGet\fR. With \fBTcl_DictObjPutKeyList\fR, nested
456 dictionaries are created for non-terminal keys where they do not
457 already exist. With \fBTcl_DictObjRemoveKeyList\fR, all non-terminal
458 keys must exist and have dictionaries as their values.
460 Using the dictionary iteration interface to search determine if there
461 is a key that maps to itself:
464 Tcl_DictSearch search;
465 Tcl_Obj *key, *value;
469 * Assume interp and objPtr are parameters. This is the
470 * idiomatic way to start an iteration over the dictionary; it
471 * sets a lock on the internal representation that ensures that
472 * there are no concurrent modification issues when normal
473 * reference count management is also used. The lock is
474 * released automatically when the loop is finished, but must
475 * be released manually when an exceptional exit from the loop
476 * is performed. However it is safe to try to release the lock
477 * even if we've finished iterating over the loop.
479 if (\fBTcl_DictObjFirst\fR(interp, objPtr, &search,
480 &key, &value, &done) != TCL_OK) {
483 for (; !done ; \fBTcl_DictObjNext\fR(&search, &key, &value, &done)) {
485 * Note that strcmp() is not a good way of comparing
486 * values and is just used here for demonstration
489 if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) {
493 \fBTcl_DictObjDone\fR(&search);
494 Tcl_SetObjResult(interp, Tcl_NewBooleanObj(!done));
498 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable
500 dict, dict value, dictionary, dictionary value, hash table, iteration, value
OSDN Git Service
