Package io.microsphere.collection

Class CollectionUtils

  • All Implemented Interfaces:
    Utils
    public abstract class CollectionUtils
extends java.lang.Object
implements Utils
    The utilities class for Java Collection
    Author:
    Mercy
    See Also:
    Collections

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T> int addAll​(java.util.Collection<T> collection, T... values)
      Adds all the elements in the specified array to the given collection.
      static <T> java.util.Deque<T> emptyDeque()
      Returns an empty, immutable Deque instance that throws UnsupportedOperationException for all modification operations.
      static <E> java.lang.Iterable<E> emptyIterable()
      Returns an empty, immutable Iterable that contains no elements.
      static <E> java.util.Iterator<E> emptyIterator()
      Returns an empty iterator that contains no elements.
      static <T> java.util.Queue<T> emptyQueue()
      Returns an empty, immutable Queue that throws UnsupportedOperationException for all modification operations.
      static boolean equals​(java.util.Collection<?> one, java.util.Collection<?> another)
      Compares two collections for equality, considering null and empty collections as equal.
      static <T> T first​(java.lang.Iterable<T> values)
      Retrieves the first element from the given Iterable.
      static <T> T first​(java.util.Collection<T> values)
      Retrieves the first element from the given collection.
      static <T> T first​(java.util.Iterator<T> values)
      Retrieves the first element from the given Iterator.
      static boolean isEmpty​(java.util.Collection<?> collection)
      Checks if the provided collection is null or empty.
      static boolean isNotEmpty​(java.util.Collection<?> collection)
      Checks if the provided collection is not null and not empty.
      static <E> java.util.Enumeration<E> singletonEnumeration​(E element)
      Creates a singleton read-only Enumeration that contains only the specified element.
      static <E> java.lang.Iterable<E> singletonIterable​(E element)
      Creates a singleton Iterable that contains only the specified element.
      static <E> java.util.Iterator<E> singletonIterator​(E element)
      Creates a singleton read-only Iterator that contains only the specified element.
      static int size​(java.lang.Iterable<?> iterable)
      Returns the size of the specified Iterable.
      static int size​(java.util.Collection<?> collection)
      Returns the size of the specified Collection.
      static <E> java.lang.Iterable<E> toIterable​(java.util.Collection<E> collection)
      Converts a nullable Collection into an Iterable.
      static <E> java.lang.Iterable<E> toIterable​(java.util.Enumeration<E> enumeration)
      Converts a nullable Enumeration into an Iterable.
      static <E> java.lang.Iterable<E> toIterable​(java.util.Iterator<E> iterator)
      Converts a nullable Iterator into an Iterable.
      static <E> java.util.Iterator<E> toIterator​(java.util.Enumeration<E> enumeration)
      Converts a nullable Enumeration into an Iterator.
      static <E> java.util.Iterator<E> unmodifiableIterator​(java.util.Iterator<E> iterator)
      Returns an unmodifiable (read-only) view of the given iterator.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • isEmpty

        public static boolean isEmpty​(@Nullable
                              java.util.Collection<?> collection)
        Checks if the provided collection is null or empty.
        Parameters:
        collection - the collection to check
        Returns:
        true if the collection is null or empty, false otherwise

        Example Usage

        
 CollectionUtils.isEmpty(null)             // returns true
 CollectionUtils.isEmpty(Collections.emptyList())  // returns true
 CollectionUtils.isEmpty(Arrays.asList(1, 2, 3))     // returns false

      • isNotEmpty

        public static boolean isNotEmpty​(@Nullable
                                 java.util.Collection<?> collection)
        Checks if the provided collection is not null and not empty.
        Parameters:
        collection - the collection to check
        Returns:
        true if the collection is neither null nor empty, false otherwise

        Example Usage

        
 CollectionUtils.isNotEmpty(null)             // returns false
 CollectionUtils.isNotEmpty(Collections.emptyList())  // returns false
 CollectionUtils.isNotEmpty(Arrays.asList(1, 2, 3))     // returns true

      • toIterable

        @Nonnull
