java8.util

Class Lists2

java.lang.Object

java8.util.Lists2

public final class Lists2
extends Object

A place for the new Java 9 JEP 269 "Immutable List Static Factory Methods" in the List interface.

Immutable List Static Factory Methods

The Lists.of() static factory methods provide a convenient way to create immutable lists. The List instances created by these methods have the following characteristics:

• They are structurally immutable. Elements cannot be added, removed, or replaced. Calling any mutator method will always cause UnsupportedOperationException to be thrown. However, if the contained elements are themselves mutable, this may cause the List's contents to appear to change.
• They disallow null elements. Attempts to create them with null elements result in NullPointerException.
• They are serializable if all elements are serializable.
• The order of elements in the list is the same as the order of the provided arguments, or of the elements in the provided array.
• They are value-based. Callers should make no assumptions about the identity of the returned instances. Factories are free to create new instances or reuse existing ones. Therefore, identity-sensitive operations on these instances (reference equality ( ==), identity hash code, and synchronization) are unreliable and should be avoided.

Method Summary

Modifier and Type	Method and Description
static <E> List<E>	of() Returns an immutable list containing zero elements.
static <E> List<E>	of(E... elements) Returns an immutable list containing an arbitrary number of elements.
static <E> List<E>	of(E e1) Returns an immutable list containing one element.
static <E> List<E>	of(E e1, E e2) Returns an immutable list containing two elements.
static <E> List<E>	of(E e1, E e2, E e3) Returns an immutable list containing three elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4) Returns an immutable list containing four elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5) Returns an immutable list containing five elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6) Returns an immutable list containing six elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) Returns an immutable list containing seven elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) Returns an immutable list containing eight elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) Returns an immutable list containing nine elements.
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) Returns an immutable list containing ten elements.

Methods inherited from class java.lang.Object

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

Method Detail

of

public static <E> List<E> of()

Returns an immutable list containing zero elements. See Immutable List Static Factory Methods for details.

Type Parameters:

E - the List's element type

Returns:

an empty List

Since:

9

of

public static <E> List<E> of(E e1)

Returns an immutable list containing one element. See Immutable List Static Factory Methods for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the single element

Returns:

a List containing the specified element

Throws:

NullPointerException - if the element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2)

Returns an immutable list containing two elements. See Immutable List Static Factory Methods for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3)

Returns an immutable list containing three elements. See Immutable List Static Factory Methods for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4)

Returns an immutable list containing four elements. See Immutable List Static Factory Methods for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5)

Returns an immutable list containing five elements. See Immutable List Static Factory Methods for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6)

Returns an immutable list containing six elements. See Immutable List Static Factory Methods for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

e6 - the sixth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6,
                             E e7)

Returns an immutable list containing seven elements. See Immutable List Static Factory Methods for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

e6 - the sixth element

e7 - the seventh element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6,
                             E e7,
                             E e8)

Returns an immutable list containing eight elements. See Immutable List Static Factory Methods for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

e6 - the sixth element

e7 - the seventh element

e8 - the eighth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6,
                             E e7,
                             E e8,
                             E e9)

Returns an immutable list containing nine elements. See Immutable List Static Factory Methods for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

e6 - the sixth element

e7 - the seventh element

e8 - the eighth element

e9 - the ninth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6,
                             E e7,
                             E e8,
                             E e9,
                             E e10)

Returns an immutable list containing ten elements. See Immutable List Static Factory Methods for details.

Type Parameters:

E - the List's element type

Parameters:

e1 - the first element

e2 - the second element

e3 - the third element

e4 - the fourth element

e5 - the fifth element

e6 - the sixth element

e7 - the seventh element

e8 - the eighth element

e9 - the ninth element

e10 - the tenth element

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null

Since:

9

of

public static <E> List<E> of(E... elements)

Returns an immutable list containing an arbitrary number of elements. See Immutable List Static Factory Methods for details.

API Note:
This method also accepts a single array as an argument. The element type of the resulting list will be the component type of the array, and the size of the list will be equal to the length of the array. To create a list with a single element that is an array, do the following:

     String[] array = ... ;
     List<String[]> list = Lists.<String[]>of(array);
 

This will cause the Lists.of(E) method to be invoked instead.

Type Parameters:

E - the List's element type

Parameters:

elements - the elements to be contained in the list

Returns:

a List containing the specified elements

Throws:

NullPointerException - if an element is null or if the array is null

Since:

9