Spring Framework 6.1.4 · org.springframework.util.CollectionUtils

Modifier and Type	Field and Description
pack-priv static final float	DEFAULT_LOAD_FACTOR Default load factor for `HashMap`/`LinkedHashMap` variants.

Access	Constructor and Description
public	CollectionUtils()

Method Summary

Modifier and Type	Method and Description
public static List<?>	Returns: the converted List result arrayToList(Object the (potentially primitive) array source) Convert the supplied array into a List.
private static int	computeMapInitialCapacity(int expectedSize)
public static boolean	Returns: `true` if found, `false` otherwise contains(Iterator<?> the Iterator to check iterator, Object the element to look for element) Check whether the given Iterator contains the given element.
public static boolean	Returns: `true` if found, `false` otherwise contains(Enumeration<?> the Enumeration to check enumeration, Object the element to look for element) Check whether the given Enumeration contains the given element.
public static boolean	Returns: whether any of the candidates has been found containsAny(Collection<?> the source Collection source, Collection<?> the candidates to search for candidates) Return `true` if any element in '`candidates`' is contained in '`source`'; otherwise returns `false`.
public static boolean	Returns: `true` if found, `false` otherwise containsInstance(Collection<?> the Collection to check collection, Object the element to look for element) Check whether the given Collection contains the given element instance.
public static Class<?>	Returns: the common element type, or `null` if no clear common type has been found (or the collection was empty) findCommonElementType(Collection<?> the Collection to check collection) Find the common element type of the given Collection, if any.
public static <E> E	Returns: the first present object, or `null` if not found findFirstMatch(Collection<?> the source Collection source, Collection<E> the candidates to search for candidates) Return the first element in '`candidates`' that is contained in '`source`'.
public static <T> T	Returns: a value of the given type found if there is a clear match, or `null` if none or more than one such value found findValueOfType(Collection<?> the Collection to search collection, Class<T> the type to look for type) Find a single value of the given type in the given Collection.
public static Object	Returns: a value of one of the given types found if there is a clear match, or `null` if none or more than one such value found findValueOfType(Collection<?> the collection to search collection, Class<?>[] the types to look for, in prioritized order types) Find a single value of one of the given types in the given Collection: searching the Collection for a value of the first type, then searching for a value of the second type, etc.
public static <T> T	Returns: the first element, or `null` if none firstElement(Set<T> the Set to check (may be `null` or empty) set) Retrieve the first element of the given Set, using `SortedSet#first()` or otherwise using the iterator.
public static <T> T	Returns: the first element, or `null` if none firstElement(List<T> the List to check (may be `null` or empty) list) Retrieve the first element of the given List, accessing the zero index.
public static boolean	Returns: `true` if the collection contains a single reference or multiple references to the same instance, `false` otherwise hasUniqueObject(Collection<?> the Collection to check collection) Determine whether the given Collection only contains a single unique object.
public static boolean	Returns: whether the given Collection is empty isEmpty(Collection<?> the Collection to check collection) Return `true` if the supplied Collection is `null` or empty.
public static boolean	Returns: whether the given Map is empty isEmpty(Map<?, ?> the Map to check map) Return `true` if the supplied Map is `null` or empty.
public static <T> T	Returns: the last element, or `null` if none lastElement(Set<T> the Set to check (may be `null` or empty) set) Retrieve the last element of the given Set, using `SortedSet#last()` or otherwise iterating over all elements (assuming a linked set).
public static <T> T	Returns: the last element, or `null` if none lastElement(List<T> the List to check (may be `null` or empty) list) Retrieve the last element of the given List, accessing the highest index.
public static <E> void	mergeArrayIntoCollection(Object the array to merge (may be `null`) array, Collection<E> the target Collection to merge the array into collection) Merge the given array into the given Collection.
public static <K, V> void	mergePropertiesIntoMap(Properties the Properties instance to merge (may be `null`) props, Map<K, V> the target Map to merge the properties into map) Merge the given Properties instance into the given Map, copying all properties (key-value pairs) over.
public static <K, V> HashMap<K, V>	newHashMap(int the expected number of elements (with a corresponding capacity to be derived so that no resize/rehash operations are needed) expectedSize) Instantiate a new `HashMap` with an initial capacity that can accommodate the specified number of elements without any immediate resize/rehash operations to be expected.
public static <K, V> LinkedHashMap<K, V>	newLinkedHashMap(int the expected number of elements (with a corresponding capacity to be derived so that no resize/rehash operations are needed) expectedSize) Instantiate a new `LinkedHashMap` with an initial capacity that can accommodate the specified number of elements without any immediate resize/rehash operations to be expected.
public static <A, E extends A> A[]	toArray(Enumeration<E> enumeration, A[] array) Marshal the elements from the given enumeration into an array of the given type.
public static <E> Iterator<E>	Returns: the adapted `Iterator` toIterator(Enumeration<E> the original `Enumeration` enumeration) Adapt an `Enumeration` to an `Iterator`.
public static <K, V> MultiValueMap<K, V>	Returns: the adapted multi-value map (wrapping the original map) toMultiValueMap(Map<K, List<V>> the original map targetMap) Adapt a `Map<K, List<V>>` to an `MultiValueMap<K, V>`.
public static <K, V> MultiValueMap<K, V>	Returns: an unmodifiable view of the specified multi-value map unmodifiableMultiValueMap(MultiValueMap<? extends K, ? extends V> the map for which an unmodifiable view is to be returned. targetMap) Return an unmodifiable view of the specified multi-value map.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

