| Member Functions | |
| applyToKeyAndValue() clear() clearAndDestroy() contains() entries() find() findKeyAndValue() findValue() insertKeyAndValue() isEmpty() |
operator=() operator[]() remove() resize() |
#include <rw/tphdict.h> unsigned hashFun(const K&); RWTPtrHashDictionary<K,V> dictionary(hashFun);
If you do not have the Standard C++ Library, use the interface described here. Otherwise, use the interface to RWTPtrHashMap described in the Class Reference.
RWTPtrHashDictionary<K,V> is a dictionary of keys of type K and values of type V, implemented using a hash table. While duplicates of values are allowed, duplicates of keys are not.
It is a pointer based collection: pointers to the keys and values are copied in and out of the hash buckets.
Parameters K and V represent the type of the key and the type of the value, respectively, to be inserted into the table. These can be either classes or fundamental types. Class K must have
well-defined equality semantics (K::operator==(const K&)).
Class V can be of any type.
A user-supplied hashing function for type K must be supplied to the constructor when creating a new table. If K is a Rogue Wave class, then this requirement is usually trivial because most Rogue Wave objects know how to return a hashing value. In fact, classes RWCString, RWDate, RWTime, and RWWString contain static member functions called hash that can be supplied to the constructor as is. The function must have prototype:
unsigned hFun(const K& a);
and should return a suitable hash value for the object a.
To find a value, the key is first hashed to determine in which bucket the key and value can be found. The bucket is then searched for an object that is equal (as determined by the equality operator) to the key.
The initial number of buckets in the table is set by the constructor. There is a default value. If the number of (key/value) pairs in the collection greatly exceeds the number of buckets then efficiency will sag because each bucket must be searched linearly. The number of buckets can be changed by calling member function resize(). This is relatively expensive because all of the keys must be rehashed.
If you wish for this to be done automatically, then you can subclass from this class and implement your own special insert() and remove() functions which perform a resize() as necessary.
None
#include <rw/tphdict.h>
#include <rw/cstring.h>
#include <rw/rwdate.h>
#include <rw/rstream.h>
main() {
RWTPtrHashDictionary<RWCString, RWDate>
birthdays(RWCString::hash);
birthdays.insertKeyAndValue
(new RWCString("John"),
new RWDate(12, "April", 1975)
);
birthdays.insertKeyAndValue
(new RWCString("Ivan"),
new RWDate(2, "Nov", 1980)
);
// Alternative syntax:
birthdays[new RWCString("Susan")] =
new RWDate(30, "June", 1955);
birthdays[new RWCString("Gene")] =
new RWDate(5, "Jan", 1981);
// Print a birthday:
RWCString key("John");
cout << *birthdays[&key] << endl;
birthdays.clearAndDestroy();
return 0;
}
Program output:
April 12, 1975
RWTPtrHashDictionary<K,V>(unsigned (*hashKey)(const K&),
size_t buckets = RWDEFAULT_CAPACITY);
Constructs an empty hash dictionary. The first argument is a pointer to a user-defined hashing function for items of type K (the key). The table will initally have buckets buckets although this can be changed with member function resize().
RWTPtrHashDictionary<K,V>(const RWTPtrHashDictionary<K,V>& c);
Constructs a new hash dictionary as a shallow copy of c. After construction, pointers will be shared between the two collections. The new object will use the same hashing function and have the same number of buckets as c. Hence, the keys will not be rehashed.
RWTPtrHashDictionary<K,V>& operator=(const RWTPtrHashDictionary<K,V>& c);
Sets self to a shallow copy of c. Afterwards, pointers will be shared between the two collections. Self will use the same hashing function and have the number of buckets as c. Hence, the keys will not be rehashed.
V*& operator[](K* key);
Look up the key key and return a reference to the pointer of its associated value. If the key is not in the dictionary, then it is added to the dictionary. In this case, the pointer to the value will be undefined. Because of this, if there is a possibility that a key will not be in the dictionary, then this operator can only be used as an lvalue.
void applyToKeyAndValue( void (*applyFun)(K*,V*&,void*),void* d);
Applies the user-defined function pointed to by applyFun to every key-value pair in the dictionary. This function must have prototype:
void yourFun(K* key, V*& value, void* d);
This function will be called for each key value pair in the dictionary, with a pointer to the key as the first argument and a reference to a pointer to the value as the second argument. The key should not be changed or touched. A new value can be substituted, or the old value can be changed. Client data may be passed through as parameter d.
void clear();
Removes all key value pairs from the collection.
void clearAndDestroy();
Removes all key value pairs from the collection and deletes both the keys and the values. Do not use this method if multiple pointers to the same object are stored.
RWBoolean contains(const K* key) const;
Returns TRUE if the dictionary contains a key which is equal to the key pointed to by key. Returns FALSE otherwise. Equality is measured by the class-defined equality operator for type K.
size_t entries() const;
Returns the number of key-value pairs currently in the dictionary.
K* find(const K* key) const;
Returns a pointer to the key which is equal to the key pointed to by key, or nil if no such item could be found. Equality is measured by the class-defined equality operator for type K.
V* findValue(const K* key) const;
Returns a pointer to the value associated with the key pointed to by key, or nil if no such item could be found. Equality is measured by the class-defined equality operator for type K.
K* findKeyAndValue(const K* key, V*& retVal) const;
Returns a pointer to the key associated with the key pointed to by key, or nil if no such item could be found. If a key is found, the pointer to its associated value is put in retVal. Equality is measured by the class-defined equality operator for type K.
void insertKeyAndValue(K* key, V* value);
If the key pointed to by key is in the dictionary, then its associated value is changed to value. Otherwise, a new key value pair is inserted into the dictionary.
RWBoolean isEmpty() const;
Returns TRUE if the dictionary has no items in it, FALSE otherwise.
K* remove(const K* key);
Removes the key and value pair where the key is equal to the key pointed to by key. Returns the key or nil if no match was found. Equality is measured by the class-defined equality operator for type K.
void resize(size_t N);
Changes the number of buckets to N. This will result in all of the keys being rehashed.