RWTValHashDictionary(3C++) RWTValHashDictionary(3C++)
Name
RWTValHashDictionary<K,V> - Rogue Wave library class
Synopsis
#include <rw/tvhdict.h>
unsigned hashFun(const K&);
RWTValHashDictionary<K,V> dictionary(hashFun);
Please Note!
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.
Description
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&))..in -5
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
Page 1
RWTValHashDictionary(3C++) RWTValHashDictionary(3C++)
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.
Persistence
None
Example
#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
Public Constructors
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
Page 2
RWTValHashDictionary(3C++) RWTValHashDictionary(3C++)
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.
Public Operators
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.
Public Member Functions
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();
Page 3
RWTValHashDictionary(3C++) RWTValHashDictionary(3C++)
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;
Page 4
RWTValHashDictionary(3C++) RWTValHashDictionary(3C++)
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.
Page 5
