Top Description Inners Fields Constructors Methods
org.apache.commons.collections4.set

public Class ListOrderedSet<E>

extends AbstractSerializableSetDecorator<E>
Class Inheritance
Type Parameters
<E>
the type of the elements in this set
Imports
java.util.ArrayList, .Collection, .HashSet, .Iterator, .List, .ListIterator, .Set, .Objects, java.util.function.Predicate, org.apache.commons.collections4.CollectionUtils, .OrderedIterator, org.apache.commons.collections4.functors.UniquePredicate, org.apache.commons.collections4.iterators.AbstractIteratorDecorator, org.apache.commons.collections4.list.UnmodifiableList
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

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static class
ListOrderedSet.OrderedSetIterator<E>

Internal iterator handle remove.

Field Summary

Modifier and TypeField and Description
private static final long
serialVersionUID

Hides org.apache.commons.collections4.set.AbstractSerializableSetDecorator.serialVersionUID.

Serialization version
private final List<E>
setOrder

Internal list to hold the sequence of objects

Constructor Summary

AccessConstructor and Description
public
ListOrderedSet()

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

protected
ListOrderedSet(final Set<E>
the set to decorate, must not be null
set)

Constructor that wraps (not copies).

protected
ListOrderedSet(final Set<E>
the set to decorate, must not be null
set, final List<E>
the list to decorate, must not be null
list)

Constructor that wraps (not copies) the Set and specifies the list to use.

Method Summary

