Package eu.bandm.tools.util.java

Class Collections

java.lang.Object

eu.bandm.tools.util.java.Collections

public abstract class Collections
extends Object

Library of constants and operations for working with the Java collection framework.

Meta-Stability

A collection is called meta-stable if and only if its encounter order (the order of elements as seen through iterators) remains the same unless a change of content occurs. What constitutes a change of content may depend on the semantics of the particular implementation. We consider the following criteria as indicative that a change of content of collection c has occurred between time points t1 and t2:

• A copy of c has been obtained as d = new OtherCollection(c) at t1; c.equals(d) returns true at t1 but false at t2.
• An iterator over c has been obtained as i = c.iterator() at t1; an attempt to use it throws ConcurrentModificationException at t2.

This property is not specified in the JDK collection framework, but applies to many common implementations:

• Lists (ArrayList, LinkedList, etc.) are always meta-stable.
• Ordered collections (TreeSet, TreeMap, etc.) are always meta-stable.
• Hybrid hash-based collections (LinkedHashSet, LinkedHashMap) are always meta-stable.
• Pure hash-based collections (HashSet, HashMap) are likely meta-stable; some caution is recommended.

Collection implementations that apply spontaneous self-optimization or compute elements on the fly are not expected to be meta-stable; careful investigation is recommended before applying any operations that rely on meta-stability.

See Also:

• Collection

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Collections.MapBuilder<K,V>	Helper class for building maps incrementally.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	METHOD_NAME_CLONE	The name of the clone method.

Method Summary

Modifier and Type	Method	Description
static <K, V> Map<K,V>	buildMap(Consumer<? super Collections.MapBuilder<K,V>> initializer)	Builds a map using the given initializer.
static <A, B, C extends B> Map<A,B>	castValues(Class<? extends C> cls, Map<A,C> things)	Returns a view on a given collection that modifies the type of each element by casting.
static <A> Collection<A>	concat(Collection<? extends A> some, Collection<? extends A> other)	Returns a collection view that contains all elements of two given collections.
static <A, B> Map<B,A>	converse(Map<A,B> map)	Returns a map that contains all pairs of a given map with key and value swapped.
static <A> List<A>	duplicate(List<A> proto)	Creates an independent copy of a list with behavior as similar as possible.
static <A, B> Map<A,B>	duplicate(Map<A,B> proto)	Creates an independent copy of a map with behavior as similar as possible.
static <A, B> NavigableMap<A,B>	duplicate(NavigableMap<A,B> proto)	Creates an independent copy of a navigable map with behavior as similar as possible.
static <A> Set<A>	duplicate(Set<A> proto)	Creates an independent copy of a set with behavior as similar as possible.
static <A, B> SortedMap<A,B>	duplicate(SortedMap<A,B> proto)	Creates an independent copy of a sorted map with behavior as similar as possible.
static <A> SortedSet<A>	duplicate(SortedSet<A> proto)	Creates an independent copy of a sorted set with behavior as similar as possible.
static <A> Set<A>	elements(Collection<? extends A> things)	Returns a new set of the elements of a given collection, without duplicates.
static <A> SortedSet<A>	elements(Collection<? extends A> things, Comparator<? super A> comparator)	Returns a new set of the elements of a given collection, without duplicates according to a given ordering.
static <A, B> SortedMap<A,B>	emptySortedMap()	Returns an unmodifiable empty sorted map.
static <A> SortedSet<A>	emptySortedSet()	Returns an unmodifiable empty sorted set.
static <A> Collection<A>	flatten(Collection<? extends Collection<? extends A>> colls)	Returns a view on a collection of collections that contains all of their elements.
static <A> void	forEach(A[] list, ObjIntConsumer<A> code)	Apply code to array elements in ascending order, together with their indices
static <A> void	forEach(List<A> list, ObjIntConsumer<A> code)	Apply code to list elements in ascending order, together with their indices.
static <A> int	indexOf(List<A> list, Predicate<A> filter)	Return the index of the first element which fulfills the given predicate.
static <D> D	infimum(SortedSet<D> set, D value)	Return the greatest member of a given nonempty set which is less or equal the given upper bound.
static <D> D	infimumKey(SortedMap<D,?> map, D key)	Return the greatest key in the domain of a given nonempty map which is less or equal the upper bound.
static <A> Set<A>	intersection(Collection<? extends A> some, Collection<? extends A> other)	Returns a new set that contains the elements commonly contained in both given collections.
static <A> A	lastOf(List<A> list)	Return the last element in a nonempty list.
static List<Integer>	literalIntList(int... values)	Returns an unmodifiable list of the given elements.
static <A> List<A>	literalList(A... values)	Returns an unmodifiable list of the given elements.
static <A, B> Collections.MapBuilder<A,B>	literalMap(A a, B b)	Starts the incremental creation of a map with one entry.
static <A> Set<A>	literalSet(A... values)	Returns an unmodifiable set of the given elements.
static <A> Set<A>	setminus(Collection<? extends A> some, Collection<? extends A> other)	Returns a new set that contains the elements contained in one given collection but not the other.
static <A extends Comparable<? super A>, B> SortedMap<A,B>	singletonSortedMap(A key, B value)	Returns an unmodifiable sorted map with one entry.
static <A, B> SortedMap<A,B>	singletonSortedMap(Comparator<? super A> comparator, A key, B value)	Returns an unmodifiable sorted map with one entry and a given ordering.
static <A extends Comparable<? super A>> SortedSet<A>	singletonSortedSet(A elem)	Returns an unmodifiable sorted set with one element.
static <A> SortedSet<A>	singletonSortedSet(Comparator<? super A> comparator, A elem)	Returns an unmodifiable sorted set with one element and a given ordering.
static <T> T	some(Collection<T> set)	Finds an arbitrary element contained in a collection.
static <T> T	the(Collection<T> set)	Finds the single element contained in a collection.
static <A, B> Map<A,B>	toGraph(Function<? super A,? extends B> fun, Set<? extends A> dom)	Returns a map with a given key set and values computed by a function.
static <A, B, C> Map<B,C>	toSpan(Function<? super A,? extends B> left, Function<? super A,? extends C> right, Collection<? extends A> gen)	Creates a map by generating entries from generating elements using two functions.
static <A, B, C> Map<B,C>	toSpan(Function<? super A,? extends B> left, Function<? super A,? extends C> right, BiFunction<? super C,? super C,? extends C> merge, Collection<? extends A> gen)	Creates a map by generating entries from generating elements using two functions.
static <A> Set<A>	union(Collection<? extends A> some, Collection<? extends A> other)	Returns a new set that contains the elements contained in either of the given collections.
static <K, V> Map.Entry<K,V>	unmodifiableEntry(Map.Entry<? extends K,? extends V> entry)	Returns an unmodifiable view on a given map entry.