DEFAULT_LOAD_FACTOR	back to summary
pack-priv static final float DEFAULT_LOAD_FACTOR Default load factor for `HashMap`/`LinkedHashMap` variants. See Also `newHashMap(int)`, `newLinkedHashMap(int)`

CollectionUtils	back to summary
public CollectionUtils()

Method Detail

arrayToList back to summary

arrayToList	back to summary
public static List<?> arrayToList(Object source) Convert the supplied array into a List. A primitive array gets converted into a List of the appropriate wrapper type. Note Generally prefer the standard `Arrays#asList` method. This `arrayToList` method is just meant to deal with an incoming Object value that might be an `Object[]` or a primitive array at runtime. A `null` source value will be converted to an empty List. Parameters source:Object the (potentially primitive) array Returns:List<?> the converted List result See Also `ObjectUtils#toObjectArray(Object)`, `Arrays#asList(Object[])`

public static List<?> arrayToList(Object source)

Convert the supplied array into a List. A primitive array gets converted into a List of the appropriate wrapper type.

Note

Generally prefer the standard Arrays#asList method. This arrayToList method is just meant to deal with an incoming Object value that might be an Object[] or a primitive array at runtime.

A null source value will be converted to an empty List.

Parameters

source:Object: the (potentially primitive) array

Returns:List<?>

the converted List result

computeMapInitialCapacity	back to summary
private static int computeMapInitialCapacity(int expectedSize)

contains back to summary

contains	back to summary
public static boolean contains(Iterator<?> iterator, Object element) Check whether the given Iterator contains the given element. Parameters iterator:Iterator<?> the Iterator to check element:Object the element to look for Returns:boolean `true` if found, `false` otherwise

public static boolean contains(Iterator<?> iterator, Object element)

Check whether the given Iterator contains the given element.

Parameters

iterator:Iterator<?>: the Iterator to check
element:Object: the element to look for

Returns:boolean

true if found, false otherwise

contains back to summary

contains	back to summary
public static boolean contains(Enumeration<?> enumeration, Object element) Check whether the given Enumeration contains the given element. Parameters enumeration:Enumeration<?> the Enumeration to check element:Object the element to look for Returns:boolean `true` if found, `false` otherwise

public static boolean contains(Enumeration<?> enumeration, Object element)

Check whether the given Enumeration contains the given element.

Parameters

enumeration:Enumeration<?>: the Enumeration to check
element:Object: the element to look for

Returns:boolean

true if found, false otherwise

containsAny back to summary

containsAny	back to summary
public static boolean containsAny(Collection<?> source, Collection<?> candidates) Return `true` if any element in '`candidates`' is contained in '`source`'; otherwise returns `false`. Parameters source:Collection<?> the source Collection candidates:Collection<?> the candidates to search for Returns:boolean whether any of the candidates has been found

public static boolean containsAny(Collection<?> source, Collection<?> candidates)

Return true if any element in 'candidates' is contained in 'source'; otherwise returns false.

Parameters

source:Collection<?>: the source Collection
candidates:Collection<?>: the candidates to search for

Returns:boolean

whether any of the candidates has been found

containsInstance back to summary

containsInstance	back to summary
public static boolean containsInstance(Collection<?> collection, Object element) Check whether the given Collection contains the given element instance. Enforces the given instance to be present, rather than returning `true` for an equal element as well. Parameters collection:Collection<?> the Collection to check element:Object the element to look for Returns:boolean `true` if found, `false` otherwise

public static boolean containsInstance(Collection<?> collection, Object element)

Check whether the given Collection contains the given element instance.

Enforces the given instance to be present, rather than returning true for an equal element as well.

Parameters

collection:Collection<?>: the Collection to check
element:Object: the element to look for

Returns:boolean

