Why does Guava's ImmutableList have so many overloaded of() methods?

Question

I was just looking at Guava's ImmutableList and I noticed that the of() method was overloaded 12 times.

It looks to me that all they needed was:

static <E> ImmutableList<E> of(); static <E> ImmutableList<E> of(E element); // not even necessary static <E> ImmutableList<E> of(E... elements); 

What's the reason for having so many similar variations?

Answer 1

Varargs and generics do not play nicely together. Varargs methods can cause a warning with generic arguments, and the overloads prevent that warning except in the rare case that you want to add more than 11 items to the immutable list using of().

The comments in the source say:

These go up to eleven. After that, you just get the varargs form, and whatever warnings might come along with it. :(

Note that Java 7's @SafeVarargs annotation was added specifically to eliminate the need for this sort of thing. A single of(E...) method annotated with @SafeVarargs could be used and would not give warnings with generic arguments.

Answer 2

There's also a performance reason. Every invocation of a varargs method causes an array allocation and initialization. If you have somehow determined that e.g. 95% of the calls are with 3 or less arguments and only 5% with 4 or more, then overloading like this

public static <E> ImmutableList<E> of(); public static <E> ImmutableList<E> of( E e ); public static <E> ImmutableList<E> of( E e1, E e2 ); public static <E> ImmutableList<E> of( E e1, E e2, E e3 ); public static <E> ImmutableList<E> of( E e1, E e2, E e3, E... es ); 

leads to a nice performance boost in 95% of the cases. Differently put, the average case performance goes up.