PageRenderTime 368ms CodeModel.GetById 73ms app.highlight 194ms RepoModel.GetById 88ms app.codeStats 1ms

/gecko_api/include/nsCOMArray.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 274 lines | 127 code | 45 blank | 102 comment | 0 complexity | fa11b6b39fae240c8b9056f506b92401 MD5 | raw file
  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
 49class NS_COM_GLUE nsCOMArray_base
 50{
 51    friend class nsArray;
 52protected:
 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
 92public:
 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
118private:
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.
145template <class T>
146class 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 PR_CALLBACK enumerate(T* aElement, void* aData)
223    typedef PRBool (* PR_CALLBACK 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 (* PR_CALLBACK 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
267private:
268
269    // don't implement these!
270    nsCOMArray<T>& operator=(const nsCOMArray<T>& other);
271};
272
273
274#endif