de.ipcon.tools

Class CollectionTools

java.lang.Object

de.ipcon.tools.CollectionTools

public final class CollectionTools
extends java.lang.Object

utility class that provides helper methods for working with collections

Constructor Summary

Constructors

Constructor and Description
CollectionTools()

Method Summary

Modifier and Type	Method and Description
static <T> java.util.List<T>	asImmutable(java.util.List<T> l) Returns an immutable copy of the provided list.
static int	countNonNullValues(java.util.Collection<?> c) Returns the number of non-null values in the passed Collection or zero if null was passed.
static <T> java.util.Collection<T>	filterNull(java.util.Collection<T> c) Returns a new collection (ArrayList), containing only the non-null values of the passed Collection or an empty Collection if null was passed.
static <T> T	firstElement(java.lang.Iterable<T> iterable) Returns the first element (as determined by the default iterator) of the passed iterable or null if it is null or empty.
static <T> T	firstElement(java.lang.Iterable<T> iterable, boolean returnNullIfNullOrEmpty) Returns the first element (as determined by the default iterator) of the passed iterable or null if it is null or empty and returnNullIfNullOrEmpty was passed as true.
static <T> T	getOnlyElement(java.lang.Iterable<T> iterable) Returns the single element contained in iterable.
static <T> T	getOnlyElement(java.lang.Iterable<T> iterable, boolean returnNullIfNullOrEmpty) Returns the single element contained in iterable.
static <T> T	getOnlyElement(java.lang.Iterable<T> iterable, boolean returnNullIfNullOrEmpty, java.util.function.Supplier<? extends java.lang.RuntimeException> exceptionSupplier) Returns the single element contained in iterable.
static <T> T	getOnlyElementInternal(java.lang.Iterable<T> iterable, boolean returnNullIfNullOrEmpty, java.util.function.Supplier<? extends java.lang.RuntimeException> exceptionSupplier) Internal method for getting the single element contained in iterable.
static void	removeNullValues(java.util.Collection<?> c) Modifies the passed Collection and removes all null values from it.
static <R> java.util.stream.Collector<R,?,R>	toOnlyElement() Returns a Collector that produces the only element.
static <R> java.util.stream.Collector<R,?,R>	toOnlyElement(boolean returnNullIfNullOrEmpty) Returns a Collector that produces the only element.
static <R> java.util.stream.Collector<R,?,R>	toOnlyElement(boolean returnNullIfNullOrEmpty, java.util.function.Supplier<? extends java.lang.RuntimeException> exceptionSupplier) Returns a Collector that produces the only element.
static <T> java.util.Set<T>	toUnmodifiableSet(T[] data) Returns a new immutable Set containing the elements from the given array.

Methods inherited from class java.lang.Object

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

Constructor Detail

CollectionTools

public CollectionTools()

Method Detail

firstElement

public static final <T> T firstElement(java.lang.Iterable<T> iterable)

Returns the first element (as determined by the default iterator) of the passed iterable or null if it is null or empty.

Parameters:

iterable - the Iterable to inspect

Returns:

the first value from the iterable or null if it is null or empty

firstElement

public static final <T> T firstElement(java.lang.Iterable<T> iterable,
                                       boolean returnNullIfNullOrEmpty)

Returns the first element (as determined by the default iterator) of the passed iterable or null if it is null or empty and returnNullIfNullOrEmpty was passed as true.

Parameters:

iterable - the Iterable to inspect

returnNullIfNullOrEmpty - a boolean specifying if we should produce a null value for a passed null or empty Iterable, otherwise an IllegalArgumentException will be thrown

Returns:

the first value from the iterable or null if it is null or empty and returnNullIfNullOrEmpty was passed as true

Throws:

java.util.NoSuchElementException - if the iterable is null or empty and returnNullIfNullOrEmpty was passed as false

toOnlyElement

public static final <R> java.util.stream.Collector<R,?,R> toOnlyElement()

Returns a Collector that produces the only element. Produces a null value for empty or null Collections. Usage example with streams: l.stream().collect(CollectionTools.toOnlyElement())

Returns:

A Collector that produces the only element or a null value for empty or null Collections.

toOnlyElement

public static final <R> java.util.stream.Collector<R,?,R> toOnlyElement(boolean returnNullIfNullOrEmpty)

Returns a Collector that produces the only element. Usage example with streams: l.stream().collect(CollectionTools.toOnlyElement())

Parameters:

returnNullIfNullOrEmpty - A boolean specifying if we should produce a null value for empty or null Collections; otherwise, a NoSuchElementException will be thrown.

Returns:

A Collector that produces the only element.

toOnlyElement

public static final <R> java.util.stream.Collector<R,?,R> toOnlyElement(boolean returnNullIfNullOrEmpty,
                                                                        java.util.function.Supplier<? extends java.lang.RuntimeException> exceptionSupplier)

Returns a Collector that produces the only element. Usage example with streams: l.stream().collect(CollectionTools.toOnlyElement())

Parameters:

returnNullIfNullOrEmpty - A boolean specifying if we should produce a null value for empty or null Collections; otherwise, a NoSuchElementException will be thrown.

exceptionSupplier - A Supplier that returns a RuntimeException to throw instead of the default IllegalArgumentException.