public static <E> java.lang.Iterable<E> toIterable​(@Nullable
                                                   java.util.Collection<E> collection)
        Converts a nullable Collection into an Iterable. If the provided collection is null, it returns an empty iterable.
        Type Parameters:
        E - the type of elements in the collection
        Parameters:
        collection - the collection to convert, may be null
        Returns:
        an Iterable backed by the given collection; never null

        Example Usage

        
 // Convert a non-null collection to iterable
 Collection<String> list = Arrays.asList("a", "b", "c");
 Iterable<String> iterable = CollectionUtils.toIterable(list);

 // Convert a null collection to iterable
 Iterable<String> emptyIterable = CollectionUtils.toIterable(null); // returns empty iterable

      • toIterable

        @Nonnull
public static <E> java.lang.Iterable<E> toIterable​(@Nullable
                                                   java.util.Iterator<E> iterator)
        Converts a nullable Iterator into an Iterable. If the provided iterator is null, it returns an empty iterable.
        Type Parameters:
        E - the type of elements in the iterator
        Parameters:
        iterator - the iterator to convert, may be null
        Returns:
        a non-null Iterable backed by the given iterator

        Example Usage

        
 // Convert a non-null iterator to iterable
 Iterator<String> iterator = Arrays.asList("a", "b", "c").iterator();
 Iterable<String> iterable = CollectionUtils.toIterable(iterator);

 // Convert a null iterator to iterable
 Iterable<String> emptyIterable = CollectionUtils.toIterable(null); // returns empty iterable

      • toIterator

        @Nonnull
public static <E> java.util.Iterator<E> toIterator​(@Nullable
                                                   java.util.Enumeration<E> enumeration)
        Converts a nullable Enumeration into an Iterator. If the provided enumeration is null, it returns an empty iterator.
        Type Parameters:
        E - the type of elements in the enumeration
        Parameters:
        enumeration - the enumeration to convert, may be null
        Returns:
        a non-null Iterator backed by the given enumeration

        Example Usage

        
 // Convert a non-null enumeration to iterator
 Enumeration<String> enumeration = Collections.enumeration(Arrays.asList("a", "b", "c"));
 Iterator<String> iterator = CollectionUtils.toIterator(enumeration);

 // Convert a null enumeration to iterator
 Iterator<String> emptyIterator = CollectionUtils.toIterator(null); // returns empty iterator

      • toIterable

        @Nonnull
public static <E> java.lang.Iterable<E> toIterable​(@Nullable
                                                   java.util.Enumeration<E> enumeration)
        Converts a nullable Enumeration into an Iterable. If the provided enumeration is null, it returns an empty iterable.
        Type Parameters:
        E - the type of elements in the enumeration
        Parameters:
        enumeration - the enumeration to convert, may be null
        Returns:
        a non-null Iterable backed by the given enumeration

        Example Usage

        
 // Convert a non-null enumeration to iterable
 Enumeration<String> enumeration = Collections.enumeration(Arrays.asList("a", "b", "c"));
 Iterable<String> iterable = CollectionUtils.toIterable(enumeration);

 // Convert a null enumeration to iterable
 Iterable<String> emptyIterable = CollectionUtils.toIterable(null); // returns empty iterable

      • singletonIterable

        @Nonnull
@Immutable
public static <E> java.lang.Iterable<E> singletonIterable​(@Nullable
                                                          E element)
        Creates a singleton Iterable that contains only the specified element. If the provided element is null, returns an empty iterable.
        Type Parameters:
        E - the type of the element
        Parameters:
        element - the single element to be contained in the iterable, may be null
        Returns:
        a non-null Iterable containing the single element or an empty iterable if element is null

        Example Usage

        
 // Create an iterable with a non-null element
 Iterable<String> iterable1 = CollectionUtils.singletonIterable("hello");

 // Create an empty iterable from a null element
 Iterable<String> iterable2 = CollectionUtils.singletonIterable(null);

      • singletonIterator

        @Nonnull
