Skip to content

Document requireNonNullElseGet in firstNonNull Javadoc. #8199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
copybara-service merged 1 commit into from
Feb 5, 2026
+44 −40
Merged

Document requireNonNullElseGet in firstNonNull Javadoc. #8199

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 22 additions & 20 deletions android/guava/src/com/google/common/base/MoreObjects.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,12 @@
import java.util.Arrays;
import java.util.Collection;
import java.util.Map;
import java.util.Objects;
import org.jspecify.annotations.Nullable;

/**
* Helper functions that operate on any {@code Object}, and are not already provided in {@link
* java.util.Objects}.
* Objects}.
*
* <p>See the Guava User Guide on <a
* href="https://github.com/google/guava/wiki/CommonObjectUtilitiesExplained">writing {@code Object}
Expand All @@ -50,12 +51,13 @@ public final class MoreObjects {
* lazy evaluation of the fallback instance, using {@link Optional#or(Supplier)
* first.or(supplier)}.
*
* <p><b>Java 9 users:</b> use {@code java.util.Objects.requireNonNullElse(first, second)}
* instead.
* <p><b>Java 9 users:</b> use {@link Objects#requireNonNullElse} instead. For lazy evaluation of
* the fallback, use {@link Objects#requireNonNullElseGet Objects.requireNonNullElseGet(first, ()
* -> second)}}.
*
* @return {@code first} if it is non-null; otherwise {@code second} if it is non-null
* @throws NullPointerException if both {@code first} and {@code second} are null
* @since 18.0 (since 3.0 as {@code Objects.firstNonNull()}).
* @since 18.0 (since 3.0 as {@code Objects.firstNonNull}).
*/
public static <T> T firstNonNull(@Nullable T first, @Nullable T second) {
if (first != null) {
Expand Down Expand Up @@ -105,7 +107,7 @@ public static <T> T firstNonNull(@Nullable T first, @Nullable T second) {
*
* @param self the object to generate the string for (typically {@code this}), used only for its
* class name
* @since 18.0 (since 2.0 as {@code Objects.toStringHelper()}).
* @since 18.0 (since 2.0 as {@code Objects.toStringHelper}).
*/
public static ToStringHelper toStringHelper(Object self) {
return new ToStringHelper(self.getClass().getSimpleName());
Expand All @@ -119,7 +121,7 @@ public static ToStringHelper toStringHelper(Object self) {
* <p>Note that in GWT, class names are often obfuscated.
*
* @param clazz the {@link Class} of the instance
* @since 18.0 (since 7.0 as {@code Objects.toStringHelper()}).
* @since 18.0 (since 7.0 as {@code Objects.toStringHelper}).
*/
public static ToStringHelper toStringHelper(Class<?> clazz) {
return new ToStringHelper(clazz.getSimpleName());
Expand All @@ -131,7 +133,7 @@ public static ToStringHelper toStringHelper(Class<?> clazz) {
* Object#getClass()}.
*
* @param className the name of the instance type
* @since 18.0 (since 7.0 as {@code Objects.toStringHelper()}).
* @since 18.0 (since 7.0 as {@code Objects.toStringHelper}).
*/
public static ToStringHelper toStringHelper(String className) {
return new ToStringHelper(className);
Expand Down Expand Up @@ -160,7 +162,7 @@ private ToStringHelper(String className) {
* value. The order of calling this method, relative to the {@code add()}/{@code addValue()}
* methods, is not significant.
*
* @since 18.0 (since 12.0 as {@code Objects.ToStringHelper.omitNullValues()}).
* @since 18.0 (since 12.0 as {@code Objects.ToStringHelper.omitNullValues}).
*/
@CanIgnoreReturnValue
public ToStringHelper omitNullValues() {
Expand Down Expand Up @@ -199,7 +201,7 @@ public ToStringHelper add(String name, @Nullable Object value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, boolean value) {
Expand All @@ -209,7 +211,7 @@ public ToStringHelper add(String name, boolean value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, char value) {
Expand All @@ -219,7 +221,7 @@ public ToStringHelper add(String name, char value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, double value) {
Expand All @@ -229,7 +231,7 @@ public ToStringHelper add(String name, double value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, float value) {
Expand All @@ -239,7 +241,7 @@ public ToStringHelper add(String name, float value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, int value) {
Expand All @@ -249,7 +251,7 @@ public ToStringHelper add(String name, int value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, long value) {
Expand All @@ -273,7 +275,7 @@ public ToStringHelper addValue(@Nullable Object value) {
* <p>It is strongly encouraged to use {@link #add(String, boolean)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(boolean value) {
Expand All @@ -286,7 +288,7 @@ public ToStringHelper addValue(boolean value) {
* <p>It is strongly encouraged to use {@link #add(String, char)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(char value) {
Expand All @@ -299,7 +301,7 @@ public ToStringHelper addValue(char value) {
* <p>It is strongly encouraged to use {@link #add(String, double)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(double value) {
Expand All @@ -312,7 +314,7 @@ public ToStringHelper addValue(double value) {
* <p>It is strongly encouraged to use {@link #add(String, float)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(float value) {
Expand All @@ -325,7 +327,7 @@ public ToStringHelper addValue(float value) {
* <p>It is strongly encouraged to use {@link #add(String, int)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(int value) {
Expand All @@ -338,7 +340,7 @@ public ToStringHelper addValue(int value) {
* <p>It is strongly encouraged to use {@link #add(String, long)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(long value) {
Expand Down
42 changes: 22 additions & 20 deletions guava/src/com/google/common/base/MoreObjects.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,15 @@
import java.util.Arrays;
import java.util.Collection;
import java.util.Map;
import java.util.Objects;
import java.util.OptionalDouble;
import java.util.OptionalInt;
import java.util.OptionalLong;
import org.jspecify.annotations.Nullable;

/**
* Helper functions that operate on any {@code Object}, and are not already provided in {@link
* java.util.Objects}.
* Objects}.
*
* <p>See the Guava User Guide on <a
* href="https://github.com/google/guava/wiki/CommonObjectUtilitiesExplained">writing {@code Object}
Expand All @@ -53,12 +54,13 @@ public final class MoreObjects {
* lazy evaluation of the fallback instance, using {@link Optional#or(Supplier)
* first.or(supplier)}.
*
* <p><b>Java 9 users:</b> use {@code java.util.Objects.requireNonNullElse(first, second)}
* instead.
* <p><b>Java 9 users:</b> use {@link Objects#requireNonNullElse} instead. For lazy evaluation of
* the fallback, use {@link Objects#requireNonNullElseGet Objects.requireNonNullElseGet(first, ()
* -> second)}}.
*
* @return {@code first} if it is non-null; otherwise {@code second} if it is non-null
* @throws NullPointerException if both {@code first} and {@code second} are null
* @since 18.0 (since 3.0 as {@code Objects.firstNonNull()}).
* @since 18.0 (since 3.0 as {@code Objects.firstNonNull}).
*/
public static <T> T firstNonNull(@Nullable T first, @Nullable T second) {
if (first != null) {
Expand Down Expand Up @@ -108,7 +110,7 @@ public static <T> T firstNonNull(@Nullable T first, @Nullable T second) {
*
* @param self the object to generate the string for (typically {@code this}), used only for its
* class name
* @since 18.0 (since 2.0 as {@code Objects.toStringHelper()}).
* @since 18.0 (since 2.0 as {@code Objects.toStringHelper}).
*/
public static ToStringHelper toStringHelper(Object self) {
return new ToStringHelper(self.getClass().getSimpleName());
Expand All @@ -122,7 +124,7 @@ public static ToStringHelper toStringHelper(Object self) {
* <p>Note that in GWT, class names are often obfuscated.
*
* @param clazz the {@link Class} of the instance
* @since 18.0 (since 7.0 as {@code Objects.toStringHelper()}).
* @since 18.0 (since 7.0 as {@code Objects.toStringHelper}).
*/
public static ToStringHelper toStringHelper(Class<?> clazz) {
return new ToStringHelper(clazz.getSimpleName());
Expand All @@ -134,7 +136,7 @@ public static ToStringHelper toStringHelper(Class<?> clazz) {
* Object#getClass()}.
*
* @param className the name of the instance type
* @since 18.0 (since 7.0 as {@code Objects.toStringHelper()}).
* @since 18.0 (since 7.0 as {@code Objects.toStringHelper}).
*/
public static ToStringHelper toStringHelper(String className) {
return new ToStringHelper(className);
Expand Down Expand Up @@ -163,7 +165,7 @@ private ToStringHelper(String className) {
* value. The order of calling this method, relative to the {@code add()}/{@code addValue()}
* methods, is not significant.
*
* @since 18.0 (since 12.0 as {@code Objects.ToStringHelper.omitNullValues()}).
* @since 18.0 (since 12.0 as {@code Objects.ToStringHelper.omitNullValues}).
*/
@CanIgnoreReturnValue
public ToStringHelper omitNullValues() {
Expand Down Expand Up @@ -202,7 +204,7 @@ public ToStringHelper add(String name, @Nullable Object value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, boolean value) {
Expand All @@ -212,7 +214,7 @@ public ToStringHelper add(String name, boolean value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, char value) {
Expand All @@ -222,7 +224,7 @@ public ToStringHelper add(String name, char value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, double value) {
Expand All @@ -232,7 +234,7 @@ public ToStringHelper add(String name, double value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, float value) {
Expand All @@ -242,7 +244,7 @@ public ToStringHelper add(String name, float value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, int value) {
Expand All @@ -252,7 +254,7 @@ public ToStringHelper add(String name, int value) {
/**
* Adds a name/value pair to the formatted output in {@code name=value} format.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.add}).
*/
@CanIgnoreReturnValue
public ToStringHelper add(String name, long value) {
Expand All @@ -276,7 +278,7 @@ public ToStringHelper addValue(@Nullable Object value) {
* <p>It is strongly encouraged to use {@link #add(String, boolean)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(boolean value) {
Expand All @@ -289,7 +291,7 @@ public ToStringHelper addValue(boolean value) {
* <p>It is strongly encouraged to use {@link #add(String, char)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(char value) {
Expand All @@ -302,7 +304,7 @@ public ToStringHelper addValue(char value) {
* <p>It is strongly encouraged to use {@link #add(String, double)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(double value) {
Expand All @@ -315,7 +317,7 @@ public ToStringHelper addValue(double value) {
* <p>It is strongly encouraged to use {@link #add(String, float)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(float value) {
Expand All @@ -328,7 +330,7 @@ public ToStringHelper addValue(float value) {
* <p>It is strongly encouraged to use {@link #add(String, int)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(int value) {
Expand All @@ -341,7 +343,7 @@ public ToStringHelper addValue(int value) {
* <p>It is strongly encouraged to use {@link #add(String, long)} instead and give value a
* readable name.
*
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue()}).
* @since 18.0 (since 11.0 as {@code Objects.ToStringHelper.addValue}).
*/
@CanIgnoreReturnValue
public ToStringHelper addValue(long value) {
Expand Down
Loading