Package io.microsphere.collection

Class ListUtils

  • All Implemented Interfaces:
    Utils
    public abstract class ListUtils
extends java.lang.Object
implements Utils
    The utilities class for Java List
    Since:
    1.0.0
    Author:
    Mercy
    See Also:
    Lists, List

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <E> E first​(java.util.List<E> list)
      Retrieves the first element from the specified list.
      static <T> void forEach​(java.util.List<T> values, java.util.function.BiConsumer<java.lang.Integer,​T> indexedElementConsumer)
      Performs the given action for each element of the specified list, providing both the index and the element.
      static <T> void forEach​(java.util.List<T> values, java.util.function.Consumer<T> consumer)
      Performs the given action for each element of the specified list.
      static boolean isList​(java.lang.Class<?> type)
      Checks if the specified type is assignable from List.
      static boolean isList​(java.lang.Object values)
      Checks if the specified object is an instance of List.
      static <E> E last​(java.util.List<E> list)
      Retrieves the last element from the specified list.
      static <E> java.util.ArrayList<E> newArrayList()
      Creates a new empty ArrayList instance.
      static <E> java.util.ArrayList<E> newArrayList​(int size)
      Creates a new ArrayList instance with the specified initial capacity.
      static <E> java.util.ArrayList<E> newArrayList​(java.lang.Iterable<E> values)
      Creates a new ArrayList instance containing all elements from the specified Iterable.
      static <E> java.util.ArrayList<E> newArrayList​(java.util.Enumeration<E> values)
      Creates a new LinkedList instance from the specified Enumeration.
      static <E> java.util.ArrayList<E> newArrayList​(java.util.Iterator<E> iterator)
      Creates a new ArrayList instance containing all elements from the specified Iterator.
      static <E> java.util.LinkedList<E> newLinkedList()
      Creates a new empty LinkedList instance.
      static <E> java.util.LinkedList<E> newLinkedList​(java.lang.Iterable<E> values)
      Creates a new LinkedList instance containing all elements from the specified Iterable.
      static <E> java.util.LinkedList<E> newLinkedList​(java.util.Enumeration<E> values)
      Creates a new LinkedList instance from the specified Enumeration.
      static <E> java.util.LinkedList<E> newLinkedList​(java.util.Iterator<E> iterator)
      Creates a new LinkedList instance containing all elements from the specified Iterator.
      static <E> java.util.List<E> of​(E... elements)
      Creates an immutable list from the given elements.
      static <E> java.util.ArrayList<E> ofArrayList​(E... array)
      Creates a new ArrayList containing all elements from the specified array.
      static <E> java.util.LinkedList<E> ofLinkedList​(E... array)
      Creates a new LinkedList containing all elements from the specified array.
      static <E> java.util.List<E> ofList​(E... elements)
      Creates an immutable list from the given array of elements.
      static <E> java.util.List<E> ofList​(java.lang.Iterable<E> iterable)
      Creates an immutable list from the specified Iterable.
      static <E> java.util.List<E> ofList​(java.util.Enumeration<E> enumeration)
      Creates an immutable list from the specified Enumeration.
      static <E> java.util.List<E> ofList​(java.util.Iterator<E> iterator)
      Creates an immutable list from the specified Iterator.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • isList

        public static boolean isList​(@Nullable
                             java.lang.Object values)
        Checks if the specified object is an instance of List.

        Example Usage

        
     List<String> list = Arrays.asList("a", "b", "c");
     boolean result1 = ListUtils.isList(list);  // returns true

     String notAList = "not a list";
     boolean result2 = ListUtils.isList(notAList);  // returns false

     Object nullObject = null;
     boolean result3 = ListUtils.isList(nullObject);  // returns false
        Parameters:
        values - the object to check
        Returns:
        true if the specified object is an instance of List, otherwise false

      • isList

        public static boolean isList​(@Nullable
                             java.lang.Class<?> type)
        Checks if the specified type is assignable from List.

        Example Usage

        
     boolean result1 = ListUtils.isList(ArrayList.class);  // returns true
     boolean result2 = ListUtils.isList(String.class);     // returns false
     boolean result3 = ListUtils.isList(List.class);       // returns true
        Parameters:
        type - the type to check
        Returns:
        true if the specified type is assignable from List, otherwise false

      • first

        @Nullable
