xpcom/ds/nsIAtom.idl@6474c204b198
xpcom/ds/nsIAtom.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
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"
7 %{C++
8 #include "nsStringGlue.h"
9 #include "nsCOMPtr.h"
10 #include "nsStringBuffer.h"
11 %}
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 */
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();
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);
34 [noscript, notxpcom] boolean equalsUTF8(in AUTF8String aString);
36 /**
37 * Returns true if the atom is static and false otherwise.
38 */
39 [noscript, notxpcom] boolean isStaticAtom();
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 }
47 inline char16ptr_t GetUTF16String() const {
48 return mString;
49 }
51 inline const uint32_t GetLength() const {
52 return mLength;
53 }
55 inline void ToString(nsAString& aBuf) {
56 nsStringBuffer::FromData(mString)->ToString(mLength, aBuf);
57 }
59 inline nsStringBuffer* GetStringBuffer() const {
60 return nsStringBuffer::FromData(mString);
61 }
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 }
72 protected:
73 uint32_t mLength;
74 uint32_t mHash;
75 char16_t* mString;
76 %}
77 };
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 */
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);
104 inline already_AddRefed<nsIAtom> do_GetAtom(const char* aUTF8String)
105 { return NS_NewAtom(aUTF8String); }
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); }
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); }
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); }
130 /**
131 * Return a count of the total number of atoms currently
132 * alive in the system.
133 */
134 extern nsrefcnt NS_GetNumberOfAtoms(void);
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);
142 /**
143 * Seal the static atom table
144 */
145 extern void NS_SealStaticAtomTable();
147 class nsAtomString : public nsString
148 {
149 public:
150 nsAtomString(nsIAtom* aAtom)
151 {
152 aAtom->ToString(*this);
153 }
154 };
156 class nsAtomCString : public nsCString
157 {
158 public:
159 nsAtomCString(nsIAtom* aAtom)
160 {
161 aAtom->ToUTF8String(*this);
162 }
163 };
165 class nsDependentAtomString : public nsDependentString
166 {
167 public:
168 nsDependentAtomString(nsIAtom* aAtom)
169 : nsDependentString(aAtom->GetUTF16String(), aAtom->GetLength())
170 {
171 }
172 };
174 %}
