xpcom/ds/nsCOMArray.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef nsCOMArray_h__
   8 #define nsCOMArray_h__
   9
  10 #include "mozilla/Attributes.h"
  11 #include "mozilla/ArrayIterator.h"
  12 #include "mozilla/MemoryReporting.h"
  13
  14 #include "nsCycleCollectionNoteChild.h"
  15 #include "nsTArray.h"
  16 #include "nsISupports.h"
  17
  18 #include <iterator>
  19
  20 // See below for the definition of nsCOMArray<T>
  21
  22 // a class that's nsISupports-specific, so that we can contain the
  23 // work of this class in the XPCOM dll
  24 class nsCOMArray_base {
  25   friend class nsArrayBase;
  26
  27  protected:
  28   nsCOMArray_base() = default;
  29   explicit nsCOMArray_base(int32_t aCount) : mArray(aCount) {}
  30   nsCOMArray_base(const nsCOMArray_base& aOther);
  31   nsCOMArray_base(nsCOMArray_base&& aOther) = default;
  32   nsCOMArray_base& operator=(nsCOMArray_base&& aOther) = default;
  33   ~nsCOMArray_base();
  34
  35   int32_t IndexOf(nsISupports* aObject, uint32_t aStartIndex = 0) const;
  36   bool Contains(nsISupports* aObject) const { return IndexOf(aObject) != -1; }
  37
  38   int32_t IndexOfObject(nsISupports* aObject) const;
  39   bool ContainsObject(nsISupports* aObject) const {
  40     return IndexOfObject(aObject) != -1;
  41   }
  42
  43   typedef bool (*nsBaseArrayEnumFunc)(void* aElement, void* aData);
  44
  45   // enumerate through the array with a callback.
  46   bool EnumerateForwards(nsBaseArrayEnumFunc aFunc, void* aData) const;
  47
  48   bool EnumerateBackwards(nsBaseArrayEnumFunc aFunc, void* aData) const;
  49
  50   typedef int (*nsISupportsComparatorFunc)(nsISupports* aElement1,
  51                                            nsISupports* aElement2, void* aData);
  52
  53   struct nsISupportsComparatorContext {
  54     nsISupportsComparatorFunc mComparatorFunc;
  55     void* mData;
  56   };
  57
  58   static int VoidStarComparator(const void* aElement1, const void* aElement2,
  59                                 void* aData);
  60   void Sort(nsISupportsComparatorFunc aFunc, void* aData);
  61
  62   bool InsertObjectAt(nsISupports* aObject, int32_t aIndex);
  63   void InsertElementAt(uint32_t aIndex, nsISupports* aElement);
  64   void InsertElementAt(uint32_t aIndex, already_AddRefed<nsISupports> aElement);
  65   bool InsertObjectsAt(const nsCOMArray_base& aObjects, int32_t aIndex);
  66   void InsertElementsAt(uint32_t aIndex, const nsCOMArray_base& aElements);
  67   void InsertElementsAt(uint32_t aIndex, nsISupports* const* aElements,
  68                         uint32_t aCount);
  69   void ReplaceObjectAt(nsISupports* aObject, int32_t aIndex);
  70   void ReplaceElementAt(uint32_t aIndex, nsISupports* aElement) {
  71     nsISupports* oldElement = mArray[aIndex];
  72     NS_IF_ADDREF(mArray[aIndex] = aElement);
  73     NS_IF_RELEASE(oldElement);
  74   }
  75   bool AppendObject(nsISupports* aObject) {
  76     return InsertObjectAt(aObject, Count());
  77   }
  78   void AppendElement(nsISupports* aElement) {
  79     InsertElementAt(Length(), aElement);
  80   }
  81   void AppendElement(already_AddRefed<nsISupports> aElement) {
  82     InsertElementAt(Length(), std::move(aElement));
  83   }
  84
  85   bool AppendObjects(const nsCOMArray_base& aObjects) {
  86     return InsertObjectsAt(aObjects, Count());
  87   }
  88   void AppendElements(const nsCOMArray_base& aElements) {
  89     return InsertElementsAt(Length(), aElements);
  90   }
  91   void AppendElements(nsISupports* const* aElements, uint32_t aCount) {
  92     return InsertElementsAt(Length(), aElements, aCount);
  93   }
  94   bool RemoveObject(nsISupports* aObject);
  95   nsISupports** Elements() { return mArray.Elements(); }
  96   void SwapElements(nsCOMArray_base& aOther) {
  97     mArray.SwapElements(aOther.mArray);
  98   }
  99
 100  public:
 101   // elements in the array (including null elements!)
 102   int32_t Count() const { return mArray.Length(); }
 103   // nsTArray-compatible version
 104   uint32_t Length() const { return mArray.Length(); }
 105   bool IsEmpty() const { return mArray.IsEmpty(); }
 106
 107   // If the array grows, the newly created entries will all be null;
 108   // if the array shrinks, the excess entries will all be released.
 109   bool SetCount(int32_t aNewCount);
 110   // nsTArray-compatible version
 111   void TruncateLength(uint32_t aNewLength) {
 112     if (mArray.Length() > aNewLength) {
 113       RemoveElementsAt(aNewLength, mArray.Length() - aNewLength);
 114     }
 115   }
 116
 117   // remove all elements in the array, and call NS_RELEASE on each one
 118   void Clear();
 119
 120   nsISupports* ObjectAt(int32_t aIndex) const { return mArray[aIndex]; }
 121   // nsTArray-compatible version
 122   nsISupports* ElementAt(uint32_t aIndex) const { return mArray[aIndex]; }
 123
 124   nsISupports* SafeObjectAt(int32_t aIndex) const {
 125     return mArray.SafeElementAt(aIndex, nullptr);
 126   }
 127   // nsTArray-compatible version
 128   nsISupports* SafeElementAt(uint32_t aIndex) const {
 129     return mArray.SafeElementAt(aIndex, nullptr);
 130   }
 131
 132   nsISupports* operator[](int32_t aIndex) const { return mArray[aIndex]; }
 133
 134   // remove an element at a specific position, shrinking the array
 135   // as necessary
 136   bool RemoveObjectAt(int32_t aIndex);
 137   // nsTArray-compatible version
 138   void RemoveElementAt(uint32_t aIndex);
 139
 140   // remove a range of elements at a specific position, shrinking the array
 141   // as necessary
 142   bool RemoveObjectsAt(int32_t aIndex, int32_t aCount);
 143   // nsTArray-compatible version
 144   void RemoveElementsAt(uint32_t aIndex, uint32_t aCount);
 145
 146   void SwapElementsAt(uint32_t aIndex1, uint32_t aIndex2) {
 147     nsISupports* tmp = mArray[aIndex1];
 148     mArray[aIndex1] = mArray[aIndex2];
 149     mArray[aIndex2] = tmp;
 150   }
 151
 152   // Ensures there is enough space to store a total of aCapacity objects.
 153   // This method never deletes any objects.
 154   void SetCapacity(uint32_t aCapacity) { mArray.SetCapacity(aCapacity); }
 155   uint32_t Capacity() { return mArray.Capacity(); }
 156
 157   // Measures the size of the array's element storage. If you want to measure
 158   // anything hanging off the array, you must iterate over the elements and
 159   // measure them individually; hence the "Shallow" prefix. Note that because
 160   // each element in an nsCOMArray<T> is actually a T* any such iteration
 161   // should use a SizeOfIncludingThis() function on each element rather than a
 162   // SizeOfExcludingThis() function, so that the memory taken by the T itself
 163   // is included as well as anything it points to.
 164   size_t ShallowSizeOfExcludingThis(mozilla::MallocSizeOf aMallocSizeOf) const {
 165     return mArray.ShallowSizeOfExcludingThis(aMallocSizeOf);
 166   }
 167
 168  private:
 169   // the actual storage
 170   nsTArray<nsISupports*> mArray;
 171
 172   // don't implement these, defaults will muck with refcounts!
 173   nsCOMArray_base& operator=(const nsCOMArray_base& aOther) = delete;
 174 };
 175
 176 inline void ImplCycleCollectionUnlink(nsCOMArray_base& aField) {
 177   aField.Clear();
 178 }
 179
 180 inline void ImplCycleCollectionTraverse(
 181     nsCycleCollectionTraversalCallback& aCallback, nsCOMArray_base& aField,
 182     const char* aName, uint32_t aFlags = 0) {
 183   aFlags |= CycleCollectionEdgeNameArrayFlag;
 184   int32_t length = aField.Count();
 185   for (int32_t i = 0; i < length; ++i) {
 186     CycleCollectionNoteChild(aCallback, aField[i], aName, aFlags);
 187   }
 188 }
 189
 190 // a non-XPCOM, refcounting array of XPCOM objects
 191 // used as a member variable or stack variable - this object is NOT
 192 // refcounted, but the objects that it holds are
 193 //
 194 // most of the read-only accessors like ObjectAt()/etc do NOT refcount
 195 // on the way out. This means that you can do one of two things:
 196 //
 197 // * does an addref, but holds onto a reference
 198 // nsCOMPtr<T> foo = array[i];
 199 //
 200 // * avoids the refcount, but foo might go stale if array[i] is ever
 201 // * modified/removed. Be careful not to NS_RELEASE(foo)!
 202 // T* foo = array[i];
 203 //
 204 // This array will accept null as an argument for any object, and will store
 205 // null in the array. But that also means that methods like ObjectAt() may
 206 // return null when referring to an existing, but null entry in the array.
 207 template <class T>
 208 class nsCOMArray : public nsCOMArray_base {
 209  public:
 210   typedef int32_t index_type;
 211   typedef mozilla::ArrayIterator<T*, nsCOMArray> iterator;
 212   typedef mozilla::ArrayIterator<const T*, nsCOMArray> const_iterator;
 213   typedef std::reverse_iterator<iterator> reverse_iterator;
 214   typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
 215
 216   nsCOMArray() = default;
 217   explicit nsCOMArray(int32_t aCount) : nsCOMArray_base(aCount) {}
 218   explicit nsCOMArray(const nsCOMArray<T>& aOther) : nsCOMArray_base(aOther) {}
 219   nsCOMArray(nsCOMArray<T>&& aOther) = default;
 220   ~nsCOMArray() = default;
 221
 222   // We have a move assignment operator, but no copy assignment operator.
 223   nsCOMArray<T>& operator=(nsCOMArray<T>&& aOther) = default;
 224
 225   // these do NOT refcount on the way out, for speed
 226   T* ObjectAt(int32_t aIndex) const {
 227     return static_cast<T*>(nsCOMArray_base::ObjectAt(aIndex));
 228   }
 229   // nsTArray-compatible version
 230   T* ElementAt(uint32_t aIndex) const {
 231     return static_cast<T*>(nsCOMArray_base::ElementAt(aIndex));
 232   }
 233
 234   // these do NOT refcount on the way out, for speed
 235   T* SafeObjectAt(int32_t aIndex) const {
 236     return static_cast<T*>(nsCOMArray_base::SafeObjectAt(aIndex));
 237   }
 238   // nsTArray-compatible version
 239   T* SafeElementAt(uint32_t aIndex) const {
 240     return static_cast<T*>(nsCOMArray_base::SafeElementAt(aIndex));
 241   }
 242
 243   // indexing operator for syntactic sugar
 244   T* operator[](int32_t aIndex) const { return ObjectAt(aIndex); }
 245
 246   // index of the element in question.. does NOT refcount
 247   // note: this does not check COM object identity. Use
 248   // IndexOfObject() for that purpose
 249   int32_t IndexOf(T* aObject, uint32_t aStartIndex = 0) const {
 250     return nsCOMArray_base::IndexOf(aObject, aStartIndex);
 251   }
 252   bool Contains(T* aObject) const { return nsCOMArray_base::Contains(aObject); }
 253
 254   // index of the element in question.. be careful!
 255   // this is much slower than IndexOf() because it uses
 256   // QueryInterface to determine actual COM identity of the object
 257   // if you need to do this frequently then consider enforcing
 258   // COM object identity before adding/comparing elements
 259   int32_t IndexOfObject(T* aObject) const {
 260     return nsCOMArray_base::IndexOfObject(aObject);
 261   }
 262   bool ContainsObject(nsISupports* aObject) const {
 263     return nsCOMArray_base::ContainsObject(aObject);
 264   }
 265
 266   // inserts aObject at aIndex, shifting the objects at aIndex and
 267   // later to make space
 268   bool InsertObjectAt(T* aObject, int32_t aIndex) {
 269     return nsCOMArray_base::InsertObjectAt(aObject, aIndex);
 270   }
 271   // nsTArray-compatible version
 272   void InsertElementAt(uint32_t aIndex, T* aElement) {
 273     nsCOMArray_base::InsertElementAt(aIndex, aElement);
 274   }
 275
 276   // inserts the objects from aObject at aIndex, shifting the
 277   // objects at aIndex and later to make space
 278   bool InsertObjectsAt(const nsCOMArray<T>& aObjects, int32_t aIndex) {
 279     return nsCOMArray_base::InsertObjectsAt(aObjects, aIndex);
 280   }
 281   // nsTArray-compatible version
 282   void InsertElementsAt(uint32_t aIndex, const nsCOMArray<T>& aElements) {
 283     nsCOMArray_base::InsertElementsAt(aIndex, aElements);
 284   }
 285   void InsertElementsAt(uint32_t aIndex, T* const* aElements, uint32_t aCount) {
 286     nsCOMArray_base::InsertElementsAt(
 287         aIndex, reinterpret_cast<nsISupports* const*>(aElements), aCount);
 288   }
 289
 290   // replaces an existing element. Warning: if the array grows,
 291   // the newly created entries will all be null
 292   void ReplaceObjectAt(T* aObject, int32_t aIndex) {
 293     nsCOMArray_base::ReplaceObjectAt(aObject, aIndex);
 294   }
 295   // nsTArray-compatible version
 296   void ReplaceElementAt(uint32_t aIndex, T* aElement) {
 297     nsCOMArray_base::ReplaceElementAt(aIndex, aElement);
 298   }
 299
 300   typedef int (*TComparatorFunc)(T* aElement1, T* aElement2, void* aData);
 301
 302   struct TComparatorContext {
 303     TComparatorFunc mComparatorFunc;
 304     void* mData;
 305   };
 306
 307   static int nsISupportsComparator(nsISupports* aElement1,
 308                                    nsISupports* aElement2, void* aData) {
 309     auto ctx = static_cast<TComparatorContext*>(aData);
 310     return (*ctx->mComparatorFunc)(static_cast<T*>(aElement1),
 311                                    static_cast<T*>(aElement2), ctx->mData);
 312   }
 313
 314   void Sort(TComparatorFunc aFunc, void* aData) {
 315     TComparatorContext ctx = {aFunc, aData};
 316     nsCOMArray_base::Sort(nsISupportsComparator, &ctx);
 317   }
 318
 319   // append an object, growing the array as necessary
 320   bool AppendObject(T* aObject) {
 321     return nsCOMArray_base::AppendObject(aObject);
 322   }
 323   // nsTArray-compatible version
 324   void AppendElement(T* aElement) { nsCOMArray_base::AppendElement(aElement); }
 325   void AppendElement(already_AddRefed<T> aElement) {
 326     nsCOMArray_base::AppendElement(std::move(aElement));
 327   }
 328
 329   // append objects, growing the array as necessary
 330   bool AppendObjects(const nsCOMArray<T>& aObjects) {
 331     return nsCOMArray_base::AppendObjects(aObjects);
 332   }
 333   // nsTArray-compatible version
 334   void AppendElements(const nsCOMArray<T>& aElements) {
 335     return nsCOMArray_base::AppendElements(aElements);
 336   }
 337   void AppendElements(T* const* aElements, uint32_t aCount) {
 338     InsertElementsAt(Length(), aElements, aCount);
 339   }
 340
 341   // remove the first instance of the given object and shrink the
 342   // array as necessary
 343   // Warning: if you pass null here, it will remove the first null element
 344   bool RemoveObject(T* aObject) {
 345     return nsCOMArray_base::RemoveObject(aObject);
 346   }
 347   // nsTArray-compatible version
 348   bool RemoveElement(T* aElement) {
 349     return nsCOMArray_base::RemoveObject(aElement);
 350   }
 351
 352   T** Elements() { return reinterpret_cast<T**>(nsCOMArray_base::Elements()); }
 353   void SwapElements(nsCOMArray<T>& aOther) {
 354     nsCOMArray_base::SwapElements(aOther);
 355   }
 356
 357   // Methods for range-based for loops.
 358   iterator begin() { return iterator(*this, 0); }
 359   const_iterator begin() const { return const_iterator(*this, 0); }
 360   const_iterator cbegin() const { return begin(); }
 361   iterator end() { return iterator(*this, Length()); }
 362   const_iterator end() const { return const_iterator(*this, Length()); }
 363   const_iterator cend() const { return end(); }
 364
 365   // Methods for reverse iterating.
 366   reverse_iterator rbegin() { return reverse_iterator(end()); }
 367   const_reverse_iterator rbegin() const {
 368     return const_reverse_iterator(end());
 369   }
 370   const_reverse_iterator crbegin() const { return rbegin(); }
 371   reverse_iterator rend() { return reverse_iterator(begin()); }
 372   const_reverse_iterator rend() const {
 373     return const_reverse_iterator(begin());
 374   }
 375   const_reverse_iterator crend() const { return rend(); }
 376
 377  private:
 378   // don't implement these!
 379   nsCOMArray<T>& operator=(const nsCOMArray<T>& aOther) = delete;
 380 };
 381
 382 template <typename T>
 383 inline void ImplCycleCollectionUnlink(nsCOMArray<T>& aField) {
 384   aField.Clear();
 385 }
 386
 387 template <typename E>
 388 inline void ImplCycleCollectionTraverse(
 389     nsCycleCollectionTraversalCallback& aCallback, nsCOMArray<E>& aField,
 390     const char* aName, uint32_t aFlags = 0) {
 391   aFlags |= CycleCollectionEdgeNameArrayFlag;
 392   int32_t length = aField.Count();
 393   for (int32_t i = 0; i < length; ++i) {
 394     CycleCollectionNoteChild(aCallback, aField[i], aName, aFlags);
 395   }
 396 }
 397
 398 #endif