Click on the banner to return to the Class Reference home page.
Return to the Appendix home page.
©Copyright 1996 Rogue Wave Software
#include <rw/tvhdict.h>
unsigned hashFun(const K&); RWTValHashDictionary<K,V> dictionary(hashFun);
If you do not have the Standard C++ Library, use the interface described here. Otherwise, use the interface to RWTValHashMap described in the Class Reference.
RWTValHashDictionary<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 value based collection: 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. Classes K and V must have:
well-defined copy semantics (T::T(const T&) or equivalent);
well-defined assignment semantics (T::operator=(const T&) or equivalent).
In addition, class K must have
well-defined equality semantics (K::operator==(const K&)).
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 an expensive proposition because not only must all the items be copied into the new buckets, but all of the keys must be rehashed.
If you wish 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/tvhdict.h>
#include <rw/cstring.h>
#include <rw/rwdate.h>
#include <rw/rstream.h>
main() {
RWTValHashDictionary<RWCString, RWDate> birthdays(RWCString::hash);
birthdays.insertKeyAndValue(
"John",
RWDate(12, "April", 1975)
);
birthdays.insertKeyAndValue("Ivan", RWDate(2, "Nov", 1980));
// Alternative syntax:
birthdays["Susan"] = RWDate(30, "June", 1955);
birthdays["Gene"] = RWDate(5, "Jan", 1981);
// Print a birthday:
cout << birthdays["John"] << endl;
return 0;
}
Program output:
April 12, 1975
RWTValHashDictionary<K,V>(unsigned (*hashKey)(const K&),
size_t buckets = RWDEFAULT_CAPACITY);
Constructs a new 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().
RWTValHashDictionary<K,V>(const RWTValHashDictionary<K,V>&
dict);
Copy constructor. Constructs a new hash dictionary as a copy of dict. The new dictionary will have the same number of buckets as the old table. Hence, although the keys and values must be copied into the new table, the keys will not be rehashed.
RWTValHashDictionary<K,V>& operator=(const RWTValHashDictionary<K,V>& dict);
Sets self to a copy of dict. Afterwards, the new table will have the same number of buckets as the old table. Hence, although the keys and values must be copied into the new table, the keys will not be rehashed.
V& operator[](const K& key);
Look up the key key and return its associated value as an lvalue reference. If the key is not in the dictionary, then it is added to the dictionary. In this case, the value associated with the key will be provided by the default constructor for objects of type V.
void
applyToKeyAndValue(void (*applyFun)(const 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(const K& key, V& value, void* d);
The key will be passed by constant reference and hence cannot be changed. The value will be passed by reference and can be modified. Client data may be passed through as parameter d.
void clear();
Removes all items from the collection.
RWBoolean contains(const K& key) const;
Returns TRUE if the dictionary contains a key which is equal to key. Returns FALSE otherwise. Equality is measured by the class-defined equality operator for class K.
size_t entries() const;
Returns the number of key-value pairs currently in the dictionary.
RWBoolean find(const K& target, K& retKey) const;
Returns TRUE if the dictionary contains a key which is equal to target and puts the matching key into retKey. Returns FALSE otherwise and leaves retKey untouched. Equality is measured by the class-defined equality operator for class K.
RWBoolean findValue(const K& key, V& retVal) const;
Returns TRUE if the dictionary contains a key which is equal to key and puts the associated value into retVal. Returns FALSE otherwise and leaves retVal untouched. Equality is measured by the class-defined equality operator for class K.
RWBoolean findKeyAndValue(const K& key, K& retKey,V& retVal) const;
Returns TRUE if the dictionary contains a key which is equal to key and puts the matching key into retKey and the associated value into retVal. Returns FALSE otherwise and leaves retKey and retVal untouched. Equality is measured by the class-defined equality operator for class K.
void insertKeyAndValue(const K& key, const V& value);
Inserts the key key and value value into the dictionary.
RWBoolean isEmpty() const;
Returns TRUE if the dictionary has no items in it, FALSE otherwise.
RWBoolean remove(const K& key);
Returns TRUE and removes the (key/value) pair where the key is equal to the key. Returns FALSE if there is no such key. Equality is measured by the class-defined equality operator for class K.
void resize(size_t N);
Changes the number of buckets to N, a relatively expensive operation if there are many items in the collection.
