Значения результата от запроса

const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
double sqlite3_column_double(sqlite3_stmt*, int iCol);
int sqlite3_column_int(sqlite3_stmt*, int iCol);
sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
int sqlite3_column_type(sqlite3_stmt*, int iCol);

Обзор:

sqlite3_column_blob	→	BLOB
sqlite3_column_double	→	REAL
sqlite3_column_int	→	32-bit INTEGER
sqlite3_column_int64	→	64-bit INTEGER
sqlite3_column_text	→	UTF-8 TEXT
sqlite3_column_text16	→	UTF-16 TEXT
sqlite3_column_value	→	Результат как объект unprotected sqlite3_value.
sqlite3_column_bytes	→	Размер результата BLOB или UTF-8 TEXT в байтах
sqlite3_column_bytes16	→	Размер UTF-16 TEXT в байтах
sqlite3_column_type	→	Тип данных по умолчанию для результата

Детали:

Это возвращает информацию об отдельном столбце текущей строки результата запроса. В каждом случае первый аргумент это указатель на подготовленный запрос, который оценивается (sqlite3_stmt*, который был возвращен из sqlite3_prepare_v2() или один из его вариантов), второй аргумент это индекс колонки, для которой должна быть возвращена информация. У крайнего левого столбца набора результатов индекс 0. Количество колонок в результате может быть определено, используя sqlite3_column_count().

Если SQL-оператор в настоящее время не указывает на действительную строку или если индекс столбца вне диапазона, результат не определен. Это можно вызвать только, когда новый запрос к sqlite3_step() вернул SQLITE_ROW и sqlite3_reset() или sqlite3_finalize() не вызвали впоследствии. Если sqlite3_reset(), sqlite3_finalize() или sqlite3_step() вернула что-то кроме SQLITE_ROW, результаты не определены. Если sqlite3_step(), sqlite3_reset() или sqlite3_finalize() вызывают из другого потока в то время как эта процедура выполняется, то результаты не определены.

Первые шесть интерфейсов (_blob, _double, _int, _int64, _text и _text16) возвращает значение столбца результата в определенном формате данных. Если столбец результата не находится первоначально в запрашиваемом формате (например, если запрос возвращает целое число, но sqlite3_column_text() используется, чтобы извлечь значение), тогда выполняется автоматическое преобразование типов.

sqlite3_column_type() вернет код типа данных для типа исходных данных столбца результата. Возвращенное значение одно из SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB или SQLITE_NULL. Возвращаемое значение sqlite3_column_type() может использоваться, чтобы решить, какой из первых шести интерфейсов должен использоваться, чтобы извлечь значение столбца. Значение, возвращенное sqlite3_column_type(), значащее только если никакие автоматические преобразования типов не произошли для рассматриваемого значения. После преобразования типов результат запроса sqlite3_column_type() не определен, хотя безопасен. Будущие версии SQLite могут изменить поведение sqlite3_column_type() после преобразования типов.

Если результат BLOB или TEXT, sqlite3_column_bytes() или sqlite3_column_bytes16() может использоваться, чтобы определить размер того BLOB или последовательности.

Если результат BLOB или строка UTF-8, sqlite3_column_bytes() возвращает число байтов в том BLOB или последовательности. Если результат последовательность UTF-16, то sqlite3_column_bytes() преобразовывает последовательность в UTF-8 и затем возвращает число байтов. Если результат числовое значение, тогда sqlite3_column_bytes() применяет sqlite3_snprintf(), чтобы преобразовать значение в последовательность UTF-8 и возвращает число байтов в той последовательности. Если результат NULL, то sqlite3_column_bytes() вернет 0.

Если результат BLOB или строка в UTF-16, sqlite3_column_bytes16() возвращает число байтов в том BLOB или последовательности. Если результат последовательность UTF-8, то sqlite3_column_bytes16() преобразовывает последовательность в UTF-16 и затем возвращает число байтов. Если результат числовое значение, тогда sqlite3_column_bytes16() использует sqlite3_snprintf(), чтобы преобразовать значение в последовательность UTF-16 и возвращает число байтов в той последовательности. Если результат NULL, то sqlite3_column_bytes16() вернет 0.

Значения, возвращенные sqlite3_column_bytes() и sqlite3_column_bytes16(), не включают нулевых терминаторов в конце последовательности. Для ясности: значения, возвращенные sqlite3_column_bytes() и sqlite3_column_bytes16(), являются числом байтов в последовательности, но не количеством знаков.

Последовательности, возвращенные sqlite3_column_text() и sqlite3_column_text16(), даже пустые строки, всегда заканчиваются нолем. Возвращаемое значение sqlite3_column_blob() для нулевой длины BLOB является NULL.

У последовательностей, возвращенных sqlite3_column_text16(), всегда есть завершитель, который является родным на платформе, независимо от текстового набора кодирования для базы данных.

