Descrição

unpack(string $format, string $string, int $offset = 0): array|false

Desempacota uma srting binária em um array de acordo com o formato especificado em format.

Os dados desempacotados são armazenados em um array associativo. Para que isto seja feito, os diferentes códigos de formato devem ser nomeados e separados por uma barra /. Se um argumento repetidor estiver presente, cada chave do array terá um número de sequência atrás do nome fornecido.

Form feitas alterações para que esta função ficasse alinhada com a linguagem Perl:

O código "a" agora retém os bytes NULL ao final da string.
O código "A" agora remove todos os tipos de espaço ASCII do final da string (espaços, tabulações, novas linhas, retorno de carro e bytes NULL).
O código "Z" foi adicionado para strings com bytes NULL à esquerda, e remove bytes NULL à direita.

Parâmetros

format: Consulte a página da função pack() para uma explicação sobre os códigos de formatos.
string: Os dados empacotados.
offset: O deslocamento na string a partir de onde os dados serão desempacotados.

Valor Retornado

Retorna um array associativo contendo elementos desempacotados da string binária, ou false em caso de falha.

Registro de Alterações

Versão Descrição

7.2.0 Tipos float e double suportam Big Endian e Little Endian.

7.1.0 O parâmetro opcional offset foi adicionado.

Versão	Descrição
7.2.0	Tipos float e double suportam Big Endian e Little Endian.
7.1.0	O parâmetro opcional `offset` foi adicionado.

Exemplos

Exemplo #1 Exemplo de unpack()

<?php
$binarydata = "\x04\x00\xa0\x00";
$array = unpack("cchars/nint", $binarydata);
print_r($array);
?>

O exemplo acima produzirá:

Array
(
    [chars] => 4
    [int] => 160
)

Exemplo #2 Exemplo de unpack() com um repetidor

<?php
$binarydata = "\x04\x00\xa0\x00";
$array = unpack("c2chars/nint", $binarydata);
print_r($array);
?>

O exemplo acima produzirá:

Array
(
    [chars1] => 4
    [chars2] => 0
    [int] => 40960
)

Notas

Cuidado

Observe que internamente o PHP armazena com sinal os valores inteiros. Se um inteiro grande longo sem sinal for desempacotado, e for do mesmo tamanho que os valores armazenados internamente pelo PHP, o resultado será um número negativo mesmo que tenha sido especificado um desempacotamento sem sinal.

Cuidado

Se um elemento não for nomeado, seão usados índices numéricos iniciando em 1. Fique ciente que se houver mais de um elemento sem nome, alguns dados serão sobrescritos porque a numeração reiniciará a partir de 1 para cada elemento.

Exemplo #3 Exemplo de unpack() com chaves sem nome

<?php
$binarydata = "\x32\x42\x00\xa0";
$array = unpack("c2/n", $binarydata);
var_dump($array);
?>

O exemplo acima produzirá:

array(2) {
  [1]=>
  int(160)
  [2]=>
  int(66)
}

Observe que o primeiro valor especificado por c foi sobrescrito pelo primeiro valor de n especificado.

Veja Também

pack() - Empacota dados em uma string binária