Package 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>

Type Parameters:
  `E` - the type of the elements in this set

All Implemented Interfaces:
  `Serializable`, `Iterable<E>`, `Collection<E>`, `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
  Modifier
  Constructor
  Description
  ``
  `ListOrderedSet()`
  Constructs a new empty `ListOrderedSet` using a `HashSet` and an `ArrayList` internally.
  `protected`
  `ListOrderedSet(Set<E> set)`
  Constructor that wraps (not copies).
  `protected`
  `ListOrderedSet(Set<E> set, List<E> list)`
  Constructor that wraps (not copies) the Set and specifies the list to use.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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`
  `add(E object)`
  `boolean`
  `addAll(int index, Collection<? extends E> coll)`
  Inserts all elements in the specified collection not yet contained in the ordered set at the specified position (optional operation).
  `boolean`
  `addAll(Collection<? extends E> coll)`
  `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(Object object)`
  Returns the index of the first occurrence of the specified element in ordered set.
  `OrderedIterator<E>`
  `iterator()`
  `static <E> ListOrderedSet<E>`
  `listOrderedSet(List<E> list)`
  Factory method to create an ordered set using the supplied list to retain order.
  `static <E> ListOrderedSet<E>`
  `listOrderedSet(Set<E> set)`
  Factory method to create an ordered set.
  `static <E> ListOrderedSet<E>`
  `listOrderedSet(Set<E> set, 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(Object object)`
  `boolean`
  `removeAll(Collection<?> coll)`
  `boolean`
  `removeIf(Predicate<? super E> filter)`
  `boolean`
  `retainAll(Collection<?> coll)`
  `Object[]`
  `toArray()`
  `<T> T[]`
  `toArray(T[] a)`
  `String`
  `toString()`
  Uses the underlying List's toString so that order is achieved.

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

  `decorated, equals, hashCode`

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

  `contains, containsAll, isEmpty, setCollection, size`

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface java.util.Collection

  `parallelStream, stream`

  ### Methods inherited from interface java.lang.Iterable

  `forEach`

  ### Methods inherited from interface java.util.Set

  `contains, containsAll, isEmpty, size, spliterator`

- ## Constructor Details

  - ### ListOrderedSet

    public ListOrderedSet()
    Constructs a new empty `ListOrderedSet` using a `HashSet` and an `ArrayList` internally.
    Since:
      3.1

  - ### ListOrderedSet

    protected ListOrderedSet(Set<E> set)
    Constructor that wraps (not copies).
    Parameters:
      `set` - the set to decorate, must not be null
    Throws:
      `NullPointerException` - if set is null

  - ### ListOrderedSet

    protected ListOrderedSet(Set<E> set, List<E> list)
    Constructor that wraps (not copies) the Set and specifies the list to use.

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

    Parameters:
      `set` - the set to decorate, must not be null
      `list` - the list to decorate, must not be null
    Throws:
      `NullPointerException` - if set or list is null

- ## Method Details

  - ### listOrderedSet

    public static <E> ListOrderedSet<E> listOrderedSet(List<E> list)
    Factory method to create an ordered set using the supplied list to retain order.

    A `HashSet` is used for the set behavior.

    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:
      `NullPointerException` - if list is null
    Since:
      4.0

  - ### listOrderedSet

    public static <E> ListOrderedSet<E> listOrderedSet(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:
      `NullPointerException` - if set is null
    Since:
      4.0

  - ### listOrderedSet

    public static <E> ListOrderedSet<E> listOrderedSet(Set<E> set, 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:
      `NullPointerException` - if set or list is null
      `IllegalArgumentException` - if either the set or list is not empty
    Since:
      4.0

  - ### add

    public boolean add(E object)
    Specified by:
      `add` in interface `Collection<E>`
    Specified by:
      `add` in interface `Set<E>`
    Overrides:
      `add` in class `AbstractCollectionDecorator<E>`

  - ### 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(Collection<? extends E> coll)
    Specified by:
      `addAll` in interface `Collection<E>`
    Specified by:
      `addAll` in interface `Set<E>`
    Overrides:
      `addAll` in class `AbstractCollectionDecorator<E>`

  - ### addAll

    public boolean addAll(int index, 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)`

  - ### asList

    public 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 `Collection<E>`
    Specified by:
      `clear` in interface `Set<E>`
    Overrides:
      `clear` 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(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)`

  - ### iterator

    public OrderedIterator<E> iterator()
    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`
    Specified by:
      `iterator` in interface `Set<E>`
    Overrides:
      `iterator` in class `AbstractCollectionDecorator<E>`

  - ### 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)`

  - ### remove

    public boolean remove(Object object)
    Specified by:
      `remove` in interface `Collection<E>`
    Specified by:
      `remove` in interface `Set<E>`
    Overrides:
      `remove` in class `AbstractCollectionDecorator<E>`

  - ### removeAll

    public boolean removeAll(Collection<?> coll)
    Specified by:
      `removeAll` in interface `Collection<E>`
    Specified by:
      `removeAll` in interface `Set<E>`
    Overrides:
      `removeAll` in class `AbstractCollectionDecorator<E>`

  - ### removeIf

    public boolean removeIf(Predicate<? super E> filter)
    Specified by:
      `removeIf` in interface `Collection<E>`
    Overrides:
      `removeIf` in class `AbstractCollectionDecorator<E>`
    Since:
      4.4

  - ### retainAll

    public boolean retainAll(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 `Collection<E>`
    Specified by:
      `retainAll` in interface `Set<E>`
    Overrides:
      `retainAll` in class `AbstractCollectionDecorator<E>`

  - ### toArray

    public Object[] toArray()
    Specified by:
      `toArray` in interface `Collection<E>`
    Specified by:
      `toArray` in interface `Set<E>`
    Overrides:
      `toArray` in class `AbstractCollectionDecorator<E>`

  - ### toArray

    public <T> T[] toArray(T[] a)
    Specified by:
      `toArray` in interface `Collection<E>`
    Specified by:
      `toArray` in interface `Set<E>`
    Overrides:
      `toArray` in class `AbstractCollectionDecorator<E>`

  - ### toString

    public 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