(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
vsprintf — Return a formatted string
Operates as sprintf() but accepts an array of arguments, rather than a variable number of arguments.
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
.
Um número inteiro seguido por um cifrão $
, para especificar qual o número de argumento a tratar na conversão.
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). |
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.
Um ponto .
opcionalmente seguido por um número inteiro ou *
, cujo significado depende do especificador:
e
, E
, f
e F
: este é o número de dígitos a serem impressos após o ponto decimal (por padrão, é 6). g
, G
, h
e H
: este é o número máximo de dígitos significativos a serem impressos. s
: atua como um ponto de corte, definindo um limite máximo de caracteres para a string. Nota: 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.
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). |
O especificador de tipo c
ignora preenchimento e largura.
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:
Tipo | Especificadores |
---|---|
string | s |
int | d , u , c , o , x , X , b |
float | e , E , f , F , g , G , h , H |
values
Return array values as a formatted string according to format
.
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.
Versão | Descrição |
---|---|
8.0.0 | Esta função não mais retorna false em caso de falha. |
8.0.0 | Lança uma exceção ValueError se o número de argumentos for zero; anteriormente esta função emitia um E_WARNING . |
8.0.0 | Lança uma exceção 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 uma exceção 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 uma exceção ValueError quando houver menos parâmetros que os necessários; anteriormente esta função emitia um E_WARNING . |
Exemplo #1 vsprintf(): zero-padded integers
<?php
print vsprintf("%04d-%02d-%02d", explode('-', '1988-8-1'));
?>
O exemplo acima produzirá:
1988-08-01