diff options
| -rw-r--r-- | doc/Hash.3 | 85 |
1 files changed, 41 insertions, 44 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.24 2007/10/28 14:17:39 dkf Exp $ +'\" RCS: @(#) $Id: Hash.3,v 1.25 2007/11/20 20:38:42 dkf Exp $ '\" .so man.macros .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" @@ -243,10 +243,10 @@ 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: .CS typedef struct Tcl_HashKeyType { int \fIversion\fR; @@ -258,52 +258,50 @@ typedef struct Tcl_HashKeyType { } Tcl_HashKeyType; .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. +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. +The \fIhashKeyProc\fR member contains the address of a function called to +calculate a hash value for the key. .CS typedef unsigned int (Tcl_HashKeyProc) ( Tcl_HashTable *\fItablePtr\fR, void *\fIkeyPtr\fR); .CE -If this is NULL then \fIkeyPtr\fR is used and +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. .CS typedef int (Tcl_CompareHashKeysProc) ( 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. +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. +The \fIallocEntryProc\fR member contains the address of a function called to +allocate space for an entry and initialize the key and clientData. .CS typedef Tcl_HashEntry *(Tcl_AllocHashEntryProc) ( Tcl_HashTable *\fItablePtr\fR, @@ -311,21 +309,20 @@ typedef Tcl_HashEntry *(Tcl_AllocHashEntryProc) ( .CE If this is NULL then Tcl_Alloc 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. +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 +object. .PP -The \fIfreeEntryProc\fR member contains the address of a function -called to free space for an entry. +The \fIfreeEntryProc\fR member contains the address of a function called to +free space for an entry. .CS typedef void (Tcl_FreeHashEntryProc) (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. +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. .SH KEYWORDS hash table, key, lookup, search, value |