Methods inherited from class java.lang.Object

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

Field Details

METHOD_NAME_CLONE

public static final String METHOD_NAME_CLONE

The name of the clone method.

See Also:

• Constant Field Values

Method Details

the

public static <T> T the(Collection<T> set)

Finds the single element contained in a collection.

Type Parameters:

T - the type of elements

Parameters:

set - a collection of elements of size 1

Returns:

the single element contained in the collection

Throws:

IllegalArgumentException - if set contains none, or more than one element

See Also:

• Collection.size()

some

public static <T> T some(Collection<T> set)

Finds an arbitrary element contained in a collection. As long as the collection is meta-stable, the returned element will not change.

Type Parameters:

T - the type of elements

Parameters:

set - a nonempty collection of elements

Returns:

an arbitrary element contained in the collection

Throws:

IllegalArgumentException - if set contains no element

See Also:

• Collection.isEmpty()

literalSet

@SafeVarargs
public static <A> Set<A> literalSet(A... values)

Returns an unmodifiable set of the given elements.

Use this method where the behavior of the alternative Set.of(Object[]) is not appropriate.

Type Parameters:

A - the type of elements

Parameters:

values - an array of elements

Returns:

a set containing exactly the given elements

See Also:

• Collections.emptySet()
• Collections.singleton(T)

literalList

@SafeVarargs
public static <A> List<A> literalList(A... values)

Returns an unmodifiable list of the given elements.

Use this method where the behavior of the alternative List.of(Object[]) is not appropriate.

Type Parameters:

A - the type of elements

Parameters:

values - an array of elements

Returns:

a list containing exactly the given elements in the same order

See Also:

• Collections.emptyList()
• Collections.singletonList(T)

literalIntList

public static List<Integer> literalIntList(int... values)

Returns an unmodifiable list of the given elements.

Parameters:

values - an array of elements

Returns:

a list containing exactly the given elements (boxed) in the same order

toSpan

public static <A,
B,
C> Map<B,C> toSpan(Function<? super A,? extends B> left,
 Function<? super A,? extends C> right,
 Collection<? extends A> gen)

