Package org.apache.juneau.commons.utils

Class CollectionUtils

java.lang.Object
org.apache.juneau.commons.utils.CollectionUtils
public class CollectionUtils extends Object
Utility methods for working with collections and maps.
Complex Data Structure Construction:

This class provides convenient shorthand methods for creating complex nested data structures. The primary methods for building structures are:

Examples:

// Array of lists of maps var data = a( l(m("name", "John", "age", 30)), l(m("name", "Jane", "age", 25)) ); // Compare with traditional Java syntax: List<Map<String,Object>>[] data = new List[]{ new ArrayList<>(Arrays.asList( new LinkedHashMap<>(){{ put("name", "John"); put("age", 30); }} )), new ArrayList<>(Arrays.asList( new LinkedHashMap<>(){{ put("name", "Jane"); put("age", 25); }} )) };

// Complex nested structure: Array of lists containing maps and arrays var complex = a( l( m("user", "admin", "roles", a("read", "write", "delete")), m("user", "guest", "roles", a("read")) ), l( m("status", "active", "count", 42) ) ); // Traditional Java equivalent (significantly more verbose): List<Map<String,Object>>[] complex = new List[]{ new ArrayList<>(Arrays.asList( new LinkedHashMap<>(){{ put("user", "admin"); put("roles", new String[]{"read", "write", "delete"}); }}, new LinkedHashMap<>(){{ put("user", "guest"); put("roles", new String[]{"read"}); }} )), new ArrayList<>(Arrays.asList( new LinkedHashMap<>(){{ put("status", "active"); put("count", 42); }} )) };

// Using unmodifiable maps for immutable data var config = a( m("env", "production", "debug", false), m("env", "development", "debug", true) );

