Add a note about SequencedCollection.getFirst() / getLast() to `I…

…terables.getFirst()` / `getLast()`. RELNOTES=n/a PiperOrigin-RevId: 733371274
scope-demo · Mar 4, 2025 · 8a9497c · 8a9497c
1 parent 5004483
commit 8a9497c
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 0 deletions.
diff --git a/android/guava/src/com/google/common/collect/Iterables.java b/android/guava/src/com/google/common/collect/Iterables.java
@@ -823,6 +823,11 @@ public Iterator<T> iterator() {
    *
    * <p><b>{@code Stream} equivalent:</b> {@code stream.findFirst().orElse(defaultValue)}
    *
+   * <p><b>Java 21+ users:</b> if {code iterable} is a {@code SequencedCollection} (e.g., any list),
+   * consider using {@code collection.getFirst()} instead. Note that if the collection is empty,
+   * {@code getFirst()} throws a {@code NoSuchElementException}, while this method returns the
+   * default value.
+   *
    * @param defaultValue the default value to return if the iterable is empty
    * @return the first element of {@code iterable} or the default value
    * @since 7.0
@@ -839,6 +844,9 @@ public Iterator<T> iterator() {
    *
    * <p><b>{@code Stream} equivalent:</b> {@link Streams#findLast Streams.findLast(stream).get()}
    *
+   * <p><b>Java 21+ users:</b> if {code iterable} is a {@code SequencedCollection} (e.g., any list),
+   * consider using {@code collection.getLast()} instead.
+   *
    * @return the last element of {@code iterable}
    * @throws NoSuchElementException if the iterable is empty
    */
@@ -863,6 +871,11 @@ public Iterator<T> iterator() {
    *
    * <p><b>{@code Stream} equivalent:</b> {@code Streams.findLast(stream).orElse(defaultValue)}
    *
+   * <p><b>Java 21+ users:</b> if {code iterable} is a {@code SequencedCollection} (e.g., any list),
+   * consider using {@code collection.getLast()} instead. Note that if the collection is empty,
+   * {@code getLast()} throws a {@code NoSuchElementException}, while this method returns the
+   * default value.
+   *
    * @param defaultValue the value to return if {@code iterable} is empty
    * @return the last element of {@code iterable} or the default value
    * @since 3.0

diff --git a/guava/src/com/google/common/collect/Iterables.java b/guava/src/com/google/common/collect/Iterables.java
@@ -813,6 +813,11 @@ public Spliterator<T> spliterator() {
    *
    * <p><b>{@code Stream} equivalent:</b> {@code stream.findFirst().orElse(defaultValue)}
    *
+   * <p><b>Java 21+ users:</b> if {code iterable} is a {@code SequencedCollection} (e.g., any list),
+   * consider using {@code collection.getFirst()} instead. Note that if the collection is empty,
+   * {@code getFirst()} throws a {@code NoSuchElementException}, while this method returns the
+   * default value.
+   *
    * @param defaultValue the default value to return if the iterable is empty
    * @return the first element of {@code iterable} or the default value
    * @since 7.0
@@ -829,6 +834,9 @@ public Spliterator<T> spliterator() {
    *
    * <p><b>{@code Stream} equivalent:</b> {@link Streams#findLast Streams.findLast(stream).get()}
    *
+   * <p><b>Java 21+ users:</b> if {code iterable} is a {@code SequencedCollection} (e.g., any list),
+   * consider using {@code collection.getLast()} instead.
+   *
    * @return the last element of {@code iterable}
    * @throws NoSuchElementException if the iterable is empty
    */
@@ -853,6 +861,11 @@ public Spliterator<T> spliterator() {
    *
    * <p><b>{@code Stream} equivalent:</b> {@code Streams.findLast(stream).orElse(defaultValue)}
    *
+   * <p><b>Java 21+ users:</b> if {code iterable} is a {@code SequencedCollection} (e.g., any list),
+   * consider using {@code collection.getLast()} instead. Note that if the collection is empty,
+   * {@code getLast()} throws a {@code NoSuchElementException}, while this method returns the
+   * default value.
+   *
    * @param defaultValue the value to return if {@code iterable} is empty
    * @return the last element of {@code iterable} or the default value
    * @since 3.0