org.apache.commons.collections4.set

Class ListOrderedSet<E>

java.lang.Object

org.apache.commons.collections4.collection.AbstractCollectionDecorator<E>

org.apache.commons.collections4.set.AbstractSetDecorator<E>

org.apache.commons.collections4.set.AbstractSerializableSetDecorator<E>

org.apache.commons.collections4.set.ListOrderedSet<E>

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.Set<E>

public class ListOrderedSet<E>
extends AbstractSerializableSetDecorator<E>

Decorates another Set to ensure that the order of addition is retained and used by the iterator.

If an object is added to the set for a second time, it will remain in the original position in the iteration. The order can be observed from the set via the iterator or toArray methods.

The ListOrderedSet also has various useful direct methods. These include many from List, such as get(int), remove(int) and indexOf(int). An unmodifiable List view of the set can be obtained via asList().

This class cannot implement the List interface directly as various interface methods (notably equals/hashCode) are incompatible with a set.

This class is Serializable from Commons Collections 3.1.

Since:

3.0

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
ListOrderedSet() Constructs a new empty ListOrderedSet using a HashSet and an ArrayList internally.

Method Summary

Modifier and Type	Method and Description
boolean	add(E object)
void	add(int index, E object) Inserts the specified element at the specified position if it is not yet contained in this ordered set (optional operation).
boolean	addAll(java.util.Collection<? extends E> coll)
boolean	addAll(int index, java.util.Collection<? extends E> coll) Inserts all elements in the specified collection not yet contained in the ordered set at the specified position (optional operation).
java.util.List<E>	asList() Gets an unmodifiable view of the order of the Set.
void	clear()
E	get(int index) Returns the element at the specified position in this ordered set.
int	indexOf(java.lang.Object object) Returns the index of the first occurrence of the specified element in ordered set.
OrderedIterator<E>	iterator()
static <E> ListOrderedSet<E>	listOrderedSet(java.util.List<E> list) Factory method to create an ordered set using the supplied list to retain order.
static <E> ListOrderedSet<E>	listOrderedSet(java.util.Set<E> set) Factory method to create an ordered set.
static <E> ListOrderedSet<E>	listOrderedSet(java.util.Set<E> set, java.util.List<E> list) Factory method to create an ordered set specifying the list and set to use.
E	remove(int index) Removes the element at the specified position from the ordered set.
boolean	remove(java.lang.Object object)
boolean	removeAll(java.util.Collection<?> coll)
boolean	retainAll(java.util.Collection<?> coll)
java.lang.Object[]	toArray()
<T> T[]	toArray(T[] a)
java.lang.String	toString() Uses the underlying List's toString so that order is achieved.

Methods inherited from class org.apache.commons.collections4.set.AbstractSetDecorator

equals, hashCode

Methods inherited from class org.apache.commons.collections4.collection.AbstractCollectionDecorator

contains, containsAll, isEmpty, size

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Set

contains, containsAll, isEmpty, size, spliterator

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Constructor Detail

ListOrderedSet

public ListOrderedSet()

Constructs a new empty ListOrderedSet using a HashSet and an ArrayList internally.

Since:

3.1

Method Detail

listOrderedSet

public static <E> ListOrderedSet<E> listOrderedSet(java.util.Set<E> set,
                                                   java.util.List<E> list)

Factory method to create an ordered set specifying the list and set to use.

The list and set must both be empty.

Type Parameters:

E - the element type

Parameters:

set - the set to decorate, must be empty and not null

list - the list to decorate, must be empty and not null

Returns:

a new ordered set

Throws:

java.lang.NullPointerException - if set or list is null

java.lang.IllegalArgumentException - if either the set or list is not empty

Since:

4.0

listOrderedSet

public static <E> ListOrderedSet<E> listOrderedSet(java.util.Set<E> set)

Factory method to create an ordered set.

An ArrayList is used to retain order.

Type Parameters:

E - the element type

Parameters:

set - the set to decorate, must not be null

Returns:

a new ordered set

Throws:

java.lang.NullPointerException - if set is null

Since:

4.0

listOrderedSet

public static <E> ListOrderedSet<E> listOrderedSet(java.util.List<E> list)

Factory method to create an ordered set using the supplied list to retain order.

A HashSet is used for the set behaviour.

NOTE: If the list contains duplicates, the duplicates are removed, altering the specified list.

