java8.util.Lists Maven / Gradle / Ivy
Show all versions of streamsupport Show documentation
/*
* Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java8.util;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.List;
import java.util.ListIterator;
import java8.util.function.UnaryOperator;
/**
* A place for static default implementations of the new Java 8 default
* interface methods and static interface methods in the {@link List} interface
* and, in addition, the JEP 269
* {@code "Unmodifiable List Static Factory Methods"} in the {@link List}
* interface that were introduced in Java 9.
*
* Unmodifiable Lists
*
* The {@link Lists#of(Object...) Lists.of} and {@link Lists#copyOf
* Lists.copyOf} static factory methods provide a convenient way to create
* unmodifiable lists. The {@code List} instances created by these methods have
* the following characteristics:
*
*
* - They are unmodifiable. Elements cannot
* be added, removed, or replaced. Calling any mutator method on the List
* will always cause {@code 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 {@code null} elements. Attempts to create them with
* {@code null} elements result in {@code 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 ( {@code ==}), identity hash code, and synchronization) are
* unreliable and should be avoided.
*
*/
public final class Lists {
/**
* Sorts the passed list according to the order induced by the specified
* {@link Comparator}. The sort is stable: this method does not
* reorder equal elements.
*
* All elements in the list must be mutually comparable using the
* specified comparator (that is, {@code c.compare(e1, e2)} must not throw
* a {@code ClassCastException} for any elements {@code e1} and {@code e2}
* in the list).
*
*
If the specified comparator is {@code null} then all elements in the
* list must implement the {@link Comparable} interface and the elements'
* {@linkplain Comparable natural ordering} should be used.
*
*
The list must be modifiable, but need not be resizable.
*
*
Implementation Requirements:
* The implementation obtains an array containing all elements in
* the list, sorts the array, and iterates over the list resetting each
* element from the corresponding position in the array. (This avoids the
* n2 log(n) performance that would result from attempting
* to sort a linked list in place.)
*
* @param the type of the elements of the list to be sorted
* @param list the list that should be sorted
* @param c the {@code Comparator} used to compare list elements.
* A {@code null} value indicates that the elements'
* {@linkplain Comparable natural ordering} should be used
* @throws ClassCastException if the list contains elements that are not
* mutually comparable using the specified comparator
* @throws UnsupportedOperationException if the list's list-iterator does
* not support the {@code set} operation
* @throws IllegalArgumentException (optional)
* if the comparator is found to violate the {@link Comparator}
* contract
* @throws NullPointerException if the specified list is null
* @since 1.8
*/
public static void sort(List list, Comparator c) {
Collections.sort(list, c);
}
/**
* Replaces each element of the passed list with the result of applying the
* operator to that element. Errors or runtime exceptions thrown by
* the operator are relayed to the caller.
*
* Implementation Requirements:
* The default implementation is equivalent to, for the passed {@code list}:
*
{@code
* final ListIterator li = list.listIterator();
* while (li.hasNext()) {
* li.set(operator.apply(li.next()));
* }
* }
*
* If the list's list-iterator does not support the {@code set} operation
* then an {@code UnsupportedOperationException} will be thrown when
* replacing the first element.
*
* @param the type of the elements of the list to be replaced
* @param list the list whose elements should be replaced
* @param operator the operator to apply to each element
* @throws UnsupportedOperationException if the passed list is unmodifiable.
* Implementations may throw this exception if an element
* cannot be replaced or if, in general, modification is not
* supported
* @throws NullPointerException if the specified list is null or the specified
* operator is null or if the operator result is a null value and the
* passed list does not permit null elements (optional)
* @since 1.8
*/
public static void replaceAll(List list, UnaryOperator operator) {
Objects.requireNonNull(list);
Objects.requireNonNull(operator);
ListIterator li = list.listIterator();
while (li.hasNext()) {
li.set(operator.apply(li.next()));
}
}
/**
* Creates a {@link Spliterator} over the elements in the passed list.
*
* The {@code Spliterator} reports at least {@link Spliterator#SIZED},
* {@link Spliterator#ORDERED} and {@link Spliterator#SUBSIZED}.
*
*
Implementation Note:
* This implementation delegates to {@link Spliterators#spliterator(java.util.Collection)}
* so it is effectively the same as calling
*
{@code
* Spliterators.spliterator(list);
* }
*
* @param the type of the elements of the list to be splitted
* @param list the list to be splitted
* @return a {@code Spliterator} over the elements in the passed list
* @since 1.8
*/
public static Spliterator spliterator(List list) {
return Spliterators.spliterator(list);
}
/**
* Returns an unmodifiable list containing zero elements.
*
* See Unmodifiable Lists for details.
*
* @param the {@code List}'s element type
* @return an empty {@code List}
*
* @since 9
*/
@SuppressWarnings("unchecked")
public static List of() {
return (List) ImmutableCollections.EMPTY_LIST;
}
/**
* Returns an unmodifiable list containing one element.
*
* See Unmodifiable Lists for details.
*
* @param the {@code List}'s element type
* @param e1 the single element
* @return a {@code List} containing the specified element
* @throws NullPointerException if the element is {@code null}
*
* @since 9
*/
public static List of(E e1) {
return new ImmutableCollections.List12(e1);
}
/**
* Returns an unmodifiable list containing two elements.
*
* See Unmodifiable Lists for details.
*
* @param the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @return a {@code List} containing the specified elements
* @throws NullPointerException if an element is {@code null}
*
* @since 9
*/
public static List of(E e1, E e2) {
return new ImmutableCollections.List12(e1, e2);
}
/**
* Returns an unmodifiable list containing three elements.
*
* See Unmodifiable Lists for details.
*
* @param the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
* @return a {@code List} containing the specified elements
* @throws NullPointerException if an element is {@code null}
*
* @since 9
*/
public static List of(E e1, E e2, E e3) {
return ImmutableCollections.listFromTrustedArray(e1, e2, e3);
}
/**
* Returns an unmodifiable list containing four elements.
*
* See Unmodifiable Lists for details.
*
* @param the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
* @param e4 the fourth element
* @return a {@code List} containing the specified elements
* @throws NullPointerException if an element is {@code null}
*
* @since 9
*/
public static List of(E e1, E e2, E e3, E e4) {
return ImmutableCollections.listFromTrustedArray(e1, e2, e3, e4);
}
/**
* Returns an unmodifiable list containing five elements.
*
* See Unmodifiable Lists for details.
*
* @param the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
* @param e4 the fourth element
* @param e5 the fifth element
* @return a {@code List} containing the specified elements
* @throws NullPointerException if an element is {@code null}
*
* @since 9
*/
public static List of(E e1, E e2, E e3, E e4, E e5) {
return ImmutableCollections.listFromTrustedArray(e1, e2, e3, e4, e5);
}
/**
* Returns an unmodifiable list containing six elements.
*
* See Unmodifiable Lists for details.
*
* @param the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
* @param e4 the fourth element
* @param e5 the fifth element
* @param e6 the sixth element
* @return a {@code List} containing the specified elements
* @throws NullPointerException if an element is {@code null}
*
* @since 9
*/
public static List of(E e1, E e2, E e3, E e4, E e5, E e6) {
return ImmutableCollections.listFromTrustedArray(e1, e2, e3, e4, e5,
e6);
}
/**
* Returns an unmodifiable list containing seven elements.
*
* See Unmodifiable Lists for details.
*
* @param the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
* @param e4 the fourth element
* @param e5 the fifth element
* @param e6 the sixth element
* @param e7 the seventh element
* @return a {@code List} containing the specified elements
* @throws NullPointerException if an element is {@code null}
*
* @since 9
*/
public static List of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
return ImmutableCollections.listFromTrustedArray(e1, e2, e3, e4, e5,
e6, e7);
}
/**
* Returns an unmodifiable list containing eight elements.
*
* See Unmodifiable Lists for details.
*
* @param the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
* @param e4 the fourth element
* @param e5 the fifth element
* @param e6 the sixth element
* @param e7 the seventh element
* @param e8 the eighth element
* @return a {@code List} containing the specified elements
* @throws NullPointerException if an element is {@code null}
*
* @since 9
*/
public static List of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
return ImmutableCollections.listFromTrustedArray(e1, e2, e3, e4, e5,
e6, e7, e8);
}
/**
* Returns an unmodifiable list containing nine elements.
*
* See Unmodifiable Lists for details.
*
* @param the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
* @param e4 the fourth element
* @param e5 the fifth element
* @param e6 the sixth element
* @param e7 the seventh element
* @param e8 the eighth element
* @param e9 the ninth element
* @return a {@code List} containing the specified elements
* @throws NullPointerException if an element is {@code null}
*
* @since 9
*/
public static List of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
return ImmutableCollections.listFromTrustedArray(e1, e2, e3, e4, e5,
e6, e7, e8, e9);
}
/**
* Returns an unmodifiable list containing ten elements.
*
* See Unmodifiable Lists for details.
*
* @param the {@code List}'s element type
* @param e1 the first element
* @param e2 the second element
* @param e3 the third element
* @param e4 the fourth element
* @param e5 the fifth element
* @param e6 the sixth element
* @param e7 the seventh element
* @param e8 the eighth element
* @param e9 the ninth element
* @param e10 the tenth element
* @return a {@code List} containing the specified elements
* @throws NullPointerException if an element is {@code null}
*
* @since 9
*/
public static List of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) {
return ImmutableCollections.listFromTrustedArray(e1, e2, e3, e4, e5,
e6, e7, e8, e9, e10);
}
/**
* Returns an unmodifiable list containing an arbitrary number of elements.
* See Unmodifiable Lists 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:
*
*
{@code
* String[] array = ... ;
* List list = Lists.of(array);
* }
*
* This will cause the {@link Lists#of(Object) Lists.of(E)} method
* to be invoked instead.
*
* @param the {@code List}'s element type
* @param elements the elements to be contained in the list
* @return a {@code List} containing the specified elements
* @throws NullPointerException if an element is {@code null} or if the array is {@code null}
*
* @since 9
*/
public static List of(@SuppressWarnings("unchecked") E... elements) {
switch (elements.length) { // implicit null check of elements
case 0:
@SuppressWarnings("unchecked")
List list = (List) ImmutableCollections.EMPTY_LIST;
return list;
case 1:
return new ImmutableCollections.List12(elements[0]);
case 2:
return new ImmutableCollections.List12(elements[0], elements[1]);
default:
return ImmutableCollections.listFromArray(elements);
}
}
/**
* Returns an unmodifiable List containing the elements of
* the given Collection, in its iteration order. The given Collection must not be null,
* and it must not contain any null elements. If the given Collection is subsequently
* modified, the returned List will not reflect such modifications.
*
* Implementation Note:
* If the given Collection is an unmodifiable List,
* calling copyOf will generally not create a copy.
*
* @param the {@code List}'s element type
* @param coll the collection from which elements are drawn, must be non-null
* @return a {@code List} containing the elements of the given {@code Collection}
* @throws NullPointerException if coll is null, or if it contains any nulls
* @since 10
*/
public static List copyOf(Collection coll) {
return ImmutableCollections.listCopy(coll);
}
private Lists() {
}
}