Class AbstractList

Object
   |
   +--AbstractList

Direct Known Subclasses:

WidgetList, ArrayList, EmptyList, LinkedList

class AbstractList

Defined in abstract_list.js

Constructor Detail

AbstractList

function AbstractList()

An abstract base class for lists. All the methods in this class are implemented on top of its four private methods (_getListPointerForIndex, _getListPointerForItem, _insertAt, and _removeFrom).

append

void append(<Object> item)

Appends the given item to the end of the list.

Parameters:
item - the object to add to the end of the list.

clear

void clear()

Empties the list. After a call to clear(), the list is empty—list.getHead(), list.getTail() will both return null and list.getLength() will return 0.

Implementation note: this method removes the items from the list one at a time, starting with the tail.

contains

boolean contains(<Object> item)

Searches the list for item and returns true if it is found.

Parameters:
item - the value to search for

Returns:
true if item is in the list and false otherwise.

copy

void copy(<Object> source, <boolean> keepOldItems)

Copies the contents of the source into this list. If keepOldItems is true, then the elements in source will be appended to this list, otherwise this list is cleared first.

Parameters:
source - either an Array, an AbstractList, or a single object. If source is an array or a list, source's elements will be copied into this list. If source is a single object, it will be copied into this list. If source is null or undefined, then no elements are added to this list (this means that list.copy(null, false) is equivalent to list.clear()).
keepOldItems - (Optional) - a boolean indicating whether or not to keep the items already in this list (true) or to clear this list before inserting any new items (false). Defaults to false.

getHead

Object getHead()

Returns the item at the head of the list.

Returns:
the head of the list.

getIndexOf

int getIndexOf(<Object> item)

Returns the index of item in this list. Returns this.getLength() if item is not in the list.

Implementation note: this method makes use of iterators to find item's index in linear time.

Parameters:
item - the item to look for

Returns:
this index in the list of item, or this.getLength() if item is not in the list.

getItemAfter

Object getItemAfter(<Object> item)

Retrieves the item after item in this list.

Parameters:
item - the item to search for

Returns:
the item after item

getItemAt

Object getItemAt(<int> index)

Returns the item in the list whose index is index.

Parameters:
index - the index of the item to return

Returns:
the item at index index

getItemBefore

Object getItemBefore(<Object> item)

Retrieves the item before item in this list.

Parameters:
item - the item to search for

Returns:
the item before item

getLength

int getLength()

Returns the length of the list. (ie. Returns the number of items in the list).

Returns:
the length of the list

getTail

Object getTail()

Returns the item at the tail of the list.

Returns:
the tail of the list.

insertAfter

void insertAfter(<Object> newItem, <Object> oldItem)

Inserts newItem after oldItem. Inserts newItem at the beginning of the list if oldItem is not in the list.

Parameters:
newItem - the item to insert into this list
oldItem - the item to insert newItem after

insertBefore

void insertBefore(<Object> newItem, <Object> oldItem)

Inserts newItem before oldItem. Inserts newItem at the end of the list if oldItem is not in the list.

Parameters:
newItem - the item to insert into this list
oldItem - the item to insert newItem before

insertItemAt

void insertItemAt(<Object> item, <int> index)

Inserts item at index index. If there are any items already in the list with indices greater than or equal to index, all those items are ‘shuffled right’ by one.

Parameters:
item - the item to insert
index - the index at which to insert item

isEmpty

boolean isEmpty()

Returns true if and only if the list is empty.

Returns:
true if the list is empty and false otherwise

iterator

Iterator iterator()

Returns an iterator on this list. Iterators support linear traversal of lists.

Iterators have the following interface:

boolean hasNext()

Returns true if calling next() will not cause an error

Object next()

Returns the next item in the iteration

A common idiom is as follows:

var it = list.iterator();

while(it.hasNext()) {
    var cursor = it.next();
    // do something with cursor
}

The above code will make one iteration of the while-loop for each item in the list. cursor will assume the value of each item in the list in order, starting with list.getHead() and ending with list.getTail(), at which point the loop will terminate.

There is no guarantee that an iterator will remain valid in the face of modifications to the list. Generally speaking no changes should be made to a list while there are iterators active on it.

Returns:
a forward iterator

join

string join(<string> separator)

Joins the elements of the list into a string, separated by separator.

Parameters:
separator - the string to put between consecutive elements of the list

Returns:
a string composed of all elements of the list, separated by separator

prepend

void prepend(<Object> item)

Inserts item into this list before the head.

Parameters:
item - this item to insert

remove

Object remove(<Object> item)

Removes item from this list and returns it.

Parameters:
item - the item to remove

Returns:
item is returned

removeAll

void removeAll(<AbstractList> list)

Removes all elements from this list that are also in list.

Parameters:
list - a list of elements to remove from this list

removeHead

Object removeHead()

Removes the head of this list and returns it.

Returns:
the head of the list

removeItemAt

Object removeItemAt(<int> index)

Removes and returns the item at the given index.

Parameters:
index - the index of the item to remove

Returns:
the item in this list at index index

removeTail

Object removeTail()

Removes the tail of this list and returns it.

Returns:
the tail of the list

replace

Object replace(<Object> newItem, <Object> oldItem)

Replaces oldItem with newItem in this list. Does nothing if oldItem is not in this list or if newItem could not be inserted.

Parameters:
newItem - the item to insert into the list
oldItem - the item in the list to be replaced by newItem

Returns:
oldItem is returned if it was in the list—otherwise null is returned.

reverseIterator

Iterator reverseIterator()

Returns a reverse iterator on this list. A reverse iterator has the same interface and uses as an forward iterator except that successive calls to next() will return the list's items in the opposite order to a forward iterator. Specifically, the first call to next() will return the tail of the list, and successive calls to next() will ‘advance’ the iterator towards the head of the list. The last successful call to next() on a reverse iterator returns the head of the list, and then invalidates the iterator.

Returns:
a reverse iterator

See:
- AbstractList.iterator()

selectRangeInto

AbstractList selectRangeInto(<Object> startObj, <Object> endObj, <AbstractList> list)

Selects all elements of this list between startObj and endObj inclusive and copies them into list. It doesn't matter if endObj comes before startObj in the list—the algorithm will behave as if they were swapped. If the list contains duplicates of startObj or endObj the resulting selection is undefined. For conveniece, list is the return value so you can say

var newList = oldList.selectRangeInto(foo, bar, new LinkedList());

and have everything work out.

Parameters:
startObj - the object at the "start" of the range
endObj - the object at the "end" of the range
list - the list into which the selection should be inserted

Returns:
list with the selection inserted

sort

void sort(<Function> comparator)

Destructively sorts the list.

Parameters:
comparator - a function taking two arguments and returning an integer:
• return a negative if the first argument is less than the second
• return zero if the two arguments are equal
• return a positive if the first argument is greater than the second
If comparator is null or not provided then the elements of the list are sorted lexicographically according to their value after being converted to a string.

toArray

Array toArray()

Returns an array containing the same items as this list, in the same order.

Returns:
an Array containing all the items in this list, and in the same order as this list.

toString

string toString()

Returns a string representation of this list.