fgetcsv.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 6501c09deda9a063eb47e05ca3cbb6d922b7eb49 Maintainer: seros Status: ready -->
<!-- Reviewed: no Maintainer: seros -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fgetcsv">
 <refnamediv>
  <refname>fgetcsv</refname>
  <refpurpose>Obtiene una línea de un puntero a un fichero y la analiza en busca de campos CSV</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>fgetcsv</methodname>
   <methodparam><type>resource</type><parameter>handle</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>length</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>delimiter</parameter><initializer>","</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>enclosure</parameter><initializer>'"'</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>escape</parameter><initializer>"\"</initializer></methodparam>
  </methodsynopsis>
  <para>
   Similar a <function>fgets</function> excepto que
   <function>fgetcsv</function> analiza la línea que lee para buscar campos en formato
   <acronym>CSV</acronym>, devolviendo un array que contiene los campos
   leídos.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>handle</parameter></term>
     <listitem>
      <para>
       Un puntero a un fichero abierto correctamente por
       <function>fopen</function>, <function>popen</function>, o
       <function>fsockopen</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>length</parameter></term>
     <listitem>
      <para>
       La longitud. Debe ser mayor que la línea más larga (en caracteres) encontrada en
       el fichero CSV (permitiendo caracteres fin de línea finales). Es
       opcional en PHP 5. Al omitir este parámetro (o estableciéndolo a 0 en PHP
       5.1.0 y posterior), la longitud máxima de línea no está limitada, lo que es
       ligeramente más lento.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>delimiter</parameter></term>
     <listitem>
      <para>
       El parámetro opcional <parameter>delimiter</parameter> establece el delimitador de campo (un sólo carácter).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>enclosure</parameter></term>
     <listitem>
      <para>
       El parámetro opcional <parameter>enclosure</parameter> establece el carácter circundante de cada campo (un sólo carácter).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>escape</parameter></term>
     <listitem>
      <para>
       El parámetro opcional <parameter>escape</parameter> establece el carácter de escape (un sólo carácter). Por defecto, es una barra invertida.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve un array indexado que contiene los campos leídos.
  </para>
  <note>
   <para>
    Una línea en blanco en un fichero CSV será devuelta como un array
    que comprende un único campo <type>null</type>, por lo que no será tratada
    como un error.
   </para>
  </note>
  &note.line-endings;
  <para>
   <function>fgetcsv</function> devuelve &null; si se proporciona un
   <parameter>handle</parameter> no válido, o &false; en los demás errores,
   incluido el final de fichero.
  </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.3.0</entry>
       <entry>
        Se añadió el parámetro <parameter>escape</parameter>
       </entry>
      </row>
      <row>
       <entry>5.1.0</entry>
       <entry>
        El parámetro <parameter>length</parameter> ahora es opcional.
        El valor predeterminado es <literal>0</literal>, significando sin límite de longitud.
        <!--
        Note to documentors: the length parameter was actually
        made optional in PHP 5.0.4 but didn't behave properly.
        Let's gloss over that here. :)
        -->
       </entry>
      </row>
      <row>
       <entry>4.3.5</entry>
       <entry>
        <function>fgetcsv</function> ahora es segura al trabajar con datos binarios
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Leer e imprimir el contenido completo de un fichero CSV</title>
    <programlisting role="php">
<![CDATA[
<?php
$fila = 1;
if (($gestor = fopen("test.csv", "r")) !== FALSE) {
    while (($datos = fgetcsv($gestor, 1000, ",")) !== FALSE) {
        $numero = count($datos);
        echo "<p> $numero de campos en la línea $fila: <br /></p>\n";
        $fila++;
        for ($c=0; $c < $numero; $c++) {
            echo $datos[$c] . "<br />\n";
        }
    }
    fclose($gestor);
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Esta función toma en cuenta los parámetros de configuraciones regionales. Si
    <varname>LANG</varname> es, p.ej., <literal>en_US.UTF-8</literal>, los ficheros
    codificados con un byte son leídos de forma errónea por esta función.
   </para>
  </note>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>str_getcsv</function></member>
    <member><function>explode</function></member>
    <member><function>file</function></member>
    <member><function>pack</function></member>
    <member><function>fputcsv</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
-->