diff options
Diffstat (limited to 'doc/DictObj.3')
| -rw-r--r-- | doc/DictObj.3 | 103 |
1 files changed, 18 insertions, 85 deletions
diff --git a/doc/DictObj.3 b/doc/DictObj.3 index 0b4c1ca..badba69 100644 --- a/doc/DictObj.3 +++ b/doc/DictObj.3 @@ -3,13 +3,13 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tcl_DictObj 3 8.5 Tcl "Tcl Library Procedures" .so man.macros .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 values as dictionaries +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 @@ -47,23 +47,23 @@ int .SH ARGUMENTS .AS Tcl_DictSearch "**valuePtrPtr" in/out .AP 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 +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 value to be manipulated. -If \fIdictPtr\fR does not already point to a dictionary value, +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 value. +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 manipulated within the -dictionary value (or sub-value, in the case of +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 @@ -88,15 +88,15 @@ completed, and a zero otherwise. 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 values that +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 value passed to them. +sub-dictionaries of the main dictionary object passed to them. .BE .SH DESCRIPTION .PP -Tcl dictionary values have an internal representation that supports +Tcl dictionary objects 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 @@ -106,11 +106,11 @@ keys of the dictionary, and each will be followed (in the odd-valued index) by the value associated with that key. .PP The procedures described in this man page are used to -create, modify, index, and iterate over dictionary values from C code. +create, modify, index, and iterate over dictionary objects from C code. .PP -\fBTcl_NewDictObj\fR 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. +\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 @@ -190,73 +190,6 @@ path as this is easy to construct from repeated use of dictionaries are created for non-terminal keys where they do not already exist. With \fBTcl_DictObjRemoveKeyList\fR, all non-terminal keys must exist and have dictionaries as their values. -.SH "REFERENCE COUNT MANAGEMENT" -.PP -\fBTcl_NewDictObj\fR always returns a zero-reference object, much like -\fBTcl_NewObj\fR. -.PP -\fBTcl_DictObjPut\fR does not modify the reference count of its \fIdictPtr\fR -argument, but does require that the object be unshared. If -\fBTcl_DictObjPut\fR returns \fBTCL_ERROR\fR it does not manipulate any -reference counts; but if it returns \fBTCL_OK\fR then it definitely increments -the reference count of \fIvaluePtr\fR and may increment the reference count of -\fIkeyPtr\fR; the latter case happens exactly when the key did not previously -exist in the dictionary. Note however that this function may set the -interpreter result; if that is the only place that is holding a reference to -an object, it will be deleted. -.PP -\fBTcl_DictObjGet\fR only reads from its \fIdictPtr\fR and \fIkeyPtr\fR -arguments, and does not manipulate their reference counts at all. If the -\fIvaluePtrPtr\fR argument is not set to NULL (and the function doesn't return -\fBTCL_ERROR\fR), it will be set to a value with a reference count of at least -1, with a reference owned by the dictionary. Note however that this function -may set the interpreter result; if that is the only place that is holding a -reference to an object, it will be deleted. -.PP -\fBTcl_DictObjRemove\fR does not modify the reference count of its -\fIdictPtr\fR argument, but does require that the object be unshared. It does -not manipulate the reference count of its \fIkeyPtr\fR argument at all. Note -however that this function may set the interpreter result; if that is the only -place that is holding a reference to an object, it will be deleted. -.PP -\fBTcl_DictObjSize\fR does not modify the reference count of its \fIdictPtr\fR -argument; it only reads. Note however that this function may set the -interpreter result; if that is the only place that is holding a reference to -the dictionary object, it will be deleted. -.PP -\fBTcl_DictObjFirst\fR does not modify the reference count of its -\fIdictPtr\fR argument; it only reads. The variables given by the -\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated -to contain references to the relevant values in the dictionary; their -reference counts will be at least 1 (due to the dictionary holding a reference -to them). It may also manipulate internal references; these are not exposed to -user code, but require a matching \fBTcl_DictObjDone\fR call. Note however -that this function may set the interpreter result; if that is the only place -that is holding a reference to the dictionary object, it will be deleted. -.PP -Similarly for \fBTcl_DictObjNext\fR; the variables given by the -\fIkeyPtrPtr\fR and \fIvaluePtrPtr\fR arguments (if not NULL) will be updated -to contain references to the relevant values in the dictionary; their -reference counts will be at least 1 (due to the dictionary holding a reference -to them). -.PP -\fBTcl_DictObjDone\fR does not manipulate (user-visible) reference counts. -.PP -\fBTcl_DictObjPutKeyList\fR is similar to \fBTcl_DictObjPut\fR; it does not -modify the reference count of its \fIdictPtr\fR argument, but does require -that the object be unshared. It may increment the reference count of any value -passed in the \fIkeyv\fR argument, and will increment the reference count of -the \fIvaluePtr\fR argument on success. It is recommended that values passed -via \fIkeyv\fR and \fIvaluePtr\fR do not have zero reference counts. Note -however that this function may set the interpreter result; if that is the only -place that is holding a reference to an object, it will be deleted. -.PP -\fBTcl_DictObjRemoveKeyList\fR is similar to \fBTcl_DictObjRemove\fR; it does -not modify the reference count of its \fIdictPtr\fR argument, but does require -that the object be unshared, and does not modify the reference counts of any -of the values passed in the \fIkeyv\fR argument. Note however that this -function may set the interpreter result; if that is the only place that is -holding a reference to an object, it will be deleted. .SH EXAMPLE Using the dictionary iteration interface to search determine if there is a key that maps to itself: @@ -284,7 +217,7 @@ if (\fBTcl_DictObjFirst\fR(interp, objPtr, &search, for (; !done ; \fBTcl_DictObjNext\fR(&search, &key, &value, &done)) { /* * Note that strcmp() is not a good way of comparing - * values and is just used here for demonstration + * objects and is just used here for demonstration * purposes. */ if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) { @@ -298,4 +231,4 @@ return TCL_OK; .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable .SH KEYWORDS -dict, dict value, dictionary, dictionary value, hash table, iteration, value +dict, dict object, dictionary, dictionary object, hash table, iteration, object |