175 lines
7.2 KiB
Groff
175 lines
7.2 KiB
Groff
.Dd December 19, 2018
|
|
.Dt SQLITE3_CREATE_FUNCTION 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sqlite3_create_function ,
|
|
.Nm sqlite3_create_function16 ,
|
|
.Nm sqlite3_create_function_v2 ,
|
|
.Nm sqlite3_create_window_function
|
|
.Nd Create Or Redefine SQL Functions
|
|
.Sh SYNOPSIS
|
|
.Ft int
|
|
.Fo sqlite3_create_function
|
|
.Fa "sqlite3 *db"
|
|
.Fa "const char *zFunctionName"
|
|
.Fa "int nArg"
|
|
.Fa "int eTextRep"
|
|
.Fa "void *pApp"
|
|
.Fa "void (*xFunc)(sqlite3_context*,int,sqlite3_value**)"
|
|
.Fa "void (*xStep)(sqlite3_context*,int,sqlite3_value**)"
|
|
.Fa "void (*xFinal)(sqlite3_context*) "
|
|
.Fc
|
|
.Ft int
|
|
.Fo sqlite3_create_function16
|
|
.Fa "sqlite3 *db"
|
|
.Fa "const void *zFunctionName"
|
|
.Fa "int nArg"
|
|
.Fa "int eTextRep"
|
|
.Fa "void *pApp"
|
|
.Fa "void (*xFunc)(sqlite3_context*,int,sqlite3_value**)"
|
|
.Fa "void (*xStep)(sqlite3_context*,int,sqlite3_value**)"
|
|
.Fa "void (*xFinal)(sqlite3_context*) "
|
|
.Fc
|
|
.Ft int
|
|
.Fo sqlite3_create_function_v2
|
|
.Fa "sqlite3 *db"
|
|
.Fa "const char *zFunctionName"
|
|
.Fa "int nArg"
|
|
.Fa "int eTextRep"
|
|
.Fa "void *pApp"
|
|
.Fa "void (*xFunc)(sqlite3_context*,int,sqlite3_value**)"
|
|
.Fa "void (*xStep)(sqlite3_context*,int,sqlite3_value**)"
|
|
.Fa "void (*xFinal)(sqlite3_context*)"
|
|
.Fa "void(*xDestroy)(void*) "
|
|
.Fc
|
|
.Ft int
|
|
.Fo sqlite3_create_window_function
|
|
.Fa "sqlite3 *db"
|
|
.Fa "const char *zFunctionName"
|
|
.Fa "int nArg"
|
|
.Fa "int eTextRep"
|
|
.Fa "void *pApp"
|
|
.Fa "void (*xStep)(sqlite3_context*,int,sqlite3_value**)"
|
|
.Fa "void (*xFinal)(sqlite3_context*)"
|
|
.Fa "void (*xValue)(sqlite3_context*)"
|
|
.Fa "void (*xInverse)(sqlite3_context*,int,sqlite3_value**)"
|
|
.Fa "void(*xDestroy)(void*) "
|
|
.Fc
|
|
.Sh 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 the three "sqlite3_create_function*" 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.
|
|
Function sqlite3_create_window_function() is similar, but allows the
|
|
user to supply the extra callback functions needed by aggregate window functions.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The fifth parameter is an arbitrary pointer.
|
|
The implementation of the function can gain access to this pointer
|
|
using sqlite3_user_data().
|
|
.Pp
|
|
The sixth, seventh and eighth parameters passed to the three "sqlite3_create_function*"
|
|
functions, 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.
|
|
.Pp
|
|
The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue
|
|
and xInverse) passed to sqlite3_create_window_function are pointers
|
|
to C-language callbacks that implement the new function.
|
|
xStep and xFinal must both be non-NULL.
|
|
xValue and xInverse may either both be NULL, in which case a regular
|
|
aggregate function is created, or must both be non-NULL, in which case
|
|
the new function may be used as either an aggregate or aggregate window
|
|
function.
|
|
More details regarding the implementation of aggregate window functions
|
|
are available here.
|
|
.Pp
|
|
If the final parameter to sqlite3_create_function_v2() or sqlite3_create_window_function()
|
|
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 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().
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
Built-in functions may be overloaded by new application-defined functions.
|
|
.Pp
|
|
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.
|
|
.Sh SEE ALSO
|
|
.Xr sqlite3 3 ,
|
|
.Xr sqlite3_limit 3 ,
|
|
.Xr sqlite3_user_data 3 ,
|
|
.Xr sqlite3_value_blob 3 ,
|
|
.Xr SQLITE_DETERMINISTIC 3 ,
|
|
.Xr SQLITE_LIMIT_LENGTH 3 ,
|
|
.Xr SQLITE_OK 3 ,
|
|
.Xr SQLITE_UTF8 3
|