diff options
Diffstat (limited to 'doc/DictObj.3')
| -rw-r--r-- | doc/DictObj.3 | 184 |
1 files changed, 184 insertions, 0 deletions
diff --git a/doc/DictObj.3 b/doc/DictObj.3 new file mode 100644 index 0000000..24f41dd --- /dev/null +++ b/doc/DictObj.3 @@ -0,0 +1,184 @@ +'\" +'\" 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.1 2003/04/05 01:03:20 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 *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 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. +.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 +initialised 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 dict objects have an internal representation that supports +efficient mapping from keys to values. +The procedures described in this man page are used to +create, modify, index, and iterate over Tcl dict 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 initialised 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. +.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. + +'\" TODO: Example of using Tcl_DictObj{First,Next,Done} + +.SH "SEE ALSO" +Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable + +.SH KEYWORDS +dict, dict object, dictionary, hash table, iteration, object + |