javaslam.util
Class ListSet

java.lang.Object
  |
  +--java.util.AbstractCollection
        |
        +--java.util.AbstractSet
              |
              +--javaslam.util.ListSet

All Implemented Interfaces:

Collection, List, Set

public class ListSet

extends AbstractSet

implements List

A set implemented by a list, or equivalently, a list with no duplicate elements. This class provides a simple implementation of a set whose elements can be placed in an arbitrary order. (In contrast, the elements of a SortedSet are ordered based upon intrinsic properties of the objects.) This class is implemented in terms of a backing list, and it will support all of the methods supported by that list.

The notion of equality is different for sets and lists, and this class adheres to the contract of Set rather than List. In particular, this implies that a List and a ListSet formed from it are not equal. Such comparisons can be made correctly by accessing the backing list via asList.

Field Summary

protected List

list The underlying list.

Constructor Summary

ListSet()
Constructor.

ListSet(Collection c)
Constructor.

ListSet(Object obj)
Constructor.

ListSet(Object[] objs)
Constructor.

Method Summary

void	add(int index, Object element) Inserts the specified element at the specified position in this set (optional operation).
boolean	add(Object o) Appends the specified element to the end of this set if it is not already in the set (optional operation).
boolean	addAll(Collection c) Appends all of the elements in the specified collection to the end of this set, in the order that they are returned by the specified collection's iterator.
boolean	addAll(int index, Collection c) Inserts all of the elements in the specified collection into this set at the specified position (optional operation).
List	asList() Returns an unmodifiable view of this set as a list.
void	clear() Removes all of the elements from this set (optional operation).
ListSet	complement(Set other) Creates an ordered set that is the complement of this set in the supplied set of objects.
boolean	contains(Object o) Returns true if this set contains the specified element.
boolean	containsAll(Collection c) Returns true if this set contains all of the elements of the specified collection.
boolean	containsAny(Collection c) Returns true if this set contains any of the elements of the specified collection.
Object	get(int index) Returns the element at the specified position in this set.
int	indexOf(Object o) Returns the index in this set of the specified element, or -1 if this set does not contain this element.
boolean	isEmpty() Returns true if this set contains no elements.
Iterator	iterator() Returns an iterator over the elements in this set in proper sequence.
int	lastIndexOf(Object o) Returns the index in this set of the specified element, or -1 if this set does not contain this element.
ListIterator	listIterator() Returns a list iterator of the elements in this set (in proper sequence).
ListIterator	listIterator(int index) Returns a list iterator of the elements in this list (in proper sequence), starting at the specified position in this set.
Object	remove(int index) Removes the element at the specified position in this set (optional operation).
boolean	remove(Object o) Removes the the specified element from this set (optional operation).
boolean	removeAll(Collection c) Removes from this set all the elements that are contained in the specified collection (optional operation).
boolean	retainAll(Collection c) Retains only the elements in this set that are contained in the specified collection (optional operation).
Object	set(int index, Object element) Replaces the element at the specified position in this set with the specified element (optional operation).
int	size() Returns the number of elements in this set.
List	subList(int fromIndex, int toIndex) Returns a view of the portion of this set between the specified fromIndex, inclusive, and toIndex, exclusive.
Object[]	toArray() Returns an array containing all of the elements in this set in proper sequence.
Object[]	toArray(Object[] a) Returns an array containing all of the elements in this set in proper sequence; the runtime type of the returned array is that of the specified array.

Methods inherited from class java.util.AbstractSet

equals, hashCode

Methods inherited from class java.util.AbstractCollection

toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.List

equals, hashCode

Field Detail

list

protected List list

The underlying list.

Constructor Detail

ListSet

public ListSet()

Constructor. The backing list is a LinkedList.

ListSet

public ListSet(Object obj)

Constructor. The backing list is a LinkedList, and the set is initialized to contain the single supplied object.

ListSet

public ListSet(Object[] objs)

Constructor. The backing list is a LinkedList, and the set is initialized to contain the single supplied object, and the set is initialized to contain the elements of the supplied array (in order). Only the first occurrence of each element is retained.

ListSet

public ListSet(Collection c)

Constructor. The backing list is a LinkedList, and the set is initialized to contain the elements of the supplied collection (in their iteration order). Only the first occurrence of each element is retained.

Method Detail

asList

public List asList()

