# Class Collections

java.lang.Object
java.util.Collections

public class Collections extends Object
`Collections` contains static methods which operate on `Collection` classes.

Since:
  1.2

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final List`
  `EMPTY_LIST`
  An empty immutable instance of `List`.
  `static final Map`
  `EMPTY_MAP`
  An empty immutable instance of `Map`.
  `static final Set`
  `EMPTY_SET`
  An empty immutable instance of `Set`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> boolean`
  `addAll(Collection<? super T> c, T... a)`
  Adds all the specified elements to the specified collection.
  `static <T> Queue<T>`
  `asLifoQueue(Deque<T> deque)`
  Answers a LIFO Queue as a view of a Deque.
  `static <T> int`
  `binarySearch(List<? extends Comparable<? super T>> list, T object)`
  Performs a binary search for the specified element in the specified sorted list.
  `static <T> int`
  `binarySearch(List<? extends T> list, T object, Comparator<? super T> comparator)`
  Performs a binary search for the specified element in the specified sorted list using the specified comparator.
  `static <E> Collection<E>`
  `checkedCollection(Collection<E> c, Class<E> type)`
  Returns a dynamically typesafe view of the specified collection.
  `static <T> void`
  `copy(List<? super T> destination, List<? extends T> source)`
  Copies the elements from the source list to the destination list.
  `static boolean`
  `disjoint(Collection<?> c1, Collection<?> c2)`
  Returns whether the specified collections have no elements in common.
  `static final <T> List<T>`
  `emptyList()`
  Returns a type-safe empty, immutable `List`.
  `static final <K,V> Map<K,V>`
  `emptyMap()`
  Returns a type-safe empty, immutable `Map`.
  `static final <T> Set<T>`
  `emptySet()`
  Returns a type-safe empty, immutable `Set`.
  `static <T> Enumeration<T>`
  `enumeration(Collection<T> collection)`
  Returns an `Enumeration` on the specified collection.
  `static <T> void`
  `fill(List<? super T> list, T object)`
  Fills the specified list with the specified element.
  `static int`
  `frequency(Collection<?> c, Object o)`
  Returns the number of elements in the `Collection` that match the `Object` passed.
  `static int`
  `indexOfSubList(List<?> list, List<?> sublist)`
  Searches the `list` for `sublist` and returns the beginning index of the first occurrence.
  `static int`
  `lastIndexOfSubList(List<?> list, List<?> sublist)`
  Searches the `list` for `sublist` and returns the beginning index of the last occurrence.
  `static <T> ArrayList<T>`
  `list(Enumeration<T> enumeration)`
  Returns an `ArrayList` with all the elements in the `enumeration`.
  `static <T extends Object & Comparable<? super T>>
  T`
  `max(Collection<? extends T> collection)`
  Searches the specified collection for the maximum element.
  `static <T> T`
  `max(Collection<? extends T> collection, Comparator<? super T> comparator)`
  Searches the specified collection for the maximum element using the specified comparator.
  `static <T extends Object & Comparable<? super T>>
  T`
  `min(Collection<? extends T> collection)`
  Searches the specified collection for the minimum element.
  `static <T> T`
  `min(Collection<? extends T> collection, Comparator<? super T> comparator)`
  Searches the specified collection for the minimum element using the specified comparator.
  `static <T> List<T>`
  `nCopies(int length, T object)`
  Returns a list containing the specified number of the specified element.
  `static <E> Set<E>`
  `newSetFromMap(Map<E,Boolean> map)`
  Answers a set backed by a map.
  `static <T> boolean`
  `replaceAll(List<T> list, T obj, T obj2)`
  Replaces all occurrences of Object `obj` in `list` with `newObj`.
  `static void`
  `reverse(List<?> list)`
  Modifies the specified `List` by reversing the order of the elements.
  `static <T> Comparator<T>`
  `reverseOrder()`
  A comparator which reverses the natural order of the elements.
  `static <T> Comparator<T>`
  `reverseOrder(Comparator<T> c)`
  Returns a `Comparator` that reverses the order of the `Comparator` passed.
  `static void`
  `rotate(List<?> lst, int dist)`
  Rotates the elements in `list` by the distance `dist`
  `static void`
  `shuffle(List<?> list)`
  Moves every element of the list to a random new position in the list.
  `static void`
  `shuffle(List<?> list, Random random)`
  Moves every element of the list to a random new position in the list using the specified random number generator.
  `static <E> Set<E>`
  `singleton(E object)`
  Returns a set containing the specified element.
  `static <E> List<E>`
  `singletonList(E object)`
  Returns a list containing the specified element.
  `static <K,V> Map<K,V>`
  `singletonMap(K key, V value)`
  Returns a Map containing the specified key and value.
  `static <T extends Comparable<? super T>>
  void`
  `sort(List<T> list)`
  Sorts the specified list in ascending natural order.
  `static <T> void`
  `sort(List<T> list, Comparator<? super T> comparator)`
  Sorts the specified list using the specified comparator.
  `static void`
  `swap(List<?> list, int index1, int index2)`
  Swaps the elements of list `list` at indices `index1` and `index2`.
  `static <T> Collection<T>`
  `synchronizedCollection(Collection<T> collection)`
  Returns a wrapper on the specified collection which synchronizes all access to the collection.
  `static <T> List<T>`
  `synchronizedList(List<T> list)`
  Returns a wrapper on the specified List which synchronizes all access to the List.
  `static <K,V> Map<K,V>`
  `synchronizedMap(Map<K,V> map)`
  Returns a wrapper on the specified map which synchronizes all access to the map.
  `static <E> Set<E>`
  `synchronizedSet(Set<E> set)`
  Returns a wrapper on the specified set which synchronizes all access to the set.
  `static <K,V> SortedMap<K,V>`
  `synchronizedSortedMap(SortedMap<K,V> map)`
  Returns a wrapper on the specified sorted map which synchronizes all access to the sorted map.
  `static <E> SortedSet<E>`
  `synchronizedSortedSet(SortedSet<E> set)`
  Returns a wrapper on the specified sorted set which synchronizes all access to the sorted set.
  `static <E> Collection<E>`
  `unmodifiableCollection(Collection<? extends E> collection)`
  Returns a wrapper on the specified collection which throws an `UnsupportedOperationException` whenever an attempt is made to modify the collection.
  `static <E> List<E>`
  `unmodifiableList(List<? extends E> list)`
  Returns a wrapper on the specified list which throws an `UnsupportedOperationException` whenever an attempt is made to modify the list.
  `static <K,V> Map<K,V>`
  `unmodifiableMap(Map<? extends K, ? extends V> map)`
  Returns a wrapper on the specified map which throws an `UnsupportedOperationException` whenever an attempt is made to modify the map.
  `static <E> Set<E>`
  `unmodifiableSet(Set<? extends E> set)`
  Returns a wrapper on the specified set which throws an `UnsupportedOperationException` whenever an attempt is made to modify the set.
  `static <K,V> SortedMap<K,V>`
  `unmodifiableSortedMap(SortedMap<K, ? extends V> map)`
  Returns a wrapper on the specified sorted map which throws an `UnsupportedOperationException` whenever an attempt is made to modify the sorted map.
  `static <E> SortedSet<E>`
  `unmodifiableSortedSet(SortedSet<E> set)`
  Returns a wrapper on the specified sorted set which throws an `UnsupportedOperationException` whenever an attempt is made to modify the sorted set.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### EMPTY_LIST

    public static final List EMPTY_LIST
    An empty immutable instance of `List`.

  - ### EMPTY_SET

    public static final Set EMPTY_SET
    An empty immutable instance of `Set`.

  - ### EMPTY_MAP

    public static final Map EMPTY_MAP
    An empty immutable instance of `Map`.

