diff options
Diffstat (limited to 'doc/Hash.3')
| -rw-r--r-- | doc/Hash.3 | 131 |
1 files changed, 67 insertions, 64 deletions
@@ -5,10 +5,8 @@ '\" 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.24 2007/10/28 14:17:39 dkf Exp $ -'\" -.so man.macros .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" +.so man.macros .BS .SH NAME Tcl_InitHashTable, Tcl_InitCustomHashTable, Tcl_InitObjHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats \- procedures to manage hash tables @@ -37,7 +35,7 @@ ClientData .sp \fBTcl_SetHashValue\fR(\fIentryPtr, value\fR) .sp -char * +void * \fBTcl_GetHashKey\fR(\fItablePtr, entryPtr\fR) .sp Tcl_HashEntry * @@ -46,10 +44,10 @@ Tcl_HashEntry * Tcl_HashEntry * \fBTcl_NextHashEntry\fR(\fIsearchPtr\fR) .sp -const char * +char * \fBTcl_HashStats\fR(\fItablePtr\fR) .SH ARGUMENTS -.AS Tcl_HashKeyType *searchPtr out +.AS "const Tcl_HashKeyType" *searchPtr out .AP Tcl_HashTable *tablePtr in Address of hash table structure (for all procedures but \fBTcl_InitHashTable\fR, this must have been initialized by @@ -59,8 +57,8 @@ Kind of keys to use for new hash table. Must be either \fBTCL_STRING_KEYS\fR, \fBTCL_ONE_WORD_KEYS\fR, \fBTCL_CUSTOM_TYPE_KEYS\fR, \fBTCL_CUSTOM_PTR_KEYS\fR, or an integer value greater than 1. .AP Tcl_HashKeyType *typePtr in -Address of structure which defines the behaviour of the hash table. -.AP "const char" *key in +Address of structure which defines the behavior of the hash table. +.AP "const void" *key in Key to use for probe into table. Exact form depends on \fIkeyType\fR used to create table. .AP int *newPtr out @@ -83,8 +81,8 @@ very quickly locate the entry, and hence its value. There may be at most one entry in a hash table with a particular key, but many entries may have the same value. Keys can take one of four forms: strings, one-word values, integer arrays, or custom keys defined by a -Tcl_HashKeyType structure (See section \fBTHE TCL_HASHKEYTYPE -STRUCTURE\fR below). All of the keys in a given table have the same +Tcl_HashKeyType structure (See section \fBTHE TCL_HASHKEYTYPE 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 @@ -221,7 +219,7 @@ NULL if the end of the table has been reached. A call to \fBTcl_FirstHashEntry\fR followed by calls to \fBTcl_NextHashEntry\fR will return each of the entries in the table exactly once, in an arbitrary order. -It is unadvisable to modify the structure of the table, e.g. +It is inadvisable to modify the structure of the table, e.g. by creating or deleting entries, while the search is in progress, with the exception of deleting the entry returned by \fBTcl_FirstHashEntry\fR or \fBTcl_NextHashEntry\fR. @@ -243,10 +241,11 @@ to any of the fields of any of the hash-related data structures; use the procedures and macros defined here. .SH "THE TCL_HASHKEYTYPE STRUCTURE" .PP -Extension writers can define new hash key types by defining four -procedures, initializing a Tcl_HashKeyType structure to describe -the type, and calling \fBTcl_InitCustomHashTable\fR. -The \fBTcl_HashKeyType\fR structure is defined as follows: +Extension writers can define new hash key types by defining four procedures, +initializing a \fBTcl_HashKeyType\fR structure to describe the type, and +calling \fBTcl_InitCustomHashTable\fR. The \fBTcl_HashKeyType\fR structure is +defined as follows: +.PP .CS typedef struct Tcl_HashKeyType { int \fIversion\fR; @@ -255,77 +254,81 @@ typedef struct Tcl_HashKeyType { Tcl_CompareHashKeysProc *\fIcompareKeysProc\fR; Tcl_AllocHashEntryProc *\fIallocEntryProc\fR; Tcl_FreeHashEntryProc *\fIfreeEntryProc\fR; -} Tcl_HashKeyType; +} \fBTcl_HashKeyType\fR; .CE .PP -The \fIversion\fR member is the version of the table. If this -structure is extended in future then the version can be used -to distinguish between different structures. It should be set -to \fBTCL_HASH_KEY_TYPE_VERSION\fR. +The \fIversion\fR member is the version of the table. If this structure is +extended in future then the version can be used to distinguish between +different structures. It should be set 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: +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 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 -then using the upper N bits as the index into the table. +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 then using the upper N +bits as the index into the table. .IP \fBTCL_HASH_KEY_SYSTEM_HASH\fR 25 -.VS 8.5 -This flag forces Tcl to use the memory allocation -procedures provided by the operating system when allocating -and freeing memory used to store the hash table data structures, -and not any of Tcl's own customized memory allocation routines. -This is important if the hash table is to be used in the -implementation of a custom set of allocation routines, or something -that a custom set of allocation routines might depend on, in -order to avoid any circular dependency. -.VE 8.5 -.PP -The \fIhashKeyProc\fR member contains the address of a function -called to calculate a hash value for the key. +This flag forces Tcl to use the memory allocation procedures provided by the +operating system when allocating and freeing memory used to store the hash +table data structures, and not any of Tcl's own customized memory allocation +routines. This is important if the hash table is to be used in the +implementation of a custom set of allocation routines, or something that a +custom set of allocation routines might depend on, in order to avoid any +circular dependency. +.PP +The \fIhashKeyProc\fR member contains the address of a function called to +calculate a hash value for the key. +.PP .CS -typedef unsigned int (Tcl_HashKeyProc) ( +typedef unsigned int \fBTcl_HashKeyProc\fR( Tcl_HashTable *\fItablePtr\fR, void *\fIkeyPtr\fR); .CE -If this is NULL then \fIkeyPtr\fR is used and +.PP +If this is NULL then \fIkeyPtr\fR is used and \fBTCL_HASH_KEY_RANDOMIZE_HASH\fR is assumed. .PP -The \fIcompareKeysProc\fR member contains the address of a function -called to compare two keys. +The \fIcompareKeysProc\fR member contains the address of a function called to +compare two keys. +.PP .CS -typedef int (Tcl_CompareHashKeysProc) ( +typedef int \fBTcl_CompareHashKeysProc\fR( void *\fIkeyPtr\fR, Tcl_HashEntry *\fIhPtr\fR); .CE -If this is NULL then the \fIkeyPtr\fR pointers are compared. -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 -called to allocate space for an entry and initialize the key and clientData. +If this is NULL then the \fIkeyPtr\fR pointers are compared. 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 called to +allocate space for an entry and initialize the key and clientData. +.PP .CS -typedef Tcl_HashEntry *(Tcl_AllocHashEntryProc) ( +typedef Tcl_HashEntry *\fBTcl_AllocHashEntryProc\fR( Tcl_HashTable *\fItablePtr\fR, void *\fIkeyPtr\fR); .CE -If this is NULL then Tcl_Alloc is used to allocate enough space for a +.PP +If this is NULL then \fBTcl_Alloc\fR is used to allocate enough space for a Tcl_HashEntry, the key pointer is assigned to key.oneWordValue and the -cleintData is set to NULL. -String keys and array keys use this function to allocate enough -space for the entry and the key in one block, rather than doing -it in two blocks. This saves space for a pointer to the key from -the entry and another memory allocation. Tcl_Obj * keys use this -function to allocate enough space for an entry and increment the -reference count on the object. -.PP -The \fIfreeEntryProc\fR member contains the address of a function -called to free space for an entry. +clientData is set to NULL. String keys and array keys use this function to +allocate enough space for the entry and the key in one block, rather than +doing it in two blocks. This saves space for a pointer to the key from the +entry and another memory allocation. Tcl_Obj* keys use this function to +allocate enough space for an entry and increment the reference count on the +value. +.PP +The \fIfreeEntryProc\fR member contains the address of a function called to +free space for an entry. +.PP .CS -typedef void (Tcl_FreeHashEntryProc) (Tcl_HashEntry *\fIhPtr\fR); +typedef void \fBTcl_FreeHashEntryProc\fR( + Tcl_HashEntry *\fIhPtr\fR); .CE -If this is NULL then Tcl_Free is used to free the space for the -entry. Tcl_Obj * keys use this function to decrement the -reference count on the object. +.PP +If this is NULL then \fBTcl_Free\fR is used to free the space for the entry. +Tcl_Obj* keys use this function to decrement the reference count on the +value. .SH KEYWORDS hash table, key, lookup, search, value |