1\section{\class{wxHashMap}}\label{wxhashmap} 2 3This is a simple, type-safe, and reasonably efficient hash map class, 4whose interface is a subset of the interface of STL containers. In 5particular, the interface is modeled after std::map, and the various, 6non-standard, std::hash\_map. 7 8\wxheading{Example} 9 10\begin{verbatim} 11 class MyClass { /* ... */ }; 12 13 // declare a hash map with string keys and int values 14 WX_DECLARE_STRING_HASH_MAP( int, MyHash5 ); 15 // same, with int keys and MyClass* values 16 WX_DECLARE_HASH_MAP( int, MyClass*, wxIntegerHash, wxIntegerEqual, MyHash1 ); 17 // same, with wxString keys and int values 18 WX_DECLARE_STRING_HASH_MAP( int, MyHash3 ); 19 // same, with wxString keys and values 20 WX_DECLARE_STRING_HASH_MAP( wxString, MyHash2 ); 21 22 MyHash1 h1; 23 MyHash2 h2; 24 25 // store and retrieve values 26 h1[1] = new MyClass( 1 ); 27 h1[10000000] = NULL; 28 h1[50000] = new MyClass( 2 ); 29 h2["Bill"] = "ABC"; 30 wxString tmp = h2["Bill"]; 31 // since element with key "Joe" is not present, this will return 32 // the default value, which is an empty string in the case of wxString 33 MyClass tmp2 = h2["Joe"]; 34 35 // iterate over all the elements in the class 36 MyHash2::iterator it; 37 for( it = h2.begin(); it != h2.end(); ++it ) 38 { 39 wxString key = it->first, value = it->second; 40 // do something useful with key and value 41 } 42\end{verbatim} 43 44\wxheading{Declaring new hash table types} 45 46\begin{verbatim} 47 WX_DECLARE_STRING_HASH_MAP( VALUE_T, // type of the values 48 CLASSNAME ); // name of the class 49\end{verbatim} 50 51Declares a hash map class named CLASSNAME, with {\tt wxString} keys 52and VALUE\_T values. 53 54\begin{verbatim} 55 WX_DECLARE_VOIDPTR_HASH_MAP( VALUE_T, // type of the values 56 CLASSNAME ); // name of the class 57\end{verbatim} 58 59Declares a hash map class named CLASSNAME, with {\tt void*} keys 60and VALUE\_T values. 61 62\begin{verbatim} 63 WX_DECLARE_HASH_MAP( KEY_T, // type of the keys 64 VALUE_T, // type of the values 65 HASH_T, // hasher 66 KEY_EQ_T, // key equality predicate 67 CLASSNAME); // name of the class 68\end{verbatim} 69 70The HASH\_T and KEY\_EQ\_T are the types 71used for the hashing function and key comparison. wxWidgets provides 72three predefined hashing functions: {\tt wxIntegerHash} 73for integer types ( {\tt int}, {\tt long}, {\tt short}, 74and their unsigned counterparts ), {\tt wxStringHash} for strings 75( {\tt wxString}, {\tt wxChar*}, {\tt char*} ), and 76{\tt wxPointerHash} for any kind of pointer. 77Similarly three equality predicates: 78{\tt wxIntegerEqual}, {\tt wxStringEqual}, {\tt wxPointerEqual} are provided. 79 80Using this you could declare a hash map mapping {\tt int} values 81to {\tt wxString} like this: 82 83\begin{verbatim} 84 WX_DECLARE_HASH_MAP( int, 85 wxString, 86 wxIntegerHash, 87 wxIntegerEqual, 88 MyHash ); 89 90 // using an user-defined class for keys 91 class MyKey { /* ... */ }; 92 93 // hashing function 94 class MyKeyHash 95 { 96 public: 97 MyKeyHash() { } 98 99 unsigned long operator()( const MyKey& k ) const 100 { /* compute the hash */ } 101 102 MyKeyHash& operator=(const MyKeyHash&) { return *this; } 103 }; 104 105 // comparison operator 106 class MyKeyEqual 107 { 108 public: 109 MyKeyEqual() { } 110 bool operator()( const MyKey& a, const MyKey& b ) const 111 { /* compare for equality */ } 112 113 MyKeyEqual& operator=(const MyKeyEqual&) { return *this; } 114 }; 115 116 WX_DECLARE_HASH_MAP( MyKey, // type of the keys 117 SOME_TYPE, // any type you like 118 MyKeyHash, // hasher 119 MyKeyEqual, // key equality predicate 120 CLASSNAME); // name of the class 121\end{verbatim} 122 123\latexignore{\rtfignore{\wxheading{Types}}} 124 125In the documentation below you should replace wxHashMap with the name 126you used in the class declaration. 127 128\begin{twocollist} 129\twocolitem{wxHashMap::key\_type}{Type of the hash keys} 130\twocolitem{wxHashMap::mapped\_type}{Type of the values stored in the hash map} 131\twocolitem{wxHashMap::value\_type}{Equivalent to 132{\tt struct \{ key\_type first; mapped\_type second \};} } 133\twocolitem{wxHashMap::iterator}{Used to enumerate all the elements in a hash 134map; it is similar to a {\tt value\_type*}} 135\twocolitem{wxHashMap::const\_iterator}{Used to enumerate all the elements 136in a constant hash map; it is similar to a {\tt const value\_type*}} 137\twocolitem{wxHashMap::size\_type}{Used for sizes} 138\twocolitem{wxHashMap::Insert\_Result}{The return value for 139\helpref{insert()}{wxhashmapinsert}} 140\end{twocollist} 141 142\wxheading{Iterators} 143 144An iterator is similar to a pointer, and so you can use the usual pointer 145operations: {\tt ++it} ( and {\tt it++} ) to move to the next element, 146{\tt *it} to access the element pointed to, {\tt it->first} 147( {\tt it->second} ) to access the key ( value ) 148of the element pointed to. Hash maps provide forward only iterators, this 149means that you can't use {\tt --it}, {\tt it + 3}, {\tt it1 - it2}. 150 151\wxheading{Include files} 152 153<wx/hashmap.h> 154 155\latexignore{\rtfignore{\wxheading{Members}}} 156 157\membersection{wxHashMap::wxHashMap}\label{wxhashmapctor} 158 159\func{}{wxHashMap}{\param{size\_type}{ size = 10}} 160 161The size parameter is just a hint, the table will resize automatically 162to preserve performance. 163 164\func{}{wxHashMap}{\param{const wxHashMap\&}{ map}} 165 166Copy constructor. 167 168\membersection{wxHashMap::begin}\label{wxhashmapbegin} 169 170\constfunc{const\_iterator}{begin}{} 171 172\func{iterator}{begin}{} 173 174Returns an iterator pointing at the first element of the hash map. 175Please remember that hash maps do not guarantee ordering. 176 177\membersection{wxHashMap::clear}\label{wxhashmapclear} 178 179\func{void}{clear}{} 180 181Removes all elements from the hash map. 182 183\membersection{wxHashMap::count}\label{wxhashmapcount} 184 185\constfunc{size\_type}{count}{\param{const key\_type\&}{ key}} 186 187Counts the number of elements with the given key present in the map. 188This function returns only 0 or 1. 189 190\membersection{wxHashMap::empty}\label{wxhashmapempty} 191 192\constfunc{bool}{empty}{} 193 194Returns true if the hash map does not contain any elements, false otherwise. 195 196\membersection{wxHashMap::end}\label{wxhashmapend} 197 198\constfunc{const\_iterator}{end}{} 199 200\func{iterator}{end}{} 201 202Returns an iterator pointing at the one-after-the-last element of the hash map. 203Please remember that hash maps do not guarantee ordering. 204 205\membersection{wxHashMap::erase}\label{wxhashmaperase} 206 207\func{size\_type}{erase}{\param{const key\_type\&}{ key}} 208 209Erases the element with the given key, and returns the number of elements 210erased (either 0 or 1). 211 212\func{void}{erase}{\param{iterator}{ it}} 213 214\func{void}{erase}{\param{const\_iterator}{ it}} 215 216Erases the element pointed to by the iterator. After the deletion 217the iterator is no longer valid and must not be used. 218 219\membersection{wxHashMap::find}\label{wxhashmapfind} 220 221\func{iterator}{find}{\param{const key\_type\&}{ key}} 222 223\constfunc{const\_iterator}{find}{\param{const key\_type\&}{ key}} 224 225If an element with the given key is present, the functions returns 226an iterator pointing at that element, otherwise an invalid iterator 227is returned (i.e. hashmap.find( non\_existent\_key ) == hashmap.end()). 228 229\membersection{wxHashMap::insert}\label{wxhashmapinsert} 230 231\func{Insert\_Result}{insert}{\param{const value\_type\&}{ v}} 232 233Inserts the given value in the hash map. The return value is 234equivalent to a \texttt{std::pair<wxHashMap::iterator, bool>}; 235the iterator points to the inserted element, the boolean value 236is \texttt{true} if \texttt{v} was actually inserted. 237 238\membersection{wxHashMap::operator[]}\label{wxhashmapbracket} 239 240\func{mapped\_type\&}{operator[]}{\param{const key\_type\&}{ key}} 241 242Use the key as an array subscript. The only difference is that if the 243given key is not present in the hash map, an element with the 244default {\tt value\_type()} is inserted in the table. 245 246\membersection{wxHashMap::size}\label{wxhashmapsize} 247 248\constfunc{size\_type}{size}{} 249 250Returns the number of elements in the map. 251 252