Modifier and TypeMethod and Description
public boolean
add(final E
element to be added to this set
object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.add.

Implements java.util.Set.add, java.util.Collection.add.

Adds the specified element to this set if it is not already present (optional operation).
public void
add(final int
the index at which the element is to be inserted
index, final E
the element to be inserted
object)

Inserts the specified element at the specified position if it is not yet contained in this ordered set (optional operation).

public boolean
addAll(final Collection<? extends E>
collection containing elements to be added to this set
coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.addAll.

Implements java.util.Set.addAll, java.util.Collection.addAll.

Adds all of the elements in the specified collection to this set if they're not already present (optional operation).
public boolean

Returns:

true if this ordered set changed as a result of the call
addAll(final int
the position to insert the elements
index, final Collection<? extends E>
the collection containing the elements to be inserted
coll)

Inserts all elements in the specified collection not yet contained in the ordered set at the specified position (optional operation).

public List<E>

Returns:

an unmodifiable list view
asList()

Gets an unmodifiable view of the order of the Set.

public void
clear()

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.clear.

Implements java.util.Set.clear, java.util.Collection.clear.

Removes all of the elements from this set (optional operation).
public E

Returns:

the element at position index
get(final int
the position of the element in the ordered Set.
index)

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

public int

Returns:

the index of the first occurrence of the object, or -1 if this ordered set does not contain this object
indexOf(final Object
the element to search for
object)

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

public OrderedIterator<E>
iterator()

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.iterator.

Implements java.util.Set.iterator, java.util.Collection.iterator.

Returns an iterator over the elements in this set.
public static <
the element type
E> ListOrderedSet<E>

Returns:

a new ordered set
listOrderedSet(final Set<E>
the set to decorate, must be empty and not null
set, final List<E>
the list to decorate, must be empty and not null
list)

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

public static <
the element type
E> ListOrderedSet<E>

Returns:

a new ordered set
listOrderedSet(final Set<E>
the set to decorate, must not be null
set)

Factory method to create an ordered set.

public static <
the element type
E> ListOrderedSet<E>

Returns:

a new ordered set
listOrderedSet(final List<E>
the list to decorate, must not be null
list)

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

public boolean
remove(final Object
object to be removed from this set, if present
object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.remove.

Implements java.util.Set.remove, java.util.Collection.remove.

Removes the specified element from this set if it is present (optional operation).
public E

Returns:

the element that has been remove from the ordered set
remove(final int
the index of the element to be removed
index)

Removes the element at the specified position from the ordered set.

public boolean
removeAll(final Collection<?>
collection containing elements to be removed from this set
coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.removeAll.

Implements java.util.Set.removeAll, java.util.Collection.removeAll.

Removes from this set all of its elements that are contained in the specified collection (optional operation).
public boolean
removeIf(final Predicate<? super E>
a predicate which returns true for elements to be removed
filter)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.removeIf.

Overrides default java.util.Collection.removeIf.

Removes all of the elements of this collection that satisfy the given predicate.
public boolean
retainAll(final Collection<?>
collection containing elements to be retained in this set
coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.retainAll.

Implements java.util.Set.retainAll, java.util.Collection.retainAll.

Retains only the elements in this set that are contained in the specified collection (optional operation).
public Object[]
toArray()

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.toArray.

Implements java.util.Set.toArray, java.util.Collection.toArray.

Returns an array containing all of the elements in this set.
public <T> T[]
toArray(final T[]
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.
a)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.toArray.

Implements java.util.Set.toArray, java.util.Collection.toArray.

Returns an array containing all of the elements in this set; the runtime type of the returned array is that of the specified array.
public String

Returns:

a string representation of the ordered set
toString()

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.toString.

Uses the underlying List's toString so that order is achieved.

Field Detail

serialVersionUIDback to summary
private static final long serialVersionUID

Hides org.apache.commons.collections4.set.AbstractSerializableSetDecorator.serialVersionUID.

Serialization version

setOrderback to summary
private final List<E> setOrder

Internal list to hold the sequence of objects

Constructor Detail

ListOrderedSetback to summary
public ListOrderedSet()

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

Since
3.1
ListOrderedSetback to summary
protected ListOrderedSet(final Set<E> set)

Constructor that wraps (not copies).

Parameters
set:Set<E>

the set to decorate, must not be null

Exceptions
IllegalArgumentException:
if set is null
ListOrderedSetback to summary
protected ListOrderedSet(final Set<E> set, final List<E> list)

Constructor that wraps (not copies) the Set and specifies the list to use.

The set and list must both be correctly initialised to the same elements.

Parameters
set:Set<E>

the set to decorate, must not be null

list:List<E>

the list to decorate, must not be null

Exceptions
NullPointerException:
if set or list is null

Method Detail

addback to summary
public boolean add(final E object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.add.

Implements java.util.Set.add, java.util.Collection.add.

Doc from java.util.Set.add.

Adds the specified element to this set if it is not already present (optional operation). More formally, adds the specified element e to this set if the set contains no element e2 such that Objects.equals(e, e2). If this set already contains the element, the call leaves the set unchanged and returns false. In combination with the restriction on constructors, this ensures that sets never contain duplicate elements.

The stipulation above does not imply that sets must accept all elements; sets may refuse to add any particular element, including null, and throw an exception, as described in the specification for Collection.add. Individual set implementations should clearly document any restrictions on the elements that they may contain.

Parameters
object:E

element to be added to this set

Returns:boolean

true if this set did not already contain the specified element

Annotations
@Override
addback to summary
public void add(final int index, final 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:int

the index at which the element is to be inserted

object:E

the element to be inserted

See Also
List#add(int, Object)
addAllback to summary
public boolean addAll(final Collection<? extends E> coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.addAll.

Implements java.util.Set.addAll, java.util.Collection.addAll.

Doc from java.util.Set.addAll.

Adds all of the elements in the specified collection to this set if they're not already present (optional operation). If the specified collection is also a set, the addAll operation effectively modifies this set so that its value is the union of the two sets. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress.

Parameters
coll:Collection<? extends E>

collection containing elements to be added to this set

Returns:boolean

true if this set changed as a result of the call

Annotations
@Override
addAllback to summary
public boolean addAll(final int index, final 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:int

the position to insert the elements

coll:Collection<? extends E>

the collection containing the elements to be inserted

Returns:boolean

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

See Also
List#addAll(int, Collection)
asListback to summary
public List<E> asList()

Gets an unmodifiable view of the order of the Set.

Returns:List<E>

an unmodifiable list view

clearback to summary
public void clear()

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.clear.

Implements java.util.Set.clear, java.util.Collection.clear.

Doc from java.util.Set.clear.

Removes all of the elements from this set (optional operation). The set will be empty after this call returns.

Annotations
@Override
getback to summary
public E get(final int index)

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

Parameters
index:int

the position of the element in the ordered Set.

Returns:E

the element at position index

See Also
List#get(int)
indexOfback to summary
public int indexOf(final Object object)

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

Parameters
object:Object

the element to search for

Returns:int

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)
iteratorback to summary
public OrderedIterator<E> iterator()

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.iterator.

Implements java.util.Set.iterator, java.util.Collection.iterator.

Doc from java.util.Set.iterator.

Returns an iterator over the elements in this set. The elements are returned in no particular order (unless this set is an instance of some class that provides a guarantee).

Returns:OrderedIterator<E>

an iterator over the elements in this set

Annotations
@Override
listOrderedSetback to summary
public static <E> ListOrderedSet<E> listOrderedSet(final Set<E> set, final 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.

Parameters
<E>
the element type
set:Set<E>

the set to decorate, must be empty and not null

list:List<E>

the list to decorate, must be empty and not null

Returns:ListOrderedSet<E>

a new ordered set

Exceptions
NullPointerException:
if set or list is null
IllegalArgumentException:
if either the set or list is not empty
Since
4.0
listOrderedSetback to summary
public static <E> ListOrderedSet<E> listOrderedSet(final Set<E> set)

Factory method to create an ordered set.

An ArrayList is used to retain order.

Parameters
<E>
the element type
set:Set<E>

the set to decorate, must not be null

Returns:ListOrderedSet<E>

a new ordered set

Exceptions
NullPointerException:
if set is null
Since
4.0
listOrderedSetback to summary
public static <E> ListOrderedSet<E> listOrderedSet(final 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.

Parameters
<E>
the element type
list:List<E>

the list to decorate, must not be null

Returns:ListOrderedSet<E>

a new ordered set

Exceptions
NullPointerException:
if list is null
Since
4.0
removeback to summary
public boolean remove(final Object object)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.remove.

Implements java.util.Set.remove, java.util.Collection.remove.

Doc from java.util.Set.remove.

Removes the specified element from this set if it is present (optional operation). More formally, removes an element e such that Objects.equals(o, e), if this set contains such an element. Returns true if this set contained the element (or equivalently, if this set changed as a result of the call). (This set will not contain the element once the call returns.)

Parameters
object:Object

object to be removed from this set, if present

Returns:boolean

true if this set contained the specified element

Annotations
@Override
removeback to summary
public E remove(final int index)

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

Parameters
index:int

the index of the element to be removed

Returns:E

the element that has been remove from the ordered set

See Also
List#remove(int)
removeAllback to summary
public boolean removeAll(final Collection<?> coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.removeAll.

Implements java.util.Set.removeAll, java.util.Collection.removeAll.

Doc from java.util.Set.removeAll.

Removes from this set all of its elements that are contained in the specified collection (optional operation). If the specified collection is also a set, this operation effectively modifies this set so that its value is the asymmetric set difference of the two sets.

Parameters
coll:Collection<?>

collection containing elements to be removed from this set

Returns:boolean

true if this set changed as a result of the call

Annotations
@Override
removeIfback to summary
public boolean removeIf(final Predicate<? super E> filter)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.removeIf.

Overrides default java.util.Collection.removeIf.

Doc from java.util.Collection.removeIf.

Removes all of the elements of this collection that satisfy the given predicate. Errors or runtime exceptions thrown during iteration or by the predicate are relayed to the caller.

Parameters
filter:Predicate<? super E>

a predicate which returns true for elements to be removed

Returns:boolean

true if any elements were removed

Annotations
@Override
Since
4.4
retainAllback to summary
public boolean retainAll(final Collection<?> coll)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.retainAll.

Implements java.util.Set.retainAll, java.util.Collection.retainAll.

Doc from java.util.Set.retainAll.

Retains only the elements in this set that are contained in the specified collection (optional operation). In other words, removes from this set all of its elements that are not contained in the specified collection. If the specified collection is also a set, this operation effectively modifies this set so that its value is the intersection of the two sets.

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

Parameters
coll:Collection<?>

collection containing elements to be retained in this set

Returns:boolean

true if this set changed as a result of the call

Annotations
@Override
toArrayback to summary
public Object[] toArray()

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.toArray.

Implements java.util.Set.toArray, java.util.Collection.toArray.

Doc from java.util.Set.toArray.

Returns an array containing all of the elements in this set. If this set makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

The returned array will be "safe" in that no references to it are maintained by this set. (In other words, this method must allocate a new array even if this set is backed by an array). The caller is thus free to modify the returned array.

This method acts as bridge between array-based and collection-based APIs.

Returns:Object[]

an array containing all the elements in this set

Annotations
@Override
toArrayback to summary
public <T> T[] toArray(final T[] a)

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.toArray.

Implements java.util.Set.toArray, java.util.Collection.toArray.

Doc from java.util.Set.toArray.

Returns an array containing all of the elements in this set; the runtime type of the returned array is that of the specified array. If the set fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this set.

If this set fits in the specified array with room to spare (i.e., the array has more elements than this set), the element in the array immediately following the end of the set is set to null. (This is useful in determining the length of this set only if the caller knows that this set does not contain any null elements.)

If this set makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

Like the toArray() method, this method acts as bridge between array-based and collection-based APIs. Further, this method allows precise control over the runtime type of the output array, and may, under certain circumstances, be used to save allocation costs.

Suppose x is a set known to contain only strings. The following code can be used to dump the set into a newly allocated array of String: 

    String[] y = x.toArray(new String[0]);
Note that toArray(new Object[0]) is identical in function to toArray().
Parameters
<T>

Doc from java.util.Collection.toArray. the component type of the array to contain the collection

a:T[]

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:T[]

an array containing all the elements in this set

Annotations
@Override
toStringback to summary
public String toString()

Overrides org.apache.commons.collections4.collection.AbstractCollectionDecorator.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.

Returns:String

a string representation of the ordered set

Annotations
@Override
org.apache.commons.collections4.set back to summary

pack-priv Class ListOrderedSet.OrderedSetIterator<E>

extends AbstractIteratorDecorator<E>
implements OrderedIterator<E>
Class Inheritance
All Implemented Interfaces
org.apache.commons.collections4.OrderedIterator, java.util.Iterator
Internal iterator handle remove.

Field Summary

Modifier and TypeField and Description
private E
last

Last object retrieved

private final Collection<E>
set

Object we iterate on

Constructor Summary

AccessConstructor and Description
private
OrderedSetIterator(final ListIterator<E> iterator, final Collection<E> set)

Method Summary

Modifier and TypeMethod and Description
public boolean
hasPrevious()

Implements org.apache.commons.collections4.OrderedIterator.hasPrevious.

Checks to see if there is a previous element that can be iterated to.
public E
next()

Overrides org.apache.commons.collections4.iterators.AbstractIteratorDecorator.next.

Implements java.util.Iterator.next.

Returns the next element in the iteration.
public E
previous()

Implements org.apache.commons.collections4.OrderedIterator.previous.

Gets the previous element from the container.
public void
remove()

Overrides org.apache.commons.collections4.iterators.AbstractUntypedIteratorDecorator.remove.

Overrides default java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation).

Field Detail

lastback to summary
private E last

Last object retrieved

setback to summary
private final Collection<E> set

Object we iterate on

Constructor Detail

OrderedSetIteratorback to summary
private OrderedSetIterator(final ListIterator<E> iterator, final Collection<E> set)

Method Detail

hasPreviousback to summary
public boolean hasPrevious()

Implements org.apache.commons.collections4.OrderedIterator.hasPrevious.

Doc from org.apache.commons.collections4.OrderedIterator.hasPrevious.

Checks to see if there is a previous element that can be iterated to.

Returns:boolean

true if the iterator has a previous element

Annotations
@Override
nextback to summary
public E next()

Overrides org.apache.commons.collections4.iterators.AbstractIteratorDecorator.next.

Implements java.util.Iterator.next.

Doc from java.util.Iterator.next.

Returns the next element in the iteration.

Returns:E

the next element in the iteration

Annotations
@Override
previousback to summary
public E previous()

Implements org.apache.commons.collections4.OrderedIterator.previous.

Doc from org.apache.commons.collections4.OrderedIterator.previous.

Gets the previous element from the container.

Returns:E

the previous element in the iteration

Annotations
@Override
removeback to summary
public void remove()

Overrides org.apache.commons.collections4.iterators.AbstractUntypedIteratorDecorator.remove.

Overrides default java.util.Iterator.remove.

Doc from java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation). This method can be called only once per call to next.

The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method, unless an overriding class has specified a concurrent modification policy.

The behavior of an iterator is unspecified if this method is called after a call to the forEachRemaining method.

Annotations
@Override