HASHTABLE__DEFINE

Class Name

HASHTABLE

Purpose

A hash table class which associates key strings with arbitrary values

Superclasses

None.
SUBCLASSES:
This class has no subclasses.
CREATION:
See HASHTABLE::INIT

Description

This is a hash table class. With this data structure, users
can associate arbitrary values (scalars, arrays, structures,
objects, etc) with a scalar string "key." The hash table is a
collection of (key,value) associations. Users may dynamically
add and remove entries.
Upon initialization, users may choose the size of the hash
table. This size should be larger than the expected number of
entries in the table. Regardless of the size of the table, an
essentially unlimited number of entries may be stored.
Duplicate keys may be allowed or disallowed, depending on the
NO_DUPLICATES keyword to the initialization method.

Methods

Intrinsic Methods
This class has the following methods:
HASHTABLE::CLEANUP removes an existing hash table object
HASHTABLE::INIT initializes a new hash table object
HASHTABLE::ADD adds a new entry to an existing hash table object
HASHTABLE::COUNT returns the number of entries in a hash table
HASHTABLE::REMOVE removes an entry from an existing hash table
HASHTABLE::ISCONTAINED is a KEYNAME contained within a hash table?
HASHTABLE::GET returns value associated with KEYNAME in hash table
HASHTABLE::KEYS returns all the keys in an existing hash table
HASHTABLE::STRUCT returns hash table, converted to a structure

Example

;; Create hash table object
ht = obj_new('hashtable')

;; Add some entries
ht->add, 'one', 1 ;; Add the scalar number 1
ht->add, 'two', [1,2] ;; Add a vector [1,2]
ht->add, 'struct', {alpha: 1, beta: 2} ;; Add a structure
ht->add, 'hash', obj_new('hashtable') ;; Add another hash table!
ht->add, 'one', 10 ;; Adding a duplicate entry!!
;; NOTE: if you do not wish to allow multiple entries with the
;; same key, then add entries like this:
ht->add, 'one', 10, /replace
;; in which case 10 would replace 1.
;; Number of entries stored
print, ht->count()
---> 5

;; Retreive some entries
print, ht->get('two')
---> [1,2]
;; How multiple entries are retrieved
print, ht->get('one', position=0) ;; Returns first entry of this key
---> 10
print, ht->get('one', position=1) ;; Returns second entry of this key
---> 1

;; Show number of keys in table
print, ht->keys()
---> ['two','one','one','struct', 'hash']
;; Destroy hash table
obj_destroy, ht

Modification History

Written and documented, Nov 2003, CM
Adjusted ::STRHASHVAL to accomodate possible overflow
exceptions, Apr 2004, CM
Enhanced ::STRHASHVAL to accept empty strings, 03 Jul 2006, CM
(thanks to William Dieckmann)
"Fixed" the empty-string problem yet again, 23 Oct 2006, CM
(thanks again to William Dieckmann)
Decrement COUNT variable after deleting keys, 09 Mar 2007, CM
Make ::REMOVE more efficient by using WHERE(COMPLEMENT=),
12 Jun 2007, CM
Change array notation to square brackets and enforce with
compiler option, 15 Jun 2007, CM
Add user-defined "null" value for missing elements,
15 Jun 2007, CM
Convert to [] array index notation, 20 Jun 2007, CM
Change the two WHERE's in ::REMOVE to a single WHERE
with COMPLEMENT, 20 Jun 2007, CM
Fix glaring bug in ::REMOVE when an entry still exists,
in a bucket, 27 Jun 2007, CM
Clean up the new NULL_VALUE pointer when destroying object,
(thanks to I. Zimine) 30 Jul 2007, CM
Fix case where user stores many identical keys (more than
LENGTH), 09 Aug 2007, CM
Add POSITION keyword to ::REMOVE, 12 Nov 2008, CM
Document the REPLACE keyword; correct COUNT() when replacing an
entry, 28 Jun 2009, CM
Add example documentation, 28 Jun 2009, CM