* }
 * }</pre>
 *
 * <p>would be flagged as having called {@code sqrt()} with an illegal argument.
 *
 * <h3>Performance</h3>
 *
 * <p>Avoid passing message arguments that are expensive to compute; your code will always compute
 * them, even though they usually won't be needed. If you have such arguments, use the conventional
 * if/throw idiom instead.
 *

        this.bitsPerChar = log2(chars.length, UNNECESSARY);
      } catch (ArithmeticException e) {
        throw new IllegalArgumentException("Illegal alphabet length " + chars.length, e);
      }

      // Compute how input bytes are chunked. For example, with base64 we chunk every 3 bytes into
      // 4 characters. We have bitsPerChar == 6, charsPerChunk == 4, and bytesPerChunk == 3.

      // Because Supplier is read-heavy, we use the "double-checked locking" pattern.
      if (delegate != SUCCESSFULLY_COMPUTED) {
        synchronized (this) {
          if (delegate != SUCCESSFULLY_COMPUTED) {
            T t = delegate.get();
            value = t;
            delegate = (Supplier<T>) SUCCESSFULLY_COMPUTED;
            return t;
          }
        }
      }
      // This is safe because we checked `delegate`.

   * the information of these hash codes in an ordered fashion. That is, whenever two equal hash
   * codes are produced by two calls to this method, it is <i>as likely as possible</i> that each
   * was computed from the <i>same</i> input hash codes in the <i>same</i> order.
   *
   * @throws IllegalArgumentException if {@code hashCodes} is empty, or the hash codes do not all
   *     have the same bit length
   */

   *
   * <p><i>Notes:</i> This is an implementation of the algorithm for Lexicographical Permutations
   * Generation, described in Knuth's "The Art of Computer Programming", Volume 4, Chapter 7,
   * Section 7.2.1.2. The iteration order follows the lexicographical order. This means that the
   * first permutation will be in ascending order, and the last will be in descending order.
   *

      }
    }
  }

  /**
   * Returns the expected number of distinct elements given the specified elements. The number of
   * distinct elements is only computed if {@code elements} is an instance of {@code Multiset};
   * otherwise the default value of 11 is returned.
   */
  static int inferDistinctElements(Iterable<?> elements) {
    if (elements instanceof Multiset) {

   * values are merged using the specified merging function. If the merging function returns {@code
   * null}, then the collector removes the value that has been computed for the key thus far (though
   * future occurrences of the key would reinsert it).
   *
   * <p>Entries will appear in the encounter order of the first occurrence of the key.
   *

   *
   * <p><i>Notes:</i> This is an implementation of the algorithm for Lexicographical Permutations
   * Generation, described in Knuth's "The Art of Computer Programming", Volume 4, Chapter 7,
   * Section 7.2.1.2. The iteration order follows the lexicographical order. This means that the
   * first permutation will be in ascending order, and the last will be in descending order.
   *

      return expectedSize + 1;
    }
    if (expectedSize < Ints.MAX_POWER_OF_TWO) {
      // This seems to be consistent across JDKs. The capacity argument to HashMap and LinkedHashMap
      // ends up being used to compute a "threshold" size, beyond which the internal table
      // will be resized. That threshold is ceilingPowerOfTwo(capacity*loadFactor), where
      // loadFactor is 0.75 by default. So with the calculation here we ensure that the

   */
  public static Equivalence<Object> equals() {
    return Equals.INSTANCE;
  }

  /**
   * Returns an equivalence that uses {@code ==} to compare values and {@link
   * System#identityHashCode(Object)} to compute the hash code. {@link Equivalence#equivalent}
   * returns {@code true} if {@code a == b}, including in the case that a and b are both null.
   *
   * @since 13.0
   * @since 4.0 (in Equivalences)
   */