true if found, false otherwise

findCommonElementType back to summary

findCommonElementType	back to summary
public static Class<?> findCommonElementType(Collection<?> collection) Find the common element type of the given Collection, if any. Parameters collection:Collection<?> the Collection to check Returns:Class<?> the common element type, or `null` if no clear common type has been found (or the collection was empty) Annotations @Nullable

public static Class<?> findCommonElementType(Collection<?> collection)

Find the common element type of the given Collection, if any.

Parameters

collection:Collection<?>: the Collection to check

Returns:Class<?>

the common element type, or null if no clear common type has been found (or the collection was empty)

Annotations

@Nullable

findFirstMatch back to summary

findFirstMatch	back to summary
public static <E> E findFirstMatch(Collection<?> source, Collection<E> candidates) Return the first element in '`candidates`' that is contained in '`source`'. If no element in '`candidates`' is present in '`source`' returns `null`. Iteration order is `Collection` implementation specific. Parameters source:Collection<?> the source Collection candidates:Collection<E> the candidates to search for Returns:E the first present object, or `null` if not found Annotations @Nullable

public static <E> E findFirstMatch(Collection<?> source, Collection<E> candidates)

Return the first element in 'candidates' that is contained in 'source'. If no element in 'candidates' is present in 'source' returns null. Iteration order is Collection implementation specific.

Parameters

source:Collection<?>: the source Collection
candidates:Collection<E>: the candidates to search for

Returns:E

the first present object, or null if not found

Annotations

@Nullable

findValueOfType back to summary

findValueOfType	back to summary
public static <T> T findValueOfType(Collection<?> collection, Class<T> type) Find a single value of the given type in the given Collection. Parameters collection:Collection<?> the Collection to search type:Class<T> the type to look for Returns:T a value of the given type found if there is a clear match, or `null` if none or more than one such value found Annotations @SuppressWarnings:unchecked @Nullable

public static <T> T findValueOfType(Collection<?> collection, Class<T> type)

Find a single value of the given type in the given Collection.

Parameters

collection:Collection<?>: the Collection to search
type:Class<T>: the type to look for

Returns:T

a value of the given type found if there is a clear match, or null if none or more than one such value found

Annotations

@SuppressWarnings:unchecked
@Nullable

findValueOfType back to summary

findValueOfType	back to summary
public static Object findValueOfType(Collection<?> collection, Class<?>[] types) Find a single value of one of the given types in the given Collection: searching the Collection for a value of the first type, then searching for a value of the second type, etc. Parameters collection:Collection<?> the collection to search types:Class<?>[] the types to look for, in prioritized order Returns:Object a value of one of the given types found if there is a clear match, or `null` if none or more than one such value found Annotations @Nullable

public static Object findValueOfType(Collection<?> collection, Class<?>[] types)

Find a single value of one of the given types in the given Collection: searching the Collection for a value of the first type, then searching for a value of the second type, etc.

Parameters

collection:Collection<?>: the collection to search
types:Class<?>[]: the types to look for, in prioritized order

Returns:Object

a value of one of the given types found if there is a clear match, or null if none or more than one such value found

Annotations

@Nullable

firstElement back to summary

firstElement	back to summary
public static <T> T firstElement(Set<T> set) Retrieve the first element of the given Set, using `SortedSet#first()` or otherwise using the iterator. Parameters set:Set<T> the Set to check (may be `null` or empty) Returns:T the first element, or `null` if none Annotations @Nullable Since 5.2.3 See Also `SortedSet`, `LinkedHashMap#keySet()`, `java.util.LinkedHashSet`

public static <T> T firstElement(Set<T> set)

Retrieve the first element of the given Set, using SortedSet#first() or otherwise using the iterator.

Parameters

set:Set<T>: the Set to check (may be null or empty)

Returns:T

the first element, or null if none

Annotations

@Nullable

Since

5.2.3

firstElement back to summary

firstElement	back to summary
public static <T> T firstElement(List<T> list) Retrieve the first element of the given List, accessing the zero index. Parameters list:List<T> the List to check (may be `null` or empty) Returns:T the first element, or `null` if none Annotations @Nullable Since 5.2.3

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

Retrieve the first element of the given List, accessing the zero index.

Parameters

list:List<T>: the List to check (may be null or empty)

Returns:T

the first element, or null if none

Annotations

@Nullable

Since

5.2.3

hasUniqueObject back to summary

hasUniqueObject	back to summary
public static boolean hasUniqueObject(Collection<?> collection) Determine whether the given Collection only contains a single unique object. Parameters collection:Collection<?> the Collection to check Returns:boolean `true` if the collection contains a single reference or multiple references to the same instance, `false` otherwise

