archived-doc-it/reference/filesystem/functions/fgetcsv.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 0a3648a71895f35f570573d31ca9e003786aa993 Maintainer: pastore Status: working -->
<!-- CREDITS: cortesi -->
<!-- CREDITS: fernando -->
<refentry xml:id="function.fgetcsv" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>fgetcsv</refname>
  <refpurpose>Prende una riga da un puntatore a file e l'analizza in cerca di campi CSV</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>fgetcsv</methodname>
   <methodparam><type>resource</type><parameter>stream</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>separator</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>
   Simile a <function>fgets</function> eccetto per il fatto che
   <function>fgetcsv</function> analizza le riga letta alla ricerca di campi
   in formato <acronym>CSV</acronym> e restituisce un array contenente i campi
   letti.
  </para>
  <note>
   <simpara>
    Le impostazioni locali vengono prese in considerazione da questa funzione.
    Ad esempio, i dati codificati in determinati formati a byte singolo potrebbero essere analizzati
    in modo errato se <constant>LC_CTYPE</constant> è impostato su
    <literal>en_US.UTF-8</literal>.
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>stream</parameter></term>
     <listitem>
      <para>
       Un puntatore valido a un file che punta a un file aperto con successo da
       <function>fopen</function>, <function>popen</function> o
       <function>fsockopen</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>length</parameter></term>
     <listitem>
      <para>
       Deve essere più grande della riga più lunga (in caratteri) per essere trovato nel
       file CSV (tenendo conto dei caratteri di fine riga). Altrimenti, la riga
       viene suddivisa in blocchi di <parameter>length</parameter> caratteri,
       a meno che la divisione non avvenga all'interno di una chiusura.
      </para>
      <para>
       Se si omette questo parametro (o lo si imposta su 0,
       o &null; in PHP 8.0.0 o versioni successive), la lunghezza massima della riga non è limitata,
       ma è leggermente più lenta.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>separator</parameter></term>
     <listitem>
      <para>
       Il parametro <parameter>separator</parameter> imposta il separatore di campo.
       Deve essere un carattere a byte singolo.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>enclosure</parameter></term>
     <listitem>
      <para>
       Il parametro <parameter>enclosure</parameter> imposta il carattere di chiusura del campo.
       Deve essere un carattere a byte singolo.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>escape</parameter></term>
     <listitem>
      <para>
       Il parametro <parameter>escape</parameter> imposta il carattere di escape.
       Deve essere un carattere a byte singolo o la stringa vuota.
       La stringa vuota (<literal>""</literal>) disabilita il meccanismo di escape proprietario.
      </para>
      <warning xml:id="function.fgetcsv..warn.escape.parameter">
       <simpara>
        Nel flusso di input, il carattere <parameter>enclosure</parameter>
        può sempre essere sottoposto a escape raddoppiandolo all’interno di una stringa tra virgolette,
        producendo un singolo carattere <parameter>enclosure</parameter>
        nel risultato analizzato.
        Il carattere <parameter>escape</parameter> funziona in modo diverso:
        se una sequenza di caratteri <parameter>escape</parameter> e
        <parameter>enclosure</parameter> appare nell’input,
        entrambi i caratteri saranno presenti nel risultato analizzato.
        Quindi, per i parametri predefiniti, una riga CVS come
        <literal>"a""b","c\"d"</literal> avrà i campi analizzati come
        <literal>a"b</literal> e <literal>c\"d</literal>, rispettivamente.
       </simpara>
      </warning>
      <warning>
       <simpara>
        A partire da PHP 8.4.0, dipendere dal valore predefinito di
        <parameter>escape</parameter> è deprecato.
        Deve essere fornito esplicitamente, sia per posizione che mediante l'uso
        dei <link linkend="functions.named-arguments">named arguments</link>.
       </simpara>
      </warning>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  &warning.csv.escape-parameter;
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Restituisce un array indicizzato contenente i campi letti in caso di successo, &return.falseforfailure;.
  </para>
  <note>
   <para>
    Una riga vuota in un file CSV verrà restituita come un array
    contenente un singolo campo <type>null</type> e non sarà trattata
    come un errore.
   </para>
  </note>
  &note.line-endings;
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   Genera un <exceptionname>ValueError</exceptionname> se
   <parameter>separator</parameter> o <parameter>enclosure</parameter>
   non sono lunghi un byte.
  </simpara>
  <simpara>
   Genera un <exceptionname>ValueError</exceptionname> se
   <parameter>escape</parameter> non è lungo un byte o è una stringa vuota.
  </simpara>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.4.0</entry>
       <entry>
        L'affidamento sul valore predefinito di <parameter>escape</parameter> è ora
        deprecato.
       </entry>
      </row>
      <row>
       <entry>8.3.0</entry>
       <entry>
        Viene restituita una stringa vuota invece di una stringa con un singolo
        byte null per l'ultimo campo se contiene solo una chiusura
        non terminata.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        <parameter>length</parameter> è ora nullable.
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
        Il parametro <parameter>escape</parameter> ora accetta anche una stringa
        vuota per disabilitare il meccanismo di escape proprietario.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Legge e stampa il contenuto di un file CSV</title>
    <programlisting role="php">
<![CDATA[
<?php
$row = 1;
if (($handle = fopen("test.csv", "r")) !== FALSE) {
    while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
        $num = count($data);
        echo "<p> $num campi sulla riga $row: <br /></p>\n";
        $row++;
        for ($c=0; $c < $num; $c++) {
            echo $data[$c] . "<br />\n";
        }
    }
    fclose($handle);
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>fputcsv</function></member>
   <member><function>str_getcsv</function></member>
   <member><methodname>SplFileObject::fgetcsv</methodname></member>
   <member><methodname>SplFileObject::fputcsv</methodname></member>
   <member><methodname>SplFileObject::setCsvControl</methodname></member>
   <member><methodname>SplFileObject::getCsvControl</methodname></member>
   <member><function>explode</function></member>
   <member><function>file</function></member>
   <member><function>pack</function></member>
  </simplelist>
 </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
-->