Domine a formatação de Strings em Java com String.format

O format é um método estático da classe String do pacote java.lang, sua função é formatar uma string com base em uma cadeia de formato e um conjunto de argumentos, devido a ser um método estático não é necessário a instancia de nenhum objeto para sua utilização.

O método format está disponível desde a versão 1.5 do Java (Java 5), esse método faz parte das melhorias introduzidas no pacote java.util para oferecer suporte à formatação de strings, dessa forma pode-se utilizar o método em todas as versões a partir do Java 5.

Assinaturas do método

• public static String format(String format, Object… args): é usada passando uma string que será formatada e um conjunto de objetos separados por virgula.
• public static String format(Locale l, String format, Object… args): é usado passando um objeto Locale, uma string que será formatada e um conjunto de objetos que serão adicionados a string.

Exemplo de uso do String.format

Na String que será formatada é necessário passar os especificadores de formato para que o método funcione corretamente, disponibilizamos uma lista de especificadores.

1 – Uso básico do método:

String message = "Meu nome é %s e tenho %d anos";
String name = "Ellen";
int age = 27;
String output = String.format(message, name, age);
System.out.println(output);

Saída:

Meu nome é Ellen e tenho 27 anos

2 – Usando como o parâmetro Locale:

O Locale é utilizado para especificar as convenções regionais para o formato de número, datas moedas entre outros, especificar o Locale é importante quando você deseja garantir que a formatação esteja em conformidade com as convenções, um exemplo é no Brasil utilizar virgula para separação de casas decimais.

Locale locale = new Locale("pt", "BR");
String message = "Tenho uma divida de R$ %.2f";
double value = 1622.37;
String output = String.format(locale, message, value);
System.out.println(output);

Saída:

Tenho uma divida de R$ 1622,37

Também é possível utilizar constantes da classe Locale que utilizam-se de construtores de fábrica, que são comumente utilizados:

Locale english = Locale.ENGLISH;
Locale france = Locale.FRANCE;

Infelizmente não existe essas constantes para o português brasileiro, então pode ser utilizado adicionando os valores de linguagem no construtor, segue alguns exemplos:

Locale locale = new Locale("pt", "BR");
Locale portuguesBrasilABNT = new Locale("pt", "BR", "ABNT");

3 – Exemplo de formato inválido e lançamento de Exception:

Vale lembrar que as exceções lançadas por essa classe são extensões da exceção RuntimeException, isso significa que ela não te força a fazer o tratamento dessas exceções, mas é importante que na sua aplicação em alguma camada esse erro seja tratado para evitar que esse erro retorne ao usuário sem nenhuma tratativa, ou impedir o funcionamento da aplicação de alguma forma.

String message = "Meu nome é %x e tenho %d anos";
String name = "Ellen";
int age = 27;
String output = String.format(message, name, age);
System.out.println(output);

Saída:

Exception in thread "main" java.util.IllegalFormatConversionException: x != java.lang.String
	at java.base/java.util.Formatter$FormatSpecifier.failConversion(Formatter.java:4442)
	at java.base/java.util.Formatter$FormatSpecifier.printInteger(Formatter.java:2963)
	at java.base/java.util.Formatter$FormatSpecifier.print(Formatter.java:2918)
	at java.base/java.util.Formatter.format(Formatter.java:2689)
	at java.base/java.util.Formatter.format(Formatter.java:2625)
	at java.base/java.lang.String.format(String.java:4143)
	at desvendando_java/desvendando.java.strings.ConcatenandoStrings.main(ConcatenandoStrings.java:12)

Também é possível forçar o tratamento da exceção adicionando um try/catch envolvendo o código que faz a transformação, a hierarquia de exceções que podem ser adicionadas são: IllegalFormatConversionException, IllegalFormatException, IllegalArgumentException, ou simplesmente adicionar RuntimeException.

Especificadores de formato

Especificadores de formato são códigos usados em strings para controlar a formatação de valores quando são impressos ou convertidos, eles são muito úteis quando utilizado em conjunto com a classe String.format, também podem ser utilizados com outras classes do java como a “System.out.printf” e “Formatter”.

Lista de especificadores de formato que podem ser utilizados em conjunto com o método format:

• %d: usado para formatar valores inteiros (int, long, byte, short) em decimal;
• %f: usado para formatar valores de ponto flutuante (float, double) em decimal;
• %s: usado para formatar valores de tipo String;
• %c: usado para formatar caracteres;
• %b: usado para formatar valores booleanos;
• %o: usado para formatar valores inteiros em octal;
• %x: usado para formatar valores inteiros em hexadecimal;
• %e ou %E: usado para formatar valores de ponto flutuante em notação científica.

Usos comuns

O uso do método format é mais útil e versátil do que só formatar strings, indo muito mais além do que simplesmente construir mensagens, pode ser aplicado em diversas áreas da sua aplicação facilitando a implementação e a legibilidade do seu código, segue alguns exemplos de uso:

1 – Geração de Strings formatadas para Log:

Quando é necessário logar mensagens, que devem conter detalhes ou depuração, pode ser criar mensagens formatadas, facilitando a leitura e analise dos logs.

String mensagemLog = String.format("Erro ao processar o arquivo '%s'. Linha: %d, Coluna: %d", nomeArquivo, linha, coluna);
log.error(mensagemLog);

2 – Construção de SQL Dinâmico:

Quando é necessário criar consultas SQL dinâmica, podemos utilizar o método format para adicionar na consulta valores que podem ser variáveis.

String query = String.format("SELECT * FROM tabela WHERE nome = '%s' AND idade > %d", nome, idadeMinima);

Importante!
Sempre que estamos desenvolvendo uma aplicação é importante considerar a segurança em primeiro lugar, ciente disso muito cuidado quando form incorporar dados de entrada em queries SQL, essa pratica pode deixar a aplicação vulnerável a ataques do tipo SQL injection. Nesses casos é preferível utilizar métodos mais seguros para lidar com construções de queries dinâmicas, como o uso de funções presentes em ORMs.

3 – Mensagens de error personalizada:

Quando se está lançando exceções nativas da linguagem java, é interessante que a mensagem seja bem definida e explicativa, para a próxima camada do sistema, para isso podemos facilmente formatá-las adicionando informações varáveis.

throw new IllegalArgumentException(String.format("Valor inválido para o parâmetro '%s'. Deve ser entre %d e %d.", parametro, valorMinimo, valorMaximo));

4 – Geração de relatórios ou documentação:

Ao gerar relatórios ou documentos, que precisam de informação dinâmica, o método format pode ser usado para estruturar as informações de maneira mais legível e deixar com um aspecto mais amigável:

String relatorio = String.format("Total de Vendas: %.2f\nProdutos Vendidos: %d", totalVendas, quantidadeProdutos);

5 – Mensagens ao usuário:

Mensagens ao usuário muitas vezes requerem informações dinâmicas, como o próprio nome do usuário isso é facilmente implementado utilizando o método format:

String mensagemBoasVindas = String.format("Bem-vindo, %s!", nomeUsuario);

Conclusão

O método format oferece uma maneira poderosa e flexível de formatar strings, permitindo a incorporação de valores formatados, em conjunto com os especificadores de formato, garante um maior controle sobre os valores de saída, além de ser de fácil utilização é um recurso nativo da linguagem dispensando qualquer instalação de bibliotecas de terceiro e garantindo a máxima performance em suas aplicações.

Referências

• Documentação oficial do Java