com.diffplug.common.collect

Class Immutables

java.lang.Object

com.diffplug.common.collect.Immutables

public class Immutables
extends Object

This class contains static methods for manipulating and creating immutable collections.

1. Creating mutated copies of existing immutable collections
2. Mapping Optional to/from ImmutableSet
3. Java 8 Collectors for immutable collections

Mutating existing immutable collections

For each kind of ImmutableCollection, this class contains a static method:

• ImmutableCollection mutateCollection(ImmutableCollection source, Consumer<MutableCollection> mutator)

e.g. ImmutableSet mutateSet(ImmutableSet source, Consumer<Set> mutator) and so on for List, Set, Map, SortedSet, SortedMap, and BiMap.

The methods work as follows:

• Copy the ImmutableCollection into a new MutableCollection. (e.g. ImmutableSet into LinkedHashSet)
• Pass this MutableCollection to the mutator, which modifies it.
• Copy the (now-modified) MutableCollection into a new ImmutableCollection.
• Return this ImmutableCollection.

There are also UnaryOperator<ImmutableCollection> mutatorCollection(Consumer<MutableCollection> mutator) variants for each of the collection types. These are a short hand for this:

public static <T> UnaryOperator<ImmutableList<T>> mutatorList(Consumer<List<T>> mutator) {
    return input -> mutateList(input, mutator);
}

There also methods for per-element mutators.

Mapping Optional to/from ImmutableSet

• optionalFrom(ImmutableCollection)
• optionalToSet(Optional)

Creating new immutable collections using Java 8 Collector’s

• toList()
• toSet()
• toMap(Function, Function)
• toSortedSet(Comparator)
• toSortedMap(Comparator, Function, Function)
• toBiMap(Function, Function)

Each collector method also contains a version in which the constructor takes an initialCapacity argument, which helps with performance.

Method Summary

