Classe Utilitária Java Arrays

java.util.Arrays é a coleção de utilitários de arrays da biblioteca padrão. É uma classe final com apenas métodos static — você nunca a instancia, apenas chama seus métodos diretamente: Arrays.sort(...), Arrays.toString(...), e assim por diante. Quando você sabe o que há nela, o código de manipulação de arrays que você escreve fica muito mais curto.

Este capítulo é um tour guiado. Ordenação e cópia têm seus próprios capítulos; aqui focamos no restante.

Importação

import java.util.Arrays;

Quase todos os exemplos abaixo assumem esta importação.

toString e deepToString

Transforma um array em uma string legível. toString lida com arrays unidimensionais:

int[] data = {3, 1, 4};
String s = Arrays.toString(data);   // "[3, 1, 4]"

deepToString formata recursivamente arrays aninhados:

int[][] grid = {{1, 2}, {3, 4}};
String s = Arrays.deepToString(grid);   // "[[1, 2], [3, 4]]"

Ambos funcionam para tipos de elementos primitivos e de objeto.

equals e deepEquals

== compara referências de arrays. Para comparar conteúdos:

int[] a = {1, 2, 3};
int[] b = {1, 2, 3};
boolean same = Arrays.equals(a, b);   // true

Para arrays aninhados, use deepEquals:

int[][] g1 = {{1, 2}, {3, 4}};
int[][] g2 = {{1, 2}, {3, 4}};
boolean same = Arrays.deepEquals(g1, g2);   // true

Ambos consideram null == null como true.

hashCode e deepHashCode

Hashes baseados em conteúdo, úteis quando uma classe encapsula um array e precisa de equals/hashCode:

int[] data = {1, 2, 3};
int h = Arrays.hashCode(data);

Se você sobrescrever equals para usar Arrays.equals, deve sobrescrever hashCode para usar Arrays.hashCode a fim de manter o contrato.

fill

Define todos os elementos com um valor, ou define um intervalo:

int[] data = new int[5];
Arrays.fill(data, 7);              // {7, 7, 7, 7, 7}
Arrays.fill(data, 1, 4, 0);        // zero indexes 1..3

sort e parallelSort

Ordenação in-place, ascendente:

int[] data = {3, 1, 4, 1, 5};
Arrays.sort(data);                 // {1, 1, 3, 4, 5}

Para arrays muito grandes, você pode usar parallelSort para distribuir o trabalho em múltiplos núcleos. A história completa de ordenação — primitivos, objetos, ordens personalizadas — está no capítulo Ordenando arrays.

binarySearch

Encontra um elemento em um array ordenado em O(log n):

int[] sorted = {1, 3, 5, 7, 9};
int idx = Arrays.binarySearch(sorted, 5);   // 2
int miss = Arrays.binarySearch(sorted, 6);  // negative — encodes insertion point

Se o elemento estiver ausente, o valor de retorno é -(insertionPoint) - 1. Então miss == -4 significa que 6 pertenceria ao índice 3. Se a entrada não estiver ordenada, o resultado é indefinido — ordene primeiro.

copyOf e copyOfRange

Retorna um novo array, copiando valores de um existente:

int[] data = {1, 2, 3, 4, 5};
int[] all   = Arrays.copyOf(data, data.length);    // exact copy
int[] grown = Arrays.copyOf(data, 8);              // padded with zeros
int[] slice = Arrays.copyOfRange(data, 1, 4);      // {2, 3, 4}

Estes são abordados em detalhes em Copiando arrays.

asList

Envolve um array de referências como uma List de tamanho fixo:

String[] arr = {"a", "b", "c"};
List<String> list = Arrays.asList(arr);

A lista é suportada pelo array — list.set(0, "z") também altera arr[0]. O tamanho é fixo, então add/remove lançam exceção. Com arrays primitivos, não faz o que você esperaria: Arrays.asList(new int[]{1, 2, 3}) produz uma List<int[]> de comprimento um. Para primitivos, converta com streams primeiro.

stream

Obtém um stream de qualquer array numérico ou de objetos:

int[] nums = {3, 1, 4, 1, 5};
int sum = Arrays.stream(nums).sum();
double avg = Arrays.stream(nums).average().orElse(0);

Para arrays de objetos, Arrays.stream(arr) retorna um Stream<T>. Também existem formas limitadas por intervalo — Arrays.stream(arr, from, to).

setAll e parallelSetAll

Preenche um array usando uma função do índice:

int[] squares = new int[6];
Arrays.setAll(squares, i -> i * i);
// {0, 1, 4, 9, 16, 25}

Use setAll quando quiser uma sequência derivada e um loop for seria apenas ruído.

compare e mismatch (Java 9+)

Arrays.compare(a, b) retorna negativo, zero ou positivo — ordem lexicográfica sobre os elementos:

int[] a = {1, 2, 3};
int[] b = {1, 2, 4};
int cmp = Arrays.compare(a, b);   // negative — a is smaller

Arrays.mismatch(a, b) retorna o índice do primeiro elemento diferente, ou -1 se forem iguais:

int diff = Arrays.mismatch(a, b);   // 2

Quando um array é um prefixo próprio do outro, o mais curto é considerado "menor" por compare, e mismatch retorna o comprimento do array mais curto:

int[] s = {1, 2};
int[] l = {1, 2, 3};
Arrays.compare(s, l);    // negative — s is a prefix, so it sorts first
Arrays.mismatch(s, l);   // 2 — they agree up to index 2, then s runs out

Estes são úteis quando você precisa de ordem ou "onde divergiram" sem escrever o loop manualmente.

Armadilhas comuns

Algumas armadilhas pegam as pessoas com frequência suficiente para valer a pena listar em um só lugar:

• == não é comparação de conteúdo. a == b é true somente quando ambos os nomes apontam para o mesmo objeto array. Use Arrays.equals (ou Arrays.deepEquals para arrays aninhados) para comparar conteúdos.
• toString é superficial. Arrays.toString(grid) em um int[][] imprime algo como [[I@1b6d3586, ...] — os arrays internos usam seu Object.toString padrão. Use Arrays.deepToString sempre que um array contiver outros arrays.
• asList com um array primitivo te surpreende. Arrays.asList(new int[]{1, 2, 3}) é uma List<int[]> de um elemento, não uma List<Integer> de comprimento três, porque int[] é um único objeto. Use Arrays.stream(arr).boxed().toList() (Java 16+) para obter a lista que você pretendia.
• asList tem tamanho fixo. É uma visão sobre o array original, então set funciona mas add e remove lançam UnsupportedOperationException. Envolva com new ArrayList<>(Arrays.asList(...)) se precisar crescê-lo.
• binarySearch precisa de um array ordenado. Em entrada não ordenada, o resultado é indefinido — não lança exceção, apenas retorna um índice errado. Ordene primeiro.

Um exemplo prático

A demonstração abaixo une a maioria dos métodos. Execute-a e compare a saída com os comentários acima — binarySearch retornando 5 para o valor 5, o resultado negativo para um elemento ausente, e a lista [red, green, blue] de asList:

O que vem a seguir

Usamos Arrays.sort apenas de relance. O próximo capítulo, Ordenando arrays, aprofunda como a ordenação funciona para primitivos versus objetos, ascendente versus descendente, e como ordenar por seus próprios critérios com um Comparator.

Prática