public static boolean hasUniqueObject(Collection<?> collection)

Determine whether the given Collection only contains a single unique object.

Parameters

collection:Collection<?>: the Collection to check

Returns:boolean

true if the collection contains a single reference or multiple references to the same instance, false otherwise

isEmpty back to summary

isEmpty	back to summary
public static boolean isEmpty(Collection<?> collection) Return `true` if the supplied Collection is `null` or empty. Otherwise, return `false`. Parameters collection:Collection<?> the Collection to check Returns:boolean whether the given Collection is empty

public static boolean isEmpty(Collection<?> collection)

Return true if the supplied Collection is null or empty. Otherwise, return false.

Parameters

collection:Collection<?>: the Collection to check

Returns:boolean

whether the given Collection is empty

isEmpty back to summary

isEmpty	back to summary
public static boolean isEmpty(Map<?, ?> map) Return `true` if the supplied Map is `null` or empty. Otherwise, return `false`. Parameters map:Map<?, ?> the Map to check Returns:boolean whether the given Map is empty

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

Return true if the supplied Map is null or empty. Otherwise, return false.

Parameters

map:Map<?, ?>: the Map to check

Returns:boolean

whether the given Map is empty

lastElement back to summary

lastElement	back to summary
public static <T> T lastElement(Set<T> set) Retrieve the last element of the given Set, using `SortedSet#last()` or otherwise iterating over all elements (assuming a linked set). Parameters set:Set<T> the Set to check (may be `null` or empty) Returns:T the last element, or `null` if none Annotations @Nullable Since 5.0.3 See Also `SortedSet`, `LinkedHashMap#keySet()`, `java.util.LinkedHashSet`

public static <T> T lastElement(Set<T> set)

Retrieve the last element of the given Set, using SortedSet#last() or otherwise iterating over all elements (assuming a linked set).

Parameters

set:Set<T>: the Set to check (may be null or empty)

Returns:T

the last element, or null if none

Annotations

@Nullable

Since

5.0.3

lastElement back to summary

lastElement	back to summary
public static <T> T lastElement(List<T> list) Retrieve the last element of the given List, accessing the highest index. Parameters list:List<T> the List to check (may be `null` or empty) Returns:T the last element, or `null` if none Annotations @Nullable Since 5.0.3

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

Retrieve the last element of the given List, accessing the highest index.

Parameters

list:List<T>: the List to check (may be null or empty)

Returns:T

the last element, or null if none

Annotations

@Nullable

Since

5.0.3

mergeArrayIntoCollection back to summary

mergeArrayIntoCollection	back to summary
public static <E> void mergeArrayIntoCollection(Object array, Collection<E> collection) Merge the given array into the given Collection. Parameters array:Object the array to merge (may be `null`) collection:Collection<E> the target Collection to merge the array into Annotations @SuppressWarnings:unchecked

public static <E> void mergeArrayIntoCollection(Object array, Collection<E> collection)

Merge the given array into the given Collection.

Parameters

array:Object: the array to merge (may be null)
collection:Collection<E>: the target Collection to merge the array into

Annotations

@SuppressWarnings:unchecked

mergePropertiesIntoMap back to summary

mergePropertiesIntoMap	back to summary
public static <K, V> void mergePropertiesIntoMap(Properties props, Map<K, V> map) Merge the given Properties instance into the given Map, copying all properties (key-value pairs) over. Uses `Properties.propertyNames()` to even catch default properties linked into the original Properties instance. Parameters props:Properties the Properties instance to merge (may be `null`) map:Map<K, V> the target Map to merge the properties into Annotations @SuppressWarnings:unchecked

public static <K, V> void mergePropertiesIntoMap(Properties props, Map<K, V> map)

Merge the given Properties instance into the given Map, copying all properties (key-value pairs) over.

Uses Properties.propertyNames() to even catch default properties linked into the original Properties instance.

Parameters

props:Properties: the Properties instance to merge (may be null)
map:Map<K, V>: the target Map to merge the properties into

Annotations

@SuppressWarnings:unchecked

newHashMap back to summary

newHashMap	back to summary
public static <K, V> HashMap<K, V> newHashMap(int expectedSize) Instantiate a new `HashMap` with an initial capacity that can accommodate the specified number of elements without any immediate resize/rehash operations to be expected. This differs from the regular `HashMap` constructor which takes an initial capacity relative to a load factor but is effectively aligned with the JDK's `java.util.concurrent.ConcurrentHashMap#ConcurrentHashMap(int)`. Parameters expectedSize:int the expected number of elements (with a corresponding capacity to be derived so that no resize/rehash operations are needed) Since 5.3 See Also `newLinkedHashMap(int)`

