Package com.norconex.commons.lang.collection

# Class CollectionUtil

java.lang.Object
com.norconex.commons.lang.collection.CollectionUtil

public final class CollectionUtil extends Object
Collection-related utility methods.

Since:
  2.0.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> List<T>`
  `adaptedList(Object object)`
  Adapts any object to a new non-null mutable List, regardless of the nature of the object.
  `static <T> Set<T>`
  `adaptedSet(Object object)`
  Adapts any object to a new non-null mutable Set, regardless of the nature of the object.
  `static <T> List<T>`
  `asListOrEmpty(T... values)`
  Returns a fixed-size list backed by the specified array or an empty list if the array is `null`.
  `static <T> List<T>`
  `asListOrNull(T... values)`
  Returns a fixed-size list backed by the specified array or `null` if the array is `null`.
  `static void`
  `blanksToNulls(Collection<String> c)`
  Convert blank string entries to `null`.
  `static void`
  `emptiesToNulls(Collection<String> c)`
  Convert empty string entries to `null`.
  `static void`
  `nullsToEmpties(Collection<String> c)`
  Convert `null` entries to empty strings.
  `static void`
  `removeBlanks(Collection<String> c)`
  Removes blank strings in the given collection.
  `static void`
  `removeEmpties(Collection<String> c)`
  Removes empty strings in the given collection.
  `static void`
  `removeNulls(Collection<?> c)`
  Removes `null` entries in the given collection.
  `static <T> void`
  `replaceAll(Collection<T> c, T source, T target)`
  Replaces all elements matching the source value with the target value.
  `static <T> void`
  `setAll(Collection<T> target, Collection<T> source)`
  Sets all values of the source collection into the target one.
  `static <T> void`
  `setAll(Collection<T> target, T... source)`
  Sets all values of the source array into the target collection.
  `static <K, V> void`
  `setAll(Map<K,V> target, Map<K,V> source)`
  Sets all values of the source map into the target one.
  `static Object`
  `toArray(Collection<?> c, @NonNull Class<?> arrayType)`
  Converts a collection to an array using the specified type (never `null`).
  `static List<String>`
  `toStringList(Object... values)`
  Converts a list of objects to an unmodifiable list of strings using default `GenericConverter` instance.
  `static List<String>`
  `toStringList(Collection<?> values)`
  Converts a list of objects to an unmodifiable list of strings using default `GenericConverter` instance.
  `static <T> List<T>`
  `toTypeList(List<String> values, Class<T> targetClass)`
  Converts a list of strings to an unmodifiable list of objects matching the return type.
  `static <T> List<T>`
  `toTypeList(List<String> values, Function<String,T> converter)`
  Converts a list of strings to an unmodifiable list of objects matching the return type.
  `static <T> List<T>`
  `unionList(Object... objects)`
  Create a non-null mutable list containing the combination of supplied objects of the specified type.
  `static <T> Set<T>`
  `unionSet(Object... objects)`
  Create a non-null mutable set containing the combination of supplied objects of the specified type (minus duplicates).
  `static <T> List<T>`
  `unmodifiableList(T... values)`
  Returns an unmodifiable view of the specified list.
  `static <T> Set<T>`
  `unmodifiableSet(T... values)`
  Returns an unmodifiable view of the specified set.

  ### Methods inherited from class java.lang.Object

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

- ## Method Details

  - ### adaptedList

    public static <T> List<T> adaptedList(Object object)
    Adapts any object to a new non-null mutable List, regardless of the nature of the object. If the object is a Collection or array, it will be iterated over to populate the new list. If it is any other object, it will become the first and only item in the newly created list. If the object is `null` or a blank string, an empty list is returned. The supplied object must be a value or values of the expected type.
    Type Parameters:
      `T` - the expected return type of the list
    Parameters:
      `object` - object to adapt
    Returns:
      adapted list

  - ### adaptedSet

    public static <T> Set<T> adaptedSet(Object object)
    Adapts any object to a new non-null mutable Set, regardless of the nature of the object. If the object is a Collection or array, it will be iterated over to populate the new set. If it is any other object, it will become the first and only item in the newly created set. If the object is `null` or a blank string, an empty set is returned. The supplied object must be a value or values of the expected type.
    Type Parameters:
      `T` - the expected return type of the set
    Parameters:
      `object` - object to adapt
    Returns:
      adapted set

  - ### toArray

    public static Object toArray(Collection<?> c, @NonNull @NonNull Class<?> arrayType)

    Converts a collection to an array using the specified type (never `null`).

    Since 3.0.0, passing a `null` collection argument will will return an empty array of the supplied type.

    Parameters:
      `c` - collection to convert or `null`
      `arrayType` - array type (must not be `null`)
    Returns:
      the new array (never `null`)
    Throws:
      `NullPointerException` - if arrayType is `null`

  - ### setAll

    public static <T> void setAll(Collection<T> target, Collection<T> source)
    Sets all values of the source collection into the target one. Same as doing a "clear", followed by "addAll", but it also checks for `null` and will not clear/add if the source collection is the same instance as the target one. If target is `null`, invoking this method has no effect. If source is `null` will clear the target collection
    Type Parameters:
      `T` - objects class type
    Parameters:
      `target` - target collection
      `source` - source collection

  - ### setAll

    @SafeVarargs public static <T> void setAll(Collection<T> target, T... source)
    Sets all values of the source array into the target collection. Same as doing a "clear", followed by "addAll" after converting the array to a list. It also checks for `null`. If target is `null`, invoking this method has no effect. If source is `null` or is an array containing only one `null` element, it will clear the target collection
    Type Parameters:
      `T` - objects class type
    Parameters:
      `target` - target collection
      `source` - source collection

  - ### setAll

    public static <K, V> void setAll(Map<K,V> target, Map<K,V> source)
    Sets all values of the source map into the target one. Same as doing a "clear", followed by "putAll", but it also checks for `null` and will not clear/add if the source map is the same instance as the target one. If target is `null`, invoking this method has no effect. If source is `null` will clear the target map
    Type Parameters:
      `K` - key type
      `V` - value type
    Parameters:
      `target` - target map
      `source` - source map

  - ### asListOrEmpty

    @SafeVarargs public static <T> List<T> asListOrEmpty(T... values)
    Returns a fixed-size list backed by the specified array or an empty list if the array is `null`. This is a null-safe version of `Arrays.asList(Object...)`.
    Type Parameters:
      `T` - objects class type
    Parameters:
      `values` - the array by which the list will be backed
    Returns:
      a list view of the specified array (never `null`)
    See Also:
      - `asListOrNull(Object...)`

  - ### asListOrNull

    @SafeVarargs public static <T> List<T> asListOrNull(T... values)
    Returns a fixed-size list backed by the specified array or `null` if the array is `null`. This is a null-safe version of `Arrays.asList(Object...)`. A list is returned even if the array is empty or contains only `null` values.
    Type Parameters:
      `T` - objects class type
    Parameters:
      `values` - the array by which the list will be backed
    Returns:
      a list view of the specified array
    See Also:
      - `asListOrEmpty(Object...)`

  - ### toStringList

    public static List<String> toStringList(Object... values)
    Converts a list of objects to an unmodifiable list of strings using default `GenericConverter` instance. If the supplied list is `null`, an empty string list is returned.
    Parameters:
      `values` - list to convert to a list of strings
    Returns:
      list of strings

  - ### toStringList

    public static List<String> toStringList(Collection<?> values)
    Converts a list of objects to an unmodifiable list of strings using default `GenericConverter` instance. If the supplied list is `null`, an empty string list is returned.
    Parameters:
      `values` - list to convert to a list of strings
    Returns:
      list of strings

  - ### toTypeList

    public static <T> List<T> toTypeList(List<String> values, Class<T> targetClass)
    Converts a list of strings to an unmodifiable list of objects matching the return type. If the supplied list is `null`, an empty list is returned.
    Type Parameters:
      `T` - objects class type
    Parameters:
      `values` - list to convert to a list of the given type
      `targetClass` - target class
    Returns:
      list

  - ### toTypeList

    public static <T> List<T> toTypeList(List<String> values, Function<String,T> converter)
    Converts a list of strings to an unmodifiable list of objects matching the return type. If the supplied list is `null`, an empty list is returned.
    Type Parameters:
      `T` - target objects class type
    Parameters:
      `values` - list to convert to a list of the given type
      `converter` - function converting string to type
    Returns:
      list

  - ### unmodifiableList

    public static <T> List<T> unmodifiableList(T... values)
    Returns an unmodifiable view of the specified list. Convenience method for doing with an array the same as `Collections.unmodifiableList(List)`. A `null` array argument will return an empty list.
    Type Parameters:
      `T` - target objects class type
    Parameters:
      `values` - the values to convert to an unmodifiable list
    Returns:
      unmodifiable list (never `null`)

  - ### unmodifiableSet

    public static <T> Set<T> unmodifiableSet(T... values)
    Returns an unmodifiable view of the specified set. Convenience method for doing with an array the same as `Collections.unmodifiableSet(Set)`. A `null` array argument will return an empty set. This method uses a `LinkedHashSet` to maintain order.
    Type Parameters:
      `T` - target objects class type
    Parameters:
      `values` - the values to convert to an unmodifiable list
    Returns:
      unmodifiable list

  - ### removeNulls

    public static void removeNulls(Collection<?> c)
    Removes `null` entries in the given collection. Only useful for collection implementations allowing `null` entries.
    Parameters:
      `c` - a collection

  - ### removeBlanks

    public static void removeBlanks(Collection<String> c)
    Removes blank strings in the given collection.
    Parameters:
      `c` - a string collection

  - ### removeEmpties

    public static void removeEmpties(Collection<String> c)
    Removes empty strings in the given collection.
    Parameters:
      `c` - a string collection

  - ### replaceAll

    public static <T> void replaceAll(Collection<T> c, T source, T target)
    Replaces all elements matching the source value with the target value.
    Type Parameters:
      `T` - elements type
    Parameters:
      `c` - a collection
      `source` - object to replace
      `target` - replacement

  - ### nullsToEmpties

    public static void nullsToEmpties(Collection<String> c)
    Convert `null` entries to empty strings.
    Parameters:
      `c` - a string collection

  - ### emptiesToNulls

    public static void emptiesToNulls(Collection<String> c)
    Convert empty string entries to `null`.
    Parameters:
      `c` - a string collection

  - ### blanksToNulls

    public static void blanksToNulls(Collection<String> c)
    Convert blank string entries to `null`.
    Parameters:
      `c` - a string collection

  - ### unionList

    public static <T> List<T> unionList(Object... objects)
    Create a non-null mutable list containing the combination of supplied objects of the specified type. If the object is a Collection or array, it will be iterated over to populate the new list (recursively). Any `null` objects are ignored (not added to the returned list). Objects are returned in the order supplied.
    Parameters:
      `objects` - objects to combine into a new list
    Returns:
      a new non-null, mutable list
    Since:
      3.0.0

  - ### unionSet

    public static <T> Set<T> unionSet(Object... objects)
    Create a non-null mutable set containing the combination of supplied objects of the specified type (minus duplicates). If the object is a Collection or array, it will be iterated over to populate the new set (recursively). Any `null` objects are ignored (not added to the returned set). There are no guarantee on the order in which objects are returned.
    Parameters:
      `objects` - objects to combine into a new set
    Returns:
      a new non-null, mutable set
    Since:
      3.0.0