gecko-dev/xpcom/ds/nsIAtom.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"

%{C++
#include "nsStringGlue.h"
#include "nsCOMPtr.h"
#include "nsStringBuffer.h"
%}

native MallocSizeOf(mozilla::MallocSizeOf);

/*
 * Should this really be scriptable?  Using atoms from script or proxies
 * could be dangerous since double-wrapping could lead to loss of
 * pointer identity.
 */
 
[scriptable, builtinclass, uuid(8b8c11d4-3ed5-4079-8974-73c7576cdb34)]
interface nsIAtom : nsISupports
{
  /**
   * Get the Unicode or UTF8 value for the string
   */
  [binaryname(ScriptableToString)] AString toString(); 
  [noscript] AUTF8String toUTF8String();
  
  /**
   * Compare the atom to a specific string value
   * Note that this will NEVER return/throw an error condition.
   */
  [binaryname(ScriptableEquals)] boolean equals(in AString aString);

  [noscript, notxpcom]
  size_t SizeOfIncludingThis(in MallocSizeOf aMallocSizeOf);

%{C++
  // note this is NOT virtual so this won't muck with the vtable!
  inline bool Equals(const nsAString& aString) const {
    return aString.Equals(nsDependentString(mString, mLength));
  }

  inline bool IsStaticAtom() const {
    return mIsStatic;
  }

  inline char16ptr_t GetUTF16String() const {
    return mString;
  }

  inline uint32_t GetLength() const {
    return mLength;
  }

  inline void ToString(nsAString& aBuf) {
    // See the comment on |mString|'s declaration.
    nsStringBuffer::FromData(mString)->ToString(mLength, aBuf);
  }

  inline nsStringBuffer* GetStringBuffer() const {
    // See the comment on |mString|'s declaration.
    return nsStringBuffer::FromData(mString);
  }

  /**
   * A hashcode that is better distributed than the actual atom
   * pointer, for use in situations that need a well-distributed
   * hashcode.
   */
  inline uint32_t hash() const {
    return mHash;
  }

protected:
  uint32_t mLength:31;
  uint32_t mIsStatic:1;
  uint32_t mHash;
  /**
   * WARNING! There is an invisible constraint on |mString|: the chars it
   * points to must belong to an nsStringBuffer. This is so that the
   * nsStringBuffer::FromData() calls above are valid.
   */
  char16_t* mString;
%}
};


%{C++
/*
 * The four forms of NS_Atomize (for use with |nsCOMPtr<nsIAtom>|) return the
 * atom for the string given. At any given time there will always be one atom
 * representing a given string. Atoms are intended to make string comparison
 * cheaper by simplifying it to pointer equality. A pointer to the atom that
 * does not own a reference is not guaranteed to be valid.
 */


/**
 * Find an atom that matches the given UTF-8 string.
 * The string is assumed to be zero terminated.  Never returns null.
 */
extern already_AddRefed<nsIAtom> NS_Atomize(const char* aUTF8String);

/**
 * Find an atom that matches the given UTF-8 string.  Never returns null.
 */
extern already_AddRefed<nsIAtom> NS_Atomize(const nsACString& aUTF8String);

/**
 * Find an atom that matches the given UTF-16 string.
 * The string is assumed to be zero terminated.  Never returns null.
 */
extern already_AddRefed<nsIAtom> NS_Atomize(const char16_t* aUTF16String);

/**
 * Find an atom that matches the given UTF-16 string.  Never returns null.
 */
extern already_AddRefed<nsIAtom> NS_Atomize(const nsAString& aUTF16String);

/**
 * Return a count of the total number of atoms currently
 * alive in the system.
 */
extern nsrefcnt NS_GetNumberOfAtoms(void);

/**
 * Return a pointer for a static atom for the string or null if there's 
 * no static atom for this string.
 */
extern nsIAtom* NS_GetStaticAtom(const nsAString& aUTF16String);

/**
 * Seal the static atom table
 */
extern void NS_SealStaticAtomTable();

class nsAtomString : public nsString
{
public:
  explicit nsAtomString(nsIAtom* aAtom)
  {
    aAtom->ToString(*this);
  }
};

class nsAtomCString : public nsCString
{
public:
  explicit nsAtomCString(nsIAtom* aAtom)
  {
    aAtom->ToUTF8String(*this);
  }
};

class nsDependentAtomString : public nsDependentString
{
public:
  explicit nsDependentAtomString(nsIAtom* aAtom)
    : nsDependentString(aAtom->GetUTF16String(), aAtom->GetLength())
  {
  }
};

%}