<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: 51610360d58ed09bc9d1312f419057c0d1d1a998 Maintainer: sergey Status: ready -->

<!-- Reviewed: no -->

<refentry xml:id="pdo-sqlite.createaggregate" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>Pdo\Sqlite::createAggregate</refname>

<refpurpose>

Регистрирует агрегирующую пользовательскую функцию для использования в SQL-выражениях

</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis role="Pdo\\Sqlite">

<modifier>public</modifier> <type>bool</type><methodname>Pdo\Sqlite::createAggregate</methodname>

<methodparam><type>string</type><parameter>name</parameter></methodparam>

<methodparam><type>callable</type><parameter>step</parameter></methodparam>

<methodparam><type>callable</type><parameter>finalize</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>numArgs</parameter><initializer>-1</initializer></methodparam>

</methodsynopsis>

<simpara>

Метод похож на <methodname>Pdo\Sqlite::createFunction</methodname>, за исключением того,

что он регистрирует функции, которые могут быть использованы для вычисления результата,

агрегированного по всем строкам запроса.

</simpara>

<simpara>

Ключевое отличие метода от <methodname>Pdo\Sqlite::createFunction</methodname> заключается в том,

что для управления агрегатом требуется две функции.

</simpara>

<tip>

<simpara>

С помощью метода можно переопределить собственные SQL-функции.

</simpara>

</tip>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<variablelist>

<varlistentry>

<term><parameter>name</parameter></term>

<listitem>

<simpara>

Имя функции, используемой в SQL-выражениях.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>step</parameter></term>

<listitem>

<simpara>

Callback-функция, вызываемая для каждой строки набора результатов.

Callback-функция должна накапливать результат и сохранять его в контексте агрегации.

</simpara>

<para>

Сигнатура функции должна быть определена как:

<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>

<simpara>

&null; для первой строки; в последующих строках это будет значение,

которое ранее было возвращено функцией step;

это необходимо использовать для поддержания агрегатного состояния.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>rownumber</parameter></term>

<listitem>

<simpara>

Номер текущей строки.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>value</parameter></term>

<listitem>

<simpara>

Первый аргумент, передаваемый агрегату.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>values</parameter></term>

<listitem>

<simpara>

Дополнительные аргументы, передаваемые агрегату.

</simpara>

</listitem>

</varlistentry>

</variablelist>

Возвращаемое значение функции будет использовано

в качестве аргумента <parameter>context</parameter>

при следующем вызове функций step или finalize.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>finalize</parameter></term>

<listitem>

<simpara>

Callback-функция для агрегации «пошаговых» данных из каждой строки.

После обработки всех строк будет вызвана функция,

которая должна получить данные из контекста агрегации и вернуть результат.

Callback-функция должна возвращать тип, понятный SQLite

(например, <link linkend="language.types.intro">скалярный тип</link>).

</simpara>

<para>

Сигнатура функции должна быть определена как:

<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>

Хранит значение, возвращённое при последнем вызове функции step.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>rowcount</parameter></term>

<listitem>

<para>

Указывает количество строк, по которым было выполнено агрегирование.

</para>

</listitem>

</varlistentry>

</variablelist>

Возвращаемое значение функции будет использоваться

в качестве возвращаемого значения для агрегата.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>numArgs</parameter></term>

<listitem>

<simpara>

Подсказка парсеру SQLite, если callback-функция

принимает заданное количество аргументов.

</simpara>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<simpara>

&return.success;

</simpara>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<example>

<title>Пример использования метода <methodname>Pdo\Sqlite::createAggregate</methodname></title>

<simpara>

В этом примере создаётся пользовательская агрегатная функция

с именем <literal>max_length</literal>,

которую можно использовать в SQL-запросах.

</simpara>

<simpara>

В этом примере создаётся агрегирующая функция с именем <literal>max_length</literal>,

которая будет вычислять длину самой длинной строки в одном из столбцов таблицы.

Для каждой строки вызывается функция <literal>max_len_step</literal>,

которой передаётся параметр <literal>$context</literal>.

Параметр context, как и любая другая переменная PHP, может содержать массив (<type>array</type>)

или даже объект (<type>object</type>).

В этом примере он используется для хранения максимальной длины, которую уже была обработана;

если <varname>$string</varname> длиннее, чем текущий максимум, контекст обновляется,

чтобы содержать новую максимальную длину.

</simpara>

<simpara>

После обработки всех строк, SQLite вызывает функцию <literal>max_len_finalize</literal>

для определения агрегированного результата.

Можно выполнить какое-либо вычисление на основе данных в <literal>$context</literal>.

В данном примере результат вычислялся по мере выполнения запроса,

поэтому значение контекста может быть возвращено напрямую.

</simpara>

<programlisting role="php">

<![CDATA[

<?php

$data = [

'one',

'two',

'three',

'four',

'five',

'six',

'seven',

'eight',

'nine',

'ten',

];

$db = new Pdo\Sqlite('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, $row_number, $string)

{

if (strlen($string) > $context) {

$context = strlen($string);

}

return $context;

}

function max_len_finalize($context, $row_count)

{

return $context === null ? 0 : $context;

}

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

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

?>

]]>

</programlisting>

<tip>

<simpara>

НЕ рекомендуется хранить копию значений в контексте и затем обрабатывать их в конце,

так как SQLite будет использовать много памяти для обработки запроса – просто подумайте,

сколько памяти вам понадобится, если в памяти будет храниться миллион строк,

каждая из которых будет содержать строку длиной 32 байта.

</simpara>

</tip>

</example>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<simplelist>

<member><methodname>Pdo\Sqlite::createFunction</methodname></member>

<member><methodname>Pdo\Sqlite::createCollation</methodname></member>

<member><function>sqlite_create_function</function></member>

<member><function>sqlite_create_aggregate</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

-->