Back to index

lightning-sunbird  0.9+nobinonly
nsCOMArray.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is a COM aware array class.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corp.
00019  * Portions created by the Initial Developer are Copyright (C) 2002
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *   Alec Flett <alecf@netscape.com>
00024  *
00025  * Alternatively, the contents of this file may be used under the terms of
00026  * either the GNU General Public License Version 2 or later (the "GPL"), or
00027  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00028  * in which case the provisions of the GPL or the LGPL are applicable instead
00029  * of those above. If you wish to allow use of your version of this file only
00030  * under the terms of either the GPL or the LGPL, and not to allow others to
00031  * use your version of this file under the terms of the MPL, indicate your
00032  * decision by deleting the provisions above and replace them with the notice
00033  * and other provisions required by the GPL or the LGPL. If you do not delete
00034  * the provisions above, a recipient may use your version of this file under
00035  * the terms of any one of the MPL, the GPL or the LGPL.
00036  *
00037  * ***** END LICENSE BLOCK ***** */
00038 
00039 #ifndef nsCOMArray_h__
00040 #define nsCOMArray_h__
00041 
00042 #include "nsVoidArray.h"
00043 #include "nsISupports.h"
00044 
00045 // See below for the definition of nsCOMArray<T>
00046 
00047 // a class that's nsISupports-specific, so that we can contain the
00048 // work of this class in the XPCOM dll
00049 class NS_COM nsCOMArray_base
00050 {
00051     friend class nsArray;
00052 protected:
00053     nsCOMArray_base() {}
00054     nsCOMArray_base(PRInt32 aCount) : mArray(aCount) {}
00055     nsCOMArray_base(const nsCOMArray_base& other);
00056     ~nsCOMArray_base();
00057 
00058     PRInt32 IndexOf(nsISupports* aObject) const {
00059         return mArray.IndexOf(aObject);
00060     }
00061 
00062     PRInt32 IndexOfObject(nsISupports* aObject) const;
00063 
00064     PRBool EnumerateForwards(nsVoidArrayEnumFunc aFunc, void* aData) {
00065         return mArray.EnumerateForwards(aFunc, aData);
00066     }
00067     
00068     PRBool EnumerateBackwards(nsVoidArrayEnumFunc aFunc, void* aData) {
00069         return mArray.EnumerateBackwards(aFunc, aData);
00070     }
00071     
00072     void Sort(nsVoidArrayComparatorFunc aFunc, void* aData) {
00073         mArray.Sort(aFunc, aData);
00074     }
00075     
00076     // any method which is not a direct forward to mArray should
00077     // avoid inline bodies, so that the compiler doesn't inline them
00078     // all over the place
00079     void Clear();
00080     PRBool InsertObjectAt(nsISupports* aObject, PRInt32 aIndex);
00081     PRBool InsertObjectsAt(const nsCOMArray_base& aObjects, PRInt32 aIndex);
00082     PRBool ReplaceObjectAt(nsISupports* aObject, PRInt32 aIndex);
00083     PRBool AppendObject(nsISupports *aObject) {
00084         return InsertObjectAt(aObject, Count());
00085     }
00086     PRBool AppendObjects(const nsCOMArray_base& aObjects) {
00087         return InsertObjectsAt(aObjects, Count());
00088     }
00089     PRBool RemoveObject(nsISupports *aObject);
00090     PRBool RemoveObjectAt(PRInt32 aIndex);
00091 
00092 public:
00093     // override nsVoidArray stuff so that they can be accessed by
00094     // consumers of nsCOMArray
00095     PRInt32 Count() const {
00096         return mArray.Count();
00097     }
00098 
00099     nsISupports* ObjectAt(PRInt32 aIndex) const {
00100         return NS_STATIC_CAST(nsISupports*, mArray.FastElementAt(aIndex));
00101     }
00102     
00103     nsISupports* SafeObjectAt(PRInt32 aIndex) const {
00104         return NS_STATIC_CAST(nsISupports*, mArray.SafeElementAt(aIndex));
00105     }
00106 
00107     nsISupports* operator[](PRInt32 aIndex) const {
00108         return ObjectAt(aIndex);
00109     }
00110 
00111     // Ensures there is enough space to store a total of aCapacity objects.
00112     // This method never deletes any objects.
00113     PRBool SetCapacity(PRUint32 aCapacity) {
00114       return aCapacity > 0 ? mArray.SizeTo(NS_STATIC_CAST(PRInt32, aCapacity))
00115                            : PR_TRUE;
00116     }
00117 
00118 private:
00119     
00120     // the actual storage
00121     nsVoidArray mArray;
00122 
00123     // don't implement these, defaults will muck with refcounts!
00124     nsCOMArray_base& operator=(const nsCOMArray_base& other);
00125 };
00126 
00127 // a non-XPCOM, refcounting array of XPCOM objects
00128 // used as a member variable or stack variable - this object is NOT
00129 // refcounted, but the objects that it holds are
00130 //
00131 // most of the read-only accessors like ObjectAt()/etc do NOT refcount
00132 // on the way out. This means that you can do one of two things:
00133 //
00134 // * does an addref, but holds onto a reference
00135 // nsCOMPtr<T> foo = array[i];
00136 //
00137 // * avoids the refcount, but foo might go stale if array[i] is ever
00138 // * modified/removed. Be careful not to NS_RELEASE(foo)!
00139 // T* foo = array[i];
00140 //
00141 // This array will accept null as an argument for any object, and will
00142 // store null in the array, just like nsVoidArray. But that also means
00143 // that methods like ObjectAt() may return null when referring to an
00144 // existing, but null entry in the array.
00145 template <class T>
00146 class nsCOMArray : public nsCOMArray_base
00147 {
00148  public:
00149     nsCOMArray() {}
00150     nsCOMArray(PRInt32 aCount) : nsCOMArray_base(aCount) {}
00151     
00152     // only to be used by trusted classes who are going to pass us the
00153     // right type!
00154     nsCOMArray(const nsCOMArray<T>& aOther) : nsCOMArray_base(aOther) { }
00155 
00156     ~nsCOMArray() {}
00157 
00158     // these do NOT refcount on the way out, for speed
00159     T* ObjectAt(PRInt32 aIndex) const {
00160         return NS_STATIC_CAST(T*,nsCOMArray_base::ObjectAt(aIndex));
00161     }
00162 
00163     // these do NOT refcount on the way out, for speed
00164     T* SafeObjectAt(PRInt32 aIndex) const {
00165         return NS_STATIC_CAST(T*,nsCOMArray_base::SafeObjectAt(aIndex));
00166     }
00167 
00168     // indexing operator for syntactic sugar
00169     T* operator[](PRInt32 aIndex) const {
00170         return ObjectAt(aIndex);
00171     }
00172 
00173     // index of the element in question.. does NOT refcount
00174     // note: this does not check COM object identity. Use
00175     // IndexOfObject() for that purpose
00176     PRInt32 IndexOf(T* aObject) const {
00177         return nsCOMArray_base::IndexOf(NS_STATIC_CAST(nsISupports*, aObject));
00178     }
00179 
00180     // index of the element in question.. be careful!
00181     // this is much slower than IndexOf() because it uses
00182     // QueryInterface to determine actual COM identity of the object
00183     // if you need to do this frequently then consider enforcing
00184     // COM object identity before adding/comparing elements
00185     PRInt32 IndexOfObject(T* aObject) const {
00186         return nsCOMArray_base::IndexOfObject(NS_STATIC_CAST(nsISupports*, aObject));
00187     }
00188 
00189     // inserts aObject at aIndex, shifting the objects at aIndex and
00190     // later to make space
00191     PRBool InsertObjectAt(T* aObject, PRInt32 aIndex) {
00192         return nsCOMArray_base::InsertObjectAt(NS_STATIC_CAST(nsISupports*, aObject), aIndex);
00193     }
00194 
00195     // inserts the objects from aObject at aIndex, shifting the
00196     // objects at aIndex and later to make space
00197     PRBool InsertObjectsAt(const nsCOMArray<T>& aObjects, PRInt32 aIndex) {
00198         return nsCOMArray_base::InsertObjectsAt(aObjects, aIndex);
00199     }
00200 
00201     // replaces an existing element. Warning: if the array grows,
00202     // the newly created entries will all be null
00203     PRBool ReplaceObjectAt(T* aObject, PRInt32 aIndex) {
00204         return nsCOMArray_base::ReplaceObjectAt(NS_STATIC_CAST(nsISupports*, aObject), aIndex);
00205     }
00206 
00207     // override nsVoidArray stuff so that they can be accessed by
00208     // other methods
00209 
00210     // elements in the array (including null elements!)
00211     PRInt32 Count() const {
00212         return nsCOMArray_base::Count();
00213     }
00214 
00215     // remove all elements in the array, and call NS_RELEASE on each one
00216     void Clear() {
00217         nsCOMArray_base::Clear();
00218     }
00219 
00220     // Enumerator callback function. Return PR_FALSE to stop
00221     // Here's a more readable form:
00222     // PRBool PR_CALLBACK enumerate(T* aElement, void* aData)
00223     typedef PRBool (* PR_CALLBACK nsCOMArrayEnumFunc)
00224         (T* aElement, void *aData);
00225     
00226     // enumerate through the array with a callback. 
00227     PRBool EnumerateForwards(nsCOMArrayEnumFunc aFunc, void* aData) {
00228         return nsCOMArray_base::EnumerateForwards(nsVoidArrayEnumFunc(aFunc),
00229                                                   aData);
00230     }
00231 
00232     PRBool EnumerateBackwards(nsCOMArrayEnumFunc aFunc, void* aData) {
00233         return nsCOMArray_base::EnumerateBackwards(nsVoidArrayEnumFunc(aFunc),
00234                                                   aData);
00235     }
00236     
00237     typedef int (* PR_CALLBACK nsCOMArrayComparatorFunc)
00238         (T* aElement1, T* aElement2, void* aData);
00239         
00240     void Sort(nsCOMArrayComparatorFunc aFunc, void* aData) {
00241         nsCOMArray_base::Sort(nsVoidArrayComparatorFunc(aFunc), aData);
00242     }
00243 
00244     // append an object, growing the array as necessary
00245     PRBool AppendObject(T *aObject) {
00246         return nsCOMArray_base::AppendObject(NS_STATIC_CAST(nsISupports*, aObject));
00247     }
00248 
00249     // append objects, growing the array as necessary
00250     PRBool AppendObjects(const nsCOMArray<T>& aObjects) {
00251         return nsCOMArray_base::AppendObjects(aObjects);
00252     }
00253     
00254     // remove the first instance of the given object and shrink the
00255     // array as necessary
00256     // Warning: if you pass null here, it will remove the first null element
00257     PRBool RemoveObject(T *aObject) {
00258         return nsCOMArray_base::RemoveObject(NS_STATIC_CAST(nsISupports*, aObject));
00259     }
00260 
00261     // remove an element at a specific position, shrinking the array
00262     // as necessary
00263     PRBool RemoveObjectAt(PRInt32 aIndex) {
00264         return nsCOMArray_base::RemoveObjectAt(aIndex);
00265     }
00266 
00267 private:
00268 
00269     // don't implement these!
00270     nsCOMArray<T>& operator=(const nsCOMArray<T>& other);
00271 };
00272 
00273 
00274 #endif