From: drh <> Date: Sat, 24 Jan 2026 12:19:00 +0000 (+0000) Subject: Expound upon the meaning of SQLITE_UTF8_ZT, in an attempt to head off X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=40b6eace0e0b342f91189599d1294570470134d0;p=thirdparty%2Fsqlite.git Expound upon the meaning of SQLITE_UTF8_ZT, in an attempt to head off confusion. FossilOrigin-Name: 9a74d0c3e78eef9a32775f445ecb3fae76e2f3886b9173a16971d7c7506967fe --- diff --git a/manifest b/manifest index b7adffd477..8342499d54 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Expose\sSQLITE_UTF_ZT\sto\sWASM\sfor\scompleteness's\ssake,\sbut\sthe\sWASM\sbuild\sdoes\snot\sexpose\ssqlite3_bind_text64()\sor\ssqlite3_result_text64()\sbecause\sit\sonly\ssupports\sUTF8\sencoding,\sso\sZT\sdoes\snot\scurrently\shave\sa\sgenuine\suse\sthere. -D 2026-01-24T01:17:06.334 +C Expound\supon\sthe\smeaning\sof\sSQLITE_UTF8_ZT,\sin\san\sattempt\sto\shead\soff\nconfusion. +D 2026-01-24T12:19:00.053 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea @@ -740,7 +740,7 @@ F src/resolve.c 47aa7fdc9ec4c19b103ac5e79d7887d30119b5675309facf5eed1118391c868b F src/rowset.c 8432130e6c344b3401a8874c3cb49fefe6873fec593294de077afea2dce5ec97 F src/select.c f6ab7ed61778798626c2655d67f43506545d75becb1736c1f0dbc6a2830bf644 F src/shell.c.in e8818572acd50464bc00426fe0d755e98239f73d531437c3dc7721d1fecb1231 -F src/sqlite.h.in d463dcdd67d4865991cd62dc8d3f678086b38365593861f77c09c3401551d59f +F src/sqlite.h.in 69eccc01b4c0ff8e8c830e1961971290f1b94d46dc59cfd40f82d26cb9331eb0 F src/sqlite3.rc 015537e6ac1eec6c7050e17b616c2ffe6f70fca241835a84a4f0d5937383c479 F src/sqlite3ext.h f590cd8cb4c36fc727632c9b5fbbafc85f7efe2c6890f9958d7e711dc26ec01e F src/sqliteInt.h af67bc95fa6b66cd3c7f3d18d2d040ad386e4cbb02965ee318cc721ee9d5fa45 @@ -2193,8 +2193,8 @@ F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee F tool/warnings.sh d924598cf2f55a4ecbc2aeb055c10bd5f48114793e7ba25f9585435da29e7e98 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f F tool/winmain.c 00c8fb88e365c9017db14c73d3c78af62194d9644feaf60e220ab0f411f3604c -P fc4e93a381dfb99dddfd2ef001bf56b92ab89ee3c7044c7ce13ad32f38b3f418 -R a9cdfbbcb1ff104986a8b31da02f4969 -U stephan -Z ee2348f029e196ec88a93e6054116c63 +P d931831ce9d2dea3730f33afc046e159ad886842114831a6bbe56d5b746ab0af +R b6310b010b0cd1549f829e25e9f96b16 +U drh +Z 253e0d47080fbade0ed407fedf0fe786 # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index 7034257068..87f8d87af5 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -d931831ce9d2dea3730f33afc046e159ad886842114831a6bbe56d5b746ab0af +9a74d0c3e78eef9a32775f445ecb3fae76e2f3886b9173a16971d7c7506967fe diff --git a/src/sqlite.h.in b/src/sqlite.h.in index e5ed24efbf..67e03ef387 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -4922,12 +4922,15 @@ typedef struct sqlite3_context sqlite3_context; ** object and pointer to it must remain valid until then. ^SQLite will then ** manage the lifetime of its private copy. ** -** ^The sixth argument to sqlite3_bind_text64() must be one of +** ^The sixth argument (the E argument) +** to sqlite3_bind_text64(S,K,Z,N,D,E) must be one of ** [SQLITE_UTF8], [SQLITE_UTF8_ZT], [SQLITE_UTF16], [SQLITE_UTF16BE], ** or [SQLITE_UTF16LE] to specify the encoding of the text in the -** third parameter. The special value [SQLITE_UTF8_ZT] means that the -** string argument is both UTF-8 encoded and is zero-terminated. If -** the sixth argument to sqlite3_bind_text64() is not one of the +** third parameter, Z. The special value [SQLITE_UTF8_ZT] means that the +** string argument is both UTF-8 encoded and is zero-terminated. In other +** words, SQLITE_UTF8_ZT means that the Z array is allocated to hold at +** least N+1 bytes and that the Z[N] byte is zero. If +** the E argument to sqlite3_bind_text64(S,K,Z,N,D,E) is not one of the ** allowed values shown above, or if the text encoding is different ** from the encoding specified by the sixth parameter, then the behavior ** is undefined. @@ -5794,6 +5797,51 @@ int sqlite3_create_window_function( ** ** These constants define integer codes that represent the various ** text encodings supported by SQLite. +** +**
+** [[SQLITE_UTF8]]
SQLITE_UTF8
Text is encoding as UTF-8
+** +** [[SQLITE_UTF16LE]]
SQLITE_UTF16LE
Text is encoding as UTF-16 +** with each code point being expressed "little endian" - the least significant +** byte first. This is the usual encoding, for example on Windows.
+** +** [[SQLITE_UTF16BE]]
SQLITE_UTF16BE
Text is encoding as UTF-16 +** with each code point being expressed "big endian" - the most significant +** byte first. This encoding is less common, but is still sometimes seen, +** specially on older systems. +** +** [[SQLITE_UTF16]]
SQLITE_UTF16
Text is encoding as UTF-16 +** with each code point being expressed either little endian or as big +** endian, according to the native endianness of the host computer. +** +** [[SQLITE_ANY]]
SQLITE_ANY
This encoding value may only be used +** to declare the preferred text for [application-defined SQL functions] +** created using [sqlite3_create_function()] and similar. If the preferred +** encoding (the 4th parameter to sqlite3_create_function() - the eTextRep +** parameter) is SQLITE_ANY, that indicates that the function does not have +** a preference regarding the text encoding of its parameters and can take +** any text encoding that the SQLite core find convenient to supply. This +** option is deprecated. Please do not use it in new applications. +** +** [[SQLITE_UTF16_ALIGNED]]
SQLITE_UTF16_ALIGNED
This encoding +** value may be used as the 3rd parameter (the eTextRep parameter) to +** [sqlite3_create_collation()] and similar. This encoding value means +** that the application-defined collating sequence created expects its +** input strings to be in UTF16 in native byte order, and that the start +** of the strings must be aligned to a 2-byte boundary. +** +** [[SQLITE_UTF8_ZT]]
SQLITE_UTF8_ZT
This option can only be +** used to specify the text encoding to strings input to [sqlite3_result_text64()] +** and [sqlite3_bind_text64()]. It means that the input string (call it "z") +** is UTF-8 encoded and that it is zero-terminated. If the length parameter +** (call it "n") is non-negative, this encoding option means that the caller +** guarantees that z array contains at least n+1 bytes and that the z[n] +** byte has a value of zero. +** This option gives the same output as SQLITE_UTF8, but can be more efficient +** by avoiding the need to make a copy of the input string, in some cases. +** However, if z is allocated to hold fewer than n+1 bytes or if the +** z[n] byte is not zero, undefined behavior may result. +**
*/ #define SQLITE_UTF8 1 /* IMP: R-37514-35566 */ #define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */ @@ -6422,12 +6470,14 @@ typedef void (*sqlite3_destructor_type)(void*); ** set the return value of the application-defined function to be ** a text string which is represented as UTF-8, UTF-16 native byte order, ** UTF-16 little endian, or UTF-16 big endian, respectively. -** ^The sqlite3_result_text64() interface sets the return value of an +** ^The sqlite3_result_text64(C,Z,N,D,E) interface sets the return value of an ** application-defined function to be a text string in an encoding -** specified by the fifth (and last) parameter, which must be one +** specified the E parameter, which must be one ** of [SQLITE_UTF8], [SQLITE_UTF8_ZT], [SQLITE_UTF16], [SQLITE_UTF16BE], ** or [SQLITE_UTF16LE]. ^The special value [SQLITE_UTF8_ZT] means that -** the result text is both UTF-8 and zero-terminated. +** the result text is both UTF-8 and zero-terminated. In other words, +** SQLITE_UTF8_ZT means that the Z array holds at least N+1 byes and that +** the Z[N] is zero. ** ^SQLite takes the text result from the application from ** the 2nd parameter of the sqlite3_result_text* interfaces. ** ^If the 3rd parameter to any of the sqlite3_result_text* interfaces @@ -6514,7 +6564,7 @@ void sqlite3_result_int(sqlite3_context*, int); void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); void sqlite3_result_null(sqlite3_context*); void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); -void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64, +void sqlite3_result_text64(sqlite3_context*, const char *z, sqlite3_uint64 n, void(*)(void*), unsigned char encoding); void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));