Type Parameters:

E - the element type

Parameters:

list - the list to decorate, must not be null

Returns:

a new ordered set

Throws:

java.lang.NullPointerException - if list is null

Since:

4.0

asList

public java.util.List<E> asList()

Gets an unmodifiable view of the order of the Set.

Returns:

an unmodifiable list view

clear

public void clear()

Specified by:

clear in interface java.util.Collection<E>

Specified by:

clear in interface java.util.Set<E>

Overrides:

clear in class AbstractCollectionDecorator<E>

iterator

public OrderedIterator<E> iterator()

Specified by:

iterator in interface java.lang.Iterable<E>

Specified by:

iterator in interface java.util.Collection<E>

Specified by:

iterator in interface java.util.Set<E>

Overrides:

iterator in class AbstractCollectionDecorator<E>

add

public boolean add(E object)

Specified by:

add in interface java.util.Collection<E>

Specified by:

add in interface java.util.Set<E>

Overrides:

add in class AbstractCollectionDecorator<E>

addAll

public boolean addAll(java.util.Collection<? extends E> coll)

Specified by:

addAll in interface java.util.Collection<E>

Specified by:

addAll in interface java.util.Set<E>

Overrides:

addAll in class AbstractCollectionDecorator<E>

remove

public boolean remove(java.lang.Object object)

Specified by:

remove in interface java.util.Collection<E>

Specified by:

remove in interface java.util.Set<E>

Overrides:

remove in class AbstractCollectionDecorator<E>

removeAll

public boolean removeAll(java.util.Collection<?> coll)

Specified by:

removeAll in interface java.util.Collection<E>

Specified by:

removeAll in interface java.util.Set<E>

Overrides:

removeAll in class AbstractCollectionDecorator<E>

retainAll

public boolean retainAll(java.util.Collection<?> coll)

This implementation iterates over the elements of this set, checking each element in turn to see if it's contained in coll. If it's not contained, it's removed from this set. As a consequence, it is advised to use a collection type for coll that provides a fast (e.g. O(1)) implementation of Collection.contains(Object).

Specified by:

retainAll in interface java.util.Collection<E>

Specified by:

retainAll in interface java.util.Set<E>

Overrides:

retainAll in class AbstractCollectionDecorator<E>

toArray

public java.lang.Object[] toArray()

Specified by:

toArray in interface java.util.Collection<E>

Specified by:

toArray in interface java.util.Set<E>

Overrides:

toArray in class AbstractCollectionDecorator<E>

toArray

public <T> T[] toArray(T[] a)

Specified by:

toArray in interface java.util.Collection<E>

Specified by:

toArray in interface java.util.Set<E>

Overrides:

toArray in class AbstractCollectionDecorator<E>

get

public E get(int index)

Returns the element at the specified position in this ordered set.

Parameters:

index - the position of the element in the ordered Set.

Returns:

the element at position index

See Also:

List.get(int)

indexOf

public int indexOf(java.lang.Object object)

Returns the index of the first occurrence of the specified element in ordered set.

Parameters:

object - the element to search for

Returns:

the index of the first occurrence of the object, or -1 if this ordered set does not contain this object

See Also:

List.indexOf(Object)

add

public void add(int index,
                E object)

Inserts the specified element at the specified position if it is not yet contained in this ordered set (optional operation). Shifts the element currently at this position and any subsequent elements to the right.

Parameters:

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

object - the element to be inserted

See Also:

List.add(int, Object)

addAll

public boolean addAll(int index,
                      java.util.Collection<? extends E> coll)

Inserts all elements in the specified collection not yet contained in the ordered set at the specified position (optional operation). Shifts the element currently at the position and all subsequent elements to the right.

Parameters:

index - the position to insert the elements

coll - the collection containing the elements to be inserted

Returns:

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

See Also:

List.addAll(int, Collection)

remove

public E remove(int index)

Removes the element at the specified position from the ordered set. Shifts any subsequent elements to the left.

Parameters:

index - the index of the element to be removed

Returns:

the element that has been remove from the ordered set

See Also:

List.remove(int)

toString

public java.lang.String toString()

Uses the underlying List's toString so that order is achieved. This means that the decorated Set's toString is not used, so any custom toStrings will be ignored.

Overrides:

toString in class AbstractCollectionDecorator<E>

Returns:

a string representation of the ordered set