(PHP 4, PHP 5, PHP 7, PHP 8)
pack — Empacota dados em uma string binária
Empacota os argumentos fornecidos em uma string binária de acordo com o formato especificado em format.
A ideia para esta função foi tirada do Perl e todos os códigos de formatação funcionam da mesma forma que no Perl. Entretando, há alguns códigos de formatação que não existem, como código "u" do Perl.
Observe que a distinção entre valores com e sem sinal somente afeta a função unpack(), enquanto que a função pack() fornece o mesmo resultado para códigos de formato com e sem sinal.
format A string format consistem em códigos de formado seguidos de um argumento repetidor opcional. O arrgumento repetidor pode ser um valor inteiro ou * para repetir até o final dos dados de entrada. Para a, A, h, H a contagem de repetição especifica quantos caractares de um argumento de dados são tomados, para @ é a posição absoluta onde colocar o próximo dado, para todo o restante a contagem de repetição especifica quantos argumentos de dados são consumidos e empacotados na string binária resultante.
Os formatos atualmente implementados são:
| Código | Descrição |
|---|---|
| a | String com bytes NUL à esquerda |
| A | String com espaços à esquerda |
| h | String hexadecimal, nibble menos significativo primeiro |
| H | String hexadecimal, nibble mais significativo primeiro |
| c | signed char |
| C | unsigned char |
| s | signed short (sempre 16 bits, ordem de bytes da máquina) |
| S | unsigned short (sempre 16 bits, ordem de bytes da máquina) |
| n | unsigned short (sempre 16 bits, ordem de bytes Big Endian) |
| v | unsigned short (sempre 16 bits, ordem de bytes Little Endian) |
| i | signed integer (tamanho e ordem de bytes dependentes da máquina) |
| I | unsigned integer (tamanho e ordem de bytes dependentes da máquina) |
| l | signed long (sempre 32 bits, ordem de bytes da máquina) |
| L | unsigned long (sempre 32 bits, ordem de bytes da máquina) |
| N | unsigned long (sempre 32 bits, ordem de bytes Big Endian) |
| V | unsigned long (sempre 32 bits, ordem de bytes Little Endian) |
| q | signed long long (sempre 64 bits, ordem de bytes da máquina) |
| Q | unsigned long long (sempre 64 bits, ordem de bytes da máquina) |
| J | unsigned long long (sempre 64 bits, ordem de bytes Big Endian) |
| P | unsigned long long (sempre 64 bits, ordem de bytes Little Endian) |
| f | float (representação e tamanho dependentes da máquina) |
| g | float (tamanho dependente da máquina, ordem de bytes Little Endian) |
| G | float (tamanho dependente da máquina, ordem de bytes Big Endian) |
| d | double (representação e tamanho dependentes da máquina) |
| e | double (tamanho dependente da máquina, ordem de bytes Little Endian) |
| E | double (tamanho dependente da máquina, ordem de bytes Big Endian) |
| x | byte NUL |
| X | Volta um byte |
| Z | String com bytes NUL à esquerda |
| @ | Preenche com bytes NUL até a posição absoluta |
valuesRetorna uma string binária contendo dados.
| Versão | Descrição |
|---|---|
| 8.0.0 | Esta função não mais retorna false em caso de falha. |
| 7.2.0 | Tipos float e double suportam tanto Big Endian quanto Little Endian. |
| 7.0.15,7.1.1 | Os códigos "e", "E", "g" e "G" foram adicionados para habilitar suporte a ordem de byte para float e double. |
Exemplo #1 Exemplo de pack()
<?php
$binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66);
?>A string binária resultante terá 6 bytes de comprimento e conterá a sequência de bytes 0x12, 0x34, 0x78, 0x56, 0x41, 0x42.
Observe que internamente o PHP armazena valores int como valores com sinal de tamanho dependente da máquina (o tipo long da linaguagem C). Literais inteiros e operações que resultam em números fora da faixa do tipo int serão armazenados como float. Ao empacotar estes floats como inteiros, eles primeiro são convertidos para o tipo inteiro. Isto pode ou não resultar no padrão de bytes desejado.
O caso mais relevante ocorre ao empacotar números sem sinal que poderiam ser representáveis pelo tipo int se eles fossem sem sinal. Em sistemas onde o tipo int tem 32 bits, a conversão normalmente resulta no mesmo padrão de byte como se o int fosse sem sinal (embora isso dependa das conversões de sem sinal para com sinal definidas pela implementação, conforme o padrão C). Em sistemas onte o tipo int tem 64 bits, o tipo float provavelmente não terá a mantissa grande o suficiente para representar o valor sem perda de precisão. Se estes sistemas também tiverem o tipo int nativo de 64 bits (a maioria dos sistemas tipo UNIX não têm), a única maneira de usar o formato I de empacotamento na faixa superior é criar valores negativos int com a mesma representação de bytes do valor sem sinal desejado.