/ Check-in [f1aa951a]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Improvements to documentation of the sqlite3_column_xxxxx() interfaces. No code changes.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: f1aa951a337037c18ee14e114e36314835e05926
User & Date: drh 2015-05-12 13:32:55
Context
2015-05-12
14:22
Fix a compiler warning when building with tclsqlite3.c and without SQLITE_ENABLE_DBSTAT_VTAB. check-in: aad3ff25 user: drh tags: trunk
13:32
Improvements to documentation of the sqlite3_column_xxxxx() interfaces. No code changes. check-in: f1aa951a user: drh tags: trunk
12:24
Try to get recent sqlite3_analyzer and sqldiff tests working for all tested combinations of compile-time options, especially SQLITE_OMIT_VIRTUALTABLE and SQLITE_OMIT_LOAD_EXTENSION. check-in: 07c7d392 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  3889   3889   #define SQLITE3_TEXT     3
  3890   3890   
  3891   3891   /*
  3892   3892   ** CAPI3REF: Result Values From A Query
  3893   3893   ** KEYWORDS: {column access functions}
  3894   3894   ** METHOD: sqlite3_stmt
  3895   3895   **
  3896         -** These routines form the "result set" interface.
  3897         -**
  3898   3896   ** ^These routines return information about a single column of the current
  3899   3897   ** result row of a query.  ^In every case the first argument is a pointer
  3900   3898   ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
  3901   3899   ** that was returned from [sqlite3_prepare_v2()] or one of its variants)
  3902   3900   ** and the second argument is the index of the column for which information
  3903   3901   ** should be returned. ^The leftmost column of the result set has the index 0.
  3904   3902   ** ^The number of columns in the result can be determined using
................................................................................
  3950   3948   ** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
  3951   3949   ** bytes in the string, not the number of characters.
  3952   3950   **
  3953   3951   ** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
  3954   3952   ** even empty strings, are always zero-terminated.  ^The return
  3955   3953   ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
  3956   3954   **
  3957         -** ^The object returned by [sqlite3_column_value()] is an
  3958         -** [unprotected sqlite3_value] object.  An unprotected sqlite3_value object
  3959         -** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
         3955  +** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
         3956  +** [unprotected sqlite3_value] object.  In a multithreaded environment,
         3957  +** an unprotected sqlite3_value object may only be used safely with
         3958  +** [sqlite3_bind_value()] and [sqlite3_result_value()].
  3960   3959   ** If the [unprotected sqlite3_value] object returned by
  3961   3960   ** [sqlite3_column_value()] is used in any other way, including calls
  3962   3961   ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
  3963         -** or [sqlite3_value_bytes()], then the behavior is undefined.
         3962  +** or [sqlite3_value_bytes()], the behavior is not threadsafe.
  3964   3963   **
  3965   3964   ** These routines attempt to convert the value where appropriate.  ^For
  3966   3965   ** example, if the internal representation is FLOAT and a text result
  3967   3966   ** is requested, [sqlite3_snprintf()] is used internally to perform the
  3968   3967   ** conversion automatically.  ^(The following table details the conversions
  3969   3968   ** that are applied:
  3970   3969   **
................................................................................
  3987   3986   ** <tr><td>  TEXT    <td>   BLOB    <td> No change
  3988   3987   ** <tr><td>  BLOB    <td> INTEGER   <td> [CAST] to INTEGER
  3989   3988   ** <tr><td>  BLOB    <td>  FLOAT    <td> [CAST] to REAL
  3990   3989   ** <tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed
  3991   3990   ** </table>
  3992   3991   ** </blockquote>)^
  3993   3992   **
  3994         -** The table above makes reference to standard C library functions atoi()
  3995         -** and atof().  SQLite does not really use these functions.  It has its
  3996         -** own equivalent internal routines.  The atoi() and atof() names are
  3997         -** used in the table for brevity and because they are familiar to most
  3998         -** C programmers.
  3999         -**
  4000   3993   ** Note that when type conversions occur, pointers returned by prior
  4001   3994   ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
  4002   3995   ** sqlite3_column_text16() may be invalidated.
  4003   3996   ** Type conversions and pointer invalidations might occur
  4004   3997   ** in the following cases:
  4005   3998   **
  4006   3999   ** <ul>
................................................................................
  4017   4010   **
  4018   4011   ** ^Conversions between UTF-16be and UTF-16le are always done in place and do
  4019   4012   ** not invalidate a prior pointer, though of course the content of the buffer
  4020   4013   ** that the prior pointer references will have been modified.  Other kinds
  4021   4014   ** of conversion are done in place when it is possible, but sometimes they
  4022   4015   ** are not possible and in those cases prior pointers are invalidated.
  4023   4016   **
  4024         -** The safest and easiest to remember policy is to invoke these routines
         4017  +** The safest policy is to invoke these routines
  4025   4018   ** in one of the following ways:
  4026   4019   **
  4027   4020   ** <ul>
  4028   4021   **  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
  4029   4022   **  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
  4030   4023   **  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
  4031   4024   ** </ul>
................................................................................
  4037   4030   ** to sqlite3_column_text() or sqlite3_column_blob() with calls to
  4038   4031   ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
  4039   4032   ** with calls to sqlite3_column_bytes().
  4040   4033   **
  4041   4034   ** ^The pointers returned are valid until a type conversion occurs as
  4042   4035   ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
  4043   4036   ** [sqlite3_finalize()] is called.  ^The memory space used to hold strings
  4044         -** and BLOBs is freed automatically.  Do <b>not</b> pass the pointers returned
         4037  +** and BLOBs is freed automatically.  Do <em>not</em> pass the pointers returned
  4045   4038   ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
  4046   4039   ** [sqlite3_free()].
  4047   4040   **
  4048   4041   ** ^(If a memory allocation error occurs during the evaluation of any
  4049   4042   ** of these routines, a default value is returned.  The default value
  4050   4043   ** is either the integer 0, the floating point number 0.0, or a NULL
  4051   4044   ** pointer.  Subsequent calls to [sqlite3_errcode()] will return