Интерфейс Comparator<T>

@FunctionalInterface
public interface Comparator<T>

Функция сравнения, которая накладывает полный порядок на некую коллекцию объектов. Компараторы могут передаваться методу сортировки (например, Collections.sort или Arrays.sort), чтобы обеспечить точный контроль над порядком сортировки. Компараторы также могут использоваться для управления порядком определенных структур данных (таких как sorted sets или sorted maps) или для предоставления порядка для коллекций объектов, которые не имеют natural ordering.

Порядок, налагаемый компаратором c на набор элементов S считается совместимым с equals тогда и только тогда, когда c.compare(e1, e2)==0 имеет то же булево значение, что и e1.equals(e2) для каждого e1 и e2 в S.

Следует соблюдать осторожность при использовании компаратора, способного накладывать порядок, несовместимый с equals, для упорядочивания отсортированного набора (или отсортированной карты). Предположим, что отсортированный набор (или отсортированная карта) с явным компаратором c используется с элементами (или ключами), взятыми из набора S. Если порядок, налагаемый c на S, несовместим с equals, отсортированный набор (или отсортированная карта) будет вести себя «странно». В частности, отсортированный набор (или отсортированная карта) нарушит общий контракт для набора (или карты), который определяется в терминах equals.

Например, предположим, что мы добавляем два элемента a и b, такие что (a.equals(b) && c.compare(a, b) != 0) в пустой TreeSet с компаратором c. Вторая операция add вернёт true (и размер набора увеличится), потому что a и b не эквивалентны с точки зрения набора, даже если это противоречит спецификации метода Set.add.

Примечание: В целом рекомендуется, чтобы компараторы также реализовывали java.io.Serializable, так как они могут использоваться в качестве методов упорядочения в сериализуемых структурах данных (например, TreeSet, TreeMap). Для успешной сериализации структуры данных компаратор (если он предоставлен) должен реализовывать Serializable.

Для математически настроенных, отношение, определяющее накладываемый порядок, который данный компаратор c накладывает на данный набор объектов S, следующее:

{(x, y) such that c.compare(x, y) <= 0}.

Частное для этого полного порядка:

{(x, y) such that c.compare(x, y) == 0}.

Из контракта для compare непосредственно следует, что частное является отношением эквивалентности на S, а налагаемый порядок является полным порядком на S. Когда мы говорим, что порядок, налагаемый c на S совместим с equals, мы имеем в виду, что частное для порядка является отношением эквивалентности, определённым методом(ами) equals(Object) объектов:

{(x, y) such that x.equals(y)}.

В отличие от Comparable, компаратор может по желанию допускать сравнение нулевых аргументов, сохраняя при этом требования к отношению эквивалентности.

Этот интерфейс является членом Java Collections Framework.

Методы

compare

int compare(T o1,
            T o2)

Параметры:

o1 - первый сравниваемый объект.

o2 - второй сравниваемый объект.

Возвращает:

отрицательное целое число, ноль или положительное целое число, если первый аргумент меньше, равен или больше второго соответственно.

Исключения:

NullPointerException - если аргумент равен null, и этот компаратор не допускает null-аргументов

ClassCastException - если типы аргументов не позволяют их сравнение этим компаратором.

equals

boolean equals(Object obj)

Переопределяет:

equals в классе Object

Параметры:

obj - объект-ссылка для сравнения.

Возвращает:

true только в том случае, если указанный объект также является компаратором и задаёт тот же порядок, что и этот компаратор.

См. также:

Object.equals(Object), Object.hashCode()

reversed

default Comparator<T> reversed()

Возвращает компаратор, который задаёт обратный порядок этого компаратора.

Возвращает:

компаратор, который задаёт обратный порядок этого компаратора.

С:

1.8

thenComparing

default Comparator<T> thenComparing(Comparator<? super T> other)

Примечание API:

Например, чтобы отсортировать коллекцию String по длине, а затем по естественному порядку без учёта регистра, компаратор можно составить, используя следующий код:

Comparator<String> cmp = Comparator.comparingInt(String::length)
             .thenComparing(String.CASE_INSENSITIVE_ORDER);

