org.opencastproject.util.data

Class Collections

java.lang.Object

org.opencastproject.util.data.Collections

public final class Collections
extends Object

This class provides functions to ease and secure the handling of collections by supporting a type safe -- at least to the extent Java's type system allows -- immutable and more functional style. Note that all functions do not mutate input collections unless otherwise stated.

Method Summary

Modifier and Type	Method and Description
static <A,T extends Collection<A>,S extends Iterable<? extends A>> T	appendTo(T target, S as) Append source collection as to target.
static <A,T extends Collection<A>,X extends A> T	appendToA(T target, X... as) Append source collections as to target.
static <A,T extends Collection<A>,S extends Iterable<? extends A>> T	appendToM(T target, S... as) Append source collections as to target.
static <K,V> Map<K,V>	asMap(List<V> values, Function<V,K> keyGen) Partition a list after some predicate keyGen.
static <K,V> Map<K,V>	asMap(Map<K,V> map, List<V> values, Function<V,K> keyGen) Partition a list after some predicate keyGen into map.
static <A> List<A>	concat(List<? extends A> as, List<? extends A> bs) Concatenates two lists.
static <A,M extends Collection<? extends Collection<A>>> List<A>	concat(M as) Concat (aka flatten) a collection of collections by concatenating them all.
static <A,M extends Iterable<? extends A>> List<A>	concat(M as, M bs) Concatenates two iterables into a new list.
static <A> List<A>	cons(A a, List<? extends A> as) Construct a new list by prepending an element to a given list.
static <A> Function<List<A>,Function<A,Boolean>>	containedIn() Curried version of List.contains(Object).
static <A> Function<A,Boolean>	containedIn(List<A> as) Create a function that checks if its argument is contained in as.
static <K,V> Dictionary<K,V>	dict(Tuple<? extends K,? extends V>... ts) Create a dictionary from a list of tuples (K, V).
static <A,M extends Iterable<? extends A>> List<A>	diff(M as, M bs)
static <A> boolean	exists(Collection<A> as, Predicate<A> p) Deprecated. use Monadics
static <A,M extends Collection<A>> M	filter(M as, Predicate<A> p) Deprecated. use Monadics
static <A> Option<A>	find(Collection<A> as, Predicate<A> p) Deprecated. use Monadics
static <A,B> Collection<B>	flatMap(Collection<A> as, Function<A,Collection<B>> f) Deprecated. use Monadics
static <A,B,M extends Collection<B>> M	flatMap(Collection<A> as, M bs, Function<A,Collection<B>> f) Deprecated. use Monadics
static <A,B> Function<A[],List<B>>	flatMapArrayToList(Function<A,List<B>> f)
static <A,B> B	foldl(Collection<A> as, B start, Function2<B,A,B> f) Deprecated. use Monadics
static <A> Iterable<A>	forc(Iterator<A> as) Make an Iterator usable in a for comprehension like this:
static <A,B> Function<A,Option<B>>	getMap(Map<A,B> map) Return a function to get data from a map.
static <K,V> V	getOrCreate(Map<K,V> map, K key, Creator<V> c) Get a value from a map, creating and adding a new one, if the value is missing, i.e.
static <K,V> V	getOrCreate(Map<K,V> map, K key, Function0<V> f) Get a value from a map, creating and adding a new one, if the value is missing, i.e.
static <A> Function<Option<A>,A>	getOrElse(A a)
static <K,V> com.google.common.collect.ImmutableMultimap<K,V>	groupBy(Iterable<? extends V> values, Function<? super V,? extends K> group) Partition a list after some predicate group into map.
static <K,V> com.google.common.collect.Multimap<K,V>	groupBy(com.google.common.collect.Multimap<K,V> map, Iterable<? extends V> values, Function<? super V,? extends K> group) Partition a list after some predicate group into map.
static <A> List<List<A>>	grouped(List<A> as, int size) Partition a list in chunks of size size.
static <A> Function<List<A>,Option<A>>	head()
static <A> Option<A>	head(List<A> as) Return the head of list as or none.
static <A> Iterator<A>	iterator(A... as) Create an iterator form an array.
static <A> Iterator<A>	join(Iterator<A> a, Iterator<A> b) Join two iterators.
static <A> Option<A>	last(A[] as) Return the last element of the array.
static <A> Option<A>	last(List<A> as) Return the last element of the list.
static <A> List<A>	list(A... as) Create a list from an array.
static <K,V,X> com.google.common.collect.Multimap<K,V>	makeMap(com.google.common.collect.Multimap<K,V> map, Iterable<? extends X> values, Function<? super X,Tuple<K,V>> group) Partition a list after some predicate group into map.
static <A,B> Collection<B>	map(Collection<A> as, Function<A,B> f) Deprecated. use Monadics
static <A,B,M extends Collection<B>> M	map(Collection<A> as, M bs, Function<A,B> f) Deprecated. use Monadics
static <K,V> Map<K,V>	map(Tuple<? extends K,? extends V>... ts) Create a map from a list of tuples (K, V).
static <A,B> Map<A,B>	merge(Map<? extends A,? extends B> a, Map<? extends A,? extends B> b) Merge two maps where b takes precedence.
static <A> Set<A>	merge(Set<? extends A> a, Set<? extends A> b) Merge two sets into one.
static <A> List<A>	mkList(List<A> as) Deprecated. use nullToNil(java.util.List)
static String	mkString(Collection<?> as, String sep) Make a string from a collection separating each element by sep.
static <A> List<A>	nil() The empty list.
static <A> List<A>	nil(Class<A> type) The empty list.
static <A> List<A>	nonNullList(A... as) Create a list from an array.
static <A> List<A>	nullToNil(List<A> as) Return the list as is or nil, if as is null.
static <A> Function<Option<A>,Iterator<A>>	optionToIterator() Turn an option into an iterator.
static <A> Function<Option<A>,List<A>>	optionToList()
static Properties	properties(Tuple<String,String>... ts) Create properties from a list of tuples (K, V).
static <A,X extends A> Iterator<A>	repeat(X a, int times) Create an iterator that repeats a for the said times.
static <A> Set<A>	set(A... as) Create a set from an array.
static <K,V> SortedMap<K,V>	smap(Tuple<? extends K,? extends V>... ts) Create a sorted map from a list of tuples (K, V) based on the natural ordering of K.
static <A extends Comparable> Function<List<A>,List<A>>	sort() Sort a list.
static <A,B extends A> A[]	toArray(Class<A> elemType, Collection<B> a) Create an array from a collection.
static double[]	toDoubleArray(Collection<Double> as) Convert a collection of Doubles into an array of primitive type.
static float[]	toFloatArray(Collection<Float> as) Convert a collection of Floats into an array of primitive type.
static int[]	toIntArray(Collection<Integer> as) Convert a collection of Integers into an array of primitive type.
static <A> List<A>	toList(A a) Return nil if a is null or a list containing a otherwise.
static <A> List<A>	toList(Collection<A> as) Drain all elements of as into a list.
static <A> List<A>	toList(Iterator<? extends A> as) Drain all elements of as into a list.
static <K,V> List<Tuple<K,V>>	toList(Map<K,V> map) Create a list of tuples (K, V) from a map.
static <K,V> Map<K,V>	toList(Tuple<? extends K,? extends V>... ts)
static Map<String,String>	toMap(Properties p) Convert a properties object into a typed immutable map.
static <A> Set<A>	toSet(List<A> as) Create a set from a list.
static <A,B> Collection<A>	unique(List<A> as, Function<A,B> criteria) Create a list of unique elements determined by a given criteria.

