* "plain {@code T}." This API provides that.
   */
  @SuppressWarnings({"nullness", "TypeParameterUnusedInFormals", "ReturnMissingNullable"})
  // The warnings are legitimate. Each time we use this method, we document why.
  @ParametricNullness
  static <T extends @Nullable Object> T uncheckedNull() {
    return null;
  }

  private NullnessCasts() {}

 * non-ASCII characters to their numeric entity replacements. These XML escapers provide the minimal
 * level of escaping to ensure that the output can be safely included in a Unicode XML document.
 *
 * <p>For details on the behavior of the escapers in this class, see sections <a
 * href="http://www.w3.org/TR/2008/REC-xml-20081126/#charsets">2.2</a> and <a

 * (such as an XML document). Typically (but not always), the inverse process of "unescaping" the
 * text is performed automatically by the relevant parser.
 *
 * <p>For example, an XML escaper would convert the literal string {@code "Foo<Bar>"} into {@code
 * "Foo&lt;Bar&gt;"} to prevent {@code "<Bar>"} from being confused with an XML tag. When the

  @SuppressWarnings({"nullness", "TypeParameterUnusedInFormals", "ReturnMissingNullable"})
  // The warnings are legitimate. Each time we use this method, we document why.
  @ParametricNullness
  static <T extends @Nullable Object> T unsafeNull() {
    return null;
  }

  private NullnessCasts() {}

 * entire "chunk" (of implementation-dependent length) is ready to be hashed.
 *
 * @author Kevin Bourrillion
 * @author Dimitris Andreou
 */
// TODO(kevinb): this class still needs some design-and-document-for-inheritance love
@ElementTypesAreNonnullByDefault
abstract class AbstractStreamingHasher extends AbstractHasher {
  /** Buffer via which we pass data to the hash algorithm (the implementor) */

 * context (such as an XML document). Typically (but not always), the inverse process of
 * "unescaping" the text is performed automatically by the relevant parser.
 *
 * <p>For example, an XML escaper would convert the literal string {@code "Foo<Bar>"} into {@code
 * "Foo&lt;Bar&gt;"} to prevent {@code "<Bar>"} from being confused with an XML tag. When the

          .add("aString", aString)
          .add("anInt", anInt)
          .add("anEnum", anEnum)
          .toString();
    }
  }

  /** Validates that the Comparator equivalent we document is correct. */
  @J2ktIncompatible // TODO b/315311435 - J2kt cannot emulate Comparator<C>.<U>thenComparing()
  public void testComparatorEquivalent() {
    Comparator<Foo> comparatorUsingComparisonChain =
        (a, b) ->

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all

    return new ByteSink() {
      @Override
      public OutputStream openStream() throws IOException {
        return encodingStream(encodedSink.openStream());
      }
    };
  }

  // TODO(lowasser): document the extent of leniency, probably after adding ignore(CharMatcher)

  private static byte[] extract(byte[] result, int length) {
    if (length == result.length) {
      return result;
    }

    return list;
  }

  @VisibleForTesting
  static int computeArrayListCapacity(int arraySize) {
    checkNonnegative(arraySize, "arraySize");

    // TODO(kevinb): Figure out the right behavior, and document it
    return Ints.saturatedCast(5L + arraySize + (arraySize / 10));
  }

  /**
   * Creates an {@code ArrayList} instance backed by an array with the specified initial size;