Modifier and Type	Method and Description
static <K,V> ImmutableBiMap<K,V>	mutateBiMap(ImmutableBiMap<K,V> source, Consumer<BiMap<K,V>> mutator) Returns a mutated version of the given sorted map.
static <T> ImmutableList<T>	mutateList(ImmutableList<T> source, Consumer<List<T>> mutator) Returns a mutated version of the given list.
static <K,V> ImmutableMap<K,V>	mutateMap(ImmutableMap<K,V> source, Consumer<Map<K,V>> mutator) Returns a mutated version of the given map.
static <T> ImmutableSet<T>	mutateSet(ImmutableSet<T> source, Consumer<Set<T>> mutator) Returns a mutated version of the given set.
static <K,V> ImmutableSortedMap<K,V>	mutateSortedMap(ImmutableSortedMap<K,V> source, Consumer<NavigableMap<K,V>> mutator) Returns a mutated version of the given sorted map.
static <T> ImmutableSortedSet<T>	mutateSortedSet(ImmutableSortedSet<T> source, Consumer<NavigableSet<T>> mutator) Returns a mutated version of the given sorted set.
static <K,V> UnaryOperator<ImmutableBiMap<K,V>>	mutatorBiMap(Consumer<BiMap<K,V>> mutator) Returns a function which mutates a sorted map using the given mutator.
static <T> UnaryOperator<ImmutableList<T>>	mutatorList(Consumer<List<T>> mutator) Returns a function which mutates a list using the given mutator.
static <K,V> UnaryOperator<ImmutableMap<K,V>>	mutatorMap(Consumer<Map<K,V>> mutator) Returns a function which mutates a map using the given mutator.
static <T> UnaryOperator<ImmutableSet<T>>	mutatorSet(Consumer<Set<T>> mutator) Returns a function which mutates a set using the given mutator.
static <K,V> UnaryOperator<ImmutableSortedMap<K,V>>	mutatorSortedMap(Consumer<NavigableMap<K,V>> mutator) Returns a function which mutates a sorted map using the given mutator.
static <T> UnaryOperator<ImmutableSortedSet<T>>	mutatorSortedSet(Consumer<NavigableSet<T>> mutator) Returns a function which mutates a sorted set using the given mutator.
static <T> Optional<T>	optionalFrom(ImmutableCollection<T> collection) Converts an ImmutableCollection to an Optional.
static <T> ImmutableSet<T>	optionalToSet(Optional<T> selection) Converts an Optional to an ImmutableSet.
static <T,R> Converter<ImmutableList<T>,ImmutableList<R>>	perElementConverterList(ConverterNullable<T,R> perElement) Uses a Converter<T, R> to generate a Converter<ImmutableList<T>, ImmutableList<R>>.
static <T,R> Converter<Optional<T>,Optional<R>>	perElementConverterOpt(ConverterNullable<T,R> perElement) Uses a Converter<T, R> to generate a Converter<Optional<T>, Optional<R>>.
static <T,R> Converter<ImmutableSet<T>,ImmutableSet<R>>	perElementConverterSet(ConverterNullable<T,R> perElement) Uses a Converter<T, R> to generate a Converter<ImmutableSet<T>, ImmutableSet<R>>.
static <T,R> ImmutableList<R>	perElementMutateList(ImmutableList<T> source, Function<? super T,? extends R> mutator) Returns a mutated version of the given set.
static <T,R> ImmutableSet<R>	perElementMutateSet(ImmutableSet<T> source, Function<? super T,? extends R> mutator) Returns a mutated version of the given set.
static <T,K,V> Collector<T,?,ImmutableBiMap<K,V>>	toBiMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends V> valueMapper) A Collector which returns an ImmutableBiMap which is ordered by the given comparator, and populated by the given pair of key and value functions.
static <T,K,V> Collector<T,?,ImmutableBiMap<K,V>>	toBiMap(int initialCapacity, Function<? super T,? extends K> keyMapper, Function<? super T,? extends V> valueMapper) A Collector which returns an ImmutableBiMap which is ordered by the given comparator, and populated by the given pair of key and value functions.
static <T> Collector<T,?,ImmutableList<T>>	toList() A Collector which returns an ImmutableList.
static <T> Collector<T,?,ImmutableList<T>>	toList(int initialCapacity) A Collector which returns an ImmutableList, with the given initial capacity.
static <T,K,V> Collector<T,?,ImmutableMap<K,V>>	toMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends V> valueMapper) A Collector which returns an ImmutableMap using the given pair of key and value functions.
static <T,K,V> Collector<T,?,ImmutableMap<K,V>>	toMap(int initialCapacity, Function<? super T,? extends K> keyMapper, Function<? super T,? extends V> valueMapper) A Collector which returns an ImmutableMap using the given initial capacity and pair of key and value functions
static <T> Collector<T,?,ImmutableSet<T>>	toSet() A Collector which returns an ImmutableSet.
static <T> Collector<T,?,ImmutableSet<T>>	toSet(int initialCapacity) A Collector which returns an ImmutableSet, with the given initial capacity.
static <T,K extends Comparable<?>,V> Collector<T,?,ImmutableSortedMap<K,V>>	toSortedMap(Comparator<? super K> comparator, Function<? super T,? extends K> keyMapper, Function<? super T,? extends V> valueMapper) A Collector which returns an ImmutableSortedMap ordered by the given comparator, and populated by the given pair of key and value functions.
static <T,K extends Comparable<?>,V> Collector<T,?,ImmutableSortedMap<K,V>>	toSortedMap(int initialCapacity, Comparator<? super K> comparator, Function<? super T,? extends K> keyMapper, Function<? super T,? extends V> valueMapper) A Collector which returns an ImmutableSortedMap using the given initial capacity, ordered by the given comparator, and populated by the given pair of key and value functions.
static <T> Collector<T,?,ImmutableSortedSet<T>>	toSortedSet(Comparator<? super T> comparator) A Collector which returns an ImmutableSortedSet which is ordered by the given comparator.
static <T> Collector<T,?,ImmutableSortedSet<T>>	toSortedSet(int initialCapacity, Comparator<? super T> comparator) A Collector which returns an ImmutableSortedSet using the given initial capacity and ordered by the given comparator.

