* period or an interrupt while waiting for the expected event will result in a {@link
 * RuntimeException}.
 *
 * <p>Here's an example that tests a {@code finalize} method:
 *
 * {@snippet :
 * final CountDownLatch latch = new CountDownLatch(1);
 * Object x = new MyClass() {
 *   ...
 *   protected void finalize() { latch.countDown(); ... }
 * };
 * x = null;  // Hint to the JIT that x is stack-unreachable

   *
   * {@snippet :
   * b ---- a ---- d
   * |      |
   * |      |
   * e ---- c ---- f
   * }
   */
  private static final SuccessorsFunction<Character> JAVADOC_GRAPH =
      createUndirectedGraph("ba", "ad", "be", "ac", "ec", "cf");

  /**
   * A diamond shaped directed graph (arrows going down):
   *
   * {@snippet :
   *   a
   *  / \
   * b   c
   *  \ /

   *
   * {@snippet :
   * b ---- a ---- d
   * |      |
   * |      |
   * e ---- c ---- f
   * }
   */
  private static final SuccessorsFunction<Character> JAVADOC_GRAPH =
      createUndirectedGraph("ba", "ad", "be", "ac", "ec", "cf");

  /**
   * A diamond shaped directed graph (arrows going down):
   *
   * {@snippet :
   *   a
   *  / \
   * b   c
   *  \ /

 * period or an interrupt while waiting for the expected event will result in a {@link
 * RuntimeException}.
 *
 * <p>Here's an example that tests a {@code finalize} method:
 *
 * {@snippet :
 * final CountDownLatch latch = new CountDownLatch(1);
 * Object x = new MyClass() {
 *   ...
 *   protected void finalize() { latch.countDown(); ... }
 * };
 * x = null;  // Hint to the JIT that x is stack-unreachable

import java.util.concurrent.TimeoutException;
import org.jspecify.annotations.Nullable;

/**
 * A {@link ListenableFuture} that supports fluent chains of operations. For example:
 *
 * {@snippet :
 * ListenableFuture<Boolean> adminIsLoggedIn =
 *     FluentFuture.from(usersDatabase.getAdminUser())
 *         .transform(User::getId, directExecutor())
 *         .transform(ActivityService::isLoggedIn, threadPool)

   * respective source streams. For example:
   *
   * {@snippet :
   * Streams.forEachPair(
   *   Stream.of("foo1", "foo2", "foo3"),
   *   Stream.of("bar1", "bar2"),
   *   (arg1, arg2) -> System.out.println(arg1 + ":" + arg2)
   * }
   *
   * <p>will print:
   *
   * {@snippet :
   * foo1:bar1
   * foo2:bar2
   * }
   *

 * times when the first style is more useful, use the multimap's {@link #asMap} view (or create a
 * {@code Map<K, Collection<V>>} in the first place).
 *
 * <h3>Example</h3>
 *
 * <p>The following code:
 *
 * {@snippet :
 * ListMultimap<String, String> multimap = ArrayListMultimap.create();
 * for (President pres : US_PRESIDENTS_IN_ORDER) {
 *   multimap.put(pres.firstName(), pres.lastName());
 * }

 * generally prefer the methods in {@link Comparator}; see <a href="#java8">below</a>.
 *
 * <p>Example usage of {@code ComparisonChain}:
 *
 * {@snippet :
 * public int compareTo(Foo that) {
 *   return ComparisonChain.start()
 *       .compare(this.aString, that.aString)
 *       .compare(this.anInt, that.anInt)

   * java.util.stream} Javadoc), that order is preserved, but entries are <a
   * href="ImmutableMultimap.html#iteration">grouped by key</a>.
   *
   * <p>Example:
   *
   * {@snippet :
   * static final Multimap<Character, String> FIRST_LETTER_MULTIMAP =
   *     Stream.of("banana", "apple", "carrot", "asparagus", "cherry")

   * {@code Comparator}) input elements, in ascending order, as an unmodifiable {@code List}. Ties
   * are broken arbitrarily.
   *
   * <p>For example:
   *
   * {@snippet :
   * Stream.of("foo", "quux", "banana", "elephant")
   *     .collect(least(2, comparingInt(String::length)))
   * // returns {"foo", "quux"}
   * }
   *