Creates a map by generating entries from generating elements using two functions.

Type Parameters:

A - the type of generating elemens

B - the type of keys

C - the type of values

Parameters:

left - the key-generating function

right - the value-generating function

gen - the generating elements

Returns:

an unmodifiable map that contains, for each generating element, the computed entry

Throws:

IllegalArgumentException - if two generating elements result in the same key but different values

toSpan

public static <A,
B,
C> Map<B,C> toSpan(Function<? super A,? extends B> left,
 Function<? super A,? extends C> right,
 BiFunction<? super C,? super C,? extends C> merge,
 Collection<? extends A> gen)

Creates a map by generating entries from generating elements using two functions.

Type Parameters:

A - the type of generating elemens

B - the type of keys

C - the type of values

Parameters:

left - the key-generating function

right - the value-generating function

merge - an operation to reconcile values if two generating elements result in the same key

gen - the generating elements

Returns:

an unmodifiable map that contains, for each generating element, the computed entry

toGraph

public static <A,
B> Map<A,B> toGraph(Function<? super A,? extends B> fun,
 Set<? extends A> dom)

Returns a map with a given key set and values computed by a function.

Type Parameters:

A - the type of keys

B - the type of values

Parameters:

fun - a function to compute values from keys

dom - the key set

Returns:

a new map that maps all keys in dom to values computed with fun

concat

public static <A> Collection<A> concat(Collection<? extends A> some,
 Collection<? extends A> other)

Returns a collection view that contains all elements of two given collections.

Changes to the underlying collections are reflected in the resulting collection. By contrast, the resulting collection cannot be modified on its own.

Type Parameters:

A - the element type

Parameters:

some - one collection

other - another collection

Returns:

an unmodifiable collection that always contains the current elements of both given collections

Throws:

NullPointerException - if some or other is null

union

public static <A> Set<A> union(Collection<? extends A> some,
 Collection<? extends A> other)

Returns a new set that contains the elements contained in either of the given collections.

Changes to the underlying sets are not reflected by the result.

Type Parameters:

A - the type of elements

Parameters:

some - a collection of elements

other - another collection of elements

Returns:

a new set that contains those elements that are contained in either some or other

setminus

public static <A> Set<A> setminus(Collection<? extends A> some,
 Collection<? extends A> other)

Returns a new set that contains the elements contained in one given collection but not the other.

Changes to the underlying sets are not reflected by the result.

Type Parameters:

A - the type of elements

Parameters:

some - a collection of elements

other - another collection of elements

Returns:

a new set that contains those elements that are contained in some but not in other

intersection

public static <A> Set<A> intersection(Collection<? extends A> some,
 Collection<? extends A> other)

Returns a new set that contains the elements commonly contained in both given collections.

Changes to the underlying sets are not reflected by the result.

Type Parameters:

A - the type of elements

Parameters:

some - a collection of elements

other - another collection of elements

Returns:

a new set that contains those elements that are contained in both some and other

flatten

public static <A> Collection<A> flatten(Collection<? extends Collection<? extends A>> colls)

Returns a view on a collection of collections that contains all of their elements.

Changes to the underlying collection(s) are reflected by the resulting view.

Type Parameters:

A - the type of elements

Parameters:

colls - a collection of collections of elements

Returns:

an unmodifiable collection that contains all elements that are contained in a collection contained in colls

unmodifiableEntry

public static <K,
V> Map.Entry<K,V> unmodifiableEntry(Map.Entry<? extends K,? extends V> entry)

Returns an unmodifiable view on a given map entry.

Changes to the underlying entry are reflected by the resulting view.

Type Parameters:

K - the key type

V - the value type

Parameters:

entry - the entry

Returns:

an unmodifiable map entry with the same key and value as entry

elements

public static <A> Set<A> elements(Collection<? extends A> things)

Returns a new set of the elements of a given collection, without duplicates.

Duplicates are element for which Object.equals(java.lang.Object) returns true.

Type Parameters:

A - the type of elements

Parameters:

things - a collection of elements

Returns:

a new set containing all elements of things, but no duplicates

elements

public static <A> SortedSet<A> elements(Collection<? extends A> things,
 Comparator<? super A> comparator)

Returns a new set of the elements of a given collection, without duplicates according to a given ordering.

Duplicates are element for which comparator.compare returns 0.

Type Parameters:

A - the type of elements

Parameters:

