io microsphere collection ListUtils

ListUtils

Type: Class | Module: microsphere-java-core | Package: io.microsphere.collection | Since: 1.0.0

Source: microsphere-java-core/src/main/java/io/microsphere/collection/ListUtils.java

Overview

The utilities class for Java List

Declaration

public abstract class ListUtils implements Utils

Author: Mercy

Version Information

• Introduced in: 1.0.0
• Current Project Version: 0.3.6-SNAPSHOT

Version Compatibility

This component is tested and compatible with the following Java versions:

Java Version	Status
Java 8	✅ Compatible
Java 11	✅ Compatible
Java 17	✅ Compatible
Java 21	✅ Compatible
Java 25	✅ Compatible

Examples

Method Examples

isList

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

isList

boolean result1 = ListUtils.isList(ArrayList.class);  // returns true
    boolean result2 = ListUtils.isList(String.class);     // returns false
    boolean result3 = ListUtils.isList(List.class);       // returns true

first

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

last

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

of

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: []

ofList

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: []

ofList

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: []

ofList

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: []

ofList

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: []

newArrayList

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

    list.add("Hello");
    System.out.println(list); // Output: [Hello]

newArrayList

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

    list.add("Hello");
    System.out.println(list); // Output: [Hello]

newArrayList

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: []

newArrayList

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: []

newArrayList

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: []

newArrayList

Set<String> fruits = new HashSet<>(Arrays.asList("apple", "banana", "cherry"));
    List<String> listCopy = ListUtils.newArrayList(fruits);
    System.out.println(listCopy.size()); // Output: 3

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

newLinkedList

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

    list.add("Hello");
    System.out.println(list); // Output: [Hello]

newLinkedList

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: []

newLinkedList

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: []

newLinkedList

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: []

newLinkedList

Set<String> fruits = new HashSet<>(Arrays.asList("apple", "banana", "cherry"));
    List<String> listCopy = ListUtils.newLinkedList(fruits);
    System.out.println(listCopy.size()); // Output: 3

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

Usage

Maven Dependency

Add the following dependency to your pom.xml:

<dependency>
    <groupId>io.github.microsphere-projects</groupId>
    <artifactId>microsphere-java-core</artifactId>
    <version>${microsphere-java.version}</version>
</dependency>

Tip: Use the BOM (microsphere-java-dependencies) for consistent version management. See the Getting Started guide.

Import

import io.microsphere.collection.ListUtils;

API Reference

Public Methods

Method	Description
isList	Checks if the specified object is an instance of List.
isList	Checks if the specified type is assignable from List.
first	Retrieves the first element from the specified list.
last	Retrieves the last element from the specified list.
of	Creates an immutable list from the given elements.
ofList	Creates an immutable list from the given array of elements.
ofList	Creates an immutable list from the specified Iterable.
ofList	Creates an immutable list from the specified Enumeration.
ofList	Creates an immutable list from the specified Iterator.
newArrayList	Creates a new empty ArrayList instance.
newArrayList	Creates a new ArrayList instance with the specified initial capacity.
newArrayList	Creates a new LinkedList instance from the specified Enumeration.
newArrayList	Creates a new ArrayList instance containing all elements from the specified Iterable.
newArrayList	Creates a new ArrayList instance containing all elements from the specified Iterator.
newArrayList	Creates a new ArrayList instance containing all elements from the specified Collection.
newLinkedList	Creates a new empty LinkedList instance.
newLinkedList	Creates a new LinkedList instance from the specified Enumeration.
newLinkedList	Creates a new LinkedList instance containing all elements from the specified Iterable.
newLinkedList	Creates a new LinkedList instance containing all elements from the specified Iterator.
newLinkedList	Creates a new LinkedList instance containing all elements from the specified Collection.

Method Details

isList

public static boolean isList(@Nullable Object values)

Checks if the specified object is an instance of List.

Example Usage

`List 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
`

isList

