unpack.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 55929e29ac7535345c9f38ad3f703c6f3cd2cc59 Maintainer: chuso Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.unpack" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>unpack</refname>
  <refpurpose>Desempaqueta datos de una cadena binaria</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>unpack</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam><type>string</type><parameter>data</parameter></methodparam>
  </methodsynopsis>
  <para>
   Desempaqueta desde una cadena binaria a una matriz de acuerdo a
   <parameter>format</parameter>.
  </para>
  <para>
   Los datos desempaquetados son almacenados en una matriz asociativa. Para
   lograr esto es necesario nombrar los diferentes códigos de formato y
   separarlos con una barra /. Si estuviera presente un parámetro repetidor,
   cada una de las claves de la matriz tendría un número de secuencia tras
   el valor establecido.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       Vea <function>pack</function> para una explicación de los códigos de
       formato.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>data</parameter></term>
     <listitem>
      <para>
       Los datos empaquetados.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve una matriz asociativa que contiene los elementos desempaquetados
   de la cadena binaria.
  </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>5.5.0</entry>
       <entry>
        <para>
         Cambios realizados para poner esta función en línea con Perl:
        </para>
        <para>
         El código "a" ahora guarda bytes NULL sobrantes de cola.
        </para>
        <para>
         El código "A" ahora elimina todos los espacios en blanco ASCII sobrantes de cola
         (espacios, tabulaciones, nuevas líneas, retorno de carro, y bytes NULL).
        </para>
        <para>
         Se añadió en código "Z" para cadenas rellenadas con NULL, y elimina los bytes NULL
         sobrantes de cola.
        </para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1><!-- }}} -->
 
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo de <function>unpack</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$datosbinarios = "\x04\x00\xa0\x00";
$matriz = unpack("cchars/nint", $datosbinarios);
?>
]]>
    </programlisting>
    <para>
     La matriz resultante contendrá las entradas "chars" con el valor
     <literal>4</literal> e "int" con el valor <literal>160</literal>.
    </para>
   </example>
  </para>
  
  <para>
   <example>
    <title>Ejemplo de <function>unpack</function> con un repetidor</title>
    <programlisting role="php">
<![CDATA[
<?php
$datosbinarios = "\x04\x00\xa0\x00";
$matriz = unpack("c2chars/nint", $datosbinarios);
?>
]]>
    </programlisting>
    <para>
     La matriz resultante contendrá las entradas "chars1",
     "chars2" e "int".
    </para>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <caution>
   <para>
    Note que PHP almacena internamente los valores enteros como valores con
    signo. Si desempaqueta un entero largo sin signo y es del mismo tamaño
    que los valores almacenados internamente por PHP, el resultado será un
    número negativo incluso si se especifica un valor sin signo al
    desempaquetar.
   </para>
  </caution>
  <caution>
   <para>
    Tenga en cuenta que si un elemento no tiene nombre, se usará una cadena vacía.
    Si hubiera más de un elemento sin nombre, esto significaría que se
    sobrescribirían algunos datos, ya que sus claves coincidirían, como ocurre en:
   </para>
   <para>
    <example>
     <title>Ejemplo <function>unpack</function> con claves sin nombre</title>
     <programlisting role="php">
<![CDATA[
<?php
$datosbinarios = "\x32\x42\x00\xa0";
$matriz = unpack("c2/n", $datosbinarios);
var_dump($matriz);
?>
]]>
     </programlisting>
     <para>
      La matriz resultante contendrá las entradas "1" con el valor
      <literal>160</literal> y "2" con <literal>66</literal>. El
      primer valor del especificador <literal>c</literal> quedaría
      sobrescrito por el primer valor del 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>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->