Retona uma string formatada

Descrição

sprintf(string $format, mixed ...$values): string

Retorna uma string produzida de acordo com a string de formatação informada no parâmetro format.

Parâmetros

format

A string de formato é composta de zero ou mais diretivas: caracteres comuns (excluindo %) que são copiados diretamente para o resultado e especificações de conversão, cada uma das quais resulta na busca de seu próprio parâmetro.

Uma especificação de conversão segue este protótipo: %[argnum$][flags][width][.precision]especificador.

Argnum

Um número inteiro seguido por um cifrão $, para especificar qual o número de argumento a tratar na conversão.

**Flags**
Flag	Descrição
`-`	Justificar à esquerda dentro da largura de campo especificada; A justificação à direita é o padrão.
`+`	Prefixa números positivos com um sinal de mais `+`; Por padrão, apenas números negativos são prefixados com um sinal negativo.
(espaço)	Preenche o resultado com espaços. Este é o padrão.
`0`	Preenche números com zeros apenas à esquerda. Com os especificadores `s`, também pode preencher com zeros à direita.
`'`(char)	Preenche o resultado com o caractere (char).

Width

Um número inteiro que define em quantos caracteres (mínimo) esta conversão deve resultar, ou *. Se * for usado, a largura será fornecida como um valor inteiro adicional precedendo aquele formatado pelo especificador.

Precision

Um ponto . opcionalmente seguido por um número inteiro ou *, cujo significado depende do especificador:

Para os especificadores e, E, f e F: este é o número de dígitos a serem impressos após o ponto decimal (por padrão, é 6).
Para os especificadores g, G, h e H: este é o número máximo de dígitos significativos a serem impressos.
Para o especificador s: atua como um ponto de corte, definindo um limite máximo de caracteres para a string.

Note: Se o ponto for especificado sem um valor explícito para precisão, 0 é assumido. Se * for usado, a precisão é fornecida como um valor inteiro adicional precedendo aquele formatado pelo especificador.

**Especificadores**
Especificador	Descrição
`%`	Um caractere literal de porcentagem. Nenhum argumento é necessário.
`b`	O argumento é tratado como um número inteiro e apresentado como um número binário.
`c`	O argumento é tratado como um número inteiro e apresentado como o caractere com aquele código ASCII.
`d`	O argumento é tratado como um número inteiro e apresentado como um número decimal (com sinal).
`e`	O argumento é tratado como notação científica (por exemplo, 1.2e+2).
`E`	Como o especificador `e`, mas usa letra maiúscula (por exemplo, 1.2E+2).
`f`	O argumento é tratado como um float e apresentado como um número de ponto flutuante (com reconhecimento da localidade).
`F`	O argumento é tratado como um float e apresentado como um número de ponto flutuante (sem reconhecimento da localidade).
`g`	Formato geral. Deixa P igual à precisão se for diferente de zero, 6 se a precisão for omitida, ou 1 se a precisão for zero. Então, se uma conversão com estilo E tivesse um expoente de X: Se P > X ≥ −4, a conversão é com estilo f e precisão P − (X + 1). Caso contrário, a conversão é com estilo e e precisão P − 1.
`G`	Como o especificador `g`, mas usa `E` e `f`.
`h`	Como o especificador `g`, mas usa `F`. Disponível a partir do PHP 8.0.0.
`H`	Como o especificador `g`, mas usa `E` e `F`. Disponível a partir do PHP 8.0.0.
`o`	O argumento é tratado como um número inteiro e apresentado como um número octal.
`s`	O argumento é tratado e apresentado como uma string.
`u`	O argumento é tratado como um número inteiro e apresentado como um número decimal sem sinal.
`x`	O argumento é tratado como um número inteiro e apresentado como um número hexadecimal (com letras minúsculas).
`X`	O argumento é tratado como um número inteiro e apresentado como um número hexadecimal (com letras maiúsculas).

Warning

O especificador de tipo c ignora preenchimento e largura.

Warning

Tentar usar uma combinação dos especificadores de string e largura com conjuntos de caracteres que requerem mais de um byte por caractere pode resultar em resultados inesperados.

As variáveis serão forçadas a um tipo adequado para o especificador:

**Tratamento de Tipos**
Tipo	Especificadores
string	`s`
int	`d`, `u`, `c`, `o`, `x`, `X`, `b`
float	`e`, `E`, `f`, `F`, `g`, `G`, `h`, `H`

