| Package | com.bourre.collection |
| Interface | public interface List extends Collection, Iterable |
| Implementors | ArrayIterator, Set, Stack, StringIterator |
| Player version: | Flash Player 9.0 |
| Language version: | ActionScript 3.0 |
Unlike sets, lists typically allow duplicate elements. More formally, lists typically allow pairs of elements e1 and e2 such that e1 === e2, and they typically allow multiple null elements if they allow null elements at all. It is not inconceivable that someone might wish to implement a list that prohibits duplicates, by throwing runtime exceptions when the user attempts to insert them, but we expect this usage to be rare.
The List interface places additional stipulations, beyond those specified in the Collection interface, on the contracts of the iterator, add and remove methods. Declarations for other inherited methods are also included here for convenience.
The List interface provides four methods for positional (indexed) access to list elements. Lists (like arrays) are zero based. Note that these operations may execute in time proportional to the index value for some implementations. Thus, iterating over the elements in a list is typically preferable to indexing through it if the caller does not know the implementation.
The List interface provides a special iterator, called a ListIterator, that allows element insertion and replacement, and bidirectional access in addition to the normal operations that the Iterator interface provides. A method is provided to obtain a list iterator that starts at a specified position in the list.
The List interface provides two methods to search for a specified object. From a performance standpoint, these methods should be used with caution. In many implementations they will perform costly linear searches.
The List interface provides two methods to efficiently insert and remove multiple elements at an arbitrary point in the list.
Some list implementations have restrictions on the elements that they may contain. For example, some implementations prohibit null elements, and some have restrictions on the types of their elements. Attempting to add an ineligible element throws an unchecked exception, typically NullPointerException or ClassCastException. Attempting to query the presence of an ineligible element may throw an exception, or it may simply return false; some implementations will exhibit the former behavior and some will exhibit the latter. More generally, attempting an operation on an ineligible element whose completion would not result in the insertion of an ineligible element into the list may throw an exception or it may succeed, at the option of the implementation. Such exceptions are marked as "optional" in the specification for this interface.
See also
| Method | Defined by | ||
|---|---|---|---|
 |
