Returns a multimap containing the mappings in
unfiltered whose keys
satisfy a predicate. The returned multimap is a live view of
unfiltered; changes to one affect the other.
The resulting multimap's views have iterators that don't support
remove(), but all other methods are supported by the multimap and
its views. When adding a key that doesn't satisfy the predicate, the
multimap's
put(),
putAll(), and
replaceValues()methods throw an
IllegalArgumentException.
When methods such as
removeAll() and
clear() are called on
the filtered multimap or its views, only mappings whose keys satisfy the
filter will be removed from the underlying multimap.
The returned multimap isn't threadsafe or serializable, even if
unfiltered is.
Many of the filtered multimap's methods, such as
size(), iterate
across every key/value mapping in the underlying multimap and determine
which satisfy the filter. When a live view is not needed, it may be
faster to copy the filtered multimap and use the copy.
Warning:
keyPredicate must be consistent with equals,
as documented at
Predicate#apply. Do not provide a predicate such
as
Predicates.instanceOf(ArrayList.class), which is inconsistent
with equals.