Manual do PHP
Anterior |  | Próxima

# sprintf

(PHP 3, PHP 4 , PHP 5)

sprintf -- Retorna uma string formatada

## Descrição

string sprintf ( string format [, mixed args] )

Retorna uma string produzida de acordo com a string de formatação format.

A string e formatação é composta de zero ou mais diretivas: caracteres normais (excluindo %) que são copiados diretamente para o resultado, e especificações de conversão, cada um dos quais resulta em obter o seu próprio parâmetro. Isto se aplica para sprintf() e printf().

Cada especificação de conversão consiste em um símbolo de porcento (%), seguido por um ou mais destes elementos em ordem:

1. Um especificador de prenchimento opcional que diz qual caractere será usado para prencher o resultado para o tamanho certo. Isto pode ser um espaço ou 0 (zero character). O padrão é prencher com espaços. Um caractere alternativo de prenchimento pode ser especificado colocando uma aspa simples (') antes. Veja os exemplos abaixo.

2. Um especificador de alinhamento opcional que diz se o resultado deve ser alinhado a esquerda ou a direita. O padrão é alinhar a direita; um caractere - fará com que seja alinhado a esquerda.

3. Um número opcional, um especificador de tamanho que diz quantos caracteres (mínimo) deve resultar desta conversão.

4. Um especificador de precisão opcional que diz quantos digitos decimais devem ser mostrados para números de ponto flutuante. Esta opção não tem efeito para outros tipos que não sejam float. (Outra função útil para formatar números é number_format().)

5. Um especificador de tipo que diz que o argumento deve ser tratado como do tipo. Os tipos possivéis são:

   % - Um caractere porcento. Não é requerido neenhum argumento.
   b - O argumento é tratado com um inteiro, e mostrado como um binário.
   c - O argumento é tratado como um inteiro, e mostrado como o caractere ASCII correspondente.
   d - O argumento é tratado como um inteiro, e mostrado como um número decimal com sinal.
   u - O argumento é tratado com um inteiro, e mostrado como um número decimal sem sinal.
   f - O argumento é tratado como um float, e mostrado como um número de ponto flutuante.
   o - O argumento é tratado com um inteiro, e mostrado como un número octal.
   s - O argumento é tratado e mostrado como uma string.
   x - O argumento é tratado como um inteiro, e mostrado como um número hexadecimal (com as letras minúsculas).
   X - O argumento é tratado como um inteiro, e mostrado como um número hexadecimal (com as letras maiúsculas).

Apartir do PHP 4.0.6 a string de formatação suporta numeração/troca. Aqui esta um exemplo:

Exemplo 1. Troca de argumentos
`<?php $format = "There are %d monkeys in the %s"; printf($format,$num,$location); ?>`

Este deve mostrar, "There are 5 monkeys in the tree". Mas imagine que nós estejamos criando a string de formatação em um arquivo separado, normalmente para internacionalizar e rescrevemos como:

Exemplo 2. Troca de argumentos
`<?php $format = "The %s contains %d monkeys"; printf($format,$num,$location); ?>`

Agora nós temos um problema. A ordem dos argumentos na string de formatação não combina com os argumentos no código. Nós gostariamos de deixar o código como esta e simplesmente indicar na string de formatação quais argumentos pertencem aonde. Podemos escrever a string de formatação assim:

Exemplo 3. Troca de argumento
`<?php $format = "The %2\$s contains %1\$d monkeys"; printf($format,$num,$location); ?>`

Um beneficio adicional disto é ue você pode repetir os especificadores de conversão sem adicionar mais argumentos em seu código. Por exemplo:

Exemplo 4. Troca de argumento
`<?php $format = "The %2\$s contains %1\$d monkeys. That's a nice %2\$s full of %1\$d monkeys."; printf($format, $num, $location); ?>`

Veja também printf(), sscanf(), fscanf(), vsprintf() e number_format().

## Examplos

Exemplo 5. sprintf(): inteiros prenchidos com zero
`<?php $isodate = sprintf("%04d-%02d-%02d", $year, $month, $day); ?>`

Exemplo 6. sprintf(): formatando dinheiro
`<?php $money1 = 68.75; $money2 = 54.35; $money = $money1 + $money2; // echo $money irá mostrar "123.1"; $formatted = sprintf("%01.2f", $money); // echo $formatted irá mostrar "123.10" ?>`

Anterior | Principal | Próxima
soundex | Acima | sscanf