diff options
Diffstat (limited to 'doc/Hash.3')
| -rw-r--r-- | doc/Hash.3 | 40 |
1 files changed, 26 insertions, 14 deletions
@@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Hash.3,v 1.23 2007/10/26 20:11:51 dgp Exp $ +'\" RCS: @(#) $Id: Hash.3,v 1.24 2007/10/28 14:17:39 dkf Exp $ '\" .so man.macros .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" @@ -88,7 +88,9 @@ STRUCTURE\fR below). All of the keys in a given table have the same form, which is specified when the table is initialized. .PP The value of a hash table entry can be anything that fits in the same -space as a ``char *'' pointer. Values for hash table entries are +space as a +.QW "char *" +pointer. Values for hash table entries are managed entirely by clients, not by the hash module itself. Typically each entry's value is a pointer to a data structure managed by client code. @@ -124,8 +126,10 @@ They are passed to hashing routines using the address of the first character of the string. .IP \fBTCL_ONE_WORD_KEYS\fR 25 Keys are single-word values; they are passed to hashing routines -and stored in hash table entries as ``char *'' values. -The pointer value is the key; it need not (and usually doesn't) +and stored in hash table entries as +.QW "char *" +values. +The pointer value is the key; it need not (and usually does not) actually point to a string. .IP \fBTCL_CUSTOM_TYPE_KEYS\fR 25 Keys are of arbitrary type, and are stored in the entry. Hashing @@ -140,7 +144,9 @@ structure is described in the section .IP \fIother\fR 25 If \fIkeyType\fR is not one of the above, then it must be an integer value greater than 1. -In this case the keys will be arrays of ``int'' values, where +In this case the keys will be arrays of +.QW int +values, where \fIkeyType\fR gives the number of ints in each key. This allows structures to be used as keys. All keys must have the same size. @@ -161,7 +167,7 @@ before deleting the table. .PP \fBTcl_CreateHashEntry\fR locates the entry corresponding to a particular key, creating a new entry in the table if there -wasn't already one with the given key. +was not already one with the given key. If an entry already existed with the given key then \fI*newPtr\fR is set to zero. If a new entry was created, then \fI*newPtr\fR is set to a non-zero @@ -177,28 +183,34 @@ the client is responsible for any cleanup associated with the entry's value, such as freeing a structure that it points to. .PP \fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR -except that it doesn't create a new entry if the key doesn't exist; +except that it does not create a new entry if the key doesn't exist; instead, it returns NULL as result. .PP \fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to read and write an entry's value, respectively. -Values are stored and retrieved as type ``ClientData'', which is +Values are stored and retrieved as type +.QW ClientData , +which is large enough to hold a pointer value. On almost all machines this is large enough to hold an integer value too. .PP \fBTcl_GetHashKey\fR returns the key for a given hash table entry, -either as a pointer to a string, a one-word (``char *'') key, or +either as a pointer to a string, a one-word +.PQ "char *" +key, or as a pointer to the first word of an array of integers, depending on the \fIkeyType\fR used to create a hash table. In all cases \fBTcl_GetHashKey\fR returns a result with type -``char *''. +.QW "char *" . When the key is a string or array, the result of \fBTcl_GetHashKey\fR points to information in the table entry; this information will remain valid until the entry is deleted or its table is deleted. .PP \fBTcl_FirstHashEntry\fR and \fBTcl_NextHashEntry\fR may be used to scan all of the entries in a hash table. -A structure of type ``Tcl_HashSearch'', provided by the client, +A structure of type +.QW Tcl_HashSearch , +provided by the client, is used to keep track of progress through the table. \fBTcl_FirstHashEntry\fR initializes the search record and returns the first entry in the table (or NULL if the table is @@ -253,9 +265,9 @@ to \fBTCL_HASH_KEY_TYPE_VERSION\fR. .PP The \fIflags\fR member is 0 or one or more of the following values OR'ed together: .IP \fBTCL_HASH_KEY_RANDOMIZE_HASH\fR 25 -There are some things, pointers for example which don't hash well +There are some things, pointers for example which do not hash well because they do not use the lower bits. If this flag is set then the -hash table will attempt to rectify this by randomizing the bits and +hash table will attempt to rectify this by randomizing the bits and then using the upper N bits as the index into the table. .IP \fBTCL_HASH_KEY_SYSTEM_HASH\fR 25 .VS 8.5 @@ -287,7 +299,7 @@ typedef int (Tcl_CompareHashKeysProc) ( Tcl_HashEntry *\fIhPtr\fR); .CE If this is NULL then the \fIkeyPtr\fR pointers are compared. -If the keys don't match then the function returns 0, otherwise +If the keys do not match then the function returns 0, otherwise it returns 1. .PP The \fIallocEntryProc\fR member contains the address of a function |