nsIArray
Last changed in Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)Consumers of nsIArray
should not QueryInterface
to nsIMutableArray
unless they own the array.
As above, it is legal to add null
elements to the array. Note also that null
elements can be created as a side effect of insertElementAt()
. Conversely, if insertElementAt()
is never used, and null
elements are never explicitly added to the array, then it is guaranteed that nsIArray.queryElementAt()
will never return a null
value.
Any of these methods may throw NS_ERROR_OUT_OF_MEMORY when the array must grow to complete the call, but the allocation fails.
Method overview
void appendElement(in nsISupports element, in boolean weak); |
void clear(); |
void insertElementAt(in nsISupports element, in unsigned long index, in boolean weak); |
void removeElementAt(in unsigned long index); |
void replaceElementAt(in nsISupports element, in unsigned long index, in boolean weak); |
Methods
appendElement()
Append an element at the end of the array.
void appendElement( in nsISupports element, in boolean weak );
Parameters
-
element
- The element to append.
-
weak
- Whether or not to store the element using a weak reference.
Exceptions thrown
-
NS_ERROR_FAILURE
-
When a weak reference is requested, but the element does not support
nsIWeakReference
.
clear()
Clear the entire array, releasing all stored objects.
void clear();
Parameters
None.
insertElementAt()
Insert an element at the given position, moving the element currently located in that position, and all elements in higher position, up by one.
void insertElementAt( in nsISupports element, in unsigned long index, in boolean weak );
Parameters
-
element
- The element to insert.
-
index
- The position in the array: If the position is lower than the current length of the array, the elements at that position and onwards are bumped one position up. If the position is equal to the current length of the array, the new element is appended. An index lower than 0 or higher than the current length of the array is invalid and will be ignored.
-
weak
- Whether or not to store the element using a weak reference.
Exceptions thrown
-
NS_ERROR_FAILURE
-
When a weak reference is requested, but the element does not support
nsIWeakReference
.
removeElementAt()
Remove an element at a specific position, moving all elements stored at a higher position down one. To remove a specific element, use nsIArray.indexOf()
to find the index first, then call removeElementAt
.
void removeElementAt( in unsigned long index );
Parameters
-
index
- The position of the item.
replaceElementAt()
Replace the element at the given position.
void replaceElementAt( in nsISupports element, in unsigned long index, in boolean weak );
Parameters
-
element
- The new element to insert.
-
index
- The position in the array. If the position is lower than the current length of the array, an existing element will be replaced. If the position is equal to the current length of the array, the new element is appended. If the position is higher than the current length of the array, empty elements are appended followed by the new element at the specified position. An index lower than 0 is invalid and will be ignored.
-
weak
- Whether or not to store the new element using a weak reference.
Exceptions thrown
-
NS_ERROR_FAILURE
-
When a weak reference is requested, but the element does not support
nsIWeakReference
.