Guava——CollectionUtils

比 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 NoSuchElementExceptionif 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 Iterablereturning 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();
    }
  });