Параметры:

other - другой компаратор, используемый, когда этот компаратор считает два объекта равными.

Возвращает:

компаратор лексикографического порядка, составленный из этого и другого компаратора

Исключения:

NullPointerException - если аргумент равен null.

С:

1.8

thenComparing

default <U> Comparator<T> thenComparing(Function<? super T,? extends U> keyExtractor,
                                        Comparator<? super U> keyComparator)

Возвращает компаратор лексикографического порядка с функцией, которая извлекает ключ для сравнения с заданным Comparator.

Требования к реализации:

Эта реализация по умолчанию работает так, как если бы thenComparing(comparing(keyExtractor, cmp)).

Параметры типа:

U - тип ключа сортировки

Параметры:

keyExtractor - функция, используемая для извлечения ключа сортировки

keyComparator - Comparator для сравнения ключа сортировки

Возвращает:

компаратор лексикографического порядка, составленный из этого компаратора и компаратора, сравнивающего ключ, извлечённый функцией keyExtractor

Исключения:

NullPointerException - если любой из аргументов равен null.

С:

1.8

См. также:

comparing(Function, Comparator), thenComparing(Comparator)

thenComparing

default <U extends Comparable<? super U>> Comparator<T> thenComparing(Function<? super T,? extends U> keyExtractor)

Возвращает компаратор лексикографического порядка с функцией, которая извлекает Comparable ключ сортировки.

Требования к реализации:

Эта реализация по умолчанию работает так, как если бы thenComparing(comparing(keyExtractor)).

Параметры типа:

U - тип ключа сортировки Comparable

Параметры:

keyExtractor - функция, используемая для извлечения ключа сортировки Comparable

Возвращает:

компаратор лексикографического порядка, составленный из этого и компаратора ключа сортировки Comparable.

Исключения:

NullPointerException - если аргумент равен null.

С:

1.8

См. также:

comparing(Function), thenComparing(Comparator)

thenComparingInt

default Comparator<T> thenComparingInt(ToIntFunction<? super T> keyExtractor)

Возвращает компаратор лексикографического порядка с функцией, которая извлекает int ключ сортировки.

Требования к реализации:

Эта реализация по умолчанию работает так, как если бы thenComparing(comparingInt(keyExtractor)).

Параметры:

keyExtractor - функция, используемая для извлечения целочисленного ключа сортировки

Возвращает:

компаратор лексикографического порядка, составленный из этого и целочисленного ключа сортировки

Исключения:

NullPointerException - если аргумент равен null.

С:

1.8

См. также:

comparingInt(ToIntFunction), thenComparing(Comparator)

thenComparingLong

default Comparator<T> thenComparingLong(ToLongFunction<? super T> keyExtractor)

Возвращает компаратор лексикографического порядка с функцией, которая извлекает long ключ сортировки.

Требования к реализации:

Эта реализация по умолчанию работает так, как если бы thenComparing(comparingLong(keyExtractor)).

Параметры:

keyExtractor - функция, используемая для извлечения длинного ключа сортировки

Возвращает:

компаратор лексикографического порядка, составленный из этого и длинного ключа сортировки

Исключения:

NullPointerException - если аргумент равен null.

С:

1.8

См. также:

comparingLong(ToLongFunction), thenComparing(Comparator)

thenComparingDouble

default Comparator<T> thenComparingDouble(ToDoubleFunction<? super T> keyExtractor)

Возвращает компаратор лексикографического порядка с функцией, которая извлекает double ключ сортировки.

Требования к реализации:

Эта реализация по умолчанию работает так, как если бы thenComparing(comparingDouble(keyExtractor)).

Параметры:

keyExtractor - функция, используемая для извлечения вещественного ключа сортировки

Возвращает:

компаратор лексикографического порядка, составленный из этого и вещественного ключа сортировки

Исключения:

NullPointerException - если аргумент равен null.

С:

1.8

См. также:

comparingDouble(ToDoubleFunction), thenComparing(Comparator)

reverseOrder

