Valores de resultados desde una consulta

const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes16(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);
int sqlite3_column_type(sqlite3_stmt*, int iCol);
sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);

Estas funciones forman el interfaz de "conjunto de resultados".

Estas funciones devuelven información sobre una columna de una fila de los resultados actuales de una consulta. En todos los casos, el primer argumento es un puntero a la sentencia preparada que se está evaluando (el sqlite3_stmt* que fue devuelto desde un sqlite3_prepare_v2() o una de sus variantes) y el segundo argumento es el índice de la columna cuya información se quiere recuperar. La columna más a la izquierda del conjunto de resultados tiene el índice 0. El número de columnas en el resultado puede ser determinado usando la función sqlite3_column_count().

Si la sentencia SQL no apunta actualmente a una fila válida, o si el índice de la columna está fuera de rango, el resultado es indefinido. Estas funciones sólo pueden ser invocadas cuando la llamada más reciente a sqlite3_step() ha retornado SQLITE_ROW y ni sqlite3_reset() ni sqlite3_finalize() han sido llamadas después. Si cualquiera de estas funciones es invocada después de sqlite3_reset() o sqlite3_finalize() o después de que sqlite3_step() haya devuelto algo diferente que SQLITE_ROW, el resultado queda indefinido. Si sqlite3_step() o sqlite3_reset() o sqlite3_finalize() son invocadas desde un hilo diferente mientras cualquiera de estas funciones está pendiente, los resultados quedan indefinidos.

La función sqlite3_column_type() devuelve el código de tipo de dato para el tipo de datos inicial de la columna del resultados. El valor devuelto es uno entre SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB o SQLITE_NULL. El valor devuelto por sqlite3_column_type() sólo tiene sentido si no se producen conversiones de tipo como los descritos más abajo. Después de una conversión de tipo, el valor retornado por sqlite3_column_type() queda indefinido. Futuras versiones de SQLite pueden modificar este comportamiento de sqlite3_column_type() después de una conversión de tipo.

Si el resultado es un BLOB o una cadena UTF-8 entonces la función sqlite3_column_bytes() devuelve el número de bytes en ese BLOB o cadena. Si el resultado es una cadena UTF-16, entonces sqlite3_column_bytes() convierte la cadena a UTF-8 y después devuelve el número de bytes. Si el resultado es un valor numérico entonces sqlite3_column_bytes() use sqlite3_snprintf() para convertir ese valor a una cadena UTF-8 y devuelve el número de bytes en esa cadena. Si el resultado es NULL, entonces sqlite3_column_bytes() retorna cero.

Si el resultado es un BLOB o una cadena UTF-16 entonces la función sqlite3_column_bytes16() devuelve el número de bytes en ese BLOB o cadena. Si el resultado es una cadena UTF-8, entonces sqlite3_column_bytes16() convierte esa cadena a UTF-16 y devuelve el número de bytes. Si el resultado es un valor numérico, sqlite3_column_bytes16() usa sqlite3_snprintf() para convertir ese valor a una cadena UTF-16 y devuelve el número de bytes de esa cadena. Si el resultado es NULL, entonces sqlite3_column_bytes16() retorna cero.

Los valores devueltos por sqlite3_column_bytes() y sqlite3_column_bytes16() no incluyen los ceros terminadores al final de la cadena. Por claridad: los valores retornados por sqlite3_column_bytes() y sqlite3_column_bytes16() son el número de bytes en la cadena, no el número de caracteres.

Las cadenas devueltas por sqlite3_column_text() y sqlite3_column_text16(), incluso las cadenas vacías, están siempre terminadas con cero. El valor de retorno desde sqlite3_column_blob() para un BLOB de longitud nula es un puntero NULL.

El objeto devuelto por sqlite3_column_value() es un objeto sqlite3_value no protegido. Un objeto sqlite3_value no protegido sólo puede ser usado con sqlite3_bind_value() y sqlite3_result_value(). Si el objeto sqlite3_value no protegido retornado por sqlite3_column_value() se usa de otro modo, incluyendo llamadas a funciones como sqlite3_value_int(), sqlite3_value_text() o sqlite3_value_bytes(), entonces el comportamiento es indefinido.

Estas funciones intentan convertir el valor donde resulta apropiado. Por ejemplo, si la representación interna es FLOAT y se requiere un resultado de texto, se usa internamente sqlite3_snprintf() para realizar la conversión automáticamente. La siguiente tabla detalla las conversiones que se aplican:

La tabla anterior hace referencia a las funciones de librería estándar C atoi() y atof(). SQLite no usa realmente esas funciones. Tiene sus propias funciones internas equivalentes. Los nombres atoi() y atof() se usan en la tabla para abreviar y porque son familiares a los programadores de C.

Hay que tener en cuenta que cuando se producen conversiones de tipo, los punteros devueltos por llamadas previas a sqlite3_column_blob(), sqlite3_column_text() y/o sqlite3_column_text16() pueden ser invalidados. Las conversiones de tipo e invalidaciones de puntero pueden ocurrir en los siguientes casos:

• El contenido inicial es un BLOB y se llama a sqlite3_column_text() o sqlite3_column_text16(). Puede ser necesario añadir un terminador cero a la cadena.
• El contenido incial es un texto UTF-8 y se invoca a sqlite3_column_bytes16() o sqlite3_column_text16(). El contenido debe ser convertido a UTF-16.
• El contenido inicial es un texto UTF-16 y se invoca a sqlite3_column_bytes() o sqlite3_column_text(). El contenido debe ser convertido a UTF-8.

Las conversiones entre UTF-16be y UTF-16le siempre se realizan en el mismo sitio y no invalidan el puntero previo, aunque por supuesto el contenido del buffer al que el puntero previo hace referencia se habrá modificado. Otros tipos de conversiones también se hacen en el mismo sitio cuando es posible, pero algunas veces eso no es posible y en esos casos los punteros previos son invalidados.

La política más segura y sencilla de recordar es invocar estar rutinas de una de las siguientes formas:

• sqlite3_column_text() seguido por sqlite3_column_bytes().
• sqlite3_column_blob() seguido por sqlite3_column_bytes().
• sqlite3_column_text16() seguido por sqlite3_column_bytes16().

En otras palabras, se debe invocar a sqlite3_column_text(), sqlite3_column_blob() o sqlite3_column_text16() primero para forzar el resultado al formato deseado, y después a sqlite3_column_bytes() o sqlite3_column_bytes16() para encontrar el tamaño del resultado. No se deben mezclar llamadas a sqlite3_column_text() o sqlite3_column_blob() con llamadas a sqlite3_column_bytes16(), ni llamadas a sqlite3_column_text16() con sqlite3_column_bytes().

Los punteros devueltos son válidos hasta que se produce una conversión de tipo como las descritas antes, o hasta que se invoca a sqlite3_step(), sqlite3_reset() o sqlite3_finalize(). El espacio de memoria usado para contener cadenas y BLOBs se libera de forma automática. No se deben pasar los punteros retornados por sqlite3_column_blob(), sqlite3_column_text(), etc. a sqlite3_free().

Si se produce un error de reserva de memoria durante la evaluación de cualquiera de estas funciones, se devuelve un valor por defecto. Ese valor por defecto es el entero 0, el número en coma flotante 0.0 o un puntero NULL. Subsiguientes llamadas a sqlite3_errcode() retornarán con SQLITE_NOMEM.