Guava——CollectionUtils

2018-04-09 本文已影响234人 jiangmo

比 java.util.Collections强大的工具包。

Util 与Collection的对应关系

Interface	JDK or Guava?	Corresponding Guava utility class
`Collection`	JDK	`Collections2`
`List`	JDK	`Lists`
`Set`	JDK	`Sets`
`SortedSet`	JDK	`Sets`
`Map`	JDK	`Maps`
`SortedMap`	JDK	`Maps`
`Queue`	JDK	`Queues`
`Multiset`	Guava	`Multisets`
`Multimap`	Guava	`Multimaps`
`BiMap`	Guava	`Maps`
`Table`	Guava	`Tables`

Looking for transform, filter, and the like? That stuff is in our functional programming article, under functional idioms.

Iterable

Whenever possible, Guava prefers to provide utilities accepting an Iterable rather than a Collection. Here at Google, it's not out of the ordinary to encounter a "collection" that isn't actually stored in main memory, but is being gathered from a database, or from another data center, and can't support operations like size() without actually grabbing all of the elements.

As a result, many of the operations you might expect to see supported for all collections can be found in Iterables. Additionally, most Iterables methods have a corresponding version in Iterators that accepts the raw iterator.

The overwhelming majority of operations in the Iterables class are lazy: they only advance the backing iteration when absolutely necessary. Methods that themselves return Iterables return lazily computed views, rather than explicitly constructing a collection in memory.

As of Guava 12, Iterables is supplemented by the FluentIterable class, which wraps an Iterable and provides a "fluent" syntax for many of these operations.

Method	Description	See Also
`concat(Iterable<Iterable>)`	Returns a lazy view of the concatenation of several iterables.	`concat(Iterable...)`
`frequency(Iterable, Object)`	Returns the number of occurrences of the object.	Compare `Collections.frequency(Collection, Object)`; see `Multiset`
`partition(Iterable, int)`	Returns an unmodifiable view of the iterable partitioned into chunks of the specified size.	`Lists.partition(List, int)`, `paddedPartition(Iterable, int)`
`getFirst(Iterable, T default)`	Returns the first element of the iterable, or the default value if empty.	Compare `Iterable.iterator().next()`, `FluentIterable.first()`
`getLast(Iterable)`	Returns the last element of the iterable, or fails fast with a `NoSuchElementException`if it's empty.	`getLast(Iterable, T default)`, `FluentIterable.last()`
`elementsEqual(Iterable, Iterable)`	Returns true if the iterables have the same elements in the same order.	Compare `List.equals(Object)`
`unmodifiableIterable(Iterable)`	Returns an unmodifiable view of the iterable.	Compare `Collections.unmodifiableCollection(Collection)`
`limit(Iterable, int)`	Returns an `Iterable`returning at most the specified number of elements.	`FluentIterable.limit(int)`
`getOnlyElement(Iterable)`	Returns the only element in `Iterable`. Fails fast if the iterable is empty or has multiple elements.	`getOnlyElement(Iterable, T default)`

Collection-Like

Typically, collections support these operations naturally on other collections, but not on iterables.

Method	Analogous `Collection` method	`FluentIterable` equivalent
`addAll(Collection addTo, Iterable toAdd)`	`Collection.addAll(Collection)`
`contains(Iterable, Object)`	`Collection.contains(Object)`	`FluentIterable.contains(Object)`
`removeAll(Iterable removeFrom, Collection toRemove)`	`Collection.removeAll(Collection)`
`retainAll(Iterable removeFrom, Collection toRetain)`	`Collection.retainAll(Collection)`
`size(Iterable)`	`Collection.size()`	`FluentIterable.size()`
`toArray(Iterable, Class)`	`Collection.toArray(T[])`	`FluentIterable.toArray(Class)`
`isEmpty(Iterable)`	`Collection.isEmpty()`	`FluentIterable.isEmpty()`
`get(Iterable, int)`	`List.get(int)`	`FluentIterable.get(int)`
`toString(Iterable)`	`Collection.toString()`	`FluentIterable.toString()`

