org.apache.commons.collections4.set

Class ListOrderedSet<E>

  • 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 Detail

      • 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:
        IllegalArgumentException - 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 initialised 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 Detail

      • 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

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

      • asList

        public List<E> asList()
        Gets an unmodifiable view of the order of the Set.
        Returns:
        an unmodifiable list view

      • clear

        public void clear()

      • add

        public boolean add(E object)

      • addAll

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

      • remove

        public boolean remove(Object object)

      • removeAll

        public boolean removeAll(Collection<?> coll)

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

      • toArray

        public Object[] toArray()

      • toArray

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

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

      • 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,
                      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 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