Methods inherited from class java.lang.Object

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

Method Detail

getOrCreate

public static <K,V> V getOrCreate(Map<K,V> map,
                                  K key,
                                  Creator<V> c)

Get a value from a map, creating and adding a new one, if the value is missing, i.e. it is null.

Parameters:

c - creates the missing value

getOrCreate

public static <K,V> V getOrCreate(Map<K,V> map,
                                  K key,
                                  Function0<V> f)

Get a value from a map, creating and adding a new one, if the value is missing, i.e. it is null.

map

@Deprecated
public static <A,B,M extends Collection<B>> M map(Collection<A> as,
                                                              M bs,
                                                              Function<A,B> f)

Deprecated. use Monadics

Apply a function f to all elements of collection as to produce a new collection bs. An (empty) instance of the target collection has to be provided explicitly.

Parameters:

as - the source collection

bs - the (empty) target collection

f - the function to apply to each element of as

foldl

@Deprecated
public static <A,B> B foldl(Collection<A> as,
                                        B start,
                                        Function2<B,A,B> f)

Deprecated. use Monadics

Apply a binary function (operator) to a start value and all elements of the list in turn. Example: (+) 0 [1, 2, 3] -> (((0 + 1) + 2) + 3)

map

@Deprecated
public static <A,B> Collection<B> map(Collection<A> as,
                                                  Function<A,B> f)

Deprecated. use Monadics

Apply a function f to all elements of collection as to produce a new collection bs. The type of collection as needs a parameterless constructor. Please note that since java does not support higher-order polymorphism -- which is needed to capture the type of the collection -- some casting on the client side may still be necessary.

Throws:

RuntimeException - if the target collection cannot be created

flatMap

@Deprecated
public static <A,B> Collection<B> flatMap(Collection<A> as,
                                                      Function<A,Collection<B>> f)

