*/
@GwtCompatible
@ElementTypesAreNonnullByDefault
public final class Comparators {
  private Comparators() {}

  /**
   * Returns a new comparator which sorts iterables by comparing corresponding elements pairwise
   * until a nonzero result is found; imposes "dictionary order." If the end of one iterable is
   * reached, but not the other, the shorter iterable is considered to be less than the longer one.

   *
   * <p>The returned object is serializable if this object is serializable.
   *
   * @since 10.0
   */
  @GwtCompatible(serializable = true)
  public final <S extends @Nullable T> Equivalence<Iterable<S>> pairwise() {
    // Ideally, the returned equivalence would support Iterable<? extends T>. However,
    // the need for this is so rare that it's not worth making callers deal with the ugly wildcard.

      Iterable<? extends Comparator<? super T>> comparators) {
    return new CompoundOrdering<>(comparators);
  }

  /**
   * Returns a new ordering which sorts iterables by comparing corresponding elements pairwise until
   * a nonzero result is found; imposes "dictionary order". If the end of one iterable is reached,
   * but not the other, the shorter iterable is considered to be less than the longer one. For

<p>
The type <code>T</code> in a term of the form <code>T</code> or <code>~T</code> cannot
be a <a href="#Type_parameter_declarations">type parameter</a>, and the type sets of all
non-interface terms must be pairwise disjoint (the pairwise intersection of the type sets must be empty).
Given a type parameter <code>P</code>:
</p>

<pre>
interface {
	P                // illegal: P is a type parameter