モジュール java.base
パッケージ java.util

インタフェースComparator<T>

型パラメータ:
T - このコンパレータにより比較されるオブジェクトの型
既知のすべての実装クラス:
Collator, RuleBasedCollator
関数型インタフェース:
これは関数型インタフェースなので、ラムダ式またはメソッド参照の代入先として使用できます。
@FunctionalInterface
public interface Comparator<T>
オブジェクトのコレクションで全体順序付けを行う比較関数です。 コンパレータ(Comparator)をソート・メソッド(Collections.sortやArrays.sortなど)に渡すと、ソート順を正確に制御できます。 また、コンパレータを使用すると、sorted sets (ソート・セット)やsorted maps (ソート・マップ)などの特定のデータ構造の順序を制御したり、natural ordering (自然順序付け)を持たないオブジェクトのコレクションに順序付けを提供したりすることもできます。

コンパレータcが要素のセットSで行う順序付けは、Sのすべてのe1およびe2についてc.compare(e1, e2)==0がe1.equals(e2)と同じboolean値を持つ場合にだけequalsとの一貫性があることになります。

ソート・セット(またはソート・マップ)を順序付けするために、equalsと一貫性のない順序付けを行うことができるコンパレータを使う場合には注意が必要です。 明示的なコンパレータcを持つソート・セット(またはソート・マップ)がセットSからの要素(またはキー)と一緒に使われると仮定します。 cによってSに課される順序付けがequalsと一貫性がない場合、ソート・セット(またはソート・マップ)の動作は異常になります。 特に、ソート・セット(またはソート・マップ)は、equalsで定義されているセット(またはマップ)の一般規約に違反します。

たとえば、(a.equals(b)&& c.compare(a, b)!= 0)である2つの要素aおよびbをコンパレータcで空のTreeSetに追加すると仮定します。 aとbはツリー・セットの点から見て等価ではないため、2番目のaddオペレーションは、Set.addメソッドの仕様とは異なる場合でも、trueを返し、ツリー・セットのサイズは大きくなります。

注:通常は、コンパレータで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とは異なり、コンパレータは等価関係の要件を保ちつつ、null引数の比較をオプションで許可できます。

このインタフェースは、Java Collections Frameworkのメンバーです。

