Tcl_InitCustomHashTable man page on OpenServer

Man page or keyword search:  
man Server   5388 pages
apropos Keyword Search (all sections)
Output format
OpenServer logo
[printable version]

Tcl_Hash(3)		    Tcl Library Procedures		   Tcl_Hash(3)

______________________________________________________________________________

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

SYNOPSIS
       #include <tcl.h>

       Tcl_InitHashTable(tablePtr, keyType)

       Tcl_InitCustomHashTable(tablePtr, keyType, typePtr)

       Tcl_InitObjHashTable(tablePtr)

       Tcl_DeleteHashTable(tablePtr)

       Tcl_HashEntry *
       Tcl_CreateHashEntry(tablePtr, key, newPtr)

       Tcl_DeleteHashEntry(entryPtr)

       Tcl_HashEntry *
       Tcl_FindHashEntry(tablePtr, key)

       ClientData
       Tcl_GetHashValue(entryPtr)

       Tcl_SetHashValue(entryPtr, value)

       char *
       Tcl_GetHashKey(tablePtr, entryPtr)

       Tcl_HashEntry *
       Tcl_FirstHashEntry(tablePtr, searchPtr)

       Tcl_HashEntry *
       Tcl_NextHashEntry(searchPtr)

       CONST char *
       Tcl_HashStats(tablePtr)

ARGUMENTS
       Tcl_HashTable	*tablePtr    (in)      Address of hash table structure
					       (for   all    procedures	   but
					       Tcl_InitHashTable,   this  must
					       have been initialized by previ-
					       ous call to Tcl_InitHashTable).

       int		keyType	     (in)      Kind of keys  to	 use  for  new
					       hash  table.   Must  be	either
					       TCL_STRING_KEYS,
					       TCL_ONE_WORD_KEYS,     TCL_CUS-
					       TOM_TYPE_KEYS,	      TCL_CUS-
					       TOM_PTR_KEYS,   or  an  integer
					       value greater than 1.

       Tcl_HashKeyType	*typePtr     (in)      Address	of   structure	 which
					       defines	the  behaviour	of the
					       hash table.

       CONST char	*key	     (in)      Key to use for probe  into  ta-
					       ble.   Exact  form  depends  on
					       keyType used to create table.

       int		*newPtr	     (out)     The word at *newPtr is set to 1
					       if  a new entry was created and
					       0 if there was already an entry
					       for key.

       Tcl_HashEntry	*entryPtr    (in)      Pointer to hash table entry.

       ClientData	value	     (in)      New value to assign to hash ta-
					       ble entry.  Need not have  type
					       ClientData,  but	 must  fit  in
					       same space as ClientData.

       Tcl_HashSearch	*searchPtr   (in)      Pointer to  record  to  use  to
					       keep  track of progress in enu-
					       merating all the entries	 in  a
					       hash table.
_________________________________________________________________

