Formatação de strings em Java: String.format, printf e especificadores de formato

Duas maneiras de formatar

Java formata strings a partir de um template que contém especificadores de formato (os marcadores %) mais os valores a serem inseridos. Há dois pontos de entrada, e eles compartilham uma sintaxe idêntica:

• String.format(template, values...) retorna uma nova String.
• System.out.printf(template, values...) imprime o resultado diretamente.

public class Main {
    public static void main(String[] args) {
        String name = "Ada";
        int age = 36;

        String line = String.format("%s is %d years old", name, age);
        System.out.println(line);

        System.out.printf("%s is %d years old%n", name, age);
    }
}

Ambos produzem o mesmo texto. String.format o devolve para que você possa armazená-lo; printf o escreve no console. Repare no %n no fim do template do printf - essa é a quebra de linha independente de plataforma (prefira-a a \n em strings de formato).

Os especificadores mais comuns

Cada especificador começa com % e termina com uma letra que indica que tipo de valor é esperado:

public class Main {
    public static void main(String[] args) {
        System.out.printf("string: %s%n", "hello");
        System.out.printf("integer: %d%n", 42);
        System.out.printf("float: %f%n", 3.14);
        System.out.printf("boolean: %b%n", true);
        System.out.printf("char: %c%n", 'A');
        System.out.printf("hex: %x%n", 255);
        System.out.printf("percent sign: %%%n");
    }
}

Os três do dia a dia são %s (qualquer valor, via seu toString), %d (números inteiros) e %f (decimais). Use %% para imprimir um sinal de porcentagem literal. Passar o tipo errado - digamos, uma String para %d - lança uma IllegalFormatConversionException em tempo de execução.

Controlando as casas decimais

%f usa por padrão seis casas decimais, o que raramente é o que você quer. Coloque .N antes do f para fixar a precisão (o valor é arredondado):

public class Main {
    public static void main(String[] args) {
        double price = 3.14159;

        System.out.printf("%f%n", price);     // 3.141590
        System.out.printf("%.2f%n", price);   // 3.14
        System.out.printf("%.0f%n", price);   // 3
    }
}

Adicione o sinalizador de vírgula para os separadores de agrupamento em números grandes:

public class Main {
    public static void main(String[] args) {
        double total = 1234567.891;
        System.out.printf("%,.2f%n", total);   // 1,234,567.89
    }
}

Largura e preenchimento

Um número entre o % e a letra do tipo define uma largura mínima de campo, preenchendo com espaços para que as colunas fiquem alinhadas. Um - inicial alinha à esquerda; um 0 inicial preenche os números com zeros:

public class Main {
    public static void main(String[] args) {
        System.out.printf("[%10s]%n", "hi");    // right-aligned in 10 cols
        System.out.printf("[%-10s]%n", "hi");   // left-aligned
        System.out.printf("[%05d]%n", 42);      // zero-padded to width 5
    }
}

É isso que torna legíveis as tabelas formatadas e os relatórios alinhados:

public class Main {
    public static void main(String[] args) {
        String[] names = {"Ada", "Boris", "Chen"};
        int[] scores = {95, 8, 142};

        for (int i = 0; i < names.length; i++) {
            System.out.printf("%-8s %5d%n", names[i], scores[i]);
        }
    }
}

O %-8s alinha os nomes à esquerda em uma coluna de 8 de largura e %5d alinha as pontuações à direita em uma coluna de 5 de largura, de modo que os números ficam alinhados independentemente da quantidade de dígitos.

Ordem dos argumentos

Por padrão, os especificadores consomem os valores da esquerda para a direita. Você pode repetir ou reordenar um valor com N$ (índice começando em um), útil quando o mesmo valor aparece duas vezes:

public class Main {
    public static void main(String[] args) {
        System.out.printf("%1$s, %1$s, hello %2$s%n", "echo", "world");
    }
}

%1$s se refere ao primeiro argumento nas duas vezes, então echo é impresso duas vezes.

O método formatted()

Desde o Java 15, toda string tem um método de instância formatted - o mesmo motor do String.format, apenas escrito como uma chamada de método sobre o template:

public class Main {
    public static void main(String[] args) {
        String msg = "%s scored %d".formatted("Ada", 95);
        System.out.println(msg);
    }
}

Ele combina especialmente bem com os text blocks (strings de várias linhas com aspas triplas) ao montar saídas formatadas maiores.

Quando não usar String.format

Para junções simples e pontuais, a concatenação comum com + é mais clara e rápida:

String greeting = "Hi, " + name + "!";   // simpler than String.format here

Recorra a String.format / printf quando precisar de formatação de verdade - casas decimais fixas, preenchimento, alinhamento, agrupamento - e não apenas colar alguns valores.

A seguir: Operadores

A formatação transforma valores em texto. Para calcular esses valores em primeiro lugar, você precisa dos operadores do Java - aritméticos, de comparação e lógicos. Essa é a próxima página.