diff options
author | dgp <dgp@users.sourceforge.net> | 2007-10-26 20:11:50 (GMT) |
---|---|---|
committer | dgp <dgp@users.sourceforge.net> | 2007-10-26 20:11:50 (GMT) |
commit | 6b9dd216db20bac6c76552a6193d67a01e1d34ee (patch) | |
tree | b86166558de62f70eef1a7524fac75f7b47a4f44 /doc/Hash.3 | |
parent | 236c395276f8f1cf4d5b745ea490b4966e6eb148 (diff) | |
download | tcl-6b9dd216db20bac6c76552a6193d67a01e1d34ee.zip tcl-6b9dd216db20bac6c76552a6193d67a01e1d34ee.tar.gz tcl-6b9dd216db20bac6c76552a6193d67a01e1d34ee.tar.bz2 |
* changes: Updated for 8.5b2 release.core_8_5_b2
* doc/*.1: Revert doc changes that broke
* doc/*.3: `make html` so we can get the release
* doc/*.n: out the door.
Diffstat (limited to 'doc/Hash.3')
-rw-r--r-- | doc/Hash.3 | 34 |
1 files changed, 13 insertions, 21 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.22 2007/10/24 14:29:38 dkf Exp $ +'\" RCS: @(#) $Id: Hash.3,v 1.23 2007/10/26 20:11:51 dgp Exp $ '\" .so man.macros .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures" @@ -88,9 +88,7 @@ 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 -.QW "char *" -pointer. Values for hash table entries are +space as a ``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. @@ -126,9 +124,7 @@ 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 -.QW "char *" -values. +and stored in hash table entries as ``char *'' values. The pointer value is the key; it need not (and usually doesn't) actually point to a string. .IP \fBTCL_CUSTOM_TYPE_KEYS\fR 25 @@ -144,9 +140,8 @@ 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 -.QW int -values, where \fIkeyType\fR gives the number of ints in each key. +In this case the keys will be arrays of ``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. Array keys are passed into hashing functions using the address @@ -187,28 +182,25 @@ 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 -.QW ClientData , -which is +Values are stored and retrieved as type ``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 (e.g. -.QW "char *" ) -key, or as a pointer to the first word of an array of integers, depending +either as a pointer to a string, a one-word (``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 -.QW "char *" . +``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 -.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 +to scan all of the entries in a hash table. +A structure of type ``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 empty). Each subsequent call to \fBTcl_NextHashEntry\fR returns the |