Methods inherited from class java.lang.Object

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

Method Detail

mutateList

public static <T> ImmutableList<T> mutateList(ImmutableList<T> source,
                                              Consumer<List<T>> mutator)

Returns a mutated version of the given list.

mutateSet

public static <T> ImmutableSet<T> mutateSet(ImmutableSet<T> source,
                                            Consumer<Set<T>> mutator)

Returns a mutated version of the given set.

mutateMap

public static <K,V> ImmutableMap<K,V> mutateMap(ImmutableMap<K,V> source,
                                                Consumer<Map<K,V>> mutator)

Returns a mutated version of the given map.

mutateSortedSet

public static <T> ImmutableSortedSet<T> mutateSortedSet(ImmutableSortedSet<T> source,
                                                        Consumer<NavigableSet<T>> mutator)

Returns a mutated version of the given sorted set.

mutateSortedMap

public static <K,V> ImmutableSortedMap<K,V> mutateSortedMap(ImmutableSortedMap<K,V> source,
                                                            Consumer<NavigableMap<K,V>> mutator)

Returns a mutated version of the given sorted map.

mutateBiMap

public static <K,V> ImmutableBiMap<K,V> mutateBiMap(ImmutableBiMap<K,V> source,
                                                    Consumer<BiMap<K,V>> mutator)

Returns a mutated version of the given sorted map.

mutatorList

public static <T> UnaryOperator<ImmutableList<T>> mutatorList(Consumer<List<T>> mutator)

Returns a function which mutates a list using the given mutator.

mutatorSet

public static <T> UnaryOperator<ImmutableSet<T>> mutatorSet(Consumer<Set<T>> mutator)

Returns a function which mutates a set using the given mutator.

mutatorMap

public static <K,V> UnaryOperator<ImmutableMap<K,V>> mutatorMap(Consumer<Map<K,V>> mutator)

Returns a function which mutates a map using the given mutator.

mutatorSortedSet

public static <T> UnaryOperator<ImmutableSortedSet<T>> mutatorSortedSet(Consumer<NavigableSet<T>> mutator)

Returns a function which mutates a sorted set using the given mutator.

mutatorSortedMap

public static <K,V> UnaryOperator<ImmutableSortedMap<K,V>> mutatorSortedMap(Consumer<NavigableMap<K,V>> mutator)

Returns a function which mutates a sorted map using the given mutator.

mutatorBiMap

public static <K,V> UnaryOperator<ImmutableBiMap<K,V>> mutatorBiMap(Consumer<BiMap<K,V>> mutator)

Returns a function which mutates a sorted map using the given mutator.

perElementMutateList

public static <T,R> ImmutableList<R> perElementMutateList(ImmutableList<T> source,
                                                          Function<? super T,? extends R> mutator)

Returns a mutated version of the given set. Function can return null to indicate the element should be removed.

perElementMutateSet

public static <T,R> ImmutableSet<R> perElementMutateSet(ImmutableSet<T> source,
                                                        Function<? super T,? extends R> mutator)

Returns a mutated version of the given set. Function can return null to indicate the element should be removed.

perElementConverterOpt

public static <T,R> Converter<Optional<T>,Optional<R>> perElementConverterOpt(ConverterNullable<T,R> perElement)

Uses a Converter<T, R> to generate a Converter<Optional<T>, Optional<R>>.

perElementConverterSet

public static <T,R> Converter<ImmutableSet<T>,ImmutableSet<R>> perElementConverterSet(ConverterNullable<T,R> perElement)

Uses a Converter<T, R> to generate a Converter<ImmutableSet<T>, ImmutableSet<R>>.

