From f47614d0da610e01a518ab702c8023c981487365 Mon Sep 17 00:00:00 2001
From: Suzanne Millstein <smillst@cs.washington.edu>
Date: Fri, 18 Sep 2026 10:28:14 -0700
Subject: [PATCH] Add purity annotations to Comparator.

---
 .../share/classes/java/util/Comparator.java      | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/src/java.base/share/classes/java/util/Comparator.java b/src/java.base/share/classes/java/util/Comparator.java
index 53c07a37638a..115b025326f7 100644
--- a/src/java.base/share/classes/java/util/Comparator.java
+++ b/src/java.base/share/classes/java/util/Comparator.java
@@ -161,6 +161,7 @@ public interface Comparator<T> {
      * @throws ClassCastException if the arguments' types prevent them from
      *         being compared by this comparator.
      */
+    @Pure
     int compare(T o1, T o2);
 
     /**
@@ -227,6 +228,7 @@ default Comparator<T> reversed() {
      * @throws NullPointerException if the argument is null.
      * @since 1.8
      */
+    @SideEffectFree
     default Comparator<T> thenComparing(Comparator<? super T> other) {
         Objects.requireNonNull(other);
         return (Comparator<T> & Serializable) (c1, c2) -> {
@@ -252,6 +254,7 @@ default Comparator<T> thenComparing(Comparator<? super T> other) {
      * @see #thenComparing(Comparator)
      * @since 1.8
      */
+    @SideEffectFree
     default <U> Comparator<T> thenComparing(
             Function<? super T, ? extends U> keyExtractor,
             Comparator<? super U> keyComparator)
@@ -276,6 +279,7 @@ default <U> Comparator<T> thenComparing(
      * @see #thenComparing(Comparator)
      * @since 1.8
      */
+    @SideEffectFree
     default <U extends Comparable<? super U>> Comparator<T> thenComparing(
             Function<? super T, ? extends U> keyExtractor)
     {
@@ -297,6 +301,7 @@ default <U extends Comparable<? super U>> Comparator<T> thenComparing(
      * @see #thenComparing(Comparator)
      * @since 1.8
      */
+    @SideEffectFree
     default Comparator<T> thenComparingInt(ToIntFunction<? super T> keyExtractor) {
         return thenComparing(comparingInt(keyExtractor));
     }
@@ -316,6 +321,7 @@ default Comparator<T> thenComparingInt(ToIntFunction<? super T> keyExtractor) {
      * @see #thenComparing(Comparator)
      * @since 1.8
      */
+    @SideEffectFree
     default Comparator<T> thenComparingLong(ToLongFunction<? super T> keyExtractor) {
         return thenComparing(comparingLong(keyExtractor));
     }
@@ -335,6 +341,7 @@ default Comparator<T> thenComparingLong(ToLongFunction<? super T> keyExtractor)
      * @see #thenComparing(Comparator)
      * @since 1.8
      */
+    @SideEffectFree
     default Comparator<T> thenComparingDouble(ToDoubleFunction<? super T> keyExtractor) {
         return thenComparing(comparingDouble(keyExtractor));
     }
@@ -352,6 +359,7 @@ default Comparator<T> thenComparingDouble(ToDoubleFunction<? super T> keyExtract
      * @see Comparable
      * @since 1.8
      */
+    @Pure
     public static <T extends Comparable<? super T>> Comparator<T> reverseOrder() {
         return Collections.reverseOrder();
     }
@@ -369,6 +377,7 @@ public static <T extends Comparable<? super T>> Comparator<T> reverseOrder() {
      * @see Comparable
      * @since 1.8
      */
+    @Pure
     @SuppressWarnings("unchecked")
     public static <T extends Comparable<@NonNull ? super @NonNull T>> Comparator<T> naturalOrder() {
         return (Comparator<T>) Comparators.NaturalOrderComparator.INSTANCE;
@@ -391,6 +400,7 @@ public static <T extends Comparable<? super T>> Comparator<T> reverseOrder() {
      *         {@code Comparator}.
      * @since 1.8
      */
+    @SideEffectFree
     public static <T> Comparator<@Nullable T> nullsFirst(@Nullable Comparator<? super T> comparator) {
         return new Comparators.NullComparator<>(true, comparator);
     }
@@ -412,6 +422,7 @@ public static <T extends Comparable<? super T>> Comparator<T> reverseOrder() {
      *         {@code Comparator}.
      * @since 1.8
      */
+    @SideEffectFree
     public static <T> Comparator<@Nullable T> nullsLast(@Nullable Comparator<? super T> comparator) {
         return new Comparators.NullComparator<>(false, comparator);
     }
@@ -443,6 +454,7 @@ public static <T extends Comparable<? super T>> Comparator<T> reverseOrder() {
      * @throws NullPointerException if either argument is null
      * @since 1.8
      */
+    @SideEffectFree
     public static <T, U> Comparator<T> comparing(
             Function<? super T, ? extends U> keyExtractor,
             Comparator<? super U> keyComparator)
@@ -478,6 +490,7 @@ public static <T, U> Comparator<T> comparing(
      * @throws NullPointerException if the argument is null
      * @since 1.8
      */
+    @SideEffectFree
     public static <T, U extends Comparable<? super U>> Comparator<T> comparing(
             Function<? super T, ? extends U> keyExtractor)
     {
@@ -501,6 +514,7 @@ public static <T, U extends Comparable<? super U>> Comparator<T> comparing(
      * @throws NullPointerException if the argument is null
      * @since 1.8
      */
+    @SideEffectFree
     public static <T> Comparator<T> comparingInt(ToIntFunction<? super T> keyExtractor) {
         Objects.requireNonNull(keyExtractor);
         return (Comparator<T> & Serializable)
@@ -522,6 +536,7 @@ public static <T> Comparator<T> comparingInt(ToIntFunction<? super T> keyExtract
      * @throws NullPointerException if the argument is null
      * @since 1.8
      */
+    @SideEffectFree
     public static <T> Comparator<T> comparingLong(ToLongFunction<? super T> keyExtractor) {
         Objects.requireNonNull(keyExtractor);
         return (Comparator<T> & Serializable)
@@ -543,6 +558,7 @@ public static <T> Comparator<T> comparingLong(ToLongFunction<? super T> keyExtra
      * @throws NullPointerException if the argument is null
      * @since 1.8
      */
+    @SideEffectFree
     public static<T> Comparator<T> comparingDouble(ToDoubleFunction<? super T> keyExtractor) {
         Objects.requireNonNull(keyExtractor);
         return (Comparator<T> & Serializable)