Package de.xima.fc.utils

Class XCollectionUtils

java.lang.Object

de.xima.fc.utils.XCollectionUtils

public class XCollectionUtils
extends Object

Utility class for operations on collections and iterables.

Since:

7.0.0

Author:

XIMA Media GmbH

Method Summary

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

Methods inherited from class java.lang.Object

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

Method Detail

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.

growToSize

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

Grows a list to at least the given target size, doing nothing if the list's size is already equal to or greater than the target size. When the given list is null, an empty list is created, grown, and returned.

Type Parameters:

T - Type of the list items.

Parameters:

list - List to mutate.

targetSize - Target size.

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

Returns:

The given list grown to the target size.

Throws:

NullPointerException - When the value supplier is null.

mapToList

public static <T,S> List<S> mapToList(Iterable<T> items,
                                            Function<T,S> mapper)

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

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

The returned list is serializable and mutable.

Type Parameters:

T - Type of the source elements.

S - Type of the target elements.

Parameters:

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

mapper - Mapping function to apply.

Returns:

A new list with the mapped elements.

mapToList

public static <T,S,C extends Collection<S>> C mapToList(Iterable<T> items,
                                                                    Function<T,S> mapper,
                                                                    Supplier<C> collectionFactory)

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

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

Type Parameters:

T - Type of the source elements.

S - Type of the target elements.

C - Type of the new collection.

Parameters:

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

mapper - Mapping function to apply.

collectionFactory - Factory for creating a new collection.

Returns:

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

itemAt

public static <T> T itemAt(List<T> list,
                           int index)

Gets the item at the given index, or null if the index is out of bounds.

Type Parameters:

T - Type of the elements in the list.

Parameters:

list - List to process.

index - Index to access.

Returns:

The element at the index, null if there is no such element.

lastItem

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

Type Parameters:

T - Type of the elements in the list.

Parameters:

list - List to process.

Returns:

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

listOfSize

public static <T> List<T> listOfSize(int targetSize,
                                     T initialValue)

Type Parameters:

T - Type of the list elements.

Parameters:

targetSize - Desired size of the list.

initialValue - Initial value for each element.

Returns:

A list of the given size, with each element set to the given initial value.

listOfSizeWith

public static <T> List<T> listOfSizeWith(int targetSize,
                                         IntFunction<T> initialValue)

Type Parameters:

T - Type of the list elements.

Parameters:

targetSize - Desired size of the list.

initialValue - Supplier for the initial value for each element.

Returns:

A list of the given size, with each element set to the value returned by the given supplier.

adjoiningIndex

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

Type Parameters:

T - Type of the input elements.

Returns:

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

adjoiningIndex

public static <T,R> Collector<T,?,R> adjoiningIndex(Function<Iterable<IterableUtils.Indexed<T>>,R> finisher)

Type Parameters:

T - Type of the input elements.

R - Type of the output.

Parameters:

finisher - Finisher that transform the indexed element to the output type.

Returns:

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

adjoiningIndex

public static <T,A,R> Collector<T,?,R> adjoiningIndex(Collector<IterableUtils.Indexed<T>,A,R> downstream)

Type Parameters:

T - Type of the input elements.

A - Type of the intermediate elements of the downstream collector.

R - Type of the output.

Parameters:

downstream - Downstream that combines all elements into a single value.

Returns:

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

mapKeys

public static <K1,K2,V> Map<K2,V> mapKeys(Map<? extends K1,? extends V> map,
                                                            Function<? super K1,? extends K2> keyMapper)

Remaps the keys of a map by applying the given mapping function to all keys, returning a new map. If there are multiple mapped entries with the same key, the latter entry will be used.

Type Parameters:

K1 - Type of the input map keys.

K2 - Type of the output map keys.

V - Type of the map values.

Parameters:

map - Map to process.

keyMapper - Mapping function for the keys.

Returns:

The new map.

Since:

8.0.0

mapKeys

public static <K1,K2,V> Map<K2,V> mapKeys(Map<? extends K1,? extends V> map,
                                                            Function<? super K1,? extends K2> keyMapper,
                                                            BinaryOperator<V> mergeFunction)

Remaps the keys of a map by applying the given mapping function to all keys, returning a new map.

Type Parameters:

K1 - Type of the input map keys.

K2 - Type of the output map keys.

V - Type of the map values.

Parameters:

map - Map to process.

keyMapper - Mapping function for the keys.

mergeFunction - Merge function values that map to the same key.

Returns:

The new map.

Since:

8.0.0

mapKeysToUnmodifiableMap

public static <K1,K2,V> Map<K2,V> mapKeysToUnmodifiableMap(Map<? extends K1,? extends V> map,
                                                                             Function<? super K1,? extends K2> keyMapper)

Remaps the keys of a map by applying the given mapping function to all keys, returning a new unmodifiable map. If there are multiple mapped entries with the same key, the latter entry will be used.

Type Parameters:

K1 - Type of the input map keys.

K2 - Type of the output map keys.

V - Type of the map values.

Parameters:

map - Map to process.

keyMapper - Mapping function for the keys.

Returns:

The new map.

Since:

8.0.0

mapKeysToUnmodifiableMap

