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