Collation routines

Collation routines order the results from a SELECT statement.
You can define your own routines and tell QDB to use them by providing the
COLLATE keyword in the ORDER BY clause.

In your code, you must define a collation routine by providing both a setup function
and a sorting function. You must also define a qdb_collation structure
that references these functions. Consider this sample collation that provides a setup
function that allows the caller to reverse the sorting order (by passing in the string
"reverse"), and then uses memcmp() in its sorting function:

In this case, the tag value for the structure is my_sort_runtime_cfg,
the collation name as visible to SQL is also my_sort_runtime_cfg,
the C function used for setup is my_sort_cfg_setup(), and the C
function used for comparison is my_sort_cfg_sort(). Each function
has the my_sort_cfg_data value passed in as its
arg value.
For more information on defining SQLite collation sequences, see the SQLite docs on
sqlite3_create_collation().

You can define multiple collation sequences (in the same or different DLLs), but each
must have a Collation entry in the configuration object as well as a
struct qdb_collation object with a unique name describing the routine.

The name used for this function in SQL statements. This is limited to 255
bytes, exclusive of the null-terminator, and it can't contain any special
tokens or start with a digit. Any attempt to create a function with an
invalid name results in an SQLITE_ERROR error.

encoding

The character encoding of strings passed to your function. Can be one of:

SQLITE_UTF8

SQLITE_UTF16

SQLITE_UTF16BE

SQLITE_UTF16LE

arg

An arbitrary pointer to user data that is passed as the first argument to
your function each time it's invoked.

compare

A pointer to your comparison function.

This entry must not be NULL because all collations need a function that
tells them how to compare two items.
The signature of this function looks like this:

The context pointer. This is copied from arg in the
qdb_collation structure.

l1

The size of the first data item, in bytes.

s1

A pointer to the first data item.

l2

The size of the second data item, in bytes.

s2

A pointer to the second data item.

setup

A pointer to a setup function that allows you to configure the sorting
order at runtime.

If a collation has no dynamic configuration, you can specify
NULL for its setup entry. Note that this
entry can't be changed at runtime. When the entry is non-NULL, the
referenced function is invoked at startup and at each
qdb_collation() call.
The signature of the setup function looks like this:

int (*setup)(void *arg, const void *data, int nbytes, char **errmsg);

The function parameters are:

void *arg

The context pointer. This is copied from the
arg field in the qdb_collation
structure.

const void *data

The data used to configure the sorting. When the routine is invoked at
startup, this value is NULL. At runtime, it refers to the data provided
to the qdb_collation() function.
Note that the DLL must cooperate with the caller to exchange data
of a known format.

intnbytes

The data size, in bytes. At startup, this value is 0. At runtime, it
contains the size of the data given to qdb_collation().

char **errmsg

A pointer to an error message string that is available to
qdb_geterrmsg() and is displayed on failure.
At startup, QDB fails the setup function; at runtime, QDB fails
qdb_collation() and makes this string available
through qdb_geterrmsg().

The function returns either EOK (if it succeeds) or a POSIX
errno value (if it fails).