Mercurial > embed
comparison sqlite/sqlite3.h @ 69:a49197d6289b
sqlite: upgrade to 3.24.0, closes #886 @5m
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 13 Jul 2018 13:23:49 +0200 |
parents | e5880f2798a1 |
children |
comparison
equal
deleted
inserted
replaced
68:1a32b6d17c8e | 69:a49197d6289b |
---|---|
121 ** | 121 ** |
122 ** See also: [sqlite3_libversion()], | 122 ** See also: [sqlite3_libversion()], |
123 ** [sqlite3_libversion_number()], [sqlite3_sourceid()], | 123 ** [sqlite3_libversion_number()], [sqlite3_sourceid()], |
124 ** [sqlite_version()] and [sqlite_source_id()]. | 124 ** [sqlite_version()] and [sqlite_source_id()]. |
125 */ | 125 */ |
126 #define SQLITE_VERSION "3.23.1" | 126 #define SQLITE_VERSION "3.24.0" |
127 #define SQLITE_VERSION_NUMBER 3023001 | 127 #define SQLITE_VERSION_NUMBER 3024000 |
128 #define SQLITE_SOURCE_ID "2018-04-10 17:39:29 4bb2294022060e61de7da5c227a69ccd846ba330e31626ebcd59a94efd148b3b" | 128 #define SQLITE_SOURCE_ID "2018-06-04 19:24:41 c7ee0833225bfd8c5ec2f9bf62b97c4e04d03bd9566366d5221ac8fb199a87ca" |
129 | 129 |
130 /* | 130 /* |
131 ** CAPI3REF: Run-Time Library Version Numbers | 131 ** CAPI3REF: Run-Time Library Version Numbers |
132 ** KEYWORDS: sqlite3_version sqlite3_sourceid | 132 ** KEYWORDS: sqlite3_version sqlite3_sourceid |
133 ** | 133 ** |
502 #define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8)) | 502 #define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8)) |
503 #define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29<<8)) | 503 #define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29<<8)) |
504 #define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8)) | 504 #define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8)) |
505 #define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8)) | 505 #define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8)) |
506 #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8)) | 506 #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8)) |
507 #define SQLITE_LOCKED_VTAB (SQLITE_LOCKED | (2<<8)) | |
507 #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8)) | 508 #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8)) |
508 #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8)) | 509 #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8)) |
509 #define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8)) | 510 #define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8)) |
510 #define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8)) | 511 #define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8)) |
511 #define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8)) | 512 #define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8)) |
512 #define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8)) | 513 #define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8)) |
513 #define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8)) | 514 #define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8)) |
515 #define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT | (2<<8)) | |
514 #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8)) | 516 #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8)) |
515 #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8)) | 517 #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8)) |
516 #define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8)) | 518 #define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8)) |
517 #define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8)) | 519 #define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8)) |
518 #define SQLITE_READONLY_CANTINIT (SQLITE_READONLY | (5<<8)) | 520 #define SQLITE_READONLY_CANTINIT (SQLITE_READONLY | (5<<8)) |
1928 ** Since many statement journals never become large, setting the spill | 1930 ** Since many statement journals never become large, setting the spill |
1929 ** threshold to a value such as 64KiB can greatly reduce the amount of | 1931 ** threshold to a value such as 64KiB can greatly reduce the amount of |
1930 ** I/O required to support statement rollback. | 1932 ** I/O required to support statement rollback. |
1931 ** The default value for this setting is controlled by the | 1933 ** The default value for this setting is controlled by the |
1932 ** [SQLITE_STMTJRNL_SPILL] compile-time option. | 1934 ** [SQLITE_STMTJRNL_SPILL] compile-time option. |
1935 ** | |
1936 ** [[SQLITE_CONFIG_SORTERREF_SIZE]] | |
1937 ** <dt>SQLITE_CONFIG_SORTERREF_SIZE | |
1938 ** <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter | |
1939 ** of type (int) - the new value of the sorter-reference size threshold. | |
1940 ** Usually, when SQLite uses an external sort to order records according | |
1941 ** to an ORDER BY clause, all fields required by the caller are present in the | |
1942 ** sorted records. However, if SQLite determines based on the declared type | |
1943 ** of a table column that its values are likely to be very large - larger | |
1944 ** than the configured sorter-reference size threshold - then a reference | |
1945 ** is stored in each sorted record and the required column values loaded | |
1946 ** from the database as records are returned in sorted order. The default | |
1947 ** value for this option is to never use this optimization. Specifying a | |
1948 ** negative value for this option restores the default behaviour. | |
1949 ** This option is only available if SQLite is compiled with the | |
1950 ** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option. | |
1933 ** </dl> | 1951 ** </dl> |
1934 */ | 1952 */ |
1935 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ | 1953 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ |
1936 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ | 1954 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ |
1937 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ | 1955 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ |
1957 #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */ | 1975 #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */ |
1958 #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ | 1976 #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ |
1959 #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ | 1977 #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ |
1960 #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */ | 1978 #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */ |
1961 #define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */ | 1979 #define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */ |
1980 #define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */ | |
1962 | 1981 |
1963 /* | 1982 /* |
1964 ** CAPI3REF: Database Connection Configuration Options | 1983 ** CAPI3REF: Database Connection Configuration Options |
1965 ** | 1984 ** |
1966 ** These constants are the available integer configuration options that | 1985 ** These constants are the available integer configuration options that |
2093 ** or negative to leave the setting unchanged. | 2112 ** or negative to leave the setting unchanged. |
2094 ** The second parameter is a pointer to an integer into which is written | 2113 ** The second parameter is a pointer to an integer into which is written |
2095 ** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if | 2114 ** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if |
2096 ** it is not disabled, 1 if it is. | 2115 ** it is not disabled, 1 if it is. |
2097 ** </dd> | 2116 ** </dd> |
2117 ** | |
2118 ** <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt> | |
2119 ** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run | |
2120 ** [VACUUM] in order to reset a database back to an empty database | |
2121 ** with no schema and no content. The following process works even for | |
2122 ** a badly corrupted database file: | |
2123 ** <ol> | |
2124 ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0); | |
2125 ** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0); | |
2126 ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0); | |
2127 ** </ol> | |
2128 ** Because resetting a database is destructive and irreversible, the | |
2129 ** process requires the use of this obscure API and multiple steps to help | |
2130 ** ensure that it does not happen by accident. | |
2131 ** </dd> | |
2098 ** </dl> | 2132 ** </dl> |
2099 */ | 2133 */ |
2100 #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ | 2134 #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ |
2101 #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ | 2135 #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ |
2102 #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ | 2136 #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ |
2104 #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ | 2138 #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ |
2105 #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ | 2139 #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ |
2106 #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ | 2140 #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ |
2107 #define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */ | 2141 #define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */ |
2108 #define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */ | 2142 #define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */ |
2109 #define SQLITE_DBCONFIG_MAX 1008 /* Largest DBCONFIG */ | 2143 #define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */ |
2144 #define SQLITE_DBCONFIG_MAX 1009 /* Largest DBCONFIG */ | |
2110 | 2145 |
2111 /* | 2146 /* |
2112 ** CAPI3REF: Enable Or Disable Extended Result Codes | 2147 ** CAPI3REF: Enable Or Disable Extended Result Codes |
2113 ** METHOD: sqlite3 | 2148 ** METHOD: sqlite3 |
2114 ** | 2149 ** |
5491 ** or else the use of the [data_store_directory pragma] should be avoided. | 5526 ** or else the use of the [data_store_directory pragma] should be avoided. |
5492 */ | 5527 */ |
5493 SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory; | 5528 SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory; |
5494 | 5529 |
5495 /* | 5530 /* |
5531 ** CAPI3REF: Win32 Specific Interface | |
5532 ** | |
5533 ** These interfaces are available only on Windows. The | |
5534 ** [sqlite3_win32_set_directory] interface is used to set the value associated | |
5535 ** with the [sqlite3_temp_directory] or [sqlite3_data_directory] variable, to | |
5536 ** zValue, depending on the value of the type parameter. The zValue parameter | |
5537 ** should be NULL to cause the previous value to be freed via [sqlite3_free]; | |
5538 ** a non-NULL value will be copied into memory obtained from [sqlite3_malloc] | |
5539 ** prior to being used. The [sqlite3_win32_set_directory] interface returns | |
5540 ** [SQLITE_OK] to indicate success, [SQLITE_ERROR] if the type is unsupported, | |
5541 ** or [SQLITE_NOMEM] if memory could not be allocated. The value of the | |
5542 ** [sqlite3_data_directory] variable is intended to act as a replacement for | |
5543 ** the current directory on the sub-platforms of Win32 where that concept is | |
5544 ** not present, e.g. WinRT and UWP. The [sqlite3_win32_set_directory8] and | |
5545 ** [sqlite3_win32_set_directory16] interfaces behave exactly the same as the | |
5546 ** sqlite3_win32_set_directory interface except the string parameter must be | |
5547 ** UTF-8 or UTF-16, respectively. | |
5548 */ | |
5549 SQLITE_API int sqlite3_win32_set_directory( | |
5550 unsigned long type, /* Identifier for directory being set or reset */ | |
5551 void *zValue /* New value for directory being set or reset */ | |
5552 ); | |
5553 SQLITE_API int sqlite3_win32_set_directory8(unsigned long type, const char *zValue); | |
5554 SQLITE_API int sqlite3_win32_set_directory16(unsigned long type, const void *zValue); | |
5555 | |
5556 /* | |
5557 ** CAPI3REF: Win32 Directory Types | |
5558 ** | |
5559 ** These macros are only available on Windows. They define the allowed values | |
5560 ** for the type argument to the [sqlite3_win32_set_directory] interface. | |
5561 */ | |
5562 #define SQLITE_WIN32_DATA_DIRECTORY_TYPE 1 | |
5563 #define SQLITE_WIN32_TEMP_DIRECTORY_TYPE 2 | |
5564 | |
5565 /* | |
5496 ** CAPI3REF: Test For Auto-Commit Mode | 5566 ** CAPI3REF: Test For Auto-Commit Mode |
5497 ** KEYWORDS: {autocommit mode} | 5567 ** KEYWORDS: {autocommit mode} |
5498 ** METHOD: sqlite3 | 5568 ** METHOD: sqlite3 |
5499 ** | 5569 ** |
5500 ** ^The sqlite3_get_autocommit() interface returns non-zero or | 5570 ** ^The sqlite3_get_autocommit() interface returns non-zero or |
6222 sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */ | 6292 sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */ |
6223 }; | 6293 }; |
6224 | 6294 |
6225 /* | 6295 /* |
6226 ** CAPI3REF: Virtual Table Scan Flags | 6296 ** CAPI3REF: Virtual Table Scan Flags |
6297 ** | |
6298 ** Virtual table implementations are allowed to set the | |
6299 ** [sqlite3_index_info].idxFlags field to some combination of | |
6300 ** these bits. | |
6227 */ | 6301 */ |
6228 #define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */ | 6302 #define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */ |
6229 | 6303 |
6230 /* | 6304 /* |
6231 ** CAPI3REF: Virtual Table Constraint Operator Codes | 6305 ** CAPI3REF: Virtual Table Constraint Operator Codes |
6997 #define SQLITE_TESTCTRL_PENDING_BYTE 11 | 7071 #define SQLITE_TESTCTRL_PENDING_BYTE 11 |
6998 #define SQLITE_TESTCTRL_ASSERT 12 | 7072 #define SQLITE_TESTCTRL_ASSERT 12 |
6999 #define SQLITE_TESTCTRL_ALWAYS 13 | 7073 #define SQLITE_TESTCTRL_ALWAYS 13 |
7000 #define SQLITE_TESTCTRL_RESERVE 14 | 7074 #define SQLITE_TESTCTRL_RESERVE 14 |
7001 #define SQLITE_TESTCTRL_OPTIMIZATIONS 15 | 7075 #define SQLITE_TESTCTRL_OPTIMIZATIONS 15 |
7002 #define SQLITE_TESTCTRL_ISKEYWORD 16 | 7076 #define SQLITE_TESTCTRL_ISKEYWORD 16 /* NOT USED */ |
7003 #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */ | 7077 #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */ |
7004 #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 | 7078 #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 |
7005 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ | 7079 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ |
7006 #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19 | 7080 #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19 |
7007 #define SQLITE_TESTCTRL_NEVER_CORRUPT 20 | 7081 #define SQLITE_TESTCTRL_NEVER_CORRUPT 20 |
7010 #define SQLITE_TESTCTRL_ISINIT 23 | 7084 #define SQLITE_TESTCTRL_ISINIT 23 |
7011 #define SQLITE_TESTCTRL_SORTER_MMAP 24 | 7085 #define SQLITE_TESTCTRL_SORTER_MMAP 24 |
7012 #define SQLITE_TESTCTRL_IMPOSTER 25 | 7086 #define SQLITE_TESTCTRL_IMPOSTER 25 |
7013 #define SQLITE_TESTCTRL_PARSER_COVERAGE 26 | 7087 #define SQLITE_TESTCTRL_PARSER_COVERAGE 26 |
7014 #define SQLITE_TESTCTRL_LAST 26 /* Largest TESTCTRL */ | 7088 #define SQLITE_TESTCTRL_LAST 26 /* Largest TESTCTRL */ |
7089 | |
7090 /* | |
7091 ** CAPI3REF: SQL Keyword Checking | |
7092 ** | |
7093 ** These routines provide access to the set of SQL language keywords | |
7094 ** recognized by SQLite. Applications can uses these routines to determine | |
7095 ** whether or not a specific identifier needs to be escaped (for example, | |
7096 ** by enclosing in double-quotes) so as not to confuse the parser. | |
7097 ** | |
7098 ** The sqlite3_keyword_count() interface returns the number of distinct | |
7099 ** keywords understood by SQLite. | |
7100 ** | |
7101 ** The sqlite3_keyword_name(N,Z,L) interface finds the N-th keyword and | |
7102 ** makes *Z point to that keyword expressed as UTF8 and writes the number | |
7103 ** of bytes in the keyword into *L. The string that *Z points to is not | |
7104 ** zero-terminated. The sqlite3_keyword_name(N,Z,L) routine returns | |
7105 ** SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z | |
7106 ** or L are NULL or invalid pointers then calls to | |
7107 ** sqlite3_keyword_name(N,Z,L) result in undefined behavior. | |
7108 ** | |
7109 ** The sqlite3_keyword_check(Z,L) interface checks to see whether or not | |
7110 ** the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero | |
7111 ** if it is and zero if not. | |
7112 ** | |
7113 ** The parser used by SQLite is forgiving. It is often possible to use | |
7114 ** a keyword as an identifier as long as such use does not result in a | |
7115 ** parsing ambiguity. For example, the statement | |
7116 ** "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and | |
7117 ** creates a new table named "BEGIN" with three columns named | |
7118 ** "REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid | |
7119 ** using keywords as identifiers. Common techniques used to avoid keyword | |
7120 ** name collisions include: | |
7121 ** <ul> | |
7122 ** <li> Put all identifier names inside double-quotes. This is the official | |
7123 ** SQL way to escape identifier names. | |
7124 ** <li> Put identifier names inside [...]. This is not standard SQL, | |
7125 ** but it is what SQL Server does and so lots of programmers use this | |
7126 ** technique. | |
7127 ** <li> Begin every identifier with the letter "Z" as no SQL keywords start | |
7128 ** with "Z". | |
7129 ** <li> Include a digit somewhere in every identifier name. | |
7130 ** </ul> | |
7131 ** | |
7132 ** Note that the number of keywords understood by SQLite can depend on | |
7133 ** compile-time options. For example, "VACUUM" is not a keyword if | |
7134 ** SQLite is compiled with the [-DSQLITE_OMIT_VACUUM] option. Also, | |
7135 ** new keywords may be added to future releases of SQLite. | |
7136 */ | |
7137 SQLITE_API int sqlite3_keyword_count(void); | |
7138 SQLITE_API int sqlite3_keyword_name(int,const char**,int*); | |
7139 SQLITE_API int sqlite3_keyword_check(const char*,int); | |
7140 | |
7141 /* | |
7142 ** CAPI3REF: Dynamic String Object | |
7143 ** KEYWORDS: {dynamic string} | |
7144 ** | |
7145 ** An instance of the sqlite3_str object contains a dynamically-sized | |
7146 ** string under construction. | |
7147 ** | |
7148 ** The lifecycle of an sqlite3_str object is as follows: | |
7149 ** <ol> | |
7150 ** <li> ^The sqlite3_str object is created using [sqlite3_str_new()]. | |
7151 ** <li> ^Text is appended to the sqlite3_str object using various | |
7152 ** methods, such as [sqlite3_str_appendf()]. | |
7153 ** <li> ^The sqlite3_str object is destroyed and the string it created | |
7154 ** is returned using the [sqlite3_str_finish()] interface. | |
7155 ** </ol> | |
7156 */ | |
7157 typedef struct sqlite3_str sqlite3_str; | |
7158 | |
7159 /* | |
7160 ** CAPI3REF: Create A New Dynamic String Object | |
7161 ** CONSTRUCTOR: sqlite3_str | |
7162 ** | |
7163 ** ^The [sqlite3_str_new(D)] interface allocates and initializes | |
7164 ** a new [sqlite3_str] object. To avoid memory leaks, the object returned by | |
7165 ** [sqlite3_str_new()] must be freed by a subsequent call to | |
7166 ** [sqlite3_str_finish(X)]. | |
7167 ** | |
7168 ** ^The [sqlite3_str_new(D)] interface always returns a pointer to a | |
7169 ** valid [sqlite3_str] object, though in the event of an out-of-memory | |
7170 ** error the returned object might be a special singleton that will | |
7171 ** silently reject new text, always return SQLITE_NOMEM from | |
7172 ** [sqlite3_str_errcode()], always return 0 for | |
7173 ** [sqlite3_str_length()], and always return NULL from | |
7174 ** [sqlite3_str_finish(X)]. It is always safe to use the value | |
7175 ** returned by [sqlite3_str_new(D)] as the sqlite3_str parameter | |
7176 ** to any of the other [sqlite3_str] methods. | |
7177 ** | |
7178 ** The D parameter to [sqlite3_str_new(D)] may be NULL. If the | |
7179 ** D parameter in [sqlite3_str_new(D)] is not NULL, then the maximum | |
7180 ** length of the string contained in the [sqlite3_str] object will be | |
7181 ** the value set for [sqlite3_limit](D,[SQLITE_LIMIT_LENGTH]) instead | |
7182 ** of [SQLITE_MAX_LENGTH]. | |
7183 */ | |
7184 SQLITE_API sqlite3_str *sqlite3_str_new(sqlite3*); | |
7185 | |
7186 /* | |
7187 ** CAPI3REF: Finalize A Dynamic String | |
7188 ** DESTRUCTOR: sqlite3_str | |
7189 ** | |
7190 ** ^The [sqlite3_str_finish(X)] interface destroys the sqlite3_str object X | |
7191 ** and returns a pointer to a memory buffer obtained from [sqlite3_malloc64()] | |
7192 ** that contains the constructed string. The calling application should | |
7193 ** pass the returned value to [sqlite3_free()] to avoid a memory leak. | |
7194 ** ^The [sqlite3_str_finish(X)] interface may return a NULL pointer if any | |
7195 ** errors were encountered during construction of the string. ^The | |
7196 ** [sqlite3_str_finish(X)] interface will also return a NULL pointer if the | |
7197 ** string in [sqlite3_str] object X is zero bytes long. | |
7198 */ | |
7199 SQLITE_API char *sqlite3_str_finish(sqlite3_str*); | |
7200 | |
7201 /* | |
7202 ** CAPI3REF: Add Content To A Dynamic String | |
7203 ** METHOD: sqlite3_str | |
7204 ** | |
7205 ** These interfaces add content to an sqlite3_str object previously obtained | |
7206 ** from [sqlite3_str_new()]. | |
7207 ** | |
7208 ** ^The [sqlite3_str_appendf(X,F,...)] and | |
7209 ** [sqlite3_str_vappendf(X,F,V)] interfaces uses the [built-in printf] | |
7210 ** functionality of SQLite to append formatted text onto the end of | |
7211 ** [sqlite3_str] object X. | |
7212 ** | |
7213 ** ^The [sqlite3_str_append(X,S,N)] method appends exactly N bytes from string S | |
7214 ** onto the end of the [sqlite3_str] object X. N must be non-negative. | |
7215 ** S must contain at least N non-zero bytes of content. To append a | |
7216 ** zero-terminated string in its entirety, use the [sqlite3_str_appendall()] | |
7217 ** method instead. | |
7218 ** | |
7219 ** ^The [sqlite3_str_appendall(X,S)] method appends the complete content of | |
7220 ** zero-terminated string S onto the end of [sqlite3_str] object X. | |
7221 ** | |
7222 ** ^The [sqlite3_str_appendchar(X,N,C)] method appends N copies of the | |
7223 ** single-byte character C onto the end of [sqlite3_str] object X. | |
7224 ** ^This method can be used, for example, to add whitespace indentation. | |
7225 ** | |
7226 ** ^The [sqlite3_str_reset(X)] method resets the string under construction | |
7227 ** inside [sqlite3_str] object X back to zero bytes in length. | |
7228 ** | |
7229 ** These methods do not return a result code. ^If an error occurs, that fact | |
7230 ** is recorded in the [sqlite3_str] object and can be recovered by a | |
7231 ** subsequent call to [sqlite3_str_errcode(X)]. | |
7232 */ | |
7233 SQLITE_API void sqlite3_str_appendf(sqlite3_str*, const char *zFormat, ...); | |
7234 SQLITE_API void sqlite3_str_vappendf(sqlite3_str*, const char *zFormat, va_list); | |
7235 SQLITE_API void sqlite3_str_append(sqlite3_str*, const char *zIn, int N); | |
7236 SQLITE_API void sqlite3_str_appendall(sqlite3_str*, const char *zIn); | |
7237 SQLITE_API void sqlite3_str_appendchar(sqlite3_str*, int N, char C); | |
7238 SQLITE_API void sqlite3_str_reset(sqlite3_str*); | |
7239 | |
7240 /* | |
7241 ** CAPI3REF: Status Of A Dynamic String | |
7242 ** METHOD: sqlite3_str | |
7243 ** | |
7244 ** These interfaces return the current status of an [sqlite3_str] object. | |
7245 ** | |
7246 ** ^If any prior errors have occurred while constructing the dynamic string | |
7247 ** in sqlite3_str X, then the [sqlite3_str_errcode(X)] method will return | |
7248 ** an appropriate error code. ^The [sqlite3_str_errcode(X)] method returns | |
7249 ** [SQLITE_NOMEM] following any out-of-memory error, or | |
7250 ** [SQLITE_TOOBIG] if the size of the dynamic string exceeds | |
7251 ** [SQLITE_MAX_LENGTH], or [SQLITE_OK] if there have been no errors. | |
7252 ** | |
7253 ** ^The [sqlite3_str_length(X)] method returns the current length, in bytes, | |
7254 ** of the dynamic string under construction in [sqlite3_str] object X. | |
7255 ** ^The length returned by [sqlite3_str_length(X)] does not include the | |
7256 ** zero-termination byte. | |
7257 ** | |
7258 ** ^The [sqlite3_str_value(X)] method returns a pointer to the current | |
7259 ** content of the dynamic string under construction in X. The value | |
7260 ** returned by [sqlite3_str_value(X)] is managed by the sqlite3_str object X | |
7261 ** and might be freed or altered by any subsequent method on the same | |
7262 ** [sqlite3_str] object. Applications must not used the pointer returned | |
7263 ** [sqlite3_str_value(X)] after any subsequent method call on the same | |
7264 ** object. ^Applications may change the content of the string returned | |
7265 ** by [sqlite3_str_value(X)] as long as they do not write into any bytes | |
7266 ** outside the range of 0 to [sqlite3_str_length(X)] and do not read or | |
7267 ** write any byte after any subsequent sqlite3_str method call. | |
7268 */ | |
7269 SQLITE_API int sqlite3_str_errcode(sqlite3_str*); | |
7270 SQLITE_API int sqlite3_str_length(sqlite3_str*); | |
7271 SQLITE_API char *sqlite3_str_value(sqlite3_str*); | |
7015 | 7272 |
7016 /* | 7273 /* |
7017 ** CAPI3REF: SQLite Runtime Status | 7274 ** CAPI3REF: SQLite Runtime Status |
7018 ** | 7275 ** |
7019 ** ^These interfaces are used to retrieve runtime status information | 7276 ** ^These interfaces are used to retrieve runtime status information |
8280 ** | 8537 ** |
8281 ** If the sqlite3_vtab_nochange(X) routine is called within the [xColumn] | 8538 ** If the sqlite3_vtab_nochange(X) routine is called within the [xColumn] |
8282 ** method of a [virtual table], then it returns true if and only if the | 8539 ** method of a [virtual table], then it returns true if and only if the |
8283 ** column is being fetched as part of an UPDATE operation during which the | 8540 ** column is being fetched as part of an UPDATE operation during which the |
8284 ** column value will not change. Applications might use this to substitute | 8541 ** column value will not change. Applications might use this to substitute |
8285 ** a lighter-weight value to return that the corresponding [xUpdate] method | 8542 ** a return value that is less expensive to compute and that the corresponding |
8286 ** understands as a "no-change" value. | 8543 ** [xUpdate] method understands as a "no-change" value. |
8287 ** | 8544 ** |
8288 ** If the [xColumn] method calls sqlite3_vtab_nochange() and finds that | 8545 ** If the [xColumn] method calls sqlite3_vtab_nochange() and finds that |
8289 ** the column is not changed by the UPDATE statement, they the xColumn | 8546 ** the column is not changed by the UPDATE statement, then the xColumn |
8290 ** method can optionally return without setting a result, without calling | 8547 ** method can optionally return without setting a result, without calling |
8291 ** any of the [sqlite3_result_int|sqlite3_result_xxxxx() interfaces]. | 8548 ** any of the [sqlite3_result_int|sqlite3_result_xxxxx() interfaces]. |
8292 ** In that case, [sqlite3_value_nochange(X)] will return true for the | 8549 ** In that case, [sqlite3_value_nochange(X)] will return true for the |
8293 ** same column in the [xUpdate] method. | 8550 ** same column in the [xUpdate] method. |
8294 */ | 8551 */ |
8779 ** memory representation of the database exists. A contiguous memory | 9036 ** memory representation of the database exists. A contiguous memory |
8780 ** representation of the database will usually only exist if there has | 9037 ** representation of the database will usually only exist if there has |
8781 ** been a prior call to [sqlite3_deserialize(D,S,...)] with the same | 9038 ** been a prior call to [sqlite3_deserialize(D,S,...)] with the same |
8782 ** values of D and S. | 9039 ** values of D and S. |
8783 ** The size of the database is written into *P even if the | 9040 ** The size of the database is written into *P even if the |
8784 ** SQLITE_SERIALIZE_NOCOPY bit is set but no contigious copy | 9041 ** SQLITE_SERIALIZE_NOCOPY bit is set but no contiguous copy |
8785 ** of the database exists. | 9042 ** of the database exists. |
8786 ** | 9043 ** |
8787 ** A call to sqlite3_serialize(D,S,P,F) might return NULL even if the | 9044 ** A call to sqlite3_serialize(D,S,P,F) might return NULL even if the |
8788 ** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory | 9045 ** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory |
8789 ** allocation error occurs. | 9046 ** allocation error occurs. |