things - a collection of elements

comparator - a comparison function that specifies the ordering

Returns:

a new set containing all elements of things, but no duplicates

Throws:

IllegalArgumentException - if some elements cannot be compared

castValues

public static <A,
B,
C extends B> Map<A,B> castValues(Class<? extends C> cls,
 Map<A,C> things)

Returns a view on a given collection that modifies the type of each element by casting.

Changes to the underlying collection are reflected by the resulting view.

Type Parameters:

A - the type of keys

B - the actual type of elements

C - the apparent type of elements

Parameters:

cls - the class to cast to

things - the map to transform

Returns:

an unmodifiable map that has, for each current value of things, a cast reference of type cls, for the same key

literalMap

public static <A,
B> Collections.MapBuilder<A,B> literalMap(A a,
 B b)

Starts the incremental creation of a map with one entry.

Type Parameters:

A - the type of keys

B - the type of values

Parameters:

a - the key of the initial entry

b - the value of the initial entry

Returns:

a builder for a map that already contains the given entry

See Also:

• Collections.MapBuilder.close()

buildMap

public static <K,
V> Map<K,V> buildMap(Consumer<? super Collections.MapBuilder<K,V>> initializer)

Builds a map using the given initializer.

The initializer is passed a reference to a new empty Collections.MapBuilder object. The resulting map is created from the contents of that object once the initializer returns.

Type Parameters:

K - the type of map keys

V - the type of map values

Parameters:

initializer - a piece of initializer code

Returns:

an unmodifiable map initialized as specified

Throws:

NullPointerException - if initializer is null

Since:

1.3

emptySortedSet

public static <A> SortedSet<A> emptySortedSet()

Returns an unmodifiable empty sorted set.

Type Parameters:

A - the type of elements

Returns:

an unmodifiable empty sorted set

See Also:

• Collections.emptySet()

singletonSortedSet

public static <A extends Comparable<? super A>>
SortedSet<A> singletonSortedSet(A elem)

Returns an unmodifiable sorted set with one element.

Type Parameters:

A - the type of elements

Parameters:

elem - the element

Returns:

an unmodifiable sorted set with the given element

See Also:

• Collections.singleton(T)

singletonSortedSet

public static <A> SortedSet<A> singletonSortedSet(Comparator<? super A> comparator,
 A elem)

Returns an unmodifiable sorted set with one element and a given ordering.

Type Parameters:

A - the type of elements

Parameters:

comparator - a comparison function that specifies the ordering

elem - the element

Returns:

an unmodifiable sorted set with the given element

See Also:

• Collections.singleton(T)

emptySortedMap

public static <A,
B> SortedMap<A,B> emptySortedMap()

Returns an unmodifiable empty sorted map.

Type Parameters:

A - the type of keys

B - the type of values

Returns:

an unmodifiable empty sorted map

See Also:

• Collections.emptyMap()

singletonSortedMap

public static <A extends Comparable<? super A>,
B>
SortedMap<A,B> singletonSortedMap(A key,
 B value)

Returns an unmodifiable sorted map with one entry.

Type Parameters:

A - the type of keys

B - the type of values

Parameters:

key - the key of the entry

value - the value of the entry

Returns:

an unmodifiable sorted map with the given entry

Throws:

NullPointerException - if key is null

See Also:

• Collections.singletonMap(K, V)

singletonSortedMap

public static <A,
B> SortedMap<A,B> singletonSortedMap(Comparator<? super A> comparator,
 A key,
 B value)

Returns an unmodifiable sorted map with one entry and a given ordering.

Type Parameters:

A - the type of keys

B - the type of values

Parameters:

comparator - a comparison function specifying the ordering

key - the key of the entry

value - the value of the entry

Returns:

an unmodifiable sorted map with the given entry

See Also:

• Collections.singletonMap(K, V)

infimum

public static <D> D infimum(SortedSet<D> set,
 D value)

Return the greatest member of a given nonempty set which is less or equal the given upper bound.

Type Parameters:

D - the type of elements

Parameters:

set - a nonempty sorted set

value - the upper bound

Returns:

the greatest element of set which is less or equal to value

Throws:

NoSuchElementException - if the given set is empty

infimumKey

public static <D> D infimumKey(SortedMap<D,?> map,
 D key)

Return the greatest key in the domain of a given nonempty map which is less or equal the upper bound.

This method is not easily emulated by infimum(SortedSet, Object), because for some reason SortedMap.keySet() does not return a SortedSet.

