xpcom/glue/nsHashKeys.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is C++ hashtable templates.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Benjamin Smedberg.
  19  * Portions created by the Initial Developer are Copyright (C) 2002
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef nsTHashKeys_h__
  39 #define nsTHashKeys_h__
  40
  41 #include "nsID.h"
  42 #include "nsISupports.h"
  43 #include "nsIHashable.h"
  44 #include "nsCOMPtr.h"
  45 #include "pldhash.h"
  46 #include NEW_H
  47
  48 #include "nsStringGlue.h"
  49 #include "nsCRTGlue.h"
  50
  51 #include <stdlib.h>
  52 #include <string.h>
  53
  54 /** @file nsHashKeys.h
  55  * standard HashKey classes for nsBaseHashtable and relatives. Each of these
  56  * classes follows the nsTHashtable::EntryType specification
  57  *
  58  * Lightweight keytypes provided here:
  59  * nsStringHashKey
  60  * nsCStringHashKey
  61  * nsUint32HashKey
  62  * nsUint64HashKey
  63  * nsPtrHashkey
  64  * nsClearingPtrHashKey
  65  * nsVoidPtrHashKey
  66  * nsClearingVoidPtrHashKey
  67  * nsISupportsHashKey
  68  * nsIDHashKey
  69  * nsDepCharHashKey
  70  * nsCharPtrHashKey
  71  * nsUnicharPtrHashKey
  72  * nsHashableHashKey
  73  */
  74
  75 NS_COM_GLUE PRUint32 HashString(const nsAString& aStr);
  76 NS_COM_GLUE PRUint32 HashString(const nsACString& aStr);
  77 NS_COM_GLUE PRUint32 HashString(const char* aKey);
  78 NS_COM_GLUE PRUint32 HashString(const PRUnichar* aKey);
  79
  80 /**
  81  * hashkey wrapper using nsAString KeyType
  82  *
  83  * @see nsTHashtable::EntryType for specification
  84  */
  85 class nsStringHashKey : public PLDHashEntryHdr
  86 {
  87 public:
  88   typedef const nsAString& KeyType;
  89   typedef const nsAString* KeyTypePointer;
  90
  91   nsStringHashKey(KeyTypePointer aStr) : mStr(*aStr) { }
  92   nsStringHashKey(const nsStringHashKey& toCopy) : mStr(toCopy.mStr) { }
  93   ~nsStringHashKey() { }
  94
  95   KeyType GetKey() const { return mStr; }
  96   PRBool KeyEquals(const KeyTypePointer aKey) const
  97   {
  98     return mStr.Equals(*aKey);
  99   }
 100
 101   static KeyTypePointer KeyToPointer(KeyType aKey) { return &aKey; }
 102   static PLDHashNumber HashKey(const KeyTypePointer aKey)
 103   {
 104     return HashString(*aKey);
 105   }
 106   enum { ALLOW_MEMMOVE = PR_TRUE };
 107
 108 private:
 109   const nsString mStr;
 110 };
 111
 112 /**
 113  * hashkey wrapper using nsACString KeyType
 114  *
 115  * @see nsTHashtable::EntryType for specification
 116  */
 117 class nsCStringHashKey : public PLDHashEntryHdr
 118 {
 119 public:
 120   typedef const nsACString& KeyType;
 121   typedef const nsACString* KeyTypePointer;
 122
 123   nsCStringHashKey(const nsACString* aStr) : mStr(*aStr) { }
 124   nsCStringHashKey(const nsCStringHashKey& toCopy) : mStr(toCopy.mStr) { }
 125   ~nsCStringHashKey() { }
 126
 127   KeyType GetKey() const { return mStr; }
 128
 129   PRBool KeyEquals(KeyTypePointer aKey) const { return mStr.Equals(*aKey); }
 130
 131   static KeyTypePointer KeyToPointer(KeyType aKey) { return &aKey; }
 132   static PLDHashNumber HashKey(KeyTypePointer aKey)
 133   {
 134     return HashString(*aKey);
 135   }
 136   enum { ALLOW_MEMMOVE = PR_TRUE };
 137
 138 private:
 139   const nsCString mStr;
 140 };
 141
 142 /**
 143  * hashkey wrapper using PRUint32 KeyType
 144  *
 145  * @see nsTHashtable::EntryType for specification
 146  */
 147 class nsUint32HashKey : public PLDHashEntryHdr
 148 {
 149 public:
 150   typedef const PRUint32& KeyType;
 151   typedef const PRUint32* KeyTypePointer;
 152
 153   nsUint32HashKey(KeyTypePointer aKey) : mValue(*aKey) { }
 154   nsUint32HashKey(const nsUint32HashKey& toCopy) : mValue(toCopy.mValue) { }
 155   ~nsUint32HashKey() { }
 156
 157   KeyType GetKey() const { return mValue; }
 158   PRBool KeyEquals(KeyTypePointer aKey) const { return *aKey == mValue; }
 159
 160   static KeyTypePointer KeyToPointer(KeyType aKey) { return &aKey; }
 161   static PLDHashNumber HashKey(KeyTypePointer aKey) { return *aKey; }
 162   enum { ALLOW_MEMMOVE = PR_TRUE };
 163
 164 private:
 165   const PRUint32 mValue;
 166 };
 167
 168 /**
 169  * hashkey wrapper using PRUint64 KeyType
 170  *
 171  * @see nsTHashtable::EntryType for specification
 172  */
 173 class nsUint64HashKey : public PLDHashEntryHdr
 174 {
 175 public:
 176   typedef const PRUint64& KeyType;
 177   typedef const PRUint64* KeyTypePointer;
 178
 179   nsUint64HashKey(KeyTypePointer aKey) : mValue(*aKey) { }
 180   nsUint64HashKey(const nsUint64HashKey& toCopy) : mValue(toCopy.mValue) { }
 181   ~nsUint64HashKey() { }
 182
 183   KeyType GetKey() const { return mValue; }
 184   PRBool KeyEquals(KeyTypePointer aKey) const { return *aKey == mValue; }
 185
 186   static KeyTypePointer KeyToPointer(KeyType aKey) { return &aKey; }
 187   static PLDHashNumber HashKey(KeyTypePointer aKey) { return PLDHashNumber(*aKey); }
 188   enum { ALLOW_MEMMOVE = PR_TRUE };
 189
 190 private:
 191   const PRUint64 mValue;
 192 };
 193
 194 /**
 195  * hashkey wrapper using nsISupports* KeyType
 196  *
 197  * @see nsTHashtable::EntryType for specification
 198  */
 199 class nsISupportsHashKey : public PLDHashEntryHdr
 200 {
 201 public:
 202   typedef nsISupports* KeyType;
 203   typedef const nsISupports* KeyTypePointer;
 204
 205   nsISupportsHashKey(const nsISupports* key) :
 206     mSupports(const_cast<nsISupports*>(key)) { }
 207   nsISupportsHashKey(const nsISupportsHashKey& toCopy) :
 208     mSupports(toCopy.mSupports) { }
 209   ~nsISupportsHashKey() { }
 210
 211   KeyType GetKey() const { return mSupports; }
 212
 213   PRBool KeyEquals(KeyTypePointer aKey) const { return aKey == mSupports; }
 214
 215   static KeyTypePointer KeyToPointer(KeyType aKey) { return aKey; }
 216   static PLDHashNumber HashKey(KeyTypePointer aKey)
 217   {
 218     return NS_PTR_TO_INT32(aKey) >>2;
 219   }
 220   enum { ALLOW_MEMMOVE = PR_TRUE };
 221
 222 private:
 223   nsCOMPtr<nsISupports> mSupports;
 224 };
 225
 226 /**
 227  * hashkey wrapper using T* KeyType
 228  *
 229  * @see nsTHashtable::EntryType for specification
 230  */
 231 template<class T>
 232 class nsPtrHashKey : public PLDHashEntryHdr
 233 {
 234  public:
 235   typedef T *KeyType;
 236   typedef const T *KeyTypePointer;
 237
 238   nsPtrHashKey(const T *key) : mKey(const_cast<T*>(key)) {}
 239   nsPtrHashKey(const nsPtrHashKey<T> &toCopy) : mKey(toCopy.mKey) {}
 240   ~nsPtrHashKey() {}
 241
 242   KeyType GetKey() const { return mKey; }
 243
 244   PRBool KeyEquals(KeyTypePointer key) const { return key == mKey; }
 245
 246   static KeyTypePointer KeyToPointer(KeyType key) { return key; }
 247   static PLDHashNumber HashKey(KeyTypePointer key)
 248   {
 249     return NS_PTR_TO_INT32(key) >> 2;
 250   }
 251   enum { ALLOW_MEMMOVE = PR_TRUE };
 252
 253  protected:
 254   T *mKey;
 255 };
 256
 257 /**
 258  * hashkey wrapper using T* KeyType that sets key to NULL upon
 259  * destruction. Relevant only in cases where a memory pointer-scanner
 260  * like valgrind might get confused about stale references.
 261  *
 262  * @see nsTHashtable::EntryType for specification
 263  */
 264
 265 template<class T>
 266 class nsClearingPtrHashKey : public nsPtrHashKey<T>
 267 {
 268  public:
 269   nsClearingPtrHashKey(const T *key) : nsPtrHashKey<T>(key) {}
 270   nsClearingPtrHashKey(const nsClearingPtrHashKey<T> &toCopy) :
 271     nsPtrHashKey<T>(toCopy) {}
 272   ~nsClearingPtrHashKey() { nsPtrHashKey<T>::mKey = nsnull; }
 273 };
 274
 275 typedef nsPtrHashKey<const void> nsVoidPtrHashKey;
 276 typedef nsClearingPtrHashKey<const void> nsClearingVoidPtrHashKey;
 277
 278 /**
 279  * hashkey wrapper using nsID KeyType
 280  *
 281  * @see nsTHashtable::EntryType for specification
 282  */
 283 class nsIDHashKey : public PLDHashEntryHdr
 284 {
 285 public:
 286   typedef const nsID& KeyType;
 287   typedef const nsID* KeyTypePointer;
 288
 289   nsIDHashKey(const nsID* inID) : mID(*inID) { }
 290   nsIDHashKey(const nsIDHashKey& toCopy) : mID(toCopy.mID) { }
 291   ~nsIDHashKey() { }
 292
 293   KeyType GetKey() const { return mID; }
 294
 295   PRBool KeyEquals(KeyTypePointer aKey) const { return aKey->Equals(mID); }
 296
 297   static KeyTypePointer KeyToPointer(KeyType aKey) { return &aKey; }
 298   static PLDHashNumber HashKey(KeyTypePointer aKey);
 299   enum { ALLOW_MEMMOVE = PR_TRUE };
 300
 301 private:
 302   const nsID mID;
 303 };
 304
 305 /**
 306  * hashkey wrapper for "dependent" const char*; this class does not "own"
 307  * its string pointer.
 308  *
 309  * This class must only be used if the strings have a lifetime longer than
 310  * the hashtable they occupy. This normally occurs only for static
 311  * strings or strings that have been arena-allocated.
 312  *
 313  * @see nsTHashtable::EntryType for specification
 314  */
 315 class nsDepCharHashKey : public PLDHashEntryHdr
 316 {
 317 public:
 318   typedef const char* KeyType;
 319   typedef const char* KeyTypePointer;
 320
 321   nsDepCharHashKey(const char* aKey) { mKey = aKey; }
 322   nsDepCharHashKey(const nsDepCharHashKey& toCopy) { mKey = toCopy.mKey; }
 323   ~nsDepCharHashKey() { }
 324
 325   const char* GetKey() const { return mKey; }
 326   PRBool KeyEquals(const char* aKey) const
 327   {
 328     return !strcmp(mKey, aKey);
 329   }
 330
 331   static const char* KeyToPointer(const char* aKey) { return aKey; }
 332   static PLDHashNumber HashKey(const char* aKey) { return HashString(aKey); }
 333   enum { ALLOW_MEMMOVE = PR_TRUE };
 334
 335 private:
 336   const char* mKey;
 337 };
 338
 339 /**
 340  * hashkey wrapper for const char*; at construction, this class duplicates
 341  * a string pointed to by the pointer so that it doesn't matter whether or not
 342  * the string lives longer than the hash table.
 343  */
 344 class nsCharPtrHashKey : public PLDHashEntryHdr
 345 {
 346 public:
 347   typedef const char* KeyType;
 348   typedef const char* KeyTypePointer;
 349
 350   nsCharPtrHashKey(const char* aKey) : mKey(strdup(aKey)) { }
 351   nsCharPtrHashKey(const nsCharPtrHashKey& toCopy) : mKey(strdup(toCopy.mKey)) { }
 352   ~nsCharPtrHashKey() { if (mKey) free(const_cast<char *>(mKey)); }
 353
 354   const char* GetKey() const { return mKey; }
 355   PRBool KeyEquals(KeyTypePointer aKey) const
 356   {
 357     return !strcmp(mKey, aKey);
 358   }
 359
 360   static KeyTypePointer KeyToPointer(KeyType aKey) { return aKey; }
 361   static PLDHashNumber HashKey(KeyTypePointer aKey) { return HashString(aKey); }
 362
 363   enum { ALLOW_MEMMOVE = PR_TRUE };
 364
 365 private:
 366   const char* mKey;
 367 };
 368
 369 /**
 370  * hashkey wrapper for const PRUnichar*; at construction, this class duplicates
 371  * a string pointed to by the pointer so that it doesn't matter whether or not
 372  * the string lives longer than the hash table.
 373  */
 374 class nsUnicharPtrHashKey : public PLDHashEntryHdr
 375 {
 376 public:
 377   typedef const PRUnichar* KeyType;
 378   typedef const PRUnichar* KeyTypePointer;
 379
 380   nsUnicharPtrHashKey(const PRUnichar* aKey) : mKey(NS_strdup(aKey)) { }
 381   nsUnicharPtrHashKey(const nsUnicharPtrHashKey& toCopy) : mKey(NS_strdup(toCopy.mKey)) { }
 382   ~nsUnicharPtrHashKey() { if (mKey) NS_Free(const_cast<PRUnichar *>(mKey)); }
 383
 384   const PRUnichar* GetKey() const { return mKey; }
 385   PRBool KeyEquals(KeyTypePointer aKey) const
 386   {
 387     return !NS_strcmp(mKey, aKey);
 388   }
 389
 390   static KeyTypePointer KeyToPointer(KeyType aKey) { return aKey; }
 391   static PLDHashNumber HashKey(KeyTypePointer aKey) { return HashString(aKey); }
 392
 393   enum { ALLOW_MEMMOVE = PR_TRUE };
 394
 395 private:
 396   const PRUnichar* mKey;
 397 };
 398
 399 /**
 400  * Hashtable key class to use with objects that support nsIHashable
 401  */
 402 class nsHashableHashKey : public PLDHashEntryHdr
 403 {
 404 public:
 405     typedef nsIHashable* KeyType;
 406     typedef const nsIHashable* KeyTypePointer;
 407
 408     nsHashableHashKey(const nsIHashable* aKey) :
 409         mKey(const_cast<nsIHashable*>(aKey)) { }
 410     nsHashableHashKey(const nsHashableHashKey& toCopy) :
 411         mKey(toCopy.mKey) { }
 412     ~nsHashableHashKey() { }
 413
 414     nsIHashable* GetKey() const { return mKey; }
 415
 416     PRBool KeyEquals(const nsIHashable* aKey) const {
 417         PRBool eq;
 418         if (NS_SUCCEEDED(mKey->Equals(const_cast<nsIHashable*>(aKey), &eq))) {
 419             return eq;
 420         }
 421         return PR_FALSE;
 422     }
 423
 424     static const nsIHashable* KeyToPointer(nsIHashable* aKey) { return aKey; }
 425     static PLDHashNumber HashKey(const nsIHashable* aKey) {
 426         PRUint32 code = 8888; // magic number if GetHashCode fails :-(
 427 #ifdef NS_DEBUG
 428         nsresult rv =
 429 #endif
 430         const_cast<nsIHashable*>(aKey)->GetHashCode(&code);
 431         NS_ASSERTION(NS_SUCCEEDED(rv), "GetHashCode should not throw!");
 432         return code;
 433     }
 434
 435     enum { ALLOW_MEMMOVE = PR_TRUE };
 436
 437 private:
 438     nsCOMPtr<nsIHashable> mKey;
 439 };
 440
 441 #endif // nsTHashKeys_h__