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<XIterableUtils.Indexed<T>>>	adjoiningIndex()
static <T,R> Collector<T,?,R>	adjoiningIndex(Function<Iterable<XIterableUtils.Indexed<T>>,R> finisher)
static <T,A,R> Collector<T,?,R>	adjoiningIndex(Collector<XIterableUtils.Indexed<T>,A,R> downstream)
static <Item,Key,Container> Container	collectDistinct(Iterable<? extends Item> items, Function<? super Item,? extends Key> keyExtractor, Collector<? super Item,?,? extends Container> collector)	Collects the distinct items from the given iterable into a new container.
static <Item,Container> Container	collectDistinct(Iterable<? extends Item> items, Collector<? super Item,?,? extends Container> collector)	Collects the distinct items from the given iterable into a new container.
static boolean	collectionsHaveOverlap(Collection<?> collA, Collection<?> collB)	Checks if the two given collections have any overlap, i.e.
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)	Deprecated. Use emptyListIfNull(List) or emptyModifiableListIfNull(List).
static <T> Set<T>	defaultSet(Set<T> set)	Deprecated. Use emptySetIfNull(Set) or emptyModifiableSetIfNull(Set).
static <V> Iterable<V>	emptyIterableIfNull(Iterable<V> iterable)	Returns an empty iterable if the given iterable is null.
static <V> List<V>	emptyListIfNull(List<V> list)	Returns an empty list if the given list is null.
static <K,V> Map<K,V>	emptyMapIfNull(Map<K,V> map)	Returns an empty map if the given map is null.
static <V> List<V>	emptyModifiableListIfNull(List<V> list)	Returns an empty modifiable list if the given list is null.
static <K,V> Map<K,V>	emptyModifiableMapIfNull(Map<K,V> map)	Returns an empty, modifiable map if the given map is null.
static <V> Set<V>	emptyModifiableSetIfNull(Set<V> set)	Returns an empty modifiable set if the given set is null.
static <V> Set<V>	emptySetIfNull(Set<V> set)	Returns an empty set if the given set is null.
static <T,A> T	findBestMatchingItem(Iterable<T> items, Iterable<? extends Predicate<? super A>> matchers, Function<? super T,? extends A> attributeExtractor)	Finds the best matching element from a stream of items.
static <T,A> T	findBestMatchingItem(Stream<T> items, Iterable<? extends Predicate<? super A>> matchers, Function<? super T,? extends A> attributeExtractor)	Finds the best matching element from a stream of items.
static <T> T	firstElement(Iterable<T> elements)	Finds the first element of the iterable.
static <T> T	firstElementOr(Iterable<? extends T> elements, T defaultValue)	Finds the first element of the iterable.
static <T> T	firstItem(Iterable<? extends T> items, Predicate<? super T> filter)	Finds the first item in the list that matches the given filter.
static <T> T	firstItem(Iterable<T> items)	Finds the first item in the given list.
static <T> T	firstItem(List<T> list)
static <T> List<T>	fitToSize(List<T> list, int targetSize, IntFunction<T> missingValueSupplier)	Grows or shrink a list so that its size equals the given target size, doing nothing if the list's size is already equal to the target size.
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 <T> T[]	growToSize(T[] array, int targetSize, IntFunction<T[]> arrayCtor, IntFunction<T> missingValueSupplier)	Returns either the given array when its length is equal to or less than the target size, or a new array with the same first elements as the given array, but with additional elements added as provided by the given supplier, so that it's length equals the target size.
static boolean	isEmptyCollection(Collection<?> collection)	Same as CollectionUtils.isEmpty(Collection), but with a more verbose name when using static imports.
static boolean	isEmptyMap(Map<?,?> map)	Sames as MapUtils.isEmpty(Map), but with a more verbose name suitable 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 boolean	isNonEmptyMap(Map<?,?> map)	Sames as MapUtils.isNotEmpty(Map), but with a more verbose name when using static imports.
static <T> T	itemAt(Iterable<T> items, int index)	Gets the item at the given index, handling null and out-of-bound indices by returning null instead of throwing an error.
static String	joinIterable(Iterable<?> items, String separator)	Joins the items of an iterable into a single string, separated by the given separator.
static String	joinIterable(Iterable<?> items, String separator, String prefix, String suffix)	Joins the items of an iterable into a single string, separated by the given separator.
static <T> String	joinIterable(Iterable<? extends T> items, String separator, String prefix, String suffix, Function<? super T,?> stringifier)	Joins the items of an iterable into a single string, separated by the given separator.
static <T> String	joinIterable(Iterable<? extends T> items, String separator, Function<? super T,?> stringifier)	Joins the items of an iterable into a single string, separated by the given separator.
static <Item,Coll extends Collection<Item>> Coll	keepFirstDistinct(Coll items)	Removes all duplicate elements from the given collection, keeping only the first occurrence of each element.
static <Item,Key,Coll extends Collection<Item>> Coll	keepFirstDistinct(Coll items, Function<? super Item,? extends Key> keyExtractor)	Removes all duplicate elements from the given collection, keeping only the first occurrence of each element.
static <T> T	lastElement(Iterable<T> elements)
static <T> T	lastElementOr(Iterable<? extends T> elements, T defaultValue)	Finds the last element of the iterable.
static <T> T	lastItem(List<T> list)	Gets the last item in the list, or null if the list is null or empty.
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>	mappedUnmodifiableList(Supplier<? extends List<? extends T>> listSupplier, Function<? super T,? extends S> mapper)	Returns an unmodifiable view of from the given list supplier, with the elements mapped by the given function.
static <T,S,C extends Collection<S>> C	mapToCollection(Iterable<? extends T> items, Function<? super T,? extends S> mapper, Supplier<? extends C> collectionFactory)	Maps the elements of an iterable to new elements via the given mapping function, putting the result into a collection.
static <T,S> List<S>	mapToList(Iterable<? extends T> items, Function<? super T,? extends S> mapper)	Maps the elements of an iterable to new elements via the given mapping function.
static <T,S,L extends List<S>> L	mapToList(Iterable<? extends T> items, Function<? super T,? extends S> mapper, Supplier<? extends L> collectionFactory)	Maps the elements of an iterable to new elements via the given mapping function, putting the result into a list.
static <T,K,V> Map<K,V>	mapToMap(Iterable<? extends T> items, Function<? super T,? extends K> keyMapper, Function<? super T,? extends V> valueMapper)	Maps the elements of an iterable to a new map via the given mapping functions.
static <T,K,V,M extends Map<K,V>> M	mapToMap(Iterable<? extends T> items, Function<? super T,? extends K> keyMapper, Function<? super T,? extends V> valueMapper, Supplier<? extends M> mapFactory)	Maps the elements of an iterable to a new map via the given mapping functions.
static <T,K,V,M extends Map<K,V>> M	mapToMap(Iterable<? extends T> items, Function<? super T,? extends K> keyMapper, Function<? super T,? extends V> valueMapper, Supplier<? extends M> mapFactory, BinaryOperator<V> mergeFunction)	Maps the elements of an iterable to a new map via the given mapping functions.
static <T,S> Set<S>	mapToSet(Iterable<? extends T> items, Function<? super T,? extends S> mapper)	Maps the elements of an iterable to new elements via the given mapping function.
static <T,U,S extends Set<U>> S	mapToSet(Iterable<? extends T> items, Function<? super T,? extends U> mapper, Supplier<? extends S> setFactory)	Maps the elements of an iterable to new elements via the given mapping function, putting the result into a set.
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>	mutableList(T... items)	Creates a new mutable list with the given items.
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.
static <T> List<T>	shrinkToSize(List<T> list, int targetSize)	Shrinks a list to the given target size, doing nothing if the list's size is already equal to or less than the target size.
static <V> Stream<V>	streamArray(V[] array)	Similar to Arrays.stream(Object[]), but treats null arrays as empty streams.
static <V> Stream<V>	streamIterable(Iterable<V> iterable)	Returns a stream over the given iterable.
static <K,V> Stream<Map.Entry<K,V>>	streamMapEntries(Map<K,V> map)	Returns a stream over the entries of the given map.
static <K> Stream<K>	streamMapKeys(Map<K,?> map)	Returns a stream over the keys of the given map.
static <V> Stream<V>	streamMapValues(Map<?,V> map)	Returns a stream over the values of the given map.

