org.lockss.util.ListUtil Maven / Gradle / Ivy
Show all versions of lockss-util Show documentation
/*
Copyright (c) 2000, Board of Trustees of Leland Stanford Jr. University
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors
may be used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package org.lockss.util;
import java.util.*;
import java.util.function.*;
import org.apache.commons.collections4.*;
/**
*
* {@link List} utilities.
*
*
* @since 1.0.0
*/
public class ListUtil {
/**
*
* Prevents instantiation.
*
*
* @since 1.0.0
*/
private ListUtil() {
// Prevent instantiation
}
/**
*
* Creates a modifiable list from any number of arguments.
*
*
* {@link Arrays#asList(Object...)} differs from this in that it returns a
* fixed-size list backed by the varargs array.
*
*
* @param elements
* A succession of elements (possibly zero).
* @param
* The type of element contained in the list.
* @return A modifiable {@link List} of those elements (an empty list if no
* elements).
* @since 1.0.0
* @see CollectionUtil2#collection(Supplier, Object...)
*/
public static List list(T... elements) {
return CollectionUtil2.collection(ArrayList::new, elements);
}
/**
*
* Makes a new, single list made of the elements of all the given lists
* concatenated together. If a given list is null, it is ignored. If no input
* lists are given (taking null lists into account), the result is an empty
* list.
*
*
* @param lists
* A succession of lists (possibly zero).
* @param
* The type of element contained in the list.
* @return A new, single {@link List} made of the elements of all the non-null
* lists concatenated together.
* @since 1.0.0
*/
public static List append(List... lists) {
List ret = new ArrayList();
if (lists != null) {
for (List list : lists) {
if (list != null) {
ret.addAll(list);
}
}
}
return ret;
}
/**
*
* Now that {@link #list(Object...)} is generic, this method does exactly the
* same thing and simply calls it.
*
*
* @param array
* An array of objects.
* @param
* The type of element contained in the list.
* @return A modifiable {@link List} made of the objects in the array.
* @since 1.0.0
* @deprecated Use {@link #list(Object...)} instead.
* @see #list(Object...)
*/
@Deprecated
public static List fromArray(T[] array) {
return list(array);
}
/**
*
* Prepends the elements of ofList to the linked list
* toList, creating a new linked list from ofList if
* toList is null.
*
*
* If toList is null, the result is a new linked list made from
* ofList. If ofList is null,
*
*
* @param ofList
* The list whose elements are prepended.
* @param toList
* The list to which elements are prepended.
* @param
* The type of element contained in the list.
* @return A linked list with the elements of the first prepended to the
* elements of the second.
* @since 1.0.0
* @see LinkedList#addFirst(Object)
**/
public static LinkedList prependAll(List ofList, LinkedList toList) {
if (toList == null) {
return ofList == null ? new LinkedList() : new LinkedList(ofList);
}
if (ofList == null) {
return toList;
}
List revOfList = reverseCopy(ofList);
for (T item : revOfList) {
toList.addFirst(item);
}
return toList;
}
/**
*
* Returns a trimmed {@link ArrayList} equal to the given {@link List}
* instance.
*
*
* @param lst
* A list.
* @param
* The type of element contained in the list.
* @return An {@link ArrayList} instance of the same elements, trimmed to the
* size of the given list. If the input list is itself an
* {@link ArrayList} instance, that instance is trimmed an returned
* without allocating a new instance.
* @since 1.0.0
* @see ArrayList#ArrayList(Collection)
* @see ArrayList#trimToSize()
*/
public static ArrayList minimalArrayList(List lst) {
if (lst instanceof ArrayList) {
ArrayList alst = (ArrayList)lst;
alst.trimToSize();
return alst;
}
else {
return new ArrayList(lst);
}
}
/**
*
* Creates a list containing the elements of the given iterator.
*
*
* The preferred way of doing this is with
* {@link IteratorUtils#toList(Iterator)}, which behaves exactly the same way
* as this method.
*
*
* @param iterator
* An iterator.
* @param
* The type of element contained in the list.
* @return A list built from consuming the iterator.
* @since 1.0.0
* @see CollectionUtil2#fromIterator(Supplier, Iterator)
*/
public static List fromIterator(Iterator iterator) {
return CollectionUtil2.fromIterator(ArrayList::new, iterator);
}
/**
*
* Creates a list containing the elements of the given iterable.
*
*
* @param iterable
* An iterable.
* @param
* The type of element contained in the list.
* @return A list built from the elements in the iterable.
* @since 1.0.0
* @see CollectionUtil2#fromIterable(Supplier, Iterable)
*/
public static List fromIterable(Iterable iterable) {
return CollectionUtil2.fromIterable(ArrayList::new, iterable);
}
/**
*
* Creates a list containing the elements of a comma separated string, with
* the caveat that the processing is done by {@link StringTokenizer} with the
* delimiter ",".
*
*
* {@link StringTokenizer} simplistically looks for separators without a
* quoting mechanism to return tokens containing the delimiter, nor does it
* trim whitespace between tokens and delimiters. It also does not return
* empty tokens, so calling this method with ",,," will return an
* empty list, not a list of four empty strings.
*
*
* @param csv
* A simplistic CSV string.
* @return A list of tokens as separated by commas in the given input string.
* @since 1.0.0
* @see CollectionUtil2#fromCsvStringTokenizer(Supplier, String)
**/
public static List fromCSV(String csv) {
return CollectionUtil2.fromCsvStringTokenizer(ArrayList::new, csv);
}
/**
*
* Checks that all elements of the list are of the specified type, and returns
* an unmodifiable copy of the list, with null elements disallowed.
*
*
* @param list
* The input list.
* @param type
* The class with which all items of the list must be
* assignment-compatible.
* @param
* The type of element contained in the list.
* @return An immutable copy of the list.
* @throws NullPointerException
* if the list is null or if any element is null.
* @throws ClassCastException
* if an item is not of the proper type.
* @since 1.0.0
* @see #immutableListOfType(List, Class, boolean)
*/
public static List immutableListOfType(List list,
Class type) {
return immutableListOfType(list, type, false);
}
/**
*
* Checks that all elements of the list are of the specified type, and returns
* an unmodifiable copy of the list, with null elements allowed.
*
*
* @param list
* The input list.
* @param type
* The class with which all items of the list must be
* assignment-compatible.
* @param
* The type of element contained in the list.
* @return An immutable copy of the list.
* @throws NullPointerException
* if the list is null
* @throws ClassCastException
* if an item is not of the proper type.
* @since 1.0.0
* @see #immutableListOfType(List, Class, boolean)
*/
public static List immutableListOfTypeOrNull(List list,
Class type) {
return immutableListOfType(list, type, true);
}
/**
*
* Checks that all elements of the list are of the specified type, and returns
* an unmodifiable copy of the list, with null elements either allowed or
* disallowed.
*
*
* @param list
* The input list.
* @param type
* The class with which all items of the list must be
* assignment-compatible.
* @param nullOk
* Whether null elements are allowed.
* @param
* The type of element contained in the list.
* @return An immutable copy of the list.
* @throws NullPointerException
* if the list is null or if any element is null.
* @throws ClassCastException
* if an item is not of the proper type.
* @since 1.0.0
*/
protected static List immutableListOfType(List list,
Class type,
boolean nullOk) {
return CollectionUtil2.immutableCollectionOfType((IntFunction>)ArrayList::new,
Collections::unmodifiableList,
list,
type,
nullOk);
}
/**
*
* Returns a copy of the list, with elements in reverse order.
*
*
* @param list
* The list to reverse.
* @param
* The type of element contained in the list.
* @return A new list with elements in reverse order from the original list.
* @since 1.0.0
* @see Collections#reverse(List)
*/
public static List reverseCopy(List list) {
List ret = new ArrayList(list);
Collections.reverse(ret);
return ret;
}
}