view release on metacpan or  search on metacpan

lib/DBD/SQLite/BundledExtensions.pm  view on Meta::CPAN

=item nextchar 

The next_char(A,T,F,W,C) function finds all valid "next" characters for
string A given the vocabulary in T.F.  If the W value exists and is a
non-empty string, then it is an SQL expression that limits the entries
in T.F that will be considered.  If C exists and is a non-empty string,
then it is the name of the collating sequence to use for comparison.  If

Only the first three arguments are required.  If the C parameter is 
omitted or is NULL or is an empty string, then the default collating 
sequence of T.F is used for comparision.  If the W parameter is omitted
or is NULL or is an empty string, then no filtering of the output is
done.

The T.F column should be indexed using collation C or else this routine
will be quite slow.

For example, suppose an application has a dictionary like this:

    CREATE TABLE dictionary(word TEXT UNIQUE);

Further suppose that for user keypad entry, it is desired to disable
(gray out) keys that are not valid as the next character.  If the
the user has previously entered (say) 'cha' then to find all allowed
next characters (and thereby determine when keys should not be grayed
out) run the following query:

    SELECT next_char('cha','dictionary','word');

IMPLEMENTATION NOTES:

The next_char function is implemented using recursive SQL that makes
use of the table name and column name as part of a query.  If either
the table name or column name are keywords or contain special characters,
then they should be escaped.  For example:

    SELECT next_char('cha','[dictionary]','[word]');

This also means that the table name can be a subquery:

    SELECT next_char('cha','(SELECT word AS w FROM dictionary)','w');

=item percentile 

This file contains code to implement the percentile(Y,P) SQL function
as described below:

  (1)  The percentile(Y,P) function is an aggregate function taking
       exactly two arguments.
  (2)  If the P argument to percentile(Y,P) is not the same for every
       row in the aggregate then an error is thrown.  The word "same"
       in the previous sentence means that the value differ by less
       than 0.001.
  (3)  If the P argument to percentile(Y,P) evaluates to anything other
       than a number in the range of 0.0 to 100.0 inclusive then an
       error is thrown.
  (4)  If any Y argument to percentile(Y,P) evaluates to a value that
       is not NULL and is not numeric then an error is thrown.
  (5)  If any Y argument to percentile(Y,P) evaluates to plus or minus
       infinity then an error is thrown.  (SQLite always interprets NaN
       values as NULL.)
  (6)  Both Y and P in percentile(Y,P) can be arbitrary expressions,
       including CASE WHEN expressions.
  (7)  The percentile(Y,P) aggregate is able to handle inputs of at least
       one million (1,000,000) rows.
  (8)  If there are no non-NULL values for Y, then percentile(Y,P)
       returns NULL.
  (9)  If there is exactly one non-NULL value for Y, the percentile(Y,P)
       returns the one Y value.
 (10)  If there N non-NULL values of Y where N is two or more and
       the Y values are ordered from least to greatest and a graph is
       drawn from 0 to N-1 such that the height of the graph at J is
       the J-th Y value and such that straight lines are drawn between
       adjacent Y values, then the percentile(Y,P) function returns
       the height of the graph at P*(N-1)/100.
 (11)  The percentile(Y,P) function always returns either a floating
       point number or NULL.
 (12)  The percentile(Y,P) is implemented as a single C99 source-code
       file that compiles into a shared-library or DLL that can be loaded
       into SQLite using the sqlite3_load_extension() interface.

=item series 

This extension implements the generate_series() function
which gives similar results to the eponymous function in PostgreSQL.

Examples:

     SELECT * FROM generate_series(0,100,5);

The query above returns integers from 0 through 100 counting by steps
of 5.

     SELECT * FROM generate_series(0,100);

Integers from 0 through 100 with a step size of 1.

     SELECT * FROM generate_series(20) LIMIT 10;

Integers 20 through 29.

HOW IT WORKS

The generate_series "function" is really a virtual table with the
following schema:

    CREATE FUNCTION generate_series(
      value,
      start HIDDEN,
      stop HIDDEN,
      step HIDDEN
    );

Function arguments in queries against this virtual table are translated
into equality constraints against successive hidden columns.  In other
words, the following pairs of queries are equivalent to each other:

   SELECT * FROM generate_series(0,100,5);
   SELECT * FROM generate_series WHERE start=0 AND stop=100 AND step=5;
   SELECT * FROM generate_series(0,100);