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()	Gets a collector that adds the 0-based index to all elements, and returns a stream of these elements.
static <T,R> Collector<T,?,R>	adjoiningIndex(Function<? super Iterable<XIterableUtils.Indexed<T>>, R> finisher)	Gets a collector that adds the 0-based index to all elements, and applies the finisher to the list of indexed elements.
static <T,A,R> Collector<T,?,R>	adjoiningIndex(Collector<XIterableUtils.Indexed<T>, A, R> downstream)	Gets a collector that adds the 0-based index to all elements, and applies the downstream collector to all elements.
static boolean	areAllCollectionsEmpty(Collection<?>... collections)	Checks if all the given collections are empty. null is treated as an empty collection.
static <T> List<T>	arrayAsUnmodifiableListView(T[] items)	Returns a list view of the array that is unmodifiable and serializable (assuming the type T is serializable).
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. whether at least one element exists that is contained in both collections.
static int	collectionSize(Collection<?> collection)	Same as CollectionUtils.size(Object), but with a more verbose name for static imports.
static <T,R> R	collectItems(Iterable<? extends T> items, Collector<? super T, ?, ? extends R> collector)	Collects the given items into a single result via the given collector.
static <T> List<T>	combinedList(List<T> list, T end)	Creates a new list that combines the given list with the given element at the end.
static <T> List<T>	combinedList(T start, List<T> list)	Creates a new list that combines the given start element with the given list.
static <T> List<T>	combinedList(T start, List<T> list, T end)	Creates a new list that combines the start element with the list and the end element.
static <T> Iterable<T>	concatenatedIterable(Iterable<T> first, Iterable<T> second)	Combines two iterables into a single iterable that iterates over the items of both iterables.
static <T> List<T>	concatenatedList(List<T> head, List<T> tail)	Returns a read-only list view that combines the two given lists.
static <T> ToDoubleFunction<T>	constantToDoubleFunction(double value)	Returns a constant ToDoubleFunction that always returns the given value.
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> Iterable<V>	emptyIterableIfNull(V[] array)	Returns an empty iterable if the given array is null.
static <V> Iterator<V>	emptyIteratorIfNull(Iterator<V> iterator)	Returns an empty iterator if the given iterator 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, C extends Collection<T>> C	filterToCollection(Iterable<? extends T> items, Predicate<? super T> filter, Supplier<? extends C> collectionFactory)	Filters the elements of an iterable via the given filter function, putting the result into a collection.
static <T, C extends Collection<T>> C	filterToCollection(Iterator<? extends T> items, Predicate<? super T> filter, Supplier<? extends C> collectionFactory)	Filters the elements of an iterator via the given filter function, putting the result into a collection.
static <T, C extends Collection<T>> C	filterToCollection(T[] items, Predicate<? super T> filter, Supplier<? extends C> collectionFactory)	Filters the elements of an iterable via the given filter function, putting the result into a collection.
static <T> List<T>	filterToList(Iterable<? extends T> items, Predicate<? super T> filter)	Filters the elements of an iterable via the given filter function.
static <T, L extends List<T>> L	filterToList(Iterable<? extends T> items, Predicate<? super T> filter, Supplier<? extends L> collectionFactory)	Filters the elements of an iterable via the given filter function, putting the result into a list.
static <T, C extends List<T>> C	filterToList(Iterable<? extends T> items, Predicate<? super T> filter, Collector<? super T, ?, ? extends C> collector)	Filters the elements of an iterable via the given filter function, putting the result into a list via the given collector.
static <T> List<T>	filterToList(Iterator<? extends T> items, Predicate<? super T> filter)	Filters the elements of an iterator via the given filter function.
static <T, L extends List<T>> L	filterToList(Iterator<? extends T> items, Predicate<? super T> filter, Supplier<? extends L> collectionFactory)	Filters the elements of an iterator via the given filter function, putting the result into a list.
static <T, C extends List<T>> C	filterToList(Iterator<? extends T> items, Predicate<? super T> filter, Collector<? super T, ?, ? extends C> collector)	Filters the elements of an iterator via the given filter function, putting the result into a list via the given collector.
static <T> List<T>	filterToList(T[] items, Predicate<? super T> filter)	Filters the elements of an iterable via the given filter function.
static <T, L extends List<T>> L	filterToList(T[] items, Predicate<? super T> filter, Supplier<? extends L> collectionFactory)	Filters the elements of an iterable via the given filter function, putting the result into a list.
static <T, C extends List<T>> C	filterToList(T[] items, Predicate<? super T> filter, Collector<? super T, ?, ? extends C> collector)	Filters the elements of an iterable via the given filter function, putting the result into a list via the given collector.
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> int	findIndex(Iterable<? extends T> items, Predicate<? super T> test)	Finds the first index of the item for which the given test returns true.
static <T> int	findLastIndex(Iterable<? extends T> items, Predicate<? super T> test)	Finds the last index of the item for which the given test returns true.
static <T> T	firstElement(Iterable<T> elements)	Finds the first element of the iterable.
static <T> T	firstElement(Iterator<T> elements)	Finds the first element of the iterator.
static <T> T	firstElementOr(Iterable<? extends T> elements, T defaultValue)	Finds the first element of the iterable.
static <T> T	firstElementOr(Iterator<? extends T> elements, T defaultValue)	Finds the first element of the iterator.
static double	firstItem(double[] item)	Gets the first item, or null if no elements were given.
static int	firstItem(int[] item)	Gets the first item, or null if no elements were given.
static long	firstItem(long[] item)	Gets the first item, or null if no elements were given.
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> T	firstItem(T[] item)	Gets the first item, or null if no elements were given.
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,K> Map<K,List<T>>	groupItemsBy(Iterable<? extends T> items, Function<? super T, ? extends K> classifier)	Groups a list of items by classifying each item using the given classifier function.
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 <T,K> Map<K,T>	indexItemsBy(Iterable<? extends T> items, Function<? super T, ? extends K> indexExtractor)	Indexes the items of an iterable by the given index extractor function.
static boolean	isEmptyCollection(Collection<?> collection)	Same as CollectionUtils.isEmpty(Collection), but with a more verbose name for static imports.
static boolean	isEmptyIterable(Iterable<?> items)	Checks whether the given iterable contains no items.
static boolean	isEmptyMap(Map<?,?> map)	Sames as MapUtils.isEmpty(Map), but with a more verbose name for static imports.
static boolean	isNonEmptyCollection(Collection<?> collection)	Sames as CollectionUtils.isNotEmpty(Collection), but with a more verbose name when using static imports.
static boolean	isNonEmptyIterable(Iterable<?> items)	Checks whether the given iterable contains any items.
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 boolean	iterableContains(Iterable<?> items, Object value)	Checks if the given iterable contains the given value.
static boolean	iterableContainsAny(Iterable<?> items, Object... values)	Checks if the given iterable contains any of the given value.
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, String prefix, String suffix, Function<? super T, ?> stringifier, Predicate<? super String> filter)	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 String	joinIterableOmitEmpty(Iterable<?> items, String separator)	Joins the items of an iterable into a single string, separated by the given separator.
static String	joinIterableOmitEmpty(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	joinIterableOmitEmpty(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	joinIterableOmitEmpty(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 String	joinVarArgs(String separator, Object... values)	Joins the given variable number of arguments into a single string, separated by the given separator.
static String	joinVarArgsOmitEmpty(String separator, Object... items)	Joins the given variable number of arguments 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,R> R	lastElement(Iterable<? extends T> elements, Function<? super T, ? extends R> valueExtractor)	Gets the last element of an iterable, and, if non-null, applies the given value extractor to it.
static <T> T	lastElement(Iterable<T> elements)	Returns the last element of the iterable, or null if the iterable is null or empty, or the last item is null.
static <T> T	lastElement(Iterator<T> elements)	Returns the last element of the iterator, or null if the iterator is null or empty, or the last item is null.
static <T> T	lastElementOr(Iterable<? extends T> elements, T defaultValue)	Finds the last element of the iterable.
static <T> T	lastElementOr(Iterator<? extends T> elements, T defaultValue)	Finds the last element of the iterator.
static double	lastItem(double[] item)	Gets the last item, or null if no elements were given.
static int	lastItem(int[] item)	Gets the last item, or null if no elements were given.
static long	lastItem(long[] item)	Gets the last item, or null if no elements were given.
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> T	lastItem(T[] item)	Gets the last item, or null if no elements were given.
static <T> List<T>	listOfSize(int targetSize, T initialValue)
static <T> List<T>	listOfSizeWith(int targetSize, IntFunction<T> initialValue)
static <T> List<T>	listWithoutItem(List<T> items, T itemToRemove)	Returns a list that excludes the given item, if present.
static <T> List<T>	listWithoutItems(List<T> items, Predicate<T> removalTest)	Returns a list that excludes the items that match the removal predicate, if any.
static <K,V> Set<Map.Entry<K,V>>	mapEntries(Map<K,V> map)	Returns a set with the entries of the given map.
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 <K> Set<K>	mapKeys(Map<K,?> map)	Returns a set with the keys of the given 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, C extends Collection<S>> C	mapToCollection(Iterable<? extends T> items, Function<? super T, ? extends S> mapper, Collector<? super S, ?, ? extends C> collector)	Maps the elements of an iterable to new elements via the given mapping function, putting the result into a collection via the given collector.
static <T, S, C extends Collection<S>> C	mapToCollection(Iterator<? extends T> items, Function<? super T, ? extends S> mapper, Supplier<? extends C> collectionFactory)	Maps the elements of an iterator to new elements via the given mapping function, putting the result into a collection.
static <T, S, C extends Collection<S>> C	mapToCollection(Iterator<? extends T> items, Function<? super T, ? extends S> mapper, Collector<? super S, ?, ? extends C> collector)	Maps the elements of an iterator to new elements via the given mapping function, putting the result into a collection via the given collector.
static <T, S, C extends Collection<S>> C	mapToCollection(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, C extends Collection<S>> C	mapToCollection(T[] items, Function<? super T, ? extends S> mapper, Collector<? super S, ?, ? extends C> collector)	Maps the elements of an iterable to new elements via the given mapping function, putting the result into a collection via the given collector.
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, S, C extends List<S>> C	mapToList(Iterable<? extends T> items, Function<? super T, ? extends S> mapper, Collector<? super S, ?, ? extends C> collector)	Maps the elements of an iterable to new elements via the given mapping function, putting the result into a list via the given collector.
static <T,S> List<S>	mapToList(Iterator<? extends T> items, Function<? super T, ? extends S> mapper)	Maps the elements of an iterator to new elements via the given mapping function.
static <T, S, L extends List<S>> L	mapToList(Iterator<? extends T> items, Function<? super T, ? extends S> mapper, Supplier<? extends L> collectionFactory)	Maps the elements of an iterator to new elements via the given mapping function, putting the result into a list.
static <T, S, C extends List<S>> C	mapToList(Iterator<? extends T> items, Function<? super T, ? extends S> mapper, Collector<? super S, ?, ? extends C> collector)	Maps the elements of an iterator to new elements via the given mapping function, putting the result into a list via the given collector.
static <T,S> List<S>	mapToList(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(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, S, C extends List<S>> C	mapToList(T[] items, Function<? super T, ? extends S> mapper, Collector<? super S, ?, ? extends C> collector)	Maps the elements of an iterable to new elements via the given mapping function, putting the result into a list via the given collector.
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, S, C extends Set<S>> C	mapToSet(Iterable<? extends T> items, Function<? super T, ? extends S> mapper, Collector<? super S, ?, ? extends C> collector)	Maps the elements of an iterable to new elements via the given mapping function, putting the result into a set via the given collector.
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 <V> Collection<V>	mapValues(Map<?,V> map)	Returns a collection with the values of the given 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> T	maxItem(Iterable<? extends T> items, Comparator<? super T> comparator)	Returns the maximum item from the given items, according to the given comparator.
static <T> T	minItem(Iterable<? extends T> items, Comparator<? super T> comparator)	Returns the minimum item from the given items, according to the given comparator.
static <T> List<T>	mutableList(T... items)	Creates a new mutable list with the given items.
static <T> CollectionPartition<T>	partitionSets(Iterable<T> first, Iterable<T> second)	Partitions to set of items into three sets: items that are only in the first set, items that are only in the second set, and items that are in both sets.
static <T> T	removeElementAt(Iterable<T> iterable, int index)	Removes the element at given index from the iterable.
static <T> T	removeFirstElement(Iterable<T> iterable)	Removes the element at given index from the iterable.
static <T> T	removeLastElement(Iterable<T> iterable)	Removes the element at given index from the iterable.
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> Set<T>	setUnion(Iterable<? extends T> a, Iterable<? extends T> b)	Returns a set that is the union of the given items (ignoring duplicates).
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 <T> Iterable<T>	sortedIterable(Iterable<? extends T> items, Comparator<? super T> comparator)	Returns a sorted iterable over the given items, using the given comparator.
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.
static <T> List<T>	subList(List<T> list, int fromInclusive, int endExclusive)	Similar to List.subList, but handles out of bounds indices gracefully.
static <Value> Map<String,Value>	toCaseInsensitiveKeysMap(Map<String,Value> map)
static <Item,Key,R> R	toDistinctKeepFirst(Iterable<? extends Item> items, Function<? super Item, ? extends Key> keyExtractor, Collector<Item,?,R> collector)

Methods inherited from class Object

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

Method Details

adjoiningIndex

public static <T>
Collector<T, ?, Stream<XIterableUtils.Indexed<T>>> adjoiningIndex()

Gets a collector that adds the 0-based index to all elements, and returns a stream of these elements.

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<? super Iterable<XIterableUtils.Indexed<T>>, R> finisher)

Gets a collector that adds the 0-based index to all elements, and applies the finisher to the list of indexed elements.

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)

Gets a collector that adds the 0-based index to all elements, and applies the downstream collector to all elements.

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.

areAllCollectionsEmpty

public static boolean areAllCollectionsEmpty(Collection<?>... collections)

Checks if all the given collections are empty. null is treated as an empty collection.

Parameters:

collections - Collections to check.

Returns:

true if all collections are null or empty, false if at least one collection is not empty.

arrayAsUnmodifiableListView

public static <T> List<T> arrayAsUnmodifiableListView(T[] items)

Returns a list view of the array that is unmodifiable and serializable (assuming the type T is serializable). Changes to the array will be reflected in the list, but the array cannot be modified via the list interface.

Type Parameters:

T - Type of the items in the array.

Parameters:

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

Returns:

An unmodifiable list view of the given array.

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.

collectItems

public static <T,R> R collectItems(Iterable<? extends T> items,
 Collector<? super T, ?, ? extends R> collector)

Collects the given items into a single result via the given collector. This is functionally the same as

    StreamSupport.stream(items.spliterator(), false).collect(collector)

Type Parameters:

T - Type of the items in the iterable.

R - Type of the result of the collection.

Parameters:

items - Items to collect. Can be null, which is interpreted as an empty iterable.

collector - The collector to use for collecting the items. The collector must not be null.

Returns:

The result of the collection, as produced by the collector.

collectionSize

public static int collectionSize(Collection<?> collection)

Same as CollectionUtils.size(Object), but with a more verbose name for static imports.

Parameters:

collection - Collection to check.

Returns:

true if the collection is null or empty.

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.

combinedList

public static <T> List<T> combinedList(List<T> list,
 T end)

Creates a new list that combines the given list with the given element at the end. If the end element is null, returns the list as is, without an additional element.

Type Parameters:

T - Type of the list elements.

Parameters:

list - List to combine with the end element. null is treated as an empty list.

end - Element to add at the end of the list.

Returns:

The combined list, never null.

combinedList

public static <T> List<T> combinedList(T start,
 List<T> list)

Creates a new list that combines the given start element with the given list. If the start element is null, returns the list as is, without an additional element at the start.

Type Parameters:

T - Type of the list elements.

Parameters:

start - Element to add at the start of the list.

list - List to combine with the start element. null is treated as an empty list.

Returns:

The combined list, never null.

combinedList

public static <T> List<T> combinedList(T start,
 List<T> list,
 T end)

Creates a new list that combines the start element with the list and the end element. If both start and end elements are null, returns the list as is, without additional elements. If only one of them is null, adds the other one to the list.

Type Parameters:

T - Type of the list elements.

Parameters:

start - Element to add at the start of the list.

list - List to combine with the start and end elements. null is treated as an empty list.

end - Element to add at the end of the list.

Returns:

The combined list, never null.

concatenatedIterable

public static <T> Iterable<T> concatenatedIterable(Iterable<T> first,
 Iterable<T> second)

Combines two iterables into a single iterable that iterates over the items of both iterables. A null iterable is treated as an empty iterable.

Type Parameters:

T - Type of the items in the iterables.s

Parameters:

first - The first iterable. null is treated as an empty iterable.

second - The second iterable. null is treated as an empty iterable.

Returns:

An iterable that iterates over the items of both iterables, or an empty iterable if both are null.

concatenatedList

public static <T> List<T> concatenatedList(List<T> head,
 List<T> tail)

Returns a read-only list view that combines the two given lists. If either of the lists is null, it is treated as an empty list. Changes in the input list will be reflected in the returned list.

Type Parameters:

T - Type of the items in the lists.

Parameters:

head - The first list to combine.

tail - The second list to combine.

Returns:

A new list that contains all elements from both lists, or an empty list if both are null.

constantToDoubleFunction

public static <T> ToDoubleFunction<T> constantToDoubleFunction(double value)

Returns a constant ToDoubleFunction that always returns the given value.

Type Parameters:

T - Type of the input to the function.

Parameters:

value - The value to return.

Returns:

A function that always returns the given value.

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

emptyIterableIfNull

public static <V> Iterable<V> emptyIterableIfNull(V[] array)

Returns an empty iterable if the given array is null. Otherwise, returns an iterator over the array.

Type Parameters:

V - Type of the items in the array.

Parameters:

array - An array to process.

Returns:

An iterable over the given array when not null, or an empty iterable otherwise.

emptyIteratorIfNull

public static <V> Iterator<V> emptyIteratorIfNull(Iterator<V> iterator)

Returns an empty iterator if the given iterator is null. Otherwise, just returns the iterator 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 iterator.

Parameters:

iterator - An iterator to process.

Returns:

The given iterator when not null, or an empty iterator 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.

filterToCollection

public static <T, C extends Collection<T>> C filterToCollection(Iterable<? extends T> items,
 Predicate<? super T> filter,
 Supplier<? extends C> collectionFactory)

Filters the elements of an iterable via the given filter function, putting the result into a collection. Functionally the same as

StreamSupport.stream(items.spliterator(), false).filter(filter).collect(Collectors.toCollection(() -> listFactory.apply(list.size()))

Type Parameters:

T - Type of the source elements.

C - Type of the new collection.

Parameters:

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

filter - Filter 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.

filterToCollection

public static <T, C extends Collection<T>> C filterToCollection(Iterator<? extends T> items,
 Predicate<? super T> filter,
 Supplier<? extends C> collectionFactory)

Filters the elements of an iterator via the given filter function, putting the result into a collection. Functionally the same as

stream(items).filter(filter).collect(Collectors.toCollection(() -> listFactory.apply(list.size()))

Type Parameters:

T - Type of the source elements.

C - Type of the new collection.

Parameters:

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

filter - Filter 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.

filterToCollection

public static <T, C extends Collection<T>> C filterToCollection(T[] items,
 Predicate<? super T> filter,
 Supplier<? extends C> collectionFactory)

Filters the elements of an iterable via the given filter function, putting the result into a collection. Functionally the same as

Arrays.stream(items).filter(filter).collect(Collectors.toCollection(() -> listFactory.apply(list.size()))

Type Parameters:

T - Type of the source elements.

C - Type of the new collection.

Parameters:

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

filter - Filter 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.

filterToList

public static <T, C extends List<T>> C filterToList(Iterable<? extends T> items,
 Predicate<? super T> filter,
 Collector<? super T, ?, ? extends C> collector)

Filters the elements of an iterable via the given filter function, putting the result into a list via the given collector. Functionally the same as

StreamSupport.stream(items.spliterator(), false).filter(filter).collect(collector)

Type Parameters:

T - Type of the source elements.

C - Type of the new collection.

Parameters:

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

filter - Filter function to apply.

collector - Collector for creating a new list.

Returns:

A list as created by the collector, with the filtered elements.

filterToList

public static <T, C extends List<T>> C filterToList(Iterator<? extends T> items,
 Predicate<? super T> filter,
 Collector<? super T, ?, ? extends C> collector)

Filters the elements of an iterator via the given filter function, putting the result into a list via the given collector. Functionally the same as

stream(items).filter(filter).collect(collector)

Type Parameters:

T - Type of the source elements.

C - Type of the new collection.

Parameters:

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

filter - Filter function to apply.

collector - Collector for creating a new list.

Returns:

A list as created by the collector, with the filtered elements.

filterToList

public static <T, C extends List<T>> C filterToList(T[] items,
 Predicate<? super T> filter,
 Collector<? super T, ?, ? extends C> collector)

Filters the elements of an iterable via the given filter function, putting the result into a list via the given collector. Functionally the same as

Arrays.stream(items).filter(filter).collect(collector)

Type Parameters:

T - Type of the source elements.

C - Type of the new collection.

Parameters:

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

filter - Filter function to apply.

collector - Collector for creating a new list.

Returns:

A list as created by the collector, with the filtered elements.

filterToList

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

Filters the elements of an iterable via the given filter function. Functionally the same as

StreamSupport.stream(items.spliterator(), false).filter(filter).collect(Collectors.toList())

The returned list is serializable and mutable.

Type Parameters:

T - Type of the source elements.

Parameters:

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

filter - Filter function to apply.

Returns:

A new list with the filtered elements.

filterToList

public static <T> List<T> filterToList(Iterator<? extends T> items,
 Predicate<? super T> filter)

Filters the elements of an iterator via the given filter function. Functionally the same as

stream(items).filter(filter).collect(Collectors.toList())

The returned list is serializable and mutable.

Type Parameters:

T - Type of the source elements.

Parameters:

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

filter - Filter function to apply.

Returns:

A new list with the filtered elements.

filterToList

public static <T> List<T> filterToList(T[] items,
 Predicate<? super T> filter)

Filters the elements of an iterable via the given filter function. Functionally the same as

Arrays.stream(items).filter(filter).collect(Collectors.toList())

The returned list is serializable and mutable.

Type Parameters:

T - Type of the source elements.

Parameters:

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

filter - Filter function to apply.

Returns:

A new list with the filtered elements.

filterToList

public static <T, L extends List<T>> L filterToList(Iterable<? extends T> items,
 Predicate<? super T> filter,
 Supplier<? extends L> collectionFactory)

Filters the elements of an iterable via the given filter function, putting the result into a list. Functionally the same as

StreamSupport.stream(items.spliterator(), false).filter(filter).collect(Collectors.toCollection(() -> listFactory.apply(list.size()))

Type Parameters:

T - Type of the source elements.

L - Type of the new collection.

Parameters:

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

filter - Filter function to apply.

collectionFactory - Factory for creating a new list.

Returns:

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

filterToList

public static <T, L extends List<T>> L filterToList(Iterator<? extends T> items,
 Predicate<? super T> filter,
 Supplier<? extends L> collectionFactory)

Filters the elements of an iterator via the given filter function, putting the result into a list. Functionally the same as

stream(items).filter(filter).collect(Collectors.toCollection(() -> listFactory.apply(list.size()))

Type Parameters:

T - Type of the source elements.

L - Type of the new collection.

Parameters:

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

filter - Filter function to apply.

collectionFactory - Factory for creating a new list.

Returns:

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

filterToList

public static <T, L extends List<T>> L filterToList(T[] items,
 Predicate<? super T> filter,
 Supplier<? extends L> collectionFactory)

Filters the elements of an iterable via the given filter function, putting the result into a list. Functionally the same as

Arrays.stream(items).filter(filter).collect(Collectors.toCollection(() -> listFactory.apply(list.size()))

Type Parameters:

T - Type of the source elements.

L - Type of the new collection.

Parameters:

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

filter - Filter function to apply.

collectionFactory - Factory for creating a new list.

Returns:

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

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.

findIndex

public static <T> int findIndex(Iterable<? extends T> items,
 Predicate<? super T> test)

Finds the first index of the item for which the given test returns true. If the test never returns true for any item, returns -1.

Type Parameters:

T - Type of the items in the iterable.

Parameters:

items - The items to search through.

test - The test to apply to each item.

Returns:

The index of the first item for which the test returns true, or -1 if no such item exists.

findLastIndex

public static <T> int findLastIndex(Iterable<? extends T> items,
 Predicate<? super T> test)

Finds the last index of the item for which the given test returns true. If the test never returns true for any item, returns -1.

Type Parameters:

T - Type of the items in the iterable.

Parameters:

items - The items to search through.

test - The test to apply to each item.

Returns:

The index of the last item for which the test returns true, or -1 if no such item exists.

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.

firstElement

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

Finds the first element of the iterator. Returns null if the iterator 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.

firstElementOr

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

Finds the first element of the iterator. Returns the default value if the iterator 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.

firstItem

public static <T> T firstItem(T[] item)

Gets the first item, or null if no elements were given.

Type Parameters:

T - Type of the items.

Parameters:

item - Items to process.

Returns:

The first item from the items, or null if the items are null or empty.

firstItem

public static int firstItem(int[] item)

Gets the first item, or null if no elements were given.

Parameters:

item - Items to process.

Returns:

The first item from the items, or 0 if the items are null or empty.

firstItem

public static long firstItem(long[] item)

Gets the first item, or null if no elements were given.

Parameters:

item - Items to process.

Returns:

The first item from the items, or 0 if the items are null or empty.

firstItem

public static double firstItem(double[] item)

Gets the first item, or null if no elements were given.

Parameters:

item - Items to process.

Returns:

The first item from the items, or 0 if the items are null or empty.

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.

groupItemsBy

public static <T,K> Map<K,List<T>> groupItemsBy(Iterable<? extends T> items,
 Function<? super T, ? extends K> classifier)

Groups a list of items by classifying each item using the given classifier function. Returns a map where the keys are the classifier, and the values are lists of items corresponding to each classifier. Functionally the same as

    StreamSupport.stream(items.spliterator(), false).collect(Collectors.groupingBy(classifier));

Type Parameters:

T - Type of the items in the iterable.

K - Type of the classifier for each item.

Parameters:

items - Items to group. Can be null, which is interpreted as an empty iterable.

classifier - Function that classifies each item into a key. The classifier must not be null.

Returns:

A map where the keys are the classifier, and the values are lists of items corresponding to each classifier.

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. When null, all values are set to null.

Returns:

The given list grown to the target size.

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.

indexItemsBy

public static <T,K> Map<K,T> indexItemsBy(Iterable<? extends T> items,
 Function<? super T, ? extends K> indexExtractor)

Indexes the items of an iterable by the given index extractor function. Returns a map where the keys are the index values as returned by the index extractor, and the values are the items themselves. If multiple items share the same index value, the last item is kept in the map.

Type Parameters:

T - Type of the items in the iterable.

K - Type of the index values as returned by the index extractor.

Parameters:

items - Items to index. Can be null, which is interpreted as an empty iterable.

indexExtractor - Function that extracts the index value for each item. The index extractor must not be null.

Returns:

A map where the keys are the index values as returned by the index extractor, and the values are the items themselves.

isEmptyCollection

public static boolean isEmptyCollection(Collection<?> collection)

Same as CollectionUtils.isEmpty(Collection), but with a more verbose name for static imports.

Parameters:

collection - Collection to check.

Returns:

true if the collection is null or empty.

isEmptyIterable

public static boolean isEmptyIterable(Iterable<?> items)

Checks whether the given iterable contains no items. Returns true if it has no items and false if it has at least one item. A null iterable is treated as empty.

Parameters:

items - Items to check.

Returns:

true if the iterable is empty or null, false otherwise.

isEmptyMap

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

Sames as MapUtils.isEmpty(Map), but with a more verbose name for 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.

isNonEmptyIterable

public static boolean isNonEmptyIterable(Iterable<?> items)

Checks whether the given iterable contains any items. Returns true if it has at least one item and false if it has no items. A null iterable is treated as empty.

Parameters:

items - Iterable to check.

Returns:

Whether the iterable is non-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

iterableContains

public static boolean iterableContains(Iterable<?> items,
 Object value)

Checks if the given iterable contains the given value. The value is compared using hashCode and equals.

Parameters:

items - Iterable to check.

value - Value to check for.

iterableContainsAny

public static boolean iterableContainsAny(Iterable<?> items,
 Object... values)

Checks if the given iterable contains any of the given value. The value is compared using hashCode and equals.

Parameters:

items - Iterable to check.

values - Values to check for.

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 Object.toString(), with the empty string for null.

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.

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 Object.toString().

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 Object.toString(), with the empty string for null.

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.

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 Object.toString().

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,
 Predicate<? super String> filter)

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. Items not matching the filter are omitted from the resulting string.

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 Object.toString().

filter - Optional filter to apply to the items. If null, all items are included in the resulting string.

Returns:

The items joined into a single string.

joinIterableOmitEmpty

public static String joinIterableOmitEmpty(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 Object.toString(), with the empty string for null. Empty items (null or empty strings) are omitted from the resulting string.

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.

joinIterableOmitEmpty

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

Joins the items of an iterable into a single string, separated by the given separator. The items are converted to strings using Object.toString() with the empty string for null. Adds the given prefix and suffix before and after the items. Empty items (null or empty strings) are omitted from the resulting string.

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.

joinIterableOmitEmpty

public static <T> String joinIterableOmitEmpty(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. Empty items (null or empty strings) are omitted from the resulting string.

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 Object.toString().

Returns:

The items joined into a single string.

joinIterableOmitEmpty

public static <T> String joinIterableOmitEmpty(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. The items are converted to strings using the given stringifier. Adds the given prefix and suffix before and after the items. Empty items (null or empty strings) are omitted from the resulting string.

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 Object.toString().

Returns:

The items joined into a single string.

joinVarArgs

public static String joinVarArgs(String separator,
 Object... values)

Joins the given variable number of arguments into a single string, separated by the given separator. The items are converted to strings using Object.toString(). null items are converted to the empty string.

Parameters:

separator - Separator to insert between items.

values - Variable number of arguments to join. Null or empty items are ignored.

Returns:

The items joined into a single string.

joinVarArgsOmitEmpty

public static String joinVarArgsOmitEmpty(String separator,
 Object... items)

Joins the given variable number of arguments into a single string, separated by the given separator. The items are converted to strings using Object.toString(). null items are converted to the empty string. Strings that are null or empty are ignored.

Parameters:

separator - Separator to insert between items.

items - Variable number of arguments to join. Null or empty items are ignored.

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)

Returns the last element of the iterable, or null if the iterable is null or empty, or the last item is null.

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 last item is null.

lastElement

public static <T> T lastElement(Iterator<T> elements)

Returns the last element of the iterator, or null if the iterator is null or empty, or the last item is null.

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 last item is null.

lastElement

public static <T,R> R lastElement(Iterable<? extends T> elements,
 Function<? super T, ? extends R> valueExtractor)

Gets the last element of an iterable, and, if non-null, applies the given value extractor to it. Useful for avoiding manual null checks when you want to get a value from the last element.

Type Parameters:

T - Type of the elements.

R - Type of the extracted value.

Parameters:

elements - Elements to process.

valueExtractor - Extractor for the value of the last element.

Returns:

The result of applying the value extractor to the last element from the elements, or null if the elements are null or empty, or the last 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.

lastElementOr

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

Finds the last element of the iterator. Returns the default value if the iterator 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(T[] item)

Gets the last item, or null if no elements were given.

Type Parameters:

T - Type of the items.

Parameters:

item - Items to process.

Returns:

The last item from the items, or null if the items are null or empty.

lastItem

public static int lastItem(int[] item)

Gets the last item, or null if no elements were given.

Parameters:

item - Items to process.

Returns:

The last item from the items, or 0 if the items are null or empty.

lastItem

public static long lastItem(long[] item)

Gets the last item, or null if no elements were given.

Parameters:

item - Items to process.

Returns:

The last item from the items, or 0 if the items are null or empty.

lastItem

public static double lastItem(double[] item)

Gets the last item, or null if no elements were given.

Parameters:

item - Items to process.

Returns:

The last item from the items, or 0 if the items 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.

listWithoutItem

public static <T> List<T> listWithoutItem(List<T> items,
 T itemToRemove)

Returns a list that excludes the given item, if present.

Type Parameters:

T - Type of the items in the list.

Parameters:

items - The list of items to process.

itemToRemove - The item to exclude from the list.

Returns:

A list without the item to remove.

listWithoutItems

public static <T> List<T> listWithoutItems(List<T> items,
 Predicate<T> removalTest)

Returns a list that excludes the items that match the removal predicate, if any.

Type Parameters:

T - Type of the items in the list.

Parameters:

items - The list of items to process.

removalTest - Predicate for the items to exclude from the list. null is treated as a predicate that always returns false, meaning no items are removed.

Returns:

A list without the item to remove.

mapEntries

public static <K,V> Set<Map.Entry<K,V>> mapEntries(Map<K,V> map)

Returns a set with the entries of the given map. When the map is null, returns an empty set.

Type Parameters:

K - Type of the map keys.

V - Type of the map values.

Parameters:

map - Map with entries to retrieve.

Returns:

A set with the map's entries.

mapKeys

public static <K> Set<K> mapKeys(Map<K,?> map)

Returns a set with the keys of the given map. When the map is null, returns an empty set.

Type Parameters:

K - Type of the map keys.

Parameters:

map - Map with keys to retrieve.

Returns:

A set with the map's keys.

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.

mapToCollection

public static <T, S, C extends Collection<S>> C mapToCollection(Iterator<? extends T> items,
 Function<? super T, ? extends S> mapper,
 Supplier<? extends C> collectionFactory)

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

stream(items).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.

mapToCollection

public static <T, S, C extends Collection<S>> C mapToCollection(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

Arrays.stream(items).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.

mapToCollection

public static <T, S, C extends Collection<S>> C mapToCollection(Iterable<? extends T> items,
 Function<? super T, ? extends S> mapper,
 Collector<? super S, ?, ? extends C> collector)

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

StreamSupport.stream(items.spliterator(), false).map(mapper).collect(collector)

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.

collector - Collector for creating a new collection.

Returns:

A collection as created by the collector, with the mapped elements.

mapToCollection

public static <T, S, C extends Collection<S>> C mapToCollection(Iterator<? extends T> items,
 Function<? super T, ? extends S> mapper,
 Collector<? super S, ?, ? extends C> collector)

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

stream(items).map(mapper).collect(collector)

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.

collector - Collector for creating a new collection.

Returns:

A collection as created by the collector, with the mapped elements.

mapToCollection

public static <T, S, C extends Collection<S>> C mapToCollection(T[] items,
 Function<? super T, ? extends S> mapper,
 Collector<? super S, ?, ? extends C> collector)

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

Arrays.stream(items).map(mapper).collect(collector)

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.

collector - Collector for creating a new collection.

Returns:

A collection as created by the collector, with the mapped elements.

mapToList

public static <T, S, C extends List<S>> C mapToList(Iterable<? extends T> items,
 Function<? super T, ? extends S> mapper,
 Collector<? super S, ?, ? extends C> collector)

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

StreamSupport.stream(items.spliterator(), false).map(mapper).collect(collector)

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.

collector - Collector for creating a new list.

Returns:

A list as created by the collector, with the mapped elements.

mapToList

public static <T, S, C extends List<S>> C mapToList(Iterator<? extends T> items,
 Function<? super T, ? extends S> mapper,
 Collector<? super S, ?, ? extends C> collector)

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

stream(items).map(mapper).collect(collector)

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.

collector - Collector for creating a new list.

Returns:

A list as created by the collector, with the mapped elements.

mapToList

public static <T, S, C extends List<S>> C mapToList(T[] items,
 Function<? super T, ? extends S> mapper,
 Collector<? super S, ?, ? extends C> collector)

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

Arrays.stream(items).map(mapper).collect(collector)

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.

collector - Collector for creating a new list.

Returns:

A list as created by the collector, with the mapped elements.

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> List<S> mapToList(Iterator<? extends T> items,
 Function<? super T, ? extends S> mapper)

Maps the elements of an iterator to new elements via the given mapping function. Functionally the same as

stream(items).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> List<S> mapToList(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

Arrays.stream(items).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.

mapToList

public static <T, S, L extends List<S>> L mapToList(Iterator<? extends T> items,
 Function<? super T, ? extends S> mapper,
 Supplier<? extends L> collectionFactory)

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

stream(items).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.

mapToList

public static <T, S, L extends List<S>> L mapToList(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

Arrays.stream(items).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, C extends Set<S>> C mapToSet(Iterable<? extends T> items,
 Function<? super T, ? extends S> mapper,
 Collector<? super S, ?, ? extends C> collector)

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

StreamSupport.stream(items.spliterator(), false).map(mapper).collect(collector)

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.

collector - Collector for creating a new set.

Returns:

A set as created by the collector, with the mapped elements.

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 <V> Collection<V> mapValues(Map<?,V> map)

Returns a collection with the values of the given map. When the map is null, returns an empty collection.

Type Parameters:

V - Type of the map values.

Parameters:

map - Map with values to retrieve.

Returns:

A collection with the map's values.

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.

maxItem

public static <T> T maxItem(Iterable<? extends T> items,
 Comparator<? super T> comparator)

Returns the maximum item from the given items, according to the given comparator. Returns null if the iterable is null or empty. If more than one item is the maximum, the first one is returned.

Type Parameters:

T - Type of the items.

Parameters:

items - The items to process.

comparator - The comparator to use for comparing the items, musts not be null.

Returns:

The maximum item from the items, or null if the items are null or empty.

minItem

public static <T> T minItem(Iterable<? extends T> items,
 Comparator<? super T> comparator)

Returns the minimum item from the given items, according to the given comparator. Returns null if the iterable is null or empty. If more than one item is the minimum, the first one is returned.

Type Parameters:

T - Type of the items.

Parameters:

items - The items to process.

comparator - The comparator to use for comparing the items, musts not be null.

Returns:

The minimum item from the items, or null if the items are null or empty.

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.

partitionSets

public static <T> CollectionPartition<T> partitionSets(Iterable<T> first,
 Iterable<T> second)

Partitions to set of items into three sets: items that are only in the first set, items that are only in the second set, and items that are in both sets.

Type Parameters:

T - Type of the items.

Parameters:

first - The first set of items.

second - The second set of items.

Returns:

The partitioned sets, containing items that are only in the first set, only in the second set, and in both sets.

removeElementAt

public static <T> T removeElementAt(Iterable<T> iterable,
 int index)

Removes the element at given index from the iterable. Does nothing if the iterable is null or contains less than (index+1) elements. Returns the element that was removed.

Type Parameters:

T - Type of the items.

Parameters:

iterable - The iterable to remove the element from.

index - The index of the element to remove. Should be in the range (0, size-1).

Returns:

The element that was removed, or null if no element exists at the given index.

Throws:

UnsupportedOperationException - If the iterable does not support removal.

removeFirstElement

public static <T> T removeFirstElement(Iterable<T> iterable)

Removes the element at given index from the iterable. Does nothing if the iterable is null or does not contain any elements. Returns the element that was removed.

Type Parameters:

T - Type of the items.

Parameters:

iterable - The iterable to remove the element from.

Returns:

The first element that was removed, or null if the iterable did not have any elements.

Throws:

UnsupportedOperationException - If the iterable does not support removal.

removeLastElement

public static <T> T removeLastElement(Iterable<T> iterable)

Removes the element at given index from the iterable. Does nothing if the iterable is null or does not contain any elements. Returns the element that was removed.

Type Parameters:

T - Type of the items.

Parameters:

iterable - The iterable to remove the element from.

Returns:

The first element that was removed, or null if the iterable did not have any elements.

Throws:

UnsupportedOperationException - If the iterable does not support removal.

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.

setUnion

public static <T> Set<T> setUnion(Iterable<? extends T> a,
 Iterable<? extends T> b)

Returns a set that is the union of the given items (ignoring duplicates). The returned set is immutable and changes to the given sets will not be reflected in the returned set.

Type Parameters:

T - Type of the items in the sets.

Parameters:

a - The first set of items.

b - The second set of items.

Returns:

A new set that contains all items from both sets, without duplicates.

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.

sortedIterable

public static <T> Iterable<T> sortedIterable(Iterable<? extends T> items,
 Comparator<? super T> comparator)

Returns a sorted iterable over the given items, using the given comparator. If the iterable is a collection, that collection is not modified.

Type Parameters:

T - Type of the items.

Parameters:

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

comparator - Comparator to use for sorting. null is treated as natural order.

Returns:

A sorted iterable over the items.

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.

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.

subList

public static <T> List<T> subList(List<T> list,
 int fromInclusive,
 int endExclusive)

Similar to List.subList, but handles out of bounds indices gracefully. Restricts both indices to the range [0, size] of the given list, and returns an empty list if either the list is empty or the range is empty.

Parameters:

list - The list to take the sublist from.

fromInclusive - The start index, inclusive.

endExclusive - The end index, exclusive.

Returns:

A sublist of the given list.

toCaseInsensitiveKeysMap

public static <Value> Map<String,Value> toCaseInsensitiveKeysMap(Map<String,Value> map)

toDistinctKeepFirst

@CanIgnoreReturnValue
public static <Item,Key,R> R toDistinctKeepFirst(Iterable<? extends Item> items,
 Function<? super Item, ? extends Key> keyExtractor,
 Collector<Item,?,R> collector)