Type Parameters:

D - the type of keys

Parameters:

map - a nonempty sorted map

key - the upper bound

Returns:

the greatest key of map which is less or equal to key

Throws:

NoSuchElementException - if the given map is empty

converse

public static <A,
B> Map<B,A> converse(Map<A,B> map)

Returns a map that contains all pairs of a given map with key and value swapped.

The values of the given map must be unique. null keys and/or values are not supported.

This operation copies map entries; later changes to the given map are not reflected.

Type Parameters:

A - the key type of the given map; the value type of the resulting map

B - the value type of the given map; the key type of the resulting map

Parameters:

map - a map

Returns:

an unmodifiable map of all values of the given map to their corresponding keys

Throws:

UnsupportedOperationException - if a value is associated with more than one key

lastOf

public static <A> A lastOf(List<A> list)

Return the last element in a nonempty list.

Type Parameters:

A - the type of elements

Parameters:

list - a nonempty list

Returns:

the last element of the list

Throws:

IllegalArgumentException - if the list is empty

indexOf

public static <A> int indexOf(List<A> list,
 Predicate<A> filter)

Return the index of the first element which fulfills the given predicate.

Type Parameters:

A - the type of elements

Parameters:

list - the list of elements to search

filter - the predicate for which is searched

Returns:

the index of the first element which fulfills the given predicate, or -1 if no such element exists.

Throws:

NullPointerException - if list or filter is null

Since:

1.2

forEach

public static <A> void forEach(List<A> list,
 ObjIntConsumer<A> code)

Apply code to list elements in ascending order, together with their indices.

Type Parameters:

A - the type of elements

Parameters:

list - the list of elements to visit

code - to apply to all elements

Throws:

NullPointerException - if list or code is null

Since:

1.3

forEach

public static <A> void forEach(A[] list,
 ObjIntConsumer<A> code)

Apply code to array elements in ascending order, together with their indices

Type Parameters:

A - the type of elements

Parameters:

list - the array of elements to visit

code - to apply to all elements

Throws:

NullPointerException - if list or code is null

Since:

1.3

duplicate

public static <A,
B> Map<A,B> duplicate(Map<A,B> proto)

Creates an independent copy of a map with behavior as similar as possible. The method tries

1. a clone method;
2. a copy constructor;
3. a nullary constructor of the class of the prototype,
4. a default construction strategy, namely to construct a HashMap.

Whenever one of the first three strategies fails, the next is tried. This is the case not only when the method is not foreseen, but also when its execution throws an exception due to a programming error. In this case one can get a result constructed by a later strategy, other than expected.

This class provides more specialized methods duplicate(SortedMap) and duplicate(NavigableMap).

This method works heuristically. For instance, a clone method is not guaranteed to return instances of the class of the original, and a constructor with one argument of its own type is only recommended to copy all contained values.

Type Parameters:

A - the type of the keys in the maps

B - the type of the values in the maps

Parameters:

proto - the original map to copy

Returns:

a map that initially contains the same entries as proto, with implementation behavior as similar as possible.

Throws:

NullPointerException - if proto is null

Since:

1.2

See Also:

• Collection
• Map
• SortedMap
• Object.clone()

duplicate

public static <A,
B> SortedMap<A,B> duplicate(SortedMap<A,B> proto)

Creates an independent copy of a sorted map with behavior as similar as possible. In particular, the ordering of the copy and the prototype are the same. The method tries

1. a clone method;
2. a copy constructor;
3. the constructor with a Comparator as argument, if present in the prototype, otherwise its nullary constructor.
4. a default construction strategy, namely to construction a TreeMap.

Whenever one of the first three strategies fails, the next is tried. This is the case not only when the method is not foreseen, but also when its execution throws an exception due to a programming error. In this case one can get a result constructed by a later strategy, other than expected.

This code relies on three of the "four standard constructors" as explained with the API doc of SortedMap.

This class provides the more specialized method duplicate(NavigableMap) and the more general method duplicate(Map).

This method works heuristically. For instance, a clone method is not guaranteed to return instances of the class of the original, and a constructor with one argument of its own type is only recommended to copy all contained values.

Type Parameters:

A - the type of the keys in the maps

B - the type of the values in the maps

Parameters:

proto - the original sorted map to copy

Returns:

a sorted map that initially contains the same entries as proto, with implementation behavior as similar as possible.

Throws:

NullPointerException - if proto is null

Since:

