+ Example:
+ @code
+ 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
+ }
+ @endcode
+
+
+ @section hashmap_declaringnew Declaring new hash table types
+
+ @code
+ WX_DECLARE_STRING_HASH_MAP( VALUE_T, // type of the values
+ CLASSNAME ); // name of the class
+ @endcode
+ Declares a hash map class named CLASSNAME, with wxString keys and VALUE_T values.
+
+ @code
+ WX_DECLARE_VOIDPTR_HASH_MAP( VALUE_T, // type of the values
+ CLASSNAME ); // name of the class
+ @endcode
+ Declares a hash map class named CLASSNAME, with void* keys and VALUE_T values.
+
+ @code
+ 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
+ @endcode
+ 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 a hash map mapping int values to wxString like this:
+
+ @code
+ 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
+ @endcode
+
+
+ @section hashmap_types 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 a 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.
+ - wxHashMap::Insert_Result: The return value for insert().
+
+
+ @section hashmap_iter 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.
+
+
projects / wxWidgets.git / commitdiff
