Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Public Attributes
nsIMutableArray Interface Reference

nsIMutableArray A separate set of methods that will act on the array. More...

import "nsIArray.idl";

Inheritance diagram for nsIMutableArray:
Inheritance graph
[legend]
Collaboration diagram for nsIMutableArray:
Collaboration graph
[legend]

List of all members.

Public Member Functions

void appendElement (in nsISupports element, in boolean weak)
 appendElement()
void removeElementAt (in unsigned long index)
 removeElementAt()
void insertElementAt (in nsISupports element, in unsigned long index, in boolean weak)
 insertElementAt()
void replaceElementAt (in nsISupports element, in unsigned long index, in boolean weak)
 replaceElementAt()
void clear ()
 clear()
void queryElementAt (in unsigned long index, in nsIIDRef uuid,[iid_is(uuid), retval] out nsQIResult result)
 queryElementAt()
unsigned long indexOf (in unsigned long startIndex, in nsISupports element)
 indexOf()
nsISimpleEnumerator enumerate ()
 enumerate the array

Public Attributes

readonly attribute unsigned long length
 length

Detailed Description

nsIMutableArray A separate set of methods that will act on the array.

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 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.

UNDER_REVIEW

Definition at line 148 of file nsIArray.idl.


Member Function Documentation

void nsIMutableArray::appendElement ( in nsISupports  element,
in boolean  weak 
)

appendElement()

Append an element at the end of the array.

Parameters:
elementThe element to append.
weakWhether or not to store the element using a weak reference.
Exceptions:
NS_ERROR_FAILUREwhen a weak reference is requested, but the element does not support nsIWeakReference.

Here is the caller graph for this function:

clear()

clear the entire array, releasing all stored objects

Here is the caller graph for this function:

enumerate the array

Returns:
a new enumerator positioned at the start of the array
Exceptions:
NS_ERROR_FAILUREif the array is empty (to make it easy to detect errors)
unsigned long nsIArray::indexOf ( in unsigned long  startIndex,
in nsISupports  element 
) [inherited]

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.

Parameters:
startIndexThe initial element to search in the array To start at the beginning, use 0 as the startIndex
elementThe element you are looking for
Returns:
a number >= startIndex which is the position of the element in the array.
Exceptions:
NS_ERROR_NOT_FOUNDif the element was not in the array.

Here is the caller graph for this function:

void nsIMutableArray::insertElementAt ( in nsISupports  element,
in unsigned long  index,
in boolean  weak 
)

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.

Parameters:
elementThe element to insert
indexThe 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.
Exceptions:
NS_ERROR_FAILUREwhen a weak reference is requested, but the element does not support nsIWeakReference.

Here is the caller graph for this function:

void nsIArray::queryElementAt ( in unsigned long  index,
in nsIIDRef  uuid,
[iid_is(uuid), retval] out nsQIResult  result 
) [inherited]

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

Parameters:
indexposition of element
uuidthe IID of the requested interface
resultthe object, QI'd to the requested interface
Exceptions:
NS_ERROR_NO_INTERFACEwhen an entry exists at the specified index, but the requested interface is not available.
NS_ERROR_ILLEGAL_VALUEwhen index > length-1

Here is the caller graph for this function:

removeElementAt()

Remove an element at a specific position, moving all elements stored at a higher position down one. To remove a specific element, use indexOf() to find the index first, then call removeElementAt().

Parameters:
indexthe position of the item

Here is the caller graph for this function:

void nsIMutableArray::replaceElementAt ( in nsISupports  element,
in unsigned long  index,
in boolean  weak 
)

replaceElementAt()

Replace the element at the given position.

Parameters:
elementThe new element to insert
indexThe 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.
weakWhether or not to store the new element using a weak reference.
Exceptions:
NS_ERROR_FAILUREwhen a weak reference is requested, but the element does not support nsIWeakReference.

Member Data Documentation

readonly attribute unsigned long nsIArray::length [inherited]

length

number of elements in the array.

Definition at line 77 of file nsIArray.idl.


The documentation for this interface was generated from the following file: