From ab8caff3a352fcf10563db44b85f7e8fb154e3a1 Mon Sep 17 00:00:00 2001
From: Gary Gregory <garydgregory@gmail.com>
Date: Sun, 31 Mar 2024 15:27:07 -0400
Subject: [PATCH] Add ArrayUtils.nullTo(T[], T[])

---
 src/changes/changes.xml                       |  1 +
 .../org/apache/commons/lang3/ArrayUtils.java  | 43 ++++++++++++++-----
 .../apache/commons/lang3/ArrayUtilsTest.java  |  6 +++
 3 files changed, 39 insertions(+), 11 deletions(-)

diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 321a755a8..667346dae 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -55,6 +55,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action issue="LANG-1702" type="add" dev="ggregory" due-to="Elliotte Rusty Harold">Add test in TypeUtilsTest #1151.</action>
     <action issue="LANG-1724" type="add" dev="ggregory" due-to="Gary Gregory">Add Streams.failableStream(T), non-varargs variant.</action>
     <action issue="LANG-1724" type="add" dev="ggregory" due-to="Gary Gregory">Add Streams.nonNull(T), non-varargs variant.</action>
+    <action issue="LANG-1724" type="add" dev="ggregory" due-to="Gary Gregory">Add ArrayUtils.nullTo(T[], T[]).</action>
     
     <!-- FIX -->
     <action                   type="fix" dev="ggregory" due-to="Miklós Karakó, Gary Gregory">Improve Javadoc in ExceptionUtils #1136.</action>
diff --git a/src/main/java/org/apache/commons/lang3/ArrayUtils.java b/src/main/java/org/apache/commons/lang3/ArrayUtils.java
index 88e690041..652b48acf 100644
--- a/src/main/java/org/apache/commons/lang3/ArrayUtils.java
+++ b/src/main/java/org/apache/commons/lang3/ArrayUtils.java
@@ -4284,6 +4284,27 @@ public class ArrayUtils {
         return (T[]) Array.newInstance(componentType, length);
     }
 
