jsimple.util

Class List<E>

java.lang.Object

jsimple.lang.Iterable<E>

jsimple.util.Collection<E>

jsimple.util.List<E>

All Implemented Interfaces:

java.lang.Iterable<E>

Direct Known Subclasses:

ArrayList

public abstract class List<E>
extends Collection<E>

A List is a collection which maintains an ordering for its elements. Every element in the List has an index. Each element can thus be accessed by its index, with the first index being zero. Normally, Lists allow duplicate elements, as compared to Sets, where elements have to be unique.

AbstractList is an abstract implementation of the List interface, optimized for a backing store which supports random access. This implementation does not support adding or replacing. A subclass must implement the abstract methods get() and size(), and to create a modifiable List it's necessary to override the add() method that currently throws an UnsupportedOperationException.

Changes from the java.lang version: Removed subList method. It's rarely used (in my experience) and eliminated a fair amount of code/complexity.

Since:

1.2

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	List() Constructs a new instance of this AbstractList.

Method Summary

Modifier and Type	Method and Description
boolean	add(E object) Adds the specified object at the end of this List.
void	add(int location, E object) Inserts the specified object into this List at the specified location.
boolean	addAll(int location, Collection<? extends E> collection) Inserts the objects in the specified Collection at the specified location in this List.
boolean	equals(java.lang.Object object) By default, equals isn't supported for lists or other collections, though subclasses can choose to override this behavior if they want.
abstract E	get(int location) Returns the element at the specified location in this list.
int	hashCode() Returns the hash code of this list.
abstract int	indexOf(E object) Searches this List for the specified object and returns the index of the first occurrence.
abstract int	lastIndexOf(E object) Searches this List for the specified object and returns the index of the last occurrence.
abstract E	remove(int location) Removes the object at the specified location from this List.
abstract E	set(int location, E object) Replaces the element at the specified location in this List with the specified object.

Methods inherited from class jsimple.util.Collection

addAll, clear, contains, containsAll, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

List

protected List()

Constructs a new instance of this AbstractList.

Method Detail

add

public void add(int location,
                E object)

Inserts the specified object into this List at the specified location. The object is inserted before the current element at the specified location. If the location is equal to the size of this List, the object is added at the end. If the location is smaller than the size of this List, then all elements beyond the specified location are moved by one position towards the end of the List.

Concrete implementations that would like to support the add functionality must override this method.

Parameters:

location - the index at which to insert.

object - the object to add.

Throws:

java.lang.UnsupportedOperationException - if adding to this List is not supported.

java.lang.ClassCastException - if the class of the object is inappropriate for this List

java.lang.IllegalArgumentException - if the object cannot be added to this List

java.lang.IndexOutOfBoundsException - if location < 0 || >= size()

add

public boolean add(E object)

Adds the specified object at the end of this List.

Overrides:

add in class Collection<E>

Parameters:

object - the object to add

Returns:

true

Throws:

java.lang.UnsupportedOperationException - if adding to this List is not supported

java.lang.ClassCastException - if the class of the object is inappropriate for this List

java.lang.IllegalArgumentException - if the object cannot be added to this List

addAll

public boolean addAll(int location,
                      Collection<? extends E> collection)

Inserts the objects in the specified Collection at the specified location in this List. The objects are added in the order they are returned from the collection's iterator.

Parameters:

location - the index at which to insert.

collection - the Collection of objects

Returns:

true if this List is modified, false otherwise.

Throws:

java.lang.UnsupportedOperationException - if adding to this list is not supported.

java.lang.ClassCastException - if the class of an object is inappropriate for this list.

java.lang.IllegalArgumentException - if an object cannot be added to this list.

java.lang.IndexOutOfBoundsException - if location < 0 || > size()

equals

public boolean equals(java.lang.Object object)

By default, equals isn't supported for lists or other collections, though subclasses can choose to override this behavior if they want. Instead developers should call some other, more specific, method, checking for the exact kind of equality they want.

As background: This behavior differs from the standard java.util.AbstractList.equals method, where two lists are considered equal if the have the same number of elements and those elements are equals, according to equals, in the same order. That's so-called deep equality. Whereas C#, on the other hand, just does reference equality by default for lists, saying two lists are equal if they reference the same list.

Anyway, there are two main reasons we differ from standard Java and don't support equals here or for other collection methods:

(a) The desired semantics are ambiguous (deep, shallow, or reference equality? should order matter? list type matter?). There's no single obvious right answer & different semantics are appropriate in different cases. (b) It's hard to implement the Java semantics and support generics, with covariance, properly and have it work with Java to C#/Swift translation. Limited C# and Swift support for covariance, especially when casting from an Object, makes it all the harder. So best to just avoid all those issues & make the developer do explicitly what they want, calling some other method.

Overrides:

equals in class java.lang.Object

Parameters:

object - the object to compare to this object.

Returns:

true if the specified object is equal to this list, false otherwise; though by default this method throws an exception and developers generally shouldn't use it

get

public abstract E get(int location)

Returns the element at the specified location in this list.

Parameters:

location - the index of the element to return.

Returns:

the element at the specified index.

Throws:

java.lang.IndexOutOfBoundsException - if location < 0 || >= size()

hashCode

public int hashCode()

Returns the hash code of this list. The hash code is calculated by taking each element's hashcode into account.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code.

See Also:

equals(java.lang.Object), hashCode()

indexOf

public abstract int indexOf(E object)

Searches this List for the specified object and returns the index of the first occurrence.

Parameters:

object - the object to search for.

Returns:

the index of the first occurrence of the object or -1 if the object was not found.

lastIndexOf

public abstract int lastIndexOf(E object)

Searches this List for the specified object and returns the index of the last occurrence.

Parameters:

object - the object to search for.

Returns:

the index of the last occurrence of the object, or -1 if the object was not found.

remove

public abstract E remove(int location)

Removes the object at the specified location from this List.

Parameters:

location - the index of the object to remove.

Returns:

the removed object.

Throws:

java.lang.UnsupportedOperationException - if removing from this List is not supported.

java.lang.IndexOutOfBoundsException - if location < 0 || >= size()

set

public abstract E set(int location,
                      E object)

Replaces the element at the specified location in this List with the specified object. This operation does not change the size of the List.

Parameters:

location - the index at which to put the specified object.

object - the object to insert.

Returns:

the previous element at the index.

Throws:

java.lang.UnsupportedOperationException - if replacing elements in this List is not supported.

java.lang.ClassCastException - if the class of an object is inappropriate for this List.

java.lang.IllegalArgumentException - if an object cannot be added to this List.

java.lang.IndexOutOfBoundsException - if location < 0 || >= size()