From c26c72f8a8ee9996bff2bf139eb42fc2c56e62d8 Mon Sep 17 00:00:00 2001
From: Gary Gregory <garydgregory@gmail.com>
Date: Tue, 23 Jun 2020 15:15:38 -0400
Subject: [PATCH] Add ObjectUtils.toString(Object, Supplier<String>).

---
 src/changes/changes.xml                       |  3 ++-
 .../org/apache/commons/lang3/ObjectUtils.java | 26 ++++++++++++++++++-
 .../apache/commons/lang3/ObjectUtilsTest.java |  9 +++++++
 3 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 03989d564..4694dcddb 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -79,7 +79,8 @@ The <action> type attribute can be add,update,fix,remove.
     <action issue="LANG-1556" type="add" dev="ggregory" due-to="XenoAmess">Use Java 8 lambdas and Map operations.</action>
     <action issue="LANG-1565" type="add" dev="ggregory" due-to="XenoAmess">Change removeLastFieldSeparator to use endsWith #550.</action>
     <action issue="LANG-1557" type="add" dev="ggregory" due-to="XenoAmess, Gary Gregory">Change a Pattern to a static final field, for not letting it compile each time the function invoked. #542.</action>
-    <action                   type="add" dev="ggregory">Added ImmutablePair factory methods left() and right().</action>
+    <action                   type="add" dev="ggregory">Add ImmutablePair factory methods left() and right().</action>
+    <action                   type="add" dev="ggregory">Add ObjectUtils.toString(Object, Supplier&lt;String&gt;).</action>
   </release>
 
   <release version="3.10" date="2020-03-22" description="New features and bug fixes. Requires Java 8, supports Java 9, 10, 11.">
diff --git a/src/main/java/org/apache/commons/lang3/ObjectUtils.java b/src/main/java/org/apache/commons/lang3/ObjectUtils.java
index f1e5fa2a9..95e886228 100644
--- a/src/main/java/org/apache/commons/lang3/ObjectUtils.java
+++ b/src/main/java/org/apache/commons/lang3/ObjectUtils.java
@@ -789,7 +789,7 @@ public class ObjectUtils {
         builder.append(name)
               .append(AT_SIGN)
               .append(hexString);
-        // @formatter:off
+        // @formatter:on
         return builder.toString();
     }
 
@@ -1182,6 +1182,30 @@ public class ObjectUtils {
         return obj == null ? nullStr : obj.toString();
     }
 
+    /**
+     * <p>Gets the {@code toString} of an {@code Object} returning
+     * a specified text if {@code null} input.</p>
+     *
+     * <pre>
+     * ObjectUtils.toString(obj, () -&gt; expensive())
+     * </pre>
+     * <pre>
+     * ObjectUtils.toString(null, () -&gt; expensive())         = result of expensive()
+     * ObjectUtils.toString(null, () -&gt; expensive())         = result of expensive()
+     * ObjectUtils.toString("", () -&gt; expensive())           = ""
+     * ObjectUtils.toString("bat", () -&gt; expensive())        = "bat"
+     * ObjectUtils.toString(Boolean.TRUE, () -&gt; expensive()) = "true"
+     * </pre>
+     *
+     * @param obj  the Object to {@code toString}, may be null
+     * @param supplier  the Supplier of String used on {@code null} input, may be null
+     * @return the passed in Object's toString, or {@code nullStr} if {@code null} input
+     * @since 3.11
+     */
+    public static String toString(final Object obj, final Supplier<String> supplier) {
+        return obj == null ? supplier == null ? null : supplier.get() : obj.toString();
+    }
+
     /**
      * <p>{@code ObjectUtils} instances should NOT be constructed in
      * standard programming. Instead, the static methods on the class should
diff --git a/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java b/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
index aab3a4e77..b1da3b69c 100644
--- a/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
+++ b/src/test/java/org/apache/commons/lang3/ObjectUtilsTest.java
@@ -361,6 +361,15 @@ public class ObjectUtilsTest {
         assertEquals(Boolean.TRUE.toString(), ObjectUtils.toString(Boolean.TRUE, BAR) );
     }
 
+    @Test
+    public void testToString_SupplierString() {
+        assertEquals(null, ObjectUtils.toString(null, (Supplier<String>) null));
+        assertEquals(null, ObjectUtils.toString(null, () -> null));
+        // Pretend computing BAR is expensive.
+        assertEquals(BAR, ObjectUtils.toString(null, () -> BAR));
+        assertEquals(Boolean.TRUE.toString(), ObjectUtils.toString(Boolean.TRUE, () -> BAR));
+    }
+
     @SuppressWarnings("cast") // 1 OK, because we are checking for code change
     @Test
     public void testNull() {