Documentation Source Text

Check-in [820de7c995]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update the fts5 documentation to make it clear that the xDestroy function is not invoked if either xCreateFunction or xCreateTokenizer fails.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:820de7c9959ffc84be1b898afbdeb5bd9f1554df632a1e2624b3a65deaa6a6ab
User & Date: dan 2017-11-25 15:22:09
Context
2017-12-09
15:44
Add documentation for shell tool SQLAR archive support. check-in: 809f9fa181 user: dan tags: trunk
2017-11-25
15:22
Update the fts5 documentation to make it clear that the xDestroy function is not invoked if either xCreateFunction or xCreateTokenizer fails. check-in: 820de7c995 user: dan tags: trunk
14:02
Add a description of the "^" syntax to fts5.in. check-in: 58bbcf8b2f user: dan tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/fts5.in.

1485
1486
1487
1488
1489
1490
1491











1492
1493
1494
1495
1496
1497
1498
....
1520
1521
1522
1523
1524
1525
1526




1527
1528
1529
1530
1531
1532
1533
<tclscript>
  set res ""
  set ::extract_api_docs_mode fts5_tokenizer
  catch { set res [source [file join $::SRC ext/fts5/extract_api_docs.tcl]] }
  set res
</tclscript>
</codeblock>












<p> When an FTS5 table uses the custom tokenizer, the FTS5 core calls xCreate()
once to create a tokenizer, then xTokenize() zero or more times to tokenize
strings, then xDelete() to free any resources allocated by xCreate(). More
specifically:

<tclscript>
................................................................................
<p> The implementation is registered with the FTS5 module by calling the
xCreateFunction() method of the fts5_api object. If there is already an
auxiliary function with the same name, it is replaced by the new function.
If a non-NULL xDestroy parameter is passed to xCreateFunction(), it is invoked
with a copy of the pContext pointer passed as the only argument when the
database handle is closed or when the registered auxiliary function is
replaced.





<p> The final three arguments passed to the auxiliary function callback are
similar to the three arguments passed to the implementation of a scalar SQL
function. All arguments except the first passed to the auxiliary function are
available to the implementation in the apVal&#91;&#93; array. The
implementation should return a result or error via the content handle pCtx.








>
>
>
>
>
>
>
>
>
>
>







 







>
>
>
>







1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
....
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
<tclscript>
  set res ""
  set ::extract_api_docs_mode fts5_tokenizer
  catch { set res [source [file join $::SRC ext/fts5/extract_api_docs.tcl]] }
  set res
</tclscript>
</codeblock>

<p> The implementation is registered with the FTS5 module by calling the
xCreateTokenizer() method of the fts5_api object. If there is already a
tokenizer with the same name, it is replaced.  If a non-NULL xDestroy parameter
is passed to xCreateTokenizer(), it is invoked with a copy of the pContext
pointer passed as the only argument when the database handle is closed or when
the tokenizer is replaced.

<p> If successful, xCreateTokenizer() returns SQLITE_OK. Otherwise, it
returns an SQLite error code. In this case the xDestroy function is <b>not</b> 
invoked.

<p> When an FTS5 table uses the custom tokenizer, the FTS5 core calls xCreate()
once to create a tokenizer, then xTokenize() zero or more times to tokenize
strings, then xDelete() to free any resources allocated by xCreate(). More
specifically:

<tclscript>
................................................................................
<p> The implementation is registered with the FTS5 module by calling the
xCreateFunction() method of the fts5_api object. If there is already an
auxiliary function with the same name, it is replaced by the new function.
If a non-NULL xDestroy parameter is passed to xCreateFunction(), it is invoked
with a copy of the pContext pointer passed as the only argument when the
database handle is closed or when the registered auxiliary function is
replaced.

<p> If successful, xCreateFunction() returns SQLITE_OK. Otherwise, it
returns an SQLite error code. In this case the xDestroy function is <b>not</b> 
invoked.

<p> The final three arguments passed to the auxiliary function callback are
similar to the three arguments passed to the implementation of a scalar SQL
function. All arguments except the first passed to the auxiliary function are
available to the implementation in the apVal&#91;&#93; array. The
implementation should return a result or error via the content handle pCtx.