docs/latex/wx/hashmap.tex

   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