static <T extends Comparable<? super T>> Comparator<T> reverseOrder()

Параметры типа:

T - тип элемента Comparable для сравнения

Возвращает:

компаратор, задающий обратный порядок естественного упорядочения для объектов Comparable.

С:

1.8

См. также:

Comparable

naturalOrder

static <T extends Comparable<? super T>> Comparator<T> naturalOrder()

Параметры типа:

T - тип элемента Comparable для сравнения

Возвращает:

компаратор, задающий естественный порядок для объектов Comparable.

С:

1.8

См. также:

Comparable

nullsFirst

static <T> Comparator<T> nullsFirst(Comparator<? super T> comparator)

Параметры типа:

T - тип элементов, которые будут сравниваться

Параметры:

comparator - компаратор для сравнения ненулевых значений

Возвращает:

компаратор, который считает null меньшим, чем ненулевое значение, и сравнивает ненулевые объекты с помощью указанного Comparator.

С:

1.8

nullsLast

static <T> Comparator<T> nullsLast(Comparator<? super T> comparator)

Параметры типа:

T - тип элементов, которые будут сравниваться

Параметры:

comparator - компаратор для сравнения ненулевых значений

Возвращает:

компаратор, который считает null большим, чем ненулевое значение, и сравнивает ненулевые объекты с помощью указанного Comparator.

С:

1.8

comparing

static <T,U> Comparator<T> comparing(Function<? super T,? extends U> keyExtractor,
                                     Comparator<? super U> keyComparator)

Примечание API:

Например, чтобы получить компаратор, который сравнивает объекты Person по фамилии, игнорируя различия в регистре,

Comparator<Person> cmp = Comparator.comparing(
             Person::getLastName,
             String.CASE_INSENSITIVE_ORDER);

Параметры типа:

T - тип элемента, который будет сравниваться

U - тип ключа сортировки

Параметры:

keyExtractor - функция, используемая для извлечения ключа сортировки

keyComparator - компаратор, используемый для сравнения ключа сортировки

Возвращает:

компаратор, который сравнивает по извлеченному ключу с использованием указанного Comparator

Исключения:

NullPointerException - если любой из аргументов null

С:

1.8

comparing

static <T,U extends Comparable<? super U>> Comparator<T> comparing(Function<? super T,? extends U> keyExtractor)

Примечание API:

Например, чтобы получить компаратор, который сравнивает объекты Person по фамилии,

Comparator<Person> byLastName = Comparator.comparing(Person::getLastName);

Параметры типа:

T - тип элемента, который будет сравниваться

U - тип ключа сортировки

Параметры:

keyExtractor - функция, используемая для извлечения ключа сортировки Comparable

Возвращает:

компаратор, который сравнивает по извлеченному ключу

Исключения:

NullPointerException - если аргумент null

С:

1.8

comparingInt

static <T> Comparator<T> comparingInt(ToIntFunction<? super T> keyExtractor)

Параметры типа:

T - тип элемента, который будет сравниваться

Параметры:

keyExtractor - функция, используемая для извлечения целого ключа сортировки

Возвращает:

компаратор, который сравнивает по извлеченному ключу

Исключения:

NullPointerException - если аргумент null

С:

1.8

См. также:

comparing(Function)

comparingLong

static <T> Comparator<T> comparingLong(ToLongFunction<? super T> keyExtractor)

Параметры типа:

T - тип элемента, который будет сравниваться

Параметры:

keyExtractor - функция, используемая для извлечения ключа сортировки типа long

Возвращает:

компаратор, который сравнивает по извлеченному ключу

Исключения:

NullPointerException - если аргумент null

С:

1.8

См. также:

comparing(Function)

comparingDouble

static <T> Comparator<T> comparingDouble(ToDoubleFunction<? super T> keyExtractor)

Параметры типа:

T - тип элемента, который будет сравниваться

Параметры:

keyExtractor - функция, используемая для извлечения ключа сортировки типа double

Возвращает:

компаратор, который сравнивает по извлеченному ключу

Исключения:

NullPointerException - если аргумент null

С:

1.8

См. также:

comparing(Function)