LANG-1258: Add ArrayUtils#toStringArray(Object[], String) method (and minimal clean-up of ArrayUtils#toStringArray(Object[]))

add changes.xml entry

src/changes/changes.xml

@@ -55,6 +55,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action issue="LANG-1070" type="fix" dev="pschumacher" due-to="Paul Pogonyshev">ArrayUtils#add confusing example in javadoc</action>
     <action issue="LANG-1271" type="fix" dev="pschumacher" due-to="Pierre Templier">StringUtils#isAnyEmpty and #isAnyBlank should return false for an empty array</action>
     <action issue="LANG-1155" type="fix" dev="pschumacher" due-to="Saif Asif, Thiago Andrade">Add StringUtils#unwrap</action>
+    <action issue="LANG-1258" type="add" dev="pschumacher" due-to="IG, Grzegorz Rożniecki">Add ArrayUtils#toStringArray method</action>
     <action issue="LANG-1160" type="add" dev="kinow">StringUtils#abbreviate should support 'custom ellipses' parameter</action>
     <action issue="LANG-1270" type="add" dev="pschumacher" due-to="Pierre Templier">Add StringUtils#isAnyNotEmpty and #isAnyNotBlank</action>
     <action issue="LANG-1274" type="update" dev="pschumacher">StrSubstitutor should state its thread safety</action>

src/main/java/org/apache/commons/lang3/ArrayUtils.java

@@ -7970,25 +7970,55 @@ public class ArrayUtils {
     }
 
     /**
-     * Returns an array containing the string representation of each entry in the argument array.
+     * <p>Returns an array containing the string representation of each element in the argument array.</p>
      *
-     * <p>
-     * A {@code null} input Object[] returns {@code null}.
-     * </p>
+     * <p>This method returns {@code null} for a {@code null} input array.</p>
      *
-     * @param source the Object[] to be processed, may be null
-     * @return String[] of the same size as the source with its element's string representation,
-     * {@code null} if null Object[] input
+     * @param array the {@code Object[]} to be processed, may be null
+     * @return {@code String[]} of the same size as the source with its element's string representation,
+     * {@code null} if null array input
+     * @throws NullPointerException if array contains {@code null}
      * @since 3.6
      */
-    public static String[] toStringArray(final Object[] source) {
-        if (null == source) return null;
-
-        String[] al = new String[source.length];
-        for (int i = 0; i < source.length; i++) {
-            al[i] = source[i].toString();
+    public static String[] toStringArray(final Object[] array) {
+        if (array == null) {
+            return null;
+        } else if (array.length == 0) {
+            return EMPTY_STRING_ARRAY;
         }
 
-        return al;
+        final String[] result = new String[array.length];
+        for (int i = 0; i < array.length; i++) {
+            result[i] = array[i].toString();
+        }
+
+        return result;
+    }
+
+    /**
+     * <p>Returns an array containing the string representation of each element in the argument
+     * array handling {@code null} elements.</p>
+     *
+     * <p>This method returns {@code null} for a {@code null} input array.</p>
+     *
+     * @param array the Object[] to be processed, may be null
+     * @param valueForNullElements the value to insert if {@code null} is found
+     * @return a {@code String} array, {@code null} if null array input
+     * @since 3.6
+     */
+    public static String[] toStringArray(final Object[] array, final String valueForNullElements) {
+        if (null == array) {
+            return null;
+        } else if (array.length == 0) {
+            return EMPTY_STRING_ARRAY;
+        }
+
+        final String[] result = new String[array.length];
+        for (int i = 0; i < array.length; i++) {
+            final Object object = array[i]; 
+            result[i] = (object == null ? valueForNullElements : object.toString());
+        }
+
+        return result;
     }
 }

src/test/java/org/apache/commons/lang3/ArrayUtilsTest.java

@@ -4443,11 +4443,29 @@ public class ArrayUtilsTest  {
     }
 
     @Test
-    public void testToStringArray() {
+    public void testToStringArray_array() {
         assertNull(ArrayUtils.toStringArray(null));
 
+        assertArrayEquals(new String[0], ArrayUtils.toStringArray(new Object[0]));
+
         final Object[] array = new Object[] {1, 2, 3, "array", "test"};
         assertArrayEquals(new String[]{"1", "2", "3", "array", "test"}, ArrayUtils.toStringArray(array));
+
+        try {
+            ArrayUtils.toStringArray(new Object[] {null});
+            fail("NullPointerException expected!");
+        } catch (final NullPointerException expected) {}
+    }
+
+    @Test
+    public void testToStringArray_array_string() {
+        assertNull(ArrayUtils.toStringArray(null, ""));
+
+        assertArrayEquals(new String[0], ArrayUtils.toStringArray(new Object[0], ""));
+
+        final Object[] array = new Object[] { 1, null, "test" };
+        assertArrayEquals(new String[]{"1", "valueForNullElements", "test"},
+                ArrayUtils.toStringArray(array, "valueForNullElements"));
     }
 
 }