Mostra uma string formatada

# vprintf

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

vprintf — Mostra uma string formatada

### Descrição

function vprintf(string `$format`, array `$values`): int

Motra valores de array como uma string formatada de acordo com `format` (que está descrito na documentação da função sprintf()).

Funciona como printf() mas aceita uma array de argumentos, ao invés de um número variável de argumentos.

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

  Sinalizador | 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.
  `'`(caractere) | Preenche o resultado com o caractere especificado.

  ##### 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.

  > 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.

  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).

  Aviso

  O especificador de tipo `c` ignora preenchimento e largura.

  Aviso

  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 o comprimento da string mostrada.

### 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 ValueError 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 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`.

### Exemplos

Exemplo #1 vprintf(): inteiros preenchidos com zero

    <?php
    vprintf("%04d-%02d-%02d", explode('-', '1988-8-1'));
    ?>

O exemplo acima produzirá:

    1988-08-01

### Veja Também

- printf() - Envia uma string formatada para a saída
- sprintf() - Retona uma string formatada
- fprintf() - Escreve uma string formatada para um fluxo
- 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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open