perElementConverterList

public static <T,R> Converter<ImmutableList<T>,ImmutableList<R>> perElementConverterList(ConverterNullable<T,R> perElement)

Uses a Converter<T, R> to generate a Converter<ImmutableList<T>, ImmutableList<R>>.

optionalToSet

public static <T> ImmutableSet<T> optionalToSet(Optional<T> selection)

Converts an Optional to an ImmutableSet.

optionalFrom

public static <T> Optional<T> optionalFrom(ImmutableCollection<T> collection)

Converts an ImmutableCollection to an Optional.

Throws:

IllegalArgumentException - if there are multiple elements.

toList

public static <T> Collector<T,?,ImmutableList<T>> toList()

A Collector which returns an ImmutableList.

toList

public static <T> Collector<T,?,ImmutableList<T>> toList(int initialCapacity)

A Collector which returns an ImmutableList, with the given initial capacity.

toSet

public static <T> Collector<T,?,ImmutableSet<T>> toSet()

A Collector which returns an ImmutableSet.

toSet

public static <T> Collector<T,?,ImmutableSet<T>> toSet(int initialCapacity)

A Collector which returns an ImmutableSet, with the given initial capacity.

toMap

public static <T,K,V> Collector<T,?,ImmutableMap<K,V>> toMap(Function<? super T,? extends K> keyMapper,
                                                             Function<? super T,? extends V> valueMapper)

A Collector which returns an ImmutableMap using the given pair of key and value functions.

toMap

public static <T,K,V> Collector<T,?,ImmutableMap<K,V>> toMap(int initialCapacity,
                                                             Function<? super T,? extends K> keyMapper,
                                                             Function<? super T,? extends V> valueMapper)

A Collector which returns an ImmutableMap using the given initial capacity and pair of key and value functions

toSortedSet

public static <T> Collector<T,?,ImmutableSortedSet<T>> toSortedSet(Comparator<? super T> comparator)

A Collector which returns an ImmutableSortedSet which is ordered by the given comparator.

toSortedSet

public static <T> Collector<T,?,ImmutableSortedSet<T>> toSortedSet(int initialCapacity,
                                                                   Comparator<? super T> comparator)

A Collector which returns an ImmutableSortedSet using the given initial capacity and ordered by the given comparator.

toSortedMap

public static <T,K extends Comparable<?>,V> Collector<T,?,ImmutableSortedMap<K,V>> toSortedMap(Comparator<? super K> comparator,
                                                                                               Function<? super T,? extends K> keyMapper,
                                                                                               Function<? super T,? extends V> valueMapper)

A Collector which returns an ImmutableSortedMap ordered by the given comparator, and populated by the given pair of key and value functions.

toSortedMap

public static <T,K extends Comparable<?>,V> Collector<T,?,ImmutableSortedMap<K,V>> toSortedMap(int initialCapacity,
                                                                                               Comparator<? super K> comparator,
                                                                                               Function<? super T,? extends K> keyMapper,
                                                                                               Function<? super T,? extends V> valueMapper)

A Collector which returns an ImmutableSortedMap using the given initial capacity, ordered by the given comparator, and populated by the given pair of key and value functions.

toBiMap

public static <T,K,V> Collector<T,?,ImmutableBiMap<K,V>> toBiMap(Function<? super T,? extends K> keyMapper,
                                                                 Function<? super T,? extends V> valueMapper)

A Collector which returns an ImmutableBiMap which is ordered by the given comparator, and populated by the given pair of key and value functions.

toBiMap

public static <T,K,V> Collector<T,?,ImmutableBiMap<K,V>> toBiMap(int initialCapacity,
                                                                 Function<? super T,? extends K> keyMapper,
                                                                 Function<? super T,? extends V> valueMapper)

A Collector which returns an ImmutableBiMap which is ordered by the given comparator, and populated by the given pair of key and value functions.