RWTPtrHashDictionary(3C++) RWTPtrHashDictionary(3C++)
Name
RWTPtrHashDictionary<K,V> - Rogue Wave library class
Synopsis
#include <rw/tphdict.h>
unsigned hashFun(const K&);
RWTPtrHashDictionary<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 RWTPtrHashMap described in the
Class Reference.
Description
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
Page 1
RWTPtrHashDictionary(3C++) RWTPtrHashDictionary(3C++)
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.
Persistence
None
Example
#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
Public Constructors
RWTPtrHashDictionary<K,V>(unsigned (*hashKey)(const K&),
size_t buckets = RWDEFAULT_CAPACITY);
Constructs an empty hash dictionary. The first argument is a pointer to
Page 2
RWTPtrHashDictionary(3C++) RWTPtrHashDictionary(3C++)
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.
Public Operators
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.
Public Member Functions
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.
Page 3
RWTPtrHashDictionary(3C++) RWTPtrHashDictionary(3C++)
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.
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.
Page 4
RWTPtrHashDictionary(3C++) RWTPtrHashDictionary(3C++)
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.
Page 5