+    /**
+     * Defensive programming technique to change a {@code null}
+     * reference to an empty one.
+     * <p>
+     * This method returns a default array for a {@code null} input array.
+     * </p>
+     * <p>
+     * As a memory optimizing technique an empty array passed in will be overridden with
+     * the empty {@code public static} references in this class.
+     * </p>
+     *
+     * @param <T> The array type.
+     * @param array  the array to check for {@code null} or empty
+     * @param defaultArray A default array, usually empty.
+     * @return the same array, or defaultArray if {@code null} or empty input.
+     * @since 3.15.0
+     */
+    public static  <T> T[] nullTo(final T[] array, final T[] defaultArray) {
+        return isEmpty(array) ? defaultArray : array;
+    }
+
     /**
      * Defensive programming technique to change a {@code null}
      * reference to an empty one.
@@ -4319,7 +4340,7 @@ public class ArrayUtils {
      * @since 2.5
      */
     public static Boolean[] nullToEmpty(final Boolean[] array) {
-        return isEmpty(array) ? EMPTY_BOOLEAN_OBJECT_ARRAY : array;
+        return nullTo(array, EMPTY_BOOLEAN_OBJECT_ARRAY);
     }
 
     /**
@@ -4357,7 +4378,7 @@ public class ArrayUtils {
      * @since 2.5
      */
     public static Byte[] nullToEmpty(final Byte[] array) {
-        return isEmpty(array) ? EMPTY_BYTE_OBJECT_ARRAY : array;
+        return nullTo(array, EMPTY_BYTE_OBJECT_ARRAY);
     }
 
     /**
@@ -4395,7 +4416,7 @@ public class ArrayUtils {
      * @since 2.5
      */
     public static Character[] nullToEmpty(final Character[] array) {
-        return isEmpty(array) ? EMPTY_CHARACTER_OBJECT_ARRAY : array;
+        return nullTo(array, EMPTY_CHARACTER_OBJECT_ARRAY);
     }
 
     /**
@@ -4414,7 +4435,7 @@ public class ArrayUtils {
      * @since 3.2
      */
     public static Class<?>[] nullToEmpty(final Class<?>[] array) {
-        return isEmpty(array) ? EMPTY_CLASS_ARRAY : array;
+        return nullTo(array, EMPTY_CLASS_ARRAY);
     }
 
     /**
@@ -4452,7 +4473,7 @@ public class ArrayUtils {
      * @since 2.5
      */
     public static Double[] nullToEmpty(final Double[] array) {
-        return isEmpty(array) ? EMPTY_DOUBLE_OBJECT_ARRAY : array;
+        return nullTo(array, EMPTY_DOUBLE_OBJECT_ARRAY);
     }
 
     /**
@@ -4490,7 +4511,7 @@ public class ArrayUtils {
      * @since 2.5
      */
     public static Float[] nullToEmpty(final Float[] array) {
-        return isEmpty(array) ? EMPTY_FLOAT_OBJECT_ARRAY : array;
+        return nullTo(array, EMPTY_FLOAT_OBJECT_ARRAY);
     }
 
     /**
@@ -4528,7 +4549,7 @@ public class ArrayUtils {
      * @since 2.5
      */
     public static Integer[] nullToEmpty(final Integer[] array) {
-        return isEmpty(array) ? EMPTY_INTEGER_OBJECT_ARRAY : array;
+        return nullTo(array, EMPTY_INTEGER_OBJECT_ARRAY);
     }
 
     /**
@@ -4566,7 +4587,7 @@ public class ArrayUtils {
      * @since 2.5
      */
     public static Long[] nullToEmpty(final Long[] array) {
-        return isEmpty(array) ? EMPTY_LONG_OBJECT_ARRAY : array;
+        return nullTo(array, EMPTY_LONG_OBJECT_ARRAY);
     }
 
     /**
@@ -4585,7 +4606,7 @@ public class ArrayUtils {
      * @since 2.5
      */
     public static Object[] nullToEmpty(final Object[] array) {
-        return isEmpty(array) ? EMPTY_OBJECT_ARRAY : array;
+        return nullTo(array, EMPTY_OBJECT_ARRAY);
     }
 
     /**
@@ -4623,7 +4644,7 @@ public class ArrayUtils {
      * @since 2.5
      */
     public static Short[] nullToEmpty(final Short[] array) {
-        return isEmpty(array) ? EMPTY_SHORT_OBJECT_ARRAY : array;
+        return nullTo(array, EMPTY_SHORT_OBJECT_ARRAY);
     }
 
     /**
@@ -4642,7 +4663,7 @@ public class ArrayUtils {
      * @since 2.5
      */
     public static String[] nullToEmpty(final String[] array) {
-        return isEmpty(array) ? EMPTY_STRING_ARRAY : array;
+        return nullTo(array, EMPTY_STRING_ARRAY);
     }
 
     /**
diff --git a/src/test/java/org/apache/commons/lang3/ArrayUtilsTest.java b/src/test/java/org/apache/commons/lang3/ArrayUtilsTest.java
index 330ce9ea4..bc0e2d7c7 100644
--- a/src/test/java/org/apache/commons/lang3/ArrayUtilsTest.java
+++ b/src/test/java/org/apache/commons/lang3/ArrayUtilsTest.java
@@ -2341,6 +2341,12 @@ public class ArrayUtilsTest extends AbstractLangTest {
         assertArrayEquals(ArrayUtils.EMPTY_STRING_ARRAY, ArrayUtils.nullToEmpty((String[]) null));
     }
 
+    @Test
+    public void testNullToShortObject() {
+        @SuppressWarnings("boxing") final Short[] original = {1, 2};
+        assertArrayEquals(original, ArrayUtils.nullTo(original, ArrayUtils.EMPTY_SHORT_OBJECT_ARRAY));
+    }
+
     @Test
     public void testReverse() {
         final StringBuffer str1 = new StringBuffer("pick");