Best Practices:
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> List<T>
    accumulate(Object... o)
    Traverses all elements in the specified objects and accumulates them into a list.
    static <E> List<E>
    addAll(List<E> value, E... entries)
    Adds all the specified values to the specified collection.
    static <E> List<E>
    addAll(List<E> value, List<E> entries)
    Adds all the specified values to the specified collection.
    static <E> Set<E>
    addAll(Set<E> value, E... entries)
    Adds all the specified values to the specified collection.
    static <E> SortedSet<E>
    addAll(SortedSet<E> value, E... entries)
    Adds all the specified values to the specified collection.
    static <T> T[]
    addAll(T[] array, T... newElements)
    Appends one or more elements to an array.
    static <E, C extends Collection<? super E>>
    C
    addAllNn(C value, E... entries)
    Adds all non-null entries to the specified collection.
    static <E, C extends Collection<? super E>>
    C
    addAllNn(C value, Collection<? extends E> entries)
    Adds all non-null elements of the specified collection to the specified target collection.
    static <E> E[]
    array(Class<E> componentType, int length)
    Creates an array of the specified component type and length.
    static <E> E[]
    array(Collection<E> value, Class<E> componentType)
    Converts the specified collection to an array.
    static <T> T[]
    array(T... x)
    Creates an array of objects (varargs form).
    static <E> E[][]
    array2d(E[]... value)
    Creates a 2-dimensional array.
    static List<Object>
    arrayToList(Object array)
    Converts any array (including primitive arrays) to a List.
    static boolean[]
    booleanArray(boolean... value)
    Creates a boolean array.
    static byte[]
    byteArray(int... value)
    Creates a byte array from ints.
    static char[]
    charArray(char... value)
    Creates a char array.
    static <E> E[]
    combine(E[]... arrays)
    Combine an arbitrary number of arrays into a single array.
    static <T> boolean
    contains(T element, T[] array)
    Returns true if the specified array contains the specified element using the String.equals(Object) method.
    static List
    copyArrayToList(Object array, List list)
    Copies the specified array into the specified list.
    static <T> Stream<T>
    deepStream(Object... o)
    Traverses all elements in the specified objects and returns them as a lazily-evaluated stream, without building an intermediate list.
    static double[]
    doubleArray(double... value)
    Creates a double array.
    static <E> E
    elementAt(List<E> l, int index)
    Returns the element at the specified index.
    static FluentMap<String,Object>
    filteredBeanPropertyMap()
    Convenience factory for a filtered, sorted, fluent map with String keys and Object values.
    static <E> Optional<E>
    first(Iterable<? extends E> iterable)
    Returns the first element in an iterable.
    static <T> List<T>
    fixedSizeList(T... values)
    Creates a fixed-size list backed by the specified array (via Arrays.asList(Object...)).
    static float[]
    floatArray(float... value)
    Creates a float array.
    static <E> void
    forEachReverse(E[] value, Consumer<E> action)
    Iterates the specified array in reverse order.
    static <E> void
    forEachReverse(List<E> value, Consumer<E> action)
    Iterates the specified list in reverse order.
    static <T> Set<T>
    hashSet(T... values)
    Creates a HashSet from the specified values.
    static <K, V> Map<K,V>
    immutableMap()
    Convenience method for creating an unmodifiable map.
    static <K, V> Map<K,V>
    immutableMap(K k1, V v1)
    Convenience method for creating an unmodifiable map.
    static <K, V> Map<K,V>
    immutableMap(K k1, V v1, K k2, V v2)
    Convenience method for creating an unmodifiable map.
    static <K, V> Map<K,V>
    immutableMap(K k1, V v1, K k2, V v2, K k3, V v3)
    Convenience method for creating an unmodifiable map.
    static <K, V> Map<K,V>
    immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)
    Convenience method for creating an unmodifiable map.
    static <K, V> Map<K,V>
    immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5)
    Convenience method for creating an unmodifiable map.
    static <K, V> Map<K,V>
    immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6)
    Convenience method for creating an unmodifiable map.
    static <K, V> Map<K,V>
    immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7)
    Convenience method for creating an unmodifiable map.
    static <K, V> Map<K,V>
    immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8)
    Convenience method for creating an unmodifiable map.
    static <K, V> Map<K,V>
    immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9)
    Convenience method for creating an unmodifiable map.
    static <K, V> Map<K,V>
    immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10)
    Convenience method for creating an unmodifiable map.
    static <E> Set<E>
    immutableSet(E... values)
    Convenience method for creating an unmodifiable set.
    static <T> int
    indexOf(T element, T[] array)
    Returns the index position of the element in the specified array using the String.equals(Object) method.
    static int[]
    intArray(int... value)
    Creates an int array.
    static boolean
    isEmpty(Collection<?> c)
    Returns true if the specified collection is null or empty.
    static boolean
    isEmpty(Map<?,?> m)
    Returns true if the specified map is null or empty.
    static boolean
    isEmptyArray(Object[] array)
    Returns true if the specified array is null or has a length of zero.
    static boolean
    isNotEmpty(Collection<?> c)
    Returns true if the specified collection is not null and not empty.
    static boolean
    isNotEmpty(Map<?,?> m)
    Returns true if the specified map is not null and not empty.
    static boolean
    isNotEmptyArray(Object[] array)
    Returns true if the specified array is not null and has a length greater than zero.
    static <E> E
    last(E[] l)
    Returns the last entry in an array.
    static <E> E
    last(List<E> l)
    Returns the last entry in a list.
    static int
    length(Object array)
    Returns the length of the specified array.
    static <T> List<T>
    linkedList(T... values)
    Creates a LinkedList from the specified values.
    static <T> List<T>
    list(T... values)
    Shortcut for creating a modifiable list out of an array of values.
    static <E> Lists<E>
    listBuilder(Class<E> type)
    Convenience factory for a Lists.
    static <E> List<E>
    listOfSize(int size)
    Convenience method for creating an ArrayList of the specified size.
    static <E> List<E>
    listOfType(Class<E> elementType, E... values)
    Convenience method for creating an ArrayList.
    static long[]
    longArray(long... value)
    Creates a long array.
    static <K, V> Map<K,V>
    map()
    Convenience method for creating a LinkedHashMap.
    static <K, V> Map<K,V>
    map(K k1, V v1)
    Convenience method for creating a LinkedHashMap.
    static <K, V> Map<K,V>
    map(K k1, V v1, K k2, V v2)
    Convenience method for creating a LinkedHashMap.
    static <K, V> Map<K,V>
    map(K k1, V v1, K k2, V v2, K k3, V v3)
    Convenience method for creating a LinkedHashMap.
    static <K, V> Map<K,V>
    map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)
    Convenience method for creating a LinkedHashMap.
    static <K, V> Map<K,V>
    map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5)
    Convenience method for creating a LinkedHashMap.
    static <K, V> Map<K,V>
    map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6)
    Convenience method for creating a LinkedHashMap.
    static <K, V> Map<K,V>
    map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7)
    Convenience method for creating a LinkedHashMap.
    static <K, V> Map<K,V>
    map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8)
    Convenience method for creating a LinkedHashMap.
    static <K, V> Map<K,V>
    map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9)
    Convenience method for creating a LinkedHashMap.
    static <K, V> Map<K,V>
    map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10)
    Convenience method for creating a LinkedHashMap.
    static Maps<String,Object>
    mapb_so()
    Convenience factory for a Maps with String keys and Object values.
    static <K, V> Maps<K,V>
    mapBuilder()
    Convenience factory for a Maps builder.
    static <K, V> Maps<K,V>
    mapBuilder(Class<K> keyType, Class<V> valueType)
    Convenience factory for a Maps.
    static <K, V> Map<K,V>
    mapOfType(Class<K> keyType, Class<V> valueType)
    Convenience method for creating a LinkedHashMap.
    static <E> Optional<E>
    next(Iterator<? extends E> iterator)
    Returns the next value from an iterator, or an empty Optional if there are no more elements.
    static <T> T[]
    nullArray(Class<T> type)
    Returns null for the specified array type.
    static <E> List<E>
    nullIfEmpty(List<E> val)
    Returns null if the specified list is null or empty, otherwise returns the list.
    static <K, V> Map<K,V>
    nullIfEmpty(Map<K,V> val)
    Returns null if the specified map is null or empty, otherwise returns the map.
    static <E> Set<E>
    nullIfEmpty(Set<E> val)
    Returns null if the specified set is null or empty, otherwise returns the set.
    static <T> List<T>
    nullList(Class<T> type)
    Returns a null list.
    static <K, V> Map<K,V>
    nullMap(Class<K> keyType, Class<V> valueType)
    Returns a null map.
    static Object[]
    objectArray(Object... value)
    Creates an Object array.
    static <E> Optional<E>
    optionalAt(List<E> l, int index)
    Returns the element at the specified index, wrapped in an Optional.
    static <E> List<E>
    prependAll(List<E> value, E... entries)
    Adds all the specified values to the specified collection.
    static List<String>
    removeNegations(List<String> input)
    Removes negation tokens from a list.
    static <E> E[]
    reverse(E[] array)
    Reverses the elements in the specified array in-place.
    static <E> List<E>
    reverse(List<E> list)
    Returns a reversed view of the specified list.
    static <T> Stream<T>
    rstream(List<T> value)
    Returns a reverse stream of the specified list.
    static <T> Set<T>
    set(T... values)
    Creates a new modifiable LinkedHashSet.
    static <E> Sets<E>
    setBuilder(Class<E> type)
    Convenience factory for a Sets.
    static <E> Set<E>
    setOfType(Class<E> elementType, E... values)
    Convenience method for creating a LinkedHashSet.
    static short[]
    shortArray(int... value)
    Creates a short array from ints.
    static <E> List<E>
    sortedList(E... values)
    Convenience method for creating an ArrayList and sorting it.
    static <E> List<E>
    sortedList(Comparator<E> comparator, E[] values)
    Convenience method for creating an ArrayList and sorting it.
    static <E> List<E>
    sortedList(Comparator<E> comparator, Collection<E> value)
    Convenience method for creating an ArrayList and sorting it.
    static <K, V> SortedMap<K,V>
    sortedMap()
    Convenience method for creating a TreeMap.
    static <E> SortedSet<E>
    sortedSet(E... values)
    Convenience method for creating a TreeSet.
    static <T> Stream<T>
    stream(T[] array)
    Returns a stream of the specified array.
    static <E> List<E>
    synced(List<E> value)
    Wraps the specified list in a synchronized (thread-safe) view via Collections.synchronizedList(List).
    static <K, V> Map<K,V>
    synced(Map<K,V> value)
    Wraps the specified map in a synchronized (thread-safe) view via Collections.synchronizedMap(Map).
    static <E> Set<E>
    synced(Set<E> value)
    Wraps the specified set in a synchronized (thread-safe) view via Collections.synchronizedSet(Set).
    static <E> Object
    toArray(Collection<?> c, Class<E> elementType)
    Converts the specified collection to an array.
    static final List<?>
    toList(Object o)
    Converts various collection-like objects to a List.
    static <E> List<E>
    toList(Object array, Class<E> elementType)
    Converts the specified array to an ArrayList
    static <E> List<E>
    toList(Collection<E> value)
    Creates an ArrayList copy from a collection.
    static <E> List<E>
    toList(Collection<E> value, boolean nullIfEmpty)
    Creates an ArrayList copy from a collection.
    static List<Object>
    toObjectList(Object array)
    Recursively converts the specified array into a list of objects.
    static <E> Set<E>
    toSet(Collection<E> val)
    Creates a new set from the specified collection.
    static <T> Set<T>
    toSet(T[] array)
    Converts the specified array to a Set.
    static <E> SortedSet<E>
    toSortedSet(Collection<E> value)
    Creates a new TreeSet from the specified collection.
    static <E> SortedSet<E>
    toSortedSet(Collection<E> value, boolean nullIfEmpty)
    Creates a new TreeSet from the specified collection.
    static <T> SortedSet<T>
    toSortedSet(Set<T> copyFrom)
    Creates a new TreeSet containing a copy of the specified set.
    static Stream<Object>
    toStream(Object array)
    Converts an array to a stream of objects.
    static String[]
    toStringArray(Collection<?> c)
    Converts the specified collection to an array of strings.
    static <T> void
    traverse(Object o, Consumer<T> c)
    Traverses all elements in the specified object and executes a consumer for each leaf.
    static <E> SortedSet<E>
    treeSet(Comparator<? super E> comparator, Collection<? extends E> elements)
    Creates a TreeSet with a custom comparator from a collection of elements.
    static SortedSet<String>
    treeSetCi(Collection<String> elements)
    Creates a case-insensitive TreeSet from a collection of strings.
    static <T> List<T>
    unmodifiable(List<? extends T> value)
    Creates an unmodifiable view of the specified list.
    static <K, V> Map<K,V>
    unmodifiable(Map<? extends K,? extends V> value)
    Creates an unmodifiable view of the specified map.
    static <T> Set<T>
    unmodifiable(Set<? extends T> value)
    Creates an unmodifiable view of the specified set.
    static <T> SortedSet<T>
    unmodifiable(SortedSet<T> value)
    Creates an unmodifiable view of the specified sorted set.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • accumulate

      public static <T> List<T> accumulate(Object... o)
      Traverses all elements in the specified objects and accumulates them into a list.

      Input shapes are processed as follows:

      • Flattened (recursively): Iterable, Stream, and any array type (including all 8 primitive array types via ClassUtils.isArray(java.lang.Object)), including arbitrary nesting and mixing of these (e.g. a List<int[]>, an array of Streams, etc.).
      • Leaf (added as-is): anything else — String, Map, custom beans, boxed primitives, etc.
      • null handling: a null root, or null encountered mid-traversal, contributes nothing to the result — not even a null element.
      Example:

      List<Object> nested = List.of(new int[]{1, 2}, List.of("a", "b")); // Returns [1, 2, "a", "b"] List<Object> result = accumulate(nested); // Multi-root: returns [1, 2, "a", "b"] List<Object> result2 = accumulate(new int[]{1, 2}, "a", "b");

      Type Parameters:
      T - The element type.
      Parameters:
      o - The objects to traverse. Can be null or empty, in which case an empty list is returned.
      Returns:
      A new modifiable list containing all accumulated leaf elements.

    • deepStream

      public static <T> Stream<T> deepStream(Object... o)
      Traverses all elements in the specified objects and returns them as a lazily-evaluated stream, without building an intermediate list.

      Accepts the same input shapes as accumulate(Object...) — see that method's Javadoc for the full list of flattened vs. leaf types and null-handling semantics.

      Named deepStream rather than stream to avoid an erasure conflict with the existing shallow-array overload stream(Object[]), which has the same erased parameter type (Object[]).

      Example:

      List<Object> nested = List.of(new int[]{1, 2}, List.of("a", "b")); // Lazily yields 1, 2, "a", "b" deepStream(nested).forEach(System.out::println);

      Type Parameters:
      T - The element type.
      Parameters:
      o - The objects to traverse. Can be null or empty, in which case an empty stream is returned.
      Returns:
      A lazily-evaluated stream of all leaf elements.

    • addAll

      @SafeVarargs public static <E> List<E> addAll(List<E> value, E... entries)
      Adds all the specified values to the specified collection. Creates a new set if the value is null.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The collection to add to. Can be null (a new list is created and returned).
      entries - The entries to add. Can be null (treated as a no-op — the value is returned unchanged).
      Returns:
      The set.

    • addAll

      public static <E> List<E> addAll(List<E> value, List<E> entries)
      Adds all the specified values to the specified collection. Creates a new set if the value is null.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The collection to add to. Can be null (a new list is created and returned).
      entries - The entries to add. Can be null (treated as a no-op — the value is returned unchanged).
      Returns:
      The set.

    • addAll

      @SafeVarargs public static <E> Set<E> addAll(Set<E> value, E... entries)
      Adds all the specified values to the specified collection. Creates a new set if the value is null.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The collection to add to. Can be null (a new set is created and returned).
      entries - The entries to add. Can be null (treated as a no-op — the value is returned unchanged).
      Returns:
      The set.

    • addAll

      @SafeVarargs public static <E> SortedSet<E> addAll(SortedSet<E> value, E... entries)
      Adds all the specified values to the specified collection. Creates a new set if the value is null.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The collection to add to. Can be null (a new sorted set is created and returned).
      entries - The entries to add. Can be null (treated as a no-op — the value is returned unchanged).
      Returns:
      The set.

    • addAllNn

      @SafeVarargs public static <E, C extends Collection<? super E>> C addAllNn(C value, E... entries)
      Adds all non-null entries to the specified collection.

      null elements are skipped. A null entries array is a no-op.

      Example:

      List<String> list = new ArrayList<>(); addAllNn(list, "a", null, "b"); // list is [a, b]

      Type Parameters:
      E - The element type.
      C - The collection type.
      Parameters:
      value - The collection to add to. Must not be null.
      entries - The entries to add. Can be null (no-op); null elements are skipped.
      Returns:
      The same collection instance that was passed in.

    • addAllNn

      public static <E, C extends Collection<? super E>> C addAllNn(C value, Collection<? extends E> entries)
      Adds all non-null elements of the specified collection to the specified target collection.

      null elements are skipped. A null entries collection is a no-op.

      Example:

      Set<String> set = new LinkedHashSet<>(); addAllNn(set, Arrays.asList("a", null, "b")); // set is [a, b]

      Type Parameters:
      E - The element type.
      C - The collection type.
      Parameters:
      value - The collection to add to. Must not be null.
      entries - The entries to add. Can be null (no-op); null elements are skipped.
      Returns:
      The same collection instance that was passed in.

    • addAll

      public static <T> T[] addAll(T[] array, T... newElements)
      Appends one or more elements to an array.
      Type Parameters:
      T - The element type.
      Parameters:
      array - The array to append to. Can be null (the new elements are returned as-is).
      newElements - The new elements to append to the array. Must not be null; if empty, the original array is returned.
      Returns:
      A new array with the specified elements appended.

    • array

      public static <E> E[] array(Class<E> componentType, int length)
      Creates an array of the specified component type and length.
      Type Parameters:
      E - The component type of the array.
      Parameters:
      componentType - The component type of the array. Must not be null.
      length - The length of the array.
      Returns:
      A new array of the specified type and length. Never null.

    • array

      public static <E> E[] array(Collection<E> value, Class<E> componentType)
      Converts the specified collection to an array.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The collection to convert. Must not be null (a null argument throws IllegalArgumentException).
      componentType - The component type of the array. Must not be null.
      Returns:
      A new array.

    • arrayToList

      public static List<Object> arrayToList(Object array)
      Converts any array (including primitive arrays) to a List.
      Parameters:
      array - The array to convert. Can be any array type including primitives. Must not be null (a null argument throws IllegalArgumentException).
      Returns:
      A List containing the array elements. Primitive values are auto-boxed. Never null.
      Throws:
      IllegalArgumentException - if the input is null or is not an array.

    • combine

      public static <E> E[] combine(E[]... arrays)
      Combine an arbitrary number of arrays into a single array.
      Type Parameters:
      E - The element type.
      Parameters:
      arrays - Collection of arrays to combine. Must not be null (a null array argument throws IllegalArgumentException); individual null array entries are skipped.
      Returns:
      A new combined array, or an empty array if all arrays are null.

    • contains

      public static <T> boolean contains(T element, T[] array)
      Returns true if the specified array contains the specified element using the String.equals(Object) method.
      Parameters:
      element - The element to check for.
      array - The array to check.
      Returns:
      true if the specified array contains the specified element, false if the array or element is null.

    • copyArrayToList

      public static List copyArrayToList(Object array, List list)
      Copies the specified array into the specified list.

      Works on both object and primitive arrays.

      Parameters:
      array - The array to copy into a list. Can be null (nothing is copied).
      list - The list to copy the values into. Must not be null when the array is non-null.
      Returns:
      The same list passed in.

    • next

      public static <E> Optional<E> next(Iterator<? extends E> iterator)
      Returns the next value from an iterator, or an empty Optional if there are no more elements.

      This is a null-safe operation. Returns an empty Optional if the iterator is null or has no more elements.

      Example:

      Iterator<String> it = list.iterator(); Optional<String> first = next(it); // Optional.of("first") Optional<String> second = next(it); // Optional.of("second") Optional<String> empty = next(it); // Optional.empty() Optional<String> nullResult = next(null); // Optional.empty()

      Type Parameters:
      E - The element type.
      Parameters:
      iterator - The iterator. Can be null.
      Returns:
      An Optional containing the next element, or empty if the iterator is null or has no more elements.

    • first

      public static <E> Optional<E> first(Iterable<? extends E> iterable)
      Returns the first element in an iterable.

      This is a null-safe operation. Returns an empty Optional if the iterable is null or empty.

      Example:

      List<String> list = l("a", "b", "c"); Optional<String> first = first(list); // Optional.of("a") Set<Integer> set = s(1, 2, 3); Optional<Integer> firstInt = first(set); // Optional.of(1) or another element EnumSet<MyEnum> enumSet = EnumSet.allOf(MyEnum.class); Optional<MyEnum> firstEnum = first(enumSet); // Optional.of(first enum value) Optional<String> empty = first(Collections.emptyList()); // Optional.empty() Optional<String> nullResult = first(null); // Optional.empty()

      Type Parameters:
      E - The element type.
      Parameters:
      iterable - The iterable. Can be null.
      Returns:
      An Optional containing the first element, or empty if the iterable is null or empty.

    • forEachReverse

      public static <E> void forEachReverse(E[] value, Consumer<E> action)
      Iterates the specified array in reverse order.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The array to iterate. Must not be null.
      action - The action to perform. Must not be null.

    • forEachReverse

      public static <E> void forEachReverse(List<E> value, Consumer<E> action)
      Iterates the specified list in reverse order.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The list to iterate. Must not be null.
      action - The action to perform. Must not be null.

    • indexOf

      public static <T> int indexOf(T element, T[] array)
      Returns the index position of the element in the specified array using the String.equals(Object) method.
      Parameters:
      element - The element to check for.
      array - The array to check.
      Returns:
      The index position of the element in the specified array, or -1 if the array doesn't contain the element, or the array or element is null.

    • isEmpty

      public static boolean isEmpty(Collection<?> c)
      Returns true if the specified collection is null or empty.
      Parameters:
      c - The collection to check.
      Returns:
      true if the specified collection is null or empty.

    • isEmpty

      public static boolean isEmpty(Map<?,?> m)
      Returns true if the specified map is null or empty.
      Parameters:
      m - The map to check.
      Returns:
      true if the specified map is null or empty.

    • isEmptyArray

      public static boolean isEmptyArray(Object[] array)
      Returns true if the specified array is null or has a length of zero.
      Parameters:
      array - The array to check.
      Returns:
      true if the specified array is null or has a length of zero.

    • isNotEmptyArray

      public static boolean isNotEmptyArray(Object[] array)
      Returns true if the specified array is not null and has a length greater than zero.
      Parameters:
      array - The array to check.
      Returns:
      true if the specified array is not null and has a length greater than zero.

    • fixedSizeList

      @SafeVarargs public static <T> List<T> fixedSizeList(T... values)
      Creates a fixed-size list backed by the specified array (via Arrays.asList(Object...)).

      The returned list is fixed-size: element values can be replaced via List.set(int, Object), but elements cannot be added or removed. Returns null if the input array is null. This differs from list(Object...), which returns a fully-modifiable ArrayList.

      Type Parameters:
      T - The element type.
      Parameters:
      values - The values to add to the list.
      Returns:
      A fixed-size list containing the specified values, or null if the input is null.

    • last

      public static <E> E last(E[] l)
      Returns the last entry in an array.
      Type Parameters:
      E - The element type.
      Parameters:
      l - The array.
      Returns:
      The last element, or null if the array is null or empty.

    • last

      public static <E> E last(List<E> l)
      Returns the last entry in a list.
      Type Parameters:
      E - The element type.
      Parameters:
      l - The list.
      Returns:
      The last element, or null if the list is null or empty.

    • length

      public static int length(Object array)
      Returns the length of the specified array.

      This is a null-safe convenience method that wraps Array.getLength(Object). Works with both object arrays and primitive arrays.

      Example:

      String[] array1 = {"foo", "bar"}; int[] array2 = {1, 2, 3}; int len1 = length(array1); // Returns 2 int len2 = length(array2); // Returns 3 int len3 = length(null); // Returns 0

      Parameters:
      array - The array object. Can be null.
      Returns:
      The length of the array, or 0 if the array is null or not an array.

    • list

      @SafeVarargs public static <T> List<T> list(T... values)
      Shortcut for creating a modifiable list out of an array of values.
      Type Parameters:
      T - The element type.
      Parameters:
      values - The values to add to the list.
      Returns:
      A modifiable list containing the specified values, or null if the values array itself is null.

    • listBuilder

      public static <E> Lists<E> listBuilder(Class<E> type)
      Convenience factory for a Lists.
      Type Parameters:
      E - The element type.
      Parameters:
      type - The element type.
      Returns:
      A new list builder.

    • nullList

      public static <T> List<T> nullList(Class<T> type)
      Returns a null list.

      Intentional null return for assertion testing.

      Type Parameters:
      T - The element type.
      Parameters:
      type - The element type class.
      Returns:
      null.

    • listOfType

      @SafeVarargs public static <E> List<E> listOfType(Class<E> elementType, E... values)
      Convenience method for creating an ArrayList.
      Type Parameters:
      E - The element type.
      Parameters:
      elementType - The element type.
      values - The values to initialize the list with. Can be null (returns null).
      Returns:
      A new modifiable list, or null if the values array itself is null.

    • listOfSize

      public static <E> List<E> listOfSize(int size)
      Convenience method for creating an ArrayList of the specified size.
      Type Parameters:
      E - The element type.
      Parameters:
      size - The initial size of the list.
      Returns:
      A new modifiable list.

    • immutableMap

      public static <K, V> Map<K,V> immutableMap()
      Convenience method for creating an unmodifiable map.
      Type Parameters:
      K - The key type.
      V - The value type.
      Returns:
      A new unmodifiable empty map.

    • immutableMap

      public static <K, V> Map<K,V> immutableMap(K k1, V v1)
      Convenience method for creating an unmodifiable map. Unlike Map.of(...), supports null keys/values and preserves insertion order.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      Returns:
      A new unmodifiable map.

    • immutableMap

      public static <K, V> Map<K,V> immutableMap(K k1, V v1, K k2, V v2)
      Convenience method for creating an unmodifiable map. Unlike Map.of(...), supports null keys/values and preserves insertion order.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      Returns:
      A new unmodifiable map.

    • immutableMap

      public static <K, V> Map<K,V> immutableMap(K k1, V v1, K k2, V v2, K k3, V v3)
      Convenience method for creating an unmodifiable map. Unlike Map.of(...), supports null keys/values and preserves insertion order.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      Returns:
      A new unmodifiable map.

    • immutableMap

      public static <K, V> Map<K,V> immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)
      Convenience method for creating an unmodifiable map. Unlike Map.of(...), supports null keys/values and preserves insertion order.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      Returns:
      A new unmodifiable map.

    • immutableMap

      public static <K, V> Map<K,V> immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5)
      Convenience method for creating an unmodifiable map. Unlike Map.of(...), supports null keys/values and preserves insertion order.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      Returns:
      A new unmodifiable map.

    • immutableMap

      public static <K, V> Map<K,V> immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6)
      Convenience method for creating an unmodifiable map. Unlike Map.of(...), supports null keys/values and preserves insertion order.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      k6 - Key 6.
      v6 - Value 6.
      Returns:
      A new unmodifiable map.

    • immutableMap

      public static <K, V> Map<K,V> immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7)
      Convenience method for creating an unmodifiable map. Unlike Map.of(...), supports null keys/values and preserves insertion order.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      k6 - Key 6.
      v6 - Value 6.
      k7 - Key 7.
      v7 - Value 7.
      Returns:
      A new unmodifiable map.

    • immutableMap

      public static <K, V> Map<K,V> immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8)
      Convenience method for creating an unmodifiable map. Unlike Map.of(...), supports null keys/values and preserves insertion order.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      k6 - Key 6.
      v6 - Value 6.
      k7 - Key 7.
      v7 - Value 7.
      k8 - Key 8.
      v8 - Value 8.
      Returns:
      A new unmodifiable map.

    • immutableMap

      public static <K, V> Map<K,V> immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9)
      Convenience method for creating an unmodifiable map. Unlike Map.of(...), supports null keys/values and preserves insertion order.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      k6 - Key 6.
      v6 - Value 6.
      k7 - Key 7.
      v7 - Value 7.
      k8 - Key 8.
      v8 - Value 8.
      k9 - Key 9.
      v9 - Value 9.
      Returns:
      A new unmodifiable map.

    • immutableMap

      public static <K, V> Map<K,V> immutableMap(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10)
      Convenience method for creating an unmodifiable map. Unlike Map.of(...), supports null keys/values and preserves insertion order.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      k6 - Key 6.
      v6 - Value 6.
      k7 - Key 7.
      v7 - Value 7.
      k8 - Key 8.
      v8 - Value 8.
      k9 - Key 9.
      v9 - Value 9.
      k10 - Key 10.
      v10 - Value 10.
      Returns:
      A new unmodifiable map.

    • immutableSet

      @SafeVarargs public static <E> Set<E> immutableSet(E... values)
      Convenience method for creating an unmodifiable set. Unlike Set.of(...), supports a null element and preserves insertion order.
      Type Parameters:
      E - The element type.
      Parameters:
      values - The values to initialize the set with. Must not be null (a null array throws IllegalArgumentException).
      Returns:
      A new unmodifiable set.

    • map

      public static <K, V> Map<K,V> map()
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Returns:
      A new modifiable map.

    • map

      public static <K, V> Map<K,V> map(K k1, V v1)
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      Returns:
      A new modifiable map.

    • map

      public static <K, V> Map<K,V> map(K k1, V v1, K k2, V v2)
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      Returns:
      A new modifiable map.

    • map

      public static <K, V> Map<K,V> map(K k1, V v1, K k2, V v2, K k3, V v3)
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      Returns:
      A new modifiable map.

    • map

      public static <K, V> Map<K,V> map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      Returns:
      A new modifiable map.

    • map

      public static <K, V> Map<K,V> map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5)
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      Returns:
      A new modifiable map.

    • map

      public static <K, V> Map<K,V> map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6)
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      k6 - Key 6.
      v6 - Value 6.
      Returns:
      A new modifiable map.

    • map

      public static <K, V> Map<K,V> map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7)
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      k6 - Key 6.
      v6 - Value 6.
      k7 - Key 7.
      v7 - Value 7.
      Returns:
      A new modifiable map.

    • map

      public static <K, V> Map<K,V> map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8)
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      k6 - Key 6.
      v6 - Value 6.
      k7 - Key 7.
      v7 - Value 7.
      k8 - Key 8.
      v8 - Value 8.
      Returns:
      A new modifiable map.

    • map

      public static <K, V> Map<K,V> map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9)
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      k6 - Key 6.
      v6 - Value 6.
      k7 - Key 7.
      v7 - Value 7.
      k8 - Key 8.
      v8 - Value 8.
      k9 - Key 9.
      v9 - Value 9.
      Returns:
      A new modifiable map.

    • map

      public static <K, V> Map<K,V> map(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10)
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      k1 - Key 1.
      v1 - Value 1.
      k2 - Key 2.
      v2 - Value 2.
      k3 - Key 3.
      v3 - Value 3.
      k4 - Key 4.
      v4 - Value 4.
      k5 - Key 5.
      v5 - Value 5.
      k6 - Key 6.
      v6 - Value 6.
      k7 - Key 7.
      v7 - Value 7.
      k8 - Key 8.
      v8 - Value 8.
      k9 - Key 9.
      v9 - Value 9.
      k10 - Key 10.
      v10 - Value 10.
      Returns:
      A new modifiable map.

    • mapBuilder

      public static <K, V> Maps<K,V> mapBuilder()
      Convenience factory for a Maps builder.

      This is a shortcut for Maps.create().ordered().

      Example:

      Map<String,Object> map = mapBuilder() .add("foo", 1) .add("bar", 2) .build();

      Type Parameters:
      K - The key type.
      V - The value type.
      Returns:
      A new map builder.
      See Also:

    • mapb_so

      public static Maps<String,Object> mapb_so()
      Convenience factory for a Maps with String keys and Object values.

      This is a shortcut for Maps.create(String.class, Object.class).

      Example:

      Map<String,Object> map = mapBuilder() .add("foo", 1) .add("bar", 2) .build();

      This builder supports optional filtering to automatically exclude unwanted values:

      // Build a map excluding null and empty values Map<String,Object> map = mapBuilder().filtered() .add("foo", null) // Excluded .add("bar", "") // Excluded .add("baz", "value") // Included .build();

      Returns:
      A new map builder.
      See Also:

    • filteredBeanPropertyMap

      public static FluentMap<String,Object> filteredBeanPropertyMap()
      Convenience factory for a filtered, sorted, fluent map with String keys and Object values.

      This is a shortcut for Maps.create(String.class, Object.class).filtered().sorted().buildFluent().

      This is typically used for creating property maps in toString() methods that need to be sorted and filtered.

      Example:

      // In a properties() method return filteredBeanPropertyMap() .a("name", name) .a("value", value);

      Returns:
      A new filtered, sorted, fluent map builder.
      See Also:

    • mapBuilder

      public static <K, V> Maps<K,V> mapBuilder(Class<K> keyType, Class<V> valueType)
      Convenience factory for a Maps.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      keyType - The key type.
      valueType - The value type.
      Returns:
      A new map builder.

    • nullMap

      public static <K, V> Map<K,V> nullMap(Class<K> keyType, Class<V> valueType)
      Returns a null map.

      Intentional null return for assertion testing.

      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      keyType - The key type class.
      valueType - The value type class.
      Returns:
      null.

    • mapOfType

      public static <K, V> Map<K,V> mapOfType(Class<K> keyType, Class<V> valueType)
      Convenience method for creating a LinkedHashMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      keyType - The key type.
      valueType - The value type.
      Returns:
      A new modifiable map.

    • prependAll

      @SafeVarargs public static <E> List<E> prependAll(List<E> value, E... entries)
      Adds all the specified values to the specified collection. Creates a new set if the value is null.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The collection to add to. Can be null (a new list is created and returned).
      entries - The entries to add. Can be null (treated as a no-op — the value is returned unchanged).
      Returns:
      The set.

    • reverse

      public static <E> E[] reverse(E[] array)
      Reverses the elements in the specified array in-place.
      Type Parameters:
      E - The element type.
      Parameters:
      array - The array to reverse. Must not be null.
      Returns:
      The same array, reversed.

    • reverse

      public static <E> List<E> reverse(List<E> list)
      Returns a reversed view of the specified list.

      The returned list is a live view that reflects changes to the original list.

      Type Parameters:
      E - The element type.
      Parameters:
      list - The list to reverse. Must not be null (a null argument throws IllegalArgumentException).
      Returns:
      A reversed view of the list.

    • rstream

      public static <T> Stream<T> rstream(List<T> value)
      Returns a reverse stream of the specified list.
      Example:

      List<String> list = list("a", "b", "c"); Stream<String> reversed = rstream(list); // Produces stream: "c", "b", "a"

      Type Parameters:
      T - The element type.
      Parameters:
      value - The list to stream in reverse order. Can be null.
      Returns:
      A stream of the list elements in reverse order, or an empty stream if the list is null or empty.

    • removeNegations

      public static List<String> removeNegations(List<String> input)
      Removes negation tokens from a list.

      A negation token is a string starting with '-' followed by at least one character. When encountered, it removes the first prior occurrence of the corresponding positive token.

      Example:

      List<String> result = removeNegations(list("a", "b", "-a", "c")); // Produces: ["b", "c"]

      Parameters:
      input - The input list. Cannot be null.
      Returns:
      The list with negation tokens applied, or the original list if no negation tokens were present.

    • treeSet

      public static <E> SortedSet<E> treeSet(Comparator<? super E> comparator, Collection<? extends E> elements)
      Creates a TreeSet with a custom comparator from a collection of elements.

      Null elements in the collection are silently skipped.

      Type Parameters:
      E - The element type.
      Parameters:
      comparator - The comparator to use for ordering. Cannot be null.
      elements - The initial elements. Can be null (treated as empty).
      Returns:
      A new TreeSet containing all non-null elements from the collection.

    • treeSetCi

      public static SortedSet<String> treeSetCi(Collection<String> elements)
      Creates a case-insensitive TreeSet from a collection of strings.

      Equivalent to treeSet(String.CASE_INSENSITIVE_ORDER, elements). Null elements in the collection are silently skipped.

      Parameters:
      elements - The initial elements. Can be null (treated as empty).
      Returns:
      A new case-insensitive TreeSet containing all non-null elements from the collection.

    • setBuilder

      public static <E> Sets<E> setBuilder(Class<E> type)
      Convenience factory for a Sets.
      Type Parameters:
      E - The element type.
      Parameters:
      type - The element type.
      Returns:
      A new set builder.

    • setOfType

      @SafeVarargs public static <E> Set<E> setOfType(Class<E> elementType, E... values)
      Convenience method for creating a LinkedHashSet.
      Type Parameters:
      E - The element type.
      Parameters:
      elementType - The element type.
      values - The values to initialize the set with. Must not be null (a null array throws IllegalArgumentException).
      Returns:
      A new modifiable set.

    • sortedList

      public static <E> List<E> sortedList(Comparator<E> comparator, Collection<E> value)
      Convenience method for creating an ArrayList and sorting it.
      Type Parameters:
      E - The element type.
      Parameters:
      comparator - The comparator to use to sort the list. Can be null (natural ordering is used).
      value - The values to initialize the list with. Can be null (returns an empty list).
      Returns:
      A new modifiable list.

    • sortedList

      public static <E> List<E> sortedList(Comparator<E> comparator, E[] values)
      Convenience method for creating an ArrayList and sorting it.
      Type Parameters:
      E - The element type.
      Parameters:
      comparator - The comparator to use to sort the list. Can be null (natural ordering is used).
      values - The values to initialize the list with. Must not be null.
      Returns:
      A new modifiable list.

    • sortedList

      @SafeVarargs public static <E> List<E> sortedList(E... values)
      Convenience method for creating an ArrayList and sorting it.
      Type Parameters:
      E - The element type.
      Parameters:
      values - The values to initialize the list with. Must not be null.
      Returns:
      A new modifiable list.

    • sortedMap

      public static <K, V> SortedMap<K,V> sortedMap()
      Convenience method for creating a TreeMap.
      Type Parameters:
      K - The key type.
      V - The value type.
      Returns:
      A new modifiable set.

    • sortedSet

      @SafeVarargs public static <E> SortedSet<E> sortedSet(E... values)
      Convenience method for creating a TreeSet.

      Note: null values in the varargs array are automatically filtered out because TreeSet does not support null elements.

      Type Parameters:
      E - The element type.
      Parameters:
      values - The values to initialize the set with.
      Must not be null (a null array throws IllegalArgumentException).
      Can contain null values (they will be filtered out).
      Returns:
      A new modifiable set.

    • stream

      public static <T> Stream<T> stream(T[] array)
      Returns a stream of the specified array.

      Gracefully handles null arrays by returning an empty stream.

      Example:

      String[] array = {"a", "b", "c"}; // Prints "a", "b", "c" stream(array).forEach(System.out::println); // Handles null gracefully - returns empty stream stream(null).forEach(System.out::println); // Prints nothing

      Type Parameters:
      T - The element type.
      Parameters:
      array - The array to stream. Can be null.
      Returns:
      A stream of the array elements, or an empty stream if the array is null.

    • synced

      public static <E> List<E> synced(List<E> value)
      Wraps the specified list in a synchronized (thread-safe) view via Collections.synchronizedList(List).
      Type Parameters:
      E - The element type.
      Parameters:
      value - The list to wrap. Can be null (returns null).
      Returns:
      A synchronized view of the list, or null if the input was null.

    • synced

      public static <K, V> Map<K,V> synced(Map<K,V> value)
      Wraps the specified map in a synchronized (thread-safe) view via Collections.synchronizedMap(Map).
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      value - The map to wrap. Can be null (returns null).
      Returns:
      A synchronized view of the map, or null if the input was null.

    • synced

      public static <E> Set<E> synced(Set<E> value)
      Wraps the specified set in a synchronized (thread-safe) view via Collections.synchronizedSet(Set).
      Type Parameters:
      E - The element type.
      Parameters:
      value - The set to wrap. Can be null (returns null).
      Returns:
      A synchronized view of the set, or null if the input was null.

    • toArray

      public static <E> Object toArray(Collection<?> c, Class<E> elementType)
      Converts the specified collection to an array.

      Works on both object and primitive arrays.

      Type Parameters:
      E - The element type.
      Parameters:
      c - The collection to convert to an array. Must not be null.
      elementType - The component type of the collection. Must not be null.
      Returns:
      A new array.

    • toList

      public static <E> List<E> toList(Collection<E> value)
      Creates an ArrayList copy from a collection.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The collection to copy from. Can be null (returns an empty list).
      Returns:
      A new modifiable list.

    • toList

      public static <E> List<E> toList(Collection<E> value, boolean nullIfEmpty)
      Creates an ArrayList copy from a collection.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The collection to copy from. Can be null.
      nullIfEmpty - If true will return null if the collection is empty or null.
      Returns:
      A new modifiable list, or an empty list if the input was null (when nullIfEmpty is false), or null if nullIfEmpty and the input was null or empty.

    • toList

      public static final List<?> toList(Object o)
      Converts various collection-like objects to a List.

      This utility method enables testing of any collection-like object by converting it to a List that can be passed to methods such as TestUtils.assertList().

      Supported Input Types:
      • List: Returns the input unchanged
      • Iterable: Any collection, set, queue, etc. (converted to List preserving order)
      • Iterator: Converts iterator contents to List
      • Enumeration: Converts enumeration contents to List
      • Stream: Converts stream contents to List (stream is consumed)
      • Map: Converts map entries to List of Map.Entry objects
      • Array: Converts any array type (including primitive arrays) to List
      Usage Examples:

      // Test a Set Set<String> mySet = Set.of("a", "b", "c"); assertList(toList(mySet), "a", "b", "c"); // Test an array String[] myArray = {"x", "y", "z"}; assertList(toList(myArray), "x", "y", "z"); // Test a primitive array int[] numbers = {1, 2, 3}; assertList(toList(numbers), "1", "2", "3"); // Test a Stream Stream<String> myStream = Stream.of("foo", "bar"); assertList(toList(myStream), "foo", "bar"); // Test a Map (converted to entries) Map<String,Integer> myMap = Map.of("a", 1, "b", 2); assertList(toList(myMap), "a=1", "b=2"); // Test any Iterable collection Queue<String> myQueue = new LinkedList<>(List.of("first", "second")); assertList(toList(myQueue), "first", "second");

      Integration with Testing:

      This method is specifically designed to work with testing frameworks to provide a unified testing approach for all collection-like types. Instead of having separate assertion methods for arrays, sets, and other collections, you can convert them all to Lists and use standard list assertion methods.

      Parameters:
      o - The object to convert to a List. Must not be null and must be a supported collection-like type.
      Returns:
      A List containing the elements from the input object.
      Throws:
      IllegalArgumentException - if the input object cannot be converted to a List.
      See Also:

    • toList

      public static <E> List<E> toList(Object array, Class<E> elementType)
      Converts the specified array to an ArrayList
      Type Parameters:
      E - The element type.
      Parameters:
      array - The array to convert. Must not be null (a null argument throws NullPointerException).
      elementType - The type of objects in the array. It must match the actual component type in the array.
      Returns:
      A new ArrayList

    • toObjectList

      public static List<Object> toObjectList(Object array)
      Recursively converts the specified array into a list of objects.
      Parameters:
      array - The array to convert. Must not be null (a null argument throws NullPointerException).
      Returns:
      A new ArrayList

    • toSet

      public static <E> Set<E> toSet(Collection<E> val)
      Creates a new set from the specified collection.
      Type Parameters:
      E - The element type.
      Parameters:
      val - The value to copy from.
      Returns:
      A new LinkedHashSet, or null if the input was null.

    • toSet

      public static <T> Set<T> toSet(T[] array)
      Converts the specified array to a Set.

      The order of the entries in the set are the same as the array.

      Type Parameters:
      T - The entry type of the array.
      Parameters:
      array - The array being wrapped in a Set interface. Must not be null (a null argument throws IllegalArgumentException).
      Returns:
      The new set.

    • toSortedSet

      public static <E> SortedSet<E> toSortedSet(Collection<E> value)
      Creates a new TreeSet from the specified collection.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The value to copy from.
      Returns:
      A new TreeSet, or an empty TreeSet if the input was null.

    • toSortedSet

      public static <E> SortedSet<E> toSortedSet(Collection<E> value, boolean nullIfEmpty)
      Creates a new TreeSet from the specified collection.
      Type Parameters:
      E - The element type.
      Parameters:
      value - The value to copy from.
      nullIfEmpty - If true returns null if the collection is empty.
      Returns:
      A new TreeSet, or an empty TreeSet if the input was null, or null if nullIfEmpty and the collection is empty.

    • toSortedSet

      public static <T> SortedSet<T> toSortedSet(Set<T> copyFrom)
      Creates a new TreeSet containing a copy of the specified set.
      Type Parameters:
      T - The element type.
      Parameters:
      copyFrom - The set to copy from.
      Returns:
      A new TreeSet, or an empty TreeSet if the input was null.

    • toStream

      public static Stream<Object> toStream(Object array)
      Converts an array to a stream of objects.
      Parameters:
      array - The array to convert. Must not be null (a null or non-array argument throws IllegalArgumentException).
      Returns:
      A new stream.

    • toStringArray

      public static String[] toStringArray(Collection<?> c)
      Converts the specified collection to an array of strings.

      Entries are converted to strings using Object.toString(). null values remain null.

      Parameters:
      c - The collection to convert. Must not be null.
      Returns:
      The collection as a string array.

    • traverse

      public static <T> void traverse(Object o, Consumer<T> c)
      Traverses all elements in the specified object and executes a consumer for each leaf.

      Input shapes are processed as follows:

      • Flattened (recursively): Iterable, Stream, and any array type (including all 8 primitive array types via ClassUtils.isArray(java.lang.Object)), including arbitrary nesting and mixing of these.
      • Leaf (consumer called once): anything else — String, Map, custom beans, boxed primitives, etc.
      • null handling: a null root, or null encountered mid-traversal, causes the consumer to be called zero times — no null elements are ever delivered.
      Type Parameters:
      T - The element type.
      Parameters:
      o - The object to traverse. Can be null (the consumer is not called).
      c - The consumer of the leaf elements. Must not be null.

    • array

      @SafeVarargs public static <T> T[] array(T... x)
      Creates an array of objects (varargs form).
      Type Parameters:
      T - The component type of the array.
      Parameters:
      x - The objects to place in the array. Can be null (returned as-is).
      Returns:
      A new array containing the specified objects.

    • array2d

      @SafeVarargs public static <E> E[][] array2d(E[]... value)
      Creates a 2-dimensional array.
      Type Parameters:
      E - The element type of the inner arrays.
      Parameters:
      value - The 1D arrays that will become rows in the 2D array. Can be null (returned as-is).
      Returns:
      A 2D array containing the specified rows.

    • objectArray

      public static Object[] objectArray(Object... value)
      Creates an Object array.
      Parameters:
      value - The objects to place in the array. Can be null (returned as-is).
      Returns:
      A new Object[] containing the specified objects.

    • nullArray

      public static <T> T[] nullArray(Class<T> type)
      Returns null for the specified array type.

      Intentional null return for assertion testing.

      Type Parameters:
      T - The component type.
      Parameters:
      type - The component type class.
      Returns:
      null.

    • linkedList

      @SafeVarargs public static <T> List<T> linkedList(T... values)
      Creates a LinkedList from the specified values.
      Type Parameters:
      T - The element type.
      Parameters:
      values - The values to add to the list. Must not be null (a null array throws NullPointerException).
      Returns:
      A new modifiable LinkedList containing the specified values.

    • hashSet

      @SafeVarargs public static <T> Set<T> hashSet(T... values)
      Creates a HashSet from the specified values.
      Type Parameters:
      T - The element type.
      Parameters:
      values - The values to add to the set. Must not be null (a null array throws NullPointerException).
      Returns:
      A new modifiable HashSet containing the specified values.

    • unmodifiable

      public static <T> List<T> unmodifiable(List<? extends T> value)
      Creates an unmodifiable view of the specified list.
      Type Parameters:
      T - The element type.
      Parameters:
      value - The list to make unmodifiable. Can be null.
      Returns:
      An unmodifiable view of the list, or null if the input was null.

    • unmodifiable

      public static <K, V> Map<K,V> unmodifiable(Map<? extends K,? extends V> value)
      Creates an unmodifiable view of the specified map.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      value - The map to make unmodifiable. Can be null.
      Returns:
      An unmodifiable view of the map, or null if the input was null.

    • unmodifiable

      public static <T> Set<T> unmodifiable(Set<? extends T> value)
      Creates an unmodifiable view of the specified set.
      Type Parameters:
      T - The element type.
      Parameters:
      value - The set to make unmodifiable. Can be null.
      Returns:
      An unmodifiable view of the set, or null if the input was null.

    • unmodifiable

      public static <T> SortedSet<T> unmodifiable(SortedSet<T> value)
      Creates an unmodifiable view of the specified sorted set.
      Type Parameters:
      T - The element type.
      Parameters:
      value - The sorted set to make unmodifiable. Can be null.
      Returns:
      An unmodifiable view of the sorted set, or null if the input was null.

    • optionalAt

      public static <E> Optional<E> optionalAt(List<E> l, int index)
      Returns the element at the specified index, wrapped in an Optional.
      Type Parameters:
      E - The element type.
      Parameters:
      l - The list. Can be null.
      index - The index to access.
      Returns:
      An Optional containing the element, or an empty Optional if null/out-of-bounds.

    • nullIfEmpty

      public static <K, V> Map<K,V> nullIfEmpty(Map<K,V> val)
      Returns null if the specified map is null or empty, otherwise returns the map.
      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      val - The map to check.
      Returns:
      null if the map is null or empty, otherwise the map itself.

    • nullIfEmpty

      public static <E> List<E> nullIfEmpty(List<E> val)
      Returns null if the specified list is null or empty, otherwise returns the list.
      Type Parameters:
      E - The element type.
      Parameters:
      val - The list to check.
      Returns:
      null if the list is null or empty, otherwise the list itself.

    • nullIfEmpty

      public static <E> Set<E> nullIfEmpty(Set<E> val)
      Returns null if the specified set is null or empty, otherwise returns the set.
      Type Parameters:
      E - The element type.
      Parameters:
      val - The set to check.
      Returns:
      null if the set is null or empty, otherwise the set itself.

    • isNotEmpty

      public static boolean isNotEmpty(Collection<?> c)
      Returns true if the specified collection is not null and not empty.
      Parameters:
      c - The collection to check.
      Returns:
      true if not null and not empty.

    • isNotEmpty

      public static boolean isNotEmpty(Map<?,?> m)
      Returns true if the specified map is not null and not empty.
      Parameters:
      m - The map to check.
      Returns:
      true if not null and not empty.

    • elementAt

      public static <E> E elementAt(List<E> l, int index)
      Returns the element at the specified index.
      Type Parameters:
      E - The element type.
      Parameters:
      l - The list. Can be null.
      index - The index to access.
      Returns:
      The element, or null if out-of-bounds/null list.

    • set

      @SafeVarargs public static <T> Set<T> set(T... values)
      Creates a new modifiable LinkedHashSet.
      Type Parameters:
      T - The element type.
      Parameters:
      values - The values to add to the set. Must not be null (a null array throws IllegalArgumentException).
      Returns:
      A modifiable LinkedHashSet containing the specified values.

    • intArray

      public static int[] intArray(int... value)
      Creates an int array.
      Parameters:
      value - The values.
      Returns:
      A new int array.

    • longArray

      public static long[] longArray(long... value)
      Creates a long array.
      Parameters:
      value - The values.
      Returns:
      A new long array.

    • byteArray

      public static byte[] byteArray(int... value)
      Creates a byte array from ints.
      Parameters:
      value - The int values to convert to bytes.
      Returns:
      A new byte array.

    • charArray

      public static char[] charArray(char... value)
      Creates a char array.
      Parameters:
      value - The values.
      Returns:
      A new char array.

    • floatArray

      public static float[] floatArray(float... value)
      Creates a float array.
      Parameters:
      value - The values.
      Returns:
      A new float array.

    • doubleArray

      public static double[] doubleArray(double... value)
      Creates a double array.
      Parameters:
      value - The values.
      Returns:
      A new double array.

    • booleanArray

      public static boolean[] booleanArray(boolean... value)
      Creates a boolean array.
      Parameters:
      value - The values.
      Returns:
      A new boolean array.

    • shortArray

      public static short[] shortArray(int... value)
      Creates a short array from ints.
      Parameters:
      value - The int values to convert to shorts.
      Returns:
      A new short array.