Provided by: tcl8.6-doc_8.6.5+dfsg-2_all 
NAME
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
SYNOPSIS
#include <tcl.h>
Tcl_Obj *
Tcl_NewDictObj()
int
Tcl_DictObjGet(interp, dictPtr, keyPtr, valuePtrPtr)
int
Tcl_DictObjPut(interp, dictPtr, keyPtr, valuePtr)
int
Tcl_DictObjRemove(interp, dictPtr, keyPtr)
int
Tcl_DictObjSize(interp, dictPtr, sizePtr)
int
Tcl_DictObjFirst(interp, dictPtr, searchPtr,
keyPtrPtr, valuePtrPtr, donePtr)
void
Tcl_DictObjNext(searchPtr, keyPtrPtr, valuePtrPtr, donePtr)
void
Tcl_DictObjDone(searchPtr)
int
Tcl_DictObjPutKeyList(interp, dictPtr, keyc, keyv, valuePtr)
int
Tcl_DictObjRemoveKeyList(interp, dictPtr, keyc, keyv)
ARGUMENTS
Tcl_Interp *interp (in) If an error occurs while converting a value to
be a dictionary value, an error message is left
in the interpreter's result value unless interp
is NULL.
Tcl_Obj *dictPtr (in/out) Points to the dictionary value to be
manipulated. If dictPtr does not already point
to a dictionary value, an attempt will be made
to convert it to one.
Tcl_Obj *keyPtr (in) Points to the key for the key/value pair being
manipulated within the dictionary value.
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.
Tcl_Obj *valuePtr (in) Points to the value for the key/value pair
being manipulated within the dictionary value
(or sub-value, in the case of
Tcl_DictObjPutKeyList.)
Tcl_Obj **valuePtrPtr (out) Points to a variable that will have the value
from a key/value pair placed within it. For
Tcl_DictObjFirst and Tcl_DictObjNext, this may
be NULL to indicate that the caller is not
interested in the value.
int *sizePtr (out) Points to a variable that will have the number
of key/value pairs contained within the
dictionary placed within it.
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 Tcl_DictObjFirst.
If the enumerating is to be terminated before
all values in the dictionary have been
returned, the search record must be passed to
Tcl_DictObjDone to enable the internal locks to
be released.
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.
int keyc (in) Indicates the number of keys that will be
supplied in the keyv array.
Tcl_Obj *const *keyv (in) Array of keyc pointers to values that
Tcl_DictObjPutKeyList and
Tcl_DictObjRemoveKeyList will use to locate the
key/value pair to manipulate within the sub-
dictionaries of the main dictionary value
passed to them.
_________________________________________________________________________________________________
DESCRIPTION
Tcl dictionary values have an internal representation that supports efficient mapping from
keys to values and which guarantees that the particular ordering of keys within the
dictionary remains the same modulo any keys being deleted (which removes them from the
order) or added (which adds them to the end of the order). If reinterpreted as a list, the
values at the even-valued indices in the list will be the keys of the dictionary, and each
will be followed (in the odd-valued index) by the value associated with that key.
The procedures described in this man page are used to create, modify, index, and iterate
over dictionary values from C code.
Tcl_NewDictObj creates a new, empty dictionary value. The string representation of the
value will be invalid, and the reference count of the value will be zero.
Tcl_DictObjGet 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 valuePtrPtr, 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 dictPtr cannot be converted to a dictionary.
Tcl_DictObjPut 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 dictPtr cannot be
converted to a dictionary.
Tcl_DictObjRemove 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 dictPtr cannot be converted to a dictionary.
Tcl_DictObjSize 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 dictPtr
cannot be converted to a dictionary.
Tcl_DictObjFirst 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 keyPtrPtr and
valuePtrPtr 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 Tcl_DictObjNext. 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 dict command.) The searchPtr 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 Tcl_DictObjFirst. The donePtr 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
dictPtr argument cannot be converted to a dictionary, Tcl_DictObjFirst returns TCL_ERROR
and the iteration is not commenced, and otherwise it returns TCL_OK.
When Tcl_DictObjFirst is called upon a dictionary, a lock is placed on the dictionary to
enable that dictionary to be iterated over safely without regard for whether the
dictionary is modified during the iteration. Because of this, once the iteration over a
dictionary's keys has finished (whether because all values have been iterated over as
indicated by the variable indicated by the donePtr argument being set to one, or because
no further values are required) the Tcl_DictObjDone function must be called with the same
searchPtr as was passed to Tcl_DictObjFirst so that the internal locks can be released.
Once a particular searchPtr is passed to Tcl_DictObjDone, passing it to Tcl_DictObjNext
(without first initializing it with Tcl_DictObjFirst) will result in no values being
produced and the variable pointed to by donePtr being set to one. It is safe to call
Tcl_DictObjDone multiple times on the same searchPtr for each call to Tcl_DictObjFirst.
The procedures Tcl_DictObjPutKeyList and Tcl_DictObjRemoveKeyList are the close analogues
of Tcl_DictObjPut and Tcl_DictObjRemove 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 keyc and keyv
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 Tcl_DictObjGet. With
Tcl_DictObjPutKeyList, nested dictionaries are created for non-terminal keys where they do
not already exist. With Tcl_DictObjRemoveKeyList, all non-terminal keys must exist and
have dictionaries as their values.
EXAMPLE
Using the dictionary iteration interface to search determine if there is a key that maps
to itself:
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. 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
* values and is just used here for demonstration
* purposes.
*/
if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) {
break;
}
}
Tcl_DictObjDone(&search);
Tcl_SetObjResult(interp, Tcl_NewBooleanObj(!done));
return TCL_OK;
SEE ALSO
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable
KEYWORDS
dict, dict value, dictionary, dictionary value, hash table, iteration, value