database/sqlite
1
0
Fork 0
mirror of https://github.com/sqlite/sqlite.git synced 2025-11-15 11:41:13 +03:00
Code Activity

Improved documentation for sqlite3_set_auxdata().

Browse Source 
Ticket [406d3b2ef91c].

FossilOrigin-Name: 62465ecba7431e1d71e17a61f1af7dc65fe4fe97
This commit is contained in:
drh
2013-07-18 18:45:53 +00:00
parent 6447827e3b
commit 6b75329ae1
3 changed files with 36 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
src/sqlite.h.in
View File

@@ -4176,46 +4176,45 @@ sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
/*
** CAPI3REF: Function Auxiliary Data
**
** The following two functions may be used by scalar SQL functions to
** These functions may be used by (non-aggregate) SQL functions to
** associate metadata with argument values. If the same value is passed to
** multiple invocations of the same SQL function during query execution, under
** some circumstances the associated metadata may be preserved. This might
** be used, for example, in a regular-expression matching
** function. The compiled version of the regular expression is stored as
** metadata associated with the SQL value passed as the regular expression
** pattern. The compiled regular expression can be reused on multiple
** invocations of the same function so that the original pattern string
** does not need to be recompiled on each invocation.
** some circumstances the associated metadata may be preserved. An example
** of where this might be useful is in a regular-expression matching
** function. The compiled version of the regular expression can be stored as
** metadata associated with the pattern string.
** Then as long as the pattern string remains the same,
** the compiled regular expression can be reused on multiple
** invocations of the same function.
**
** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata
** associated by the sqlite3_set_auxdata() function with the Nth argument
** value to the application-defined function. ^If no metadata has been ever
** been set for the Nth argument of the function, or if the corresponding
** function parameter has changed since the meta-data was set,
** then sqlite3_get_auxdata() returns a NULL pointer.
** value to the application-defined function. ^If there is no metadata
** associated with the function argument, this sqlite3_get_auxdata() interface
** returns a NULL pointer.
**
** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
** argument of the application-defined function. ^Subsequent
** calls to sqlite3_get_auxdata(C,N) return P from the most recent
** sqlite3_set_auxdata(C,N,P,X) call if the data has not been dropped, or
** NULL if the data has been dropped.
** ^(If it is not NULL, SQLite will invoke the destructor
** function X passed to sqlite3_set_auxdata(C,N,P,X) when <ul>
** <li> the corresponding function parameter changes,
** <li> [sqlite3_reset()] or [sqlite3_finalize()] is called for the
** SQL statement,
** <li> sqlite3_set_auxdata() is invoked again on the same parameter, or
** <li> a memory allocation error occurs. </ul>)^
** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
** NULL if the metadata has been discarded.
** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
** SQLite will invoke the destructor function X with parameter P exactly
** once, when the metadata is discarded.
** SQLite is free to discard the metadata at any time, including: <ul>
** <li> when the corresponding function parameter changes, or
** <li> when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
** SQL statement, or
** <li> when sqlite3_set_auxdata() is invoked again on the same parameter, or
** <li> during the original sqlite3_set_auxdata() call when a memory
** allocation error occurs. </ul>)^
**
** SQLite is free to call the destructor and drop metadata on any
** parameter of any function at any time. ^The only guarantee is that
** the destructor will be called when the [prepared statement] is destroyed.
** Note in particular that the destructor X in the call to
** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before
** the sqlite3_set_auxdata() call even returns. Hence sqlite3_set_auxdata()
** Note the last bullet in particular. The destructor X in
** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
** sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata()
** should be called near the end of the function implementation and the
** implementation should not make any use of P after sqlite3_set_auxdata()
** has been called.
** function implementation should not make any use of P after
** sqlite3_set_auxdata() has been called.
**
** ^(In practice, metadata is preserved between function calls for
** function parameters that are compile-time constants, including literal