summaryrefslogtreecommitdiffstats
path: root/xpcom/glue/nsCOMArray.h
diff options
context:
space:
mode:
Diffstat (limited to 'xpcom/glue/nsCOMArray.h')
-rw-r--r--xpcom/glue/nsCOMArray.h473
1 files changed, 473 insertions, 0 deletions
diff --git a/xpcom/glue/nsCOMArray.h b/xpcom/glue/nsCOMArray.h
new file mode 100644
index 000000000..56d077a2f
--- /dev/null
+++ b/xpcom/glue/nsCOMArray.h
@@ -0,0 +1,473 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* vim: set ts=8 sts=2 et sw=2 tw=80: */
+/* 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/. */
+
+#ifndef nsCOMArray_h__
+#define nsCOMArray_h__
+
+#include "mozilla/Attributes.h"
+#include "mozilla/MemoryReporting.h"
+
+#include "nsCycleCollectionNoteChild.h"
+#include "nsTArray.h"
+#include "nsISupports.h"
+
+// See below for the definition of nsCOMArray<T>
+
+// a class that's nsISupports-specific, so that we can contain the
+// work of this class in the XPCOM dll
+class nsCOMArray_base
+{
+ friend class nsArrayBase;
+protected:
+ nsCOMArray_base() {}
+ explicit nsCOMArray_base(int32_t aCount) : mArray(aCount) {}
+ nsCOMArray_base(const nsCOMArray_base& aOther);
+ ~nsCOMArray_base();
+
+ int32_t IndexOf(nsISupports* aObject, uint32_t aStartIndex = 0) const;
+ bool Contains(nsISupports* aObject) const
+ {
+ return IndexOf(aObject) != -1;
+ }
+
+ int32_t IndexOfObject(nsISupports* aObject) const;
+ bool ContainsObject(nsISupports* aObject) const
+ {
+ return IndexOfObject(aObject) != -1;
+ }
+
+ typedef bool (*nsBaseArrayEnumFunc)(void* aElement, void* aData);
+
+ // enumerate through the array with a callback.
+ bool EnumerateForwards(nsBaseArrayEnumFunc aFunc, void* aData) const;
+
+ bool EnumerateBackwards(nsBaseArrayEnumFunc aFunc, void* aData) const;
+
+ typedef int (*nsBaseArrayComparatorFunc)(nsISupports* aElement1,
+ nsISupports* aElement2,
+ void* aData);
+
+ struct nsCOMArrayComparatorContext
+ {
+ nsBaseArrayComparatorFunc mComparatorFunc;
+ void* mData;
+ };
+
+ static int nsCOMArrayComparator(const void* aElement1, const void* aElement2,
+ void* aData);
+ void Sort(nsBaseArrayComparatorFunc aFunc, void* aData);
+
+ bool InsertObjectAt(nsISupports* aObject, int32_t aIndex);
+ void InsertElementAt(uint32_t aIndex, nsISupports* aElement);
+ void InsertElementAt(uint32_t aIndex, already_AddRefed<nsISupports> aElement);
+ bool InsertObjectsAt(const nsCOMArray_base& aObjects, int32_t aIndex);
+ void InsertElementsAt(uint32_t aIndex, const nsCOMArray_base& aElements);
+ void InsertElementsAt(uint32_t aIndex, nsISupports* const* aElements,
+ uint32_t aCount);
+ void ReplaceObjectAt(nsISupports* aObject, int32_t aIndex);
+ void ReplaceElementAt(uint32_t aIndex, nsISupports* aElement)
+ {
+ nsISupports* oldElement = mArray[aIndex];
+ NS_IF_ADDREF(mArray[aIndex] = aElement);
+ NS_IF_RELEASE(oldElement);
+ }
+ bool AppendObject(nsISupports* aObject)
+ {
+ return InsertObjectAt(aObject, Count());
+ }
+ void AppendElement(nsISupports* aElement)
+ {
+ InsertElementAt(Length(), aElement);
+ }
+ void AppendElement(already_AddRefed<nsISupports> aElement)
+ {
+ InsertElementAt(Length(), mozilla::Move(aElement));
+ }
+
+ bool AppendObjects(const nsCOMArray_base& aObjects)
+ {
+ return InsertObjectsAt(aObjects, Count());
+ }
+ void AppendElements(const nsCOMArray_base& aElements)
+ {
+ return InsertElementsAt(Length(), aElements);
+ }
+ void AppendElements(nsISupports* const* aElements, uint32_t aCount)
+ {
+ return InsertElementsAt(Length(), aElements, aCount);
+ }
+ bool RemoveObject(nsISupports* aObject);
+ nsISupports** Elements() { return mArray.Elements(); }
+ void SwapElements(nsCOMArray_base& aOther)
+ {
+ mArray.SwapElements(aOther.mArray);
+ }
+
+ void Adopt(nsISupports** aElements, uint32_t aCount);
+ uint32_t Forget(nsISupports*** aElements);
+public:
+ // elements in the array (including null elements!)
+ int32_t Count() const { return mArray.Length(); }
+ // nsTArray-compatible version
+ uint32_t Length() const { return mArray.Length(); }
+ bool IsEmpty() const { return mArray.IsEmpty(); }
+
+ // If the array grows, the newly created entries will all be null;
+ // if the array shrinks, the excess entries will all be released.
+ bool SetCount(int32_t aNewCount);
+ // nsTArray-compatible version
+ void TruncateLength(uint32_t aNewLength)
+ {
+ if (mArray.Length() > aNewLength) {
+ RemoveElementsAt(aNewLength, mArray.Length() - aNewLength);
+ }
+ }
+
+ // remove all elements in the array, and call NS_RELEASE on each one
+ void Clear();
+
+ nsISupports* ObjectAt(int32_t aIndex) const { return mArray[aIndex]; }
+ // nsTArray-compatible version
+ nsISupports* ElementAt(uint32_t aIndex) const { return mArray[aIndex]; }
+
+ nsISupports* SafeObjectAt(int32_t aIndex) const
+ {
+ return mArray.SafeElementAt(aIndex, nullptr);
+ }
+ // nsTArray-compatible version
+ nsISupports* SafeElementAt(uint32_t aIndex) const
+ {
+ return mArray.SafeElementAt(aIndex, nullptr);
+ }
+
+ nsISupports* operator[](int32_t aIndex) const { return mArray[aIndex]; }
+
+ // remove an element at a specific position, shrinking the array
+ // as necessary
+ bool RemoveObjectAt(int32_t aIndex);
+ // nsTArray-compatible version
+ void RemoveElementAt(uint32_t aIndex);
+
+ // remove a range of elements at a specific position, shrinking the array
+ // as necessary
+ bool RemoveObjectsAt(int32_t aIndex, int32_t aCount);
+ // nsTArray-compatible version
+ void RemoveElementsAt(uint32_t aIndex, uint32_t aCount);
+
+ void SwapElementsAt(uint32_t aIndex1, uint32_t aIndex2)
+ {
+ nsISupports* tmp = mArray[aIndex1];
+ mArray[aIndex1] = mArray[aIndex2];
+ mArray[aIndex2] = tmp;
+ }
+
+ // Ensures there is enough space to store a total of aCapacity objects.
+ // This method never deletes any objects.
+ void SetCapacity(uint32_t aCapacity) { mArray.SetCapacity(aCapacity); }
+ uint32_t Capacity() { return mArray.Capacity(); }
+
+ // Measures the size of the array's element storage. If you want to measure
+ // anything hanging off the array, you must iterate over the elements and
+ // measure them individually; hence the "Shallow" prefix. Note that because
+ // each element in an nsCOMArray<T> is actually a T* any such iteration
+ // should use a SizeOfIncludingThis() function on each element rather than a
+ // SizeOfExcludingThis() function, so that the memory taken by the T itself
+ // is included as well as anything it points to.
+ size_t ShallowSizeOfExcludingThis(mozilla::MallocSizeOf aMallocSizeOf) const
+ {
+ return mArray.ShallowSizeOfExcludingThis(aMallocSizeOf);
+ }
+
+private:
+
+ // the actual storage
+ nsTArray<nsISupports*> mArray;
+
+ // don't implement these, defaults will muck with refcounts!
+ nsCOMArray_base& operator=(const nsCOMArray_base& aOther) = delete;
+};
+
+inline void
+ImplCycleCollectionUnlink(nsCOMArray_base& aField)
+{
+ aField.Clear();
+}
+
+inline void
+ImplCycleCollectionTraverse(nsCycleCollectionTraversalCallback& aCallback,
+ nsCOMArray_base& aField,
+ const char* aName,
+ uint32_t aFlags = 0)
+{
+ aFlags |= CycleCollectionEdgeNameArrayFlag;
+ int32_t length = aField.Count();
+ for (int32_t i = 0; i < length; ++i) {
+ CycleCollectionNoteChild(aCallback, aField[i], aName, aFlags);
+ }
+}
+
+
+// a non-XPCOM, refcounting array of XPCOM objects
+// used as a member variable or stack variable - this object is NOT
+// refcounted, but the objects that it holds are
+//
+// most of the read-only accessors like ObjectAt()/etc do NOT refcount
+// on the way out. This means that you can do one of two things:
+//
+// * does an addref, but holds onto a reference
+// nsCOMPtr<T> foo = array[i];
+//
+// * avoids the refcount, but foo might go stale if array[i] is ever
+// * modified/removed. Be careful not to NS_RELEASE(foo)!
+// T* foo = array[i];
+//
+// This array will accept null as an argument for any object, and will store
+// null in the array. But that also means that methods like ObjectAt() may
+// return null when referring to an existing, but null entry in the array.
+template<class T>
+class nsCOMArray : public nsCOMArray_base
+{
+public:
+ nsCOMArray() {}
+ explicit nsCOMArray(int32_t aCount) : nsCOMArray_base(aCount) {}
+ explicit nsCOMArray(const nsCOMArray<T>& aOther) : nsCOMArray_base(aOther) {}
+ nsCOMArray(nsCOMArray<T>&& aOther) { SwapElements(aOther); }
+ ~nsCOMArray() {}
+
+ // We have a move assignment operator, but no copy assignment operator.
+ nsCOMArray<T>& operator=(nsCOMArray<T> && aOther)
+ {
+ SwapElements(aOther);
+ return *this;
+ }
+
+ // these do NOT refcount on the way out, for speed
+ T* ObjectAt(int32_t aIndex) const
+ {
+ return static_cast<T*>(nsCOMArray_base::ObjectAt(aIndex));
+ }
+ // nsTArray-compatible version
+ T* ElementAt(uint32_t aIndex) const
+ {
+ return static_cast<T*>(nsCOMArray_base::ElementAt(aIndex));
+ }
+
+ // these do NOT refcount on the way out, for speed
+ T* SafeObjectAt(int32_t aIndex) const
+ {
+ return static_cast<T*>(nsCOMArray_base::SafeObjectAt(aIndex));
+ }
+ // nsTArray-compatible version
+ T* SafeElementAt(uint32_t aIndex) const
+ {
+ return static_cast<T*>(nsCOMArray_base::SafeElementAt(aIndex));
+ }
+
+ // indexing operator for syntactic sugar
+ T* operator[](int32_t aIndex) const { return ObjectAt(aIndex); }
+
+ // index of the element in question.. does NOT refcount
+ // note: this does not check COM object identity. Use
+ // IndexOfObject() for that purpose
+ int32_t IndexOf(T* aObject, uint32_t aStartIndex = 0) const
+ {
+ return nsCOMArray_base::IndexOf(aObject, aStartIndex);
+ }
+ bool Contains(T* aObject) const
+ {
+ return nsCOMArray_base::Contains(aObject);
+ }
+
+ // index of the element in question.. be careful!
+ // this is much slower than IndexOf() because it uses
+ // QueryInterface to determine actual COM identity of the object
+ // if you need to do this frequently then consider enforcing
+ // COM object identity before adding/comparing elements
+ int32_t IndexOfObject(T* aObject) const
+ {
+ return nsCOMArray_base::IndexOfObject(aObject);
+ }
+ bool ContainsObject(nsISupports* aObject) const
+ {
+ return nsCOMArray_base::ContainsObject(aObject);
+ }
+
+ // inserts aObject at aIndex, shifting the objects at aIndex and
+ // later to make space
+ bool InsertObjectAt(T* aObject, int32_t aIndex)
+ {
+ return nsCOMArray_base::InsertObjectAt(aObject, aIndex);
+ }
+ // nsTArray-compatible version
+ void InsertElementAt(uint32_t aIndex, T* aElement)
+ {
+ nsCOMArray_base::InsertElementAt(aIndex, aElement);
+ }
+
+ // inserts the objects from aObject at aIndex, shifting the
+ // objects at aIndex and later to make space
+ bool InsertObjectsAt(const nsCOMArray<T>& aObjects, int32_t aIndex)
+ {
+ return nsCOMArray_base::InsertObjectsAt(aObjects, aIndex);
+ }
+ // nsTArray-compatible version
+ void InsertElementsAt(uint32_t aIndex, const nsCOMArray<T>& aElements)
+ {
+ nsCOMArray_base::InsertElementsAt(aIndex, aElements);
+ }
+ void InsertElementsAt(uint32_t aIndex, T* const* aElements, uint32_t aCount)
+ {
+ nsCOMArray_base::InsertElementsAt(
+ aIndex, reinterpret_cast<nsISupports* const*>(aElements), aCount);
+ }
+
+ // replaces an existing element. Warning: if the array grows,
+ // the newly created entries will all be null
+ void ReplaceObjectAt(T* aObject, int32_t aIndex)
+ {
+ nsCOMArray_base::ReplaceObjectAt(aObject, aIndex);
+ }
+ // nsTArray-compatible version
+ void ReplaceElementAt(uint32_t aIndex, T* aElement)
+ {
+ nsCOMArray_base::ReplaceElementAt(aIndex, aElement);
+ }
+
+ // Enumerator callback function. Return false to stop
+ // Here's a more readable form:
+ // bool enumerate(T* aElement, void* aData)
+ typedef bool (*nsCOMArrayEnumFunc)(T* aElement, void* aData);
+
+ // enumerate through the array with a callback.
+ bool EnumerateForwards(nsCOMArrayEnumFunc aFunc, void* aData)
+ {
+ return nsCOMArray_base::EnumerateForwards(nsBaseArrayEnumFunc(aFunc),
+ aData);
+ }
+
+ bool EnumerateBackwards(nsCOMArrayEnumFunc aFunc, void* aData)
+ {
+ return nsCOMArray_base::EnumerateBackwards(nsBaseArrayEnumFunc(aFunc),
+ aData);
+ }
+
+ typedef int (*nsCOMArrayComparatorFunc)(T* aElement1, T* aElement2,
+ void* aData);
+
+ void Sort(nsCOMArrayComparatorFunc aFunc, void* aData)
+ {
+ nsCOMArray_base::Sort(nsBaseArrayComparatorFunc(aFunc), aData);
+ }
+
+ // append an object, growing the array as necessary
+ bool AppendObject(T* aObject)
+ {
+ return nsCOMArray_base::AppendObject(aObject);
+ }
+ // nsTArray-compatible version
+ void AppendElement(T* aElement)
+ {
+ nsCOMArray_base::AppendElement(aElement);
+ }
+ void AppendElement(already_AddRefed<T> aElement)
+ {
+ nsCOMArray_base::AppendElement(mozilla::Move(aElement));
+ }
+
+ // append objects, growing the array as necessary
+ bool AppendObjects(const nsCOMArray<T>& aObjects)
+ {
+ return nsCOMArray_base::AppendObjects(aObjects);
+ }
+ // nsTArray-compatible version
+ void AppendElements(const nsCOMArray<T>& aElements)
+ {
+ return nsCOMArray_base::AppendElements(aElements);
+ }
+ void AppendElements(T* const* aElements, uint32_t aCount)
+ {
+ InsertElementsAt(Length(), aElements, aCount);
+ }
+
+ // remove the first instance of the given object and shrink the
+ // array as necessary
+ // Warning: if you pass null here, it will remove the first null element
+ bool RemoveObject(T* aObject)
+ {
+ return nsCOMArray_base::RemoveObject(aObject);
+ }
+ // nsTArray-compatible version
+ bool RemoveElement(T* aElement)
+ {
+ return nsCOMArray_base::RemoveObject(aElement);
+ }
+
+ T** Elements()
+ {
+ return reinterpret_cast<T**>(nsCOMArray_base::Elements());
+ }
+ void SwapElements(nsCOMArray<T>& aOther)
+ {
+ nsCOMArray_base::SwapElements(aOther);
+ }
+
+ /**
+ * Adopt parameters that resulted from an XPIDL outparam. The aElements
+ * parameter will be freed as a result of the call.
+ *
+ * Example usage:
+ * nsCOMArray<nsISomeInterface> array;
+ * nsISomeInterface** elements;
+ * uint32_t length;
+ * ptr->GetSomeArray(&elements, &length);
+ * array.Adopt(elements, length);
+ */
+ void Adopt(T** aElements, uint32_t aSize)
+ {
+ nsCOMArray_base::Adopt(reinterpret_cast<nsISupports**>(aElements), aSize);
+ }
+
+ /**
+ * Export the contents of this array to an XPIDL outparam. The array will be
+ * Clear()'d after this operation.
+ *
+ * Example usage:
+ * nsCOMArray<nsISomeInterface> array;
+ * *length = array.Forget(retval);
+ */
+ uint32_t Forget(T*** aElements)
+ {
+ return nsCOMArray_base::Forget(reinterpret_cast<nsISupports***>(aElements));
+ }
+
+private:
+
+ // don't implement these!
+ nsCOMArray<T>& operator=(const nsCOMArray<T>& aOther) = delete;
+};
+
+template<typename T>
+inline void
+ImplCycleCollectionUnlink(nsCOMArray<T>& aField)
+{
+ aField.Clear();
+}
+
+template<typename E>
+inline void
+ImplCycleCollectionTraverse(nsCycleCollectionTraversalCallback& aCallback,
+ nsCOMArray<E>& aField,
+ const char* aName,
+ uint32_t aFlags = 0)
+{
+ aFlags |= CycleCollectionEdgeNameArrayFlag;
+ int32_t length = aField.Count();
+ for (int32_t i = 0; i < length; ++i) {
+ CycleCollectionNoteChild(aCallback, aField[i], aName, aFlags);
+ }
+}
+
+#endif