Add API docs for sqlite3_column_text_v2() and sqlite3_column_blob_v2().

FossilOrigin-Name: 60614fed447270b8342f6ee04f4ed9d5c81393c5344a917820a0a7e571de19a9

diff --git a/manifest b/manifest
index b8caab04c0a17cdb80cfbc9c33c9737cce05c1b1..5abda552ca1a2eee24415be3386f8cf01c9d0384 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Random\sJS\scleanups\sand\sdocs.
-D 2025-07-01T17:38:08.691
+C Add\sAPI\sdocs\sfor\ssqlite3_column_text_v2()\sand\ssqlite3_column_blob_v2().
+D 2025-07-01T18:36:11.756
 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
@@ -787,7 +787,7 @@ F src/resolve.c d40fe18d7c2fd0339f5846ffcf7d6809866e380acdf14c76fb2af87e9fe13f64
 F src/rowset.c 8432130e6c344b3401a8874c3cb49fefe6873fec593294de077afea2dce5ec97
 F src/select.c 882d739e0d5e6c7a8b46a3cca3ada37fe1a56301f1360d6b141312c666bbe482
 F src/shell.c.in 4f14a1f5196b6006abc8e73cc8fd6c1a62cf940396f8ba909d6711f35f074bb6
-F src/sqlite.h.in b8acddc332b0ba20f7e46ada5e99156303ec7470ecafcda4dbc59285e4658bab
+F src/sqlite.h.in 54824d50c69df8f81502fcebc23d407ee09cb7f7ebd951be72b670e6f31298c4
 F src/sqlite3.rc 015537e6ac1eec6c7050e17b616c2ffe6f70fca241835a84a4f0d5937383c479
 F src/sqlite3ext.h 0bfd049bb2088cc44c2ad54f2079d1c6e43091a4e1ce8868779b75f6c1484f1e
 F src/sqliteInt.h 21c089759415895c86220d35c22cd17fdc6ca27653e1ec0c744d1e6808d0545a
@@ -2208,8 +2208,8 @@ F tool/version-info.c 3b36468a90faf1bbd59c65fd0eb66522d9f941eedd364fabccd7227350
 F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7
 F tool/warnings.sh 1ad0169b022b280bcaaf94a7fa231591be96b514230ab5c98fbf15cd7df842dd
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P 4aab781d2abc64a39c53acd0faf6d60bb38afcce42f25bc8c0fa52b73df05312
-R 8e06e1907693b695373176fe3fdc205a
+P 5a2734bbf8b471fa27f8f4b687e4d24f64c7663b823908f1ee8cd21bb93beb98
+R dae4fce04bcce555b325cd0b17ed5060
 U stephan
-Z e3cc89ebfecaca5d22dd5efe42afadb1
+Z 79b34d6cd08aaec438188d7aafa77f7b
 # Remove this line to create a well-formed Fossil manifest.

diff --git a/manifest.uuid b/manifest.uuid
index 89445ade66abb21fbd43bc1609e4a5a8c6c312d6..53643169c862d609a60f85e79b1aa333e5cb0d77 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-5a2734bbf8b471fa27f8f4b687e4d24f64c7663b823908f1ee8cd21bb93beb98
+60614fed447270b8342f6ee04f4ed9d5c81393c5344a917820a0a7e571de19a9

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index c594a54999dba31907cf90200e3595c3701bb441..9a4c1800581f1086be729f9e5f1216ac2c6f0f93 100644 (file)
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -5259,10 +5259,12 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
 ** <b>Summary:</b>
 ** <blockquote><table border=0 cellpadding=0 cellspacing=0>
 ** <tr><td><b>sqlite3_column_blob</b><td>&rarr;<td>BLOB result
+** <tr><td><b>sqlite3_column_blob_v2</b><td>&rarr;<td>BLOB result
 ** <tr><td><b>sqlite3_column_double</b><td>&rarr;<td>REAL result
 ** <tr><td><b>sqlite3_column_int</b><td>&rarr;<td>32-bit INTEGER result
 ** <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result
 ** <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result
