Java List <T> T[] toArray(T[] a) implementation

From the javadocs:

Like the toArray() method, this method acts as bridge between array-based and collection-based APIs. Further, this method allows precise control over the runtime type of the output array, and may, under certain circumstances, be used to save allocation costs.

This means that the programmer is in control over what type of array it should be.

For example, for your ArrayList<Integer> instead of an Integer[] array you might want a Number[] or Object[] array.

Furthermore, the method also checks the array that is passed in. If you pass in an array that has enough space for all elements, the the toArray method re-uses that array. This means:

Integer[] myArray = new Integer[myList.size()];
myList.toArray(myArray);

or

Integer[] myArray = myList.toArray(new Integer[myList.size()]);

has the same effect as

Integer[] myArray = myList.toArray(new Integer[0]);

Note, in older versions of Java the latter operation used reflection to check the array type and then dynamically construct an array of the right type. By passing in a correctly sized array in the first place, reflection did not have to be used to allocate a new array inside the toArray method. That is no longer the case, and both versions can be used interchangeably.


It is declared generically so that you can write code such as

Integer[] intArray = list.toArray(new Integer[0]);

without casting the array coming back.

It is declared with the following annotation:

@SuppressWarnings("unchecked")

In other words, Java is trusting you to pass in an array parameter of the same type, so your error does not occur.


The reason why the method has this signature is because the toArray API predates generics: the method

 public Object[] toArray(Object[] a)

has been introduced as early as Java 1.2.

The corresponding generic that replaces Object with T has been introduced as a 100% backward-compatible option:

public <T> T[] toArray(T[] a)

Changing the signature to generic lets callers avoid the cast: prior to Java 5, callers needed to do this:

String[] arr = (String[])stringList.toArray(new String[stringList.size()]);

Now they can do the same call without a cast:

String[] arr = stringList.toArray(new String[stringList.size()]);

EDIT :

A more "modern" signature for the toArray method would be a pair of overloads:

public <T> T[] toArray(Class<T> elementType)
public <T> T[] toArray(Class<T> elementType, int count)

This would provide a more expressive, and equally versatile, alternative to the current method signature. There is an efficient implementation of this, too, with Array.newInstance(Class<T>,int) method in place. Changing the signature in this way would not be backward-compatible, though.