michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: %{C++
michael@0: #include "nsStringGlue.h"
michael@0: #include "nsCOMPtr.h"
michael@0: #include "nsStringBuffer.h"
michael@0: %}
michael@0: 
michael@0: /*
michael@0:  * Should this really be scriptable?  Using atoms from script or proxies
michael@0:  * could be dangerous since double-wrapping could lead to loss of
michael@0:  * pointer identity.
michael@0:  */
michael@0:  
michael@0: [scriptable, builtinclass, uuid(1f341018-521a-49de-b806-1bef5c9a00b0)]
michael@0: interface nsIAtom : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Get the Unicode or UTF8 value for the string
michael@0:    */
michael@0:   [binaryname(ScriptableToString)] AString toString(); 
michael@0:   [noscript] AUTF8String toUTF8String();
michael@0:   
michael@0:   /**
michael@0:    * Compare the atom to a specific string value
michael@0:    * Note that this will NEVER return/throw an error condition.
michael@0:    */
michael@0:   [binaryname(ScriptableEquals)] boolean equals(in AString aString);
michael@0:   
michael@0:   [noscript, notxpcom] boolean equalsUTF8(in AUTF8String aString);
michael@0: 
michael@0:   /**
michael@0:    * Returns true if the atom is static and false otherwise.
michael@0:    */
michael@0:   [noscript, notxpcom] boolean isStaticAtom();
michael@0: 
michael@0: %{C++
michael@0:   // note this is NOT virtual so this won't muck with the vtable!
michael@0:   inline bool Equals(const nsAString& aString) const {
michael@0:     return aString.Equals(nsDependentString(mString, mLength));
michael@0:   }
michael@0: 
michael@0:   inline char16ptr_t GetUTF16String() const {
michael@0:     return mString;
michael@0:   }
michael@0: 
michael@0:   inline const uint32_t GetLength() const {
michael@0:     return mLength;
michael@0:   }
michael@0: 
michael@0:   inline void ToString(nsAString& aBuf) {
michael@0:     nsStringBuffer::FromData(mString)->ToString(mLength, aBuf);
michael@0:   }
michael@0: 
michael@0:   inline nsStringBuffer* GetStringBuffer() const {
michael@0:     return nsStringBuffer::FromData(mString);
michael@0:   }
michael@0: 
michael@0:   /**
michael@0:    * A hashcode that is better distributed than the actual atom
michael@0:    * pointer, for use in situations that need a well-distributed
michael@0:    * hashcode.
michael@0:    */
michael@0:   inline uint32_t hash() const {
michael@0:     return mHash;
michael@0:   }
michael@0: 
michael@0: protected:
michael@0:   uint32_t mLength;
michael@0:   uint32_t mHash;
michael@0:   char16_t* mString;
michael@0: %}
michael@0: };
michael@0: 
michael@0: 
michael@0: %{C++
michael@0: /*
michael@0:  * The three forms of NS_NewAtom and do_GetAtom (for use with
michael@0:  * |nsCOMPtr<nsIAtom>|) return the atom for the string given.  At any
michael@0:  * given time there will always be one atom representing a given string.
michael@0:  * Atoms are intended to make string comparison cheaper by simplifying
michael@0:  * it to pointer equality.  A pointer to the atom that does not own a
michael@0:  * reference is not guaranteed to be valid.
michael@0:  *
michael@0:  * The three forms of NS_NewPermanentAtom and do_GetPermanentAtom return
michael@0:  * the atom for the given string and ensure that the atom is permanent.
michael@0:  * An atom that is permanent will exist (occupy space at a specific
michael@0:  * location in memory) until XPCOM is shut down.  The advantage of
michael@0:  * permanent atoms is that they do not need to maintain a reference
michael@0:  * count, which requires locking and hurts performance.
michael@0:  */
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * Find an atom that matches the given UTF-8 string.
michael@0:  * The string is assumed to be zero terminated.  Never returns null.
michael@0:  */
michael@0: extern already_AddRefed<nsIAtom> NS_NewAtom(const char* aUTF8String);
michael@0: 
michael@0: inline already_AddRefed<nsIAtom> do_GetAtom(const char* aUTF8String)
michael@0:     { return NS_NewAtom(aUTF8String); }
michael@0:  
michael@0: /**
michael@0:  * Find an atom that matches the given UTF-8 string.  Never returns null.
michael@0:  */
michael@0: extern already_AddRefed<nsIAtom> NS_NewAtom(const nsACString& aUTF8String);
michael@0: inline already_AddRefed<nsIAtom> do_GetAtom(const nsACString& aUTF8String)
michael@0:     { return NS_NewAtom(aUTF8String); }
michael@0: 
michael@0: /**
michael@0:  * Find an atom that matches the given UTF-16 string.
michael@0:  * The string is assumed to be zero terminated.  Never returns null.
michael@0:  */
michael@0: extern already_AddRefed<nsIAtom> NS_NewAtom(const char16_t* aUTF16String);
michael@0: inline already_AddRefed<nsIAtom> do_GetAtom(const char16_t* aUTF16String)
michael@0:     { return NS_NewAtom(aUTF16String); }
michael@0: 
michael@0: /**
michael@0:  * Find an atom that matches the given UTF-16 string.  Never returns null.
michael@0:  */
michael@0: extern already_AddRefed<nsIAtom> NS_NewAtom(const nsAString& aUTF16String);
michael@0: extern nsIAtom* NS_NewPermanentAtom(const nsAString& aUTF16String);
michael@0: inline already_AddRefed<nsIAtom> do_GetAtom(const nsAString& aUTF16String)
michael@0:     { return NS_NewAtom(aUTF16String); }
michael@0: 
michael@0: /**
michael@0:  * Return a count of the total number of atoms currently
michael@0:  * alive in the system.
michael@0:  */
michael@0: extern nsrefcnt NS_GetNumberOfAtoms(void);
michael@0: 
michael@0: /**
michael@0:  * Return a pointer for a static atom for the string or null if there's 
michael@0:  * no static atom for this string.
michael@0:  */
michael@0: extern nsIAtom* NS_GetStaticAtom(const nsAString& aUTF16String);
michael@0: 
michael@0: /**
michael@0:  * Seal the static atom table
michael@0:  */
michael@0: extern void NS_SealStaticAtomTable();
michael@0: 
michael@0: class nsAtomString : public nsString
michael@0: {
michael@0: public:
michael@0:   nsAtomString(nsIAtom* aAtom)
michael@0:   {
michael@0:     aAtom->ToString(*this);
michael@0:   }
michael@0: };
michael@0: 
michael@0: class nsAtomCString : public nsCString
michael@0: {
michael@0: public:
michael@0:   nsAtomCString(nsIAtom* aAtom)
michael@0:   {
michael@0:     aAtom->ToUTF8String(*this);
michael@0:   }
michael@0: };
michael@0: 
michael@0: class nsDependentAtomString : public nsDependentString
michael@0: {
michael@0: public:
michael@0:   nsDependentAtomString(nsIAtom* aAtom)
michael@0:     : nsDependentString(aAtom->GetUTF16String(), aAtom->GetLength())
michael@0:   {
michael@0:   }
michael@0: };
michael@0: 
michael@0: %}