Returns an unmodifiable view of this set as a list.

size

public int size()

Returns the number of elements in this set. If this set contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:

size in interface List

Specified by:

size in class AbstractCollection

Returns:

the number of elements in this set.

isEmpty

public boolean isEmpty()

Returns true if this set contains no elements.

Specified by:

isEmpty in interface List

Overrides:

isEmpty in class AbstractCollection

Returns:

true if this set contains no elements.

contains

public boolean contains(Object o)

Returns true if this set contains the specified element. More formally, returns true if and only if this set contains at least one element e such that (o==null ? e==null : o.equals(e)).

Specified by:

contains in interface List

Overrides:

contains in class AbstractCollection

Parameters:

o - element whose presence in this set is to be tested.

Returns:

true if this set contains the specified element.

iterator

public Iterator iterator()

Returns an iterator over the elements in this set in proper sequence.

Specified by:

iterator in interface List

Specified by:

iterator in class AbstractCollection

Returns:

an iterator over the elements in this set in proper sequence.

toArray

public Object[] toArray()

Returns an array containing all of the elements in this set in proper sequence. Obeys the general contract of the Collection.toArray method.

Specified by:

toArray in interface List

Overrides:

toArray in class AbstractCollection

Returns:

an array containing all of the elements in this set in proper sequence.

toArray

public Object[] toArray(Object[] a)

Returns an array containing all of the elements in this set in proper sequence; the runtime type of the returned array is that of the specified array. Obeys the general contract of the Collection.toArray(Object[]) method.

Specified by:

toArray in interface List

Overrides:

toArray in class AbstractCollection

Parameters:

a - the array into which the elements of this set are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:

an array containing the elements of this set.

Throws:

ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this set.

add

public boolean add(Object o)

Appends the specified element to the end of this set if it is not already in the set (optional operation).

Specified by:

add in interface List

Overrides:

add in class AbstractCollection

Parameters:

o - element to be appended to this set.

Returns:

true if the element was added

Throws:

UnsupportedOperationException - if the add method is not supported by the backing list.

ClassCastException - if the class of an element in the specified collection prevents it from being added to the backing list.

IllegalArgumentException - if some aspect of an element in the specified collection prevents it from being added to this backing list.

remove

public boolean remove(Object o)

Removes the the specified element from this set (optional operation). If this set does not contain the element, it is unchanged. More formally, removes the element with the lowest index i such that (o==null ? get(i)==null : o.equals(get(i))) (if such an element exists).

Specified by:

remove in interface List

Overrides:

remove in class AbstractCollection

Parameters:

o - element to be removed from this set, if present.

Returns:

true if this set contained the specified element.

Throws:

UnsupportedOperationException - if the remove method is not supported by the backing list.

containsAll

public boolean containsAll(Collection c)

Returns true if this set contains all of the elements of the specified collection.

Specified by:

containsAll in interface List

Overrides:

containsAll in class AbstractCollection

Parameters:

c - collection to be checked for containment in this set.

Returns:

true if this set contains all of the elements of the specified collection.

See Also:

contains(Object)

containsAny

public boolean containsAny(Collection c)

Returns true if this set contains any of the elements of the specified collection.

Parameters:

c - collection to be checked for intersection in this set.

Returns:

true if this set contains any of the elements of the specified collection.

See Also:

contains(Object)

complement

public ListSet complement(Set other)

Creates an ordered set that is the complement of this set in the supplied set of objects.

addAll

public boolean addAll(Collection c)

Appends all of the elements in the specified collection to the end of this set, 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 set, and it's nonempty.)

Specified by:

addAll in interface List

Overrides:

addAll in class AbstractCollection

Parameters:

c - collection whose elements are to be added to this set.

Returns:

true if this set changed as a result of the call.

Throws:

UnsupportedOperationException - if the add method is not supported by the backing list.

ClassCastException - if the class of an element in the specified collection prevents it from being added to the backing list.

IllegalArgumentException - if some aspect of an element in the specified collection prevents it from being added to the backing list.

See Also:

add(Object)

addAll

public boolean addAll(int index,
                      Collection c)

Inserts all of the elements in the specified collection into this set 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 set 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 set, and it's nonempty.)

Specified by:

addAll in interface List

Parameters:

index - index at which to insert first element from the specified collection.

c - elements to be inserted into this set.

Returns:

true if this set changed as a result of the call.