public static <E> E first​(java.util.List<E> list)
        Retrieves the first element from the specified list.

        Example Usage

        
     List<Integer> numbers = Arrays.asList(1, 2, 3);
     Integer firstNumber = first(numbers); // returns 1

     List<String> emptyList = Collections.emptyList();
     String firstString = first(emptyList); // returns null
        Type Parameters:
        E - the type of element in the list
        Parameters:
        list - the list from which to retrieve the first element
        Returns:
        the first element if the list is not empty, or null otherwise

      • last

        @Nullable
public static <E> E last​(java.util.List<E> list)
        Retrieves the last element from the specified list.

        Example Usage

        
     List<Integer> numbers = Arrays.asList(1, 2, 3);
     Integer lastNumber = last(numbers); // returns 3

     List<String> emptyList = Collections.emptyList();
     String lastString = last(emptyList); // returns null
        Type Parameters:
        E - the type of element in the list
        Parameters:
        list - the list from which to retrieve the last element
        Returns:
        the last element if the list is not empty, or null otherwise

      • of

        @Nonnull
@Immutable
public static <E> java.util.List<E> of​(E... elements)
        Creates an immutable list from the given elements.

        This method is a convenient way to create a list with a small number of elements. The returned list is unmodifiable, meaning that any attempt to change its contents will result in an UnsupportedOperationException.

        Example Usage

        
     List<String> fruits = ListUtils.of("apple", "banana", "cherry");
     System.out.println(fruits); // Output: [apple, banana, cherry]

     List<Integer> numbers = ListUtils.of(1, 2, 3, 4, 5);
     System.out.println(numbers); // Output: [1, 2, 3, 4, 5]

     List<String> emptyList = ListUtils.of();
     System.out.println(emptyList); // Output: []
        Type Parameters:
        E - the type of elements in the list
        Parameters:
        elements - the elements to include in the list
        Returns:
        an immutable list containing the specified elements
        See Also:
        for more details on behavior and immutability

      • ofList

        @Nonnull
@Immutable
public static <E> java.util.List<E> ofList​(E... elements)
        Creates an immutable list from the given array of elements.

        This method is typically used to create a list from an array or varargs input. If the provided array is empty, it returns an empty list. The returned list is unmodifiable, meaning any attempt to modify it will throw an UnsupportedOperationException.

        Example Usage

        
     List<String> fruits = ListUtils.ofList("apple", "banana", "cherry");
     System.out.println(fruits); // Output: [apple, banana, cherry]

     String[] names = {};
     List<String> emptyList = ListUtils.ofList(names);
     System.out.println(emptyList); // Output: []
        Type Parameters:
        E - the type of elements in the array
        Parameters:
        elements - the array of elements to include in the list
        Returns:
        an immutable list containing the specified elements

      • ofList

        @Nonnull
@Immutable
public static <E> java.util.List<E> ofList​(java.lang.Iterable<E> iterable)
        Creates an immutable list from the specified Iterable.

        If the given iterable is null, an empty list will be returned. If the iterable is already a list, it will be wrapped in an unmodifiable list. Otherwise, the elements will be copied into a new list.

        Example Usage

        
     Set<String> fruits = new HashSet<>(Arrays.asList("apple", "banana", "cherry"));
     List<String> fruitsList = ListUtils.ofList(fruits);
     System.out.println(fruitsList); // Output: [apple, banana, cherry]

     List<Integer> numbers = Arrays.asList(1, 2, 3);
     List<Integer> unmodifiableNumbers = ListUtils.ofList(numbers);
     System.out.println(unmodifiableNumbers); // Output: [1, 2, 3] - already a list, wrapped as unmodifiable

     List<String> emptyList = ListUtils.ofList((Iterable<String>) null);
     System.out.println(emptyList); // Output: []
        Type Parameters:
        E - The type of elements in the iterable.
        Parameters:
        iterable - The iterable to convert.
        Returns:
        An immutable list containing all elements from the iterable.

      • ofList

        @Nonnull
@Immutable
public static <E> java.util.List<E> ofList​(java.util.Enumeration<E> enumeration)
        Creates an immutable list from the specified Enumeration.

        If the given enumeration is null, an empty list will be returned. Otherwise, the elements will be copied into a new list using the underlying iterator, and the result will be wrapped in an unmodifiable list.

        Example Usage

        
     Vector<String> vector = new Vector<>(Arrays.asList("one", "two", "three"));
     List<String> list = ListUtils.ofList(vector.elements());
     System.out.println(list); // Output: [one, two, three]

     List<Integer> emptyList = ListUtils.ofList((Enumeration<Integer>) null);
     System.out.println(emptyList); // Output: []
        Type Parameters:
        E - The type of elements in the enumeration.
        Parameters:
        enumeration - The enumeration to convert.
        Returns:
        An immutable list containing all elements from the enumeration.

      • ofList

        @Nonnull
