- Fixing or improving documentation.
  - Improvements to Maven configuration.

Guidelines for any code contributions:

  1. Any significant changes should be accompanied by tests. The project already
     has good test coverage, so look at some existing tests if you're unsure
     how to go about it.
  2. All contributions must be licensed Apache 2.0 and all files must have a

 *
 * <p>{@code containsKey(k)}, {@code put(k, v)} and {@code remove(k)} are all (expected and
 * amortized) constant time operations. Expected in the hashtable sense (depends on the hash
 * function doing a good job of distributing the elements to the buckets to a distribution not far
 * from uniform), and amortized since some operations can trigger a hash table resize.
 *

 * code point. An additional safe range is provided that determines whether code points without
 * specific replacements are to be considered safe and left unescaped or should be escaped in a
 * general way.
 *
 * <p>A good example of usage of this class is for HTML escaping where the replacement array
 * contains information about the named HTML entities such as {@code &amp;} and {@code &quot;} while

 *
 * <p>{@code contains(x)}, {@code add(x)} and {@code remove(x)}, are all (expected and amortized)
 * constant time operations. Expected in the hashtable sense (depends on the hash function doing a
 * good job of distributing the elements to the buckets to a distribution not far from uniform), and
 * amortized since some operations can trigger a hash table resize.
 *

  private static final long NOT_ENOUGH_MS = 5;

  private static final String GOOD_CALLABLE_RESULT = "good callable result";
  private static final Callable<String> GOOD_CALLABLE =
      new Callable<String>() {
        @Override
        public String call() throws InterruptedException {
          MILLISECONDS.sleep(DELAY_MS);
          return GOOD_CALLABLE_RESULT;
        }
      };

    assertEquals("<hello><hi><lo>", charEscaper.escape("x\uD800\uDC00"));
    assertEquals("<hello><hi><lo>", unicodeEscaper.escape("x\uD800\uDC00"));

    // Test that wrapped escapers acquire good Unicode semantics.
    assertEquals("<hi><hello><lo>", charEscaper.escape("\uD800x\uDC00"));
    try {
      unicodeEscaper.escape("\uD800x\uDC00");
      fail("should have failed for bad Unicode input");

   *
   * <p><b>Note:</b> the overhead of measurement can be more than a microsecond, so it is generally
   * not useful to specify {@link TimeUnit#NANOSECONDS} precision here.
   *
   * <p>It is generally not a good idea to use an ambiguous, unitless {@code long} to represent
   * elapsed time. Therefore, we recommend using {@link #elapsed()} instead, which returns a
   * strongly-typed {@code Duration} instance.
   *

  private void weaklyReferenceQueue() {
    frq = new FinalizableReferenceQueue();
    queueReference = new WeakReference<>(frq.queue);

    /*
     * Queue and clear a reference for good measure. We test later on that
     * the finalizer thread stopped, but we should test that it actually
     * started first.
     */
    reference =
        new FinalizableWeakReference<Object>(new Object(), frq) {

  private void weaklyReferenceQueue() {
    frq = new FinalizableReferenceQueue();
    queueReference = new WeakReference<>(frq.queue);

    /*
     * Queue and clear a reference for good measure. We test later on that
     * the finalizer thread stopped, but we should test that it actually
     * started first.
     */
    reference =
        new FinalizableWeakReference<Object>(new Object(), frq) {

import java.util.Collections;
import java.util.Iterator;
import org.checkerframework.checker.nullness.qual.Nullable;

/**
 * A utility for testing an Iterator implementation by comparing its behavior to that of a "known
 * good" reference implementation. In order to accomplish this, it's important to test a great
 * variety of sequences of the {@link Iterator#next}, {@link Iterator#hasNext} and {@link