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

Параметры типа:: T — тип объектов, которые могут сравниваться этим компаратором

Все известные реализующие классы:: Collator, RuleBasedCollator

Функциональный интерфейс:: Это функциональный интерфейс, поэтому его можно использовать в качестве целевого типа для лямбда-выражения или ссылки на метод.

@FunctionalInterface public interface Comparator<T>

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

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

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

Например, предположим, что в пустой TreeSet с компаратором c добавляются два элемента a и b, такие что (a.equals(b) && c.compare(a, b) != 0). Вторая операция 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)}.

Иными словами, если задаваемый порядок согласован с equals, классы эквивалентности, определяемые отношением эквивалентности метода equals, совпадают с классами эквивалентности, определяемыми фактор-множеством метода compare.

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

Этот интерфейс входит в состав Java Collections Framework.

Начиная с версии:

1.2

См. также:

Краткое описание методов

Модификатор и тип	Метод	Описание
`int`	`compare(T o1, T o2)`	Сравнивает два аргумента по порядку.
`static <T, U extends Comparable<? super U>> Comparator<T>`	`comparing(Function<? super T, ? extends U> keyExtractor)`	Принимает функцию, извлекающую сортировочный ключ типа `T`, реализующий `Comparable`, и возвращает `Comparator<T>`, сравнивающий объекты по этому ключу.
`static <T,U> Comparator<T>`	`comparing(Function<? super T, ? extends U> keyExtractor, Comparator<? super U> keyComparator)`	Принимает функцию, извлекающую сортировочный ключ из типа `T`, и возвращает `Comparator<T>`, сравнивающий объекты по этому ключу с использованием указанного `Comparator`.
`static <T> Comparator<T>`	`comparingDouble(ToDoubleFunction<? super T> keyExtractor)`	Принимает функцию, извлекающую сортировочный ключ типа `T`, реализующий `double`, и возвращает `Comparator<T>`, сравнивающий объекты по этому ключу.
`static <T> Comparator<T>`	`comparingInt(ToIntFunction<? super T> keyExtractor)`	Принимает функцию, извлекающую сортировочный ключ типа `T`, реализующий `int`, и возвращает `Comparator<T>`, сравнивающий объекты по этому ключу.
`static <T> Comparator<T>`	`comparingLong(ToLongFunction<? super T> keyExtractor)`	Принимает функцию, извлекающую сортировочный ключ типа `T`, реализующий `long`, и возвращает `Comparator<T>`, сравнивающий объекты по этому ключу.
`boolean`	`equals(Object obj)`	Указывает, является ли другой объект «равным» этому компаратору.
`default <U extends T> U`	`max(U o1, U o2)`	Возвращает большее из двух значений согласно этому компаратору.
`default <U extends T> U`	`min(U o1, U o2)`	Возвращает меньшее из двух значений согласно этому компаратору.
`static <T extends Comparable<? super T>> Comparator<T>`	`naturalOrder()`	Возвращает компаратор, сравнивающий объекты `Comparable` в естественном порядке.
`static <T> Comparator<T>`	`nullsFirst(Comparator<? super T> comparator)`	Возвращает компаратор, допускающий null и считающий `null` меньшим, чем ненулевое значение.
`static <T> Comparator<T>`	`nullsLast(Comparator<? super T> comparator)`	Возвращает компаратор, допускающий null и считающий `null` большим, чем ненулевое значение.
`default Comparator<T>`	`reversed()`	Возвращает компаратор, задающий обратный порядок по отношению к этому компаратору.
`static <T extends Comparable<? super T>> Comparator<T>`	`reverseOrder()`	Возвращает компаратор, задающий порядок, обратный естественному порядку.
`default Comparator<T>`	`thenComparing(Comparator<? super T> other)`	Возвращает компаратор с лексикографическим порядком, использующий другой компаратор.
`default <U extends Comparable<? super U>> Comparator<T>`	`thenComparing(Function<? super T, ? extends U> keyExtractor)`	Возвращает компаратор с лексикографическим порядком и функцией, извлекающей сортировочный ключ типа `Comparable`.
`default <U> Comparator<T>`	`thenComparing(Function<? super T, ? extends U> keyExtractor, Comparator<? super U> keyComparator)`	Возвращает компаратор с лексикографическим порядком и функцией, извлекающей ключ для сравнения с заданным `Comparator`.
`default Comparator<T>`	`thenComparingDouble(ToDoubleFunction<? super T> keyExtractor)`	Возвращает компаратор с лексикографическим порядком и функцией, извлекающей сортировочный ключ типа `double`.
`default Comparator<T>`	`thenComparingInt(ToIntFunction<? super T> keyExtractor)`	Возвращает компаратор с лексикографическим порядком и функцией, извлекающей сортировочный ключ типа `int`.
`default Comparator<T>`	`thenComparingLong(ToLongFunction<? super T> keyExtractor)`	Возвращает компаратор с лексикографическим порядком и функцией, извлекающей сортировочный ключ типа `long`.

