xpcom/glue/nsCOMArray.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is a COM aware array class.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corp.
  19  * Portions created by the Initial Developer are Copyright (C) 2002
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Alec Flett <alecf@netscape.com>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either the GNU General Public License Version 2 or later (the "GPL"), or
  27  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #ifndef nsCOMArray_h__
  40 #define nsCOMArray_h__
  41
  42 #include "nsVoidArray.h"
  43 #include "nsISupports.h"
  44
  45 // See below for the definition of nsCOMArray<T>
  46
  47 // a class that's nsISupports-specific, so that we can contain the
  48 // work of this class in the XPCOM dll
  49 class NS_COM_GLUE nsCOMArray_base
  50 {
  51     friend class nsArray;
  52 protected:
  53     nsCOMArray_base() {}
  54     nsCOMArray_base(PRInt32 aCount) : mArray(aCount) {}
  55     nsCOMArray_base(const nsCOMArray_base& other);
  56     ~nsCOMArray_base();
  57
  58     PRInt32 IndexOf(nsISupports* aObject) const {
  59         return mArray.IndexOf(aObject);
  60     }
  61
  62     PRInt32 IndexOfObject(nsISupports* aObject) const;
  63
  64     PRBool EnumerateForwards(nsVoidArrayEnumFunc aFunc, void* aData) {
  65         return mArray.EnumerateForwards(aFunc, aData);
  66     }
  67
  68     PRBool EnumerateBackwards(nsVoidArrayEnumFunc aFunc, void* aData) {
  69         return mArray.EnumerateBackwards(aFunc, aData);
  70     }
  71
  72     void Sort(nsVoidArrayComparatorFunc aFunc, void* aData) {
  73         mArray.Sort(aFunc, aData);
  74     }
  75
  76     // any method which is not a direct forward to mArray should
  77     // avoid inline bodies, so that the compiler doesn't inline them
  78     // all over the place
  79     void Clear();
  80     PRBool InsertObjectAt(nsISupports* aObject, PRInt32 aIndex);
  81     PRBool InsertObjectsAt(const nsCOMArray_base& aObjects, PRInt32 aIndex);
  82     PRBool ReplaceObjectAt(nsISupports* aObject, PRInt32 aIndex);
  83     PRBool AppendObject(nsISupports *aObject) {
  84         return InsertObjectAt(aObject, Count());
  85     }
  86     PRBool AppendObjects(const nsCOMArray_base& aObjects) {
  87         return InsertObjectsAt(aObjects, Count());
  88     }
  89     PRBool RemoveObject(nsISupports *aObject);
  90     PRBool RemoveObjectAt(PRInt32 aIndex);
  91
  92 public:
  93     // override nsVoidArray stuff so that they can be accessed by
  94     // consumers of nsCOMArray
  95     PRInt32 Count() const {
  96         return mArray.Count();
  97     }
  98
  99     nsISupports* ObjectAt(PRInt32 aIndex) const {
 100         return static_cast<nsISupports*>(mArray.FastElementAt(aIndex));
 101     }
 102
 103     nsISupports* SafeObjectAt(PRInt32 aIndex) const {
 104         return static_cast<nsISupports*>(mArray.SafeElementAt(aIndex));
 105     }
 106
 107     nsISupports* operator[](PRInt32 aIndex) const {
 108         return ObjectAt(aIndex);
 109     }
 110
 111     // Ensures there is enough space to store a total of aCapacity objects.
 112     // This method never deletes any objects.
 113     PRBool SetCapacity(PRUint32 aCapacity) {
 114       return aCapacity > 0 ? mArray.SizeTo(static_cast<PRInt32>(aCapacity))
 115                            : PR_TRUE;
 116     }
 117
 118 private:
 119
 120     // the actual storage
 121     nsVoidArray mArray;
 122
 123     // don't implement these, defaults will muck with refcounts!
 124     nsCOMArray_base& operator=(const nsCOMArray_base& other);
 125 };
 126
 127 // a non-XPCOM, refcounting array of XPCOM objects
 128 // used as a member variable or stack variable - this object is NOT
 129 // refcounted, but the objects that it holds are
 130 //
 131 // most of the read-only accessors like ObjectAt()/etc do NOT refcount
 132 // on the way out. This means that you can do one of two things:
 133 //
 134 // * does an addref, but holds onto a reference
 135 // nsCOMPtr<T> foo = array[i];
 136 //
 137 // * avoids the refcount, but foo might go stale if array[i] is ever
 138 // * modified/removed. Be careful not to NS_RELEASE(foo)!
 139 // T* foo = array[i];
 140 //
 141 // This array will accept null as an argument for any object, and will
 142 // store null in the array, just like nsVoidArray. But that also means
 143 // that methods like ObjectAt() may return null when referring to an
 144 // existing, but null entry in the array.
 145 template <class T>
 146 class nsCOMArray : public nsCOMArray_base
 147 {
 148  public:
 149     nsCOMArray() {}
 150     nsCOMArray(PRInt32 aCount) : nsCOMArray_base(aCount) {}
 151
 152     // only to be used by trusted classes who are going to pass us the
 153     // right type!
 154     nsCOMArray(const nsCOMArray<T>& aOther) : nsCOMArray_base(aOther) { }
 155
 156     ~nsCOMArray() {}
 157
 158     // these do NOT refcount on the way out, for speed
 159     T* ObjectAt(PRInt32 aIndex) const {
 160         return static_cast<T*>(nsCOMArray_base::ObjectAt(aIndex));
 161     }
 162
 163     // these do NOT refcount on the way out, for speed
 164     T* SafeObjectAt(PRInt32 aIndex) const {
 165         return static_cast<T*>(nsCOMArray_base::SafeObjectAt(aIndex));
 166     }
 167
 168     // indexing operator for syntactic sugar
 169     T* operator[](PRInt32 aIndex) const {
 170         return ObjectAt(aIndex);
 171     }
 172
 173     // index of the element in question.. does NOT refcount
 174     // note: this does not check COM object identity. Use
 175     // IndexOfObject() for that purpose
 176     PRInt32 IndexOf(T* aObject) const {
 177         return nsCOMArray_base::IndexOf(static_cast<nsISupports*>(aObject));
 178     }
 179
 180     // index of the element in question.. be careful!
 181     // this is much slower than IndexOf() because it uses
 182     // QueryInterface to determine actual COM identity of the object
 183     // if you need to do this frequently then consider enforcing
 184     // COM object identity before adding/comparing elements
 185     PRInt32 IndexOfObject(T* aObject) const {
 186         return nsCOMArray_base::IndexOfObject(static_cast<nsISupports*>(aObject));
 187     }
 188
 189     // inserts aObject at aIndex, shifting the objects at aIndex and
 190     // later to make space
 191     PRBool InsertObjectAt(T* aObject, PRInt32 aIndex) {
 192         return nsCOMArray_base::InsertObjectAt(static_cast<nsISupports*>(aObject), aIndex);
 193     }
 194
 195     // inserts the objects from aObject at aIndex, shifting the
 196     // objects at aIndex and later to make space
 197     PRBool InsertObjectsAt(const nsCOMArray<T>& aObjects, PRInt32 aIndex) {
 198         return nsCOMArray_base::InsertObjectsAt(aObjects, aIndex);
 199     }
 200
 201     // replaces an existing element. Warning: if the array grows,
 202     // the newly created entries will all be null
 203     PRBool ReplaceObjectAt(T* aObject, PRInt32 aIndex) {
 204         return nsCOMArray_base::ReplaceObjectAt(static_cast<nsISupports*>(aObject), aIndex);
 205     }
 206
 207     // override nsVoidArray stuff so that they can be accessed by
 208     // other methods
 209
 210     // elements in the array (including null elements!)
 211     PRInt32 Count() const {
 212         return nsCOMArray_base::Count();
 213     }
 214
 215     // remove all elements in the array, and call NS_RELEASE on each one
 216     void Clear() {
 217         nsCOMArray_base::Clear();
 218     }
 219
 220     // Enumerator callback function. Return PR_FALSE to stop
 221     // Here's a more readable form:
 222     // PRBool enumerate(T* aElement, void* aData)
 223     typedef PRBool (* nsCOMArrayEnumFunc)
 224         (T* aElement, void *aData);
 225
 226     // enumerate through the array with a callback.
 227     PRBool EnumerateForwards(nsCOMArrayEnumFunc aFunc, void* aData) {
 228         return nsCOMArray_base::EnumerateForwards(nsVoidArrayEnumFunc(aFunc),
 229                                                   aData);
 230     }
 231
 232     PRBool EnumerateBackwards(nsCOMArrayEnumFunc aFunc, void* aData) {
 233         return nsCOMArray_base::EnumerateBackwards(nsVoidArrayEnumFunc(aFunc),
 234                                                   aData);
 235     }
 236
 237     typedef int (* nsCOMArrayComparatorFunc)
 238         (T* aElement1, T* aElement2, void* aData);
 239
 240     void Sort(nsCOMArrayComparatorFunc aFunc, void* aData) {
 241         nsCOMArray_base::Sort(nsVoidArrayComparatorFunc(aFunc), aData);
 242     }
 243
 244     // append an object, growing the array as necessary
 245     PRBool AppendObject(T *aObject) {
 246         return nsCOMArray_base::AppendObject(static_cast<nsISupports*>(aObject));
 247     }
 248
 249     // append objects, growing the array as necessary
 250     PRBool AppendObjects(const nsCOMArray<T>& aObjects) {
 251         return nsCOMArray_base::AppendObjects(aObjects);
 252     }
 253
 254     // remove the first instance of the given object and shrink the
 255     // array as necessary
 256     // Warning: if you pass null here, it will remove the first null element
 257     PRBool RemoveObject(T *aObject) {
 258         return nsCOMArray_base::RemoveObject(static_cast<nsISupports*>(aObject));
 259     }
 260
 261     // remove an element at a specific position, shrinking the array
 262     // as necessary
 263     PRBool RemoveObjectAt(PRInt32 aIndex) {
 264         return nsCOMArray_base::RemoveObjectAt(aIndex);
 265     }
 266
 267 private:
 268
 269     // don't implement these!
 270     nsCOMArray<T>& operator=(const nsCOMArray<T>& other);
 271 };
 272
 273
 274 #endif