public static boolean isList(@Nullable 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
`

first

public static <E> E first(List<E> list)

Retrieves the first element from the specified list.

Example Usage

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

    List emptyList = Collections.emptyList();
    String firstString = first(emptyList); // returns null
`

last

public static <E> E last(List<E> list)

Retrieves the last element from the specified list.

Example Usage

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

    List emptyList = Collections.emptyList();
    String lastString = last(emptyList); // returns null
`

of

public static <E> 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 fruits = ListUtils.of("apple", "banana", "cherry");
    System.out.println(fruits); // Output: [apple, banana, cherry]

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

    List emptyList = ListUtils.of();
    System.out.println(emptyList); // Output: []
`

ofList

public static <E> 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 fruits = ListUtils.ofList("apple", "banana", "cherry");
    System.out.println(fruits); // Output: [apple, banana, cherry]

    String[] names = {`;
    List emptyList = ListUtils.ofList(names);
    System.out.println(emptyList); // Output: []
}

ofList

public static <E> List<E> ofList(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 fruits = new HashSet<>(Arrays.asList("apple", "banana", "cherry"));
    List fruitsList = ListUtils.ofList(fruits);
    System.out.println(fruitsList); // Output: [apple, banana, cherry]

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

    List emptyList = ListUtils.ofList((Iterable) null);
    System.out.println(emptyList); // Output: []
`

ofList

public static <E> List<E> ofList(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 vector = new Vector<>(Arrays.asList("one", "two", "three"));
    List list = ListUtils.ofList(vector.elements());
    System.out.println(list); // Output: [one, two, three]

    List emptyList = ListUtils.ofList((Enumeration) null);
    System.out.println(emptyList); // Output: []
`

ofList

public static <E> List<E> ofList(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 fruits = ListUtils.ofList(Arrays.asList("apple", "banana", "cherry").iterator());
    System.out.println(fruits); // Output: [apple, banana, cherry]

    List numbers = ListUtils.ofList((Iterator) null);
    System.out.println(numbers); // Output: []
`

newArrayList

public static <E> 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 list = ListUtils.newArrayList();
    System.out.println(list.isEmpty()); // Output: true

    list.add("Hello");
    System.out.println(list); // Output: [Hello]
`

newArrayList

public static <E> 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 list = ListUtils.newArrayList(10);
    System.out.println(list.isEmpty()); // Output: true

    list.add("Hello");
    System.out.println(list); // Output: [Hello]
`

newArrayList

public static <E> ArrayList<E> newArrayList(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 vector = new Vector<>(Arrays.asList("apple", "banana", "cherry"));
    List list = ListUtils.newArrayList(vector.elements());
    System.out.println(list); // Output: [apple, banana, cherry]

    List emptyList = ListUtils.newArrayList((Enumeration) null);
    System.out.println(emptyList); // Output: []
`

newArrayList

public static <E> ArrayList<E> newArrayList(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 fruits = Arrays.asList("apple", "banana", "cherry");
    List listCopy = ListUtils.newArrayList(fruits);
    System.out.println(listCopy); // Output: [apple, banana, cherry]

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

    List emptyList = ListUtils.newArrayList((Iterable) null);
    System.out.println(emptyList); // Output: []
`

newArrayList

public static <E> ArrayList<E> newArrayList(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 fruits = Arrays.asList("apple", "banana", "cherry");
    List listCopy = ListUtils.newArrayList(fruits.iterator());
    System.out.println(listCopy); // Output: [apple, banana, cherry]

    List numbers = ListUtils.newArrayList((Iterator) null);
    System.out.println(numbers); // Output: []
`

newArrayList

public static <E> ArrayList<E> newArrayList(Collection<? extends E> elements)

Creates a new ArrayList instance containing all elements from the specified Collection.

This method delegates to the ArrayList constructor that accepts a collection, ensuring all elements from the input collection are included in the resulting list. The returned list is modifiable and allows null elements.

Example Usage

`Set fruits = new HashSet<>(Arrays.asList("apple", "banana", "cherry"));
    List listCopy = ListUtils.newArrayList(fruits);
    System.out.println(listCopy.size()); // Output: 3

    List emptyList = ListUtils.newArrayList(Collections.emptyList());
    System.out.println(emptyList.isEmpty()); // Output: true
`

newLinkedList

public static <E> 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 list = ListUtils.newLinkedList();
    System.out.println(list.isEmpty()); // Output: true

    list.add("Hello");
    System.out.println(list); // Output: [Hello]
`

newLinkedList

public static <E> LinkedList<E> newLinkedList(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 vector = new Vector<>(Arrays.asList("apple", "banana", "cherry"));
    List list = ListUtils.newLinkedList(vector.elements());
    System.out.println(list); // Output: [apple, banana, cherry]

    List emptyList = ListUtils.newLinkedList((Enumeration) null);
    System.out.println(emptyList); // Output: []
`

newLinkedList

public static <E> LinkedList<E> newLinkedList(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 fruits = Arrays.asList("apple", "banana", "cherry");
    List listCopy = ListUtils.newLinkedList(fruits);
    System.out.println(listCopy); // Output: [apple, banana, cherry]

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

    List emptyList = ListUtils.newLinkedList((Iterable) null);
    System.out.println(emptyList); // Output: []
`

newLinkedList

public static <E> LinkedList<E> newLinkedList(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 fruits = Arrays.asList("apple", "banana", "cherry");
    List listCopy = ListUtils.newLinkedList(fruits.iterator());
    System.out.println(listCopy); // Output: [apple, banana, cherry]

    List numbers = ListUtils.newLinkedList((Iterator) null);
    System.out.println(numbers); // Output: []
`

newLinkedList

public static <E> LinkedList<E> newLinkedList(Collection<? extends E> elements)

Creates a new LinkedList instance containing all elements from the specified Collection.

This method delegates to the LinkedList constructor that accepts a collection, ensuring all elements from the input collection are included in the resulting list. The returned list is modifiable and allows null elements.

Example Usage

`Set fruits = new HashSet<>(Arrays.asList("apple", "banana", "cherry"));
    List listCopy = ListUtils.newLinkedList(fruits);
    System.out.println(listCopy.size()); // Output: 3

    List emptyList = ListUtils.newLinkedList(Collections.emptyList());
    System.out.println(emptyList.isEmpty()); // Output: true
`

See Also

• Lists
• List

---

This documentation was auto-generated from the source code of microsphere-java.