<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.unpack" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>unpack</refname>

<refpurpose>Desempaqueta datos desde una cadena binaria</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>array</type><type>false</type></type><methodname>unpack</methodname>

<methodparam><type>string</type><parameter>format</parameter></methodparam>

<methodparam><type>string</type><parameter>string</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>

</methodsynopsis>

<para>

Desempaqueta los datos <parameter>data</parameter>

desde una cadena binaria con el formato <parameter>format</parameter>.

</para>

<para>

Los datos desempaquetados se almacenan en un

array. Para ello, debe asignarse un nombre a cada

formato utilizado y separarlos con una barra (/). Si

se proporciona un argumento de repetición, entonces cada una de

las claves del array tendrá un número de secuencia detrás del

nombre proporcionado.

</para>

<para>

Se han realizado modificaciones para alinear el comportamiento

de esta función con Perl :

<simplelist>

<member>

El código "a" ya no elimina los bytes NULL finales.

</member>

<member>

El código "A" ahora elimina todos los espacios en blanco ASCII finales

(espacio, tabulación, nuevas líneas, retorno de carro, y bytes NULL).

</member>

<member>

Se ha añadido el código "Z" para las cadenas rellenas con caracteres

NULL, y elimina los bytes NULL finales.

</member>

</simplelist>

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>format</parameter></term>

<listitem>

<para>

Consulte la función <function>pack</function> para una explicación de los códigos de formato.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>string</parameter></term>

<listitem>

<para>

Los datos empaquetados.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>offset</parameter></term>

<listitem>

<para>

La posición donde comenzar el desempaquetado.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Devuelve un array asociativo que contiene los elementos desempaquetados

de una cadena binaria, &return.falseforfailure;.

</para>

</refsect1>

<refsect1 role="changelog"><!-- {{{ -->

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>7.2.0</entry>

<entry>

Los tipos <type>float</type> y <type>double</type> soportan tanto la orientación Big Endian como Little Endian.

</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

Se ha añadido el argumento opcional <parameter>offset</parameter>.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1><!-- }}} -->

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Ejemplo con <function>unpack</function></title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</para>

<para>

<example>

<title>Ejemplo con <function>unpack</function> y un argumento de repetición</title>

<programlisting role="php">

<![CDATA[

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<caution>

<para>

Debe tenerse en cuenta que PHP maneja los valores internamente

en forma firmada. Si se desempaqueta

un valor que es tan grande como el tamaño utilizado

internamente por PHP, el resultado será

un número negativo, incluso si se ha

desempaquetado con la opción <literal>"no firmado"</literal>.

</para>

</caution>

<caution>

<para>

Si no se nombra un elemento, se utilizan los índices numéricos a partir de

<literal>1</literal>. Tenga en cuenta que si tiene más de un

elemento sin nombre, algunos datos se sobrescriben porque la numeración

se reinicia a partir de <literal>1</literal> para cada elemento.

</para>

<para>

<example>

<title>Ejemplo con <function>unpack</function> con claves no nombradas</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

<para>

Observe que el primer

valor desde el especificador <literal>c</literal> es sobrescrito

por el primer valor desde el especificador <literal>n</literal>.

</para>

</example>

</para>

</caution>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>pack</function></member>

</simplelist>

</para>

</refsect1>

</refentry>