Mention stability in Iterables.mergeSorted() javadocs.

perceptron8 · Google Java Core Libraries · commit c1e6de293c8f · 2025-09-16T11:35:28.000-07:00
Fixes #7997 Relevant to #5773 Followup to #7989 / #7996 RELNOTES=n/a PiperOrigin-RevId: 807777880
diff --git a/android/guava/src/com/google/common/collect/Iterables.java b/android/guava/src/com/google/common/collect/Iterables.java
@@ -1061,8 +1061,9 @@ public static boolean isEmpty(Iterable<?> iterable) {
    * <p>Callers must ensure that the source {@code iterables} are in non-descending order as this
    * method does not sort its input.
    *
-   * <p>For any equivalent elements across all {@code iterables}, it is undefined which element is
-   * returned first.
+   * <p>For any equivalent elements across all {@code iterables}, elements are returned in the order
+   * of their source iterables. That is, if element A from iterable 1 and element B from iterable 2
+   * compare as equal, A will be returned before B if iterable 1 was passed before iterable 2.
    *
    * @since 11.0
    */
diff --git a/guava/src/com/google/common/collect/Iterables.java b/guava/src/com/google/common/collect/Iterables.java
@@ -1067,8 +1067,9 @@ public static boolean isEmpty(Iterable<?> iterable) {
    * <p>Callers must ensure that the source {@code iterables} are in non-descending order as this
    * method does not sort its input.
    *
-   * <p>For any equivalent elements across all {@code iterables}, it is undefined which element is
-   * returned first.
+   * <p>For any equivalent elements across all {@code iterables}, elements are returned in the order
+   * of their source iterables. That is, if element A from iterable 1 and element B from iterable 2
+   * compare as equal, A will be returned before B if iterable 1 was passed before iterable 2.
    *
    * @since 11.0
    */

Original file line number	Diff line number	Diff line change
`@@ -1061,8 +1061,9 @@ public static boolean isEmpty(Iterable<?> iterable) {`
`1061`	`1061`	`* <p>Callers must ensure that the source {@code iterables} are in non-descending order as this`
`1062`	`1062`	`* method does not sort its input.`
`1063`	`1063`	`*`
`1064`		`- * <p>For any equivalent elements across all {@code iterables}, it is undefined which element is`
`1065`		`- * returned first.`
	`1064`	`+ * <p>For any equivalent elements across all {@code iterables}, elements are returned in the order`
	`1065`	`+ * of their source iterables. That is, if element A from iterable 1 and element B from iterable 2`
	`1066`	`+ * compare as equal, A will be returned before B if iterable 1 was passed before iterable 2.`
`1066`	`1067`	`*`
`1067`	`1068`	`* @since 11.0`
`1068`	`1069`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -1067,8 +1067,9 @@ public static boolean isEmpty(Iterable<?> iterable) {`
`1067`	`1067`	`* <p>Callers must ensure that the source {@code iterables} are in non-descending order as this`
`1068`	`1068`	`* method does not sort its input.`
`1069`	`1069`	`*`
`1070`		`- * <p>For any equivalent elements across all {@code iterables}, it is undefined which element is`
`1071`		`- * returned first.`
	`1070`	`+ * <p>For any equivalent elements across all {@code iterables}, elements are returned in the order`
	`1071`	`+ * of their source iterables. That is, if element A from iterable 1 and element B from iterable 2`
	`1072`	`+ * compare as equal, A will be returned before B if iterable 1 was passed before iterable 2.`
`1072`	`1073`	`*`
`1073`	`1074`	`* @since 11.0`
`1074`	`1075`	`*/`