@Immutable
public static <E> java.util.Iterator<E> singletonIterator​(@Nullable
                                                          E element)
        Creates a singleton read-only Iterator that contains only the specified element. If the provided element is null, returns an iterator with no elements.

        The returned iterator is read-only and cannot be used to remove elements.

        Type Parameters:
        E - the type of the element
        Parameters:
        element - the single element to be contained in the iterator, may be null
        Returns:
        a non-null read-only Iterator containing the single element or an empty iterator if element is null

        Example Usage

        
 // Create an iterator with a non-null element
 Iterator<String> iterator1 = CollectionUtils.singletonIterator("hello");

 // Create an empty iterator from a null element
 Iterator<String> iterator2 = CollectionUtils.singletonIterator(null);

      • singletonEnumeration

        @Nonnull
@Immutable
public static <E> java.util.Enumeration<E> singletonEnumeration​(@Nullable
                                                                E element)
        Creates a singleton read-only Enumeration that contains only the specified element. If the provided element is null, returns an enumeration with no elements.

        The returned enumeration is read-only and cannot be used to remove elements.

        Type Parameters:
        E - the type of the element
        Parameters:
        element - the single element to be contained in the enumeration, may be null
        Returns:
        a non-null read-only Enumeration containing the single element or an empty enumeration if element is null

        Example Usage

        
 // Create an enumeration with a non-null element
 Enumeration<String> enumeration1 = CollectionUtils.singletonEnumeration("hello");

 // Create an empty enumeration from a null element
 Enumeration<String> enumeration2 = CollectionUtils.singletonEnumeration(null);

      • unmodifiableIterator

        @Nonnull
@Immutable
public static <E> java.util.Iterator<E> unmodifiableIterator​(@Nullable
                                                             java.util.Iterator<E> iterator)
        Returns an unmodifiable (read-only) view of the given iterator. Attempts to modify the underlying data structure via the returned iterator will result in an UnsupportedOperationException.

        If the provided iterator is null, this method returns an empty unmodifiable iterator.

        Type Parameters:
        E - the type of elements returned by the iterator
        Parameters:
        iterator - the iterator to wrap as unmodifiable, may be null
        Returns:
        a non-null read-only Iterator backed by the given iterator

        Example Usage

        
 // Wrap a valid iterator into an unmodifiable one
 Iterator<String> modifiable = Arrays.asList("a", "b", "c").iterator();
 Iterator<String> unmodifiable = CollectionUtils.unmodifiableIterator(modifiable);

 // Attempting to remove will throw an exception
 if (unmodifiable.hasNext()) {
     unmodifiable.next();
     unmodifiable.remove();  // throws UnsupportedOperationException
 }

 // Passing null returns an empty unmodifiable iterator
 Iterator<String> empty = CollectionUtils.unmodifiableIterator(null);
 assert !empty.hasNext();

      • emptyIterator

        @Nonnull
@Immutable
public static <E> java.util.Iterator<E> emptyIterator()
        Returns an empty iterator that contains no elements.

        Any call to Iterator.hasNext() will return false, and any call to Iterator.next() will throw a NoSuchElementException.

        Type Parameters:
        E - the type of elements returned by this iterator (though none will be returned)
        Returns:
        a non-null, read-only empty iterator

        Example Usage

        
 Iterator<String> emptyIterator = CollectionUtils.emptyIterator();
 System.out.println(emptyIterator.hasNext()); // prints: false

      • emptyIterable

        @Nonnull
