summaryrefslogtreecommitdiffstats
path: root/doc/Hash.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/Hash.3')
-rw-r--r--doc/Hash.385
1 files changed, 41 insertions, 44 deletions
diff --git a/doc/Hash.3 b/doc/Hash.3
index 240b7a8..3e53a3e 100644
--- a/doc/Hash.3
+++ b/doc/Hash.3
@@ -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