/* * Copyright (C) 2007 The Guava Authors * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.google.common.collect; import static com.google.common.base.Preconditions.checkArgument; import static com.google.common.base.Preconditions.checkNotNull; import com.google.common.annotations.Beta; import com.google.common.annotations.GwtCompatible; import com.google.common.annotations.VisibleForTesting; import com.google.common.base.Function; import java.util.Arrays; import java.util.Collections; import java.util.Comparator; import java.util.HashSet; import java.util.Iterator; import java.util.List; import java.util.Map; import java.util.NoSuchElementException; import java.util.SortedMap; import java.util.SortedSet; import java.util.concurrent.atomic.AtomicInteger; import javax.annotation.Nullable; /** * A comparator with added methods to support common functions. For example: *
{@code * * if (Ordering.from(comparator).reverse().isOrdered(list)) { ... }}* * The {@link #from(Comparator)} method returns the equivalent {@code Ordering} * instance for a pre-existing comparator. You can also skip the comparator step * and extend {@code Ordering} directly:
{@code * * Ordering* * Except as noted, the orderings returned by the factory methods of this * class are serializable if and only if the provided instances that back them * are. For example, if {@code ordering} and {@code function} can themselves be * serialized, then {@code ordering.onResultOf(function)} can as well. * * @author Jesse Wilson * @author Kevin Bourrillion * @since 2.0 (imported from Google Collections Library) */ @GwtCompatible public abstract class OrderingbyLengthOrdering = new Ordering () { * public int compare(String left, String right) { * return Ints.compare(left.length(), right.length()); * } * };}
The type specification is {@code The returned comparator throws an {@link ClassCastException} when it
* receives an input parameter that isn't among the provided values.
*
* The generated comparator is serializable if all the provided values are
* serializable.
*
* @param valuesInOrder the values that the returned comparator will be able
* to compare, in the order the comparator should induce
* @return the comparator described above
* @throws NullPointerException if any of the provided values is null
* @throws IllegalArgumentException if {@code valuesInOrder} contains any
* duplicate values (according to {@link Object#equals})
*/
@GwtCompatible(serializable = true)
public static The returned comparator throws a {@link ClassCastException} when it
* receives an input parameter that isn't among the provided values.
*
* The generated comparator is serializable if all the provided values are
* serializable.
*
* @param leastValue the value which the returned comparator should consider
* the "least" of all values
* @param remainingValuesInOrder the rest of the values that the returned
* comparator will be able to compare, in the order the comparator should
* follow
* @return the comparator described above
* @throws NullPointerException if any of the provided values is null
* @throws IllegalArgumentException if any duplicate values (according to
* {@link Object#equals(Object)}) are present among the method arguments
*/
@GwtCompatible(serializable = true)
public static Because the ordering is identity-based, it is not "consistent with
* {@link Object#equals(Object)}" as defined by {@link Comparator}. Use
* caution when building a {@link SortedSet} or {@link SortedMap} from it, as
* the resulting collection will not behave exactly according to spec.
*
* This ordering is not serializable, as its implementation relies on
* {@link System#identityHashCode(Object)}, so its behavior cannot be
* preserved across serialization.
*
* @since 2.0
*/
public static Ordering