xpcom/ds/nsIAtom.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5 #include "nsISupports.idl"
   6
   7 %{C++
   8 #include "nsStringGlue.h"
   9 #include "nsCOMPtr.h"
  10 #include "nsStringBuffer.h"
  11 %}
  12
  13 /*
  14  * Should this really be scriptable?  Using atoms from script or proxies
  15  * could be dangerous since double-wrapping could lead to loss of
  16  * pointer identity.
  17  */
  18
  19 [scriptable, builtinclass, uuid(1f341018-521a-49de-b806-1bef5c9a00b0)]
  20 interface nsIAtom : nsISupports
  21 {
  22   /**
  23    * Get the Unicode or UTF8 value for the string
  24    */
  25   [binaryname(ScriptableToString)] AString toString();
  26   [noscript] AUTF8String toUTF8String();
  27
  28   /**
  29    * Compare the atom to a specific string value
  30    * Note that this will NEVER return/throw an error condition.
  31    */
  32   [binaryname(ScriptableEquals)] boolean equals(in AString aString);
  33
  34   [noscript, notxpcom] boolean equalsUTF8(in AUTF8String aString);
  35
  36   /**
  37    * Returns true if the atom is static and false otherwise.
  38    */
  39   [noscript, notxpcom] boolean isStaticAtom();
  40
  41 %{C++
  42   // note this is NOT virtual so this won't muck with the vtable!
  43   inline bool Equals(const nsAString& aString) const {
  44     return aString.Equals(nsDependentString(mString, mLength));
  45   }
  46
  47   inline char16ptr_t GetUTF16String() const {
  48     return mString;
  49   }
  50
  51   inline const uint32_t GetLength() const {
  52     return mLength;
  53   }
  54
  55   inline void ToString(nsAString& aBuf) {
  56     nsStringBuffer::FromData(mString)->ToString(mLength, aBuf);
  57   }
  58
  59   inline nsStringBuffer* GetStringBuffer() const {
  60     return nsStringBuffer::FromData(mString);
  61   }
  62
  63   /**
  64    * A hashcode that is better distributed than the actual atom
  65    * pointer, for use in situations that need a well-distributed
  66    * hashcode.
  67    */
  68   inline uint32_t hash() const {
  69     return mHash;
  70   }
  71
  72 protected:
  73   uint32_t mLength;
  74   uint32_t mHash;
  75   char16_t* mString;
  76 %}
  77 };
  78
  79
  80 %{C++
  81 /*
  82  * The three forms of NS_NewAtom and do_GetAtom (for use with
  83  * |nsCOMPtr<nsIAtom>|) return the atom for the string given.  At any
  84  * given time there will always be one atom representing a given string.
  85  * Atoms are intended to make string comparison cheaper by simplifying
  86  * it to pointer equality.  A pointer to the atom that does not own a
  87  * reference is not guaranteed to be valid.
  88  *
  89  * The three forms of NS_NewPermanentAtom and do_GetPermanentAtom return
  90  * the atom for the given string and ensure that the atom is permanent.
  91  * An atom that is permanent will exist (occupy space at a specific
  92  * location in memory) until XPCOM is shut down.  The advantage of
  93  * permanent atoms is that they do not need to maintain a reference
  94  * count, which requires locking and hurts performance.
  95  */
  96
  97
  98 /**
  99  * Find an atom that matches the given UTF-8 string.
 100  * The string is assumed to be zero terminated.  Never returns null.
 101  */
 102 extern already_AddRefed<nsIAtom> NS_NewAtom(const char* aUTF8String);
 103
 104 inline already_AddRefed<nsIAtom> do_GetAtom(const char* aUTF8String)
 105     { return NS_NewAtom(aUTF8String); }
 106
 107 /**
 108  * Find an atom that matches the given UTF-8 string.  Never returns null.
 109  */
 110 extern already_AddRefed<nsIAtom> NS_NewAtom(const nsACString& aUTF8String);
 111 inline already_AddRefed<nsIAtom> do_GetAtom(const nsACString& aUTF8String)
 112     { return NS_NewAtom(aUTF8String); }
 113
 114 /**
 115  * Find an atom that matches the given UTF-16 string.
 116  * The string is assumed to be zero terminated.  Never returns null.
 117  */
 118 extern already_AddRefed<nsIAtom> NS_NewAtom(const char16_t* aUTF16String);
 119 inline already_AddRefed<nsIAtom> do_GetAtom(const char16_t* aUTF16String)
 120     { return NS_NewAtom(aUTF16String); }
 121
 122 /**
 123  * Find an atom that matches the given UTF-16 string.  Never returns null.
 124  */
 125 extern already_AddRefed<nsIAtom> NS_NewAtom(const nsAString& aUTF16String);
 126 extern nsIAtom* NS_NewPermanentAtom(const nsAString& aUTF16String);
 127 inline already_AddRefed<nsIAtom> do_GetAtom(const nsAString& aUTF16String)
 128     { return NS_NewAtom(aUTF16String); }
 129
 130 /**
 131  * Return a count of the total number of atoms currently
 132  * alive in the system.
 133  */
 134 extern nsrefcnt NS_GetNumberOfAtoms(void);
 135
 136 /**
 137  * Return a pointer for a static atom for the string or null if there's
 138  * no static atom for this string.
 139  */
 140 extern nsIAtom* NS_GetStaticAtom(const nsAString& aUTF16String);
 141
 142 /**
 143  * Seal the static atom table
 144  */
 145 extern void NS_SealStaticAtomTable();
 146
 147 class nsAtomString : public nsString
 148 {
 149 public:
 150   explicit nsAtomString(nsIAtom* aAtom)
 151   {
 152     aAtom->ToString(*this);
 153   }
 154 };
 155
 156 class nsAtomCString : public nsCString
 157 {
 158 public:
 159   explicit nsAtomCString(nsIAtom* aAtom)
 160   {
 161     aAtom->ToUTF8String(*this);
 162   }
 163 };
 164
 165 class nsDependentAtomString : public nsDependentString
 166 {
 167 public:
 168   explicit nsDependentAtomString(nsIAtom* aAtom)
 169     : nsDependentString(aAtom->GetUTF16String(), aAtom->GetLength())
 170   {
 171   }
 172 };
 173
 174 %}