Contents Up Previous Next

wxHashMap

This is a simple, type-safe, and reasonably efficient hash map class, whose interface is a subset of the interface of STL containers. In particular, the interface is modelled after std::map, and the various, non standard, std::hash_map.

Example

    class MyClass { /* ... */ };

    // declare a hash map with string keys and int values
    WX_DECLARE_STRING_HASH_MAP( int, MyHash5 );
    // same, with int keys and MyClass* values
    WX_DECLARE_HASH_MAP( int, MyClass*, wxIntegerHash, wxIntegerEqual, MyHash1 );
    // same, with wxString keys and int values
    WX_DECLARE_STRING_HASH_MAP( int, MyHash3 );
    // same, with wxString keys and values
    WX_DECLARE_STRING_HASH_MAP( wxString, MyHash2 );

    MyHash1 h1;
    MyHash2 h2;

    // store and retrieve values
    h1[1] = new MyClass( 1 );
    h1[10000000] = NULL;
    h1[50000] = new MyClass( 2 );
    h2["Bill"] = "ABC";
    wxString tmp = h2["Bill"];
    // since element with key "Joe" is not present, this will return
    // the default value, which is an empty string in the case of wxString
    MyClass tmp2 = h2["Joe"];

    // iterate over all the elements in the class
    MyHash2::iterator it;
    for( it = h2.begin(); it != h2.end(); ++it )
    {
        wxString key = it->first, value = it->second;
        // do something useful with key and value
    }
Declaring new hash table types

    WX_DECLARE_STRING_HASH_MAP( VALUE_T,     // type of the values
                                CLASSNAME ); // name of the class
Declares an hash map class named CLASSNAME, with wxString keys and VALUE_T values.

    WX_DECLARE_VOIDPTR_HASH_MAP( VALUE_T,     // type of the values
                                 CLASSNAME ); // name of the class
Declares an hash map class named CLASSNAME, with void* keys and VALUE_T values.

    WX_DECLARE_HASH_MAP( KEY_T,      // type of the keys
                         VALUE_T,    // type of the values
                         HASH_T,     // hasher
                         KEY_EQ_T,   // key equality predicate
                         CLASSNAME); // name of the class
The HASH_T and KEY_EQ_T are the types used for the hashing function and key comparison. wxWidgets provides three predefined hashing functions: wxIntegerHash for integer types ( int, long, short, and their unsigned counterparts ), wxStringHash for strings ( wxString, wxChar*, char* ), and wxPointerHash for any kind of pointer. Similarly three equality predicates: wxIntegerEqual, wxStringEqual, wxPointerEqual are provided.

Using this you could declare an hash map mapping int values to wxString like this:

    WX_DECLARE_HASH_MAP( int,
                         wxString,
                         wxIntegerHash,
                         wxIntegerEqual,
                         MyHash );

    // using an user-defined class for keys
    class MyKey { /* ... */ };

    // hashing function
    class MyKeyHash
    {
    public:
        MyKeyHash() { }

        unsigned long operator()( const MyKey& k ) const
            { /* compute the hash */ }

        MyKeyHash& operator=(const MyKeyHash&) { return *this; }
    };

    // comparison operator
    class MyKeyEqual
    {
    public:
        MyKeyEqual() { }
        bool operator()( const MyKey& a, const MyKey& b ) const
            { /* compare for equality */ }

        MyKeyEqual& operator=(const MyKeyEqual&) { return *this; }
    };

    WX_DECLARE_HASH_MAP( MyKey,      // type of the keys
                         SOME_TYPE,  // any type you like
                         MyKeyHash,  // hasher
                         MyKeyEqual, // key equality predicate
                         CLASSNAME); // name of the class
Types

In the documentation below you should replace wxHashMap with the name you used in the class declaration.

wxHashMap::key_type Type of the hash keys
wxHashMap::mapped_type Type of the values stored in the hash map
wxHashMap::value_type Equivalent to struct { key_type first; mapped_type second };
wxHashMap::iterator Used to enumerate all the elements in an hash map; it is similar to a value_type*
wxHashMap::const_iterator Used to enumerate all the elements in a constant hash map; it is similar to a const value_type*
wxHashMap::size_type Used for sizes

Iterators

An iterator is similar to a pointer, and so you can use the usual pointer operations: ++it ( and it++ ) to move to the next element, *it to access the element pointed to, it->first ( it->second ) to access the key ( value ) of the element pointed to. Hash maps provide forward only iterators, this means that you can't use --it, it + 3, it1 - it2.

Include files

<wx/hashmap.h>

Members

wxHashMap::wxHashMap
wxHashMap::begin
wxHashMap::clear
wxHashMap::count
wxHashMap::empty
wxHashMap::end
wxHashMap::erase
wxHashMap::find
wxHashMap::insert
wxHashMap::operator[]
wxHashMap::size


wxHashMap::wxHashMap

wxHashMap(size_type size = 10)

The size parameter is just a hint, the table will resize automatically to preserve performance.

wxHashMap(const wxHashMap& map)

Copy constructor.


wxHashMap::begin

const_iterator begin() const

iterator begin()

Returns an iterator pointing at the first element of the hash map. Please remember that hash maps do not guarantee ordering.


wxHashMap::clear

void clear()

Removes all elements from the hash map.


wxHashMap::count

size_type count(const key_type& key) const

Counts the number of elements with the given key present in the map. This function can actually return 0 or 1.


wxHashMap::empty

bool empty() const

Returns true if the hash map does not contain any element, false otherwise.


wxHashMap::end

const_iterator end() const

iterator end()

Returns an iterator pointing at the one-after-the-last element of the hash map. Please remember that hash maps do not guarantee ordering.


wxHashMap::erase

size_type erase(const key_type& key)

Erases the element with the given key, and returns the number of elements erased (either 0 or 1).

void erase(iterator it)

void erase(const_iterator it)

Erases the element pointed to by the iterator. After the deletion the iterator is no longer valid and must not be used.


wxHashMap::find

iterator find(const key_type& key)

const_iterator find(const key_type& key) const

If an element with the given key is present, the functions returns an iterator pointing at that element, otherwise an invalid iterator is returned (i.e. hashmap.find( non_existent_key ) == hashmap.end()).


wxHashMap::insert

void insert(const value_type& v)

Inserts the given value in the hash map.


wxHashMap::operator[]

mapped_type& operator[](const key_type& key)

Use it as an array subscript. The only difference is that if the given key is not present in the hash map, an element with the default value_type() is inserted in the table.


wxHashMap::size

size_type size() const

Returns the number of elements in the map.