* the discussion in the {@link #addListener} documentation. All its warnings about heavyweight
   * listeners are also applicable to heavyweight functions passed to this method.
   *
   * <p>This method is similar to {@link java.util.concurrent.CompletableFuture#exceptionally}. It
   * can also serve some of the use cases of {@link java.util.concurrent.CompletableFuture#handle}

import java.util.Map;
import java.util.Map.Entry;
import java.util.Set;
import javax.annotation.CheckForNull;
import org.checkerframework.checker.nullness.qual.Nullable;

/**
 * A collection that maps keys to values, similar to {@link Map}, but in which each key may be
 * associated with <i>multiple</i> values. You can visualize the contents of a multimap either as a
 * map from keys to <i>nonempty</i> collections of values:
 *
 * <ul>

      // (Or it's a weird case like a LinkedList in a Cache<ArrayList, ...>, but *shrug*.)
      @SuppressWarnings("unchecked")
      K castKey = (K) key;
      @SuppressWarnings("unchecked") // similar to the above
      V castValue = (V) value;

      alertListenerIfPresent(castKey, castValue, RemovalCause.EXPLICIT);
      remove(key);
      return true;
    }
    return false;
  }

 *
 * <p>The implementations of many methods in this class are based on material from Henry S. Warren,
 * Jr.'s <i>Hacker's Delight</i>, (Addison Wesley, 2002).
 *
 * <p>Similar functionality for {@code int} and for {@link BigInteger} can be found in {@link
 * IntMath} and {@link BigIntegerMath} respectively. For other common operations on {@code long}
 * values, see {@link com.google.common.primitives.Longs}.

   * multisetToRetain.count(e)}.
   *
   * <p>To be precise, {@code multisetToModify.count(e)} is set to {@code
   * Math.min(multisetToModify.count(e), multisetToRetain.count(e))}. This is similar to {@link
   * #intersection(Multiset, Multiset) intersection} {@code (multisetToModify, multisetToRetain)},
   * but mutates {@code multisetToModify} instead of returning a view.
   *

  //     Iterable<? extends T> iterable,
  //     Predicate<? super T> predicate,
  //     @JointlyNullable T defaultValue);
  //
  // ...where "@JointlyNullable" is similar to @PolyNull but slightly different:
  //
  // - @PolyNull means "@Nullable or @Nonnull"
  //   (That would be unsound for an input Iterable<@Nullable Foo>. So, if we wanted to use

 * object.
 *
 * <p><b>Comparison to {@code java.util.Optional} (JDK 8 and higher):</b> A new {@code Optional}
 * class was added for Java 8. The two classes are extremely similar, but incompatible (they cannot
 * share a common supertype). <i>All</i> known differences are listed either here or with the
 * relevant methods below.
 *
 * <ul>

     *
     * https://github.com/google/guava/issues/2254
     *
     * Other kinds of Errors are possible:
     *
     * - OutOfMemoryError from allocations in setFuture(): The calculus here is similar to
     * StackOverflowError: We can't reliably call setException(error).
     *
     * - Any kind of Error from a listener. Even if we could distinguish that case (by exposing some

    @Override
    public V setValue(V value) {
      checkValue(value);
      // Preconditions keep the map and inverse consistent.
      checkState(entrySet().contains(this), "entry no longer in map");
      // similar to putInBothMaps, but set via entry
      if (Objects.equal(value, getValue())) {
        return value;
      }
      checkArgument(!containsValue(value), "value already present: %s", value);

   * can lead to surprising behavior, so serializing the returned list is <b>not recommended</b>.
   * Instead, copy the list using {@link ImmutableList#copyOf(Collection)} (for example), then
   * serialize the copy. Other methods similar to this do not implement serialization at all for
   * this reason.
   *
   * <p><b>Java 8+ users:</b> many use cases for this method are better addressed by {@link