@Immutable
public static <E> java.util.List<E> ofList​(java.util.Iterator<E> iterator)
        Creates an immutable list from the specified Iterator.

        If the given iterator is null, an empty list will be returned. Otherwise, the elements will be copied into a new list using the underlying iteration, and the result will be wrapped in an unmodifiable list.

        Example Usage

        
     List<String> fruits = ListUtils.ofList(Arrays.asList("apple", "banana", "cherry").iterator());
     System.out.println(fruits); // Output: [apple, banana, cherry]

     List<Integer> numbers = ListUtils.ofList((Iterator<Integer>) null);
     System.out.println(numbers); // Output: []
        Type Parameters:
        E - The type of elements in the iterator.
        Parameters:
        iterator - The iterator to convert.
        Returns:
        An immutable list containing all elements from the iterator.

      • newArrayList

        @Nonnull
public static <E> java.util.ArrayList<E> newArrayList()
        Creates a new empty ArrayList instance.

        This method provides a convenient way to create an empty array list with default initial capacity. The returned list is modifiable and will grow dynamically as elements are added.

        Example Usage

        
     List<String> list = ListUtils.newArrayList();
     System.out.println(list.isEmpty()); // Output: true

     list.add("Hello");
     System.out.println(list); // Output: [Hello]
        Type Parameters:
        E - the type of elements in the list
        Returns:
        a new, empty ArrayList with default initial capacity

      • newArrayList

        @Nonnull
public static <E> java.util.ArrayList<E> newArrayList​(int size)
        Creates a new ArrayList instance with the specified initial capacity.

        This method provides a convenient way to create an array list with a predefined initial size, which can help optimize performance when the number of elements to be added is known in advance.

        Example Usage

        
     List<String> list = ListUtils.newArrayList(10);
     System.out.println(list.isEmpty()); // Output: true

     list.add("Hello");
     System.out.println(list); // Output: [Hello]
        Type Parameters:
        E - The type of elements in the list.
        Parameters:
        size - The initial capacity of the array list.
        Returns:
        A new, empty ArrayList with the specified initial capacity.

      • newArrayList

        @Nonnull
public static <E> java.util.ArrayList<E> newArrayList​(java.util.Enumeration<E> values)
        Creates a new LinkedList instance from the specified Enumeration.

        This method converts the given Enumeration into an Iterable using CollectionUtils.toIterable(Enumeration) and then delegates to newLinkedList(Iterable) to construct the list.

        Example Usage

        
     Vector<String> vector = new Vector<>(Arrays.asList("apple", "banana", "cherry"));
     List<String> list = ListUtils.newArrayList(vector.elements());
     System.out.println(list); // Output: [apple, banana, cherry]

     List<Integer> emptyList = ListUtils.newArrayList((Enumeration<Integer>) null);
     System.out.println(emptyList); // Output: []
        Type Parameters:
        E - The type of elements in the enumeration.
        Parameters:
        values - The enumeration to convert.
        Returns:
        A new linked list containing all elements from the enumeration.
        See Also:
        newLinkedList(Iterable), CollectionUtils.toIterable(Enumeration)

      • newArrayList

        @Nonnull
public static <E> java.util.ArrayList<E> newArrayList​(java.lang.Iterable<E> values)
        Creates a new ArrayList instance containing all elements from the specified Iterable.

        If the given Iterable is null, an empty array list will be returned. Otherwise, the elements will be iterated and added to a new array list.

        Example Usage

        
     List<String> fruits = Arrays.asList("apple", "banana", "cherry");
     List<String> listCopy = ListUtils.newArrayList(fruits);
     System.out.println(listCopy); // Output: [apple, banana, cherry]

     Set<Integer> numbersSet = new HashSet<>(Arrays.asList(1, 2, 3));
     List<Integer> numbersList = ListUtils.newArrayList(numbersSet);
     System.out.println(numbersList); // Output: [1, 2, 3] - order may vary depending on Set implementation

     List<String> emptyList = ListUtils.newArrayList((Iterable<String>) null);
     System.out.println(emptyList); // Output: []
        Type Parameters:
        E - The type of elements in the iterable.
        Parameters:
        values - The iterable to convert.
        Returns:
        A new array list containing all elements from the iterable.
        See Also:
        newArrayList(Iterator)

      • newArrayList

        @Nonnull
