hash : IndexToc

TEKlib / Hash module reference manual

By Timm S. Müller and Daniel Adler - Copyright © 2005 TEK neoscientists. All rights reserved.

Constructor Create a hash instance
THashPut Store a key/value pair
THashGet Retrieve a key/value pair
THashRemove Remove a key/value pair
THashValid Test if a hash is valid
THashFreeze Freeze hash

hash : ConstructorToc

CONSTRUCTOR
hash = TOpenModule("hash", version, tags)
TAPTR              TSTRPTR TUINT16  TTAGITEM*

FUNCTION
Create a hash instance, which can be used to store and retrieve a large number of items indexed by keys.
Hashes implement reasonable runtime behavior at the cost of some overhead for the maintenance of internal buckets. The number of buckets in a hash grows and shrinks on demand. Buckets group data according to a numerical hash value, which is a 32bit digest computed from the key according to a hash function.
The hash function for a 32bit numerical key can return the key itself, while for a string it is more likely some kind of checksum calculated over the key's character sequence. The hash module provides internal hashing and comparison functions for the most popular data types.

TAGS
THash_Type, (TUINT)
Type of keys to store in the hash. Valid types:
THASHTYPE_STRING
Store keys of type TSTRPTR
THASHTYPE_INT
Store keys of type TUINT
THASHTYPE_PTR
Store keys of type TAPTR
THASHTYPE_CUSTOM
Store keys of an user-specific type. This mode requires the tags THash_HashFunc and THash_CmpFunc to be supplied also.
Default: THASHTYPE_STRING
THash_HashFunc, (THASHFUNC)
Pointer to a function to generate a hash value from a key. The function must be declared as follows:
TCALLBACK TUINT hashfunc(TAPTR userdata, TTAG key)
This tag is mandatory if the hash type is THASHTYPE_CUSTOM. For any other type you are allowed to supply a hash function as well, which will override the internal default for the given THash_Type.
Default: an internal function suitable for generating hash values from keys of the specified type.
THash_CmpFunc, (TCMPFUNC)
Pointer to a function for the comparison of two hash keys. The function must be declared as follows:
TCALLBACK TINT cmpfunc(TAPTR userdata, TTAG key1, TTAG key2)
The return value must be TTRUE if the keys are equal, otherwise TFALSE.
This tag is mandatory if the hash type is THASHTYPE_CUSTOM. For any other type you are allowed to supply a comparison function as well, which will override the internal default.
Default: An internal comparison function suitable for comparing keys of the specified type.
THash_UserData
Userdata passed to user-supplied hash and comparison functions. Default: TNULL

RESULTS
hash hash instance, or TNULL if initialization failed

SEE ALSO


hash : THashPutToc

NAME
THashPut - store a key/value pair

SYNOPSIS
success = THashPut(hash, key, value)
TBOOL              TAPTR TTAG TTAG

FUNCTION
Store a key/value pair in a hash.
If the data cannot be stored in the hash (which is likely due to a lack of memory) then the return value is TFALSE and the hash falls into an 'invalid' state; it will furtheron reject attempts to store more data using THashPut. The 'invalid' state can be queried and reset using THashValid.

INPUTS
hash hash instance
key key (data or pointer)
value value to store in the hash

RESULTS
success boolean

NOTES
  • Existing keys will be overwritten. Use THashGet to check for the presence of a key.
  • If the hash is of the type THASHTYPE_INT then the key argument refers to the key itself, all other types are pointer references.

SEE ALSO


hash : THashGetToc

NAME
THashGet - retrieve the value associated with a key

SYNOPSIS
success = THashGet(hash, key, valuep)
TBOOL              TAPTR TTAG TAPTR

FUNCTION
Retrieve the value from a hash that is associated with a key. The return value indicates whether the key could be found.
If present, the value will be placed in the variable being pointed to by valuep. *valuep will be left untouched if the key cannot be found. If valuep is TNULL then only the presence of the key will be determined and returned to the caller.