add(o:Object):Boolean
Ensures that this collection contains the specified element (optional
operation).
| Collection | |
|
addAll(c:Collection):Boolean
Adds all of the elements in the specified collection to this collection
(optional operation).
| Collection | |
|
addAllAt(index:uint, c:Collection):Boolean
Inserts all of the elements in the specified collection
into this list at the specified position (optional operation).
| List | ||
|
addAt(index:uint, o:Object):void
Inserts the specified element at the specified position
in this list (optional operation).
| List | ||
|
clear():void
Removes all of the elements from this collection (optional operation).
| Collection | |
|
contains(o:Object):Boolean
Returns
true if this collection contains the specified
element. | Collection | |
|
containsAll(c:Collection):Boolean
Returns
true if this collection contains all of the elements
in the specified collection. | Collection | |
|
get(index:uint):Object
Returns the element at the specified position in this list.
| List | ||
|
indexOf(o:Object):int
Returns the index in this list of the first occurrence
of the specified element, or -1 if this list does not
contain this element.
| List | ||
|
isEmpty():Boolean
Returns
true if this collection contains no elements. | Collection | |
|
Returns an iterator over the elements in this collection.
| Iterable | |
|
lastIndexOf(o:Object):int
Returns the index in this list of the last occurrence of the
specified element, or -1 if this list does not contain this
element.
| List | ||
|
listIterator(index:uint = 0):ListIterator
Returns a list iterator of the elements in this list
(in proper sequence), starting at the specified position
in this list.
| List | ||
|
remove(o:Object):Boolean
Removes a single instance of the specified element from this
collection, if this collection contains one or more such
elements.
| Collection | |
|
removeAll(c:Collection):Boolean
Removes all this collection's elements that are also contained in the
specified collection (optional operation).
| Collection | |
|
removeAt(index:uint):Boolean
Removes the element at the specified position in this list
(optional operation).
| List | ||
|
retainAll(c:Collection):Boolean
Retains only the elements in this collection that are contained in the
specified collection (optional operation).
| Collection | |
|
set(index:uint, o:Object):Object
Replaces the element at the specified position in this
list with the specified element (optional operation).
| List | ||
|
size():uint
Returns the number of elements in this collection.
| Collection | |
|
Returns a view of the portion of this list between the specified
fromIndex, inclusive, and toIndex, exclusive.
| List | ||
|
toArray():Array
Returns an array containing all of the elements in this collection.
| Collection | |
| addAllAt | () | method |
Hide Inherited Public Methods
Show Inherited Public Methodspublic function addAllAt(index:uint, c:Collection):Boolean
| Player version: | Flash Player 9.0 |
| Language version: | ActionScript 3.0 |
Inserts all of the elements in the specified collection into this list at the specified position (optional operation). Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in this list in the order that they are returned by the specified collection's iterator. The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this list, and it's nonempty.)
Parametersindex:uint — index index at which to insert first element
from the specified collection.
|
|
c:Collection |
Boolean — c elements to be inserted into this list.
|
UnsupportedOperationException — if the addAll method
is not supported by this list.
|
|
ClassCastException — if the class of an element in the
specified collection prevents it from being added to this list.
|
|
NullPointerException — if the specified collection contains
one or more null elements and this list does not support null
elements, or if the specified collection is null.
|
|
IllegalArgumentException — if some aspect of an element in the
specified collection prevents it from being added to this list.
|
|
IndexOutOfBoundsException — if the index is out of range
(index < 0 || index > size()).
|
| addAt | () | method |
public function addAt(index:uint, o:Object):void
| Player version: | Flash Player 9.0 |
| Language version: | ActionScript 3.0 |
Inserts the specified element at the specified position in this list (optional operation). Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).
Parametersindex:uint — index index at which the specified element
is to be inserted.
|
|
o:Object — o element to be inserted.
|
UnsupportedOperationException — if the add method is not
supported by this list.
|
|
ClassCastException — if the class of the specified
element prevents it from being added to this list.
|
|
NullPointerException — if the specified element
is null and this list does not support null elements.
|
|
IllegalArgumentException — if some aspect of the specified
element prevents it from being added to this list.
|
|
IndexOutOfBoundsException — if the index is out of range
(index < 0 || index > size()).
|
| get | () | method |
public function get(index:uint):Object
| Player version: | Flash Player 9.0 |
| Language version: | ActionScript 3.0 |
Returns the element at the specified position in this list.
Parametersindex:uint — index index of element to return.
|
Object — the element at the specified position in this list.
|
IndexOutOfBoundsException — if the index is out of range
(index < 0 || index >= size()).
|
| indexOf | () | method |
public function indexOf(o:Object):int
| Player version: | Flash Player 9.0 |
| Language version: | ActionScript 3.0 |
Returns the index in this list of the first occurrence of the specified element, or -1 if this list does not contain this element. More formally, returns the lowest index i such that (o==null ? get(i)==null : o.equals(get(i))), or -1 if there is no such index.
Parameterso:Object — o element to search for.
|
int — the index in this list of the first occurrence of
the specified element, or -1 if this list does not
contain this element.
|
ClassCastException — if the type of the specified
element is incompatible with this list (optional).
|
|
NullPointerException — if the specified element is
null and this list does not support null elements (optional).
|
| lastIndexOf | () | method |
public function lastIndexOf(o:Object):int
| Player version: | Flash Player 9.0 |
| Language version: | ActionScript 3.0 |
Returns the index in this list of the last occurrence of the specified element, or -1 if this list does not contain this element. More formally, returns the highest index i such that (o==null ? get(i)==null : o.equals(get(i))), or -1 if there is no such index.
Parameterso:Object — o element to search for.
|
int — the index in this list of the last occurrence of the
specified element, or -1 if this list does not
contain this element.
|
ClassCastException — if the type of the specified
element is incompatible with this list (optional).
|
|
NullPointerException — if the specified element
is null and this list does not support null
elements (optional).
|
| listIterator | () | method |
public function listIterator(index:uint = 0):ListIterator
| Player version: | Flash Player 9.0 |
| Language version: | ActionScript 3.0 |
Returns a list iterator of the elements in this list (in proper sequence), starting at the specified position in this list. The specified index indicates the first element that would be returned by an initial call to the next method. An initial call to the previous method would return the element with the specified index minus one.
Parametersindex:uint (default = 0) |
ListIterator —
a list iterator of the elements in this list
(in proper sequence), starting at the specified
position in this list.
|
IndexOutOfBoundsException — if the index is out of
range (index < 0 || index > size()).
|
| removeAt | () | method |
public function removeAt(index:uint):Boolean
| Player version: | Flash Player 9.0 |
| Language version: | ActionScript 3.0 |
Removes the element at the specified position in this list (optional operation). Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.
Parametersindex:uint — index the index of the element to removed.
|
Boolean — the element previously at the specified position.
|
UnsupportedOperationException — if the remove method
is not supported by this list.
|
|
IndexOutOfBoundsException — if the index is out of range
(index < 0 || index >= size()).
|
| set | () | method |
public function set(index:uint, o:Object):Object
| Player version: | Flash Player 9.0 |
| Language version: | ActionScript 3.0 |
Replaces the element at the specified position in this list with the specified element (optional operation).
Parametersindex:uint — index index of element to replace.
|
|
o:Object — o element to be stored at the specified position.
|
Object — the element previously at the specified position.
|
UnsupportedOperationException — if the set method is
not supported by this list.
|
|
ClassCastException — if the class of the specified
element prevents it from being added to this list.
|
|
NullPointerException — if the specified element is
null and this list does not support null elements.
|
|
IllegalArgumentException — if some aspect of the
specified element prevents it from being added to this list.
|
|
IndexOutOfBoundsException — if the index is out of range
(index < 0 || index >= size()).
|
| subList | () | method |
public function subList(fromIndex:uint, toIndex:uint):List
| Player version: | Flash Player 9.0 |
| Language version: | ActionScript 3.0 |
Returns a view of the portion of this list between the specified fromIndex, inclusive, and toIndex, exclusive. (If fromIndex and toIndex are equal, the returned list is empty.) The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa. The returned list supports all of the optional list operations supported by this list.
This method eliminates the need for explicit range operations (of the sort that commonly exist for arrays). Any operation that expects a list can be used as a range operation by passing a subList view instead of a whole list. For example, the following idiom removes a range of elements from a list :
list.subList(from, to).clear();
Similar idioms may be constructed for indexOf and lastIndexOf, and all of the algorithms in the Collections class can be applied to a subList.
The semantics of the list returned by this method become undefined if the backing list (i.e., this list) is structurally modified in any way other than via the returned list. (Structural modifications are those that change the size of this list, or otherwise perturb it in such a fashion that iterations in progress may yield incorrect results.)
ParametersfromIndex:uint — fromIndex low endpoint (inclusive) of the subList.
|
|
toIndex:uint — toIndex high endpoint (exclusive) of the subList.
|
List —
a view of the specified range within this list.
|
IndexOutOfBoundsException — for an illegal endpoint index
value (fromIndex < 0 || toIndex > size || fromIndex > toIndex).
|