Package de.xima.fc.utils

Class XCollectionUtils

java.lang.Object
de.xima.fc.utils.XCollectionUtils
public class XCollectionUtils extends Object
Utility class for operations on collections and iterables.
Since:
7.0.0
Author:
XIMA Media GmbH

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> Collector<T,?,Stream<IterableUtils.Indexed<T>>>
    adjoiningIndex()
     
    static <T, R> Collector<T,?,R>
    adjoiningIndex(Function<Iterable<IterableUtils.Indexed<T>>,R> finisher)
     
    static <T, A, R> Collector<T,?,R>
    adjoiningIndex(Collector<IterableUtils.Indexed<T>,A,R> downstream)
     
    static <T> Collection<T>
    defaultCollection(Collection<T> collection)
    Sames as CollectionUtils.emptyIfNull(Collection), but with a more verbose name when using static imports.
    static <T> List<T>
    defaultList(List<T> list)
    Sames as ListUtils.emptyIfNull(List), but with a more verbose name when using static imports.
    static <T> Set<T>
    defaultSet(Set<T> set)
    Sames as SetUtils.emptyIfNull(Set), but with a more verbose name when using static imports.
    static <T> T
    firstElement(Iterable<T> elements)
     
    static <T> T
    firstItem(List<T> list)
     
    static <T> List<T>
    growToSize(List<T> list, int targetSize, IntFunction<T> missingValueSupplier)
    Grows a list to at least the given target size, doing nothing if the list's size is already equal to or greater than the target size.
    static boolean
    isEmptyCollection(Collection<?> collection)
    Sames as CollectionUtils.isEmpty(Collection), but with a more verbose name when using static imports.
    static boolean
    isNonEmptyCollection(Collection<?> collection)
    Sames as CollectionUtils.isNotEmpty(Collection), but with a more verbose name when using static imports.
    static <T> T
    itemAt(List<T> list, int index)
    Gets the item at the given index, or null if the index is out of bounds.
    static <T> T
    lastElement(Iterable<T> elements)
     
    static <T> T
    lastItem(List<T> list)
     
    static <T> List<T>
    listOfSize(int targetSize, T initialValue)
     
    static <T> List<T>
    listOfSizeWith(int targetSize, IntFunction<T> initialValue)
     
    static <K1, K2, V> Map<K2,V>
    mapKeys(Map<? extends K1,? extends V> map, Function<? super K1,? extends K2> keyMapper)
    Remaps the keys of a map by applying the given mapping function to all keys, returning a new map.
    static <K1, K2, V> Map<K2,V>
    mapKeys(Map<? extends K1,? extends V> map, Function<? super K1,? extends K2> keyMapper, BinaryOperator<V> mergeFunction)
    Remaps the keys of a map by applying the given mapping function to all keys, returning a new map.
    static <K1, K2, V> Map<K2,V>
    mapKeysToUnmodifiableMap(Map<? extends K1,? extends V> map, Function<? super K1,? extends K2> keyMapper)
    Remaps the keys of a map by applying the given mapping function to all keys, returning a new unmodifiable map.
    static <K1, K2, V> Map<K2,V>
    mapKeysToUnmodifiableMap(Map<? extends K1,? extends V> map, Function<? super K1,? extends K2> keyMapper, BinaryOperator<V> mergeFunction)
    Remaps the keys of a map by applying the given mapping function to all keys, returning a new unmodifiable map.
    static <K1, V1, K2, V2>
    Map<K2,V2>
    mapMap(Map<? extends K1,? extends V1> map, BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper)
    Maps the entries of a map by applying the given mapping function, returning a new map.
    static <K1, V1, K2, V2>
    Map<K2,V2>
    mapMap(Map<? extends K1,? extends V1> map, BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper, BinaryOperator<V2> mergeFunction)
    Maps the entries of a map by applying the given mapping function, returning a new map.
    static <K1, V1, K2, V2, M extends Map<K2, V2>>
    M
    mapMap(Map<? extends K1,? extends V1> map, BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper, BinaryOperator<V2> mergeFunction, Supplier<M> mapFactory)
    Maps the entries of a map by applying the given mapping function, returning a new map.
    static <T, S> List<S>
    mapToList(Iterable<T> items, Function<T,S> mapper)
    Maps the elements of an iterable to new elements via the given mapping function.
    static <T, S, C extends Collection<S>>
    C
    mapToList(Iterable<T> items, Function<T,S> mapper, Supplier<C> collectionFactory)
    Maps the elements of an iterable to new elements via the given mapping function, putting the result into a collection.
    static <K1, V1, K2, V2>
    Map<K2,V2>
    mapToUnmodifiableMap(Map<? extends K1,? extends V1> map, BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper)
    Maps the entries of a map by applying the given mapping function, returning a new unmodifiable map.
    static <K1, V1, K2, V2>
    Map<K2,V2>
    mapToUnmodifiableMap(Map<? extends K1,? extends V1> map, BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper, BinaryOperator<V2> mergeFunction)
    Maps the entries of a map by applying the given mapping function, returning a new unmodifiable map.
    static <K, V1, V2> Map<K,V2>
    mapValues(Map<? extends K,? extends V1> map, Function<? super V1,? extends V2> valueMapper)
    Remaps the values of a map by applying the given mapping function to all keys, returning a new map.
    static <K, V1, V2> Map<K,V2>
    mapValuesToUnmodifiableMap(Map<? extends K,? extends V1> map, Function<? super V1,? extends V2> valueMapper)
    Remaps the values of a map by applying the given mapping function to all keys, returning a new unmodifiable map.
    static <T> List<T>
    serializableList(Iterable<T> sequence)
    Takes any Collection or Iterable and converts it to a serializable list that can be transferred via the API.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • firstItem

      public static <T> T firstItem(List<T> list)
      Type Parameters:
      T - Type of the elements in the list.
      Parameters:
      list - List to process.
      Returns:
      The first item in the list, or null if the list is null or empty, or the first item is null.

    • firstElement

      public static <T> T firstElement(Iterable<T> elements)
      Type Parameters:
      T - Type of the elements.
      Parameters:
      elements - Elements to process.
      Returns:
      The first element from the elements, or null if the elements are null or empty, or the first item is null.

    • isEmptyCollection

      public static boolean isEmptyCollection(Collection<?> collection)
      Sames as CollectionUtils.isEmpty(Collection), but with a more verbose name when using static imports.
      Parameters:
      collection - Collection to check.
      Returns:
      true if the collection is null or empty.

    • isNonEmptyCollection

      public static boolean isNonEmptyCollection(Collection<?> collection)
      Sames as CollectionUtils.isNotEmpty(Collection), but with a more verbose name when using static imports.
      Parameters:
      collection - Collection to check.
      Returns:
      true if the collection is neither null nor empty.

    • defaultCollection

      public static <T> Collection<T> defaultCollection(Collection<T> collection)
      Sames as CollectionUtils.emptyIfNull(Collection), but with a more verbose name when using static imports.
      Type Parameters:
      T - Type of the items in the collection.
      Parameters:
      collection - Collection to check.
      Returns:
      The given collection, or an empty collection when null is given.

    • defaultList

      public static <T> List<T> defaultList(List<T> list)
      Sames as ListUtils.emptyIfNull(List), but with a more verbose name when using static imports.
      Type Parameters:
      T - Type of the items in the set.
      Parameters:
      list - List to check.
      Returns:
      The given list, or an empty list when null is given.

    • defaultSet

      public static <T> Set<T> defaultSet(Set<T> set)
      Sames as SetUtils.emptyIfNull(Set), but with a more verbose name when using static imports.
      Type Parameters:
      T - Type of the items in the set.
      Parameters:
      set - Set to check.
      Returns:
      The given set, or an empty set when null is given.

    • lastElement

      public static <T> T lastElement(Iterable<T> elements)
      Type Parameters:
      T - Type of the elements.
      Parameters:
      elements - Elements to process.
      Returns:
      The last element from the elements, or null if the elements are null or empty, or the first item is null.

    • growToSize

      public static <T> List<T> growToSize(List<T> list, int targetSize, IntFunction<T> missingValueSupplier)
      Grows a list to at least the given target size, doing nothing if the list's size is already equal to or greater than the target size. When the given list is null, an empty list is created, grown, and returned.
      Type Parameters:
      T - Type of the list items.
      Parameters:
      list - List to mutate.
      targetSize - Target size.
      missingValueSupplier - Supplier for new values when the list needs to be grown. It is given the index of the position at which an element is needed.
      Returns:
      The given list grown to the target size.
      Throws:
      NullPointerException - When the value supplier is null.

    • mapToList

      public static <T, S> List<S> mapToList(Iterable<T> items, Function<T,S> mapper)
      Maps the elements of an iterable to new elements via the given mapping function. Functionally the same as 
       StreamSupport.stream(items.spliterator(), false).map(mapper).collect(Collectors.toList())
      The returned list is serializable and mutable.
      Type Parameters:
      T - Type of the source elements.
      S - Type of the target elements.
      Parameters:
      items - Elements to map. Can be null, which is interpreted as an empty list.
      mapper - Mapping function to apply.
      Returns:
      A new list with the mapped elements.

    • mapToList

      public static <T, S, C extends Collection<S>> C mapToList(Iterable<T> items, Function<T,S> mapper, Supplier<C> collectionFactory)
      Maps the elements of an iterable to new elements via the given mapping function, putting the result into a collection. Functionally the same as 
       StreamSupport.stream(items.spliterator(), false).map(mapper).collect(Collectors.toCollection(() -> listFactory.apply(list.size()))
      Type Parameters:
      T - Type of the source elements.
      S - Type of the target elements.
      C - Type of the new collection.
      Parameters:
      items - Elements to map. Can be null, which is interpreted as an empty list.
      mapper - Mapping function to apply.
      collectionFactory - Factory for creating a new collection.
      Returns:
      A collection as obtained from the factory, with the mapped elements added at the end.

    • itemAt

      public static <T> T itemAt(List<T> list, int index)
      Gets the item at the given index, or null if the index is out of bounds.
      Type Parameters:
      T - Type of the elements in the list.
      Parameters:
      list - List to process.
      index - Index to access.
      Returns:
      The element at the index, null if there is no such element.

    • lastItem

      public static <T> T lastItem(List<T> list)
      Type Parameters:
      T - Type of the elements in the list.
      Parameters:
      list - List to process.
      Returns:
      The last item in the list, or null if the list is null or empty, or the last item is null.

    • listOfSize

      public static <T> List<T> listOfSize(int targetSize, T initialValue)
      Type Parameters:
      T - Type of the list elements.
      Parameters:
      targetSize - Desired size of the list.
      initialValue - Initial value for each element.
      Returns:
      A list of the given size, with each element set to the given initial value.

    • listOfSizeWith

      public static <T> List<T> listOfSizeWith(int targetSize, IntFunction<T> initialValue)
      Type Parameters:
      T - Type of the list elements.
      Parameters:
      targetSize - Desired size of the list.
      initialValue - Supplier for the initial value for each element.
      Returns:
      A list of the given size, with each element set to the value returned by the given supplier.

    • adjoiningIndex

      public static <T> Collector<T,?,Stream<IterableUtils.Indexed<T>>> adjoiningIndex()
      Type Parameters:
      T - Type of the input elements.
      Returns:
      A collector that adds the 0-based index to all elements, and returns a stream of these elements.

    • adjoiningIndex

      public static <T, R> Collector<T,?,R> adjoiningIndex(Function<Iterable<IterableUtils.Indexed<T>>,R> finisher)
      Type Parameters:
      T - Type of the input elements.
      R - Type of the output.
      Parameters:
      finisher - Finisher that transform the indexed element to the output type.
      Returns:
      A collector that adds the 0-based index to all elements, and applies the finisher to the list of indexed elements.

    • adjoiningIndex

      public static <T, A, R> Collector<T,?,R> adjoiningIndex(Collector<IterableUtils.Indexed<T>,A,R> downstream)
      Type Parameters:
      T - Type of the input elements.
      A - Type of the intermediate elements of the downstream collector.
      R - Type of the output.
      Parameters:
      downstream - Downstream that combines all elements into a single value.
      Returns:
      A collector that adds the 0-based index to all elements, and applies the downstream collector to all elements.

    • mapKeys

      public static <K1, K2, V> Map<K2,V> mapKeys(Map<? extends K1,? extends V> map, Function<? super K1,? extends K2> keyMapper)
      Remaps the keys of a map by applying the given mapping function to all keys, returning a new map. If there are multiple mapped entries with the same key, the latter entry will be used.
      Type Parameters:
      K1 - Type of the input map keys.
      K2 - Type of the output map keys.
      V - Type of the map values.
      Parameters:
      map - Map to process.
      keyMapper - Mapping function for the keys.
      Returns:
      The new map.
      Since:
      8.0.0

    • mapKeys

      public static <K1, K2, V> Map<K2,V> mapKeys(Map<? extends K1,? extends V> map, Function<? super K1,? extends K2> keyMapper, BinaryOperator<V> mergeFunction)
      Remaps the keys of a map by applying the given mapping function to all keys, returning a new map.
      Type Parameters:
      K1 - Type of the input map keys.
      K2 - Type of the output map keys.
      V - Type of the map values.
      Parameters:
      map - Map to process.
      keyMapper - Mapping function for the keys.
      mergeFunction - Merge function values that map to the same key.
      Returns:
      The new map.
      Since:
      8.0.0

    • mapKeysToUnmodifiableMap

      public static <K1, K2, V> Map<K2,V> mapKeysToUnmodifiableMap(Map<? extends K1,? extends V> map, Function<? super K1,? extends K2> keyMapper)
      Remaps the keys of a map by applying the given mapping function to all keys, returning a new unmodifiable map. If there are multiple mapped entries with the same key, the latter entry will be used.
      Type Parameters:
      K1 - Type of the input map keys.
      K2 - Type of the output map keys.
      V - Type of the map values.
      Parameters:
      map - Map to process.
      keyMapper - Mapping function for the keys.
      Returns:
      The new map.
      Since:
      8.0.0

    • mapKeysToUnmodifiableMap

      public static <K1, K2, V> Map<K2,V> mapKeysToUnmodifiableMap(Map<? extends K1,? extends V> map, Function<? super K1,? extends K2> keyMapper, BinaryOperator<V> mergeFunction)
      Remaps the keys of a map by applying the given mapping function to all keys, returning a new unmodifiable map.
      Type Parameters:
      K1 - Type of the input map keys.
      K2 - Type of the output map keys.
      V - Type of the map values.
      Parameters:
      map - Map to process.
      keyMapper - Mapping function for the keys.
      mergeFunction - Merge function values that map to the same key.
      Returns:
      The new map.
      Since:
      8.0.0

    • mapMap

      public static <K1, V1, K2, V2> Map<K2,V2> mapMap(Map<? extends K1,? extends V1> map, BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper)
      Maps the entries of a map by applying the given mapping function, returning a new map. If there are multiple mapped entries with the same key, the latter entry will be used.
      Type Parameters:
      K1 - Type of the input map keys.
      V1 - Type of the input map values.
      K2 - Type of the output map keys.
      V2 - Type of the output map values.
      Parameters:
      map - Map to process.
      entryMapper - Mapping function for the entries.
      Returns:
      The new map.
      Since:
      8.0.0

    • mapMap

      public static <K1, V1, K2, V2> Map<K2,V2> mapMap(Map<? extends K1,? extends V1> map, BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper, BinaryOperator<V2> mergeFunction)
      Maps the entries of a map by applying the given mapping function, returning a new map.
      Type Parameters:
      K1 - Type of the input map keys.
      V1 - Type of the input map values.
      K2 - Type of the output map keys.
      V2 - Type of the output map values.
      Parameters:
      map - Map to process.
      entryMapper - Mapping function for the entries.
      mergeFunction - Merge function for duplicate entries.
      Returns:
      The new map.
      Since:
      8.0.0

    • mapMap

      public static <K1, V1, K2, V2, M extends Map<K2, V2>> M mapMap(Map<? extends K1,? extends V1> map, BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper, BinaryOperator<V2> mergeFunction, Supplier<M> mapFactory)
      Maps the entries of a map by applying the given mapping function, returning a new map.
      Type Parameters:
      K1 - Type of the input map keys.
      V1 - Type of the input map values.
      K2 - Type of the output map keys.
      V2 - Type of the output map values.
      M - Type of the returned map.
      Parameters:
      map - Map to process.
      entryMapper - Mapping function for the entries.
      mergeFunction - Merge function for duplicate entries.
      mapFactory - Factory for the map to build.
      Returns:
      The new map.
      Since:
      8.0.0

    • mapToUnmodifiableMap

      public static <K1, V1, K2, V2> Map<K2,V2> mapToUnmodifiableMap(Map<? extends K1,? extends V1> map, BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper)
      Maps the entries of a map by applying the given mapping function, returning a new unmodifiable map. If there are multiple mapped entries with the same key, the latter entry will be used.
      Type Parameters:
      K1 - Type of the input map keys.
      V1 - Type of the input map values.
      K2 - Type of the output map keys.
      V2 - Type of the output map values.
      Parameters:
      map - Map to process.
      entryMapper - Mapping function for the entries.
      Returns:
      The new map.
      Since:
      8.0.0

    • mapToUnmodifiableMap

      public static <K1, V1, K2, V2> Map<K2,V2> mapToUnmodifiableMap(Map<? extends K1,? extends V1> map, BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper, BinaryOperator<V2> mergeFunction)
      Maps the entries of a map by applying the given mapping function, returning a new unmodifiable map.
      Type Parameters:
      K1 - Type of the input map keys.
      V1 - Type of the input map values.
      K2 - Type of the output map keys.
      V2 - Type of the output map values.
      Parameters:
      map - Map to process.
      entryMapper - Mapping function for the entries.
      mergeFunction - Merge function values that map to the same key.
      Returns:
      The new map.
      Since:
      8.0.0

    • mapValues

      public static <K, V1, V2> Map<K,V2> mapValues(Map<? extends K,? extends V1> map, Function<? super V1,? extends V2> valueMapper)
      Remaps the values of a map by applying the given mapping function to all keys, returning a new map.
      Type Parameters:
      K - Type of the map keys.
      V1 - Type of the input map values.
      V2 - Type of the output map values.
      Parameters:
      map - Map to process.
      valueMapper - Mapping function for the values.
      Returns:
      The new map.
      Since:
      8.0.0

    • mapValuesToUnmodifiableMap

      public static <K, V1, V2> Map<K,V2> mapValuesToUnmodifiableMap(Map<? extends K,? extends V1> map, Function<? super V1,? extends V2> valueMapper)
      Remaps the values of a map by applying the given mapping function to all keys, returning a new unmodifiable map.
      Type Parameters:
      K - Type of the map keys.
      V1 - Type of the input map values.
      V2 - Type of the output map values.
      Parameters:
      map - Map to process.
      valueMapper - Mapping function for the values.
      Returns:
      The new map.
      Since:
      8.0.0

    • serializableList

      public static <T> List<T> serializableList(Iterable<T> sequence)
      Takes any Collection or Iterable and converts it to a serializable list that can be transferred via the API.
      Type Parameters:
      T - Type of the list items.
      Parameters:
      sequence - A sequence of items to put into a list.
      Returns:
      A serializable list with the given items.