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

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

ofArrayList

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

ofLinkedList

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

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.
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.
ofArrayList	Creates a new ArrayList containing all elements from the specified array.
ofLinkedList	Creates a new LinkedList containing all elements from the specified array.

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

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

ofArrayList

public static <E> ArrayList<E> ofArrayList(E... array)

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 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 numberList = ListUtils.ofArrayList(numbers); // throws IllegalArgumentException

    List emptyList = ListUtils.ofLinkedList((Integer[]) null); // throws IllegalArgumentException

}

ofLinkedList

public static <E> LinkedList<E> ofLinkedList(E... array)

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 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 numberList = ListUtils.ofLinkedList(numbers); // throws IllegalArgumentException

    List emptyList = ListUtils.ofLinkedList((Integer[]) null); // throws IllegalArgumentException
}

See Also

• Lists
• List

---

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