INPUTS
hash hash instance
key key (data or pointer)
valuep pointer to a variable receiving the value, or TNULL

RESULTS
success boolean, TTRUE if the key was found

NOTES
  • If the hash is of the type THASHTYPE_INT then the key argument refers to the key itself, all other types are pointer references.

SEE ALSO


hash : THashRemoveToc

NAME
THashRemove - remove a key/value pair

SYNOPSIS
success = THashRemove(hash, key)
TBOOL                 TAPTR TTAG

FUNCTION
This function will lookup and remove the data item specified throughout the key. The return value indicates whether the key could be found.

INPUTS
hash hash instance
key key (data or pointer)

RESULTS
success boolean, indicating whether the key was removed

NOTES
  • If the hash is of the type THASHTYPE_INT then the key argument refers to the key itself, all other types are pointer references.

SEE ALSO


hash : THashValidToc

NAME
THashValid - test for integrity

SYNOPSIS
valid = THashValid(hash, reset)
TBOOL              TAPTR TBOOL

FUNCTION
This function queries the state of the hash and returns TTRUE if the hash is in 'valid' state, otherwise TFALSE. The reset argument, if TTRUE, allows to reset the state to 'valid'.

INPUTS
hash hash instance
reset reset the hash state to 'valid'

RESULTS
valid TFALSE if the hash was in 'invalid' state

SEE ALSO


hash : THashFreezeToc

NAME
THashFreeze - disallow changes of the number of buckets

SYNOPSIS
frozen = THashFreeze(hash, freeze)
TBOOL                TAPTR TBOOL

FUNCTION
This function allows to freeze and unfreeze a hash. A frozen hash does not recompute and try to update the number of buckets when new data is being added. This may result in a faster operation. Note, however, that the efficiency of the hash algorithm may suffer from an unbalanced number of buckets.

INPUTS
hash hash instance
freeze boolean; TTRUE to freeze, TFALSE to unfreeze

RESULTS
frozen previous 'frozen' state of the hash

SEE ALSO


hash : THashToListToc

NAME
THashToList - render a hash into a linked list [TODO]

SYNOPSIS
numnodes = THashToList(hash, listp)
TINT                   TAPTR struct THashNode **

FUNCTION
Render the contents of a hash into a singly-linked list. A pointer to the first node is placed in the variable being pointed to by listp.
If the operation succeeds then the list contains nodes of the type struct THashNode. It can be traversed until the next time a method is applied to the hash, as it will convert the list back to the hash's internal representation, thus rendering the list invalid.
If you unlink a node from the hash using teklib:TRemove then you might want to free it using THashFreeNode, so that its memory is getting returned to the hash's memory manager. Note, however, that all memory occupied by a hash is returned to the system anyway when the hash is being destroyed.

INPUTS
hash hash instance
listp ptr to a variable receiving a pointer to the first node

RESULTS
numnodes number of nodes inserted to the list

NOTES
  • Do not add nodes to the list.

SEE ALSO


hash : THashFreeNodeToc

NAME
THashFreeNode - free a hash node [TODO]

SYNOPSIS
THashFreeNode(hash, hashnode)
              TAPTR struct THashNode *

FUNCTION
Free a node that has been unlinked from a list generated with THashToList.

INPUTS
hash hash instance
hashnode pointer to a hash node to be freed

SEE ALSO


hash : ABOUTToc

SHORT
API documentation for the hash module

VERSION
$Id: hash.html,v 1.6 2005/07/03 13:16:53 tmueller Exp $

REVISION HISTORY
$Log: hash.html,v $ Revision 1.6 2005/07/03 13:16:53 tmueller key/value type changes to TTAG reflected Revision 1.4 2005/06/29 21:41:02 tmueller minor fixes
Revision 1.2 2005/06/28 21:55:53 tmueller reworked, rerendered


hash : Table of contents


Generated Sun Jul 3 15:15:44 2005 from hash.doc