Each of these operations delegates to the corresponding Collection interface method when the input is actually a Collection. For example, if Iterables.size is passed a Collection, it will call the Collection.size method instead of walking through the iterator.

Method	Analogous `Collection` method	`FluentIterable` equivalent
`addAll(Collection addTo, Iterable toAdd)`	`Collection.addAll(Collection)`
`contains(Iterable, Object)`	`Collection.contains(Object)`	`FluentIterable.contains(Object)`
`removeAll(Iterable removeFrom, Collection toRemove)`	`Collection.removeAll(Collection)`
`retainAll(Iterable removeFrom, Collection toRetain)`	`Collection.retainAll(Collection)`
`size(Iterable)`	`Collection.size()`	`FluentIterable.size()`
`toArray(Iterable, Class)`	`Collection.toArray(T[])`	`FluentIterable.toArray(Class)`
`isEmpty(Iterable)`	`Collection.isEmpty()`	`FluentIterable.isEmpty()`
`get(Iterable, int)`	`List.get(int)`	`FluentIterable.get(int)`
`toString(Iterable)`	`Collection.toString()`	`FluentIterable.toString()`

Lists

Method	Description
`partition(List, int)`	Returns a view of the underlying list, partitioned into chunks of the specified size.
`reverse(List)`	Returns a reversed view of the specified list. Note: if the list is immutable, consider `ImmutableList.reverse()` instead.

Sets

These return a SetView, which can be used:

as a Set directly, since it implements the Set interface
by copying it into another mutable collection with copyInto(Set)
by making an immutable copy with immutableCopy()

Method
`union(Set, Set)`
`intersection(Set, Set)`
`difference(Set, Set)`
`symmetricDifference(Set, Set)`

Maps

uniqueIndex

Maps.uniqueIndex(Iterable, Function) addresses the common case of having a bunch of objects that each have some unique attribute, and wanting to be able to look up those objects based on that attribute.

Let's say we have a bunch of strings that we know have unique lengths, and we want to be able to look up the string with some particular length.

ImmutableMap<Integer, String> stringsByIndex = Maps.uniqueIndex(strings, new Function<String, Integer> () {
    public Integer apply(String string) {
      return string.length();
    }
  });

difference

Maps.difference(Map, Map) allows you to compare all the differences between two maps. It returns a MapDifference object, which breaks down the Venn diagram into:

Method	Description
`entriesInCommon()`	The entries which are in both maps, with both matching keys and values.
`entriesDiffering()`	The entries with the same keys, but differing values. The values in this map are of type `MapDifference.ValueDifference`, which lets you look at the left and right values.
`entriesOnlyOnLeft()`	Returns the entries whose keys are in the left but not in the right map.
`entriesOnlyOnRight()`	Returns the entries whose keys are in the right but not in the left map.

Map<String, Integer> left = ImmutableMap.of("a", 1, "b", 2, "c", 3);
Map<String, Integer> right = ImmutableMap.of("b", 2, "c", 4, "d", 5);
MapDifference<String, Integer> diff = Maps.difference(left, right);

diff.entriesInCommon(); // {"b" => 2}
diff.entriesDiffering(); // {"c" => (3, 4)}
diff.entriesOnlyOnLeft(); // {"a" => 1}
diff.entriesOnlyOnRight(); // {"d" => 5}

BiMap utilities

The Guava utilities on BiMap live in the Maps class, since a BiMap is also a Map.

`BiMap` utility	Corresponding `Map` utility
`synchronizedBiMap(BiMap)`	`Collections.synchronizedMap(Map)`
`unmodifiableBiMap(BiMap)`	`Collections.unmodifiableMap(Map)`

Multisets

Multimaps

index

构建另外的索引，可以分组
Let's say we want to group strings based on their length.

ImmutableSet<String> digits = ImmutableSet.of(
    "zero", "one", "two", "three", "four",
    "five", "six", "seven", "eight", "nine");
Function<String, Integer> lengthFunction = new Function<String, Integer>() {
  public Integer apply(String string) {
    return string.length();
  }
};
ImmutableListMultimap<Integer, String> digitsByLength = Multimaps.index(digits, lengthFunction);
/*
 * digitsByLength maps:
 *  3 => {"one", "two", "six"}
 *  4 => {"zero", "four", "five", "nine"}
 *  5 => {"three", "seven", "eight"}
 */

