Docs executáveis de Java: Varargs

Um método, qualquer número de argumentos

Às vezes você não sabe de antemão quantos argumentos um método precisa. Num momento você quer max(3, 9) e no seguinte max(1, 7, 4, 2, 8). Sem varargs você teria que escrever uma sobrecarga para cada quantidade ou forçar quem chama a construir um array. Os varargs - abreviação de argumentos variáveis - permitem que um único método aceite zero, um ou muitos valores do mesmo tipo.

Você os declara colocando três pontos (...) depois do tipo do parâmetro:

public class Main {
    static int sum(int... numbers) {
        int total = 0;
        for (int n : numbers) {   // numbers é apenas um int[]
            total += n;
        }
        return total;
    }

    public static void main(String[] args) {
        System.out.println(sum(1, 2, 3));        // 6
        System.out.println(sum(10, 20));         // 30
        System.out.println(sum());               // 0 - zero argumentos é permitido
        System.out.println(sum(4, 8, 15, 16));   // 43
    }
}

Quem chama passa valores soltos; dentro do método numbers é um array de verdade. Essa é a ideia toda: o compilador empacota os argumentos em um array para você.

Varargs são apenas um array

Não há mágica em tempo de execução. Um parâmetro declarado int... numbers é exatamente um int[] quando você está dentro do método. Você pode consultar seu length, indexá-lo e percorrê-lo como qualquer outro array.

public class Main {
    static String join(String separator, String... parts) {
        if (parts.length == 0) {
            return "";
        }
        StringBuilder sb = new StringBuilder(parts[0]);
        for (int i = 1; i < parts.length; i++) {
            sb.append(separator).append(parts[i]);
        }
        return sb.toString();
    }

    public static void main(String[] args) {
        System.out.println(join("-", "2026", "06", "04"));  // 2026-06-04
        System.out.println(join(", ", "alone"));            // alone
    }
}

Como é genuinamente um array, você também pode entregar a um método varargs um array que já tem - ele aceita as duas formas:

public class Main {
    static int sum(int... numbers) {
        int total = 0;
        for (int n : numbers) total += n;
        return total;
    }

    public static void main(String[] args) {
        int[] data = {5, 10, 15};
        System.out.println(sum(data));        // passa um array existente
        System.out.println(sum(1, 2, 3, 4));  // ou valores soltos
    }
}

As regras: por último e apenas um

Duas regras mantêm os varargs sem ambiguidade, e o compilador faz cumprir as duas:

O parâmetro varargs precisa ser o último. Os parâmetros normais vêm primeiro, e então o parâmetro ... absorve tudo o que sobrar.
Um método pode ter no máximo um parâmetro varargs. Dois tornariam impossível saber onde um termina e o próximo começa.

public class Main {
    // OK: parâmetro normal primeiro, varargs por último
    static void log(String level, Object... values) {
        System.out.print("[" + level + "] ");
        for (Object v : values) {
            System.out.print(v + " ");
        }
        System.out.println();
    }

    public static void main(String[] args) {
        log("INFO", "user", 42, true);
        log("WARN");   // a parte de varargs pode estar vazia
    }
}

Isso compila. Mas colocar os varargs primeiro - static void log(Object... values, String level) - é um erro de compilação: varargs parameter must be the last. O parâmetro obrigatório level sempre precede o ....

Onde você já usa varargs

Você vem chamando métodos varargs o tempo todo. System.out.printf e String.format são os exemplos clássicos: o segundo parâmetro deles é Object... args:

public class Main {
    public static void main(String[] args) {
        System.out.printf("%s scored %d points (%.1f%%)%n", "Ada", 95, 95.0);

        String row = String.format("%-8s | %5d", "banana", 30);
        System.out.println(row);
    }
}

List.of(...), Arrays.asList(...) e muitas APIs no estilo builder também são varargs. É por isso que você pode passar qualquer número de elementos para elas sem envolver nada em um array por conta própria.

Varargs e sobrecarga

Varargs e sobrecarga interagem de uma forma surpreendente. Quando uma sobrecarga normal e uma sobrecarga varargs poderiam ambas corresponder a uma chamada, o Java prefere a mais específica: o método de aridade fixa vence:

public class Main {
    static String pick(int a, int b) {
        return "two-arg version";
    }

    static String pick(int... nums) {
        return "varargs version";
    }

    public static void main(String[] args) {
        System.out.println(pick(1, 2));      // two-arg version (mais específica)
        System.out.println(pick(1, 2, 3));   // varargs version
        System.out.println(pick());          // varargs version
    }
}

pick(1, 2) corresponde às duas, mas o Java escolhe a sobrecarga sem varargs porque ela encaixa melhor. O método varargs só é executado quando nenhuma sobrecarga de aridade fixa corresponde. Isso normalmente é o que você quer, mas significa que adicionar uma sobrecarga varargs pode mudar silenciosamente para qual método uma chamada é resolvida.

Cuidado com as chamadas vazias e com null

Duas armadilhas pegam as pessoas. Primeira: chamar um método varargs sem argumentos entrega ao método um array vazio, não null, então numbers.length é 0 e o laço não faz nada. Você não precisa de uma verificação de null para o caso sem argumentos:

public class Main {
    static int count(Object... items) {
        return items.length;   // 0 para count(), nunca uma NPE
    }

    public static void main(String[] args) {
        System.out.println(count());            // 0
        System.out.println(count("a", "b"));    // 2
    }
}

Segunda: passar um null literal é ambíguo e perigoso: o Java pode interpretar count(null) como "o array de varargs inteiro é null" em vez de "um elemento null", o que então lança uma NullPointerException quando você lê seu length. Se você realmente quer dizer um único elemento null, seja explícito com count((Object) null).

A seguir: Classes

Os varargs completam o que você pode fazer com parâmetros de métodos: listas de argumentos flexíveis em cima da sobrecarga. Até agora os métodos viveram soltos em uma classe com static. A seguir você verá como as classes realmente funcionam: agrupar dados (campos) e comportamento (métodos) em seus próprios tipos, que é o coração da programação orientada a objetos em Java.

Perguntas frequentes

O que são varargs em Java?

Varargs (argumentos variáveis) permitem que um método aceite qualquer número de argumentos do mesmo tipo. Você os declara colocando ... depois do tipo: int sum(int... numbers). Quem chama pode passar zero, um ou muitos valores, e dentro do método numbers é um array normal. É açúcar sintático: o Java reúne os argumentos soltos em um array para você.

Um método em Java pode ter mais de um parâmetro varargs?

Não. Um método pode ter no máximo um parâmetro varargs, e ele precisa ser o último da lista de parâmetros - por exemplo void log(String level, Object... values). Se não fosse o último, o Java não saberia onde termina a parte de comprimento variável e onde começa o próximo parâmetro. Os parâmetros normais vêm sempre antes do parâmetro ....

Qual é a diferença entre varargs e um parâmetro de array em Java?

Eles são quase a mesma coisa em tempo de execução: um parâmetro varargs int... é um int[] dentro do método. A diferença está no ponto da chamada: com varargs você escreve sum(1, 2, 3) (valores soltos), enquanto com um parâmetro de array explícito você precisa construir e passar um array, sum(new int[]{1, 2, 3}). Um método varargs também aceita um array diretamente, então é a escolha mais flexível.

Conceitos relacionados