values

Valor Retornado

Retorna uma string produzida de acordo com a string de formatação informada no parâmetro format.

Erros/Exceções

A partir do PHP 8.0.0, um erro ValueError será lançado se o número de argumentos for zero. Antes do PHP 8.0.0, um E_WARNING era emitido.

A partir do PHP 8.0.0, um erro ValueError será lançado se [width] for menor que zero ou maior que PHP_INT_MAX. Antes do PHP 8.0.0, um E_WARNING era emitido.

A partir do PHP 8.0.0, um erro ValueError será lançado se [precision] for menor que zero ou maior que PHP_INT_MAX. Antes do PHP 8.0.0, um E_WARNING era emitido.

A partir do PHP 8.0.0, um erro ArgumentCountError será lançado quando menos argumentos do que o necessário forem fornecidos. Antes do PHP 8.0.0, false era retornado e um E_WARNING era emitido.

Registro de Alterações

Versão	Descrição
8.0.0	Esta função não retorna mais `false` em caso de falha.
8.0.0	Lança um erro ValueError se o número de argumentos for zero; anteriormente, esta função emitia um `E_WARNING`.
8.0.0	Lança um erro ValueError se `[width]` for menor que zero ou maior que `PHP_INT_MAX`; anteriormente, esta função emitia um `E_WARNING`.
8.0.0	Lança um erro ValueError se `[precision]` for menor que zero ou maior que `PHP_INT_MAX`; anteriormente, esta função emitia um `E_WARNING`.
8.0.0	Lança um erro ArgumentCountError quando menos argumentos do que o necessário são fornecidos; anteriormente, esta função emitia um `E_WARNING`.

Exemplos

Example #1 Troca de ordem dos argumentos

A string de formatação suporta troca/numeração de argumentos.

<?php
$num = 5;
$location = 'árvore';

$format = 'Há %d macacos na %s';
echo sprintf($format, $num, $location);
?>

O exemplo acima produzirá:

Há 5 macacos na árvore

Entretanto imagine que uma string de formatação está sendo criada em um arquivo separado, normalmente porque ele poderia ser internacionalizado e seria re-escrito como:

<?php
$format = 'A %s contém %d macacos';
echo sprintf($format, $num, $location);
?>

Agora existe um problema. A ordem dos marcadores na string de formatação não corresponde à ordem dos argumentos no código. O código poderia ser deixado inalterado e na string de formatação poderiam ser indicados a que argumentos os marcadores se referem. A string de formatação seria então escrita assim:

<?php
$format = 'A %2$s contém %1$d macacos';
echo sprintf($format, $num, $location);
?>

Uma vantagem adicional é que os marcadores podem ser repetidos sem adicionar mais argumentos no código.

<?php
$format = 'A %2$s contém %1$d macacos.
           É uma bela %2$s cheia de %1$d macacos.';
echo sprintf($format, $num, $location);
?>

Ao usar troca ordem de argumentos, o especificador de posição n$ precisa vir imediatamente depois do símbolo de porcentagem (%) e antes de qualquer outro especificador, como mostrado abaixo.

Example #2 Especificando caractere de preenchimento

<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>

O exemplo acima produzirá:

......123
000000123

Example #3 Especificador de posição com outros especificadores

<?php
$format = 'A %2$s contém %1$04d macacos';
echo sprintf($format, $num, $location);
?>

O exemplo acima produzirá:

A árvore contém 0005 macacos

Example #4 sprintf(): inteiros preenchidos com zero à esquerda

<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>

Example #5 sprintf(): formatando moeda

<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
echo $money;
echo "\n";
$formatted = sprintf("%01.2f", $money);
echo $formatted;
?>

O exemplo acima produzirá:

123.1
123.10

Example #6 sprintf(): notação científica

<?php
$number = 362525200;

echo sprintf("%.3e", $number);
?>

O exemplo acima produzirá:

3.625e+8

Veja Também

printf() - Envia uma string formatada para a saída
fprintf() - Escreve uma string formatada para um fluxo
vprintf() - Mostra uma string formatada
vsprintf() - Retorna uma string formatada
vfprintf() - Escreve uma string formatada para um fluxo
sscanf() - Interpreta a entrada de uma string de acordo com um formato
fscanf() - Interpreta a leitura de um arquivo de acordo com um formato
number_format() - Formata um número com milhares agrupados
date() - Formata um timestamp Unix