Package com.globalmentor.collections

Class Lists

java.lang.Object

com.globalmentor.collections.Lists

public class Lists
extends java.lang.Object

Utilities to be used with lists.

Author:

Garret Wilson

Constructor Summary

Constructors

Constructor	Description
Lists()

Method Summary

Modifier and Type	Method	Description
static <E> java.util.List<E>	immutableListOf(E... elements)	Creates a read-only list containing the given elements.
static <E> java.util.List<E>	immutableListOf(E[] elements, int start, int end)	Creates a read-only list containing the given elements in the given range.
static <E> java.util.List<E>	immutableListOf(java.util.Collection<? extends E> collection, E... elements)	Creates a read-only list containing the elements of the provided collection along with the given elements.
static <E> java.util.List<E>	immutableListOf(java.util.Collection<? extends E> collection, E[] elements, int start, int end)	Creates a read-only list containing the elements of the provided collection along with the given elements.
static <E> java.util.List<E>	listOf(java.lang.Iterable<E> iterable, E... elements)	Creates and returns a mutable list containing the contents of the given iterable with the additional elements, if any.
static <E> java.util.List<E>	listOf(java.util.Iterator<E> iterator, E... elements)	Creates and returns a mutable list containing the contents of the given iterator with the additional elements, if any.
static <E> void	replace(java.util.List<E> list, E oldObject, E newObject)	Replaces the first occurrence of the given object with a new object.
static <T> java.util.List<T>	toList(java.lang.Iterable<T> iterable)	Returns a list to represent the given iterable.

Methods inherited from class java.lang.Object

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

Constructor Detail

Lists

public Lists()

Method Detail

replace

public static <E> void replace(java.util.List<E> list,
                               E oldObject,
                               E newObject)

Replaces the first occurrence of the given object with a new object. If the object does not appear in the list, no action is taken.

Type Parameters:

E - The type of element contained in the list.

Parameters:

list - The list in which the object is included.

oldObject - The object to replace.

newObject - The object to take the place of the old object.

immutableListOf

public static <E> java.util.List<E> immutableListOf(E... elements)

Creates a read-only list containing the given elements.

Type Parameters:

E - The type of element contained in the list.

Parameters:

elements - The elements to be contained in the list.

Returns:

The immutable version of the list.

Throws:

java.lang.NullPointerException - if the given array of elements is null.

immutableListOf

public static <E> java.util.List<E> immutableListOf(E[] elements,
                                                    int start,
                                                    int end)

Creates a read-only list containing the given elements in the given range.

Type Parameters:

E - The type of element contained in the list.

Parameters:

elements - The elements to be contained in the list.

start - the initial index of the range to be included, inclusive

end - the final index of the range to be included, exclusive.

Returns:

The immutable version of the list.

Throws:

java.lang.NullPointerException - if the given array of elements is null.

java.lang.IllegalArgumentException - if the start index is greater than the end index.

java.lang.ArrayIndexOutOfBoundsException - if the start index is less than zero or the end index is greater than the length.

immutableListOf

public static <E> java.util.List<E> immutableListOf(java.util.Collection<? extends E> collection,
                                                    E... elements)

Creates a read-only list containing the elements of the provided collection along with the given elements.

Type Parameters:

E - The type of element contained in the list.

Parameters:

collection - The existing collection to augment.

elements - The elements to be contained in the list.

Returns:

The immutable version of the list.

Throws:

java.lang.NullPointerException - if the given collection and/or array of elements is null.

immutableListOf

public static <E> java.util.List<E> immutableListOf(java.util.Collection<? extends E> collection,
                                                    E[] elements,
                                                    int start,
                                                    int end)

Creates a read-only list containing the elements of the provided collection along with the given elements.

Type Parameters:

E - The type of element contained in the list.

Parameters:

collection - The existing collection to augment.

elements - The elements to be contained in the list.

start - the initial index of the range to be included, inclusive

end - the final index of the range to be included, exclusive.

Returns:

The immutable version of the list.

Throws:

java.lang.NullPointerException - if the given collection and/or array of elements is null.

java.lang.IllegalArgumentException - if the start index is greater than the end index.

java.lang.ArrayIndexOutOfBoundsException - if the start index is less than zero or the end index is greater than the length.

listOf

public static <E> java.util.List<E> listOf(java.util.Iterator<E> iterator,
                                           E... elements)

Creates and returns a mutable list containing the contents of the given iterator with the additional elements, if any.

Type Parameters:

E - The type of the elements of the list.

Parameters:

iterator - The iterator a list of the contents of which should be returned.

elements - The additional elements, if any, to add to the list.

Returns:

A mutable list containing the indicated elements.

listOf

public static <E> java.util.List<E> listOf(java.lang.Iterable<E> iterable,
                                           E... elements)

Creates and returns a mutable list containing the contents of the given iterable with the additional elements, if any.

Type Parameters:

E - The type of the list

Parameters:

iterable - The iterable a list of the contents of which should be returned.

elements - The additional elements, if any, to add to the list.

Returns:

A mutable list containing the indicated elements.

toList

public static <T> java.util.List<T> toList(java.lang.Iterable<T> iterable)

Returns a list to represent the given iterable. If the given iterable is a List, it will be returned. If the given iterable is not a List, a temporary list will be created and filled with the contents of the given iterable.

In most cases the returned list should not be modified, as there are no guarantees of whether the list will be backed by existing data or whether the list will even be mutable.

Type Parameters:

T - The type of elements contained in the iterable.

Parameters:

iterable - The iterable of elements.

Returns:

A list containing the elements of the given iterable.