Java Varargs: Methods with Variable-Length Arguments

Varargs (short for variable arguments) is Java syntax that lets you declare a method accepting a variable number of arguments. Such methods are also called methods with variable-length arguments. The feature was introduced in Java 5 and has not changed since.

A variable-length parameter is declared with three dots after the type:

static void test(int... array)

You can call such a method with any number of arguments — including none at all:

test();                   // 0 arguments
test(1);                  // 1 argument
test(1, 2, 3);            // 3 arguments
test(new int[]{1, 2, 3}); // an array works too

Rules for declaring varargs

A method may have ordinary parameters alongside the variable-length one. However, the varargs parameter must come last in the parameter list, and a method can have only one of them:

static void test(double d, int... array)   // valid
// static void test(int... array, double d)        // compile error
// static void test(int... a, double... b)         // compile error

Example: a method with a variable number of arguments

In the example below, the test() method is declared with a variable number of int arguments. Inside the method the parameter is used as an ordinary array. At the call site you can pass any number of values — including zero — or an existing array:

public class VarArgsExample {
    static void test(int... array) {
        System.out.println("Number of arguments: " + array.length);
        for (int a : array) {
            System.out.print(a + " ");
        }
        System.out.println();
    }

    public static void main(String[] args) {
        test();
        test(1);
        test(1, 2);
        test(new int[]{1, 3});
    }
}

Program output:

Number of arguments: 0

Number of arguments: 1
1
Number of arguments: 2
1 2
Number of arguments: 2
1 3

Varargs under the hood: it is just an array

Varargs is syntactic sugar over arrays. The compiler creates the array at the call site and passes it as the argument, so after compilation these two lines are indistinguishable:

test(1, 2, 3);
// the compiler turns the call above into this one:
test(new int[]{1, 2, 3});

Two practical consequences follow from that:

• inside the method you can use length, indexing, the for-each loop, Arrays.toString() and everything else that works on arrays;
• a call with no arguments delivers an empty array, not null, so reading array.length is always safe.

Method overloading with varargs

Methods with a variable number of arguments take part in method overloading under special rules. The compiler resolves the call in three phases and moves on to the next phase only when the current one produces no applicable candidate.

Hence the golden rule: a varargs method is always considered last. If a fixed-arity method fits the call, that one wins.

When several varargs methods are applicable in phase 3, the compiler picks the most specific one — the candidate whose arguments could be handed to the other candidate without losing information. In the example below test(int... array) is more specific than test(double... array), because int widens to double but not the other way round:

public class VarArgsExample2 {
    static void test(double... array) {
        System.out.println("test(double... array)");
        System.out.println("Number of arguments: " + array.length);
        for (double a : array) {
            System.out.print(a + " ");
        }
        System.out.println();
    }

    static void test(int... array) {
        System.out.println("test(int... array)");
        System.out.println("Number of arguments: " + array.length);
        for (int a : array) {
            System.out.print(a + " ");
        }
        System.out.println();
    }

    static void test(int a) {
        System.out.println("test(int a)");
    }

    public static void main(String[] args) {
        test();
        test(3);
        test(1.0);
        test(1, 2);
    }
}

Program output:

test(int... array)
Number of arguments: 0

test(int a)
test(double... array)
Number of arguments: 1
1.0
test(int... array)
Number of arguments: 2
1 2

Call by call:

• test() — no fixed-arity method fits, so phase 3 kicks in; of the two varargs candidates the more specific test(int... array) is chosen;
• test(3) — test(int a) already matches in phase 1, so varargs are never considered;
• test(1.0) — double cannot be narrowed to int, leaving only test(double... array);
• test(1, 2) — no fixed-arity method takes two arguments, so test(int... array) wins again.

The ambiguity error

Overloading methods with variable-length arguments makes it easy to end up with an ambiguity: several candidates match equally well and none of them is more specific. This situation is caught by the compiler at build time — the code simply does not compile, so the JVM never sees it.

In the example below test is overloaded: one version takes boolean varargs, the other takes int varargs. There is no widening relationship between boolean and int, so a no-argument call test() cannot be resolved:

public class VarArgsExample3 {
    static void test(boolean... array) {
        System.out.println("test(boolean... array)");
        System.out.println("Number of arguments: " + array.length);
        for (boolean a : array) {
            System.out.print(a + " ");
        }
        System.out.println();
    }

    static void test(int... array) {
        System.out.println("test(int... array)");
        System.out.println("Number of arguments: " + array.length);
        for (int a : array) {
            System.out.print(a + " ");
        }
        System.out.println();
    }

    public static void main(String[] args) {
        // test();  // compile error: reference to test is ambiguous
        test(3);
        test(1, 2);
    }
}

Uncomment the test() call and javac reports:

error: reference to test is ambiguous
        both method test(boolean...) and method test(int...) match

There are two ways out: pass an explicit empty array of the type you want — test(new int[0]) — or drop one of the overloads and give the methods different names.

Varargs and generics: @SafeVarargs

When a varargs parameter has a generic type, the compiler warns about possible heap pollution: because of type erasure an array of List<String> is really a List[] at runtime, and anything can be stored into it.

static void unsafe(List<String>... lists) {   // warning: possible heap pollution
    Object[] objects = lists;
    objects[0] = List.of(1, 2, 3);            // the compiler does not object
    String s = lists[0].get(0);               // ClassCastException at runtime
}

If the method only reads the elements and never writes into the array, the warning is suppressed with the @SafeVarargs annotation:

@SafeVarargs
static <T> List<T> toList(T... items) {
    return new ArrayList<>(Arrays.asList(items));
}

Varargs in the standard library

Varargs is used all over the JDK, and several familiar methods feel like magic precisely because of it:

System.out.printf("%s = %d%n", "age", 30);      // printf(String, Object...)
String s = String.format("%s-%s", "a", "b");    // format(String, Object...)
List<String> list = List.of("a", "b", "c");     // of(E...)
List<Integer> nums = Arrays.asList(1, 2, 3);    // asList(T...)
int[] copy = {1, 2, 3};
System.out.println(Arrays.toString(copy));

Where developers get tripped up

• Passing null directly. Calling test(null) on test(String... s) does not pass "one null element" — it passes null as the whole array, and the very next s.length throws NullPointerException. To pass a single null element, write test((String) null).
• A primitive array where an object array is expected. Arrays.asList(new int[]{1, 2, 3}) returns a List<int[]> of size 1, not a list of three numbers: for a T... parameter an int[] counts as a single object. Use Integer[] or Arrays.stream(...).boxed().
• Expecting null on an empty call. An if (array == null) check is pointless for normal call sites: what arrives is an empty array.
• An overly greedy varargs method. test(Object... args) matches almost any call and quietly swallows invocations you intended for another overload.
• Using varargs instead of validation. If at least one argument is always required, declare test(int first, int... rest) — then the compiler enforces the rule instead of a runtime if.