Подробное описание методов

compare

int compare(T o1, T o2)

Сравнивает два аргумента в заданном порядке. Возвращает отрицательное целое число, ноль или положительное целое число в зависимости от того, меньше ли первый аргумент второго, равен ему или больше него.

Реализатор должен обеспечить, чтобы signum(compare(x, y)) == -signum(compare(y, x)) для всех x и y. (Это подразумевает, что compare(x, y) должно выбрасывать исключение тогда и только тогда, когда исключение выбрасывает compare(y, x).)

Реализатор также должен обеспечить транзитивность отношения: ((compare(x, y)>0) && (compare(y, z)>0)) подразумевает compare(x, z)>0.

Наконец, реализатор должен обеспечить, чтобы compare(x, y)==0 подразумевало, что signum(compare(x, z))==signum(compare(y, z)) для всех z.

Примечание к API:: Обычно это верно, но строго не требуется, чтобы (compare(x, y)==0) == (x.equals(y)). Как правило, любой компаратор, нарушающий это условие, должен явно указывать на этот факт. Рекомендуемая формулировка: «Примечание: этот компаратор задает порядок, несовместимый с equals».
Параметры:: o1 — первый объект для сравнения.; o2 — второй объект для сравнения.
Возвращает:: отрицательное целое число, ноль или положительное целое число в зависимости от того, меньше ли первый аргумент второго, равен ему или больше него.
Выбрасывает:: NullPointerException — если аргумент равен null, а этот компаратор не допускает аргументы null; ClassCastException — если типы аргументов не позволяют сравнить их с помощью этого компаратора.

equals

boolean equals(Object obj)

Указывает, является ли какой-либо другой объект «равным» этому компаратору. Этот метод должен соблюдать общий контракт метода Object.equals(Object). Кроме того, этот метод может возвращать true только в том случае, если указанный объект также является компаратором и задает тот же порядок, что и этот компаратор. Таким образом, comp1.equals(comp2) подразумевает, что signum

(comp1.compare(o1,
o2))==signum(comp2.compare(o1, o2))

для каждой пары ссылок на объекты o1 и o2.

Обратите внимание, что всегда безопасно не переопределять Object.equals(Object). Однако переопределение этого метода в некоторых случаях может повысить производительность, позволяя программам определять, задают ли два различных компаратора одинаковый порядок.

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

equals в классе Object

Параметры:

obj — объект-ссылка, с которым выполняется сравнение.

Возвращает:

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

См. также:

reversed

default Comparator<T> reversed()

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

Возвращает:: компаратор, задающий порядок, обратный порядку этого компаратора.
Начиная с:: 1.8

max

default <U extends T> U max(U o1, U o2)

Возвращает большее из двух значений согласно этому компаратору. Если аргументы равны с точки зрения этого компаратора, возвращается аргумент o1.

Требования к реализации:: Эта реализация по умолчанию действует так, как если бы compare(o1, o2) >= 0 ? o1 : o2.
Параметры типа:: U — тип аргументов и результата.
Параметры:: o1 — аргумент.; o2 — другой аргумент.
Возвращает:: большее из o1 и o2 согласно этому компаратору.
Выбрасывает:: NullPointerException — если аргумент равен null, а этот компаратор не допускает аргументы null; ClassCastException — если типы аргументов не позволяют сравнить их с помощью этого компаратора.
Начиная с:: 26

min

default <U extends T> U min(U o1, U o2)

Возвращает меньшее из двух значений согласно этому компаратору. Если аргументы равны с точки зрения этого компаратора, возвращается аргумент o1.

Требования к реализации:: Эта реализация по умолчанию действует так, как если бы compare(o1, o2) <= 0 ? o1 : o2.
Параметры типа:: U — тип аргументов и результата.
Параметры:: o1 — аргумент.; o2 — другой аргумент.
Возвращает:: меньшее из o1 и o2 согласно этому компаратору.
Выбрасывает:: NullPointerException — если аргумент равен null, а этот компаратор не допускает аргументы null; ClassCastException — если типы аргументов не позволяют сравнить их с помощью этого компаратора.
Начиная с:: 26