1.2

See Also:

• Collection
• Map
• SortedMap
• Object.clone()

duplicate

public static <A,
B> NavigableMap<A,B> duplicate(NavigableMap<A,B> proto)

Creates an independent copy of a navigable map with behavior as similar as possible. In particular, the ordering of the copy and the prototype are the same. The method tries

1. a clone method;
2. a copy constructor;
3. the constructor with a Comparator as argument, if present in the prototype, otherwise its nullary constructor.
4. a default construction strategy, namely to construction a TreeMap.

Whenever one of the first three strategies fails, the next is tried. This is the case not only when the method is not foreseen, but also when its execution throws an exception due to a programming error. In this case one can get a result constructed by a later strategy, other than expected.

This code relies on three of the "four standard constructors" as explained with the API doc of SortedMap.

This class provides the more general methods duplicate(Map) and duplicate(SortedMap).

This method works heuristically. For instance, a clone method is not guaranteed to return instances of the class of the original, and a constructor with one argument of its own type is only recommended to copy all contained values.

Type Parameters:

A - the type of the keys in the maps

B - the type of the values in the maps

Parameters:

proto - the original sorted map to copy

Returns:

a navigable map that initially contains the same entries as proto, with implementation behavior as similar as possible.

Throws:

NullPointerException - if proto is null

Since:

1.2

See Also:

• Collection
• Map
• SortedMap
• Object.clone()

duplicate

public static <A> Set<A> duplicate(Set<A> proto)

Creates an independent copy of a set with behavior as similar as possible. The method tries

1. a clone method;
2. a copy constructor;
3. the nullary constructor of the prototype:
4. a default strategy, namely to construct a HashSet.

Whenever one of the first three strategies fails, the next is tried. This is the case not only when the method is not foreseen, but also when its execution throws an exception due to a programming error. In this case one can get a result constructed by a later strategy, other than expected.

This class provides the more specialized method duplicate(SortedSet).

This method works heuristically. For instance, a clone method is not guaranteed to return instances of the class of the original, and a constructor with one argument of its own type is only recommended to copy all contained values.

Type Parameters:

A - the type of the set elements

Parameters:

proto - the original set to copy

Returns:

a set that initially contains the same entries as proto, with implementation behavior as similar as possible.

Throws:

NullPointerException - if proto is null

Since:

1.2

See Also:

• Collection
• Set
• Object.clone()

duplicate

public static <A> SortedSet<A> duplicate(SortedSet<A> proto)

Creates an independent copy of a sorted set with behavior as similar as possible. In particular, the ordering of the copy and the prototype are the same. The method tries

1. a clone method;
2. a copy constructor;
3. the constructor with a Comparator as argument, if present in the prototype, otherwise its nullary constructor.
4. a default construction strategy, namely to construction a TreeSet.

Whenever one of the first three strategies fails, the next is tried. This is the case not only when the method is not foreseen, but also when its execution throws an exception due to a programming error. In this case one can get a result constructed by a later strategy, other than expected.

This class provides the more general method duplicate(Set).

This method works heuristically. For instance, a clone method is not guaranteed to return instances of the class of the original, and a constructor with one argument of its own type is only recommended to copy all contained values.

Type Parameters:

A - the type of the set elements

Parameters:

proto - the original sorted set to copy

Returns:

a sorted set that initially contains the same entries as proto, with implementation behavior as similar as possible.

Throws:

NullPointerException - if proto is null

Since:

1.2

See Also:

• Collection
• Set
• SortedSet
• Object.clone()

duplicate

public static <A> List<A> duplicate(List<A> proto)

Creates an independent copy of a list with behavior as similar as possible. The method tries

1. a clone method;
2. a copy constructor;
3. the prototype's nullary constructor.
4. a default construction strategy, namely to construct an ArrayList.

Whenever one of the first three strategies fails, the next is tried. This is the case not only when the method is not foreseen, but also when its execution throws an exception due to a programming error. In this case one can get a result constructed by a later strategy, other than expected.

This method works heuristically. For instance, a clone method is not guaranteed to return instances of the class of the original, and a constructor with one argument of its own type is only recommended to copy all contained values.

Type Parameters:

A - the type of the list elements

Parameters:

proto - the original list to copy

Returns:

a list that initially contains the same entries as proto, with implementation behavior as similar as possible.

Throws:

NullPointerException - if proto is null

Since:

1.2

See Also:

• Collection
• List
• ArrayList
• Object.clone()