nsISupports
Last changed in Gecko 1.7 An indexed collection of elements. Provides basic functionality for retrieving elements at a specific position, searching for elements. Indexes are zero-based, such that the last element in the array is stored at the index length
-1.
For an array which can be modified, see nsIMutableArray
.
Neither interface makes any attempt to protect the individual elements from modification. The convention is that the elements of the array should not be modified. Documentation within a specific interface should describe variations from this convention.
It is also convention that if an interface provides access to an nsIArray
, that the array should not be QueryInterfaced to an nsIMutableArray
for modification. If the interface in question had intended the array to be modified, it would have returned an nsIMutableArray
!
null
is a valid entry in the array, and as such any nsISupports
parameters may be null
, except where noted.
Method overview
nsISimpleEnumerator enumerate(); |
unsigned long indexOf(in unsigned long startIndex, in nsISupports element); |
void queryElementAt(in unsigned long index, in nsIIDRef uuid, [iid_is(uuid), retval] out nsQIResult result); |
Attributes
Attribute | Type | Description |
length | unsigned long | The number of elements in the array. Read only. |
Methods
enumerate()
Enumerate the array.
nsISimpleEnumerator enumerate();
Parameters
None.
Return value
A new enumerator positioned at the start of the array.
Exceptions thrown
NS_ERROR_FAILURE
- If the array is empty (to make it easy to detect errors).
NS_ERROR_OUT_OF_MEMORY
- If there is not enough memory to complete the operation.
indexOf()
Get the position of a specific element. Note that since null
is a valid input, exceptions are used to indicate that an element is not found.
unsigned long indexOf( in unsigned long startIndex, in nsISupports element );
Parameters
startIndex
- The initial element to search in the array. To start at the beginning, use 0 as the
startIndex
. element
- The element you are looking for.
Return value
A number >= startIndex
which is the position of the element in the array.
Exceptions thrown
NS_ERROR_FAILURE
- If the element was not in the array.
queryElementAt()
Retrieve a specific element of the array, and QueryInterface
it to the specified interface. null
is a valid result for this method, but exceptions are thrown in other circumstances.
void queryElementAt( in unsigned long index, in nsIIDRef uuid, [iid_is(uuid), retval] out nsQIResult result );
Parameters
index
- Position of element.
uuid
- The IID of the requested interface.
result
- The object,
QueryInterface
'd to the requested interface.
Exceptions thrown
NS_ERROR_ILLEGAL_VALUE
- When index >
length
-1.