sqlite.h


Define New Collating Sequences

int sqlite3_create_collation(
  sqlite3*, 
  const char *zName, 
  int eTextRep, 
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*)
);
int sqlite3_create_collation_v2(
  sqlite3*, 
  const char *zName, 
  int eTextRep, 
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*),
  void(*xDestroy)(void*)
);
int sqlite3_create_collation16(
  sqlite3*, 
  const void *zName,
  int eTextRep, 
  void *pArg,
  int(*xCompare)(void*,int,const void*,int,const void*)
);

Estas funciones añaden, elimina o modifican una función de comparación asociada con una conexión de base de datos especificada en el primer argumento.

El nombre de la función de comparación es una cadena UTF-8 para sqlite3_create_collation() y sqlite3_create_collation_v2(), y una cadena UTF-16 en orden de bytes nativo para sqlite3_create_collation16(). Los nombres de secuencias de comparación que se consideran iguales cuando se comparan con sqlite3_strnicmp() se consideran el mismo nombre.

El tercer argumento eTextRep debe ser una de las siguientes constantes:

  • SQLITE_UTF8,
  • SQLITE_UTF16LE,
  • SQLITE_UTF16BE,
  • SQLITE_UTF16 o
  • SQLITE_UTF16_ALIGNED.

El argumento eTextRep determina la codificación de las cadenas pasadas a la función de retrollamada de comparación, xCallback. Los valores SQLITE_UTF16 y SQLITE_UTF16_ALIGNED para eTextRep fuerza a las cadenas a ser UTF-16 en orden de bytes nativo. El valor SQLITE_UTF16_ALIGNED para eTextRep fuerza a las cadenas a empezar en una dirección de memoria par.

El cuarto argumento, pArg, es un puntero a datos de la aplicación que es pasado a través del primer argumento a la función de retrollamada de comparación.

El quinto argumento, xCallback, es un puntero a la función de comparación. Se pueden registrar múltiples funciones de comparación usando el mismo nombre pero con diferentes parámetros eTextRep y SQLite usará aquella función que requiera la menor cantidad de datos de transformación. Si el argumento xCallback es NULL entonces la función de comparación se elimina. Entonces todas las funciones de comparación que tengan el mismo nombre se eliminan, y esa comparación no puede seguir usándose.

La función de retrollamada de comparación es invocada con una copia del puntero de datos de aplicación pArg y con dos cadenas en la codificación especificada por el argumento eTextRep. La función de comparación debe retornar un entero que es negativo, cero o positivo si la primera cadena es menor que, igual a o mayor que el segundo, repectivamente. Una función de comparación debe devolver siempre el mismo resultado para las mismas entradas. Si dos o más funciones de comparación están registradas con el mismo nombre (usando distintos valores de eTextRep) entonces todas deben dar una respuesta equivalente cuando sean invocadas con cadenas equivalentes. La función de comparación debe obedecer las siguientes propiedades para todas las cadenas A, B y C.

  1. Si A==B entonces B==A.
  2. Si A==B y B==C entonces A==C.
  3. Si A<B entonces B>A.
  4. Si A<B y B<C entonces A<C.

Si una función de comparación falla en cualquiera de las pasa alguna de las limitaciones anteriores y la función de comparación ha sido registrada y usada, el comportamiento de SQLite queda indefinido.

La función sqlite3_create_collation_v2() funciona como sqlite3_create_collation() con el añadido de que la retrollamada xDestroy es invocada con pArg cuando la función de comparación es borrada. Las funciones de comparación son borradas cuando son reemplazadas por llamadas posteriores a funciones de creación de comparaciones o cuando la conexión de la base de datos es cerrada usando sqlite3_close().

La retrollamada xDestroy no es invocada si la función sqlite3_create_collation_v2() falla. Las aplicaciones que invocan sqlite3_create_collation_v2() con un argumento xDestroy no NULL deben comprobar el valor de retorno y disponer del puntero de datos de la aplicación por si mismo en lugar de esperar que SQLite lo haga. Esto es diferente que en todos los otros casos de funciones de SQLite. La inconsistencia es desafortunada pero no puede ser cambiada sin romper la compatibilidad hacia atrás.

Ver también: sqlite3_collation_needed() y sqlite3_collation_needed16().