OLD | NEW |
1 /* | 1 /* |
2 ** 2014 May 31 | 2 ** 2014 May 31 |
3 ** | 3 ** |
4 ** The author disclaims copyright to this source code. In place of | 4 ** The author disclaims copyright to this source code. In place of |
5 ** a legal notice, here is a blessing: | 5 ** a legal notice, here is a blessing: |
6 ** | 6 ** |
7 ** May you do good and not evil. | 7 ** May you do good and not evil. |
8 ** May you find forgiveness for yourself and forgive others. | 8 ** May you find forgiveness for yourself and forgive others. |
9 ** May you share freely, never taking more than you give. | 9 ** May you share freely, never taking more than you give. |
10 ** | 10 ** |
(...skipping 66 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
77 ** If parameter iCol is less than zero, set output variable *pnToken | 77 ** If parameter iCol is less than zero, set output variable *pnToken |
78 ** to the total number of tokens in the current row. Or, if iCol is | 78 ** to the total number of tokens in the current row. Or, if iCol is |
79 ** non-negative but less than the number of columns in the table, set | 79 ** non-negative but less than the number of columns in the table, set |
80 ** *pnToken to the number of tokens in column iCol of the current row. | 80 ** *pnToken to the number of tokens in column iCol of the current row. |
81 ** | 81 ** |
82 ** If parameter iCol is greater than or equal to the number of columns | 82 ** If parameter iCol is greater than or equal to the number of columns |
83 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g. | 83 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g. |
84 ** an OOM condition or IO error), an appropriate SQLite error code is | 84 ** an OOM condition or IO error), an appropriate SQLite error code is |
85 ** returned. | 85 ** returned. |
86 ** | 86 ** |
| 87 ** This function may be quite inefficient if used with an FTS5 table |
| 88 ** created with the "columnsize=0" option. |
| 89 ** |
87 ** xColumnText: | 90 ** xColumnText: |
88 ** This function attempts to retrieve the text of column iCol of the | 91 ** This function attempts to retrieve the text of column iCol of the |
89 ** current document. If successful, (*pz) is set to point to a buffer | 92 ** current document. If successful, (*pz) is set to point to a buffer |
90 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes | 93 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes |
91 ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise, | 94 ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise, |
92 ** if an error occurs, an SQLite error code is returned and the final values | 95 ** if an error occurs, an SQLite error code is returned and the final values |
93 ** of (*pz) and (*pn) are undefined. | 96 ** of (*pz) and (*pn) are undefined. |
94 ** | 97 ** |
95 ** xPhraseCount: | 98 ** xPhraseCount: |
96 ** Returns the number of phrases in the current query expression. | 99 ** Returns the number of phrases in the current query expression. |
97 ** | 100 ** |
98 ** xPhraseSize: | 101 ** xPhraseSize: |
99 ** Returns the number of tokens in phrase iPhrase of the query. Phrases | 102 ** Returns the number of tokens in phrase iPhrase of the query. Phrases |
100 ** are numbered starting from zero. | 103 ** are numbered starting from zero. |
101 ** | 104 ** |
102 ** xInstCount: | 105 ** xInstCount: |
103 ** Set *pnInst to the total number of occurrences of all phrases within | 106 ** Set *pnInst to the total number of occurrences of all phrases within |
104 ** the query within the current row. Return SQLITE_OK if successful, or | 107 ** the query within the current row. Return SQLITE_OK if successful, or |
105 ** an error code (i.e. SQLITE_NOMEM) if an error occurs. | 108 ** an error code (i.e. SQLITE_NOMEM) if an error occurs. |
106 ** | 109 ** |
| 110 ** This API can be quite slow if used with an FTS5 table created with the |
| 111 ** "detail=none" or "detail=column" option. If the FTS5 table is created |
| 112 ** with either "detail=none" or "detail=column" and "content=" option |
| 113 ** (i.e. if it is a contentless table), then this API always returns 0. |
| 114 ** |
107 ** xInst: | 115 ** xInst: |
108 ** Query for the details of phrase match iIdx within the current row. | 116 ** Query for the details of phrase match iIdx within the current row. |
109 ** Phrase matches are numbered starting from zero, so the iIdx argument | 117 ** Phrase matches are numbered starting from zero, so the iIdx argument |
110 ** should be greater than or equal to zero and smaller than the value | 118 ** should be greater than or equal to zero and smaller than the value |
111 ** output by xInstCount(). | 119 ** output by xInstCount(). |
112 ** | 120 ** |
| 121 ** Usually, output parameter *piPhrase is set to the phrase number, *piCol |
| 122 ** to the column in which it occurs and *piOff the token offset of the |
| 123 ** first token of the phrase. The exception is if the table was created |
| 124 ** with the offsets=0 option specified. In this case *piOff is always |
| 125 ** set to -1. |
| 126 ** |
113 ** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM) | 127 ** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM) |
114 ** if an error occurs. | 128 ** if an error occurs. |
115 ** | 129 ** |
| 130 ** This API can be quite slow if used with an FTS5 table created with the |
| 131 ** "detail=none" or "detail=column" option. |
| 132 ** |
116 ** xRowid: | 133 ** xRowid: |
117 ** Returns the rowid of the current row. | 134 ** Returns the rowid of the current row. |
118 ** | 135 ** |
119 ** xTokenize: | 136 ** xTokenize: |
120 ** Tokenize text using the tokenizer belonging to the FTS5 table. | 137 ** Tokenize text using the tokenizer belonging to the FTS5 table. |
121 ** | 138 ** |
122 ** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback): | 139 ** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback): |
123 ** This API function is used to query the FTS table for phrase iPhrase | 140 ** This API function is used to query the FTS table for phrase iPhrase |
124 ** of the current query. Specifically, a query equivalent to: | 141 ** of the current query. Specifically, a query equivalent to: |
125 ** | 142 ** |
126 ** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid | 143 ** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid |
127 ** | 144 ** |
128 ** with $p set to a phrase equivalent to the phrase iPhrase of the | 145 ** with $p set to a phrase equivalent to the phrase iPhrase of the |
129 ** current query is executed. For each row visited, the callback function | 146 ** current query is executed. Any column filter that applies to |
130 ** passed as the fourth argument is invoked. The context and API objects | 147 ** phrase iPhrase of the current query is included in $p. For each |
131 ** passed to the callback function may be used to access the properties of | 148 ** row visited, the callback function passed as the fourth argument |
132 ** each matched row. Invoking Api.xUserData() returns a copy of the pointer | 149 ** is invoked. The context and API objects passed to the callback |
133 ** passed as the third argument to pUserData. | 150 ** function may be used to access the properties of each matched row. |
| 151 ** Invoking Api.xUserData() returns a copy of the pointer passed as |
| 152 ** the third argument to pUserData. |
134 ** | 153 ** |
135 ** If the callback function returns any value other than SQLITE_OK, the | 154 ** If the callback function returns any value other than SQLITE_OK, the |
136 ** query is abandoned and the xQueryPhrase function returns immediately. | 155 ** query is abandoned and the xQueryPhrase function returns immediately. |
137 ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK. | 156 ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK. |
138 ** Otherwise, the error code is propagated upwards. | 157 ** Otherwise, the error code is propagated upwards. |
139 ** | 158 ** |
140 ** If the query runs to completion without incident, SQLITE_OK is returned. | 159 ** If the query runs to completion without incident, SQLITE_OK is returned. |
141 ** Or, if some error occurs before the query completes or is aborted by | 160 ** Or, if some error occurs before the query completes or is aborted by |
142 ** the callback, an SQLite error code is returned. | 161 ** the callback, an SQLite error code is returned. |
143 ** | 162 ** |
(...skipping 45 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
189 ** This function is used, along with type Fts5PhraseIter and the xPhraseNext | 208 ** This function is used, along with type Fts5PhraseIter and the xPhraseNext |
190 ** method, to iterate through all instances of a single query phrase within | 209 ** method, to iterate through all instances of a single query phrase within |
191 ** the current row. This is the same information as is accessible via the | 210 ** the current row. This is the same information as is accessible via the |
192 ** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient | 211 ** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient |
193 ** to use, this API may be faster under some circumstances. To iterate | 212 ** to use, this API may be faster under some circumstances. To iterate |
194 ** through instances of phrase iPhrase, use the following code: | 213 ** through instances of phrase iPhrase, use the following code: |
195 ** | 214 ** |
196 ** Fts5PhraseIter iter; | 215 ** Fts5PhraseIter iter; |
197 ** int iCol, iOff; | 216 ** int iCol, iOff; |
198 ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff); | 217 ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff); |
199 ** iOff>=0; | 218 ** iCol>=0; |
200 ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff) | 219 ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff) |
201 ** ){ | 220 ** ){ |
202 ** // An instance of phrase iPhrase at offset iOff of column iCol | 221 ** // An instance of phrase iPhrase at offset iOff of column iCol |
203 ** } | 222 ** } |
204 ** | 223 ** |
205 ** The Fts5PhraseIter structure is defined above. Applications should not | 224 ** The Fts5PhraseIter structure is defined above. Applications should not |
206 ** modify this structure directly - it should only be used as shown above | 225 ** modify this structure directly - it should only be used as shown above |
207 ** with the xPhraseFirst() and xPhraseNext() API methods. | 226 ** with the xPhraseFirst() and xPhraseNext() API methods (and by |
| 227 ** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below). |
| 228 ** |
| 229 ** This API can be quite slow if used with an FTS5 table created with the |
| 230 ** "detail=none" or "detail=column" option. If the FTS5 table is created |
| 231 ** with either "detail=none" or "detail=column" and "content=" option |
| 232 ** (i.e. if it is a contentless table), then this API always iterates |
| 233 ** through an empty set (all calls to xPhraseFirst() set iCol to -1). |
208 ** | 234 ** |
209 ** xPhraseNext() | 235 ** xPhraseNext() |
210 ** See xPhraseFirst above. | 236 ** See xPhraseFirst above. |
| 237 ** |
| 238 ** xPhraseFirstColumn() |
| 239 ** This function and xPhraseNextColumn() are similar to the xPhraseFirst() |
| 240 ** and xPhraseNext() APIs described above. The difference is that instead |
| 241 ** of iterating through all instances of a phrase in the current row, these |
| 242 ** APIs are used to iterate through the set of columns in the current row |
| 243 ** that contain one or more instances of a specified phrase. For example: |
| 244 ** |
| 245 ** Fts5PhraseIter iter; |
| 246 ** int iCol; |
| 247 ** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol); |
| 248 ** iCol>=0; |
| 249 ** pApi->xPhraseNextColumn(pFts, &iter, &iCol) |
| 250 ** ){ |
| 251 ** // Column iCol contains at least one instance of phrase iPhrase |
| 252 ** } |
| 253 ** |
| 254 ** This API can be quite slow if used with an FTS5 table created with the |
| 255 ** "detail=none" option. If the FTS5 table is created with either |
| 256 ** "detail=none" "content=" option (i.e. if it is a contentless table), |
| 257 ** then this API always iterates through an empty set (all calls to |
| 258 ** xPhraseFirstColumn() set iCol to -1). |
| 259 ** |
| 260 ** The information accessed using this API and its companion |
| 261 ** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext |
| 262 ** (or xInst/xInstCount). The chief advantage of this API is that it is |
| 263 ** significantly more efficient than those alternatives when used with |
| 264 ** "detail=column" tables. |
| 265 ** |
| 266 ** xPhraseNextColumn() |
| 267 ** See xPhraseFirstColumn above. |
211 */ | 268 */ |
212 struct Fts5ExtensionApi { | 269 struct Fts5ExtensionApi { |
213 int iVersion; /* Currently always set to 1 */ | 270 int iVersion; /* Currently always set to 3 */ |
214 | 271 |
215 void *(*xUserData)(Fts5Context*); | 272 void *(*xUserData)(Fts5Context*); |
216 | 273 |
217 int (*xColumnCount)(Fts5Context*); | 274 int (*xColumnCount)(Fts5Context*); |
218 int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow); | 275 int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow); |
219 int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken); | 276 int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken); |
220 | 277 |
221 int (*xTokenize)(Fts5Context*, | 278 int (*xTokenize)(Fts5Context*, |
222 const char *pText, int nText, /* Text to tokenize */ | 279 const char *pText, int nText, /* Text to tokenize */ |
223 void *pCtx, /* Context passed to xToken() */ | 280 void *pCtx, /* Context passed to xToken() */ |
224 int (*xToken)(void*, int, const char*, int, int, int) /* Callback */ | 281 int (*xToken)(void*, int, const char*, int, int, int) /* Callback */ |
225 ); | 282 ); |
226 | 283 |
227 int (*xPhraseCount)(Fts5Context*); | 284 int (*xPhraseCount)(Fts5Context*); |
228 int (*xPhraseSize)(Fts5Context*, int iPhrase); | 285 int (*xPhraseSize)(Fts5Context*, int iPhrase); |
229 | 286 |
230 int (*xInstCount)(Fts5Context*, int *pnInst); | 287 int (*xInstCount)(Fts5Context*, int *pnInst); |
231 int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff); | 288 int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff); |
232 | 289 |
233 sqlite3_int64 (*xRowid)(Fts5Context*); | 290 sqlite3_int64 (*xRowid)(Fts5Context*); |
234 int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn); | 291 int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn); |
235 int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken); | 292 int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken); |
236 | 293 |
237 int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData, | 294 int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData, |
238 int(*)(const Fts5ExtensionApi*,Fts5Context*,void*) | 295 int(*)(const Fts5ExtensionApi*,Fts5Context*,void*) |
239 ); | 296 ); |
240 int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*)); | 297 int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*)); |
241 void *(*xGetAuxdata)(Fts5Context*, int bClear); | 298 void *(*xGetAuxdata)(Fts5Context*, int bClear); |
242 | 299 |
243 void (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*); | 300 int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*); |
244 void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff); | 301 void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff); |
| 302 |
| 303 int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*); |
| 304 void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol); |
245 }; | 305 }; |
246 | 306 |
247 /* | 307 /* |
248 ** CUSTOM AUXILIARY FUNCTIONS | 308 ** CUSTOM AUXILIARY FUNCTIONS |
249 *************************************************************************/ | 309 *************************************************************************/ |
250 | 310 |
251 /************************************************************************* | 311 /************************************************************************* |
252 ** CUSTOM TOKENIZERS | 312 ** CUSTOM TOKENIZERS |
253 ** | 313 ** |
254 ** Applications may also register custom tokenizer types. A tokenizer | 314 ** Applications may also register custom tokenizer types. A tokenizer |
255 ** is registered by providing fts5 with a populated instance of the | 315 ** is registered by providing fts5 with a populated instance of the |
256 ** following structure. All structure methods must be defined, setting | 316 ** following structure. All structure methods must be defined, setting |
257 ** any member of the fts5_tokenizer struct to NULL leads to undefined | 317 ** any member of the fts5_tokenizer struct to NULL leads to undefined |
258 ** behaviour. The structure methods are expected to function as follows: | 318 ** behaviour. The structure methods are expected to function as follows: |
259 ** | 319 ** |
260 ** xCreate: | 320 ** xCreate: |
261 ** This function is used to allocate and inititalize a tokenizer instance. | 321 ** This function is used to allocate and initialize a tokenizer instance. |
262 ** A tokenizer instance is required to actually tokenize text. | 322 ** A tokenizer instance is required to actually tokenize text. |
263 ** | 323 ** |
264 ** The first argument passed to this function is a copy of the (void*) | 324 ** The first argument passed to this function is a copy of the (void*) |
265 ** pointer provided by the application when the fts5_tokenizer object | 325 ** pointer provided by the application when the fts5_tokenizer object |
266 ** was registered with FTS5 (the third argument to xCreateTokenizer()). | 326 ** was registered with FTS5 (the third argument to xCreateTokenizer()). |
267 ** The second and third arguments are an array of nul-terminated strings | 327 ** The second and third arguments are an array of nul-terminated strings |
268 ** containing the tokenizer arguments, if any, specified following the | 328 ** containing the tokenizer arguments, if any, specified following the |
269 ** tokenizer name as part of the CREATE VIRTUAL TABLE statement used | 329 ** tokenizer name as part of the CREATE VIRTUAL TABLE statement used |
270 ** to create the FTS5 table. | 330 ** to create the FTS5 table. |
271 ** | 331 ** |
(...skipping 238 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
510 | 570 |
511 /* | 571 /* |
512 ** END OF REGISTRATION API | 572 ** END OF REGISTRATION API |
513 *************************************************************************/ | 573 *************************************************************************/ |
514 | 574 |
515 #ifdef __cplusplus | 575 #ifdef __cplusplus |
516 } /* end of the 'extern "C"' block */ | 576 } /* end of the 'extern "C"' block */ |
517 #endif | 577 #endif |
518 | 578 |
519 #endif /* _FTS5_H */ | 579 #endif /* _FTS5_H */ |
520 | |
OLD | NEW |