From: drh Date: Wed, 8 Sep 2010 16:30:36 +0000 (+0000) Subject: Updates to the documentation of the sqlite3_column_xxxx() family of X-Git-Tag: experimental~58 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=42262536dd31ee0a66065ae7cba03ab71a7e1c42;p=thirdparty%2Fsqlite.git Updates to the documentation of the sqlite3_column_xxxx() family of interfaces. Enhance sqlite3_column_blob() so that it always returns a NULL pointer for a zero-length blob. FossilOrigin-Name: a932fab299b3c32dea4d08729e9fab3735631e88 --- diff --git a/manifest b/manifest index 54814e3a16..7ed957fb5d 100644 --- a/manifest +++ b/manifest @@ -1,8 +1,8 @@ -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 -C Improved\sdocumentation\sof\sSQLITE_THREADSAFE\sand\ssqlite3_column_text()\sand\nevidence\smarks\sfor\seach. -D 2010-09-08T02:30:28 +C Updates\sto\sthe\sdocumentation\sof\sthe\ssqlite3_column_xxxx()\sfamily\sof\s\ninterfaces.\s\sEnhance\ssqlite3_column_blob()\sso\sthat\sit\salways\sreturns\na\sNULL\spointer\sfor\sa\szero-length\sblob. +D 2010-09-08T16:30:36 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f F Makefile.in c599a15d268b1db2aeadea19df2adc3bf2eb6bee F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23 @@ -177,7 +177,7 @@ F src/resolve.c 1c0f32b64f8e3f555fe1f732f9d6f501a7f05706 F src/rowset.c 69afa95a97c524ba6faf3805e717b5b7ae85a697 F src/select.c b0b124781474e4e0c8f64022875e5e2009e13443 F src/shell.c 8517fc1f9c59ae4007e6cc8b9af91ab231ea2056 -F src/sqlite.h.in fef9e187420e234ecc45962f76dfb30065c3ba34 +F src/sqlite.h.in 0e98e780993e6cf185bd228f275b959a5aef86c6 F src/sqlite3ext.h 69dfb8116af51b84a029cddb3b35062354270c89 F src/sqliteInt.h 81343db96497aebf81dff9c695dfd29699b377b3 F src/sqliteLimit.h a17dcd3fb775d63b64a43a55c54cb282f9726f44 @@ -230,7 +230,7 @@ F src/vacuum.c 241a8386727c1497eba4955933356dfba6ff8c9f F src/vdbe.c 1373d40f5985577a30350bfa78ebd8e1d905ee89 F src/vdbe.h 4de0efb4b0fdaaa900cf419b35c458933ef1c6d2 F src/vdbeInt.h a247bd5448039e83394bf4179975b2ae0092874c -F src/vdbeapi.c bec07756e1b3ec5cd054ce8d32a80787763fd07e +F src/vdbeapi.c 27f7696bc0d39da015fa3a72e3b6b31739cbdafb F src/vdbeaux.c de0b06b11a25293e820a49159eca9f1c51a64716 F src/vdbeblob.c 258a6010ba7a82b72b327fb24c55790655689256 F src/vdbemem.c 2b8210992499e8b846f49fa4b0035bbc2cda0ee0 @@ -860,14 +860,14 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f -P 1719cb8f49bb138adcf8913a2d042f9e1360d78a -R c02a8afe877c3b4735aad82e9e1cadd9 +P 0d7a53894866e536616e78473d253a9e9c29b1bc +R 51026716a628a7a25e271fee3df25f2c U drh -Z dd26d0f574b1e7dcc096acc18183ba83 +Z 13e058a965b93f562989a9839c193073 -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) -iD8DBQFMhvVHoxKgR168RlERAv4lAJ9vCMPF+E5e9IKquuoenoU4ncqrVACfbdGF -gqJcjtsQZK5C/LI3fg/MDHk= -=+5zW +iD8DBQFMh7owoxKgR168RlERAkV8AJ9Ukueu9Qrvz3/93BoncIePAKQpvwCgjd2V +P4MfWrwxvce8oX2rzijVHeE= +=by21 -----END PGP SIGNATURE----- diff --git a/manifest.uuid b/manifest.uuid index 97bca093a2..41c86e3fee 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -0d7a53894866e536616e78473d253a9e9c29b1bc \ No newline at end of file +a932fab299b3c32dea4d08729e9fab3735631e88 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 4472aca496..7cfcc8dd75 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -3111,18 +3111,26 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); ** ^If the result is a numeric value then sqlite3_column_bytes() uses ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns ** the number of bytes in that string. -** ^The value returned does not include the zero terminator at the end -** of the string. ^For clarity: the value returned is the number of +** ^If the result is NULL, then sqlite3_column_bytes() returns zero. +** +** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16() +** routine returns the number of bytes in that BLOB or string. +** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts +** the string to UTF-16 and then returns the number of bytes. +** ^If the result is a numeric value then sqlite3_column_bytes16() uses +** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns +** the number of bytes in that string. +** ^If the result is NULL, then sqlite3_column_bytes16() returns zero. +** +** ^The values returned by [sqlite3_column_bytes()] and +** [sqlite3_column_bytes16()] do not include the zero terminators at the end +** of the string. ^For clarity: the values returned by +** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of ** bytes in the string, not the number of characters. ** ** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(), ** even empty strings, are always zero terminated. ^The return -** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary -** pointer, possibly even a NULL pointer. -** -** ^The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() -** but leaves the result in UTF-16 in native byte order instead of UTF-8. -** ^The zero terminator is not included in this count. +** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer. ** ** ^The object returned by [sqlite3_column_value()] is an ** [unprotected sqlite3_value] object. An unprotected sqlite3_value object @@ -3167,10 +3175,10 @@ int sqlite3_data_count(sqlite3_stmt *pStmt); ** used in the table for brevity and because they are familiar to most ** C programmers. ** -** ^Note that when type conversions occur, pointers returned by prior +** Note that when type conversions occur, pointers returned by prior ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or ** sqlite3_column_text16() may be invalidated. -** ^(Type conversions and pointer invalidations might occur +** Type conversions and pointer invalidations might occur ** in the following cases: ** ** )^ +** ** ** ^Conversions between UTF-16be and UTF-16le are always done in place and do ** not invalidate a prior pointer, though of course the content of the buffer -** that the prior pointer points to will have been modified. Other kinds +** that the prior pointer references will have been modified. Other kinds ** of conversion are done in place when it is possible, but sometimes they ** are not possible and in those cases prior pointers are invalidated. ** -** ^(The safest and easiest to remember policy is to invoke these routines +** The safest and easiest to remember policy is to invoke these routines ** in one of the following ways: ** ** )^ +** ** ** In other words, you should call sqlite3_column_text(), ** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result diff --git a/src/vdbeapi.c b/src/vdbeapi.c index 256828e807..04fc3eede1 100644 --- a/src/vdbeapi.c +++ b/src/vdbeapi.c @@ -141,7 +141,7 @@ const void *sqlite3_value_blob(sqlite3_value *pVal){ sqlite3VdbeMemExpandBlob(p); p->flags &= ~MEM_Str; p->flags |= MEM_Blob; - return p->z; + return p->n ? p->z : 0; }else{ return sqlite3_value_text(pVal); } @@ -710,8 +710,7 @@ static Mem *columnMem(sqlite3_stmt *pStmt, int i){ ** sqlite3_column_real() ** sqlite3_column_bytes() ** sqlite3_column_bytes16() -** -** But not for sqlite3_column_blob(), which never calls malloc(). +** sqiite3_column_blob() */ static void columnMallocFailure(sqlite3_stmt *pStmt) {