Como Formatar Números em Java

Java oferece várias formas de converter um int, double ou BigDecimal bruto em uma string legível por humanos: separadores de milhar, casas decimais fixas, símbolos de moeda e percentuais. Este capítulo percorre as ferramentas mais usadas: String.format/printf, DecimalFormat e o NumberFormat com suporte a localidade. Para os tipos numéricos subjacentes que esses métodos aceitam, consulte Java Numbers; para o conjunto completo de conversões do printf, consulte Java String Formatting.

Formatação Rápida com String.format e printf

Para formatação pontual dentro de uma linha de log ou System.out, a abordagem com string de formato é o caminho mais curto. printf imprime diretamente; String.format retorna a string para que você possa armazená-la.

double price = 1234.5;
System.out.printf("%.2f%n", price);        // 1234.50
String s = String.format("%,.2f", price);  // 1,234.50
System.out.println(String.format("%08.2f", 42.5)); // 00042.50

A conversão %.2f fixa duas casas decimais, o flag de vírgula , adiciona separadores de agrupamento, e %08.2f preenche o campo inteiro com zeros até a largura 8. Use %n em vez de \n para uma quebra de linha correta para a plataforma. O separador de agrupamento segue a localidade padrão, então o mesmo código pode imprimir 1.234,50 em uma máquina alemã.

Padrões Personalizados com DecimalFormat

Quando você precisa de controle total sobre o padrão, ou quer formatar muitos valores com um único objeto reutilizável, use DecimalFormat. Você descreve a saída com um padrão de caracteres # (dígito opcional) e 0 (dígito obrigatório).

DecimalFormat df = new DecimalFormat("#,##0.00");
df.format(1234.5);   // "1,234.50"
df.format(0.5);      // "0.50"

DecimalFormat sci = new DecimalFormat("0.###E0");
sci.format(123456);  // "1.235E5"

DecimalFormat arredonda com RoundingMode.HALF_EVEN por padrão, o que pode surpreender (2.5 arredonda para 2). Defina df.setRoundingMode(RoundingMode.HALF_UP) se precisar do comportamento cotidiano de "arredondar metade para cima". Uma única instância de DecimalFormat não é thread-safe, portanto crie uma por thread ou proteja-a.

Moeda e Percentual com Suporte a Localidade

Para moeda e percentuais, não construa o padrão manualmente. Os métodos de fábrica do NumberFormat escolhem o símbolo correto, os separadores e a quantidade de dígitos para uma Locale.

NumberFormat us = NumberFormat.getCurrencyInstance(Locale.US);
us.format(1234.5);   // "$1,234.50"

NumberFormat pct = NumberFormat.getPercentInstance(Locale.US);
pct.format(0.87);    // "87%"

Observe que o formatador de percentual multiplica por 100, portanto você passa 0.87 para obter 87%. Passar a Locale correta é o que torna a saída adequada para cada mercado.

Um Exemplo Completo e Executável

O programa abaixo formata o mesmo número de quatro formas diferentes e depois mostra o preenchimento com zeros, para que você possa comparar as saídas lado a lado.

O que observar na execução:

• printf com %,.2f imprime 1,234,567.89, adicionando separadores de agrupamento e fixando duas casas decimais.
• DecimalFormat("#,##0.00") produz o mesmo 1,234,567.89, mas como uma string reutilizável e retornável.
• getCurrencyInstance(Locale.US) adiciona o símbolo $ para obter $1,234,567.89.
• getPercentInstance multiplica 0.8736 por 100 e arredonda para 87%.
• %08.2f preenche 42.5 com zeros até a largura 8, imprimindo 00042.50.

Prática