Throws:

UnsupportedOperationException - if the addAll method is not supported by the backing list.

ClassCastException - if the class of one of elements of the specified collection prevents it from being added to the backing list.

IllegalArgumentException - if some aspect of one of elements of the specified collection prevents it from being added to the backing list.

IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).

removeAll

public boolean removeAll(Collection c)

Removes from this set all the elements that are contained in the specified collection (optional operation).

Specified by:

removeAll in interface List

Overrides:

removeAll in class AbstractSet

Parameters:

c - collection that defines which elements will be removed from this set.

Returns:

true if this set changed as a result of the call.

Throws:

UnsupportedOperationException - if the removeAll method is not supported by the backing list.

See Also:

remove(Object), contains(Object)

retainAll

public boolean retainAll(Collection c)

Retains only the elements in this set that are contained in the specified collection (optional operation). In other words, removes from this set all the elements that are not contained in the specified collection.

Specified by:

retainAll in interface List

Overrides:

retainAll in class AbstractCollection

Parameters:

c - collection that defines which elements this set will retain.

Returns:

true if this set changed as a result of the call.

Throws:

UnsupportedOperationException - if the retainAll method is not supported by the backing list.

See Also:

remove(Object), contains(Object)

clear

public void clear()

Removes all of the elements from this set (optional operation). This set will be empty after this call returns (unless it throws an exception).

Specified by:

clear in interface List

Overrides:

clear in class AbstractCollection

Throws:

UnsupportedOperationException - if the clear method is not supported by the backing list.

get

public Object get(int index)

Returns the element at the specified position in this set.

Specified by:

get in interface List

Parameters:

index - index of element to return.

Returns:

the element at the specified position in this set.

Throws:

IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

set

public Object set(int index,
                  Object element)

Replaces the element at the specified position in this set with the specified element (optional operation).

Specified by:

set in interface List

Parameters:

index - index of element to replace.

element - element to be stored at the specified position; this element must not be currently in the set.

Returns:

the element previously at the specified position.

Throws:

UnsupportedOperationException - if the set method is not supported by the backing list.

ClassCastException - if the class of the specified element prevents it from being added to the backing list.

IllegalArgumentException - if the supplied element is already in the set

IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

add

public void add(int index,
                Object element)

Inserts the specified element at the specified position in this set (optional operation). Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

Specified by:

add in interface List

Parameters:

index - index at which the specified element is to be inserted.

element - element to be inserted.

Throws:

UnsupportedOperationException - if the add method is not supported by the backing list.

ClassCastException - if the class of the specified element prevents it from being added to the backing list.

IllegalArgumentException - if the supplied element is already in this set

IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).

remove

public Object remove(int index)

Removes the element at the specified position in this set (optional operation). Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the set.

Specified by:

remove in interface List

Parameters:

index - the index of the element to removed.

Returns:

the element previously at the specified position.

Throws:

UnsupportedOperationException - if the remove method is not supported by the backing list.

IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

indexOf

public int indexOf(Object o)

Returns the index in this set of the specified element, or -1 if this set does not contain this element.

Specified by:

indexOf in interface List

Parameters:

o - element to search for.

Returns:

the index in this set of the specified element, or -1 if this set does not contain this element.

lastIndexOf

public int lastIndexOf(Object o)

Returns the index in this set of the specified element, or -1 if this set does not contain this element.

Specified by:

lastIndexOf in interface List

Parameters:

o - element to search for.

Returns:

the index in this set of the specified element, or -1 if this set does not contain this element.

listIterator

public ListIterator listIterator()

Returns a list iterator of the elements in this set (in proper sequence).

Specified by:

listIterator in interface List

Returns:

a list iterator of the elements in this set (in proper sequence).

listIterator

public ListIterator listIterator(int index)

Returns a list iterator of the elements in this list (in proper sequence), starting at the specified position in this set. 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.

Specified by:

listIterator in interface List

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:

IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).

subList

public List subList(int fromIndex,
                    int toIndex)

Returns a view of the portion of this set between the specified fromIndex, inclusive, and toIndex, exclusive. (If fromIndex and toIndex are equal, the returned set is empty.) The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all of the optional operations supported by this list.

Specified by:

subList in interface List

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:

IndexOutOfBoundsException - for an illegal endpoint index value (fromIndex < 0 || toIndex > size || fromIndex > toIndex).