docs/latex/wx/hash.tex

   1 \section{\class{wxHashTable}}\label{wxhashtable}
   2
   3 {\bf Please note} that this class is retained for backward compatibility
   4 reasons; you should use \helpref{wxHashMap}{wxhashmap}.
   5
   6 This class provides hash table functionality for wxWindows, and for an
   7 application if it wishes.  Data can be hashed on an integer or string
   8 key.
   9
  10 \wxheading{Derived from}
  11
  12 \helpref{wxObject}{wxobject}
  13
  14 \wxheading{Include files}
  15
  16 <wx/hash.h>
  17
  18 \wxheading{Example}
  19
  20 Below is an example of using a hash table.
  21
  22 \begin{verbatim}
  23   wxHashTable table(KEY_STRING);
  24
  25   wxPoint *point = new wxPoint(100, 200);
  26   table.Put("point 1", point);
  27
  28   ....
  29
  30   wxPoint *found_point = (wxPoint *)table.Get("point 1");
  31 \end{verbatim}
  32
  33 A hash table is implemented as an array of pointers to lists. When no
  34 data has been stored, the hash table takes only a little more space than
  35 this array (default size is 1000).  When a data item is added, an
  36 integer is constructed from the integer or string key that is within the
  37 bounds of the array. If the array element is NULL, a new (keyed) list is
  38 created for the element. Then the data object is appended to the list,
  39 storing the key in case other data objects need to be stored in the list
  40 also (when a `collision' occurs).
  41
  42 Retrieval involves recalculating the array index from the key, and searching
  43 along the keyed list for the data object whose stored key matches the passed
  44 key. Obviously this is quicker when there are fewer collisions, so hashing
  45 will become inefficient if the number of items to be stored greatly exceeds
  46 the size of the hash table.
  47
  48 \wxheading{See also}
  49
  50 \helpref{wxList}{wxlist}
  51
  52 \latexignore{\rtfignore{\wxheading{Members}}}
  53
  54 \membersection{wxHashTable::wxHashTable}
  55
  56 \func{}{wxHashTable}{\param{unsigned int}{ key\_type}, \param{int}{ size = 1000}}
  57
  58 Constructor. {\it key\_type} is one of wxKEY\_INTEGER, or wxKEY\_STRING,
  59 and indicates what sort of keying is required. {\it size} is optional.
  60
  61 \membersection{wxHashTable::\destruct{wxHashTable}}
  62
  63 \func{}{\destruct{wxHashTable}}{\void}
  64
  65 Destroys the hash table.
  66
  67 \membersection{wxHashTable::BeginFind}
  68
  69 \func{void}{BeginFind}{\void}
  70
  71 The counterpart of {\it Next}.  If the application wishes to iterate
  72 through all the data in the hash table, it can call {\it BeginFind} and
  73 then loop on {\it Next}.
  74
  75 \membersection{wxHashTable::Clear}
  76
  77 \func{void}{Clear}{\void}
  78
  79 Clears the hash table of all nodes (but as usual, doesn't delete user data).
  80
  81 \membersection{wxHashTable::Delete}
  82
  83 \func{wxObject *}{Delete}{\param{long}{ key}}
  84
  85 \func{wxObject *}{Delete}{\param{const wxString\& }{ key}}
  86
  87 Deletes entry in hash table and returns the user's data (if found).
  88
  89 \membersection{wxHashTable::DeleteContents}
  90
  91 \func{void}{DeleteContents}{\param{bool}{ flag}}
  92
  93 If set to TRUE data stored in hash table will be deleted when hash table object
  94 is destroyed.
  95
  96
  97 \membersection{wxHashTable::Get}
  98
  99 \func{wxObject *}{Get}{\param{long}{ key}}
 100
 101 \func{wxObject *}{Get}{\param{const char*}{ key}}
 102
 103 Gets data from the hash table, using an integer or string key (depending on which
 104 has table constructor was used).
 105
 106 \membersection{wxHashTable::MakeKey}
 107
 108 \func{long}{MakeKey}{\param{const wxString\& }{string}}
 109
 110 Makes an integer key out of a string. An application may wish to make a key
 111 explicitly (for instance when combining two data values to form a key).
 112
 113 \membersection{wxHashTable::Next}
 114
 115 \func{wxNode *}{Next}{\void}
 116
 117 If the application wishes to iterate through all the data in the hash
 118 table, it can call {\it BeginFind} and then loop on {\it Next}. This function
 119 returns a {\bf wxNode} pointer (or NULL if there are no more nodes).  See the
 120 description for \helpref{wxNode}{wxnode}. The user will probably only wish to use the
 121 {\bf wxNode::Data} function to retrieve the data; the node may also be deleted.
 122
 123 \membersection{wxHashTable::Put}
 124
 125 \func{void}{Put}{\param{long}{ key}, \param{wxObject *}{object}}
 126
 127 \func{void}{Put}{\param{const char*}{ key}, \param{wxObject *}{object}}
 128
 129 Inserts data into the hash table, using an integer or string key (depending on which
 130 has table constructor was used). The key string is copied and stored by the hash
 131 table implementation.
 132
 133 \membersection{wxHashTable::GetCount}
 134
 135 \constfunc{size\_t}{GetCount}{\void}
 136
 137 Returns the number of elements in the hash table.
 138