NAME
sqlite3_create_function,
sqlite3_create_function16,
sqlite3_create_function_v2 —
Create
Or Redefine SQL Functions
SYNOPSIS
int
sqlite3_create_function(
sqlite3 *db,
const char *zFunctionName,
int
nArg,
int eTextRep,
void
*pApp,
void
(*xFunc)(sqlite3_context*,int,sqlite3_value**),
void
(*xStep)(sqlite3_context*,int,sqlite3_value**),
void
(*xFinal)(sqlite3_context*) );
int
sqlite3_create_function16(
sqlite3 *db,
const void *zFunctionName,
int
nArg,
int eTextRep,
void
*pApp,
void
(*xFunc)(sqlite3_context*,int,sqlite3_value**),
void
(*xStep)(sqlite3_context*,int,sqlite3_value**),
void
(*xFinal)(sqlite3_context*) );
int
sqlite3_create_function_v2(
sqlite3 *db,
const char *zFunctionName,
int
nArg,
int eTextRep,
void
*pApp,
void
(*xFunc)(sqlite3_context*,int,sqlite3_value**),
void
(*xStep)(sqlite3_context*,int,sqlite3_value**),
void
(*xFinal)(sqlite3_context*),
void(*xDestroy)(void*)
);
DESCRIPTION
These functions (collectively known as "function creation routines")
are used to add SQL functions or aggregates or to redefine the behavior of
existing SQL functions or aggregates. The only differences between these
routines are the text encoding expected for the second parameter (the name of
the function being created) and the presence or absence of a destructor
callback for the application data pointer.
The first parameter is the database connection to which the SQL function is to
be added. If an application uses more than one database connection then
application-defined SQL functions must be added to each database connection
separately.
The second parameter is the name of the SQL function to be created or redefined.
The length of the name is limited to 255 bytes in a UTF-8 representation,
exclusive of the zero-terminator. Note that the name length limit is in UTF-8
bytes, not characters nor UTF-16 bytes. Any attempt to create a function with
a longer name will result in SQLITE_MISUSE being returned.
The third parameter (nArg) is the number of arguments that the SQL function or
aggregate takes. If this parameter is -1, then the SQL function or aggregate
may take any number of arguments between 0 and the limit set by
sqlite3_limit(SQLITE_LIMIT_FUNCTION_ARG). If the third parameter is less than
-1 or greater than 127 then the behavior is undefined.
The fourth parameter, eTextRep, specifies what text encoding this SQL function
prefers for its parameters. The application should set this parameter to
SQLITE_UTF16LE if the function implementation invokes sqlite3_value_text16le()
on an input, or SQLITE_UTF16BE if the implementation invokes
sqlite3_value_text16be() on an input, or SQLITE_UTF16 if
sqlite3_value_text16() is used, or SQLITE_UTF8 otherwise. The same SQL
function may be registered multiple times using different preferred text
encodings, with different implementations for each encoding. When multiple
implementations of the same function are available, SQLite will pick the one
that involves the least amount of data conversion.
The fourth parameter may optionally be ORed with SQLITE_DETERMINISTIC to signal
that the function will always return the same result given the same inputs
within a single SQL statement. Most SQL functions are deterministic. The
built-in random() SQL function is an example of a function that is not
deterministic. The SQLite query planner is able to perform additional
optimizations on deterministic functions, so use of the SQLITE_DETERMINISTIC
flag is recommended where possible.
The fifth parameter is an arbitrary pointer. The implementation of the function
can gain access to this pointer using sqlite3_user_data().
The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are pointers
to C-language functions that implement the SQL function or aggregate. A scalar
SQL function requires an implementation of the xFunc callback only; NULL
pointers must be passed as the xStep and xFinal parameters. An aggregate SQL
function requires an implementation of xStep and xFinal and NULL pointer must
be passed for xFunc. To delete an existing SQL function or aggregate, pass
NULL pointers for all three function callbacks.
If the ninth parameter to sqlite3_create_function_v2() is not NULL, then it is
destructor for the application data pointer. The destructor is invoked when
the function is deleted, either by being overloaded or when the database
connection closes. The destructor is also invoked if the call to
sqlite3_create_function_v2() fails. When the destructor callback of the tenth
parameter is invoked, it is passed a single argument which is a copy of the
application data pointer which was the fifth parameter to
sqlite3_create_function_v2().
It is permitted to register multiple implementations of the same functions with
the same name but with either differing numbers of arguments or differing
preferred text encodings. SQLite will use the implementation that most closely
matches the way in which the SQL function is used. A function implementation
with a non-negative nArg parameter is a better match than a function
implementation with a negative nArg. A function where the preferred text
encoding matches the database encoding is a better match than a function where
the encoding is different. A function where the encoding difference is between
UTF16le and UTF16be is a closer match than a function where the encoding
difference is between UTF8 and UTF16.
Built-in functions may be overloaded by new application-defined functions.
An application-defined function is permitted to call other SQLite interfaces.
However, such calls must not close the database connection nor finalize or
reset the prepared statement in which the function is running.
SEE ALSO
sqlite3(3),
sqlite3_limit(3),
sqlite3_user_data(3),
sqlite3_value_blob(3),
SQLITE_DETERMINISTIC(3),
SQLITE_LIMIT_LENGTH(3),
SQLITE_OK(3),
SQLITE_UTF8(3)