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

<refentry xml:id="sqlite3.createaggregate" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<refnamediv>

<refname>SQLite3::createAggregate</refname>

<refpurpose>SQL の集約関数として使用する PHP 関数を登録する</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis role="SQLite3">

<modifier>public</modifier> <type>bool</type><methodname>SQLite3::createAggregate</methodname>

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

<methodparam><type>callable</type><parameter>stepCallback</parameter></methodparam>

<methodparam><type>callable</type><parameter>finalCallback</parameter></methodparam>

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

</methodsynopsis>

<para>

SQL の集約関数として使用する PHP 関数を登録します。

これは SQL 文の中で使用されるものです。

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

作成あるいは再定義したい SQL 集約関数の名前。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>stepCallback</parameter></term>

<listitem>

<para>

結果セットの各行ごとにコールされるコールバック関数。

この関数で結果を集約し、集約処理のコンテキストに保存すべきです。

</para>

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

<para>

最初の行では &null; です。

2行目以降は、step 関数から返された値をとります。

これは、集約の状況を管理するのに使います。

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

現在の行番号

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

集約に渡されるはじめの引数

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

集約に渡されるふたつめ以降の引数

</para>

</listitem>

</varlistentry>

</variablelist>

この関数の戻り値は、

次のステップで呼ばれる際、または finalize 関数での

<parameter>context</parameter> の引数として使われます。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>finalCallback</parameter></term>

<listitem>

<para>

各行からの "段階的に処理された" データを集約するコールバック関数です。

いったん全データが処理されると、この関数が呼ばれます。

集約処理のコンテキストからデータを取り出し、結果を返すべきです。

このコールバック関数は SQLite が理解する型を返します。

(例: <link linkend="language.types.intro">スカラー型</link>)

</para>

<para>

このコールバック関数は、以下のように定義すべきです:

<methodsynopsis>

<type>mixed</type><methodname><replaceable>fini</replaceable></methodname>

<methodparam><type>mixed</type><parameter>context</parameter></methodparam>

<methodparam><type>int</type><parameter>rownumber</parameter></methodparam>

</methodsynopsis>

<variablelist>

<varlistentry>

<term><parameter>context</parameter></term>

<listitem>

<para>

最後に呼ばれた step 関数から返された値を保持します。

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

常に <literal>0</literal>.

</para>

</listitem>

</varlistentry>

</variablelist>

この関数の戻り値は、集約の戻り値として使われます。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>argCount</parameter></term>

<listitem>

<para>

SQL 集約関数が受け取るパラメータの数。

負の値を指定すると、SQL 集約関数は任意の数の引数を受け取るようになります。

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

集約関数の作成に成功した場合に &true;、&return.falseforfailure;

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>max_length 集約関数の例</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen role="php">

</screen>

</example>

</para>

<para>

この例では、テーブルのカラムに入っている一番長い文字列を集約する関数を作っています。

1行ごとに、<literal>max_len_step</literal> 関数が呼ばれ、

<literal>$context</literal> パラメータが渡されます。 context パラメータ

は他のPHPの変数のように振る舞いますし、配列やオブジェクトを格納することさえできます。

この例では、単にこれまで見てきたものの中から一番大きな長さを保持するのに使っています。

つまり、<literal>$string</literal> が現在の最大値より大きな長さをもっていたら、

context を新しい最大値に更新しています。

</para>

<para>

全ての行を処理し終わったら、SQLite は

集約結果を決めるために <literal>max_len_finalize</literal> 関数を呼び出します。

ここでは、<literal>$context</literal> で見つかったデータを基にして、

ある種の計算を行うことができます。

私達のシンプルな例では、結果を段階的に計算してきているので、

単に context に入っている値を返すだけで済みます。

</para>

<tip>

<para>

値のコピーを context に保存し、一番最後に処理することは推奨できません。

なぜなら、SQLite がクエリを処理するのにたくさんのメモリを使うことになるからです。

- 100万行の情報がメモリに格納されていたとして、

それぞれの行が32バイトの長さを持っていたとすると、

どれくらいのメモリが必要になるのかを考えてみてください。

</para>

</tip>

<tip>

<para>

SQLite のネイティブなSQL関数を上書きするために

<methodname>SQLite3::createAggregate</methodname> を使うことができます。

</para>

</tip>

</refsect1>

</refentry>