@Immutable
public static <E> java.lang.Iterable<E> emptyIterable()
        Returns an empty, immutable Iterable that contains no elements.

        Any attempt to iterate over the returned iterable will result in:

        • Iterator.hasNext() always returns false
        • Iterator.next() throws a NoSuchElementException
        Type Parameters:
        E - the type of elements (though none will be present)
        Returns:
        a non-null, read-only empty iterable

        Example Usage

        
 Iterable<String> empty = CollectionUtils.emptyIterable();
 System.out.println(empty.iterator().hasNext()); // prints: false

      • size

        public static int size​(@Nullable
                       java.util.Collection<?> collection)
        Returns the size of the specified Collection.

        If the provided collection is null, this method returns 0.

        Parameters:
        collection - the specified Collection, may be null
        Returns:
        the size of the collection, or 0 if it is null

        Example Usage

        
 CollectionUtils.size(null)             // returns 0
 CollectionUtils.size(Collections.emptyList())  // returns 0
 CollectionUtils.size(Arrays.asList(1, 2, 3))     // returns 3

      • size

        public static int size​(@Nullable
                       java.lang.Iterable<?> iterable)
        Returns the size of the specified Iterable.

        If the provided iterable is null, this method returns 0.

        Parameters:
        iterable - the specified Iterable, may be null
        Returns:
        the number of elements in the iterable, or 0 if it is null

        Example Usage

        
 CollectionUtils.size((Iterable<?>) null)        // returns 0

 Iterable<String> emptyList = Collections.emptyList();
 CollectionUtils.size(emptyList)                // returns 0

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

 Iterable<String> singleton = CollectionUtils.singletonIterable("hello");
 CollectionUtils.size(singleton)                // returns 1

      • equals

        public static boolean equals​(@Nullable
                             java.util.Collection<?> one,
                             @Nullable
                             java.util.Collection<?> another)
        Compares two collections for equality, considering null and empty collections as equal.

        Two collections are considered equal if they contain the same elements in any order, and their sizes are equal. If both collections are null or both are empty, they are also considered equal.

        Example Usage

        
 CollectionUtils.equals(null, null)             // returns true
 CollectionUtils.equals(Collections.emptyList(), null)  // returns true
 CollectionUtils.equals(Arrays.asList(1, 2, 3), Arrays.asList(3, 2, 1)) // returns true
 CollectionUtils.equals(Arrays.asList(1, 2), Arrays.asList(1, 2, 3))     // returns false
        Parameters:
        one - the first collection to compare, may be null
        another - the second collection to compare, may be null
        Returns:
        true if the collections are considered equal, otherwise false

      • addAll

        public static <T> int addAll​(@Nullable
                             java.util.Collection<T> collection,
                             T... values)
        Adds all the elements in the specified array to the given collection.

        If the provided collection is null or empty, no elements are added, and 0 is returned. If the array is null or has no elements, 0 is also returned.

        Type Parameters:
        T - the type of elements in the collection and array
        Parameters:
        collection - the collection to which elements are to be added, may be null or empty
        values - the array of elements to add, may be null
        Returns:
        the number of elements successfully added to the collection

        Example Usage

        
 Collection<String> collection = new ArrayList<>();
 int count1 = CollectionUtils.addAll(collection, "a", "b", "c"); // returns 3

 int count2 = CollectionUtils.addAll(null, "a", "b"); // returns 0

 int count3 = CollectionUtils.addAll(collection, (String[]) null); // returns 0

 Collection<String> emptyCollection = Collections.emptyList();
 int count4 = CollectionUtils.addAll(emptyCollection, "x"); // returns 0

      • first

        @Nullable
public static <T> T first​(@Nullable
                          java.util.Collection<T> values)
        Retrieves the first element from the given collection.

        If the collection is null or empty, this method returns null. If the collection is an instance of a list, it delegates to ListUtils.first(List). Otherwise, it retrieves the first element using the iterator obtained from the collection.

        Example Usage

        
 Collection<String> list = Arrays.asList("a", "b", "c");
 String result1 = CollectionUtils.first(list); // returns "a"

 Collection<String> empty = Collections.emptyList();
 String result2 = CollectionUtils.first(empty); // returns null

 Collection<String> nullCollection = null;
 String result3 = CollectionUtils.first(nullCollection); // returns null
        Type Parameters:
        T - the type of elements in the collection
        Parameters:
        values - the collection to retrieve the first element from, may be null
        Returns:
        the first element if available; otherwise, null

      • first

        @Nullable