Methods inherited from class java.lang.Object

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

Method Detail

adjoiningIndex

public static <T> Collector<T,?,Stream<XIterableUtils.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<XIterableUtils.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<XIterableUtils.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.

collectDistinct

public static <Item,Container> Container collectDistinct(Iterable<? extends Item> items,
                                                               Collector<? super Item,?,? extends Container> collector)

Collects the distinct items from the given iterable into a new container. The items are identified using hashCode and equals). The collector is used to collect the items into the container. For example:

     List<Item> items = List.of(new Item(1), new Item(2), new Item(1));
     List<Item> distinctItems = collectDistinct(items, Collectors.toList());
 

Type Parameters:

Item - Type of the items.

Container - Type of the result container.

Parameters:

items - Items to process.

collector - Collector to collect the items into the container.

Returns:

The container with the distinct items.

collectDistinct

public static <Item,Key,Container> Container collectDistinct(Iterable<? extends Item> items,
                                                                         Function<? super Item,? extends Key> keyExtractor,
                                                                         Collector<? super Item,?,? extends Container> collector)

Collects the distinct items from the given iterable into a new container. The items are identified by their keys extracted by the given key extractor (using hashCode and equals). The collector is used to collect the items into the container. For example:

     List<Item> items = List.of(new Item(1), new Item(2), new Item(1));
     List<Item> distinctItems = collectDistinct(items, Item::getKey, Collectors.toList());
 

