archived-doc-es/reference/array/functions/list.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 674412f7601a477e463d67fbb4eaed0ec7fdab15 Maintainer: seros Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.list" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>list</refname>
  <refpurpose>Asignar variables como si fueran un array</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>list</methodname>
   <methodparam><type>mixed</type><parameter>var1</parameter></methodparam>
   <methodparam rep="repeat" choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
  </methodsynopsis>
  <para>
   Al igual que <function>array</function>, no es realmente una función,
   es un constructor del lenguaje. <function>list</function> se utiliza
   para asignar una lista de variables en una sola operación.  
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>var1</parameter></term>
     <listitem>
      <para>
       Una variable.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve el array asignado.
  </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.0.0</entry>
       <entry>
        <link linkend="migration70.incompatible.variable-handling.list.order">
         El orden en el que se realizan las operaciones de asignación ha
         cambiado.
        </link>
       </entry>
      </row>
      <row>
       <entry>7.0.0</entry>
       <entry>
        <link linkend="migration70.incompatible.variable-handling.list.empty">
         Las expresiones de <function>list</function> ya no pueden estar completamente
         vacías.
        </link>
       </entry>
      </row>
      <row>
       <entry>7.0.0</entry>
       <entry>
        <link linkend="migration70.incompatible.variable-handling.list.string">
         Los strings ya no pueden ser desempaquetados.
        </link>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplos de <function>list</function></title>
    <programlisting role="php">
<![CDATA[
<?php

$info = array('café', 'marrón', 'cafeína');

// Enumerar todas las variables
list($bebida, $color, $energía) = $info;
echo "El $bebida es $color y la $energía lo hace especial.\n";

// Enumerar algunas de ellas
list($bebida, , $energía) = $info;
echo "El $bebida tiene $energía.\n";

// U omitir solo la tercera
list( , , $energía) = $info;
echo "Necesito $energía!\n";

// list() no funciona con cadenas
list($bar) = "abcde";
var_dump($bar); // NULL
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Un ejemplo del uso de <function>list</function></title>
    <programlisting role="php">
<![CDATA[
<table>
 <tr>
  <th>Nombre del empleado</th>
  <th>Salario</th>
 </tr>

<?php

$resultado = $pdo->query("SELECT id, nombre, salario FROM empleados");
while (list($id, $nombre, $salario) = $resultado->fetch(PDO::FETCH_NUM)) {
    echo " <tr>\n" .
          "  <td><a href=\"info.php?id=$id\">$nombre</a></td>\n" .
          "  <td>$salario</td>\n" .
          " </tr>\n";
}

?>

</table>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Empleo de <function>list</function> anidados</title>
    <programlisting role="php">
<![CDATA[
<?php

list($a, list($b, $c)) = array(1, array(2, 3));

var_dump($a, $b, $c);

?>
]]>
    </programlisting>
    <screen>
<![CDATA[
int(1)
int(2)
int(3)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Uso de <function>list</function> con índices de array</title>
    <programlisting role="php">
<![CDATA[
<?php

$info = array('café', 'marrón', 'cafeína');

list($a[0], $a[1], $a[2]) = $info;

var_dump($a);

?>
]]>
    </programlisting>
    <para>
     Muestra la siguiente salida (nótese el orden de los elementos comparado
     con el orden escrito en la sintaxis de <function>list</function>):
    </para>
    <screen>
<![CDATA[
array(3) {
  [2]=>
  string(8) "cafeína"
  [1]=>
  string(7) "marrón"
  [0]=>
  string(5) "café"
}
]]>
    </screen>
   </example>
  </para>
 </refsect1>
 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <para>
    En PHP 5, <function>list</function> asigna los valores empezando desde el
    parámetro primero derecho. En PHP 7, <function>list</function> empieza desde el
    parámetro primero izquierdo.
   </para>
   <para>
    Si se emplean variables sencillas, esto no debe ser un problema. Pero
    se en emplean arrays con índices, normalmente se espera que el orden de los
    índices sea el mismo que el escrito en <function>list</function>,
    de izquierda a derecha, no siendo el este el caso en PHP 5, ya que se asignan en
    orden inverso.
   </para>
   <para>
    En términos generales, se aconseja evitar depender de un orden específico
    de operación debido a que este podría cambiar de nuevo en el futuro.
   </para>
  </warning>
  <warning>
   <para>
    La modificación del array durante la ejecución de <function>list</function> (p.ej.
    usando <literal>list($a, $b) = $b</literal>) resultará en un comportamiento indefinido.
   </para>
  </warning>
  <note>
   <para>
    <function>list</function> solo funciona con arrays numéricos y asume
    que los índices numéricos empiezan en 0.
   </para>
  </note>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>each</function></member>
    <member><function>array</function></member>
    <member><function>extract</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
-->