interface/wx/hash.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        hash.h
   3 // Purpose:     interface of wxHashTable
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHashTable
  11
  12     @deprecated
  13     Please note that this class is retained for backward compatibility
  14     reasons; you should use wxHashMap.
  15
  16     This class provides hash table functionality for wxWidgets, and for an
  17     application if it wishes.  Data can be hashed on an integer or string key.
  18
  19     Example:
  20     @code
  21         wxHashTable table(wxKEY_STRING);
  22
  23         wxPoint *point = new wxPoint(100, 200);
  24         table.Put("point 1", point);
  25
  26         ....
  27
  28         wxPoint *found_point = (wxPoint *)table.Get("point 1");
  29     @endcode
  30
  31     A hash table is implemented as an array of pointers to lists.
  32     When no data has been stored, the hash table takes only a little more space
  33     than this array (default size is 1000). When a data item is added, an integer
  34     is constructed from the integer or string key that is within the bounds of the array.
  35     If the array element is @NULL, a new (keyed) list is created for the element.
  36     Then the data object is appended to the list, storing the key in case other
  37     data objects need to be stored in the list also (when a 'collision' occurs).
  38
  39     Retrieval involves recalculating the array index from the key, and searching
  40     along the keyed list for the data object whose stored key matches the passed key.
  41     Obviously this is quicker when there are fewer collisions, so hashing will
  42     become inefficient if the number of items to be stored greatly exceeds the
  43     size of the hash table.
  44
  45     @library{wxbase}
  46     @category{containers}
  47
  48     @see wxList
  49 */
  50 class wxHashTable : public wxObject
  51 {
  52 public:
  53     /**
  54         Constructor. @a key_type is one of wxKEY_INTEGER, or wxKEY_STRING,
  55         and indicates what sort of keying is required. @a size is optional.
  56     */
  57     wxHashTable(wxKeyType key_type = wxKEY_INTEGER, size_t size = 1000);
  58
  59     /**
  60         Destroys the hash table.
  61     */
  62     virtual ~wxHashTable();
  63
  64     /**
  65         The counterpart of Next().  If the application wishes to iterate
  66         through all the data in the hash table, it can call BeginFind() and
  67         then loop on Next().
  68     */
  69     void BeginFind();
  70
  71     /**
  72         Clears the hash table of all nodes (but as usual, doesn't delete user data).
  73     */
  74     void Clear();
  75
  76     //@{
  77     /**
  78         Deletes entry in hash table and returns the user's data (if found).
  79     */
  80     wxObject* Delete(long key);
  81     wxObject* Delete(const wxString& key);
  82     //@}
  83
  84     /**
  85         If set to @true data stored in hash table will be deleted when hash table
  86         object is destroyed.
  87     */
  88     void DeleteContents(bool flag);
  89
  90     //@{
  91     /**
  92         Gets data from the hash table, using an integer or string key
  93         (depending on which has table constructor was used).
  94     */
  95     wxObject* Get(long key);
  96     wxObject* Get(const char* key);
  97     //@}
  98
  99     /**
 100         Returns the number of elements in the hash table.
 101     */
 102     size_t GetCount() const;
 103
 104     /**
 105         Makes an integer key out of a string. An application may wish to make a key
 106         explicitly (for instance when combining two data values to form a key).
 107     */
 108     static long MakeKey(const wxString& string);
 109
 110     /**
 111         If the application wishes to iterate through all the data in the hash
 112         table, it can call BeginFind() and then loop on Next(). This function
 113         returns a @b wxHashTable::Node pointer (or @NULL if there are no more nodes).
 114
 115         The return value is functionally equivalent to @b wxNode but might not be
 116         implemented as a @b wxNode. The user will probably only wish to use the
 117         wxNode::GetData() method to retrieve the data; the node may also be deleted.
 118     */
 119     wxHashTable::Node* Next();
 120
 121     //@{
 122     /**
 123         Inserts data into the hash table, using an integer or string key (depending on
 124         which has table constructor was used).
 125         The key string is copied and stored by the hash table implementation.
 126     */
 127     void Put(long key, wxObject* object);
 128     void Put(const char* key, wxObject* object);
 129     //@}
 130 };
 131