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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 8f8fb2bd4d9819bec5b9c2c9ca835c884aac5ea7 Maintainer: yago Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.list" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>list</refname>
  <refpurpose>Asigna variables como si fuera un array</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>list</methodname>
   <methodparam><type>mixed</type><parameter>varname</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>varname</parameter></term>
     <listitem>
      <para>
       La variable.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve el array asignado.
  </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');

// Listando todas las variables
list($drink, $color, $power) = $info;
echo "El $drink es $color y la $power lo hace especial.\n";

// Listando algunas variables
list($drink, , $power) = $info;
echo "El $drink tiene $power.\n";

// O vamos a omitir solo la tercera
list( , , $power) = $info;
echo "Necesito $power!\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

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

?>

</table>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Uso de <function>list</function> dentro de list</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 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) "café"
  [1]=>
  string(5) "marrón"
  [0]=>
  string(6) "cafeína"
}
]]>
    </screen>
   </example>
  </para>
 </refsect1>
 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <para>
    <function>list</function> asigna los valores empezando por el parámetro más
    a la derecha. Si se utilizan variables simples, no hay que preocuparse. Pero
    si se usan array con índices normalmente se espera que el orden de los ínices
    en el array sea el mismo que se escribió en <function>list</function> de
    izquierda a derecha, el cual no es. Es asignado en el orden contrario.
   </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 se asume
    que el índice numérico empieza por 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
-->