hash : Index | Toc |
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 : Constructor | Toc |
hash = TOpenModule("hash", version, tags) TAPTR TSTRPTR TUINT16 TTAGITEM*
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.
THash_Type, (TUINT)Type of keys to store in the hash. Valid types:THASHTYPE_STRINGStore keys of type TSTRPTRTHASHTYPE_INTStore keys of type TUINTTHASHTYPE_PTRStore keys of type TAPTRTHASHTYPE_CUSTOMStore keys of an user-specific type. This mode requires the tags THash_HashFunc and THash_CmpFunc to be supplied also.Default: THASHTYPE_STRINGTHash_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_UserDataUserdata passed to user-supplied hash and comparison functions. Default: TNULL
hash hash instance, or TNULL if initialization failed
hash : THashPut | Toc |
THashPut - store a key/value pair
success = THashPut(hash, key, value) TBOOL TAPTR TTAG TTAG
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.
hash hash instance key key (data or pointer) value value to store in the hash
success boolean
- 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.
hash : THashGet | Toc |
THashGet - retrieve the value associated with a key
success = THashGet(hash, key, valuep) TBOOL TAPTR TTAG TAPTR
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.
hash hash instance key key (data or pointer) valuep pointer to a variable receiving the value, or TNULL
success boolean, TTRUE if the key was found
- If the hash is of the type THASHTYPE_INT then the key argument refers to the key itself, all other types are pointer references.
hash : THashRemove | Toc |
THashRemove - remove a key/value pair
success = THashRemove(hash, key) TBOOL TAPTR TTAG
This function will lookup and remove the data item specified throughout the key. The return value indicates whether the key could be found.
hash hash instance key key (data or pointer)
success boolean, indicating whether the key was removed
- If the hash is of the type THASHTYPE_INT then the key argument refers to the key itself, all other types are pointer references.
hash : THashValid | Toc |
THashValid - test for integrity
valid = THashValid(hash, reset) TBOOL TAPTR TBOOL
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'.
hash hash instance reset reset the hash state to 'valid'
valid TFALSE if the hash was in 'invalid' state
hash : THashFreeze | Toc |
THashFreeze - disallow changes of the number of buckets
frozen = THashFreeze(hash, freeze) TBOOL TAPTR TBOOL
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.
hash hash instance freeze boolean; TTRUE to freeze, TFALSE to unfreeze
frozen previous 'frozen' state of the hash
hash : THashToList | Toc |
THashToList - render a hash into a linked list [TODO]
numnodes = THashToList(hash, listp) TINT TAPTR struct THashNode **
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.
hash hash instance listp ptr to a variable receiving a pointer to the first node
numnodes number of nodes inserted to the list
- Do not add nodes to the list.
hash : THashFreeNode | Toc |
THashFreeNode - free a hash node [TODO]
THashFreeNode(hash, hashnode) TAPTR struct THashNode *
Free a node that has been unlinked from a list generated with THashToList.
hash hash instance hashnode pointer to a hash node to be freed
hash : ABOUT | Toc |
API documentation for the hash module
$Id: hash.html,v 1.6 2005/07/03 13:16:53 tmueller Exp $
$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 fixesRevision 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