Package org.apache.commons.collections4.list

# Class SetUniqueList<E>

java.lang.Object
org.apache.commons.collections4.collection.AbstractCollectionDecorator<E>
org.apache.commons.collections4.list.AbstractListDecorator<E>
org.apache.commons.collections4.list.AbstractSerializableListDecorator<E>
org.apache.commons.collections4.list.SetUniqueList<E>

All Implemented Interfaces:
  `Serializable`, `Iterable<E>`, `Collection<E>`, `List<E>`

public class SetUniqueList<E> extends AbstractSerializableListDecorator<E>
Decorates a `List` to ensure that no duplicates are present much like a `Set`.

The `List` interface makes certain assumptions/requirements. This implementation breaks these in certain ways, but this is merely the result of rejecting duplicates. Each violation is explained in the method, but it should not affect you. Bear in mind that Sets require immutable objects to function correctly.

The `ListOrderedSet` class provides an alternative approach, by wrapping an existing Set and retaining insertion order in the iterator.

This class is Serializable from Commons Collections 3.1.

Since:
  3.0
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `SetUniqueList(List<E> list, Set<E> set)`
  Constructor that wraps (not copies) the List and specifies the set to use.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(int index, E object)`
  Adds an element to a specific index in the list if it is not already present.
  `boolean`
  `add(E object)`
  Adds an element to the list if it is not already present.
  `boolean`
  `addAll(int index, Collection<? extends E> coll)`
  Adds a collection of objects a specific index in the list avoiding duplicates.
  `boolean`
  `addAll(Collection<? extends E> coll)`
  Adds a collection of objects to the end of the list avoiding duplicates.
  `Set<E>`
  `asSet()`
  Gets an unmodifiable view as a Set.
  `void`
  `clear()`
  `boolean`
  `contains(Object object)`
  `boolean`
  `containsAll(Collection<?> coll)`
  `protected Set<E>`
  `createSetBasedOnList(Set<E> set, List<E> list)`
  Create a new `Set` with the same type as the provided `set` and populate it with all elements of `list`.
  `Iterator<E>`
  `iterator()`
  `ListIterator<E>`
  `listIterator()`
  `ListIterator<E>`
  `listIterator(int index)`
  `E`
  `remove(int index)`
  `boolean`
  `remove(Object object)`
  `boolean`
  `removeAll(Collection<?> coll)`
  `boolean`
  `removeIf(Predicate<? super E> filter)`
  `boolean`
  `retainAll(Collection<?> coll)`
  `E`
  `set(int index, E object)`
  Sets the value at the specified index avoiding duplicates.
  `static <E> SetUniqueList<E>`
  `setUniqueList(List<E> list)`
  Factory method to create a SetList using the supplied list to retain order.
  `List<E>`
  `subList(int fromIndex, int toIndex)`

  ### Methods inherited from class org.apache.commons.collections4.list.AbstractListDecorator

  `decorated, equals, get, hashCode, indexOf, lastIndexOf`

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

  `isEmpty, setCollection, size, toArray, toArray, toString`

  ### 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.List

  `isEmpty, replaceAll, size, sort, spliterator, toArray, toArray`

- ## Constructor Details

  - ### SetUniqueList

    protected SetUniqueList(List<E> list, Set<E> set)
    Constructor that wraps (not copies) the List and specifies the set 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

  - ### setUniqueList

    public static <E> SetUniqueList<E> setUniqueList(List<E> list)
    Factory method to create a SetList using the supplied list to retain order.

    If the list contains duplicates, these are removed (first indexed one kept). A `HashSet` is used for the set behavior.

    Type Parameters:
      `E` - the element type
    Parameters:
      `list` - the list to decorate, must not be null
    Returns:
      a new `SetUniqueList`
    Throws:
      `NullPointerException` - if list is null
    Since:
      4.0

  - ### add

    public boolean add(E object)
    Adds an element to the list if it is not already present.

    (Violation) The `List` interface requires that this method returns `true` always. However, this class may return `false` because of the `Set` behavior.

    Specified by:
      `add` in interface `Collection<E>`
    Specified by:
      `add` in interface `List<E>`
    Overrides:
      `add` in class `AbstractCollectionDecorator<E>`
    Parameters:
      `object` - the object to add
    Returns:
      true if object was added

  - ### add

    public void add(int index, E object)
    Adds an element to a specific index in the list if it is not already present.

    (Violation) The `List` interface makes the assumption that the element is always inserted. This may not happen with this implementation.

    Specified by:
      `add` in interface `List<E>`
    Overrides:
      `add` in class `AbstractListDecorator<E>`
    Parameters:
      `index` - the index to insert at
      `object` - the object to add

  - ### addAll

    public boolean addAll(Collection<? extends E> coll)
    Adds a collection of objects to the end of the list avoiding duplicates.

    Only elements that are not already in this list will be added, and duplicates from the specified collection will be ignored.

    (Violation) The `List` interface makes the assumption that the elements are always inserted. This may not happen with this implementation.

    Specified by:
      `addAll` in interface `Collection<E>`
    Specified by:
      `addAll` in interface `List<E>`
    Overrides:
      `addAll` in class `AbstractCollectionDecorator<E>`
    Parameters:
      `coll` - the collection to add in iterator order
    Returns:
      true if this collection changed

  - ### addAll

    public boolean addAll(int index, Collection<? extends E> coll)
    Adds a collection of objects a specific index in the list avoiding duplicates.

    Only elements that are not already in this list will be added, and duplicates from the specified collection will be ignored.

    (Violation) The `List` interface makes the assumption that the elements are always inserted. This may not happen with this implementation.

    Specified by:
      `addAll` in interface `List<E>`
    Overrides:
      `addAll` in class `AbstractListDecorator<E>`
    Parameters:
      `index` - the index to insert at
      `coll` - the collection to add in iterator order
    Returns:
      true if this collection changed

  - ### asSet

    public Set<E> asSet()
    Gets an unmodifiable view as a Set.
    Returns:
      an unmodifiable set view

  - ### clear

    public void clear()
    Specified by:
      `clear` in interface `Collection<E>`
    Specified by:
      `clear` in interface `List<E>`
    Overrides:
      `clear` in class `AbstractCollectionDecorator<E>`

  - ### contains

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

  - ### containsAll

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

  - ### createSetBasedOnList

    protected Set<E> createSetBasedOnList(Set<E> set, List<E> list)
    Create a new `Set` with the same type as the provided `set` and populate it with all elements of `list`.
    Parameters:
      `set` - the `Set` to be used as return type, must not be null
      `list` - the `List` to populate the `Set`
    Returns:
      a new `Set` populated with all elements of the provided `List`

  - ### iterator

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

  - ### listIterator

    public ListIterator<E> listIterator()
    Specified by:
      `listIterator` in interface `List<E>`
    Overrides:
      `listIterator` in class `AbstractListDecorator<E>`

  - ### listIterator

    public ListIterator<E> listIterator(int index)
    Specified by:
      `listIterator` in interface `List<E>`
    Overrides:
      `listIterator` in class `AbstractListDecorator<E>`

  - ### remove

    public E remove(int index)
    Specified by:
      `remove` in interface `List<E>`
    Overrides:
      `remove` in class `AbstractListDecorator<E>`

  - ### remove

    public boolean remove(Object object)
    Specified by:
      `remove` in interface `Collection<E>`
    Specified by:
      `remove` in interface `List<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 `List<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 list, checking each element in turn to see if it's contained in `coll`. If it's not contained, it's removed from this list. 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 `List<E>`
    Overrides:
      `retainAll` in class `AbstractCollectionDecorator<E>`

  - ### set

    public E set(int index, E object)
    Sets the value at the specified index avoiding duplicates.

    The object is set into the specified index. Afterwards, any previous duplicate is removed. If the object is not already in the list then a normal set occurs. If it is present, then the old version is removed.

    Specified by:
      `set` in interface `List<E>`
    Overrides:
      `set` in class `AbstractListDecorator<E>`
    Parameters:
      `index` - the index to insert at
      `object` - the object to set
    Returns:
      the previous object

  - ### subList

    public List<E> subList(int fromIndex, int toIndex)

    NOTE: from 4.0, an unmodifiable list will be returned, as changes to the subList can invalidate the parent list.

    Specified by:
      `subList` in interface `List<E>`
    Overrides:
      `subList` in class `AbstractListDecorator<E>`