Type Parameters:

Item - Type of the items.

Key - Type of the keys.

Container - Type of the result container.

Parameters:

items - Items to process.

keyExtractor - Extractor for the keys of the items.

collector - Collector to collect the items into the container.

Returns:

The container with the distinct items.

collectionsHaveOverlap

public static boolean collectionsHaveOverlap(Collection<?> collA,
                                             Collection<?> collB)

Checks if the two given collections have any overlap, i.e. whether at least one element exists that is contained in both collections. Same as checking whether the intersection of the two collections is not empty.

Parameters:

collA - First collection to check.

collB - Second collection to check.

Returns:

true if the collections have any overlap, false otherwise.

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

@Deprecated
public static <T> List<T> defaultList(List<T> list)

Deprecated.

Use emptyListIfNull(List) or emptyModifiableListIfNull(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

@Deprecated
public static <T> Set<T> defaultSet(Set<T> set)

Deprecated.

Use emptySetIfNull(Set) or emptyModifiableSetIfNull(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.

emptyIterableIfNull

public static <V> Iterable<V> emptyIterableIfNull(Iterable<V> iterable)

Returns an empty iterable if the given iterable is null. Otherwise, just returns the list itself. In contrast to the methods from Apache commons, this method has a more verbose name intended to be used with static imports.

Type Parameters:

V - Type of the items in the iterable.

Parameters:

iterable - An iterable to process.

Returns:

The given iterable when not null, or an empty iterable otherwise.

emptyListIfNull

public static <V> List<V> emptyListIfNull(List<V> list)

Returns an empty list if the given list is null. Otherwise, just returns the list itself. In contrast to the methods from Apache commons, this method has a more verbose name intended to be used with static imports.

Type Parameters:

V - Type of the items in the list.

Parameters:

list - A list to process.

Returns:

The given list when not null, or an empty list otherwise.

emptyMapIfNull

public static <K,V> Map<K,V> emptyMapIfNull(Map<K,V> map)

Returns an empty map if the given map is null. Otherwise, just returns the map itself. In contrast to the methods from Apache commons, this method has a more verbose name intended to be used with static imports.

Type Parameters:

V - Type of the items in the map.

Parameters:

map - A map to process.

Returns:

The given map when not null, or an empty map otherwise.

emptyModifiableListIfNull

public static <V> List<V> emptyModifiableListIfNull(List<V> list)

Returns an empty modifiable list if the given list is null. Otherwise, just returns the list itself. In contrast to the methods from Apache commons, this method has a more verbose name intended to be used with static imports.

Type Parameters:

V - Type of the items in the list.

Parameters:

list - A list to process.

Returns:

The given list when not null, or an empty modifiable list otherwise.

emptyModifiableMapIfNull

public static <K,V> Map<K,V> emptyModifiableMapIfNull(Map<K,V> map)

Returns an empty, modifiable map if the given map is null. Otherwise, just returns the map itself. In contrast to the methods from Apache commons, this method has a more verbose name intended to be used with static imports.

Type Parameters:

V - Type of the items in the map.

Parameters:

map - A map to process.

Returns:

The given map when not null, or an empty modifiable map otherwise.

emptyModifiableSetIfNull

public static <V> Set<V> emptyModifiableSetIfNull(Set<V> set)

Returns an empty modifiable set if the given set is null. Otherwise, just returns the set itself. In contrast to the methods from Apache commons, this method has a more verbose name intended to be used with static imports.

Type Parameters:

V - Type of the items in the set.

Parameters:

set - A set to process.

Returns:

The given set when not null, or an empty modifiable set otherwise.

emptySetIfNull

public static <V> Set<V> emptySetIfNull(Set<V> set)

Returns an empty set if the given set is null. Otherwise, just returns the set itself. In contrast to the methods from Apache commons, this method has a more verbose name intended to be used with static imports.

Type Parameters:

V - Type of the items in the set.

Parameters:

set - A set to process.

Returns:

The given set when not null, or an empty set otherwise.

findBestMatchingItem

public static <T,A> T findBestMatchingItem(Iterable<T> items,
                                                 Iterable<? extends Predicate<? super A>> matchers,
                                                 Function<? super T,? extends A> attributeExtractor)

Finds the best matching element from a stream of items. The best matching item is determined by the given matchers.

Given an item with an attribute, checks each matcher whether it matches the attribute. The index of the first matching matcher is used as the match quality.

The item with the best match quality (lowest number) is returned. When no items match any matchers, null is returned.

For example:

  class Item {
      public Item(String languageTag) { ... }
      public Locale getLocale() { ... }
  }

  List<Item> = List.of(new Item(nl), new Item(en-GB), new Item(it));
  List<Predicate<Locale>> matchers = List.of(
    LocaleMatcher.localeMatchExact(en-US),
    LocaleMatcher.localeMatchBaseLanguage(en)
  );

  // Return the item with en-GB, which matches the fallback for the base language en.
  var bestMatch = findElementWithBestMatchingLocale(items, matchers, Item::getLocale);
 

Type Parameters:

T - The type of the items.

A - The type of the attribute to match.

Parameters:

items - The stream of items to search.

matchers - The matchers to use for assigning a quality to each item.

attributeExtractor - The function to extract the attribute from an item.

Returns:

The item with the best matching attribute, or null if no items match.

findBestMatchingItem

public static <T,A> T findBestMatchingItem(Stream<T> items,
                                                 Iterable<? extends Predicate<? super A>> matchers,
                                                 Function<? super T,? extends A> attributeExtractor)

Finds the best matching element from a stream of items. The best matching item is determined by the given matchers.

Given an item with an attribute, checks each matcher whether it matches the attribute. The index of the first matching matcher is used as the match quality.

The item with the best match quality (lowest number) is returned. When no items match any matchers, null is returned.

For example:

  class Item {
      public Item(String languageTag) { ... }
      public Locale getLocale() { ... }
  }

  List<Item> = List.of(new Item(nl), new Item(en-GB), new Item(it));
  List<Predicate<Locale>> matchers = List.of(
    LocaleMatcher.localeMatchExact(en-US),
    LocaleMatcher.localeMatchBaseLanguage(en)
  );

  // Return the item with en-GB, which matches the fallback for the base language en.
  var bestMatch = findElementWithBestMatchingLocale(items, matchers, Item::getLocale);
 

Type Parameters:

T - The type of the items.

A - The type of the attribute to match.

Parameters:

items - The stream of items to search.

matchers - The matchers to use for assigning a quality to each item.

attributeExtractor - The function to extract the attribute from an item.

Returns:

The item with the best matching attribute, or null if no items match.

firstElement

public static <T> T firstElement(Iterable<T> elements)

Finds the first element of the iterable. Returns null if the iterable is null or empty.

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.

firstElementOr

public static <T> T firstElementOr(Iterable<? extends T> elements,
                                   T defaultValue)

Finds the first element of the iterable. Returns the default value if the iterable is null or empty.

Type Parameters:

T - Type of the elements.

Parameters:

elements - Elements to process.

defaultValue - Default value to return when the elements are null or empty.

Returns:

The first element from the elements, or the default value if the elements are null or empty.

firstItem

public static <T> T firstItem(Iterable<T> items)

Finds the first item in the given list. Returns null if the list is null or empty, or the first item is null.

Type Parameters:

T - Type of the elements in the list.

Parameters:

items - 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.

firstItem

public static <T> T firstItem(Iterable<? extends T> items,
                              Predicate<? super T> filter)

Finds the first item in the list that matches the given filter. Returns null when no such item exists. If the filter is null, this method is equivalent to firstItem(Iterable). null values are passed to the filter unchanged, so the filter is responsible for handling null values.

Type Parameters:

T - Type of the elements in the list.

Parameters:

items - Items to process.

filter - Filter to apply to the items. null is treated as if no predicate were given.

Returns:

The first item matching the filter, or null if no such item exists.

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.

fitToSize

public static <T> List<T> fitToSize(List<T> list,
                                    int targetSize,
                                    IntFunction<T> missingValueSupplier)

Grows or shrink a list so that its size equals the given target size, doing nothing if the list's size is already equal to the target size. When the given list is null, an empty list is created, grown or shrunk, and returned.

Type Parameters:

T - Type of the list items.

Parameters:

list - List to mutate.

targetSize - Target size. Values are capped to 0

Returns:

The given list grown or shrunk to the target size.

Throws:

NullPointerException - When the value supplier 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. Values are capped to 0

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.

growToSize

public static <T> T[] growToSize(T[] array,
                                 int targetSize,
                                 IntFunction<T[]> arrayCtor,
                                 IntFunction<T> missingValueSupplier)

Returns either the given array when its length is equal to or less than the target size, or a new array with the same first elements as the given array, but with additional elements added as provided by the given supplier, so that it's length equals the target size.

Type Parameters:

T - Type of the array elements.

Parameters:

array - Array to grow.

targetSize - Target size. Values are capped to 0

arrayCtor - Constructor for new arrays.

missingValueSupplier - Supplier for new values when the array needs to be grown. It is given the index of the position at which an element is needed.

Returns:

Either the given array, or a new array grown to the target size.

isEmptyCollection

public static boolean isEmptyCollection(Collection<?> collection)

Same 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.

isEmptyMap

public static boolean isEmptyMap(Map<?,?> map)

Sames as MapUtils.isEmpty(Map), but with a more verbose name suitable when using static imports.

Parameters:

map - Map to check.

Returns:

true if the map 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.

isNonEmptyMap

public static boolean isNonEmptyMap(Map<?,?> map)

Sames as MapUtils.isNotEmpty(Map), but with a more verbose name when using static imports.

Parameters:

map - Map to check.

Returns:

true if the map is neither null nor empty.

itemAt

public static <T> T itemAt(Iterable<T> items,
                           int index)

Gets the item at the given index, handling null and out-of-bound indices by returning null instead of throwing an error.

Type Parameters:

T - Type of the items.

Parameters:

items - Items to access.

index - Index of the item to access.

Returns:

The item at the given index, or null when no such item exists.

Since:

8.1.0

joinIterable

public static String joinIterable(Iterable<?> items,
                                  String separator)

Joins the items of an iterable into a single string, separated by the given separator. The items are converted to strings using String.valueOf(Object).

Parameters:

items - Items to join. null is treated as an empty iterable.

separator - Optional separator to insert between items, defaults to an empty string.

Returns:

The items joined into a single string.

joinIterable

public static <T> String joinIterable(Iterable<? extends T> items,
                                      String separator,
                                      Function<? super T,?> stringifier)

Joins the items of an iterable into a single string, separated by the given separator. The items are converted to strings using the given stringifier. If the stringifier is null, the items are converted to strings using String.valueOf(Object).

Type Parameters:

T - Type of the items.

Parameters:

items - Items to join. null is treated as an empty iterable.

separator - Optional separator to insert between items, defaults to an empty string.

stringifier - Optional function to convert items to strings, defaults to String.valueOf(Object).

Returns:

The items joined into a single string.

joinIterable

public static String joinIterable(Iterable<?> items,
                                  String separator,
                                  String prefix,
                                  String suffix)

Joins the items of an iterable into a single string, separated by the given separator. Optionally, you can specify a prefix and suffix to wrap around the items. The items are converted to strings using String.valueOf(Object).

Parameters:

items - Items to join. null is treated as an empty iterable.

separator - Optional separator to insert between items, defaults to an empty string.

prefix - Optional prefix to insert before the items, defaults to an empty string.

suffix - Optional suffix to insert after the items, defaults to an empty string.

Returns:

The items joined into a single string.

joinIterable

public static <T> String joinIterable(Iterable<? extends T> items,
                                      String separator,
                                      String prefix,
                                      String suffix,
                                      Function<? super T,?> stringifier)

Joins the items of an iterable into a single string, separated by the given separator. Optionally, you can specify a prefix and suffix to wrap around the items. The items are converted to strings using the given stringifier. If the stringifier is null, the items are converted to strings using String.valueOf(Object).

Type Parameters:

T - Type of the items.

Parameters:

items - Items to join. null is treated as an empty iterable.

separator - Optional separator to insert between items, defaults to an empty string.

prefix - Optional prefix to insert before the items, defaults to an empty string.

suffix - Optional suffix to insert after the items, defaults to an empty string.

stringifier - Optional function to convert items to strings, defaults to String.valueOf(Object).

Returns:

The items joined into a single string.

keepFirstDistinct

@CanIgnoreReturnValue
public static <Item,Coll extends Collection<Item>> Coll keepFirstDistinct(Coll items)

Removes all duplicate elements from the given collection, keeping only the first occurrence of each element. Items are identified and compared using hashCode and equals. The order of the elements is preserved. The given collection is modified in place.

Type Parameters:

Item - Type of the items.

Coll - Type of the collection.

Parameters:

items - Collection to process.

Returns:

The given collection, with all duplicate elements removed.

keepFirstDistinct

@CanIgnoreReturnValue
public static <Item,Key,Coll extends Collection<Item>> Coll keepFirstDistinct(Coll items,
                                                                                          Function<? super Item,? extends Key> keyExtractor)

Removes all duplicate elements from the given collection, keeping only the first occurrence of each element. Items are identified and compared using the given key extractor (using hashCode and equals). The order of the elements is preserved. The given collection is modified in place.

Type Parameters:

Item - Type of the items.

Key - Type of the keys.

Coll - Type of the collection.

Parameters:

items - Collection to process.

keyExtractor - Extractor for the keys of the items.

Returns:

The given collection, with all duplicate elements removed.

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.

lastElementOr

public static <T> T lastElementOr(Iterable<? extends T> elements,
                                  T defaultValue)

Finds the last element of the iterable. Returns the default value if the iterable is null or empty.

Type Parameters:

T - Type of the elements.

Parameters:

elements - Elements to process.

defaultValue - Default value to return when the elements are null or empty.

Returns:

The last element from the elements, or the default value if the elements are null or empty.

lastItem

public static <T> T lastItem(List<T> list)

Gets the last item in the list, or null if the list is null or empty.

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.

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

mapToCollection

public static <T,S,C extends Collection<S>> C mapToCollection(Iterable<? extends T> items,
                                                                          Function<? super T,? extends S> mapper,
                                                                          Supplier<? extends 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.

mapToList

public static <T,S> List<S> mapToList(Iterable<? extends T> items,
                                            Function<? super T,? extends 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,L extends List<S>> L mapToList(Iterable<? extends T> items,
                                                              Function<? super T,? extends S> mapper,
                                                              Supplier<? extends L> collectionFactory)

Maps the elements of an iterable to new elements via the given mapping function, putting the result into a list. 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.

L - 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 list.

Returns:

A list as obtained from the factory, with the mapped elements added at the end.

mapToMap

public static <T,K,V> Map<K,V> mapToMap(Iterable<? extends T> items,
                                                          Function<? super T,? extends K> keyMapper,
                                                          Function<? super T,? extends V> valueMapper)

Maps the elements of an iterable to a new map via the given mapping functions. The keys and values are determined by the given key and value mappers. If there are multiple mapped entries with the same key, the latter entry will be used.

This is a shortcut for streaming the iterable and then collecting it into a map (except that conflicts are resolved by taking the latter value, instead of throwing an exception).

Type Parameters:

T - Type of the elements in the iterable.

K - Type of the keys in the map.

V - Type of the values in the map.

Parameters:

items - The items to map. Can be null, which is interpreted as an empty list.

keyMapper - Function that maps each item to a map key.

valueMapper - Function that maps each item to a map value.

Returns:

A new map with the mapped entries.

mapToMap

public static <T,K,V,M extends Map<K,V>> M mapToMap(Iterable<? extends T> items,
                                                                            Function<? super T,? extends K> keyMapper,
                                                                            Function<? super T,? extends V> valueMapper,
                                                                            Supplier<? extends M> mapFactory)

Maps the elements of an iterable to a new map via the given mapping functions. The keys and values are determined by the given key and value mappers. Uses the map instance created by the given factory. If there are multiple mapped entries with the same key, the latter entry will be used.

This is a shortcut for streaming the iterable and then collecting it into a map (except that conflicts are resolved by taking the latter value, instead of throwing an exception).

Type Parameters:

T - Type of the elements in the iterable.

K - Type of the keys in the map.

V - Type of the values in the map.

M - Type of the map to return.

Parameters:

items - The items to map. Can be null, which is interpreted as an empty list.

keyMapper - Function that maps each item to a map key.

valueMapper - Function that maps each item to a map value.

mapFactory - Factory for creating a new map.

Returns:

A new map with the mapped entries.

mapToMap

public static <T,K,V,M extends Map<K,V>> M mapToMap(Iterable<? extends T> items,
                                                                            Function<? super T,? extends K> keyMapper,
                                                                            Function<? super T,? extends V> valueMapper,
                                                                            Supplier<? extends M> mapFactory,
                                                                            BinaryOperator<V> mergeFunction)

Maps the elements of an iterable to a new map via the given mapping functions. The keys and values are determined by the given key and value mappers. Uses the map instance created by the given factory. If there are multiple mapped entries with the same key, they are merged using the given merge function.

This is a shortcut for streaming the iterable and then collecting it into a map.

Type Parameters:

T - Type of the elements in the iterable.

K - Type of the keys in the map.

V - Type of the values in the map.

M - Type of the map to return.

Parameters:

items - The items to map. Can be null, which is interpreted as an empty list.

keyMapper - Function that maps each item to a map key.

valueMapper - Function that maps each item to a map value.

mapFactory - Factory for creating a new map.

mergeFunction - Function for merging values that map to the same key.

Returns:

A new map with the mapped entries.

mapToSet

public static <T,S> Set<S> mapToSet(Iterable<? extends T> items,
                                          Function<? super T,? extends 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.toSet())
 

The returned set 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 set with the mapped elements.

mapToSet

public static <T,U,S extends Set<U>> S mapToSet(Iterable<? extends T> items,
                                                            Function<? super T,? extends U> mapper,
                                                            Supplier<? extends S> setFactory)

Maps the elements of an iterable to new elements via the given mapping function, putting the result into a set. Functionally the same as

 StreamSupport.stream(items.spliterator(), false).map(mapper).collect(Collectors.toCollection(() -> setFactory.apply(list.size()))
 

Type Parameters:

T - Type of the source elements.

U - Type of the target elements.

S - Type of the new set.

Parameters:

items - Elements to map. Can be null, which is interpreted as an empty list.

mapper - Mapping function to apply.

setFactory - Factory for creating a new set.

Returns:

A set as obtained from the factory, with the mapped elements added at the end.

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

mappedUnmodifiableList

public static <T,S> List<S> mappedUnmodifiableList(Supplier<? extends List<? extends T>> listSupplier,
                                                         Function<? super T,? extends S> mapper)

Returns an unmodifiable view of from the given list supplier, with the elements mapped by the given function.

Type Parameters:

T - Type of the source elements.

S - Type of the target elements.

Parameters:

listSupplier - Supplier for the list to map.

mapper - Mapping function.

Returns:

An unmodifiable list with the mapped elements.

Throws:

NullPointerException - When the mapper is null.

mutableList

@SafeVarargs
public static <T> List<T> mutableList(T... items)

Creates a new mutable list with the given items. The list is serializable and mutable.

Type Parameters:

T - Type of the list items.

Parameters:

items - Items to put into the list.

Returns:

A new serializable and mutable list with the given items.

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.

shrinkToSize

public static <T> List<T> shrinkToSize(List<T> list,
                                       int targetSize)

Shrinks a list to the given target size, doing nothing if the list's size is already equal to or less than the target size. When the given list is null, an empty list is created, shrunk, and returned.

Type Parameters:

T - Type of the list items.

Parameters:

list - List to mutate.

targetSize - Target size. Values are capped to 0

Returns:

The given list shrunk to the target size.

Throws:

NullPointerException - When the value supplier is null.

streamArray

public static <V> Stream<V> streamArray(V[] array)

Similar to Arrays.stream(Object[]), but treats null arrays as empty streams. Also has a name that is appropriate for static imports. Returns a stream over the elements of the given array.

Type Parameters:

V - Type of the elements.

Parameters:

array - Array with elements to stream.

Returns:

A stream over the iterable's elements.

streamIterable

public static <V> Stream<V> streamIterable(Iterable<V> iterable)

Returns a stream over the given iterable. When the iterable is null, returns an empty stream. In contrast to the methods from Apache commons, this method has a more verbose name intended to be used with static imports.

Type Parameters:

V - Type of the items.

Parameters:

iterable - Iterable to stream.

Returns:

A stream over the iterable's items.

streamMapEntries

public static <K,V> Stream<Map.Entry<K,V>> streamMapEntries(Map<K,V> map)

Returns a stream over the entries of the given map. When the map is null, returns an empty stream. In contrast to the methods from Apache commons, this method has a more verbose name intended to be used with static imports.

Type Parameters:

K - Type of the map keys.

V - Type of the map values.

Parameters:

map - Map with entries to stream.

Returns:

A stream over the map's entries.

streamMapKeys

public static <K> Stream<K> streamMapKeys(Map<K,?> map)

Returns a stream over the keys of the given map. When the map is null, returns an empty stream. In contrast to the methods from Apache commons, this method has a more verbose name intended to be used with static imports.

Type Parameters:

K - Type of the map keys.

Parameters:

map - Map with keys to stream.

Returns:

A stream over the map's keys.

streamMapValues

public static <V> Stream<V> streamMapValues(Map<?,V> map)

Returns a stream over the values of the given map. When the map is null, returns an empty stream. In contrast to the methods from Apache commons, this method has a more verbose name intended to be used with static imports.

Type Parameters:

V - Type of the map values.

Parameters:

map - Map with values to stream.

Returns:

A stream over the map's values.