public static <T> T first​(@Nullable
                          java.lang.Iterable<T> values)
        Retrieves the first element from the given Iterable.

        If the iterable is null or has no elements, this method returns null.

        Type Parameters:
        T - the type of elements in the iterable
        Parameters:
        values - the iterable to retrieve the first element from, may be null
        Returns:
        the first element if available; otherwise, null

        Example Usage

        
 // Get the first element from a non-empty iterable
 Iterable<String> iterable1 = Arrays.asList("apple", "banana");
 String result1 = CollectionUtils.first(iterable1); // returns "apple"

 // Get the first element from an empty iterable
 Iterable<String> iterable2 = Collections.emptyList();
 String result2 = CollectionUtils.first(iterable2); // returns null

 // Get the first element from a null iterable
 String result3 = CollectionUtils.first(null); // returns null

      • first

        @Nullable
public static <T> T first​(@Nullable
                          java.util.Iterator<T> values)
        Retrieves the first element from the given Iterator.

        If the iterator is null or has no elements, this method returns null.

        Type Parameters:
        T - the type of elements in the iterator
        Parameters:
        values - the iterator to retrieve the first element from, may be null
        Returns:
        the first element if available; otherwise, null

        Example Usage

        
 // Get the first element from a non-empty iterator
 Iterator<String> iterator1 = Arrays.asList("apple", "banana").iterator();
 String result1 = CollectionUtils.first(iterator1); // returns "apple"

 // Get the first element from an empty iterator
 Iterator<String> iterator2 = Collections.emptyIterator();
 String result2 = CollectionUtils.first(iterator2); // returns null

 // Get the first element from a null iterator
 String result3 = CollectionUtils.first(null); // returns null

      • emptyQueue

        @Nonnull
@Immutable
public static <T> java.util.Queue<T> emptyQueue()
        Returns an empty, immutable Queue that throws UnsupportedOperationException for all modification operations.

        This method returns a singleton instance of an empty queue. Any attempt to modify the returned queue will result in an UnsupportedOperationException. It is useful as a placeholder or default value where an empty queue is needed without creating a new instance every time.

        Example Usage

        
 Queue<String> emptyQueue = CollectionUtils.emptyQueue();

 System.out.println(emptyQueue.isEmpty()); // true
 System.out.println(emptyQueue.size());    // 0

 try {
     emptyQueue.add("test");
 } catch (UnsupportedOperationException e) {
     System.out.println("Modification not allowed"); // This block will execute
 }
        Type Parameters:
        T - the type of elements held in the returned queue
        Returns:
        an empty and immutable queue instance
        See Also:
        EmptyDeque

      • emptyDeque

        @Nonnull
@Immutable
public static <T> java.util.Deque<T> emptyDeque()
        Returns an empty, immutable Deque instance that throws UnsupportedOperationException for all modification operations.

        This method returns a singleton instance of an empty deque. Any attempt to modify the returned deque will result in an UnsupportedOperationException. It is useful as a placeholder or default value where an empty deque is needed without creating a new instance every time.

        Example Usage

        
 Deque<String> emptyDeque = CollectionUtils.emptyDeque();

 System.out.println(emptyDeque.isEmpty()); // true
 System.out.println(emptyDeque.size());    // 0

 try {
     emptyDeque.add("test");
 } catch (UnsupportedOperationException e) {
     System.out.println("Modification not allowed"); // This block will execute
 }
        Type Parameters:
        T - the type of elements held in this deque
        Returns:
        an empty and immutable deque instance
        See Also:
        EmptyDeque