companies, or even industries — utilities useful for a sizable proportion of all Java
        programmers everywhere. If you can give enough detail such that any of us can imagine coming
        across a similar need in our own work, that's extremely helpful in studying how broadly
        useful the proposed change will be.

  - type: textarea
    attributes:
      label: Concrete Use Cases

   * {@code null}!) before returning it to callers. Depending on how the code is structured, a
   * nullness analysis might not understand that the field has been populated. To avoid that problem
   * without having to add {@code @SuppressWarnings}, the code can call this method.
   *
   * <p>Why <i>not</i> just add {@code SuppressWarnings}? The problem is that this method is

    UnicodeEscaper e = new PercentEscaper("%", false);
    assertEquals("foo%7Cbar", e.escape("foo|bar"));
    assertEquals("foo%7Cbar", e.escape("foo%7Cbar")); // idempotent
  }

  /** Test that giving a null 'safeChars' string causes a {@link NullPointerException}. */
  public void testBadArguments_null() {
    try {
      new PercentEscaper(null, false);
      fail("Expected null pointer exception for null parameter");

   * @since 12.0 (present as {@code compare} since 2.0)
   */
  public abstract ComparisonChain compareFalseFirst(boolean left, boolean right);

  /**
   * Ends this comparison chain and returns its result: a value having the same sign as the first
   * nonzero comparison result in the chain, or zero if every result was zero.
   */
  public abstract int result();

   * needed again; and for short-lived ones, it does not matter.
   */

  /**
   * Padded variant of AtomicLong supporting only raw accesses plus CAS. The value field is placed
   * between pads, hoping that the JVM doesn't reorder them.
   *
   * <p>JVM intrinsics note: It would be possible to use a release-only form of CAS here, if it were
   * provided.
   */
  static final class Cell {

   * this initiates service shutdown and returns immediately. If the service is {@linkplain
   * State#NEW new}, it is {@linkplain State#TERMINATED terminated} without having been started nor
   * stopped. If the service has already been stopped, this method returns immediately without
   * taking action.
   *
   * @return this
   * @since 15.0
   */
  @CanIgnoreReturnValue

 *
 * @author Kevin Bourrillion
 * @since 2.0
 */
@GwtCompatible(emulated = true)
@ElementTypesAreNonnullByDefault
public final class Predicates {
  private Predicates() {}

  // TODO(kevinb): considering having these implement a VisitablePredicate
  // interface which specifies an accept(PredicateVisitor) method.

  /** Returns a predicate that always evaluates to {@code true}. */
  @GwtCompatible(serializable = true)

 *       create a "fake" converter for a unit test. It is unnecessary (and confusing) to <i>mock</i>
 *       the {@code Converter} type using a mocking framework.
 *   <li>Extend this class and implement its {@link #doForward} and {@link #doBackward} methods.
 *   <li><b>Java 8+ users:</b> you may prefer to pass two lambda expressions or method references to

    assertEquals(Country.class, bimap.valueType());
  }

  public void testIterationOrder() {
    // The enum orderings are alphabetical, leading to the bimap and its inverse
    // having inconsistent iteration orderings.
    Map<Currency, Country> map =
        ImmutableMap.of(
            Currency.DOLLAR, Country.CANADA,
            Currency.PESO, Country.CHILE,

    assertEquals(Country.class, bimap.valueType());
  }

  public void testIterationOrder() {
    // The enum orderings are alphabetical, leading to the bimap and its inverse
    // having inconsistent iteration orderings.
    Map<Currency, Country> map =
        ImmutableMap.of(
            Currency.DOLLAR, Country.CANADA,
            Currency.PESO, Country.CHILE,