Returns:

A Collector that produces the only element.

Throws:

java.util.NoSuchElementException - If the Collection is empty and returnNullIfNullOrEmpty was passed as false.

java.lang.IllegalArgumentException - If the Collection contains multiple elements. The state of the underlying iterator is unspecified.

java.lang.RuntimeException - If the Collection contains multiple elements and an exceptionSupplier was passed. The state of the underlying iterator is unspecified.

getOnlyElement

public static final <T> T getOnlyElement(java.lang.Iterable<T> iterable)

Returns the single element contained in iterable.

Parameters:

iterable - The Iterable to inspect.

Returns:

The single element contained in iterable.

Throws:

java.util.NoSuchElementException - If the iterable is empty.

java.lang.IllegalArgumentException - If the iterable contains multiple elements. The state of the iterator is unspecified.

getOnlyElement

public static final <T> T getOnlyElement(java.lang.Iterable<T> iterable,
                                         boolean returnNullIfNullOrEmpty)

Returns the single element contained in iterable.

Parameters:

iterable - The Iterable to inspect.

returnNullIfNullOrEmpty - A boolean specifying if we should return null in case the passed Iterable is empty or null; otherwise, a NoSuchElementException will be thrown.

Returns:

The single element contained in iterable.

Throws:

java.util.NoSuchElementException - If the iterable is empty and returnNullIfNullOrEmpty was passed as false.

java.lang.IllegalArgumentException - If the iterable contains multiple elements. The state of the iterator is unspecified.

getOnlyElement

public static final <T> T getOnlyElement(java.lang.Iterable<T> iterable,
                                         boolean returnNullIfNullOrEmpty,
                                         java.util.function.Supplier<? extends java.lang.RuntimeException> exceptionSupplier)

Returns the single element contained in iterable.

Parameters:

iterable - The Iterable to inspect.

returnNullIfNullOrEmpty - A boolean specifying if we should return null in case the passed Iterable is empty or null; otherwise, a NoSuchElementException will be thrown.

exceptionSupplier - A Supplier that returns a RuntimeException to throw instead of the default IllegalArgumentException.

Returns:

The single element contained in iterable.

Throws:

java.util.NoSuchElementException - If the iterable is empty and returnNullIfNullOrEmpty was passed as false.

java.lang.IllegalArgumentException - If the iterable contains multiple elements. The state of the iterator is unspecified.

java.lang.RuntimeException - If the iterable contains multiple elements and an exceptionSupplier was passed. The state of the iterator is unspecified.

getOnlyElementInternal

public static final <T> T getOnlyElementInternal(java.lang.Iterable<T> iterable,
                                                 boolean returnNullIfNullOrEmpty,
                                                 java.util.function.Supplier<? extends java.lang.RuntimeException> exceptionSupplier)

Internal method for getting the single element contained in iterable.

Parameters:

iterable - The Iterable to inspect.

returnNullIfNullOrEmpty - A boolean specifying if we should return null in case the passed Iterable is empty or null; otherwise, a NoSuchElementException will be thrown.

exceptionSupplier - A Supplier that returns a RuntimeException to throw instead of the default IllegalArgumentException.

Returns:

The single element contained in iterable.

Throws:

java.util.NoSuchElementException - If the iterable is empty and returnNullIfNullOrEmpty was passed as false.

java.lang.IllegalArgumentException - If the iterable contains multiple elements. The state of the iterator is unspecified.

java.lang.RuntimeException - If the iterable contains multiple elements and an exceptionSupplier was passed. The state of the iterator is unspecified.

asImmutable

public static final <T> java.util.List<T> asImmutable(java.util.List<T> l)

Returns an immutable copy of the provided list.

Type Parameters:

T - The type of elements in the list.

Parameters:

l - The list to make immutable.

Returns:

An immutable copy of the provided list.

removeNullValues

public static final void removeNullValues(java.util.Collection<?> c)

Modifies the passed Collection and removes all null values from it.

Parameters:

c - The Collection to remove null values from.

countNonNullValues

public static final int countNonNullValues(java.util.Collection<?> c)

Returns the number of non-null values in the passed Collection or zero if null was passed.

Parameters:

c - The Collection to count non-null values from.

Returns:

The number of non-null values in the Collection.

filterNull

public static final <T> java.util.Collection<T> filterNull(java.util.Collection<T> c)

Returns a new collection (ArrayList), containing only the non-null values of the passed Collection or an empty Collection if null was passed.

Type Parameters:

T - The type of elements in the Collection.

Parameters:

c - The Collection to filter non-null values from.

Returns:

A new collection containing only the non-null values.

toUnmodifiableSet

public static <T> java.util.Set<T> toUnmodifiableSet(T[] data)

Returns a new immutable Set containing the elements from the given array. Order is kept if possible. Duplicate elements will be dropped, so the returned set can be smaller than the provided parameter.

For Java 9 and later, consider using `Set.of()` if the order of elements is not important. See Immutable Set Static Factory Methods for more details.

Type Parameters:

T - The type of elements in the array.

Parameters:

data - The array to convert, nullable.

Returns:

null if the input array is null, otherwise an immutable Set containing the elements from the array.