Java Varargs Explained

In the Java language, there are methods that can accept a variable number of arguments. They are called methods with variable-length arguments (varargs).

Three dots are used to declare variable-length arguments. For example:

static void test(int... array)

Along with a variable-length parameter, a method may also have “regular” parameters. However, the varargs parameter must be the last one in the method’s parameter list. For example:

static void test(double d, int... array)

A method can contain only one parameter with a variable number of arguments.

Using Variable-Length Arguments

The following example shows a test() method declared with a variable number of int arguments. Inside the method, these arguments are accessed as an array. When calling this method, you can pass any number of arguments (including zero) or even an 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});
    }
}

In fact, varargs are syntactic sugar over arrays. The following two lines are equivalent:

test(1, 2, 3);
// equivalent to
test(new int[]{1, 2, 3});

Method Overloading with Variable-Length Arguments

When calling a method without arguments, two methods may be applicable: test(double... array) and test(int... array). In this case, the method with the narrower value range is selected — test(int... array).

When calling the test() method with a single int value — test(3) — the method test(int a) is chosen.

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);
    }
}

Execution result:

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 

When overloading a method that accepts variable-length arguments, unexpected errors may occur. These are related to ambiguity that can arise when calling overloaded methods with varargs.

In the following example, the test method is overloaded: one version accepts varargs of type boolean, and the other also accepts varargs, but of type int. When calling test() without arguments, an ambiguity error occurs — the JVM cannot determine which method to invoke.

Variable-Length Arguments and Ambiguity

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(); // ambiguity error
        test(3);
        test(1, 2);
    }
}