Deprecated. use Monadics

Apply a function f to all elements of collection as to produce a new collection bs by concatenating the results. The type of collection as needs a parameterless constructor. Please note that since java does not support higher-order polymorphism -- which is needed to capture the type of the collection -- some casting on the client side may still be necessary.

Throws:

RuntimeException - if the result collection cannot be created

flatMap

@Deprecated
public static <A,B,M extends Collection<B>> M flatMap(Collection<A> as,
                                                                  M bs,
                                                                  Function<A,Collection<B>> f)

Deprecated. use Monadics

Exactly like flatMap(java.util.Collection, Function) but you have to provide the target collection yourself.

find

@Deprecated
public static <A> Option<A> find(Collection<A> as,
                                             Predicate<A> p)

Deprecated. use Monadics

Returns the first element in as that satisfies a predicate p.

exists

@Deprecated
public static <A> boolean exists(Collection<A> as,
                                             Predicate<A> p)

Deprecated. use Monadics

Tests if at least one element in as satisfies predicate p.

filter

@Deprecated
public static <A,M extends Collection<A>> M filter(M as,
                                                               Predicate<A> p)

Deprecated. use Monadics

Return a new collection containing only the elements that satisfy predicate p. The type of collection as needs a parameterless constructor.

head

public static <A> Option<A> head(List<A> as)

Return the head of list as or none.

last

public static <A> Option<A> last(List<A> as)

Return the last element of the list.

last

public static <A> Option<A> last(A[] as)

Return the last element of the array.

mkString

public static String mkString(Collection<?> as,
                              String sep)

Make a string from a collection separating each element by sep.

appendTo

public static <A,T extends Collection<A>,S extends Iterable<? extends A>> T appendTo(T target,
                                                                                     S as)

Append source collection as to target.

appendToM

@SafeVarargs
public static <A,T extends Collection<A>,S extends Iterable<? extends A>> T appendToM(T target,
                                                                                                   S... as)

Append source collections as to target.

appendToA

@SafeVarargs
public static <A,T extends Collection<A>,X extends A> T appendToA(T target,
                                                                               X... as)

Append source collections as to target.

concat

public static <A,M extends Iterable<? extends A>> List<A> concat(M as,
                                                                 M bs)

Concatenates two iterables into a new list.

concat

public static <A> List<A> concat(List<? extends A> as,
                                 List<? extends A> bs)

Concatenates two lists.

merge

public static <A,B> Map<A,B> merge(Map<? extends A,? extends B> a,
                                   Map<? extends A,? extends B> b)

Merge two maps where b takes precedence.

Returns:

a new immutable map

merge

public static <A> Set<A> merge(Set<? extends A> a,
                               Set<? extends A> b)

Merge two sets into one. b takes precedence over a.

Returns:

a new immutable set

diff

public static <A,M extends Iterable<? extends A>> List<A> diff(M as,
                                                               M bs)

toList

public static <A> List<A> toList(Iterator<? extends A> as)

Drain all elements of as into a list.

toList

public static <K,V> List<Tuple<K,V>> toList(Map<K,V> map)

Create a list of tuples (K, V) from a map.

toList

@SafeVarargs
public static <K,V> Map<K,V> toList(Tuple<? extends K,? extends V>... ts)

toList

public static <A> List<A> toList(Collection<A> as)

Drain all elements of as into a list.

toList

public static <A> List<A> toList(A a)

Return nil if a is null or a list containing a otherwise.

mkList

@Deprecated
public static <A> List<A> mkList(List<A> as)

Deprecated. use nullToNil(java.util.List)

Return the list as is or nil, if as is null.

nullToNil

public static <A> List<A> nullToNil(List<A> as)

Return the list as is or nil, if as is null.

list

@SafeVarargs
public static <A> List<A> list(A... as)

Create a list from an array.

nonNullList

@SafeVarargs
public static <A> List<A> nonNullList(A... as)

Create a list from an array.

nil

public static <A> List<A> nil()

The empty list.

nil

public static <A> List<A> nil(Class<A> type)

The empty list.

cons

public static <A> List<A> cons(A a,
                               List<? extends A> as)

Construct a new list by prepending an element to a given list.

set

@SafeVarargs
public static <A> Set<A> set(A... as)

Create a set from an array.

toSet

public static <A> Set<A> toSet(List<A> as)

Create a set from a list.

map

@SafeVarargs
public static <K,V> Map<K,V> map(Tuple<? extends K,? extends V>... ts)

Create a map from a list of tuples (K, V).

smap

@SafeVarargs
public static <K,V> SortedMap<K,V> smap(Tuple<? extends K,? extends V>... ts)