Предупреждение: объект, возвращенный sqlite3_column_value(), это объект unprotected sqlite3_value. В многопоточной окружающей среде незащищенный объект sqlite3_value может использоваться безопасно только с sqlite3_bind_value() и sqlite3_result_value(). Если объект unprotected sqlite3_value, возвращенный sqlite3_column_value(), используется каким-либо другим способом, включая вызовы функций вроде sqlite3_value_int(), sqlite3_value_text() или sqlite3_value_bytes(), поведение не ориентировано на многопоточное исполнение. Следовательно, sqlite3_column_value() обычно полезен только в рамках внедрения определяемых SQL-функций или виртуальных таблиц, но не в рамках кода приложения верхнего уровня.

Это может попытаться преобразовать тип данных результата. Например, если внутреннее представление FLOAT и текстовый результат требуют, sqlite3_snprintf() используется внутренне, чтобы выполнить преобразование автоматически. Следующая таблица детализирует преобразования, которые применяются:

Внутренний тип	Тип результата	Преобразование
NULL	INTEGER	Результат 0
NULL	FLOAT	Результат 0.0
NULL	TEXT	Результат NULL
NULL	BLOB	Результат NULL
INTEGER	FLOAT	Преобразование из integer в float
INTEGER	TEXT	Представление ASCII integer
INTEGER	BLOB	Ааналогично INTEGER->TEXT
FLOAT	INTEGER	CAST в INTEGER
FLOAT	TEXT	Представление ASCII float
FLOAT	BLOB	CAST в BLOB
TEXT	INTEGER	CAST в INTEGER
TEXT	FLOAT	CAST в REAL
TEXT	BLOB	Без изменений
BLOB	INTEGER	CAST в INTEGER
BLOB	FLOAT	CAST в REAL
BLOB	TEXT	CAST в TEXT, гарантируйте нулевой терминатор

Обратите внимание на то, что, когда преобразования типов происходят, указатели, возвращенные предшествующими sqlite3_column_blob(), sqlite3_column_text() и/или sqlite3_column_text16(), могут быть лишены законной силы. Преобразования типов и аннулирование указателя могли бы произойти в следующих случаях:

• Начальное содержание BLOB и вызвана sqlite3_column_text() или sqlite3_column_text16(). Нулевой терминатор, возможно, должен был быть добавлен к последовательности.
• Начальное содержание текст в UTF-8 м вызвана sqlite3_column_bytes16() или sqlite3_column_text16(). Содержание должно быть преобразовано в UTF-16.
• Начальное содержание текст в UTF-16 и вызвана sqlite3_column_bytes() или sqlite3_column_text(). Содержание должно быть преобразовано в UTF-8.

Преобразования между UTF-16be и UTF-16le всегда делаются на месте и не лишают законной силы обратный указатель, хотя, конечно, содержание буфера будет изменено. Другие виды преобразования сделаны на месте, когда это возможно, но иногда они невозможны, и в тех случаях лишены законной силы обратные указатели.

Самая безопасная политика состоит в том, чтобы вызвать это одним из следующих режимов:

• sqlite3_column_text() сопровождаемый sqlite3_column_bytes()
• sqlite3_column_blob() сопровождаемый sqlite3_column_bytes()
• sqlite3_column_text16() сопровождаемый sqlite3_column_bytes16()

Другими словами, необходимо вызвать sqlite3_column_text(), sqlite3_column_blob() или sqlite3_column_text16() сначала, чтобы привести результат в нужный формат, затем вызвать sqlite3_column_bytes() или sqlite3_column_bytes16(), чтобы найти размер результата. Не смешивайте требования к sqlite3_column_text() или sqlite3_column_blob() с вызовами sqlite3_column_bytes16() и sqlite3_column_text16() с sqlite3_column_bytes().

Возвращенные указатели действительны, пока преобразование типов не происходит, как описано выше, или до вызова sqlite3_step(), sqlite3_reset() или sqlite3_finalize(). Пространство памяти, используемое, чтобы хранить последовательности и BLOB, освобождено автоматически. Не передавайте указатели, возвращенные sqlite3_column_blob(), sqlite3_column_text() и т.д., в sqlite3_free().

Пока входные параметры правильны, это потерпит неудачу, только если ошибка памяти произойдет во время преобразования формата. Только следующее подмножество интерфейсов подвергается ошибкам памяти:

• sqlite3_column_blob()
• sqlite3_column_text()
• sqlite3_column_text16()
• sqlite3_column_bytes()
• sqlite3_column_bytes16()

Если ошибка памяти происходит, то возвращаемое значение такое, как если бы колонка содержала SQL NULL. Действительный SQL NULL можно отличить от ошибок памяти, вызвав sqlite3_errcode() немедленно после того, как подозрительное возвращаемое значение получено и прежде чем любой другой интерфейс SQLite вызовут на том же самом соединении с базой данных.