public static <K, V> HashMap<K, V> newHashMap(int expectedSize)

Instantiate a new HashMap with an initial capacity that can accommodate the specified number of elements without any immediate resize/rehash operations to be expected.

This differs from the regular HashMap constructor which takes an initial capacity relative to a load factor but is effectively aligned with the JDK's java.util.concurrent.ConcurrentHashMap#ConcurrentHashMap(int).

Parameters

expectedSize:int: the expected number of elements (with a corresponding capacity to be derived so that no resize/rehash operations are needed)

Since

5.3

See Also

newLinkedHashMap(int)

newLinkedHashMap back to summary

newLinkedHashMap	back to summary
public static <K, V> LinkedHashMap<K, V> newLinkedHashMap(int expectedSize) Instantiate a new `LinkedHashMap` with an initial capacity that can accommodate the specified number of elements without any immediate resize/rehash operations to be expected. This differs from the regular `LinkedHashMap` constructor which takes an initial capacity relative to a load factor but is aligned with Spring's own `LinkedCaseInsensitiveMap` and `LinkedMultiValueMap` constructor semantics as of 5.3. Parameters expectedSize:int the expected number of elements (with a corresponding capacity to be derived so that no resize/rehash operations are needed) Since 5.3 See Also `newHashMap(int)`

public static <K, V> LinkedHashMap<K, V> newLinkedHashMap(int expectedSize)

Instantiate a new LinkedHashMap with an initial capacity that can accommodate the specified number of elements without any immediate resize/rehash operations to be expected.

This differs from the regular LinkedHashMap constructor which takes an initial capacity relative to a load factor but is aligned with Spring's own LinkedCaseInsensitiveMap and LinkedMultiValueMap constructor semantics as of 5.3.

Parameters

expectedSize:int: the expected number of elements (with a corresponding capacity to be derived so that no resize/rehash operations are needed)

Since

5.3

See Also

newHashMap(int)

toArray	back to summary
public static <A, E extends A> A[] toArray(Enumeration<E> enumeration, A[] array) Marshal the elements from the given enumeration into an array of the given type. Enumeration elements must be assignable to the type of the given array. The array returned will be a different instance than the array given.

toIterator back to summary

toIterator	back to summary
public static <E> Iterator<E> toIterator(Enumeration<E> enumeration) Adapt an `Enumeration` to an `Iterator`. Parameters enumeration:Enumeration<E> the original `Enumeration` Returns:Iterator<E> the adapted `Iterator`

public static <E> Iterator<E> toIterator(Enumeration<E> enumeration)

Adapt an Enumeration to an Iterator.

Parameters

enumeration:Enumeration<E>: the original Enumeration

Returns:Iterator<E>

the adapted Iterator

toMultiValueMap back to summary

toMultiValueMap	back to summary
public static <K, V> MultiValueMap<K, V> toMultiValueMap(Map<K, List<V>> targetMap) Adapt a `Map<K, List<V>>` to an `MultiValueMap<K, V>`. Parameters targetMap:Map<K, List<V>> the original map Returns:MultiValueMap<K, V> the adapted multi-value map (wrapping the original map) Since 3.1

public static <K, V> MultiValueMap<K, V> toMultiValueMap(Map<K, List<V>> targetMap)

Adapt a Map<K, List<V>> to an MultiValueMap<K, V>.

Parameters

targetMap:Map<K, List<V>>: the original map

Returns:MultiValueMap<K, V>

the adapted multi-value map (wrapping the original map)

Since

3.1

unmodifiableMultiValueMap	back to summary
public static <K, V> MultiValueMap<K, V> unmodifiableMultiValueMap(MultiValueMap<? extends K, ? extends V> targetMap) Return an unmodifiable view of the specified multi-value map. Parameters targetMap:MultiValueMap<? extends K, ? extends V> the map for which an unmodifiable view is to be returned. Returns:MultiValueMap<K, V> an unmodifiable view of the specified multi-value map Annotations @SuppressWarnings:unchecked Since 3.1

unmodifiableMultiValueMap

back to summary

public static <K, V> MultiValueMap<K, V> unmodifiableMultiValueMap(MultiValueMap<? extends K, ? extends V> targetMap)

Return an unmodifiable view of the specified multi-value map.

Parameters

targetMap:MultiValueMap<? extends K, ? extends V>: the map for which an unmodifiable view is to be returned.

Returns:MultiValueMap<K, V>

an unmodifiable view of the specified multi-value map

Annotations

@SuppressWarnings:unchecked

Since

3.1

public abstract Class CollectionUtils

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail