summaryrefslogtreecommitdiffstats
path: root/doc/Hash.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/Hash.3')
-rw-r--r--doc/Hash.340
1 files changed, 26 insertions, 14 deletions
diff --git a/doc/Hash.3 b/doc/Hash.3
index ba1be49..240b7a8 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.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