public static <E> java.util.ArrayList<E> newArrayList​(java.util.Iterator<E> iterator)
        Creates a new ArrayList instance containing all elements from the specified Iterator.

        If the given Iterator is null, an empty array list will be returned. Otherwise, the elements will be iterated and added to a new array list.

        Example Usage

        
     List<String> fruits = Arrays.asList("apple", "banana", "cherry");
     List<String> listCopy = ListUtils.newArrayList(fruits.iterator());
     System.out.println(listCopy); // Output: [apple, banana, cherry]

     List<Integer> numbers = ListUtils.newArrayList((Iterator<Integer>) null);
     System.out.println(numbers); // Output: []
        Type Parameters:
        E - The type of elements in the iterator.
        Parameters:
        iterator - The iterator to convert.
        Returns:
        A new array list containing all elements from the iterator.

      • newLinkedList

        @Nonnull
public static <E> java.util.LinkedList<E> newLinkedList()
        Creates a new empty LinkedList instance.

        This method provides a convenient way to create an empty linked list. The returned list is modifiable and allows for efficient insertions and deletions.

        Example Usage

        
     List<String> list = ListUtils.newLinkedList();
     System.out.println(list.isEmpty()); // Output: true

     list.add("Hello");
     System.out.println(list); // Output: [Hello]
        Type Parameters:
        E - the type of elements in the list
        Returns:
        a new, empty LinkedList

      • newLinkedList

        @Nonnull
