From 95f26c1563454ad38d97c839c28bb4b26ad7bff9 Mon Sep 17 00:00:00 2001 From: Wez Furlong Date: Fri, 9 Sep 2005 03:25:37 +0000 Subject: [PATCH] Document sqlite specific functions for PDO. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@195553 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../functions/PDO-sqliteCreateAggregate.xml | 199 ++++++++++++++++++ .../functions/PDO-sqliteCreateFunction.xml | 167 +++++++++++++++ 2 files changed, 366 insertions(+) create mode 100644 reference/pdo_sqlite/functions/PDO-sqliteCreateAggregate.xml create mode 100644 reference/pdo_sqlite/functions/PDO-sqliteCreateFunction.xml diff --git a/reference/pdo_sqlite/functions/PDO-sqliteCreateAggregate.xml b/reference/pdo_sqlite/functions/PDO-sqliteCreateAggregate.xml new file mode 100644 index 0000000000..422d39ae73 --- /dev/null +++ b/reference/pdo_sqlite/functions/PDO-sqliteCreateAggregate.xml @@ -0,0 +1,199 @@ + + + + + PDO::sqliteCreateAggregate + + Registers an aggregating User Defined Function for use in SQL statements + + + + + &reftitle.description; + + boolPDO::sqliteCreateAggregate + stringfunction_name + callbackstep_func + callbackfinalize_func + intnum_args + + + &warn.experimental.func; + + PDO::sqliteCreateAggregate is similar to + PDO::sqliteCreateFunction except that it registers + functions that can be used to calculate a result aggregated across all the + rows of a query. + + + The key difference between this function and + PDO::sqliteCreateFunction is that two functions are + required to manage the aggregate; step_func is + called for each row of the result set. Your PHP function should + accumulate the result and store it into the aggregation context. + Once all the rows have been processed, + finalize_func will be called and it should then + take the data from the aggregation context and return the result. + Callback functions should return a type understood by SQLite (i.e. + scalar type). + + + + + &reftitle.parameters; + + + + function_name + + + The name of the function used in SQL statements. + + + + + step_func + + + Callback function called for each row of the result set. + + + + + finalize_func + + + Callback function to aggregate the "stepped" data from each row. + + + + + num_args + + + Hint to the SQLite parser if the callback function accepts a + predetermined number of arguments. + + + + + + + + + &reftitle.examples; + + + max_length aggregation function example + +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, $string) +{ + if (strlen($string) > $context) { + $context = strlen($string); + } +} + +function max_len_finalize(&$context) +{ + return $context; +} + +$db->sqliteCreateAggregate('max_len', 'max_len_step', 'max_len_finalize'); + +var_dump($db->query('SELECT max_len(a) from strings')->fetchAll()); + +?> +]]> + + + + + In this example, we are creating an aggregating function that will + calculate the length of the longest string in one of the columns of the + table. For each row, the max_len_step function is + called and passed a context parameter. The context + parameter is just like any other PHP variable and be set to hold an array + or even an object value. In this example, we are simply using it to hold + the maximum length we have seen so far; if the + string has a length longer than the current + maximum, we update the context to hold this new maximum length. + + + After all of the rows have been processed, SQLite calls the + max_len_finalize function to determine the aggregate + result. Here, we could perform some kind of calculation based on the + data found in the context. In our simple example + though, we have been calculating the result as the query progressed, so we + simply need to return the context value. + + + + It is NOT recommended for you to store a copy of the values in the context + and then process them at the end, as you would cause SQLite to use a lot of + memory to process the query - just think of how much memory you would need + if a million rows were stored in memory, each containing a string 32 bytes + in length. + + + + + You can use PDO::sqliteCreateFunction and + PDO::sqliteCreateAggregate to override SQLite native + SQL functions. + + + + + + + &reftitle.seealso; + + + PDO::sqliteCreateFunction + + + + + + diff --git a/reference/pdo_sqlite/functions/PDO-sqliteCreateFunction.xml b/reference/pdo_sqlite/functions/PDO-sqliteCreateFunction.xml new file mode 100644 index 0000000000..a37cf0d27a --- /dev/null +++ b/reference/pdo_sqlite/functions/PDO-sqliteCreateFunction.xml @@ -0,0 +1,167 @@ + + + + + PDO::sqliteCreateFunction + + Registers a User Defined Function for use in SQL statements + + + + + &reftitle.description; + + boolPDO::sqliteCreateFunction + stringfunction_name + callbackcallback + intnum_args + + + &warn.experimental.func; + + + PDO::sqliteCreateFunction allows you to register a PHP + function with SQLite as an UDF (User Defined + Function), so that it can be called from within your SQL statements. + + + The UDF can be used in any SQL statement that can call functions, such as + SELECT and UPDATE statements and also in triggers. + + + + + &reftitle.parameters; + + + + function_name + + + The name of the function used in SQL statements. + + + + + callback + + + Callback function to handle the defined SQL function. + + + + Callback functions should return a type understood by SQLite (i.e. + scalar type). + + + + + + num_args + + + Hint to the SQLite parser if the callback function accepts a + predetermined number of arguments. + + + + + + &sqlite.param-compat; + + + + &reftitle.examples; + + + <function>PDO::sqliteCreateFunction</function> example + +sqliteCreateFunction('md5rev', 'md5_and_reverse', 1); +$rows = $db->query('SELECT md5rev(filename) FROM files')->fetchAll(); +?> +]]> + + + + + In this example, we have a function that calculates the md5 sum of a + string, and then reverses it. When the SQL statement executes, it + returns the value of the filename transformed by our function. The data + returned in $rows contains the processed result. + + + The beauty of this technique is that you do not need to process the + result using a foreach() loop after you have queried for the data. + + + + + You can use PDO::sqliteCreateFunction and + PDO::sqliteCreateAggregate to override SQLite native + SQL functions. + + + + + + &reftitle.seealso; + + + PDO::sqliteCreateAggregate + + + + + +