導入されたバージョン:
1.2
関連項目:
Comparable, Serializable

  • メソッドのサマリー

    修飾子と型 メソッド 説明
    int compare​(T o1, T o2)
    順序付けのために2つの引数を比較します。
    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を使ってそのソート・キーで比較するComparator<T>を返します。
    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)
    ほかのオブジェクトがこのコンパレータと「等しい」かどうかを示します。
    static <T extends Comparable<? super T>>
    Comparator<T>    		 naturalOrder()
    Comparableオブジェクトを自然順序で比較するコンパレータを返します。
    static <T> Comparator<T> nullsFirst​(Comparator<? super T> comparator)
    nullをnull以外より小さいとみなす、nullフレンドリのコンパレータを返します。
    static <T> Comparator<T> nullsLast​(Comparator<? super T> comparator)
    nullを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)
      順序付けのために2つの引数を比較します。 最初の引数が2番目の引数より小さい場合は負の整数、両方が等しい場合は0、最初の引数が2番目の引数より大きい場合は正の整数を返します。

      実装では、すべてのxとyに対してsgn(compare(x, y))== -sgn(compare(y, x))が保証されなければいけません。 これは、compare(y, x)が例外をスローする場合にだけcompare(x, y)が例外をスローすることを意味します。

      実装では、順序関係が推移的であることも保証されなければいけません。((compare(x, y)>0)&& (compare(y, z)>0))はcompare(x, z)>0を意味します。

      最後に、実装者は、compare(x, y)==0がすべてのzでsgn(compare(x, z))==sgn(compare(y, z))を意味するようにしなければいけません。

      (compare(x, y)==0)==(x.equals(y))は厳密には要求されません。 通常は、この条件に違反するコンパレータではこの事実が明確に示される必要があります。 「注:このコンパレータはequalsと一貫性のない順序付けを課します。」のように示してください。

      前述の説明において、sgn( expression )は、expressionの値がそれぞれ負、ゼロ、または正であるかどうかに従って、-1、0、または1のうちの1つを返すように定義された数学的signum関数を指定します。

      パラメータ:
      o1 - 比較対象の最初のオブジェクト。
      o2 - 比較対象の2番目のオブジェクト。
      戻り値:
      最初の引数が2番目の引数より小さい場合は負の整数、両方が等しい場合は0、最初の引数が2番目の引数より大きい場合は正の整数。
      例外:
      NullPointerException - 引数がnullで、このコンパレータがnull引数を許可しない場合
      ClassCastException - 引数の型がこのコンパレータによる比較を妨げる場合。

    • equals

      boolean equals​(Object obj)
      ほかのオブジェクトがこのコンパレータと「等しい」かどうかを示します。 このメソッドはObject.equals(Object)の一般規約に従う必要があります。 またこのメソッドは、指定されたオブジェクトもコンパレータであり、それがこのコンパレータと同じ順序付けを行う場合にだけ trueを返すことができます。 したがって、comp1.equals(comp2)はすべてのオブジェクト参照o1およびo2でsgn(comp1.compare(o1, o2))==sgn(comp2.compare(o1, o2))を意味します。

      通常、Object.equals(Object)はオーバーライドしないほうが安全です。 ただし、このメソッドを変更し、2つの個別のコンパレータが同じ順序付けを行うことをプログラムが判断できるようにすることで、パフォーマンスが向上する場合があります。

      オーバーライド:
      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)
      辞書式順序コンパレータをもう一方のコンパレータとともに返します。 このComparatorで2つの要素が等しい(つまり、compare(a, b) == 0)と見なされる場合は、otherを使ってその順序が決められます。

      指定されたコンパレータが直列化可能の場合、返されるコンパレータも直列化可能になります。

      APIの注:
      たとえば、Stringのコレクションをまず長さに基づいてソートし、次に大文字と小文字を区別しない自然順序付けに基づいてソートするには、次のコードを使用してコンパレータを構成できます。 
      
     Comparator<String> cmp = Comparator.comparingInt(String::length)
             .thenComparing(String.CASE_INSENSITIVE_ORDER);
      パラメータ:
      other - このコンパレータが等しい2つのオブジェクトを比較するときに使用されるもう一方のコンパレータ。
      戻り値:
      このコンパレータと、その後のもう一方のコンパレータで構成される辞書式順序コンパレータ
      例外:
      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 - 整数のソート・キーの抽出に使用される関数
      戻り値:
      このコンパレータと、その後のintソート・キーで構成される辞書式順序コンパレータ
      例外:
      NullPointerException - 引数がnullである場合。
      導入されたバージョン:
      1.8
      関連項目:
      comparingInt(ToIntFunction), thenComparing(Comparator)

    • thenComparingLong

      default Comparator<T> thenComparingLong​(ToLongFunction<? super T> keyExtractor)
      longソート・キーを抽出する関数を含む辞書式順序コンパレータを返します。
      実装要件:
      このデフォルトの実装は、 thenComparing(comparingLong(keyExtractor))であるかのように動作します。
      パラメータ:
      keyExtractor - longのソート・キーの抽出に使用される関数
      戻り値:
      このコンパレータと、その後のlongソート・キーで構成される辞書式順序コンパレータ
      例外:
      NullPointerException - 引数がnullである場合。
      導入されたバージョン:
      1.8
      関連項目:
      comparingLong(ToLongFunction), thenComparing(Comparator)

    • thenComparingDouble

      default Comparator<T> thenComparingDouble​(ToDoubleFunction<? super T> keyExtractor)
      doubleソート・キーを抽出する関数を含む辞書式順序コンパレータを返します。
      実装要件:
      このデフォルトの実装は、 thenComparing(comparingDouble(keyExtractor))であるかのように動作します。
      パラメータ:
      keyExtractor - doubleのソート・キーの抽出に使用される関数
      戻り値:
      このコンパレータと、その後のdoubleソート・キーで構成される辞書式順序コンパレータ
      例外:
      NullPointerException - 引数がnullである場合。
      導入されたバージョン:
      1.8
      関連項目:
      comparingDouble(ToDoubleFunction), thenComparing(Comparator)

    • reverseOrder

      static <T extends Comparable<? super T>> Comparator<T> reverseOrder()
      自然順序付けの逆を義務付けるコンパレータを返します。

      返されるコンパレータは直列化可能であり、nullを比較した場合にNullPointerExceptionをスローします。

      型パラメータ:
      T - 比較対象の要素のComparable型
      戻り値:
      Comparableオブジェクトに自然順序付けの逆を義務付けるコンパレータ。
      導入されたバージョン:
      1.8
      関連項目:
      Comparable

    • naturalOrder

      static <T extends Comparable<? super T>> Comparator<T> naturalOrder()
      Comparableオブジェクトを自然順序で比較するコンパレータを返します。

      返されるコンパレータは直列化可能であり、nullを比較した場合にNullPointerExceptionをスローします。

      型パラメータ:
      T - 比較対象の要素のComparable型
      戻り値:
      Comparableオブジェクトに自然順序付けを義務付けるコンパレータ。
      導入されたバージョン:
      1.8
      関連項目:
      Comparable

    • nullsFirst

      static <T> Comparator<T> nullsFirst​(Comparator<? super T> comparator)
      nullをnull以外より小さいとみなす、nullフレンドリのコンパレータを返します。 両方ともnullである場合、それらは等しいと見なされます。 両方ともnull以外である場合、指定されたComparatorを使ってその順序が決められます。 指定されたコンパレータがnullである場合、返されるコンパレータはnull以外のすべての値が等しいと見なします。

      指定されたコンパレータが直列化可能の場合、返されるコンパレータも直列化可能になります。

      型パラメータ:
      T - 比較対象の要素の型
      パラメータ:
      comparator - null以外の値を比較するためのComparator
      戻り値:
      nullをnull以外よりも小さいと見なし、指定されたComparatorを使ってnull以外のオブジェクトを比較します。
      導入されたバージョン:
      1.8

    • nullsLast

      static <T> Comparator<T> nullsLast​(Comparator<? super T> comparator)
      nullをnull以外より大きいとみなす、nullフレンドリのコンパレータを返します。 両方ともnullである場合、それらは等しいと見なされます。 両方ともnull以外である場合、指定されたComparatorを使ってその順序が決められます。 指定されたコンパレータがnullである場合、返されるコンパレータはnull以外のすべての値が等しいと見なします。

      指定されたコンパレータが直列化可能の場合、返されるコンパレータも直列化可能になります。

      型パラメータ:
      T - 比較対象の要素の型
      パラメータ:
      comparator - null以外の値を比較するためのComparator
      戻り値:
      nullをnull以外よりも大きいと見なし、指定されたComparatorを使ってnull以外のオブジェクトを比較します。
      導入されたバージョン:
      1.8

    • comparing

      static <T,​ U> Comparator<T> comparing​(Function<? super T,​? extends U> keyExtractor, Comparator<? super U> keyComparator)
      型Tからソート・キーを抽出する関数を受け取り、指定されたComparatorを使ってそのソート・キーで比較するComparator<T>を返します。

      指定された関数とコンパレータの両方が直列化可能の場合、返されるコンパレータも直列化可能になります。

      APIの注:
      たとえば、 Personオブジェクトをその姓(大文字小文字の区別を無視して)で比較するComparatorを取得するには、 
      
     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)
      型TからComparableソート・キーを抽出する関数を受け取り、そのソート・キーで比較する Comparator<T>を返します。

      指定された関数が直列化可能の場合、返されるコンパレータも直列化可能になります。

      APIの注:
      たとえば、 Personオブジェクトをその姓で比較するComparatorを取得するには、 
      
     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)
      型Tからintソート・キーを抽出する関数を受け取り、そのソート・キーで比較するComparator<T>を返します。

      指定された関数が直列化可能の場合、返されるコンパレータも直列化可能になります。

      型パラメータ:
      T - 比較対象の要素の型
      パラメータ:
      keyExtractor - 整数のソート・キーの抽出に使用される関数
      戻り値:
      抽出されたキーで比較を行うコンパレータ
      例外:
      NullPointerException - 引数がnullの場合
      導入されたバージョン:
      1.8
      関連項目:
      comparing(Function)

    • comparingLong

      static <T> Comparator<T> comparingLong​(ToLongFunction<? super T> keyExtractor)
      型Tからlongソート・キーを抽出する関数を受け取り、そのソート・キーで比較するComparator<T>を返します。

      指定された関数が直列化可能の場合、返されるコンパレータも直列化可能になります。

      型パラメータ:
      T - 比較対象の要素の型
      パラメータ:
      keyExtractor - longのソート・キーの抽出に使用される関数
      戻り値:
      抽出されたキーで比較を行うコンパレータ
      例外:
      NullPointerException - 引数がnullの場合
      導入されたバージョン:
      1.8
      関連項目:
      comparing(Function)

    • comparingDouble

      static <T> Comparator<T> comparingDouble​(ToDoubleFunction<? super T> keyExtractor)
      型Tからdoubleソート・キーを抽出する関数を受け取り、そのソート・キーで比較するComparator<T>を返します。

      指定された関数が直列化可能の場合、返されるコンパレータも直列化可能になります。

      型パラメータ:
      T - 比較対象の要素の型
      パラメータ:
      keyExtractor - doubleのソート・キーの抽出に使用される関数
      戻り値:
      抽出されたキーで比較を行うコンパレータ
      例外:
      NullPointerException - 引数がnullの場合
      導入されたバージョン:
      1.8
      関連項目:
      comparing(Function)