Class CollectionMethods

java.lang.Object
org.klojang.util.CollectionMethods
public final class CollectionMethods extends Object
Methods extending the Java Collection framework.

  • Method Summary

    Modifier and Type
    Method
    Description
    static List<?>
    asList(Object value)
    Converts the specified value to a List.
    static <T,U> List<U>
    collectionToList(Collection<? extends T> src, Function<? super T, ? extends U> converter)
    Shortcut method.
    static <K,V> Map<K,V>
    collectionToMap(Collection<V> src, Function<? super V, ? extends K> keyExtractor)
    Shortcut method.
    static <T,U> Set<U>
    collectionToSet(Collection<? extends T> src, Function<? super T, ? extends U> converter)
    Shortcut method.
    static <K0,V0,K1,V1>
    Map<K1,V1>
    deepFreeze(Map<K0,V0> src, Function<Map.Entry<K0,V0>, Map.Entry<K1,V1>> entryConverter)
    Returns an unmodifiable Map where both keys and values of the input Map have been converted using the specified Function.
    static <T> T
    findFirst(Collection<T> collection, Predicate<? super T> test)
    Shortcut method.
    static <T, U, E extends Throwable>
    List<U>
    freeze(List<? extends T> src, org.klojang.check.fallible.FallibleFunction<? super T, ? extends U, E> converter)
    Returns an unmodifiable List containing the values that result from applying the specified function to the source list's elements.
    static <K,V0,V1> Map<K,V1>
    freeze(Map<K,V0> src, BiFunction<? super K, ? super V0, ? extends V1> valueConverter)
    Returns an unmodifiable Map where the values of the input Map have been converted using the specified BiFunction.
    static <K,V0,V1> Map<K,V1>
    freeze(Map<K,V0> src, Function<? super V0, ? extends V1> valueConverter)
    Returns an unmodifiable Map where the values of the input Map have been converted using the specified Function.
    static <T, U, E extends Throwable>
    Set<U>
    freeze(Set<? extends T> src, org.klojang.check.fallible.FallibleFunction<? super T, ? extends U, E> converter)
    Returns an unmodifiable Set containing the values that result from applying the specified function to the source set's elements.
    static <T> String
    implode(Collection<T> collection)
    PHP-style implode method, concatenating the collection elements using ", " (comma-space) as separator.
    static <T> String
    implode(Collection<T> collection, int limit)
    PHP-style implode method, concatenating at most limit collection elements using ", " (comma-space) as separator.
    static <T> String
    implode(Collection<T> collection, String separator)
    PHP-style implode method, concatenating the collection elements with the specified separator.
    static <T> String
    implode(Collection<T> collection, String separator, int limit)
    PHP-style implode method, concatenating at most limit collection elements using the specified separator.
    static <T> String
    implode(Collection<T> collection, Function<T,String> stringifier)
    PHP-style implode method, concatenating at most limit collection elements using ", " (comma-space) as separator.
    static <T> String
    implode(Collection<T> collection, Function<T,String> stringifier, String separator)
    PHP-style implode method, concatenating at most limit collection elements using ", " (comma-space) as separator.
    static <T> String
    implode(Collection<T> collection, Function<T,String> stringifier, String separator, int from, int to)
    PHP-style implode method.
    static <E> List<E>
    initializedList(int size, E initVal)
    Returns a fixed-size, mutable List with all elements initialized to the specified value.
    static <E> List<E>
    initializedList(int size, Supplier<E> initValSupplier)
    Returns a fixed-size, mutable List with all elements initialized to values provided by a Supplier.
    static <K,V> Map<K,V>
    initializedMap(Object... kvPairs)
    Returns a HashMap initialized with the specified key-value pairs.
    static boolean
    isNullRepellent(Collection<?> c)
    Returns true if the provided collection is a null-repellent collection.
    static boolean
    isNullRepellent(Map<?,?> m)
    Returns true if the provided map is a null-repellent map.
    static <E> List<E>
    newArrayList(int capacity, E... initialValues)
    Returns a new ArrayList initialized with the specified values.
    static <K,V> Map<K,V>
    newHashMap(int size, Class<K> keyType, Class<V> valueType, Object... kvPairs)
    Returns a HashMap initialized with the specified key-value pairs.
    static <K extends Enum<K>, V>
    EnumMap<K,V>
    saturatedEnumMap(Class<K> enumClass, V... values)
    Returns an EnumMap containing all enum constants.
    static <T> List<T>
    sublist(List<T> list, int offset, int length)
    Returns a sublist of the provided list starting with element from and containing at most length elements.
    static <K,V> Map<V,K>
    swap(Map<K,V> map)
    Returns a new Map where keys and values of the input map have traded places.
    static <K,V> Map<V,K>
    swap(Map<K,V> map, Supplier<? extends Map<V,K>> mapFactory)
    Returns a new Map where keys and values of the input map have traded places.
    static <K,V> Map<V,K>
    swapAndFreeze(Map<K,V> map)
    Returns an unmodifiable Map where keys and values of the input map have traded places.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • asList

      public static List<?> asList(Object value)

      Converts the specified value to a List.

      • if the value already is a List, it is returned as-is.
      • if the value is a Collection, it is converted to an ArrayList using the standard Collections Framework conversion mechanism — by passing it to the constructor of ArrayList
      • if the value is an instance of Object[], it is converted using Arrays.asList
      • if the value is an array of a primitive type, it is converted using ArrayMethods.asList
      • in any other case (which includes the value being null), the value is converted using Collections.singletonList

      In other words, this method takes the shortest route to turn the value into a List and there is no guarantee about what type of List is returned. The returned list will always contain at least one element, but it may be null.

      Parameters:
      value - the value to convert
      Returns:
      the value converted to a List
      See Also:

    • initializedList

      public static <E> List<E> initializedList(int size, E initVal)
      Returns a fixed-size, mutable List with all elements initialized to the specified value. The initialization value must not be null.
      Type Parameters:
      E - the type of the elements
      Parameters:
      size - the desired size of the List
      initVal - the initial value of the list elements (must not be null)
      Returns:
      a fixed-size, mutable, initialized List

    • initializedList

      public static <E> List<E> initializedList(int size, Supplier<E> initValSupplier)
      Returns a fixed-size, mutable List with all elements initialized to values provided by a Supplier.
      Type Parameters:
      E - the type of the elements
      Parameters:
      size - the desired size of the List
      initValSupplier - the supplier of the initial values
      Returns:
      a fixed-size, mutable, initialized List

    • newArrayList

      @SafeVarargs public static <E> List<E> newArrayList(int capacity, E... initialValues)
      Returns a new ArrayList initialized with the specified values. The values are allowed to be null. The initial capacity will always be at least the length of the initialValues array, whatever the value of the capacity argument.
      Type Parameters:
      E - the type of the list elements
      Parameters:
      capacity - the initial capacity of the list
      initialValues - the values to add to the list
      Returns:
      a new ArrayList initialized with the specified values.

    • initializedMap

      public static <K,V> Map<K,V> initializedMap(Object... kvPairs)
      Returns a HashMap initialized with the specified key-value pairs. Both keys and values are allowed to be null. The map will be tightly sized to the number of key-value pairs.
      Type Parameters:
      K - the type of the keys
      V - the type of the values
      Parameters:
      kvPairs - an array alternating between keys and values
      Returns:
      a HashMap initialized with the specified key-value pairs

    • newHashMap

      public static <K,V> Map<K,V> newHashMap(int size, Class<K> keyType, Class<V> valueType, Object... kvPairs)
      Returns a HashMap initialized with the specified key-value pairs. Both keys and values are allowed to be null. Keys will be checked for uniqueness. Keys and values will be type-checked against keyType and valueType, respectively.
      Type Parameters:
      K - the type of the keys
      V - the type of the values
      Parameters:
      size - the expected number of map entries. No rehashing will take place until that number is reached. If you specify a number less than the number of key-value pairs (half the length of the varargs array), it will be taken as a multiplier. For example, 2 would mean that you expect the map to grow to about twice the specified number of key-value pairs.
      keyType - the class of the keys
      valueType - the class of the values
      kvPairs - an array alternating between keys and values
      Returns:
      a HashMap initialized with the specified key-value pairs

    • saturatedEnumMap

      public static <K extends Enum<K>, V> EnumMap<K,V> saturatedEnumMap(Class<K> enumClass, V... values) throws IllegalArgumentException
      Returns an EnumMap containing all enum constants. The number of values must exactly equal the number of enum constants, and they are assigned according to ordinal number. This method throws an IllegalArgumentException if the number of values is not exactly equal to the number of constants in the enum class, or if any of the values is null.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      enumClass - the enum class
      values - the values to associate with the enum constants
      Returns:
      a fully-occupied EnumMap with no null-values
      Throws:
      IllegalArgumentException - if enumClass or Values is null, or if any of the provided values is null, or is the number of values is not exactly equals to the number of enum constants

    • sublist

      public static <T> List<T> sublist(List<T> list, int offset, int length)
      Returns a sublist of the provided list starting with element from and containing at most length elements. The returned list is backed by the original list, so changing its elements will affect the original list as well. If offset is negative, it is taken relative to the end of the list. If length is negative, the sublist is taken in the opposite direction — that is, the element at offset now becomes the last element of the sublist.
      Type Parameters:
      T - the type of the elements
      Parameters:
      list - the List to extract a sublist from
      offset - the start index if the sublist (however, see above)
      length - the length of the sublist
      Returns:
      a sublist of the provided list

    • swap

      public static <K,V> Map<V,K> swap(Map<K,V> map)
      Returns a new Map where keys and values of the input map have traded places. The specified Map must not contain duplicate values. An IllegalArgumentException is thrown if it does.
      Type Parameters:
      K - the type of the keys in the original map, and of the values in the returned map
      V - the type of the values in the original map, and of the keys in the returned map
      Parameters:
      map - the source map
      Returns:
      a new Map where keys and values are swapped

    • swap

      public static <K,V> Map<V,K> swap(Map<K,V> map, Supplier<? extends Map<V,K>> mapFactory) throws org.klojang.check.extra.DuplicateValueException
      Returns a new Map where keys and values of the input map have traded places. The specified Map must not contain duplicate values. A DuplicateValueException is thrown if it does. null keys and values are allowed, however.
      Type Parameters:
      K - the type of the keys in the original map, and of the values in the returned map
      V - the type of the values in the original map, and of the keys in the returned map
      Parameters:
      map - the source map
      mapFactory - a supplier of a Map instance
      Returns:
      a new Map where keys and values are swapped
      Throws:
      org.klojang.check.extra.DuplicateValueException - if the map contains duplicate values

    • swapAndFreeze

      public static <K,V> Map<V,K> swapAndFreeze(Map<K,V> map)
      Returns an unmodifiable Map where keys and values of the input map have traded places. The specified Map must not contain null keys, null values or duplicate values. An IllegalArgumentException is thrown if it does.
      Type Parameters:
      K - the type of the keys in the original map, and of the values in the returned map
      V - the type of the values in the original map, and of the keys in the returned map
      Parameters:
      map - the source map
      Returns:
      a new Map where keys and values are swapped

    • freeze

      public static <K,V0,V1> Map<K,V1> freeze(Map<K,V0> src, Function<? super V0, ? extends V1> valueConverter)
      Returns an unmodifiable Map where the values of the input Map have been converted using the specified Function. The specified Map must not contain null keys, null values or duplicate values. An IllegalArgumentException is thrown if it does.
      Type Parameters:
      K - the type of the keys of the input and output Map
      V0 - the type of the values of the input Map
      V1 - the type of the values of the output Map
      Parameters:
      src - the input Map
      valueConverter - a Function that converts the values of the input Map
      Returns:
      an unmodifiable Map where the values of the input Map have been converted using the specified Function

    • freeze

      public static <K,V0,V1> Map<K,V1> freeze(Map<K,V0> src, BiFunction<? super K, ? super V0, ? extends V1> valueConverter)
      Returns an unmodifiable Map where the values of the input Map have been converted using the specified BiFunction. This method passes both the key and the value to the converter function so you can make the conversion key-dependent, or so you can mention the key if the conversion fails.
      Type Parameters:
      K - the type of the keys of the input and output Map
      V0 - the type of the values of the input Map
      V1 - the type of the values of the output Map
      Parameters:
      src - the input Map
      valueConverter - a Function that converts the values of the input Map
      Returns:
      an unmodifiable Map where the values of the input Map have been converted using the specified Function

    • deepFreeze

      public static <K0,V0,K1,V1> Map<K1,V1> deepFreeze(Map<K0,V0> src, Function<Map.Entry<K0,V0>, Map.Entry<K1,V1>> entryConverter)
      Returns an unmodifiable Map where both keys and values of the input Map have been converted using the specified Function. The output map may be smaller than the input map if the conversion function does not generate unique keys.
      Type Parameters:
      K0 - The type of the keys in the input map
      V0 - the type of the values in the input map
      K1 - the type of the keys in the output map
      V1 - the type of the values in the output map
      Parameters:
      src - the input Map
      entryConverter - a Function that produces a new entry from the original entry
      Returns:
      an unmodifiable Map where the values of the input Map have been converted using the specified Function

    • freeze

      public static <T, U, E extends Throwable> List<U> freeze(List<? extends T> src, org.klojang.check.fallible.FallibleFunction<? super T, ? extends U, E> converter) throws E
      Returns an unmodifiable List containing the values that result from applying the specified function to the source list's elements. The conversion function is allowed to throw a checked exception.
      Type Parameters:
      T - the type of the elements in the source list
      U - the type of the elements in the returned list
      E - the type of exception thrown if the conversion fails
      Parameters:
      src - the source list
      converter - the conversion function
      Returns:
      an unmodifiable List containing the values that result from applying the specified function to the source list's elements
      Throws:
      E - the exception potentially being thrown from the conversion function

    • freeze

      public static <T, U, E extends Throwable> Set<U> freeze(Set<? extends T> src, org.klojang.check.fallible.FallibleFunction<? super T, ? extends U, E> converter) throws E
      Returns an unmodifiable Set containing the values that result from applying the specified function to the source set's elements. The conversion function is allowed to throw a checked exception.
      Type Parameters:
      T - the type of the elements in the source set
      U - the type of the elements in the returned set
      E - the type of exception thrown if the conversion fails
      Parameters:
      src - the source set
      converter - the conversion function
      Returns:
      an unmodifiable Set containing the values that result from applying the
      Throws:
      E - the exception potentially being thrown from the conversion function

    • collectionToList

      public static <T,U> List<U> collectionToList(Collection<? extends T> src, Function<? super T, ? extends U> converter)
      Shortcut method. Returns an unmodifiable list using: 
      
 src.stream().map(converter).collect(toUnmodifiableList());
      Type Parameters:
      T - the type of the elements in the source set
      U - the type of the elements in the returned list
      Parameters:
      src - the source list
      converter - the conversion function
      Returns:
      an unmodifiable List containing the values that result from applying the specified function to the source collection's elements

    • collectionToSet

      public static <T,U> Set<U> collectionToSet(Collection<? extends T> src, Function<? super T, ? extends U> converter)
      Shortcut method. Returns an unmodifiable set using: 
      
 src.stream().map(converter).collect(toUnmodifiableSet());
      Type Parameters:
      T - the type of the elements in the source set
      U - the type of the elements in the returned list
      Parameters:
      src - the source list
      converter - the conversion function
      Returns:
      an unmodifiable Set containing the values that result from applying the specified function to the source collection's elements

    • collectionToMap

      public static <K,V> Map<K,V> collectionToMap(Collection<V> src, Function<? super V, ? extends K> keyExtractor)
      Shortcut method. Returns an unmodifiable map from the specified collection using: 
      
 src.stream().collect(toUnmodifiableMap(keyExtractor, Function.identity()))
      Type Parameters:
      K - the type of the keys
      V - the type of the values and the list elements
      Parameters:
      src - the List to convert.
      keyExtractor - the key-extraction function
      Returns:
      an unmodifiable Map

    • findFirst

      public static <T> T findFirst(Collection<T> collection, Predicate<? super T> test)
      Shortcut method. Returns the first element that passes the specified test, or else null. Shortcut for collection.stream().filter(test).findFirst().orElse(null).
      Type Parameters:
      T - the type of the elements in the collection
      Parameters:
      collection - the collection to search
      test - the test
      Returns:
      the first element that passes the specified test, or else null

    • implode

      public static <T> String implode(Collection<T> collection)
      PHP-style implode method, concatenating the collection elements using ", " (comma-space) as separator.
      Type Parameters:
      T - the type of the elements
      Parameters:
      collection - the collection to implode
      Returns:
      a concatenation of the elements in the collection.
      See Also:

    • implode

      public static <T> String implode(Collection<T> collection, String separator)
      PHP-style implode method, concatenating the collection elements with the specified separator.
      Type Parameters:
      T - the type of the elements
      Parameters:
      collection - the collection to implode
      separator - the string used to separate the elements
      Returns:
      a concatenation of the elements in the collection.
      See Also:

    • implode

      public static <T> String implode(Collection<T> collection, int limit)
      PHP-style implode method, concatenating at most limit collection elements using ", " (comma-space) as separator.
      Type Parameters:
      T - the type of the elements
      Parameters:
      collection - the collection to implode
      limit - the maximum number of elements to collect. Specify -1 for no maximum. Specifying a number greater than the length of the collection is OK. It will be clamped to the collection length.
      Returns:
      a concatenation of the elements in the collection.
      See Also:

    • implode

      public static <T> String implode(Collection<T> collection, Function<T,String> stringifier)
      PHP-style implode method, concatenating at most limit collection elements using ", " (comma-space) as separator.
      Type Parameters:
      T - the type of the elements
      Parameters:
      collection - the collection to implode
      stringifier - a Function that converts the collection elements to strings
      Returns:
      a concatenation of the elements in the collection.
      See Also:

    • implode

      public static <T> String implode(Collection<T> collection, Function<T,String> stringifier, String separator)
      PHP-style implode method, concatenating at most limit collection elements using ", " (comma-space) as separator.
      Type Parameters:
      T - the type of the elements
      Parameters:
      collection - the collection to implode
      stringifier - a Function that converts the collection elements to strings
      separator - the string used to separate the elements
      Returns:
      a concatenation of the elements in the collection.
      See Also:

    • implode

      public static <T> String implode(Collection<T> collection, String separator, int limit)
      PHP-style implode method, concatenating at most limit collection elements using the specified separator.
      Type Parameters:
      T - the type of the elements
      Parameters:
      collection - the collection to implode
      separator - the string used to separate the elements
      limit - the maximum number of elements to collect. Specify -1 for no maximum. Specifying a number greater than the length of the collection is OK. It will be clamped to the collection length.
      Returns:
      a concatenation of the elements in the collection.
      See Also:

    • implode

      public static <T> String implode(Collection<T> collection, Function<T,String> stringifier, String separator, int from, int to)
      PHP-style implode method.
      Type Parameters:
      T - the type of the elements
      Parameters:
      collection - the collection to implode
      stringifier - a Function that converts the collection elements to strings
      separator - the string used to separate the elements
      from - the index of the element to begin the concatenation with (inclusive)
      to - the index of the element to end the concatenation with (exclusive). The specified number will be clamped to collection.size() (i.e. it's OK to specify a number greater than collection.size()). You can specify -1 as a shorthand for collection.size().
      Returns:
      a concatenation of the elements in the collection.
      See Also:

    • isNullRepellent

      public static boolean isNullRepellent(Collection<?> c)
      Returns true if the provided collection is a null-repellent collection. Null-repellent collections are those obtained via List.of(...) and Set.of(...). Note: if this method returns true, the collection is guaranteed to be null-repellent, but if this method returns false, it does not mean that the collection is guaranteed to allow null values. It just means that the collection is not known to be null-repellent.
      Parameters:
      c - the collection to inspect
      Returns:
      true if the provided collection is a null-repellent collection

    • isNullRepellent

      public static boolean isNullRepellent(Map<?,?> m)
      Returns true if the provided map is a null-repellent map. Note: if this method returns true, the map is guaranteed to be null-repellent, but if this method returns false, it does not mean that the map is guaranteed to allow null values. It just means that the map is not known to be null-repellent.
      Parameters:
      m - the collection to inspect
      Returns:
      true if the provided collection is a null-repellent collection