## IMPORTANT WARNINGS

1. APIs marked with the `@Beta` annotation at the class or method level
are subject to change. They can be modified in any way, or even
removed, at any time. If your code is a library itself (i.e. it is
used on the CLASSPATH of users outside your own control), you should
not use beta APIs, unless you [repackage] them. **If your

 * annotation implies nothing about the quality or performance of the API in question, only the fact
 * that it is not "API-frozen."
 *
 * <p>It is generally safe for <i>applications</i> to depend on beta APIs, at the cost of some extra
 * work during upgrades. However it is generally inadvisable for <i>libraries</i> (which get
 * included on users' CLASSPATHs, outside the library developers' control) to do so.
 *

  @SuppressWarnings({
    // We use this method only for cases in which we need to decompose to primitives.
    "GoodTime-ApiWithNumericTimeUnit",
    "GoodTime-DecomposeToPrimitive",
    // We use this method only from within APIs that require a Duration.
    "Java7ApiChecker",
  })
  @IgnoreJRERequirement
  static long toNanosSaturated(Duration duration) {
    // Using a try/catch seems lazy, but the catch block will rarely get invoked (except for

  @SuppressWarnings({
    // We use this method only for cases in which we need to decompose to primitives.
    "GoodTime-ApiWithNumericTimeUnit",
    "GoodTime-DecomposeToPrimitive",
    // We use this method only from within APIs that require a Duration.
    "Java7ApiChecker",
  })
  @IgnoreJRERequirement
  static long toNanosSaturated(Duration duration) {
    // Using a try/catch seems lazy, but the catch block will rarely get invoked (except for

   *   <li>{@link #JAVA_COMPILER}, while still listed as required as of Java 15, is typically not
   *       available even under older version.
   *   <li>Any property may be cleared through APIs like {@link System#clearProperty}.
   *   <li>Unusual environments like GWT may have their own special handling of system properties.
   * </ul>
   *

  @Override
  public void close() {}

  public synchronized void clear() {
    list.clear();
  }

  /** Returns a snapshot of the logged records. */
  /*
   * TODO(cpovirk): consider higher-level APIs here (say, assertNoRecordsLogged(),
   * getOnlyRecordLogged(), getAndClearLogRecords()...)
   *
   * TODO(cpovirk): consider renaming this method to reflect that it takes a snapshot (and/or return
   * an ImmutableList)
   */

  @Override
  public void close() {}

  public synchronized void clear() {
    list.clear();
  }

  /** Returns a snapshot of the logged records. */
  /*
   * TODO(cpovirk): consider higher-level APIs here (say, assertNoRecordsLogged(),
   * getOnlyRecordLogged(), getAndClearLogRecords()...)
   *
   * TODO(cpovirk): consider renaming this method to reflect that it takes a snapshot (and/or return
   * an ImmutableList)
   */

   * (In other words, this method must allocate a new array). The caller is thus free to modify the
   * returned array.
   *
   * <p>This method acts as bridge between array-based and collection-based APIs.
   *
   * @return an array containing all of the elements in this queue
   */
  @CanIgnoreReturnValue
  @Override
  public Object[] toArray() {
    final E[] items = this.items;

                   If we're building with JDK8, then clearly we're sticking to
                   JDK8 APIs. However, I assume (but did not confirm) that we'd
                   have the same issue with our -android builds, which need
                   animal-sniffer so that they can check that we're sticking to
                   JDK6-like APIs.

                   So instead, we use javac9, which doesn't lead to this error.
              -->

 *
 * <h3>Relationship to {@code Ordering}</h3>
 *
 * <p>In light of the significant enhancements to {@code Comparator} in Java 8, the overwhelming
 * majority of usages of {@code Ordering} can be written using only built-in JDK APIs. This class is
 * intended to "fill the gap" and provide those features of {@code Ordering} not already provided by
 * the JDK.
 *
 * @since 21.0
 * @author Louis Wasserman
 */
@GwtCompatible