*
 * <p>For example, this expression:
 *
 * {@snippet :
 * Splitter.on(',').split("foo,bar,qux")
 * }
 *
 * ... produces an {@code Iterable} containing {@code "foo"}, {@code "bar"} and {@code "qux"}, in
 * that order.
 *
 * <p>By default, {@code Splitter}'s behavior is simplistic and unassuming. The following
 * expression:
 *
 * {@snippet :
 * Splitter.on(',').split(" foo,,,  bar ,")
 * }
 *

 * 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());
 * }

 *
 * <p>Most implementations will only need to implement {@link #load}. Other methods may be
 * overridden as desired.
 *
 * <p>Usage example:
 *
 * {@snippet :
 * CacheLoader<Key, Graph> loader = new CacheLoader<Key, Graph>() {
 *   public Graph load(Key key) throws AnyException {
 *     return createExpensiveGraph(key);
 *   }
 * };

   * 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
   * }
   *

   * 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")

   * and not contents.
   *
   * <p>This is useful for implementing {@link Object#hashCode()}. For example, in an object that
   * has three properties, {@code x}, {@code y}, and {@code z}, one could write:
   *
   * {@snippet :
   * public int hashCode() {
   *   return Objects.hashCode(getX(), getY(), getZ());
   * }
   * }
   *
   * <p><b>Warning:</b> When a single object is supplied, the returned hash code does not equal the

   * and not contents.
   *
   * <p>This is useful for implementing {@link Object#hashCode()}. For example, in an object that
   * has three properties, {@code x}, {@code y}, and {@code z}, one could write:
   *
   * {@snippet :
   * public int hashCode() {
   *   return Objects.hashCode(getX(), getY(), getZ());
   * }
   * }
   *
   * <p><b>Warning:</b> When a single object is supplied, the returned hash code does not equal the

 * 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)

   */
  @Override
  boolean equals(@Nullable Object object);

  /**
   * Returns the hash code for this instance. This is defined as the hash code of
   *
   * {@snippet :
   * Arrays.asList(entriesOnlyOnLeft(), entriesOnlyOnRight(),
   *     entriesInCommon(), entriesDiffering())
   * }
   */
  @Override
  int hashCode();

  /**

 * 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());
 * }