doc-fr/reference/pdo_sqlite/PDO/sqliteCreateAggregate.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 9e0f03ac354d797d1d16c0fcc1663e5e170f2727 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="pdo.sqlitecreateaggregate" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>PDO::sqliteCreateAggregate</refname>
  <refpurpose>
   Référence une fonction agrégative définie par l'utilisateur pour une utilisation dans les requêtes SQL
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>bool</type><methodname>PDO::sqliteCreateAggregate</methodname>
   <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
   <methodparam><type>callable</type><parameter>step_func</parameter></methodparam>
   <methodparam><type>callable</type><parameter>finalize_func</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>num_args</parameter></methodparam>
  </methodsynopsis>
  &warn.experimental.func;
  <para>
   Cette méthode est similaire à <xref linkend="pdo.sqlitecreatefunction"
   /> à l'exception qu'elle référence les fonctions qui peuvent être utilisées pour calculer un 
   résultat agrégé à travers toutes les lignes d'une requête.
  </para>
  <para>
   La différence entre cette méthode  et <xref
   linkend="pdo.sqlitecreatefunction" /> est que deux fonctions sont
   requises pour gérer les agrégation.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>function_name</parameter></term>
     <listitem>
      <para>
       Le nom de la fonction utilisée dans les requêtes SQL.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>step_func</parameter></term>
     <listitem>
      <para>
       Fonction de rappel appelée pour chaque ligne dans le jeu de résultats. Votre
       fonction PHP devrait accumuler le résultat et stocker son contexte d'agrégation.
      </para>
      <para>
       Cette fonction doit être définie comme :
       <methodsynopsis>
        <type>mixed</type><methodname><replaceable>step</replaceable></methodname>
        <methodparam><type>mixed</type><parameter>context</parameter></methodparam>
        <methodparam><type>int</type><parameter>rownumber</parameter></methodparam>
        <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
        <methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
       </methodsynopsis>
       <variablelist>
        <varlistentry>
         <term><parameter>context</parameter></term>
         <listitem>
          <para>
           &null; pour la première ligne ; sur les lignes suivantes ceci aura la valeur
           qui a été précedement retourné par la fonction step ; vous devriez utiliser
           ceci pour maintenir l'état d'aggregation.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>rownumber</parameter></term>
         <listitem>
          <para>
           Le numéro de ligne courante.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>value</parameter></term>
         <listitem>
          <para>
           Le premier argument à passer à l'agrégateur.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>values</parameter></term>
         <listitem>
          <para>
           Arguments supplémentaires à passer à l'agrégateur.
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
       La valeur retournée de cette fonction sera utilisée comme argument
       <parameter>context</parameter> lors du prochain appel d'une fonction
       d'étape ou finale.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>finalize_func</parameter></term>
     <listitem>
      <para>
       Fonction de rappel pour agréger les "étapes" de données de chaque ligne.
       Une fois que toutes les lignes ont été traitées, la fonction sera appelée,
       prendra les données du contexte d'agrégation et retournera le résultat.
       La fonction de rappel doit retourner un type compris 
       par SQLite (c'est-à-dire <link 
       linkend="language.types.intro">un type scalaire</link>).
      </para>
      <para>
       Cette fonction doit être définie comme :
       <methodsynopsis>
        <type>mixed</type><methodname><replaceable>fini</replaceable></methodname>
        <methodparam><type>mixed</type><parameter>context</parameter></methodparam>
        <methodparam><type>int</type><parameter>rowcount</parameter></methodparam>
       </methodsynopsis>
       <variablelist>
        <varlistentry>
         <term><parameter>context</parameter></term>
         <listitem>
          <para>
           Contient la valeur de retour du tout dernier appel à la fonction step.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>rowcount</parameter></term>
         <listitem>
          <para>
           Contient le nombre de lignes sur lesquelles l'agrégat a été effectué.
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
       La valeur de retour de cette fonction sera utilisée comme valeur de retour pour
       l'agrégation.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>num_args</parameter></term>
     <listitem>
      <para>
       Conseil à l'analyseur SQLite si la fonction de rappel accepte un nombre
       prédéterminé d'arguments.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple d'agrégation avec une fonction max_length</title>
    <programlisting role="php">
<![CDATA[
<?php
$data = array(
   'one',
   'two',
   'three',
   'four',
   'five',
   'six',
   'seven',
   'eight',
   'nine',
   'ten',
   );
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($data as $str) {
    $insert->execute(array($str));
}
$insert = null;

function max_len_step($context, $rownumber, $string) 
{
    if (strlen($string) > $context) {
        $context = strlen($string);
    }
    return $context;
}

function max_len_finalize($context, $rownumber) 
{
    return $context === null ? 0 : $context;
}

$db->sqliteCreateAggregate('max_len', 'max_len_step', 'max_len_finalize');

var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Dans cet exemple, on crée une fonction agrégative qui va calculer la
   longueur de la plus grande chaîne de caractères dans une des colonnes de la
   table. Pour chaque ligne, la fonction <literal>max_len_step</literal> est
   appelée et le paramètre <literal>$context</literal> est passé. Le
   paramètre de contexte est comme n'importe quelle autre variable PHP et
   doit être fixé pour contenir un tableau ou même, un objet. Dans cet exemple,
   nous l'utilisons pour contenir la taille maximale que nous avons vu jusqu'à
   présent ; si le paramètre <literal>$string</literal> a une grandeur plus
   importante que celle courante, on met à jour le contexte pour contenir cette
   nouvelle taille maximale.
  </para>
  <para>
   Une fois que toutes les lignes ont été traitées, SQLite appelle la fonction
   <literal>max_len_finalize</literal> pour déterminer le résultat agrégatif.
   Ici, nous pourrions effectuer des calculs basés sur les données trouvées
   dans <literal>$context</literal>. Dans notre exemple simple, nous avons
   calculé le résultat comme si la requête progressait, alors que nous avons
   simplement besoin de retourner la valeur de contexte.
  </para>
  <tip>
   <para>
    Il n'est PAS recommandé d'enregistrer une copie des valeurs dans le contexte
    pour finalement les traiter. Dans ce cas, SQLite utiliserait beaucoup trop
    de mémoire pour traiter la requête - imaginez la quantité de mémoire nécessaire
    si un million de lignes étaient enregistrées en mémoire, sachant que chaque ligne
    contient une chaîne de caractères (32 octets par chaîne).
   </para>
  </tip>
  <tip>
   <para>
    Vous pouvez utiliser <xref linkend="pdo.sqlitecreatefunction" /> et
    <xref linkend="pdo.sqlitecreateaggregate" /> pour surcharger les
    fonctions natives de SQLite.
   </para>
  </tip>
 </refsect1>


 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><xref linkend="pdo.sqlitecreatefunction" /></member>
    <member><function>sqlite_create_function</function></member>
    <member><function>sqlite_create_aggregate</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
-->