public static <K1,K2,V> Map<K2,V> mapKeysToUnmodifiableMap(Map<? extends K1,? extends V> map,
                                                                             Function<? super K1,? extends K2> keyMapper,
                                                                             BinaryOperator<V> mergeFunction)

Remaps the keys of a map by applying the given mapping function to all keys, returning a new unmodifiable map.

Type Parameters:

K1 - Type of the input map keys.

K2 - Type of the output map keys.

V - Type of the map values.

Parameters:

map - Map to process.

keyMapper - Mapping function for the keys.

mergeFunction - Merge function values that map to the same key.

Returns:

The new map.

Since:

8.0.0

mapMap

public static <K1,V1,K2,V2> Map<K2,V2> mapMap(Map<? extends K1,? extends V1> map,
                                                                      BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper)

Maps the entries of a map by applying the given mapping function, returning a new map. If there are multiple mapped entries with the same key, the latter entry will be used.

Type Parameters:

K1 - Type of the input map keys.

V1 - Type of the input map values.

K2 - Type of the output map keys.

V2 - Type of the output map values.

Parameters:

map - Map to process.

entryMapper - Mapping function for the entries.

Returns:

The new map.

Since:

8.0.0

mapMap

public static <K1,V1,K2,V2> Map<K2,V2> mapMap(Map<? extends K1,? extends V1> map,
                                                                      BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper,
                                                                      BinaryOperator<V2> mergeFunction)

Maps the entries of a map by applying the given mapping function, returning a new map.

Type Parameters:

K1 - Type of the input map keys.

V1 - Type of the input map values.

K2 - Type of the output map keys.

V2 - Type of the output map values.

Parameters:

map - Map to process.

entryMapper - Mapping function for the entries.

mergeFunction - Merge function for duplicate entries.

Returns:

The new map.

Since:

8.0.0

mapMap

public static <K1,V1,K2,V2,M extends Map<K2,V2>> M mapMap(Map<? extends K1,? extends V1> map,
                                                                                        BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper,
                                                                                        BinaryOperator<V2> mergeFunction,
                                                                                        Supplier<M> mapFactory)

Maps the entries of a map by applying the given mapping function, returning a new map.

Type Parameters:

K1 - Type of the input map keys.

V1 - Type of the input map values.

K2 - Type of the output map keys.

V2 - Type of the output map values.

M - Type of the returned map.

Parameters:

map - Map to process.

entryMapper - Mapping function for the entries.

mergeFunction - Merge function for duplicate entries.

mapFactory - Factory for the map to build.

Returns:

The new map.

Since:

8.0.0

mapToUnmodifiableMap

public static <K1,V1,K2,V2> Map<K2,V2> mapToUnmodifiableMap(Map<? extends K1,? extends V1> map,
                                                                                    BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper)

Maps the entries of a map by applying the given mapping function, returning a new unmodifiable map. If there are multiple mapped entries with the same key, the latter entry will be used.

Type Parameters:

K1 - Type of the input map keys.

V1 - Type of the input map values.

K2 - Type of the output map keys.

V2 - Type of the output map values.

Parameters:

map - Map to process.

entryMapper - Mapping function for the entries.

Returns:

The new map.

Since:

8.0.0

mapToUnmodifiableMap

public static <K1,V1,K2,V2> Map<K2,V2> mapToUnmodifiableMap(Map<? extends K1,? extends V1> map,
                                                                                    BiFunction<? super K1,? super V1,? extends Map.Entry<? extends K2,? extends V2>> entryMapper,
                                                                                    BinaryOperator<V2> mergeFunction)

Maps the entries of a map by applying the given mapping function, returning a new unmodifiable map.

Type Parameters:

K1 - Type of the input map keys.

V1 - Type of the input map values.

K2 - Type of the output map keys.

V2 - Type of the output map values.

Parameters:

map - Map to process.

entryMapper - Mapping function for the entries.

mergeFunction - Merge function values that map to the same key.

Returns:

The new map.

Since:

8.0.0

mapValues

public static <K,V1,V2> Map<K,V2> mapValues(Map<? extends K,? extends V1> map,
                                                              Function<? super V1,? extends V2> valueMapper)

Remaps the values of a map by applying the given mapping function to all keys, returning a new map.

Type Parameters:

K - Type of the map keys.

V1 - Type of the input map values.

V2 - Type of the output map values.

Parameters:

map - Map to process.

valueMapper - Mapping function for the values.

Returns:

The new map.

Since:

8.0.0

mapValuesToUnmodifiableMap

public static <K,V1,V2> Map<K,V2> mapValuesToUnmodifiableMap(Map<? extends K,? extends V1> map,
                                                                               Function<? super V1,? extends V2> valueMapper)

Remaps the values of a map by applying the given mapping function to all keys, returning a new unmodifiable map.

Type Parameters:

K - Type of the map keys.

V1 - Type of the input map values.

V2 - Type of the output map values.

Parameters:

map - Map to process.

valueMapper - Mapping function for the values.

Returns:

The new map.

Since:

8.0.0

serializableList

public static <T> List<T> serializableList(Iterable<T> sequence)

Takes any Collection or Iterable and converts it to a serializable list that can be transferred via the API.

Type Parameters:

T - Type of the list items.

Parameters:

sequence - A sequence of items to put into a list.

Returns:

A serializable list with the given items.