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

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 result 


sqlite3_column_double
→
REAL result 


sqlite3_column_int
→
32-bit INTEGER result 


sqlite3_column_int64
→
64-bit INTEGER result 


sqlite3_column_text
→
UTF-8 TEXT result 


sqlite3_column_text16
→
UTF-16 TEXT result 


sqlite3_column_value
→
The result as an unprotected sqlite3_value object. 


 
 
 


sqlite3_column_bytes
→
Size of a BLOB or a UTF-8 TEXT result in bytes 



sqlite3_column_bytes16  
→ 
Size of UTF-16 TEXT in bytes 


sqlite3_column_type
→
Default datatype of the result 

Подробности:

Эти функции возвращают информацию об одном столбце текущей строки результата запроса. В каждом случае первый аргумент — указатель на подготовленное выражение, которое оценивается (значение 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() возвращает ноль.

Если результатом является 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() возвращает ноль.

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

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

Внутренний Тип	Запрошенный Тип	Преобразование
NULL	INTEGER	Результат 0
NULL	FLOAT	Результат 0.0
NULL	TEXT	Результат — указатель NULL
NULL	BLOB	Результат — указатель NULL
INTEGER	FLOAT	Преобразование из целого в вещественное
INTEGER	TEXT	ASCII-представление целого числа
INTEGER	BLOB	То же, что INTEGER->TEXT
FLOAT	INTEGER	ПРЕОБРАЗОВАНИЕ в INTEGER
FLOAT	TEXT	ASCII-представление вещественного числа
FLOAT	BLOB	ПРЕОБРАЗОВАНИЕ в BLOB
TEXT	INTEGER	ПРЕОБРАЗОВАНИЕ в INTEGER
TEXT	FLOAT	ПРЕОБРАЗОВАНИЕ в REAL
TEXT	BLOB	Без изменений
BLOB	INTEGER	ПРЕОБРАЗОВАНИЕ в INTEGER
BLOB	FLOAT	ПРЕОБРАЗОВАНИЕ в REAL
BLOB	TEXT	ПРЕОБРАЗОВАНИЕ в 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 для того же соединения с базой данных.

См. также списки Объектов, Констант и Функций.