List

Kind of class:public interface
Package:com.bourre.collection
Inherits from:Collection < Iterable
Implemented by:
Author:Cédric Néhémie
Classpath:com.bourre.collection.List
File last modified:Monday, 24 November 2008, 11:36:49
An ordered collection (also known as a sequence).
The user of this interface has precise control over where
in the list each element is inserted. The user can access
elements by their integer index (position in the list),
and search for elements in the list.

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:

Summary


Instance methods
  • addAt (index:uint, o:Object) : void
    • Inserts the specified element at the specified position
  • addAllAt (index:uint, c:Collection) : Boolean
    • Inserts all of the elements in the specified collection
  • get (index:uint) : Object
    • Returns the element at the specified position in this list.
  • indexOf (o:Object) : int
    • Returns the index in this list of the first occurrence
  • lastIndexOf (o:Object) : int
    • Returns the index in this list of the last occurrence of the
  • listIterator (index:uint = 0) : ListIterator
    • Returns a list iterator of the elements in this list
  • removeAt (index:uint) : Boolean
    • Removes the element at the specified position in this list
  • set (index:uint, o:Object) : Object
    • Replaces the element at the specified position in this
  • subList (fromIndex:uint, toIndex:uint) : List
    • Returns a view of the portion of this list between the specified
Instance methods inherited from Collection
add addAll clear contains containsAll isEmpty remove removeAll retainAll size toArray
Instance methods inherited from Iterable
iterator

Instance methods

addAllAt

public function addAllAt (
index:uint, c:Collection) : Boolean

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.)
Parameters:
index:
index at which to insert first element
from the specified collection.
Returns:
  • c elements to be inserted into this list.
Throws:
  • {VISDOC_LINK_0}UnsupportedOperationException — if the addAll method
    is not supported by this list.
  • {VISDOC_LINK_1}ClassCastException — if the class of an element in the
    specified collection prevents it from being added to this list.
  • {VISDOC_LINK_2}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.
  • {VISDOC_LINK_3}IllegalArgumentException — if some aspect of an element in the
    specified collection prevents it from being added to this list.
  • {VISDOC_LINK_4}IndexOutOfBoundsException — if the index is out of range
    (index < 0 || index > size()).

addAt

public function addAt (
index:uint, o:Object) : void

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).
Parameters:
index:
index at which the specified element
is to be inserted.
o :
element to be inserted.
Throws:
  • {VISDOC_LINK_0}UnsupportedOperationException — if the add method is not
    supported by this list.
  • {VISDOC_LINK_1}ClassCastException — if the class of the specified
    element prevents it from being added to this list.
  • {VISDOC_LINK_2}NullPointerException — if the specified element
    is null and this list does not support null elements.
  • {VISDOC_LINK_3}IllegalArgumentException — if some aspect of the specified
    element prevents it from being added to this list.
  • {VISDOC_LINK_4}IndexOutOfBoundsException — if the index is out of range
    (index < 0 || index > size()).

get

public function get (
index:uint) : Object

Returns the element at the specified position in this list.
Parameters:
index:
index of element to return.
Returns:
  • the element at the specified position in this list.
Throws:
  • {VISDOC_LINK_0}IndexOutOfBoundsException — if the index is out of range
    (index < 0 || index >= size()).

indexOf

public function 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. 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.
Parameters:
o:
element to search for.
Returns:
  • the index in this list of the first occurrence of
    the specified element, or -1 if this list does not
    contain this element.
Throws:
  • {VISDOC_LINK_0}ClassCastException — if the type of the specified
    element is incompatible with this list (optional).
  • {VISDOC_LINK_1}NullPointerException — if the specified element is
    null and this list does not support null elements (optional).

lastIndexOf

public function 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. 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.
Parameters:
o:
element to search for.
Returns:
  • the index in this list of the last occurrence of the
    specified element, or -1 if this list does not
    contain this element.
Throws:
  • {VISDOC_LINK_0}ClassCastException — if the type of the specified
    element is incompatible with this list (optional).
  • {VISDOC_LINK_1}NullPointerException — if the specified element
    is null and this list does not support null
    elements (optional).

listIterator

public function 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. 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.
Parameters:
index:
index of first element to be returned
from the list iterator (by a call to the next method).
Returns:
  • a list iterator of the elements in this list
    (in proper sequence), starting at the specified
    position in this list.
Throws:
  • {VISDOC_LINK_0}IndexOutOfBoundsException — if the index is out of
    range (index < 0 || index > size()).

removeAt

public function removeAt (
index:uint) : Boolean

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.
Parameters:
index:
the index of the element to removed.
Returns:
  • the element previously at the specified position.
Throws:
  • {VISDOC_LINK_0}UnsupportedOperationException — if the remove method
    is not supported by this list.
  • {VISDOC_LINK_1}IndexOutOfBoundsException — if the index is out of range
    (index < 0 || index >= size()).

set

public function set (
index:uint, o:Object) : Object

Replaces the element at the specified position in this
list with the specified element (optional operation).
Parameters:
index:
index of element to replace.
o :
element to be stored at the specified position.
Returns:
  • the element previously at the specified position.
Throws:
  • {VISDOC_LINK_0}UnsupportedOperationException — if the set method is
    not supported by this list.
  • {VISDOC_LINK_1}ClassCastException — if the class of the specified
    element prevents it from being added to this list.
  • {VISDOC_LINK_2}NullPointerException — if the specified element is
    null and this list does not support null elements.
  • {VISDOC_LINK_3}IllegalArgumentException — if some aspect of the
    specified element prevents it from being added to this list.
  • {VISDOC_LINK_4}IndexOutOfBoundsException — if the index is out of range
    (index < 0 || index >= size()).

subList

public function subList (
fromIndex:uint, toIndex:uint) : List

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

Parameters:
fromIndex:
low endpoint (inclusive) of the subList.
toIndex :
high endpoint (exclusive) of the subList.
Returns:
  • a view of the specified range within this list.
Throws:
  • {VISDOC_LINK_0}IndexOutOfBoundsException — for an illegal endpoint index
    value (fromIndex < 0 || toIndex > size || fromIndex > toIndex).