Stringifying Java Arrays

J2SE 5 provided significant new language features that made Java significantly easier to use and more expressive than it had ever been. Although "big" new J2SE 5 features such as enums, generics, and annotations, there was a plethora of new APIs and methods that have made our lives easier ever since. In this post, I briefly look at two of my favorites when dealing with Java arrays: the Arrays.toString(Object[]) method and the Arrays.deepToString(Object[]) method.

The Arrays class has been around since JDK 1.2, but the methods for conveniently and simply converting arrays to a readable String including relevant array content without using Arrays.asList() were added with J2SE 5. Both Arrays.toString(Object[]) and Arrays.deepToString(Object[]) are static methods that act upon the arrays provided to them. The former, Arrays.toString(Object[]), is intended for single-dimension arrays while the latter, Arrays.deepToString(Object[]), is intended for multi-dimensional arrays. As my example later in this post will demonstrate, the multi-dimension deepToString will produce expected results even for single-dimension arrays. The two methods also provide easy and safe null handling, something that I appreciate.

The next code listing is for a simple demonstration class that demonstrates trying to put the contents of various types of Java arrays into a String format. The types of arrays demonstrated are a single dimension array, a double dimensional array representing multi-dimensional arrays of various sizes, and an array that is really just null. The three methods demonstrated for getting a String out of these three types of arrays are (1) simple Object.toString() on each array (implicitly in case of null array to avoid the dreaded NullPointerException), (2) Arrays.toString(Object[]), and (3) Arrays.deepToString(Object[]).

ArrayStrings.java

package dustin.examples;

import java.util.Arrays;
import static java.lang.System.out;

/**
 * Simple demonstration of Arrays.toString(Object[]) method and the
 * Arrays.deepToString(Object[]) method.
 */
public class ArrayStrings
{
   /**
    * Demonstrate usage and behavior of Arrays.toString(Object[]).
    */
   private static void demonstrateArraysToString()
   {
      printHeader("Arrays.toString(Object[])");
      out.println(
           "Single Dimension Arrays.toString: "
         + Arrays.toString(prepareSingleDimensionArray()));
      out.println(
           "Double Dimension Arrays.toString: "
         + Arrays.toString(prepareDoubleDimensionArray()));
      out.println(
           "Null Array Arrays.toString: "
         + Arrays.toString(prepareNullArray()));
   }

   /**
    * Demonstrate usage and behavior of Arrays.deepToString(Object[]).
    */
   private static void demonstrateArraysDeepToString()
   {
      printHeader("Arrays.deepToString(Object[])");
      out.println(
           "Single Dimension Arrays.deepToString: "
         + Arrays.deepToString(prepareSingleDimensionArray()));
      out.println(
           "Double Dimension Arrays.deepToString: "
         + Arrays.deepToString(prepareDoubleDimensionArray()));
      out.println(
           "Null Array Arrays.deepToString: "
         + Arrays.deepToString(prepareNullArray()));
   }

   /**
    * Demonstrate attempting to get String version of array with simple toString()
    * call (not using Arrays class).
    */
   private static void demonstrateDirectArrayString()
   {
      printHeader("Object[].toString() [implicit or explicit]");
      out.println("Single Dimension toString(): " + prepareSingleDimensionArray().toString());
      out.println("Double Dimension toString(): " + prepareDoubleDimensionArray());
      out.println("Null Array toString(): " + prepareNullArray());
   }

   /**
    * Prepare a single-dimensional array to be used in demonstrations.
    *
    * @return Single-dimensional array.
    */
   private static Object[] prepareSingleDimensionArray()
   {
      final String[] names = {"Aaron", "Bianca", "Charles", "Denise", "Elmer"};
      return names;
   }

   /**
    * Prepare a double-dimension array to be used in demonstrations.
    *
    * @return Double-dimensional array.
    */
   private static Object[] prepareDoubleDimensionArray()
   {
      final Object[][] namesAndAges = {
         {"Aaron", 10}, {"Bianca", 25}, {"Charles", 32}, {"Denise", 29}, {"Elmer", 67}};
      return namesAndAges;
   }

   /**
    * Prepare a null array.
    *
    * @return Array that is really null.
    */
   private static Object[] prepareNullArray()
   {
      return null;
   }

   /**
    * Print simple header to standard output with provided header string.
    *
    * @param headerString Text to be included in simple header.
    */
   public static void printHeader(final String headerString)
   {
      out.println(
         "\n===================================================================");
      out.println("== " + headerString);
      out.println(
         "===================================================================");
   }

   /**
    * Main executable function for demonstrating Arrays.toString(Object[]) and
    * Arrays.deepToString(Object[]) methods.
    */
   public static void main(final String[] arguments)
   {
      demonstrateDirectArrayString();
      demonstrateArraysToString();
      demonstrateArraysDeepToString();
   }
}

The above code exercises the three mentioned approaches for getting a String out of an array on the three different types of arrays: single dimension, multi dimension, and null array. The output from running this code demonstrates the utility of the different approaches. That output is shown next.

===================================================================
== Object[].toString() [implicit or explicit]
===================================================================
Single Dimension toString(): [Ljava.lang.String;@3e25a5
Double Dimension toString(): [[Ljava.lang.Object;@19821f
Null Array toString(): null

===================================================================
== Arrays.toString(Object[])
===================================================================
Single Dimension Arrays.toString: [Aaron, Bianca, Charles, Denise, Elmer]
Double Dimension Arrays.toString: [[Ljava.lang.Object;@addbf1, [Ljava.lang.Object;@42e816, [Ljava.lang.Object;@9304b1, [Ljava.lang.Object;@190d11, [Ljava.lang.Object;@a90653]
Null Array Arrays.toString: null

===================================================================
== Arrays.deepToString(Object[])
===================================================================
Single Dimension Arrays.deepToString: [Aaron, Bianca, Charles, Denise, Elmer]
Double Dimension Arrays.deepToString: [[Aaron, 10], [Bianca, 25], [Charles, 32], [Denise, 29], [Elmer, 67]]
Null Array Arrays.deepToString: null

The code above and its corresponding output lead to several observations:

1. Simple Object.toString() on arrays is seldom what we want as it only prints the String representation of the array itself and not of its contents.
2. Arrays.toString(Object[]) will print a String representation for multi-dimensional arrays, but this representation suffers the same drawbacks as Object.toString() after the first dimension. The first dimension (and only dimension for a single dimension array) gets put into an expected String, but deeper dimensions have the same Object.toString() treatment.
3. Arrays.deepToString(Object[]), while intended for multi-dimensional arrays, produces the expected results for both single and multi-dimensional arrays.
4. Both Arrays.toString(Object[]) and Arrays.deepToString(Object[]) handle null array gracefully, simply returning a String "null".

I tend to use Java Collections far more than I use Java arrays. However, when I do need to work with arrays, it is nice to have the many useful features of the java.util.Arrays class. As this post has demonstrated, Arrays.toString(Object[]) and Arrays.deepToString(Object[]) are particularly valuable in obtaining a useful String representation of an array's contents. The java.util.Arrays class provides similar "deep" methods for performing equals and hashCode functionality on multi-dimensional arrays: Arrays.deepEquals and Arrays.deepHashCode.