Module com.aoapps.collections
Package com.aoapps.collections

Class AoCollections

java.lang.Object
com.aoapps.collections.AoCollections
public final class AoCollections extends Object
General-purpose collection utilities and constants.
Author:
AO Industries, Inc.

  • Field Details

  • Method Details

    • emptySortedSet

      @Deprecated(forRemoval=true) public static <T> SortedSet<T> emptySortedSet()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Please use Collections.emptySortedSet().
      Collections.emptySortedSet().

    • singletonSortedSet

      public static <T> SortedSet<T> singletonSortedSet(T o)

    • optimalUnmodifiableCollection

      public static <T> Collection<T> optimalUnmodifiableCollection(Collection<? extends T> collection)
      Gets the optimal implementation for unmodifiable collection. If collection is empty, uses Collections.emptyList. If the collection is already unmodifiable, returns the same collection. If collection has one element, uses Collections.singletonList. Otherwise, wraps the collection with Collections.unmodifiableCollection.
      Parameters:
      collection - may be null, which will return null

    • asCollection

      public static <E> Collection<E> asCollection(Iterable<E> iterable)
      Gets a collection from an iterable. Casts the iterable to collection, if possible. Otherwise builds a new list from the iterable, maintaining iteration order.
      Parameters:
      iterable - may be null, which will return null

    • unmodifiableCopyCollection

      public static <T> Collection<T> unmodifiableCopyCollection(Collection<? extends T> collection)
      Performs defensive shallow copy and returns unmodifiable collection.
      Parameters:
      collection - may be null, which will return null

    • unmodifiableCopyCollection

      public static <T> Collection<T> unmodifiableCopyCollection(Iterable<? extends T> iter)
      Performs defensive shallow copy and returns unmodifiable collection.
      Parameters:
      iter - may be null, which will return null

    • optimalUnmodifiableList

      public static <T> List<T> optimalUnmodifiableList(List<? extends T> list)
      Gets the optimal implementation for unmodifiable list. If list is empty, uses Collections.emptyList. If the list is already unmodifiable, returns the same list. If list has one element, uses Collections.singletonList. Otherwise, wraps the list with Collections.unmodifiableList, and will also call "trimToSize" if the list is an ArrayList.
      Parameters:
      list - may be null, which will return null
      See Also:

    • asList

      public static <E> List<E> asList(Iterable<E> iterable)
      Gets a list from an iterable. Casts the iterable to list, if possible. Otherwise builds a new list from the iterable, maintaining iteration order.
      Parameters:
      iterable - may be null, which will return null

    • unmodifiableCopyList

      public static <T> List<T> unmodifiableCopyList(Collection<? extends T> collection)
      Performs defensive shallow copy and returns unmodifiable list.
      Parameters:
      collection - may be null, which will return null

    • unmodifiableCopyList

      public static <T> List<T> unmodifiableCopyList(Iterable<? extends T> iter)
      Performs defensive shallow copy and returns unmodifiable list.
      Parameters:
      iter - may be null, which will return null

    • optimalUnmodifiableSet

      public static <T> Set<T> optimalUnmodifiableSet(Set<? extends T> set)
      Gets the optimal implementation for unmodifiable set. If set is empty, uses Collections.emptySet. If the set is already unmodifiable, returns the same set. If set has one element, uses Collections.singleton. Otherwise, wraps the set with Collections.unmodifiableSet.
      Parameters:
      set - may be null, which will return null

    • asSet

      public static <E> Set<E> asSet(Iterable<E> iterable)
      Gets a set from an iterable. Casts the iterable to set, if possible. Otherwise builds a new set from the iterable, maintaining iteration order.
      Parameters:
      iterable - may be null, which will return null

    • unmodifiableCopySet

      public static <T> Set<T> unmodifiableCopySet(Collection<? extends T> collection)
      Performs defensive shallow copy and returns unmodifiable set. The iteration order of the original set is maintained.
      Parameters:
      collection - may be null, which will return null

    • unmodifiableCopySet

      public static <T> Set<T> unmodifiableCopySet(Iterable<? extends T> iter)
      Performs defensive shallow copy and returns unmodifiable set. The iteration order of the original set is maintained.
      Parameters:
      iter - may be null, which will return null

    • optimalUnmodifiableSortedSet

      public static <T> SortedSet<T> optimalUnmodifiableSortedSet(SortedSet<T> sortedSet)
      Gets the optimal implementation for unmodifiable sorted set. If sorted set is empty, uses Collections.emptySortedSet(). If the sorted set is already unmodifiable, returns the same sorted set. If sorted set has one element, uses singletonSortedSet. Otherwise, wraps the sorted set with Collections.unmodifiableSortedSet.
      Parameters:
      sortedSet - may be null, which will return null

    • asSortedSet

      public static <E> SortedSet<E> asSortedSet(Iterable<E> iterable)
      Gets a sorted set from an iterable. Casts the iterable to sorted set, if possible. Otherwise builds a new sorted set from the iterable, in natural ordering.
      Parameters:
      iterable - may be null, which will return null

    • unmodifiableCopySortedSet

      public static <T> SortedSet<T> unmodifiableCopySortedSet(Collection<? extends T> collection)
      Performs defensive shallow copy and returns unmodifiable sorted set.
      Parameters:
      collection - may be null, which will return null

    • unmodifiableCopySortedSet

      public static <T> SortedSet<T> unmodifiableCopySortedSet(Iterable<? extends T> iter)
      Performs defensive shallow copy and returns unmodifiable sorted set.
      Parameters:
      iter - may be null, which will return null

    • optimalUnmodifiableMap

      public static <K, V> Map<K,V> optimalUnmodifiableMap(Map<? extends K,? extends V> map)
      Gets the optimal implementation for unmodifiable map. If map is empty, uses Collections.emptyMap. If the map is already unmodifiable, returns the same map. If map has one element, uses Collections.singletonMap. Otherwise, wraps the map with Collections.unmodifiableMap.
      Parameters:
      map - may be null, which will return null

    • unmodifiableCopyMap

      public static <K, V> Map<K,V> unmodifiableCopyMap(Map<? extends K,? extends V> map)
      Performs defensive shallow copy and returns unmodifiable map. The iteration order of the original set is maintained.
      Parameters:
      map - may be null, which will return null

    • optimalUnmodifiableSortedMap

      public static <K, V> SortedMap<K,V> optimalUnmodifiableSortedMap(SortedMap<K,? extends V> sortedMap)
      Gets the optimal implementation for unmodifiable sorted map. If sorted map is empty, uses emptySortedMap. If the sorted map is already unmodifiable, returns the same sorted map. If sorted map has one element, uses singletonSortedMap. Otherwise, wraps the sorted map with Collections.unmodifiableSortedMap.
      Parameters:
      sortedMap - may be null, which will return null

    • unmodifiableCopySortedMap

      public static <K, V> SortedMap<K,V> unmodifiableCopySortedMap(Map<K,? extends V> map)
      Performs defensive shallow copy and returns unmodifiable sorted map.
      Parameters:
      map - may be null, which will return null

    • emptyIterator

      @Deprecated public static <E> Iterator<E> emptyIterator()
      Deprecated.
      Use Collections.emptyIterator() as of Java 1.7.
      Gets the empty iterator.

    • singletonIterator

      @Deprecated public static <E> Iterator<E> singletonIterator(E value)
      Deprecated.
      Please use SingletonIterator from Apache Commons Collections.
      Gets an unmodifiable iterator for a single object.

    • unmodifiableIterator

      public static <E> Iterator<E> unmodifiableIterator(Iterator<? extends E> iter)
      Wraps an iterator to make it unmodifiable. If the iterator is already unmodifiable, returns the same iterator.
      Parameters:
      iter - may be null, which will return null

    • peekIterator

      public static <E> AoCollections.PeekIterator<E> peekIterator(Iterator<? extends E> iter)
      Wraps the provided iterator, allowing peek of first element. Does not support null elements.

    • equals

      public static boolean equals(Collection<?> collection1, Collection<?> collection2)
      Two collections are considered equal when they are the same size and have the same elements in the same iteration order.

      If both collections are null they are also considered equal.

    • hashCode

      public static int hashCode(Iterable<?> iterable)
      Computes the hashCode of a collection in a manner consistent with AbstractList.
      Parameters:
      iterable - may be null, which will return 0
      See Also:

    • filter

      public static <E, R extends E> List<R> filter(List<? extends E> list, Class<? extends R> clazz)
      Filters a list for all elements of a given class.
      Parameters:
      list - may be null, which will return null

    • filterByValue

      public static <K, V> Set<K> filterByValue(Map<? extends K,? extends V> map, V value)
      Returns a modifiable set of all the keys in a map that match the given value. This is a copy of the keys and will not write-through or be altered by the original map. The set will have the same iteration order as the original map.
      Parameters:
      map - may be null, which will return null

    • filterByValue

      public static <K, V> SortedSet<K> filterByValue(SortedMap<K,? extends V> map, V value)
      Returns a modifiable sorted set of all the keys in a sorted map that match the given value. This is a copy of the keys and will not write-through or be altered by the original map. The set uses the same comparator as the original map.
      Parameters:
      map - may be null, which will return null

    • getHashInitialCapacity

      public static int getHashInitialCapacity(int elements)
      Gets the initial capacity to use for hash-based collections that will contain the given number of elements, assuming the default load factor of 0.75f.
      See Also:

    • newArrayList

      public static <E> ArrayList<E> newArrayList(int elements)
      Creates a new ArrayList with a capacity large enough to contain the given number of elements without growing.
      Parameters:
      elements - The number of elements or -1 when unknown

    • newArrayList

      public static <E> ArrayList<E> newArrayList(Integer elements)
      Creates a new ArrayList with a capacity large enough to contain the given number of elements without growing.
      Parameters:
      elements - The number of elements or null when unknown

    • newHashMap

      public static <K, V> HashMap<K,V> newHashMap(int elements)
      Creates a new HashMap with a capacity large enough to contain the given number of elements without rehashing.
      Parameters:
      elements - The number of elements or -1 when unknown

    • newHashMap

      public static <K, V> HashMap<K,V> newHashMap(Integer elements)
      Creates a new HashMap with a capacity large enough to contain the given number of elements without rehashing.
      Parameters:
      elements - The number of elements or null when unknown

    • newHashSet

      public static <E> HashSet<E> newHashSet(int elements)
      Creates a new HashSet with a capacity large enough to contain the given number of elements without rehashing.
      Parameters:
      elements - The number of elements or -1 when unknown

    • newHashSet

      public static <E> HashSet<E> newHashSet(Integer elements)
      Creates a new HashSet with a capacity large enough to contain the given number of elements without rehashing.
      Parameters:
      elements - The number of elements or null when unknown

    • newIdentityHashMap

      public static <K, V> IdentityHashMap<K,V> newIdentityHashMap(int elements)
      Creates a new IdentityHashMap with a capacity large enough to contain the given number of elements without rehashing.
      Parameters:
      elements - The number of elements or -1 when unknown

    • newIdentityHashMap

      public static <K, V> IdentityHashMap<K,V> newIdentityHashMap(Integer elements)
      Creates a new IdentityHashMap with a capacity large enough to contain the given number of elements without rehashing.
      Parameters:
      elements - The number of elements or null when unknown

    • newIntArrayList

      public static IntArrayList newIntArrayList(int elements)
      Creates a new IntArrayList with a capacity large enough to contain the given number of elements without growing.
      Parameters:
      elements - The number of elements or -1 when unknown

    • newIntArrayList

      public static IntArrayList newIntArrayList(Integer elements)
      Creates a new IntArrayList with a capacity large enough to contain the given number of elements without growing.
      Parameters:
      elements - The number of elements or null when unknown

    • newLinkedHashMap

      public static <K, V> LinkedHashMap<K,V> newLinkedHashMap(int elements)
      Creates a new LinkedHashMap with a capacity large enough to contain the given number of elements without rehashing.
      Parameters:
      elements - The number of elements or -1 when unknown

    • newLinkedHashMap

      public static <K, V> LinkedHashMap<K,V> newLinkedHashMap(Integer elements)
      Creates a new LinkedHashMap with a capacity large enough to contain the given number of elements without rehashing.
      Parameters:
      elements - The number of elements or null when unknown

    • newLinkedHashSet

      public static <E> LinkedHashSet<E> newLinkedHashSet(int elements)
      Creates a new LinkedHashSet with a capacity large enough to contain the given number of elements without rehashing.
      Parameters:
      elements - The number of elements or -1 when unknown

    • newLinkedHashSet

      public static <E> LinkedHashSet<E> newLinkedHashSet(Integer elements)
      Creates a new LinkedHashSet with a capacity large enough to contain the given number of elements without rehashing.
      Parameters:
      elements - The number of elements or null when unknown

    • newLongArrayList

      public static LongArrayList newLongArrayList(int elements)
      Creates a new LongArrayList with a capacity large enough to contain the given number of elements without growing.
      Parameters:
      elements - The number of elements or -1 when unknown

    • newLongArrayList

      public static LongArrayList newLongArrayList(Integer elements)
      Creates a new LongArrayList with a capacity large enough to contain the given number of elements without growing.
      Parameters:
      elements - The number of elements or null when unknown

    • newSortedArrayList

      public static <E> SortedArrayList<E> newSortedArrayList(int elements)
      Creates a new SortedArrayList with a capacity large enough to contain the given number of elements without growing.
      Parameters:
      elements - The number of elements or -1 when unknown

    • newSortedArrayList

      public static <E> SortedArrayList<E> newSortedArrayList(Integer elements)
      Creates a new SortedArrayList with a capacity large enough to contain the given number of elements without growing.
      Parameters:
      elements - The number of elements or null when unknown