These two classes REPLACE nsISupportsArray - no new code should be using nsISupportsArray! In addition, nsIArray is a public interface that will be frozen for embeddors.
(Reviewers, please keep this in mind when reviewing new code)
I'll be working on documentation this week, but I thought I'd give you a preview.
nsCOMArray<T>
-------------
similar to nsCOMPtr, this is a typed array of objects. For instance, you can have an array nsCOMArray<nsIContent> contentObjects which is an array of nsIContent* objects. This allows you to avoid calling QueryInterface/QueryElementAt. nsCOMArray<T> is not refcounted, and not scriptable. Beneath the covers, it is more or less a wrapper around nsVoidArray. Its elements ARE refcounted, and the strong typing will make it very easy to use.
Sample usage:
// member variable
nsCOMArray<nsIObserver> mObserverList;
...
// add an element
mObserverList.AppendObject(aObserver);
...
// iterate through the array - note we can call nsIObserver::Observe() directly!
for (i=0; i< count; i++) {
if (mObserverList[i])
mObserverList[i]->Observe(a,b,c);
}
nsIArray
--------
A new, simplified array implementation based on nsCOMArray<nsISupports> - this interface WILL BE FROZEN sometime in the 1.2 or 1.3 timeframe. This array is safe for embeddors to use, and may appear in frozen interfaces. It is scriptable, refcounted, and supports both strong and weak pointers. The base nsIArray interface does not allow consumers to modify the array. There is also nsIMutableArray, which allows the array to be modified.
Sample usage:
the API is very similar to nsISupportsArray, and should hopefully be self explanitory.
Helper routines
---------------
NS_NewArray(nsIMutableArray**) - create a new nsIArray to store nsISupports* objects
NS_NewArray(nsIMutableArray**, const nsCOMArray_base&) - convert an nsCOMArray<T> into an nsIArray
NS_NewArrayEnumerator(nsISimpleEnumerator**, nsIArray*) - create an enumerator for an nsIArray
NS_NewArrayEnumerator(nsISimpleEnumerator**, const nsCOMArray_base &) - create an enumerator based on an nsCOMArray<T> - takes ownership of all objects in the array at creation.
do_QueryElementAt(nsIArray*, PRUint32, nsresult*) - do_QueryElementAt implementation for nsIArray
Please let me know if you have any questions. I will try to follow up all answers to netscape.public.mozilla.xpcom
Alec
-- Ask me about my 1999 Volkswagen GTI for sale in the San Francisco area!
