1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/ds/nsIAtom.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,174 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +%{C++
1.11 +#include "nsStringGlue.h"
1.12 +#include "nsCOMPtr.h"
1.13 +#include "nsStringBuffer.h"
1.14 +%}
1.15 +
1.16 +/*
1.17 + * Should this really be scriptable? Using atoms from script or proxies
1.18 + * could be dangerous since double-wrapping could lead to loss of
1.19 + * pointer identity.
1.20 + */
1.21 +
1.22 +[scriptable, builtinclass, uuid(1f341018-521a-49de-b806-1bef5c9a00b0)]
1.23 +interface nsIAtom : nsISupports
1.24 +{
1.25 + /**
1.26 + * Get the Unicode or UTF8 value for the string
1.27 + */
1.28 + [binaryname(ScriptableToString)] AString toString();
1.29 + [noscript] AUTF8String toUTF8String();
1.30 +
1.31 + /**
1.32 + * Compare the atom to a specific string value
1.33 + * Note that this will NEVER return/throw an error condition.
1.34 + */
1.35 + [binaryname(ScriptableEquals)] boolean equals(in AString aString);
1.36 +
1.37 + [noscript, notxpcom] boolean equalsUTF8(in AUTF8String aString);
1.38 +
1.39 + /**
1.40 + * Returns true if the atom is static and false otherwise.
1.41 + */
1.42 + [noscript, notxpcom] boolean isStaticAtom();
1.43 +
1.44 +%{C++
1.45 + // note this is NOT virtual so this won't muck with the vtable!
1.46 + inline bool Equals(const nsAString& aString) const {
1.47 + return aString.Equals(nsDependentString(mString, mLength));
1.48 + }
1.49 +
1.50 + inline char16ptr_t GetUTF16String() const {
1.51 + return mString;
1.52 + }
1.53 +
1.54 + inline const uint32_t GetLength() const {
1.55 + return mLength;
1.56 + }
1.57 +
1.58 + inline void ToString(nsAString& aBuf) {
1.59 + nsStringBuffer::FromData(mString)->ToString(mLength, aBuf);
1.60 + }
1.61 +
1.62 + inline nsStringBuffer* GetStringBuffer() const {
1.63 + return nsStringBuffer::FromData(mString);
1.64 + }
1.65 +
1.66 + /**
1.67 + * A hashcode that is better distributed than the actual atom
1.68 + * pointer, for use in situations that need a well-distributed
1.69 + * hashcode.
1.70 + */
1.71 + inline uint32_t hash() const {
1.72 + return mHash;
1.73 + }
1.74 +
1.75 +protected:
1.76 + uint32_t mLength;
1.77 + uint32_t mHash;
1.78 + char16_t* mString;
1.79 +%}
1.80 +};
1.81 +
1.82 +
1.83 +%{C++
1.84 +/*
1.85 + * The three forms of NS_NewAtom and do_GetAtom (for use with
1.86 + * |nsCOMPtr<nsIAtom>|) return the atom for the string given. At any
1.87 + * given time there will always be one atom representing a given string.
1.88 + * Atoms are intended to make string comparison cheaper by simplifying
1.89 + * it to pointer equality. A pointer to the atom that does not own a
1.90 + * reference is not guaranteed to be valid.
1.91 + *
1.92 + * The three forms of NS_NewPermanentAtom and do_GetPermanentAtom return
1.93 + * the atom for the given string and ensure that the atom is permanent.
1.94 + * An atom that is permanent will exist (occupy space at a specific
1.95 + * location in memory) until XPCOM is shut down. The advantage of
1.96 + * permanent atoms is that they do not need to maintain a reference
1.97 + * count, which requires locking and hurts performance.
1.98 + */
1.99 +
1.100 +
1.101 +/**
1.102 + * Find an atom that matches the given UTF-8 string.
1.103 + * The string is assumed to be zero terminated. Never returns null.
1.104 + */
1.105 +extern already_AddRefed<nsIAtom> NS_NewAtom(const char* aUTF8String);
1.106 +
1.107 +inline already_AddRefed<nsIAtom> do_GetAtom(const char* aUTF8String)
1.108 + { return NS_NewAtom(aUTF8String); }
1.109 +
1.110 +/**
1.111 + * Find an atom that matches the given UTF-8 string. Never returns null.
1.112 + */
1.113 +extern already_AddRefed<nsIAtom> NS_NewAtom(const nsACString& aUTF8String);
1.114 +inline already_AddRefed<nsIAtom> do_GetAtom(const nsACString& aUTF8String)
1.115 + { return NS_NewAtom(aUTF8String); }
1.116 +
1.117 +/**
1.118 + * Find an atom that matches the given UTF-16 string.
1.119 + * The string is assumed to be zero terminated. Never returns null.
1.120 + */
1.121 +extern already_AddRefed<nsIAtom> NS_NewAtom(const char16_t* aUTF16String);
1.122 +inline already_AddRefed<nsIAtom> do_GetAtom(const char16_t* aUTF16String)
1.123 + { return NS_NewAtom(aUTF16String); }
1.124 +
1.125 +/**
1.126 + * Find an atom that matches the given UTF-16 string. Never returns null.
1.127 + */
1.128 +extern already_AddRefed<nsIAtom> NS_NewAtom(const nsAString& aUTF16String);
1.129 +extern nsIAtom* NS_NewPermanentAtom(const nsAString& aUTF16String);
1.130 +inline already_AddRefed<nsIAtom> do_GetAtom(const nsAString& aUTF16String)
1.131 + { return NS_NewAtom(aUTF16String); }
1.132 +
1.133 +/**
1.134 + * Return a count of the total number of atoms currently
1.135 + * alive in the system.
1.136 + */
1.137 +extern nsrefcnt NS_GetNumberOfAtoms(void);
1.138 +
1.139 +/**
1.140 + * Return a pointer for a static atom for the string or null if there's
1.141 + * no static atom for this string.
1.142 + */
1.143 +extern nsIAtom* NS_GetStaticAtom(const nsAString& aUTF16String);
1.144 +
1.145 +/**
1.146 + * Seal the static atom table
1.147 + */
1.148 +extern void NS_SealStaticAtomTable();
1.149 +
1.150 +class nsAtomString : public nsString
1.151 +{
1.152 +public:
1.153 + nsAtomString(nsIAtom* aAtom)
1.154 + {
1.155 + aAtom->ToString(*this);
1.156 + }
1.157 +};
1.158 +
1.159 +class nsAtomCString : public nsCString
1.160 +{
1.161 +public:
1.162 + nsAtomCString(nsIAtom* aAtom)
1.163 + {
1.164 + aAtom->ToUTF8String(*this);
1.165 + }
1.166 +};
1.167 +
1.168 +class nsDependentAtomString : public nsDependentString
1.169 +{
1.170 +public:
1.171 + nsDependentAtomString(nsIAtom* aAtom)
1.172 + : nsDependentString(aAtom->GetUTF16String(), aAtom->GetLength())
1.173 + {
1.174 + }
1.175 +};
1.176 +
1.177 +%}
