* its caller has made a mistake. This allows constructs such as
 *
 * {@snippet :
 * public static double sqrt(double value) {
 *   if (value < 0) {
 *     throw new IllegalArgumentException("input is negative: " + value);
 *   }
 *   // calculate square root
 * }
 * }
 *
 * <p>to be replaced with the more compact
 *
 * {@snippet :
 * public static double sqrt(double value) {

    return new Builder<>();
  }

  /**
   * A builder for creating immutable multiset instances, especially {@code public static final}
   * multisets ("constant multisets"). Example:
   *
   * {@snippet :
   * public static final ImmutableMultiset<Bean> BEANS =
   *     new ImmutableMultiset.Builder<Bean>()
   *         .addCopies(Bean.COCOA, 4)
   *         .addCopies(Bean.GARDEN, 6)

 * its caller has made a mistake. This allows constructs such as
 *
 * {@snippet :
 * public static double sqrt(double value) {
 *   if (value < 0) {
 *     throw new IllegalArgumentException("input is negative: " + value);
 *   }
 *   // calculate square root
 * }
 * }
 *
 * <p>to be replaced with the more compact
 *
 * {@snippet :
 * public static double sqrt(double value) {

@Immutable
public interface HashFunction {
  /**
   * Begins a new hash code computation by returning an initialized, stateful {@code Hasher}
   * instance that is ready to receive data. Example:
   *
   * {@snippet :
   * HashFunction hf = Hashing.md5();
   * HashCode hc = hf.newHasher()
   *     .putLong(id)
   *     .putBoolean(isActive)
   *     .hash();
   * }
   */
  Hasher newHasher();

  /**

 *   <li>Implementations generally do not cache hash codes. If your element or key type has a slow
 *       {@code hashCode} implementation, it should cache it itself.
 * </ul>
 *
 * <h4>Example usage</h4>
 *
 * {@snippet :
 * class Foo {
 *   private static final ImmutableSet<String> RESERVED_CODES =
 *       ImmutableSet.of("AZ", "CQ", "ZX");
 *
 *   private final ImmutableSet<String> codes;
 *

   * corresponding to smaller values of {@link Enum#ordinal()} should only be acquired before locks
   * with larger ordinals. Example:
   *
   * {@snippet :
   * enum MyLockOrder {
   *   FIRST, SECOND, THIRD;
   * }
   *
   * CycleDetectingLockFactory.WithExplicitOrdering<MyLockOrder> factory =

 * cache instances created by {@code CacheBuilder} will not perform any type of eviction.
 *
 * <p>Usage example:
 *
 * {@snippet :
 * LoadingCache<Key, Graph> graphs = CacheBuilder.newBuilder()
 *     .maximumSize(10000)
 *     .expireAfterWrite(Duration.ofMinutes(10))
 *     .removalListener(MY_LISTENER)
 *     .build(

   * maxLength} chars in length and will end with the given {@code truncationIndicator}. Otherwise,
   * the sequence will be returned as a string with no changes to the content.
   *
   * <p>Examples:
   *
   * {@snippet :
   * Ascii.truncate("foobar", 7, "..."); // returns "foobar"
   * Ascii.truncate("foobar", 5, "..."); // returns "fo..."
   * }
   *

    return new Builder<>(expectedSize);
  }

  /**
   * A builder for creating immutable bimap instances, especially {@code public static final} bimaps
   * ("constant bimaps"). Example:
   *
   * {@snippet :
   * static final ImmutableBiMap<String, Integer> WORD_TO_INT =
   *     new ImmutableBiMap.Builder<String, Integer>()
   *         .put("one", 1)
   *         .put("two", 2)
   *         .put("three", 3)

   * through the returned table.
   *
   * <p>It is imperative that the user manually synchronize on the returned table when accessing any
   * of its collection views:
   *
   * {@snippet :
   * Table<R, C, V> table = Tables.synchronizedTable(HashBasedTable.create());
   * ...
   * Map<C, V> row = table.row(rowKey); // Needn't be in synchronized block
   * ...