Formatted String Printing Functions

char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*, va_list);
char *sqlite3_snprintf(int,char*,const char*, ...);
char *sqlite3_vsnprintf(int,char*,const char*, va_list);

Estas funciones imitan la forma de trabajar de la familia de funciones "fprintf()" de la biblioteca estándar C.

Las funciones sqlite3_mprintf() y sqlite3_vmprintf() escriben sus resultados en la memoria obtenida por sqlite3_malloc(). Las cadenas retornadas por estas dos funciones deben ser liberadas por sqlite3_free(). Ambas funciones devuelven un puntero NULL si sqlite3_malloc() es incapaz de obteber suficiente memoria para contener la cadena resultante.

La función sqlite3_snprintf() es similar a "snprintf()" de la biblioteca estándar C. El resultado se escribe en el buffer suministrado como segundo parámetro cuyo tamaño viene dado por el primer parámetro. Hay que tener en cuenta que el orden de los primeros dos parámetros es el contrario que en snprintf(). Esto es un accidente histórico que no puede ser corregido sin romper la compatibilidad hacia atrás. Hay que tener en cuenta que sqlite3_snprintf() devuelve un puntero a su buffer en lugar del número de caracteres actualmente escritos en el buffer. Admitimos que el número de caracteres escritos sería un valor de retorno más útil, pero no podemos cambiar la implementación de sqlite3_snprintf() ahora sin romper la compatibilidad hacia atrás.

Siempre que el tamaño del buffer sea mayor que cero, sqlite3_snprintf() garantiza que ese buffer será siempre terminado con cero. El primer parámetro "n" es el tamaño total del buffer, incluyendo el espacio para el cero terminador. De modo que la cadena más larga que puede ser escrita completamente tendrá n-1 caracteres.

La función sqlite3_vsnprintf() es una versión de número de argumentos variable de sqlite3_snprintf().

Todas estas funciones implementan algunas opciones de formato adicionales que son útiles para construir sentencias SQL. Todas las opciones de formato habituales de fprintf() son aplicacbles. Además, existen las opciones "%q", "%Q" y "%z".

La opción %q funciona como %s en la que sustituye a una cadena terminada con cero de la lista de argumentos. Pero %q también dobla todos los caracteres '\''. %q está diseñado para usarse dentro de una cadena literal. Al duplicar cada carácter '\'' se escapa ese carácter y permite que sea insertado en la cadena.

Por ejemplo, supongamos que la variable de cadena zText contiene el siguiente texto:

    char *zText = "It's a happy day!";

Se puede usar este texto en una sentencia SQL de este modo:

    char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
    sqlite3_exec(db, zSQL, 0, 0, 0);
    sqlite3_free(zSQL);

Como se ha usado el formato de cadena %q, el carácter '\'' en zText está escapado y el SQL generado de esta forma:

    INSERT INTO table1 VALUES('It''s a happy day!')

Esto es correcto. Si hubiéramos usado %s en lugar de %q, el SQL generado habría parecido como esto:

    INSERT INTO table1 VALUES('It's a happy day!');

Este segundo ejemplo es un error de sintaxis SQL. Como regla general se debe usar siempre %q en lugar de %s cuando se inserte texto en una cadena literal.

La opción %Q funciona como %q excepto que también añade comillas sencillas a los extremos de la cadena completa. Adicionalmente, si el parámetro en la lista de argumentos es un puntero NULL, %Q lo sustituye por el texto "NULL" (sin comillas simples). Así, por ejemplo, se podría decir:

    char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
    sqlite3_exec(db, zSQL, 0, 0, 0);
    sqlite3_free(zSQL);

El código anterior generará una sentencia SQL correcta en la variable zSQL incluso si la variable zText es un puntero NULL.

La opción de formato "%z" funciona como "%s" pero con el añadido de que la cadena ha sido leída y copiada en el resultado, se invoca a sqlite3_free() para la cadena de entrada.