public static <E> java.util.LinkedList<E> newLinkedList​(java.util.Enumeration<E> values)
        Creates a new LinkedList instance from the specified Enumeration.

        This method converts the given Enumeration into an Iterable using CollectionUtils.toIterable(Enumeration) and then delegates to newLinkedList(Iterable) to construct the list.

        Example Usage

        
     Vector<String> vector = new Vector<>(Arrays.asList("apple", "banana", "cherry"));
     List<String> list = ListUtils.newLinkedList(vector.elements());
     System.out.println(list); // Output: [apple, banana, cherry]

     List<Integer> emptyList = ListUtils.newLinkedList((Enumeration<Integer>) null);
     System.out.println(emptyList); // Output: []
        Type Parameters:
        E - The type of elements in the enumeration.
        Parameters:
        values - The enumeration to convert.
        Returns:
        A new linked list containing all elements from the enumeration.
        See Also:
        newLinkedList(Iterable), CollectionUtils.toIterable(Enumeration)

      • newLinkedList

        public static <E> java.util.LinkedList<E> newLinkedList​(java.lang.Iterable<E> values)
        Creates a new LinkedList instance containing all elements from the specified Iterable.

        If the given Iterable is null, an empty linked list will be returned. Otherwise, the elements will be iterated and added to a new linked list.

        Example Usage

        
     List<String> fruits = Arrays.asList("apple", "banana", "cherry");
     List<String> listCopy = ListUtils.newLinkedList(fruits);
     System.out.println(listCopy); // Output: [apple, banana, cherry]

     Set<Integer> numbersSet = new HashSet<>(Arrays.asList(1, 2, 3));
     List<Integer> numbersList = ListUtils.newLinkedList(numbersSet);
     System.out.println(numbersList); // Output: [1, 2, 3] - order may vary depending on Set implementation

     List<String> emptyList = ListUtils.newLinkedList((Iterable<String>) null);
     System.out.println(emptyList); // Output: []
        Type Parameters:
        E - The type of elements in the iterable.
        Parameters:
        values - The iterable to convert.
        Returns:
        A new linked list containing all elements from the iterable.
        See Also:
        newLinkedList(Iterator)

      • newLinkedList

        public static <E> java.util.LinkedList<E> newLinkedList​(java.util.Iterator<E> iterator)
        Creates a new LinkedList instance containing all elements from the specified Iterator.

        If the given Iterator is null, an empty linked list will be returned. Otherwise, the elements will be iterated and added to a new linked list.

        Example Usage

        
     List<String> fruits = Arrays.asList("apple", "banana", "cherry");
     List<String> listCopy = ListUtils.newLinkedList(fruits.iterator());
     System.out.println(listCopy); // Output: [apple, banana, cherry]

     List<Integer> numbers = ListUtils.newLinkedList((Iterator<Integer>) null);
     System.out.println(numbers); // Output: []
        Type Parameters:
        E - The type of elements in the iterator.
        Parameters:
        iterator - The iterator to convert.
        Returns:
        A new linked list containing all elements from the iterator.

      • ofArrayList

        public static <E> java.util.ArrayList<E> ofArrayList​(E... array)
                                              throws java.lang.IllegalArgumentException
        Creates a new ArrayList containing all elements from the specified array. The resulting list is modifiable, allowing for further additions or modifications after creation.

        If the given array is empty, the IllegalArgumentException will be thrown

        Example Usage

        
     String[] fruits = {"apple", "banana", "cherry"};
     List<String> fruitList = ListUtils.ofArrayList(fruits);
     System.out.println(fruitList); // Output: [apple, banana, cherry]
     fruitList.add("orange");       // return true
     System.out.println(fruitList); // Output: [apple, banana, cherry, orange]

     Integer[] numbers = {};
     List<Integer> numberList = ListUtils.ofArrayList(numbers); // throws IllegalArgumentException

     List<Integer> emptyList = ListUtils.ofLinkedList((Integer[]) null); // throws IllegalArgumentException
        Type Parameters:
        E - the type of elements in the array
        Parameters:
        array - the array to convert
        Returns:
        a new ArrayList containing all elements from the array
        Throws:
        java.lang.IllegalArgumentException - if the array is null or empty
        See Also:
        for creating an immutable version of the list

      • ofLinkedList

        public static <E> java.util.LinkedList<E> ofLinkedList​(E... array)
                                                throws java.lang.IllegalArgumentException
        Creates a new LinkedList containing all elements from the specified array.

        This method copies the elements from the provided array into a newly created linked list, allowing for efficient insertions and deletions. If the array is empty or null, an IllegalArgumentException will be thrown.

        Example Usage

        
     String[] fruits = {"apple", "banana", "cherry"};
     List<String> fruitList = ListUtils.ofLinkedList(fruits);
     System.out.println(fruitList); // Output: [apple, banana, cherry]
     fruitList.add("orange");       // return true
     System.out.println(fruitList); // Output: [apple, banana, cherry, orange]

     Integer[] numbers = {};
     List<Integer> numberList = ListUtils.ofLinkedList(numbers); // throws IllegalArgumentException

     List<Integer> emptyList = ListUtils.ofLinkedList((Integer[]) null); // throws IllegalArgumentException
        Type Parameters:
        E - the type of elements in the array
        Parameters:
        array - the array to convert
        Returns:
        a new LinkedList containing all elements from the array
        Throws:
        java.lang.IllegalArgumentException - if the array is null or empty
        See Also:
        for creating an immutable version of the list

      • forEach

        public static <T> void forEach​(java.util.List<T> values,
                               java.util.function.BiConsumer<java.lang.Integer,​T> indexedElementConsumer)
        Performs the given action for each element of the specified list, providing both the index and the element.

        This method iterates over the elements of the list and applies the provided bi-consumer function to each element along with its index. It is useful when operations need to take into account the position of the element in the list.

        Example Usage

        
     List<String> fruits = Arrays.asList("apple", "banana", "cherry");
     ListUtils.forEach(fruits, (index, fruit) -> System.out.println("Index: " + index + ", Fruit: " + fruit));
     // Output:
     // Index: 0, Fruit: apple
     // Index: 1, Fruit: banana
     // Index: 2, Fruit: cherry

     List<Integer> numbers = Collections.emptyList();
     ListUtils.forEach(numbers, (index, number) -> System.out.println("Index: " + index + ", Number: " + number));
     // No output, as the list is empty
        Type Parameters:
        T - the type of elements in the list
        Parameters:
        values - the list to iterate over
        indexedElementConsumer - the action to perform on each element, taking the index and the element as arguments

      • forEach

        public static <T> void forEach​(java.util.List<T> values,
                               java.util.function.Consumer<T> consumer)
        Performs the given action for each element of the specified list.

        This method ignores the index of elements and directly applies the provided consumer to each element in the list. It is useful when the operation does not require the element's index.

        Example Usage

        
     List<String> fruits = Arrays.asList("apple", "banana", "cherry");
     ListUtils.forEach(fruits, fruit -> System.out.println("Fruit: " + fruit));
     // Output:
     // Fruit: apple
     // Fruit: banana
     // Fruit: cherry

     List<Integer> numbers = Collections.emptyList();
     ListUtils.forEach(numbers, number -> System.out.println("Number: " + number));
     // No output, as the list is empty
        Type Parameters:
        T - the type of elements in the list
        Parameters:
        values - the list to iterate over
        consumer - the action to perform on each element