Add ArrayUtils.toArray (LANG-537).

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/lang/trunk@893547 13f79535-47bb-0310-9956-ffa450edef68

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

@@ -247,6 +247,51 @@ public static Map<Object, Object> toMap(Object[] array) {
         return map;
     }
 
+    // Generic array
+    //-----------------------------------------------------------------------
+    /**
+     * Create a type-safe generic array.
+     *
+     * <p>Arrays are covariant i.e. they cannot be created from a generic type:</p>
+     *
+     * <pre>
+    public static &lt;T&gt; T[] createAnArray(int size)
+    {
+        return T[size]; // compiler error here
+    }
+    public static &lt;T&gt; T[] createAnArray(int size)
+    {
+        return (T[])Object[size]; // ClassCastException at runtime
+    }
+     * </pre>
+     *
+     * <p>Therefore new arrays of generic types can be created with this method, e.g. an arrays
+     * of Strings:</p>
+     *
+     * <pre>
+    String[] array = ArrayUtils.toArray("1", "2");
+    String[] emptyArray = ArrayUtils.&lt;String&gt;toArray();
+     * </pre>
+     * 
+     * The method is typically used in scenarios, where the caller itself uses generic types
+     * that have to be combined into an array.
+     * 
+     * Note, this method makes only sense to provide arguments of the same type so that the
+     * compiler can deduce the type of the array itself. While it is possible to select the
+     * type explicitly like in <code>Number[] array = ArrayUtils.<Number>toArray(new
+     * Integer(42), new Double(Math.PI))</code>, there is no real advantage to <code>new
+     * Number[] {new Integer(42), new Double(Math.PI)}</code> anymore.
+     *
+     * @param  <T>   the array's element type
+     * @param  items the items of the array
+     * @return the array
+     * @since  3.0
+     */
+    public static <T> T[] toArray(final T... items)
+    {
+        return items;
+    }
+    
     // Clone
     //-----------------------------------------------------------------------
     /**

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

@@ -132,6 +132,72 @@ public void testIsEquals() {
         assertEquals(false, ArrayUtils.isEquals(null, array4));
     }
     
+    //-----------------------------------------------------------------------
+    /**
+     * Tests generic array creation with parameters of same type.
+     */
+    public void testArrayCreation()
+    {
+        final String[] array = ArrayUtils.toArray("foo", "bar");
+        assertEquals(2, array.length);
+        assertEquals("foo", array[0]);
+        assertEquals("bar", array[1]);
+    }
+
+    /**
+     * Tests generic array creation with general return type.
+     */
+    public void testArrayCreationWithGeneralReturnType()
+    {
+        final Object obj = ArrayUtils.toArray("foo", "bar");
+        assertTrue(obj instanceof String[]);
+    }
+
+    /**
+     * Tests generic array creation with parameters of common base type.
+     */
+    public void testArrayCreationWithDifferentTypes()
+    {
+        final Number[] array = ArrayUtils.<Number>toArray(Integer.valueOf(42), Double.valueOf(Math.PI));
+        assertEquals(2, array.length);
+        assertEquals(Integer.valueOf(42), array[0]);
+        assertEquals(Double.valueOf(Math.PI), array[1]);
+    }
+
+    /**
+     * Tests generic array creation with generic type.
+     */
+    public void testIndirectArrayCreation()
+    {
+        final String[] array = toArrayPropagatingType("foo", "bar");
+        assertEquals(2, array.length);
+        assertEquals("foo", array[0]);
+        assertEquals("bar", array[1]);
+    }
+
+    /**
+     * Tests generic empty array creation with generic type.
+     */
+    public void testEmptyArrayCreation()
+    {
+        final String[] array = ArrayUtils.<String>toArray();
+        assertEquals(0, array.length);
+    }
+
+    /**
+     * Tests indirect generic empty array creation with generic type.
+     */
+    public void testIndirectEmptyArrayCreation()
+    {
+        final String[] array = ArrayUtilsTest.<String>toArrayPropagatingType();
+        assertEquals(0, array.length);
+    }
+
+    private static <T> T[] toArrayPropagatingType(final T... items)
+    {
+        return ArrayUtils.toArray(items);
+    }
+    
     //-----------------------------------------------------------------------
     public void testToMap() {
         Map<?, ?> map = ArrayUtils.toMap(new String[][] {{"foo", "bar"}, {"hello", "world"}});