Create a sorted map from a list of tuples (K, V) based on the natural ordering of K.

dict

@SafeVarargs
public static <K,V> Dictionary<K,V> dict(Tuple<? extends K,? extends V>... ts)

Create a dictionary from a list of tuples (K, V).

properties

@SafeVarargs
public static Properties properties(Tuple<String,String>... ts)

Create properties from a list of tuples (K, V).

toMap

public static Map<String,String> toMap(Properties p)

Convert a properties object into a typed immutable map.

groupBy

public static <K,V> com.google.common.collect.Multimap<K,V> groupBy(com.google.common.collect.Multimap<K,V> map,
                                                                    Iterable<? extends V> values,
                                                                    Function<? super V,? extends K> group)

Partition a list after some predicate group into map. Use e.g. ArrayListMultimap.create() to create a multimap.

See Also:

groupBy(Iterable, Function)

groupBy

public static <K,V> com.google.common.collect.ImmutableMultimap<K,V> groupBy(Iterable<? extends V> values,
                                                                             Function<? super V,? extends K> group)

Partition a list after some predicate group into map.

Returns:

an ImmutableMultimap

See Also:

groupBy(com.google.common.collect.Multimap, Iterable, Function)

makeMap

public static <K,V,X> com.google.common.collect.Multimap<K,V> makeMap(com.google.common.collect.Multimap<K,V> map,
                                                                      Iterable<? extends X> values,
                                                                      Function<? super X,Tuple<K,V>> group)

Partition a list after some predicate group into map.

grouped

public static <A> List<List<A>> grouped(List<A> as,
                                        int size)

Partition a list in chunks of size size. The last chunk may be smaller.

unique

public static <A,B> Collection<A> unique(List<A> as,
                                         Function<A,B> criteria)

Create a list of unique elements determined by a given criteria.

asMap

public static <K,V> Map<K,V> asMap(List<V> values,
                                   Function<V,K> keyGen)

Partition a list after some predicate keyGen. The partition function has to make sure that keys are unique per list element because each key holds only one value. Later values overwrite newer ones. The resulting map is an immutable HashMap.

See Also:

asMap(java.util.Map, java.util.List, Function)

asMap

public static <K,V> Map<K,V> asMap(Map<K,V> map,
                                   List<V> values,
                                   Function<V,K> keyGen)

Partition a list after some predicate keyGen into map. The partition function has to make sure that keys are unique per list element because each key holds only one value. Later values overwrite newer ones.

See Also:

asMap(java.util.List, Function)

toArray

public static <A,B extends A> A[] toArray(Class<A> elemType,
                                          Collection<B> a)

Create an array from a collection.

toDoubleArray

public static double[] toDoubleArray(Collection<Double> as)

Convert a collection of Doubles into an array of primitive type.

toFloatArray

public static float[] toFloatArray(Collection<Float> as)

Convert a collection of Floats into an array of primitive type.

toIntArray

public static int[] toIntArray(Collection<Integer> as)

Convert a collection of Integers into an array of primitive type.

iterator

@SafeVarargs
public static <A> Iterator<A> iterator(A... as)

Create an iterator form an array.

repeat

public static <A,X extends A> Iterator<A> repeat(X a,
                                                 int times)

Create an iterator that repeats a for the said times.

join

public static <A> Iterator<A> join(Iterator<A> a,
                                   Iterator<A> b)

Join two iterators.

forc

public static <A> Iterable<A> forc(Iterator<A> as)

Make an Iterator usable in a for comprehension like this:

   Iterator<A> as = ...
   for (A a : forc(as)) {
     ...
   }
 

optionToList

public static <A> Function<Option<A>,List<A>> optionToList()

flatMapArrayToList

public static <A,B> Function<A[],List<B>> flatMapArrayToList(Function<A,List<B>> f)

optionToIterator

public static <A> Function<Option<A>,Iterator<A>> optionToIterator()

Turn an option into an iterator.

head

public static <A> Function<List<A>,Option<A>> head()

sort

public static <A extends Comparable> Function<List<A>,List<A>> sort()

Sort a list.

containedIn

public static <A> Function<A,Boolean> containedIn(List<A> as)

Create a function that checks if its argument is contained in as.

containedIn

public static <A> Function<List<A>,Function<A,Boolean>> containedIn()

Curried version of List.contains(Object).

getOrElse

public static <A> Function<Option<A>,A> getOrElse(A a)

concat

public static <A,M extends Collection<? extends Collection<A>>> List<A> concat(M as)

Concat (aka flatten) a collection of collections by concatenating them all. [[a]] -> [a]

getMap

public static <A,B> Function<A,Option<B>> getMap(Map<A,B> map)

Return a function to get data from a map. map -> key -> value