invertFrom

因为multiMap可构建N:N关系的key：value，所以可以invert一下

Since Multimap can map many keys to one value, and one key to many values, it can be useful to invert a Multimap. Guava provides invertFrom(Multimap toInvert, Multimap dest) to let you do this, without choosing an implementation for you.

NOTE: If you are using an ImmutableMultimap, consider ImmutableMultimap.inverse()instead.

ArrayListMultimap<String, Integer> multimap = ArrayListMultimap.create();
multimap.putAll("b", Ints.asList(2, 4, 6));
multimap.putAll("a", Ints.asList(4, 2, 1));
multimap.putAll("c", Ints.asList(2, 5, 3));

TreeMultimap<Integer, String> inverse = Multimaps.invertFrom(multimap, TreeMultimap.<String, Integer> create());
// note that we choose the implementation, so if we use a TreeMultimap, we get results in order
/*
 * inverse maps:
 *  1 => {"a"}
 *  2 => {"a", "b", "c"}
 *  3 => {"c"}
 *  4 => {"a", "b"}
 *  5 => {"c"}
 *  6 => {"b"}
 */

forMap

Need to use a Multimap method on a Map? forMap(Map) views a Map as a SetMultimap. This is particularly useful, for example, in combination with Multimaps.invertFrom.

Map<String, Integer> map = ImmutableMap.of("a", 1, "b", 1, "c", 2);
SetMultimap<String, Integer> multimap = Multimaps.forMap(map);
// multimap maps ["a" => {1}, "b" => {1}, "c" => {2}]
Multimap<Integer, String> inverse = Multimaps.invertFrom(multimap, HashMultimap.<Integer, String> create());
// inverse maps [1 => {"a", "b"}, 2 => {"c"}]

Wrappers

Multimap type	Unmodifiable	Synchronized	Custom
`Multimap`	`unmodifiableMultimap`	`synchronizedMultimap`	`newMultimap`
`ListMultimap`	`unmodifiableListMultimap`	`synchronizedListMultimap`	`newListMultimap`
`SetMultimap`	`unmodifiableSetMultimap`	`synchronizedSetMultimap`	`newSetMultimap`
`SortedSetMultimap`	`unmodifiableSortedSetMultimap`	`synchronizedSortedSetMultimap`	`newSortedSetMultimap`

Multimaps provides the traditional wrapper methods, as well as tools to get custom Multimap implementations based on Map and Collection implementations of your choice.

Multimap type	Unmodifiable	Synchronized	Custom
`Multimap`	`unmodifiableMultimap`	`synchronizedMultimap`	`newMultimap`
`ListMultimap`	`unmodifiableListMultimap`	`synchronizedListMultimap`	`newListMultimap`
`SetMultimap`	`unmodifiableSetMultimap`	`synchronizedSetMultimap`	`newSetMultimap`
`SortedSetMultimap`	`unmodifiableSortedSetMultimap`	`synchronizedSortedSetMultimap`	`newSortedSetMultimap`

Note that the custom Multimap methods expect a Supplier argument to generate fresh new collections. Here is an example of writing a ListMultimap backed by a TreeMap mapping to LinkedList.

ListMultimap<String, Integer> myMultimap = Multimaps.newListMultimap(
  Maps.<String, Collection<Integer>>newTreeMap(),
  new Supplier<LinkedList<Integer>>() {
    public LinkedList<Integer> get() {
      return Lists.newLinkedList();
    }
  });

Tables

`customTable`

Comparable to the Multimaps.newXXXMultimap(Map, Supplier) utilities,Tables.newCustomTable(Map, Supplier<Map>) allows you to specify a Table implementation using whatever row or column map you like.

// use LinkedHashMaps instead of HashMaps
Table<String, Character, Integer> table = Tables.newCustomTable(
  Maps.<String, Map<Character, Integer>>newLinkedHashMap(),
  new Supplier<Map<Character, Integer>> () {
    public Map<Character, Integer> get() {
      return Maps.newLinkedHashMap();
    }
  });