+** <tr><td><b>sqlite3_column_text_v2</b><td>&rarr;<td>UTF-8 TEXT result
 ** <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result
 ** <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an
 ** [sqlite3_value|unprotected sqlite3_value] object.
@@ -5287,6 +5289,19 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
 ** ^The number of columns in the result can be determined using
 ** [sqlite3_column_count()].
 **
+** ^The sqlite3_column_text_v2() and sqlite3_column_blob_v2()
+** interfaces deliver most of their output via their 3rd, 4th, and 5th
+** output-pointer arguments. The first is an output pointer to the
+** resulting memory (the same pointer which would be returned by their
+** non-v2 counterparts). The second is an integer pointer into which,
+** if it is not NULL, the length of the memory, in bytes, is
+** written. The 5th argument is an integer pointer which, if not NULL,
+** gets set to the [SQLITE_INTEGER | column's SQL type]. On success
+** these interfaces return 0. On error they do not modify any of their
+** output pointers and return SQLITE_NOMEM on allocation error,
+** SQLITE_MISUSE if either their first or third arguments are NULL,
+** and SQLITE_RANGE if the given column index is out of range.
+**
 ** If the SQL statement does not currently point to a valid row, or if the
 ** column index is out of range, the result is undefined.
 ** These routines may only be called when the most recent call to
@@ -5299,12 +5314,17 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
 ** are called from a different thread while any of these routines
 ** are pending, then the results are undefined.
 **
-** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
+** The interfaces (_blob, _double, _int, _int64, _text, and _text16)
 ** each return the value of a result column in a specific data format.  If
 ** the result column is not initially in the requested format (for example,
 ** if the query returns an integer but the sqlite3_column_text() interface
 ** is used to extract the value) then an automatic type conversion is performed.
 **
+** ^The interfaces (_text_v2, _blob_v2) interally function identically
+** to their non-_v2 counterparts but have different interfaces. Their
+** internal behaviors are the same for purposes of the following
+** documentation except where specifically noted otherwise.
+**
 ** ^The sqlite3_column_type() routine returns the
 ** [SQLITE_INTEGER | datatype code] for the initial data type
 ** of the result column.  ^The returned value is one of [SQLITE_INTEGER],
@@ -5312,7 +5332,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
 ** The return value of sqlite3_column_type() can be used to decide which
 ** of the first six interface should be used to extract the column value.
 ** The value returned by sqlite3_column_type() is only meaningful if no
-** automatic type conversions have occurred for the value in question. 
+** automatic type conversions have occurred for the value in question.
 ** After a type conversion, the result of calling sqlite3_column_type()
 ** is undefined, though harmless.  Future
 ** versions of SQLite may change the behavior of sqlite3_column_type()
@@ -5437,6 +5457,10 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
 ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
 ** with calls to sqlite3_column_bytes().
 **
+** The sqlite3_column_text_v2() and sqlite3_column_blob_v2()
+** interfaces optionally return the byte length and column data type
+** via output pointers.
+**
 ** ^The pointers returned are valid until a type conversion occurs as
 ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
 ** [sqlite3_finalize()] is called.  ^The memory space used to hold strings
@@ -5451,7 +5475,9 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
 **
 ** <ul>
 ** <li> sqlite3_column_blob()
+** <li> sqlite3_column_blob_v2()
 ** <li> sqlite3_column_text()
+** <li> sqlite3_column_text_v2()
 ** <li> sqlite3_column_text16()
 ** <li> sqlite3_column_bytes()
 ** <li> sqlite3_column_bytes16()
@@ -5463,6 +5489,10 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
 ** by invoking the [sqlite3_errcode()] immediately after the suspect
 ** return value is obtained and before any
 ** other SQLite interface is called on the same [database connection].
+**
+** The previous paragraph does not apply to the text_v2 and blob_v2
+** interfaces, which return SQLITE_NOMEM to the client for
+** out-of-memory conditions.
 */
 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
 int sqlite3_column_blob_v2(sqlite3_stmt*, int iCol, const void **, int*, int*);