DESCRIPTION
       A hash table consists of zero or more entries, each consisting of a key
       and a value.  Given the key for an entry, the hashing routines can 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 THE TCL_HASHKEYTYPE STRUCTURE below). All of the
       keys in a given table have the same form, which is specified  when  the
       table is initialized.

       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  man-
       aged  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.

       Hash tables grow gracefully as the number of entries increases, so that
       there are always less than three entries per hash bucket,  on  average.
       This  allows  for fast lookups regardless of the number of entries in a
       table.

       The core provides  three	 functions  for	 the  initialization  of  hash
       tables,	 Tcl_InitHashTable,   Tcl_InitObjHashTable   and  Tcl_InitCus-
       tomHashTable.

       Tcl_InitHashTable initializes a structure that describes a new hash ta-
       ble.  The space for the structure is provided by the caller, not by the
       hash module.  The value of keyType indicates what kinds of keys will be
       used for all entries in the table. All of the key types described later
       are allowed, with the exception of  TCL_CUSTOM_TYPE_KEYS	 and  TCL_CUS-
       TOM_PTR_KEYS.

       Tcl_InitObjHashTable  is	 a  wrapper around Tcl_InitCustomHashTable and
       initializes a hash table whose keys are Tcl_Obj *.

       Tcl_InitCustomHashTable initializes a structure that  describes	a  new
       hash  table. The space for the structure is provided by the caller, not
       by the hash module.  The value of keyType indicates what kinds of  keys
       will  be	 used  for all entries in the table.  KeyType must have one of
       the following values:

       TCL_STRING_KEYS		Keys are null-terminated  strings.   They  are
				passed	to  hashing routines using the address
				of the first character of the string.

       TCL_ONE_WORD_KEYS	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) actually point to a string.

       TCL_CUSTOM_TYPE_KEYS	Keys are of arbitrary type, and are stored  in
				the  entry.  Hashing  and comparison is deter-
				mined by typePtr. The  Tcl_HashKeyType	struc-
				ture   is   described	in   the  section  THE
				TCL_HASHKEYTYPE STRUCTURE below.

       TCL_CUSTOM_PTR_KEYS	Keys are pointers to an	 arbitrary  type,  and
				are  stored in the entry. Hashing and compari-
				son is determined by typePtr. The Tcl_HashKey-
				Type structure is described in the section THE
				TCL_HASHKEYTYPE STRUCTURE below.

       other			If keyType 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 keyType 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 of the first int
				in the array.

       Tcl_DeleteHashTable deletes all of the entries  in  a  hash  table  and
       frees  up  the  memory  associated  with	 the  table's bucket array and
       entries.	 It does not free the actual table structure  (pointed	to  by
       tablePtr),  since  that	memory is assumed to be managed by the client.
       Tcl_DeleteHashTable also does not free or otherwise manipulate the val-
       ues  of	the  hash table entries.  If the entry values point to dynami-
       cally-allocated memory, then it is the client's responsibility to  free
       these structures before deleting the table.

       Tcl_CreateHashEntry  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.	  If  an entry already existed with the given key then
       *newPtr is set to zero.	If a new entry was created,  then  *newPtr  is
       set  to	a non-zero value and the value of the new entry will be set to
       zero.  The return value from Tcl_CreateHashEntry is a  pointer  to  the
       entry, which may be used to retrieve and modify the entry's value or to
       delete the entry from the table.

       Tcl_DeleteHashEntry will remove an existing entry from  a  table.   The
       memory  associated  with the entry itself will be freed, but the client
       is responsible for any cleanup associated with the entry's value,  such
       as freeing a structure that it points to.

       Tcl_FindHashEntry  is  similar  to  Tcl_CreateHashEntry	except that it
       doesn't create a new entry  if  the  key	 doesn't  exist;  instead,  it
       returns NULL as result.

       Tcl_GetHashValue	 and  Tcl_SetHashValue	are  used to read and write an
       entry's value, respectively.  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.

       Tcl_GetHashKey  returns the key for a given hash table entry, 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 keyType used
       to create a hash table.	In all cases Tcl_GetHashKey returns  a	result
       with type ``char *''.  When the key is a string or array, the result of
       Tcl_GetHashKey points to information in the table entry;	 this informa-
       tion  will  remain  valid  until	 the  entry is deleted or its table is
       deleted.

       Tcl_FirstHashEntry and Tcl_NextHashEntry may be used to scan all of the
       entries	in a hash table.  A structure of type ``Tcl_HashSearch'', pro-
       vided by the client, is used to keep track of progress through the  ta-
       ble.   Tcl_FirstHashEntry initializes the search record and returns the
       first entry in the table (or NULL if the table is empty).  Each	subse-
       quent  call to Tcl_NextHashEntry returns the next entry in the table or
       NULL  if	 the  end  of  the  table  has	been  reached.	 A   call   to
       Tcl_FirstHashEntry  followed  by calls to Tcl_NextHashEntry 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.  by creat-
       ing or deleting entries, while the search is in progress.

       Tcl_HashStats  returns  a  dynamically-allocated	 string	 with  overall
       information  about  a hash table, such as the number of entries it con-
       tains, the number of buckets in its hash array, and the utilization  of
       the  buckets.   It  is  the  caller's responsibility to free the result
       string by passing it to ckfree.

       The header file tcl.h defines the actual data structures used to imple-
       ment  hash  tables.   This  is  necessary  so that clients can allocate
       Tcl_HashTable structures and so that macros can be  used	 to  read  and
       write  the  values  of entries.	However, users of the hashing routines
       should never refer directly to any of the fields of any	of  the	 hash-
       related data structures; use the procedures and macros defined here.

THE TCL_HASHKEYTYPE STRUCTURE
       Extension writers can define new hash key types by defining four proce-
       dures, initializing a Tcl_HashKeyType structure to describe  the	 type,
       and  calling Tcl_InitCustomHashTable.  The Tcl_HashKeyType structure is
       defined as follows:
	      typedef struct Tcl_HashKeyType {
		  int version;
		  int flags;
		  Tcl_HashKeyProc *hashKeyProc;
		  Tcl_CompareHashKeysProc *compareKeysProc;
		  Tcl_AllocHashEntryProc *allocEntryProc;
		  Tcl_FreeHashEntryProc *freeEntryProc;
	      } Tcl_HashKeyType;

       The version 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 TCL_HASH_KEY_TYPE_VERSION.

       The flags member is one or more of the following values OR'ed together:

       TCL_HASH_KEY_RANDOMIZE_HASH
				There  are  some  things, pointers for example
				which don't 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
				randomising  the bits and then using the upper
				N bits as the index into the table.

       The hashKeyProc member contains the address of  a  function  called  to
       calculate a hash value for the key.
	      typedef unsigned int (Tcl_HashKeyProc) (
		  Tcl_HashTable *tablePtr,
		  VOID *keyPtr);
       If  this is NULL then keyPtr is used and TCL_HASH_KEY_RANDOMIZE_HASH is
       assumed.

       The compareKeysProc member contains the address of a function called to
       compare two keys.
	      typedef int (Tcl_CompareHashKeysProc) (VOID *keyPtr,
		  Tcl_HashEntry *hPtr);
       If  this	 is  NULL  then the keyPtr pointers are compared.  If the keys
       don't match then the function returns 0, otherwise it returns 1.

       The allocEntryProc member contains the address of a function called  to
       allocate space for an entry and initialise the key.
	      typedef Tcl_HashEntry *(Tcl_AllocHashEntryProc) (
		  Tcl_HashTable *tablePtr, VOID *keyPtr);
       If  this	 is NULL then Tcl_Alloc is used to allocate enough space for a
       Tcl_HashEntry and the key  pointer  is  assigned	 to  key.oneWordValue.
       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.	If

       The freeEntryProc member contains the address of a function  called  to
       free space for an entry.
	      typedef void (Tcl_FreeHashEntryProc) (Tcl_HashEntry *hPtr);
       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.

KEYWORDS
       hash table, key, lookup, search, value

Tcl								   Tcl_Hash(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OpenServer

List of man pages available for OpenServer

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net