java.lang.Object
org.klojang.util.CollectionMethods
Methods extending the Java Collection framework.
-
Method Summary
Modifier and TypeMethodDescriptionstatic <T,
U> List <U> collectionToList
(Collection<? extends T> src, Function<? super T, ? extends U> converter) Shortcut method.static <K,
V> Map <K, V> collectionToMap
(Collection<V> src, Function<? super V, ? extends K> keyExtractor) Shortcut method.static <T,
U> Set <U> collectionToSet
(Collection<? extends T> src, Function<? super T, ? extends U> converter) Shortcut method.static <K0,
V0, K1, V1>
Map<K1, V1> deepFreeze
(Map<K0, V0> src, Function<Map.Entry<K0, V0>, Map.Entry<K1, V1>> entryConverter) Returns an unmodifiableMap
where both keys and values of the inputMap
have been converted using the specifiedFunction
.static <T> T
findFirst
(Collection<T> collection, Predicate<? super T> test) Shortcut method.freeze
(List<? extends T> src, org.klojang.check.fallible.FallibleFunction<? super T, ? extends U, E> converter) Returns an unmodifiableList
containing the values that result from applying the specified function to the source list's elements.static <K,
V0, V1>
Map<K, V1> freeze
(Map<K, V0> src, BiFunction<? super K, ? super V0, ? extends V1> valueConverter) Returns an unmodifiableMap
where the values of the inputMap
have been converted using the specifiedBiFunction
.static <K,
V0, V1>
Map<K, V1> Returns an unmodifiableMap
where the values of the inputMap
have been converted using the specifiedFunction
.freeze
(Set<? extends T> src, org.klojang.check.fallible.FallibleFunction<? super T, ? extends U, E> converter) Returns an unmodifiableSet
containing the values that result from applying the specified function to the source set's elements.static <T> String
implode
(Collection<T> collection) PHP-style implode method, concatenating the collection elements using ", " (comma-space) as separator.static <T> String
implode
(Collection<T> collection, int limit) PHP-style implode method, concatenating at mostlimit
collection elements using ", " (comma-space) as separator.static <T> String
implode
(Collection<T> collection, String separator) PHP-style implode method, concatenating the collection elements with the specified separator.static <T> String
implode
(Collection<T> collection, String separator, int limit) PHP-style implode method, concatenating at mostlimit
collection elements using the specified separator.static <T> String
implode
(Collection<T> collection, Function<T, String> stringifier) PHP-style implode method, concatenating at mostlimit
collection elements using ", " (comma-space) as separator.static <T> String
implode
(Collection<T> collection, Function<T, String> stringifier, String separator) PHP-style implode method, concatenating at mostlimit
collection elements using ", " (comma-space) as separator.static <T> String
implode
(Collection<T> collection, Function<T, String> stringifier, String separator, int from, int to) PHP-style implode method.static <E> List
<E> initializeList
(int size, E initVal) Returns a fixed-size, mutableList
with all elements initialized to the specified value.static <E> List
<E> initializeList
(int size, Supplier<E> initValSupplier) Returns a fixed-size, mutableList
with all elements initialized to values provided by aSupplier
.static <K,
V> Map <K, V> initializeMap
(Object... kvPairs) Returns aHashMap
initialized with the specified key-value pairs.static boolean
isNullRepellent
(Collection<?> c) Returnstrue
if the provided collection is a null-repellent collection like those obtained viaList.of(...)
andSet.of(...)
.static List
<?> Converts the specified value to aList
.static <E> List
<E> newArrayList
(int capacity, E... initialValues) Returns a newArrayList
initialized with the specified values.static <K,
V> Map <K, V> newHashMap
(int size, Class<K> keyClass, Class<V> valueClass, Object... kvPairs) Returns aHashMap
initialized with the specified key-value pairs.saturatedEnumMap
(Class<K> enumClass, V... values) Returns anEnumMap
with all enum constants set to non-null values.static <T> List
<T> Returns a sublist of the provided list starting with elementfrom
and containing at mostlength
elements.static <K,
V> Map <V, K> Returns a newMap
where keys and values of the input map have traded places.static <K,
V> Map <V, K> Returns a newMap
where keys and values of the input map have traded places.static <K,
V> Map <V, K> swapAndFreeze
(Map<K, V> map) Returns an unmodifiableMap
where keys and values of the input map have traded places.
-
Method Details
-
listify
Converts the specified value to a
List
.- if the value already is a
List
, it is returned as-is. - if the value is a
Collection
, it is converted to anArrayList
using the standard Collections Framework conversion mechanism — by passing it to the constructor ofArrayList
- if the value is an instance of
Object[]
, it is converted usingArrays.asList
- if the value is an array of a primitive type, it is converted using
ArrayMethods.asList
- in any other case the value is converted using
Collections.singletonList
In other words, this method takes the shortest route to turn the value into a
List
and there is no guarantee about what type ofList
you get.- Parameters:
value
- the value to convert- Returns:
- the value converted to a
List
- See Also:
- if the value already is a
-
initializeList
Returns a fixed-size, mutableList
with all elements initialized to the specified value. The initialization value must not benull
.- Type Parameters:
E
- the type of the elements- Parameters:
size
- The desired size of theList
initVal
- The initial value of the list elements (must not benull
)- Returns:
- a fixed-size, mutable, initialized
List
-
initializeList
Returns a fixed-size, mutableList
with all elements initialized to values provided by aSupplier
.- Type Parameters:
E
- the type of the elements- Parameters:
size
- The desired size of theList
initValSupplier
- The supplier of the initial values- Returns:
- a fixed-size, mutable, initialized
List
-
newArrayList
Returns a newArrayList
initialized with the specified values. The values are allowed to benull
. The initial capacity will always be at least the length of theinitialValues
array, whatever the value of thecapacity
argument.- Type Parameters:
E
- the type of the list elements- Parameters:
capacity
- The initial capacity of the listinitialValues
- The values to add to the list- Returns:
- a new
ArrayList
initialized with the specified values.
-
initializeMap
Returns aHashMap
initialized with the specified key-value pairs. Both keys and values are allowed to benull
. The map will be tightly sized to the number of key-value pairs.- Type Parameters:
K
- the type of the keysV
- the type of the values- Parameters:
kvPairs
- An array alternating between keys and values- Returns:
- a
HashMap
initialized with the specified key-value pairs
-
newHashMap
public static <K,V> Map<K,V> newHashMap(int size, Class<K> keyClass, Class<V> valueClass, Object... kvPairs) Returns aHashMap
initialized with the specified key-value pairs. Both keys and values are allowed to benull
. Keys will be checked for uniqueness.- Type Parameters:
K
- the type of the keysV
- the type of the values- Parameters:
size
- The expected number of map entries. No rehashing will take place until that number is reached. If you specify a number less than the number of key-value pairs (half the length of the varargs array), it will be taken as a multiplier. For example, 2 would mean that you expect the map to grow to about twice the specified number of key-value pairs.keyClass
- The class of the keysvalueClass
- The class of the valueskvPairs
- An array alternating between keys and values- Returns:
- a
HashMap
initialized with the specified key-value pairs
-
saturatedEnumMap
public static <K extends Enum<K>,V> EnumMap<K,V> saturatedEnumMap(Class<K> enumClass, V... values) throws IllegalArgumentException Returns anEnumMap
with all enum constants set to non-null values. The number of values must exactly equal the number of enum constants, and they are assigned according to ordinal number. This method throws anIllegalArgumentException
if the number of values is not exactly equal to the number of constants in the enum class, or if any of the values is null.- Type Parameters:
K
- the key typeV
- the value type- Parameters:
enumClass
- The enum classvalues
- The values to associate with the enum constants- Returns:
- a fully-occupied
EnumMap
with no null-values - Throws:
IllegalArgumentException
- ifenumClass
orValues
is null, or if any of the provided values is null, or is the number of values is not exactly equals to the number of enum constants
-
sublist
Returns a sublist of the provided list starting with elementfrom
and containing at mostlength
elements. The returned list is backed by the original list, so changing its elements will affect the original list as well. Ifoffset
is negative, it is taken relative to the end of the list. Iflength
is negative, the sublist is taken in the opposite direction — that is, the element atoffset
now becomes the last element of the sublist.- Type Parameters:
T
- the type of the elements- Parameters:
list
- theList
to extract a sublist fromoffset
- the start index if the sublist (however, see above)length
- the length of the sublist- Returns:
- a sublist of the provided list
-
swap
Returns a newMap
where keys and values of the input map have traded places. The specifiedMap
must not contain duplicate values. AnIllegalArgumentException
is thrown if it does. The returned map is tightly sized, but modifiable.- Type Parameters:
K
- the type of the keys in the original map, and of the values in the returned mapV
- the type of the values in the original map, and of the keys in the returned map- Parameters:
map
- The source map- Returns:
- a new
Map
where keys and values are swapped
-
swap
public static <K,V> Map<V,K> swap(Map<K, V> map, Supplier<? extends Map<V, throws org.klojang.check.aux.DuplicateValueExceptionK>> mapFactory) Returns a newMap
where keys and values of the input map have traded places. The specifiedMap
must not contain duplicate values. ADuplicateValueException
is thrown if it does.null
keys and values are allowed, however.- Type Parameters:
K
- the type of the keys in the original map, and of the values in the returned mapV
- the type of the values in the original map, and of the keys in the returned map- Parameters:
map
- The source mapmapFactory
- A supplier of aMap
instance- Returns:
- a new
Map
where keys and values are swapped - Throws:
org.klojang.check.aux.DuplicateValueException
- if the map contains duplicate values
-
swapAndFreeze
Returns an unmodifiableMap
where keys and values of the input map have traded places. The specifiedMap
must not containnull
keys,null
values or duplicate values. AnIllegalArgumentException
is thrown if it does.- Type Parameters:
K
- the type of the keys in the original map, and of the values in the returned mapV
- the type of the values in the original map, and of the keys in the returned map- Parameters:
map
- The source map- Returns:
- a new
Map
where keys and values are swapped
-
freeze
public static <K,V0, Map<K,V1> V1> freeze(Map<K, V0> src, Function<? super V0, ? extends V1> valueConverter) Returns an unmodifiableMap
where the values of the inputMap
have been converted using the specifiedFunction
. The specifiedMap
must not containnull
keys,null
values or duplicate values. AnIllegalArgumentException
is thrown if it does.- Type Parameters:
K
- the type of the keys of the input and outputMap
V0
- the type of the values of the inputMap
V1
- the type of the values of the outputMap
- Parameters:
src
- the inputMap
valueConverter
- AFunction
that converts the values of the inputMap
- Returns:
- an unmodifiable
Map
where the values of the inputMap
have been converted using the specifiedFunction
-
freeze
public static <K,V0, Map<K,V1> V1> freeze(Map<K, V0> src, BiFunction<? super K, ? super V0, ? extends V1> valueConverter) Returns an unmodifiableMap
where the values of the inputMap
have been converted using the specifiedBiFunction
. This method passes both the key and the value to the converter function so you can make the conversion key-dependent, or so you can mention the key if the conversion fails.- Type Parameters:
K
- the type of the keys of the input and outputMap
V0
- the type of the values of the inputMap
V1
- the type of the values of the outputMap
- Parameters:
src
- the inputMap
valueConverter
- AFunction
that converts the values of the inputMap
- Returns:
- an unmodifiable
Map
where the values of the inputMap
have been converted using the specifiedFunction
-
deepFreeze
public static <K0,V0, Map<K1,K1, V1> V1> deepFreeze(Map<K0, V0> src, Function<Map.Entry<K0, V0>, Map.Entry<K1, V1>> entryConverter) Returns an unmodifiableMap
where both keys and values of the inputMap
have been converted using the specifiedFunction
. The output map may be smaller than the input map if the conversion function does not generate unique keys.- Type Parameters:
K0
- The type of the keys in the input mapV0
- the type of the values in the input mapK1
- the type of the keys in the output mapV1
- the type of the values in the output map- Parameters:
src
- the inputMap
entryConverter
- aFunction
that produces a new entry from the original entry- Returns:
- an unmodifiable
Map
where the values of the inputMap
have been converted using the specifiedFunction
-
freeze
public static <T,U, List<U> freezeE extends Throwable> (List<? extends T> src, org.klojang.check.fallible.FallibleFunction<? super T, ? extends U, throws EE> converter) Returns an unmodifiableList
containing the values that result from applying the specified function to the source list's elements. The conversion function is allowed to throw a checked exception.- Type Parameters:
T
- the type of the elements in the source listU
- the type of the elements in the returned listE
- the type of exception thrown if the conversion fails- Parameters:
src
- the source listconverter
- the conversion function- Returns:
- an unmodifiable
List
containing the values that result from applying the specified function to the source list's elements - Throws:
E
- the exception potentially being thrown from the conversion function
-
freeze
public static <T,U, Set<U> freezeE extends Throwable> (Set<? extends T> src, org.klojang.check.fallible.FallibleFunction<? super T, ? extends U, throws EE> converter) Returns an unmodifiableSet
containing the values that result from applying the specified function to the source set's elements. The conversion function is allowed to throw a checked exception.- Type Parameters:
T
- the type of the elements in the source setU
- the type of the elements in the returned setE
- the type of exception thrown if the conversion fails- Parameters:
src
- the source setconverter
- the conversion function- Returns:
- an unmodifiable
Set
containing the values that result from applying the - Throws:
E
- the exception potentially being thrown from the conversion function
-
collectionToList
public static <T,U> List<U> collectionToList(Collection<? extends T> src, Function<? super T, ? extends U> converter) Shortcut method. Returns an unmodifiable list using:src.stream().map(converter).collect(toUnmodifiableList());
- Type Parameters:
T
- the type of the elements in the source setU
- the type of the elements in the returned list- Parameters:
src
- the source listconverter
- the conversion function- Returns:
- an unmodifiable
List
containing the values that result from applying the specified function to the source collection's elements
-
collectionToSet
public static <T,U> Set<U> collectionToSet(Collection<? extends T> src, Function<? super T, ? extends U> converter) Shortcut method. Returns an unmodifiable set using:src.stream().map(converter).collect(toUnmodifiableSet());
- Type Parameters:
T
- the type of the elements in the source setU
- the type of the elements in the returned list- Parameters:
src
- the source listconverter
- the conversion function- Returns:
- an unmodifiable
Set
containing the values that result from applying the specified function to the source collection's elements
-
collectionToMap
public static <K,V> Map<K,V> collectionToMap(Collection<V> src, Function<? super V, ? extends K> keyExtractor) Shortcut method. Returns an unmodifiable map from the specified collection using:src.stream().collect(toUnmodifiableMap(keyExtractor, Function.identity()))
- Type Parameters:
K
- the type of the keysV
- the type of the values and the list elements- Parameters:
src
- theList
to convert.keyExtractor
- The key-extraction function- Returns:
- an unmodifiable
Map
-
findFirst
Shortcut method. Returns the first element that passes the specified test, or elsenull
. Shortcut forcollection.stream().filter(test).findFirst().orElse(null)
.- Type Parameters:
T
- the type of the elements in the collection- Parameters:
collection
- the collection to searchtest
- the test- Returns:
- the first element that passes the specified test, or else
null
-
implode
PHP-style implode method, concatenating the collection elements using ", " (comma-space) as separator.- Type Parameters:
T
- the type of the elements- Parameters:
collection
- the collection to implode- Returns:
- a concatenation of the elements in the collection.
- See Also:
-
implode
PHP-style implode method, concatenating the collection elements with the specified separator.- Type Parameters:
T
- the type of the elements- Parameters:
collection
- the collection to implodeseparator
- the string used to separate the elements- Returns:
- a concatenation of the elements in the collection.
- See Also:
-
implode
PHP-style implode method, concatenating at mostlimit
collection elements using ", " (comma-space) as separator.- Type Parameters:
T
- the type of the elements- Parameters:
collection
- the collection to implodelimit
- The maximum number of elements to collect. Specify -1 for no maximum. Specifying a number greater than the length of the collection is OK. It will be clamped to the collection length.- Returns:
- a concatenation of the elements in the collection.
- See Also:
-
implode
PHP-style implode method, concatenating at mostlimit
collection elements using ", " (comma-space) as separator.- Type Parameters:
T
- the type of the elements- Parameters:
collection
- the collection to implodestringifier
- aFunction
that converts the collection elements to strings- Returns:
- a concatenation of the elements in the collection.
- See Also:
-
implode
public static <T> String implode(Collection<T> collection, Function<T, String> stringifier, String separator) PHP-style implode method, concatenating at mostlimit
collection elements using ", " (comma-space) as separator.- Type Parameters:
T
- the type of the elements- Parameters:
collection
- the collection to implodestringifier
- aFunction
that converts the collection elements to stringsseparator
- the string used to separate the elements- Returns:
- a concatenation of the elements in the collection.
- See Also:
-
implode
PHP-style implode method, concatenating at mostlimit
collection elements using the specified separator.- Type Parameters:
T
- the type of the elements- Parameters:
collection
- the collection to implodeseparator
- the string used to separate the elementslimit
- The maximum number of elements to collect. Specify -1 for no maximum. Specifying a number greater than the length of the collection is OK. It will be clamped to the collection length.- Returns:
- a concatenation of the elements in the collection.
- See Also:
-
implode
public static <T> String implode(Collection<T> collection, Function<T, String> stringifier, String separator, int from, int to) PHP-style implode method.- Type Parameters:
T
- the type of the elements- Parameters:
collection
- the collection to implodestringifier
- aFunction
that converts the collection elements to stringsseparator
- the string used to separate the elementsfrom
- the index of the element to begin the concatenation with (inclusive)to
- the index of the element to end the concatenation with (exclusive). The specified number will be clamped tocollection.size()
(i.e. it's OK to specify a number greater thancollection.size()
). You can specify -1 as a shorthand forcollection.size()
.- Returns:
- a concatenation of the elements in the collection.
- See Also:
-
isNullRepellent
Returnstrue
if the provided collection is a null-repellent collection like those obtained viaList.of(...)
andSet.of(...)
. Note that if this method returnsfalse
, it does not mean that the collection is not null-repellent. The only sure thing is that if this method returnstrue
, the collection is guaranteed not to containnull
values.- Parameters:
c
- the collection to inspect- Returns:
true
if the provided collection is a null-repellent collection
-