定義新的排序序列 (定義新的定序序列)

小巧、快速、可靠。
選擇其中三項。(擇三)

SQLite C 介面

定義新的排序序列 (定義新的定序序列)

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*)
);

這些函式會新增、移除或修改與第一個參數指定的資料庫連線相關聯的排序規則 (定序規則)。

排序規則的名稱為 sqlite3_create_collation() 和 sqlite3_create_collation_v2() 的 UTF-8 字串，以及 sqlite3_create_collation16() 的原生位元組順序 UTF-16 字串。根據 sqlite3_strnicmp() 比較相等的排序規則名稱會被視為相同的名稱。

第三個參數 (eTextRep) 必須是以下常數之一：

eTextRep 參數決定傳遞至排序函式回呼 xCompare 的字串編碼。SQLITE_UTF16 和 SQLITE_UTF16_ALIGNED 的 eTextRep 值會強制字串使用原生位元組順序的 UTF16。 SQLITE_UTF16_ALIGNED 的 eTextRep 值會強制字串從偶數位元組位址開始。

第四個參數 pArg 是一個應用程式資料指標，它會作為排序函式回呼的第一個參數傳遞。

第五個參數 xCompare 是指向排序函式的指標。可以使用相同的名稱但不同的 eTextRep 參數註冊多個排序函式，SQLite 將使用需要最少資料轉換的函式。如果 xCompare 參數為 NULL，則排序函式會被刪除。當所有具有相同名稱的排序函式都被刪除時，該排序規則將無法再使用。

排序函式回呼會使用 pArg 應用程式資料指標的副本以及以 eTextRep 參數指定的編碼的兩個字串來呼叫。排序函式回呼的兩個整數參數是兩個字串的長度（以位元組為單位）。如果第一個字串小於、等於或大於第二個字串，則排序函式必須分別返回負整數、零或正整數。排序函式在給定相同輸入的情況下必須始終返回相同的答案。如果兩個或多個排序函式註冊到相同的排序規則名稱（使用不同的 eTextRep 值），則在使用等效字串呼叫時，所有函式都必須提供等效的答案。排序函式必須遵守所有字串 A、B 和 C 的以下屬性：

如果 A==B，則 B==A。
如果 A==B 且 B==C，則 A==C。
如果 A<B，則 B>A。
如果 A<B 且 B<C，則 A<C。

如果排序函式未能滿足上述任何約束，並且該排序函式已註冊並使用，則 SQLite 的行為未定義。

sqlite3_create_collation_v2() 的作用類似於 sqlite3_create_collation()，此外，當排序函式被刪除時，會在 pArg 上呼叫 xDestroy 回呼。當排序函式被後續呼叫排序建立函式覆蓋或使用 sqlite3_close() 關閉資料庫連線時，排序函式會被刪除。

如果 sqlite3_create_collation_v2() 函式失敗，則不會呼叫 xDestroy 回呼。使用非 NULL xDestroy 參數呼叫 sqlite3_create_collation_v2() 的應用程式應檢查返回碼並自行處理應用程式資料指標，而不是期望 SQLite 為它們處理。這與其他所有 SQLite 介面都不同。這種不一致性令人遺憾，但在不破壞向後相容性的情況下無法更改。

另請參閱：sqlite3_collation_needed() 和 sqlite3_collation_needed16()。

另請參閱物件、常數和函式列表。