thenComparing

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

Возвращает компаратор с лексикографическим порядком, использующий другой компаратор. Если этот Comparator считает два элемента равными, то есть compare(a, b) == 0, для определения порядка используется 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

См. также:

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

См. также:

thenComparingInt

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

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

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

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


          thenComparing(comparingInt(keyExtractor))

Параметры:

keyExtractor — функция для извлечения целочисленного ключа сортировки

Возвращает:

компаратор с лексикографическим порядком, объединяющий этот компаратор с последующим сравнением по ключу сортировки int

Выбрасывает:

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

Начиная с:

1.8

См. также:

thenComparingLong

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

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

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

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


          thenComparing(comparingLong(keyExtractor))

Параметры:

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

Возвращает:

компаратор с лексикографическим порядком, объединяющий этот компаратор с последующим сравнением по ключу сортировки long

Выбрасывает:

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

Начиная с:

1.8

См. также:

thenComparingDouble

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

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

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

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


          thenComparing(comparingDouble(keyExtractor))

Параметры:

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

Возвращает:

компаратор с лексикографическим порядком, объединяющий этот компаратор с последующим сравнением по ключу сортировки double

Выбрасывает:

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

Начиная с:

1.8

См. также:

reverseOrder

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

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

Возвращаемый компаратор сериализуем и выбрасывает NullPointerException при сравнении null.

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

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

Возвращает:

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

Начиная с:

1.8

См. также:

naturalOrder

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

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

Возвращаемый компаратор сериализуем и выбрасывает NullPointerException при сравнении null.

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

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

Возвращает:

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


        Comparable

Начиная с:

1.8

См. также:

nullsFirst

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

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

Возвращаемый компаратор сериализуем, если указанный компаратор также сериализуем.

Параметры типа:: T — тип сравниваемых элементов
Параметры:: comparator — Comparator для сравнения ненулевых значений
Возвращает:: компаратор, считающий null меньшим, чем ненулевые значения, и сравнивающий ненулевые объекты с помощью указанного Comparator.
Начиная с:: 1.8

nullsLast

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

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

Возвращаемый компаратор сериализуем, если указанный компаратор также сериализуем.

Параметры типа:: T — тип сравниваемых элементов
Параметры:: comparator — Comparator для сравнения ненулевых значений
Возвращает:: компаратор, считающий null большим, чем ненулевые значения, и сравнивающий ненулевые объекты с помощью указанного Comparator.
Начиная с:: 1.8

comparing

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

Принимает функцию, извлекающую ключ сортировки из типа T, и возвращает Comparator<T>, сравнивающий по этому ключу сортировки с помощью указанного Comparator.

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

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

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


Person

по фамилии без учета регистра,

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

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

T — тип сравниваемого элемента

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

Параметры:

keyExtractor — функция для извлечения ключа сортировки

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

Возвращает:

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

Выбрасывает:

NullPointerException — если один из аргументов равен null

Начиная с:

1.8

comparing

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

Принимает функцию, извлекающую ключ сортировки Comparable из типа T, и возвращает


Comparator<T>

, сравнивающий по этому ключу сортировки.

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

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

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


Person

по фамилии,

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

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

T — тип сравниваемого элемента

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

Параметры:

keyExtractor — функция для извлечения ключа сортировки Comparable

Возвращает:

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

Выбрасывает:

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

Начиная с:

1.8

comparingInt

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

Принимает функцию, извлекающую int ключ сортировки из типа T, и возвращает Comparator<T>, сравнивающий по этому ключу сортировки.

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

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

T — тип сравниваемого элемента

Параметры:

keyExtractor — функция для извлечения целочисленного ключа сортировки

Возвращает:

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

Выбрасывает:

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

Начиная с:

1.8

См. также:

comparingLong

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

Принимает функцию, извлекающую long ключ сортировки из типа T, и возвращает Comparator<T>, сравнивающий по этому ключу сортировки.

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

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

T — тип сравниваемого элемента

Параметры:

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

Возвращает:

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

Выбрасывает:

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

Начиная с:

1.8

См. также:

comparingDouble

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

Принимает функцию, извлекающую double ключ сортировки из типа T, и возвращает Comparator<T>, сравнивающий по этому ключу сортировки.

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

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

T — тип сравниваемого элемента

Параметры:

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

Возвращает:

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

Выбрасывает:

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

Начиная с:

1.8

См. также:

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.