- ## Method Details

  - ### binarySearch

    public static <T> int binarySearch(List<? extends Comparable<? super T>> list, T object)
    Performs a binary search for the specified element in the specified sorted list. The list needs to be already sorted in natural sorting order. Searching in an unsorted array has an undefined result. It's also undefined which element is found if there are multiple occurrences of the same element.
    Parameters:
      `list` - the sorted list to search.
      `object` - the element to find.
    Returns:
      the non-negative index of the element, or a negative index which is the `-index - 1` where the element would be inserted
    Throws:
      `ClassCastException` - if an element in the List or the search element does not implement Comparable, or cannot be compared to each other.

  - ### binarySearch

    public static <T> int binarySearch(List<? extends T> list, T object, Comparator<? super T> comparator)
    Performs a binary search for the specified element in the specified sorted list using the specified comparator. The list needs to be already sorted according to the comparator passed. Searching in an unsorted array has an undefined result. It's also undefined which element is found if there are multiple occurrences of the same element.
    Type Parameters:
      `T` - The element type
    Parameters:
      `list` - the sorted List to search.
      `object` - the element to find.
      `comparator` - the comparator. If the comparator is `null` then the search uses the objects' natural ordering.
    Returns:
      the non-negative index of the element, or a negative index which is the `-index - 1` where the element would be inserted.
    Throws:
      `ClassCastException` - when an element in the list and the searched element cannot be compared to each other using the comparator.

  - ### copy

    public static <T> void copy(List<? super T> destination, List<? extends T> source)
    Copies the elements from the source list to the destination list. At the end both lists will have the same objects at the same index. If the destination array is larger than the source list, the elements in the destination list with `index >= source.size()` will be unchanged.
    Parameters:
      `destination` - the list whose elements are set from the source list.
      `source` - the list with the elements to be copied into the destination.
    Throws:
      `IndexOutOfBoundsException` - when the destination list is smaller than the source list.
      `UnsupportedOperationException` - when replacing an element in the destination list is not supported.

  - ### enumeration

    public static <T> Enumeration<T> enumeration(Collection<T> collection)
    Returns an `Enumeration` on the specified collection.
    Parameters:
      `collection` - the collection to enumerate.
    Returns:
      an Enumeration.

  - ### fill

    public static <T> void fill(List<? super T> list, T object)
    Fills the specified list with the specified element.
    Parameters:
      `list` - the list to fill.
      `object` - the element to fill the list with.
    Throws:
      `UnsupportedOperationException` - when replacing an element in the List is not supported.

  - ### max

    public static <T extends Object & Comparable<? super T>> T max(Collection<? extends T> collection)
    Searches the specified collection for the maximum element.
    Parameters:
      `collection` - the collection to search.
    Returns:
      the maximum element in the Collection.
    Throws:
      `ClassCastException` - when an element in the collection does not implement `Comparable` or elements cannot be compared to each other.

  - ### max

    public static <T> T max(Collection<? extends T> collection, Comparator<? super T> comparator)
    Searches the specified collection for the maximum element using the specified comparator.
    Parameters:
      `collection` - the collection to search.
      `comparator` - the comparator.
    Returns:
      the maximum element in the Collection.
    Throws:
      `ClassCastException` - when elements in the collection cannot be compared to each other using the `Comparator`.

  - ### min

    public static <T extends Object & Comparable<? super T>> T min(Collection<? extends T> collection)
    Searches the specified collection for the minimum element.
    Parameters:
      `collection` - the collection to search.
    Returns:
      the minimum element in the collection.
    Throws:
      `ClassCastException` - when an element in the collection does not implement `Comparable` or elements cannot be compared to each other.

  - ### min

    public static <T> T min(Collection<? extends T> collection, Comparator<? super T> comparator)
    Searches the specified collection for the minimum element using the specified comparator.
    Parameters:
      `collection` - the collection to search.
      `comparator` - the comparator.
    Returns:
      the minimum element in the collection.
    Throws:
      `ClassCastException` - when elements in the collection cannot be compared to each other using the `Comparator`.

  - ### nCopies

    public static <T> List<T> nCopies(int length, T object)
    Returns a list containing the specified number of the specified element. The list cannot be modified. The list is serializable.
    Parameters:
      `length` - the size of the returned list.
      `object` - the element to be added `length` times to a list.
    Returns:
      a list containing `length` copies of the element.
    Throws:
      `IllegalArgumentException` - when `length < 0`.

  - ### reverse

    public static void reverse(List<?> list)
    Modifies the specified `List` by reversing the order of the elements.
    Parameters:
      `list` - the list to reverse.
    Throws:
      `UnsupportedOperationException` - when replacing an element in the List is not supported.

  - ### reverseOrder

    public static <T> Comparator<T> reverseOrder()
    A comparator which reverses the natural order of the elements. The `Comparator` that's returned is
    invalid reference

        Serializable

    .
    Returns:
      a `Comparator` instance.
    See Also:
      - `Comparator`
      - `Comparable`
      - invalid reference

            Serializable

  - ### reverseOrder

    public static <T> Comparator<T> reverseOrder(Comparator<T> c)
    Returns a `Comparator` that reverses the order of the `Comparator` passed. If the `Comparator` passed is `null`, then this method is equivalent to `reverseOrder()`.

    The `Comparator` that's returned is

    invalid reference

        Serializable

    if the `Comparator` passed is serializable or `null`.
    Parameters:
      `c` - the `Comparator` to reverse or `null`.
    Returns:
      a `Comparator` instance.
    Since:
      1.5
    See Also:
      - `Comparator`

  - ### shuffle

    public static void shuffle(List<?> list)
    Moves every element of the list to a random new position in the list.
    Parameters:
      `list` - the List to shuffle.
    Throws:
      `UnsupportedOperationException` - when replacing an element in the List is not supported.

  - ### shuffle

    public static void shuffle(List<?> list, Random random)
    Moves every element of the list to a random new position in the list using the specified random number generator.
    Parameters:
      `list` - the list to shuffle.
      `random` - the random number generator.
    Throws:
      `UnsupportedOperationException` - when replacing an element in the list is not supported.

  - ### singleton

    public static <E> Set<E> singleton(E object)
    Returns a set containing the specified element. The set cannot be modified. The set is serializable.
    Parameters:
      `object` - the element.
    Returns:
      a set containing the element.

  - ### singletonList

    public static <E> List<E> singletonList(E object)
    Returns a list containing the specified element. The list cannot be modified. The list is serializable.
    Parameters:
      `object` - the element.
    Returns:
      a list containing the element.

  - ### singletonMap

    public static <K,V> Map<K,V> singletonMap(K key, V value)
    Returns a Map containing the specified key and value. The map cannot be modified. The map is serializable.
    Parameters:
      `key` - the key.
      `value` - the value.
    Returns:
      a Map containing the key and value.

  - ### sort

    public static <T extends Comparable<? super T>> void sort(List<T> list)
    Sorts the specified list in ascending natural order. The algorithm is stable which means equal elements don't get reordered.
    Parameters:
      `list` - the list to be sorted.
    Throws:
      `ClassCastException` - when an element in the List does not implement Comparable or elements cannot be compared to each other.

  - ### sort

    public static <T> void sort(List<T> list, Comparator<? super T> comparator)
    Sorts the specified list using the specified comparator. The algorithm is stable which means equal elements don't get reordered.
    Parameters:
      `list` - the list to be sorted.
      `comparator` - the comparator.
    Throws:
      `ClassCastException` - when elements in the list cannot be compared to each other using the comparator.

  - ### swap

    public static void swap(List<?> list, int index1, int index2)
    Swaps the elements of list `list` at indices `index1` and `index2`.
    Parameters:
      `list` - the list to manipulate.
      `index1` - position of the first element to swap with the element in index2.
      `index2` - position of the other element.
    Throws:
      `IndexOutOfBoundsException` - if index1 or index2 is out of range of this list.
    Since:
      1.4

  - ### replaceAll

    public static <T> boolean replaceAll(List<T> list, T obj, T obj2)
    Replaces all occurrences of Object `obj` in `list` with `newObj`. If the `obj` is `null`, then all occurrences of `null` are replaced with `newObj`.
    Parameters:
      `list` - the list to modify.
      `obj` - the object to find and replace occurrences of.
      `obj2` - the object to replace all occurrences of `obj` in `list`.
    Returns:
      true, if at least one occurrence of `obj` has been found in `list`.
    Throws:
      `UnsupportedOperationException` - if the list does not support setting elements.

  - ### rotate

    public static void rotate(List<?> lst, int dist)
    Rotates the elements in `list` by the distance `dist`

    e.g. for a given list with elements [1, 2, 3, 4, 5, 6, 7, 8, 9, 0], calling rotate(list, 3) or rotate(list, -7) would modify the list to look like this: [8, 9, 0, 1, 2, 3, 4, 5, 6, 7]

    Parameters:
      `lst` - the list whose elements are to be rotated.
      `dist` - is the distance the list is rotated. This can be any valid integer. Negative values rotate the list backwards.

  - ### indexOfSubList

    public static int indexOfSubList(List<?> list, List<?> sublist)
    Searches the `list` for `sublist` and returns the beginning index of the first occurrence.

    -1 is returned if the `sublist` does not exist in `list`.

    Parameters:
      `list` - the List to search `sublist` in.
      `sublist` - the List to search in `list`.
    Returns:
      the beginning index of the first occurrence of `sublist` in `list`, or -1.

  - ### lastIndexOfSubList

    public static int lastIndexOfSubList(List<?> list, List<?> sublist)
    Searches the `list` for `sublist` and returns the beginning index of the last occurrence.

    -1 is returned if the `sublist` does not exist in `list`.

    Parameters:
      `list` - the list to search `sublist` in.
      `sublist` - the list to search in `list`.
    Returns:
      the beginning index of the last occurrence of `sublist` in `list`, or -1.

  - ### list

    public static <T> ArrayList<T> list(Enumeration<T> enumeration)
    Returns an `ArrayList` with all the elements in the `enumeration`. The elements in the returned `ArrayList` are in the same order as in the `enumeration`.
    Parameters:
      `enumeration` - the source `Enumeration`.
    Returns:
      an `ArrayList` from `enumeration`.

  - ### synchronizedCollection

    public static <T> Collection<T> synchronizedCollection(Collection<T> collection)
    Returns a wrapper on the specified collection which synchronizes all access to the collection.
    Parameters:
      `collection` - the Collection to wrap in a synchronized collection.
    Returns:
      a synchronized Collection.

  - ### synchronizedList

    public static <T> List<T> synchronizedList(List<T> list)
    Returns a wrapper on the specified List which synchronizes all access to the List.
    Parameters:
      `list` - the List to wrap in a synchronized list.
    Returns:
      a synchronized List.

  - ### synchronizedMap

    public static <K,V> Map<K,V> synchronizedMap(Map<K,V> map)
    Returns a wrapper on the specified map which synchronizes all access to the map.
    Parameters:
      `map` - the map to wrap in a synchronized map.
    Returns:
      a synchronized Map.

  - ### synchronizedSet

    public static <E> Set<E> synchronizedSet(Set<E> set)
    Returns a wrapper on the specified set which synchronizes all access to the set.
    Parameters:
      `set` - the set to wrap in a synchronized set.
    Returns:
      a synchronized set.

  - ### synchronizedSortedMap

    public static <K,V> SortedMap<K,V> synchronizedSortedMap(SortedMap<K,V> map)
    Returns a wrapper on the specified sorted map which synchronizes all access to the sorted map.
    Parameters:
      `map` - the sorted map to wrap in a synchronized sorted map.
    Returns:
      a synchronized sorted map.

  - ### synchronizedSortedSet

    public static <E> SortedSet<E> synchronizedSortedSet(SortedSet<E> set)
    Returns a wrapper on the specified sorted set which synchronizes all access to the sorted set.
    Parameters:
      `set` - the sorted set to wrap in a synchronized sorted set.
    Returns:
      a synchronized sorted set.

  - ### unmodifiableCollection

    public static <E> Collection<E> unmodifiableCollection(Collection<? extends E> collection)
    Returns a wrapper on the specified collection which throws an `UnsupportedOperationException` whenever an attempt is made to modify the collection.
    Parameters:
      `collection` - the collection to wrap in an unmodifiable collection.
    Returns:
      an unmodifiable collection.

  - ### unmodifiableList

    public static <E> List<E> unmodifiableList(List<? extends E> list)
    Returns a wrapper on the specified list which throws an `UnsupportedOperationException` whenever an attempt is made to modify the list.
    Parameters:
      `list` - the list to wrap in an unmodifiable list.
    Returns:
      an unmodifiable List.

  - ### unmodifiableMap

    public static <K,V> Map<K,V> unmodifiableMap(Map<? extends K, ? extends V> map)
    Returns a wrapper on the specified map which throws an `UnsupportedOperationException` whenever an attempt is made to modify the map.
    Parameters:
      `map` - the map to wrap in an unmodifiable map.
    Returns:
      a unmodifiable map.

  - ### unmodifiableSet

    public static <E> Set<E> unmodifiableSet(Set<? extends E> set)
    Returns a wrapper on the specified set which throws an `UnsupportedOperationException` whenever an attempt is made to modify the set.
    Parameters:
      `set` - the set to wrap in an unmodifiable set.
    Returns:
      a unmodifiable set

  - ### unmodifiableSortedMap

    public static <K,V> SortedMap<K,V> unmodifiableSortedMap(SortedMap<K, ? extends V> map)
    Returns a wrapper on the specified sorted map which throws an `UnsupportedOperationException` whenever an attempt is made to modify the sorted map.
    Parameters:
      `map` - the sorted map to wrap in an unmodifiable sorted map.
    Returns:
      a unmodifiable sorted map

  - ### unmodifiableSortedSet

    public static <E> SortedSet<E> unmodifiableSortedSet(SortedSet<E> set)
    Returns a wrapper on the specified sorted set which throws an `UnsupportedOperationException` whenever an attempt is made to modify the sorted set.
    Parameters:
      `set` - the sorted set to wrap in an unmodifiable sorted set.
    Returns:
      a unmodifiable sorted set.

  - ### frequency

    public static int frequency(Collection<?> c, Object o)
    Returns the number of elements in the `Collection` that match the `Object` passed. If the `Object` is `null`, then the number of `null` elements is returned.
    Parameters:
      `c` - the `Collection` to search.
      `o` - the `Object` to search for.
    Returns:
      the number of matching elements.
    Throws:
      `NullPointerException` - if the `Collection` parameter is `null`.
    Since:
      1.5

  - ### emptyList

    public static final <T> List<T> emptyList()
    Returns a type-safe empty, immutable `List`.
    Returns:
      an empty `List`.
    Since:
      1.5
    See Also:
      - `EMPTY_LIST`

  - ### emptySet

    public static final <T> Set<T> emptySet()
    Returns a type-safe empty, immutable `Set`.
    Returns:
      an empty `Set`.
    Since:
      1.5
    See Also:
      - `EMPTY_SET`

  - ### emptyMap

    public static final <K,V> Map<K,V> emptyMap()
    Returns a type-safe empty, immutable `Map`.
    Returns:
      an empty `Map`.
    Since:
      1.5
    See Also:
      - `EMPTY_MAP`

  - ### checkedCollection

    public static <E> Collection<E> checkedCollection(Collection<E> c, Class<E> type)
    Returns a dynamically typesafe view of the specified collection. Trying to insert an element of the wrong type into this collection throws a `ClassCastException`. At creation time the types in `c` are not checked for correct type.
    Parameters:
      `c` - the collection to be wrapped in a typesafe collection.
      `type` - the type of the elements permitted to insert.
    Returns:
      a typesafe collection.

  - ### addAll

    public static <T> boolean addAll(Collection<? super T> c, T... a)
    Adds all the specified elements to the specified collection.
    Parameters:
      `c` - the collection the elements are to be inserted into.
      `a` - the elements to insert.
    Returns:
      true if the collection changed during insertion.
    Throws:
      `UnsupportedOperationException` - when the method is not supported.
      `NullPointerException` - when `c` or `a` is `null`, or `a` contains one or more `null` elements and `c` doesn't support `null` elements.
      `IllegalArgumentException` - if at least one of the elements can't be inserted into the collection.

  - ### disjoint

    public static boolean disjoint(Collection<?> c1, Collection<?> c2)
    Returns whether the specified collections have no elements in common.
    Parameters:
      `c1` - the first collection.
      `c2` - the second collection.
    Returns:
      `true` if the collections have no elements in common, `false` otherwise.
    Throws:
      `NullPointerException` - if one of the collections is `null`.

  - ### newSetFromMap

    public static <E> Set<E> newSetFromMap(Map<E,Boolean> map)
    Answers a set backed by a map. And the map must be empty when this method is called.
    Type Parameters:
      `E` - type of elements in set
    Parameters:
      `map` - the backing map
    Returns:
      the set from the map
    Throws:
      `IllegalArgumentException` - if the map is not empty
    Since:
      1.6

  - ### asLifoQueue

    public static <T> Queue<T> asLifoQueue(Deque<T> deque)
    Answers a LIFO Queue as a view of a Deque. Methods in the returned Queue need to be re-written to implement the LIFO feature.
    Type Parameters:
      `T` - type of elements
    Parameters:
      `deque` - the Deque
    Returns:
      the LIFO Queue
    Since:
      1.6