Forum und email
Strings
PHP Manual

sprintf

(PHP 4, PHP 5)

sprintf — Retorna a string formatada

Descrição

string sprintf ( string $format [, mixed $args [, mixed $... ]] )

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

Parâmetros

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 opcional sinal especificador que indica (- ou +) pode ser usado no número. Por padrão, somente o sinal - é usado no número se ele é negativo. Este especificador força números positivos a ter o sinal +, foi adicionado no PHP 4.3.0.
  2. 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.
  3. 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.
  4. Um número opcional, um especificador de tamanho que diz quantos caracteres (mínimo) deve resultar desta conversão.
  5. Um especificador de precisão opcional que diz quantos digitos decimais devem ser mostrados para números de ponto flutuante. Quando usando este especificador na string, ele age como um ponto delimitador, definindo o máximo de caracteres limit para a string.

  6. 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.
    • e - o argumento é tratado como notação científica (e.g. 1.2e+2). O especificador de precisão indica o número de dígitos depois do ponto decimal desde o PHP 5.2.1. Em versões anteriores, ele pegava o número de dígitos significantes (ou menos).
    • 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 (do locale).
    • F - o argumento é tratado como um float, e mostrado como um número de ponto flutuante (não usado o locale). Disponível desde o PHP 4.3.10 e PHP 5.0.3.
    • 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).

A string de formato suporta argumentos com numeração/troca. Aqui está um exemplo:

Example#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:

Example#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:

Example#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:

Example#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);
?>

args

...

Valor Retornado

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

Histórico

Versão Descrição
4.0.6 Suporte para argumento numerado/troca foi adicionado

Exemplos

Example#5 printf(): vários exemplos

<?php
$n =  43951789;
$u = -43951789;
$c = 65; // ASCII 65 is 'A'

// notice the double %%, this prints a literal '%' character
printf("%%b = '%b'\n", $n); // binary representation
printf("%%c = '%c'\n", $c); // print the ascii character, same as chr() function
printf("%%d = '%d'\n", $n); // standard integer representation
printf("%%e = '%e'\n", $n); // scientific notation
printf("%%u = '%u'\n", $n); // unsigned integer representation of a positive integer
printf("%%u = '%u'\n", $u); // unsigned integer representation of a negative integer
printf("%%f = '%f'\n", $n); // floating point representation
printf("%%o = '%o'\n", $n); // octal representation
printf("%%s = '%s'\n", $n); // string representation
printf("%%x = '%x'\n", $n); // hexadecimal representation (lower-case)
printf("%%X = '%X'\n", $n); // hexadecimal representation (upper-case)

printf("%%+d = '%+d'\n", $n); // sign specifier on a positive integer
printf("%%+d = '%+d'\n", $u); // sign specifier on a negative integer
?>

O exemplo acima irá imprimir:

%b = '10100111101010011010101101'
%c = 'A'
%d = '43951789'
%e = '4.39518e+7'
%u = '43951789'
%u = '4251015507'
%f = '43951789.000000'
%o = '247523255'
%s = '43951789'
%x = '29ea6ad'
%X = '29EA6AD'
%+d = '+43951789'
%+d = '-43951789'

Example#6 printf(): especificadores de string

<?php
$s = 'monkey';
$t = 'many monkeys';

printf("[%s]\n",      $s); // standard string output
printf("[%10s]\n",    $s); // right-justification with spaces
printf("[%-10s]\n",   $s); // left-justification with spaces
printf("[%010s]\n",   $s); // zero-padding works on strings too
printf("[%'#10s]\n",  $s); // use the custom padding character '#'
printf("[%10.10s]\n", $t); // left-justification but with a cutoff of 10 characters
?>

O exemplo acima irá imprimir:

[monkey]
[    monkey]
[monkey    ]
[0000monkey]
[####monkey]
[many monke]

Example#7 sprintf(): inteiros prenchidos com zero

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

Example#8 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"
?>

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

<?php
$number = 362525200;

echo sprintf("%.3e", $number); // outputs 3.625e+8
?>

Veja também

Strings
PHP Manual