Libscws C API 使用說明

Libscws C API 使用說明


Libscws - 0.0.1 C API 說明
0. 概述
Libscws 代碼是當前 SCWS(簡易中文分詞) 算法使用C語言編寫的鏈接庫，目前僅基於 Unix 族的操作系統，可能必須適當修改才能運行在 Windows 平臺中。這套 scws 庫沒有外部擴展依賴，代碼力爭簡潔高效，針對分詞詞典組織上做了一些優化。
除分詞外，由於分詞詞庫採用的是自行設計的xdb 和 xtree 結構，故本庫函數也可以用以 XDB 和 XTree 數據存取（另行介紹）。

1. 數據類型 （僅列出API中需要關注的部分）

·scws 操作句柄，幾乎所有的 API 函數都使用到它，不應嘗試拷貝 scws_st 結構，不保證這類拷貝結果會有用。
typedef struct
{
  xdict_t d;
  rule_t r;
  unsigned char *mblen;
  unsigned int mode;
  unsigned char *txt;
  int len;
  int off;
  scws_res_t res0;
  scws_res_t res1;
  word_t **wmap;
  struct scws_zchar *zmap;
} scws_st, *scws_t;
struct scws_zchar
{
  int start;
  int end;
};
注：xdict_t 和 rule_t 分別是詞典和規則集的指針，可判斷其是否爲 NULL 來判斷加載的成功與失敗。

·scws 系列結果集，每次 scws 返回的分詞結果的數量都是不定的，直到返回結果爲 NULL 才表示這次分詞過程結束，
  這是一個單鏈表結構。
typedef struct scws_result *scws_res_t;
struct scws_result
{
  int off;
  float idf;
  unsigned char len;
  char attr[3];
  scws_res_t next;
};

·scws 高頻關鍵詞統計集，簡稱＂詞表集＂，這是 scws 中統計調用時返回用的結構，也是一個單鏈表結構。

typedef struct scws_topword *scws_top_t;
struct scws_topword
{
  char *word;
  float weight;
  short times;
  char attr[2];
  scws_top_t next;
};

2. 函數說明

·scws_t scws_new();
描述：分配或初始化與scws系列操作的 scws_st 對象。該函數將自動分配、初始化、並返回新對象的指針。通過調用 scws_free() 來釋放該對象。
返回值：初始化的 scws_st * （即 scws_t） 句柄。如果無足夠內存以分配新的對象，返回NULL。
錯誤：在內存不足的情況下，返回NULL。

·void scws_free(scws_t s);
描述：釋放由 scws_new() 返回的 scws 操作句柄及對象內容，同時也會釋放已經加載的詞典和規則。
返回值：無
錯誤：無

·void scws_set_charset(scws_t s, const char *cs);
描述：設定當前 scws 所使用的字符集，目前僅支持 gbk 和 utf-8 兩種字符集。參數 cs 描述的是新指定的字符集。若無此調用則系統缺省使用gbk字符集，指定字符集時 cs 參數的大小寫不敏感。
返回值：無
錯誤：若指定的字符集不存在，則會自動使用 gbk 字符集替代。

·void scws_set_dict(scws_t s, const char *fpath, int mode);
描述：設定當前 scws 操作所有的詞典文件。參數 fpath 描述的是詞典的文件路徑，詞典格式是 XDB 格式。
參數 mode 有2種值，分別爲宏定義的：SCWS_XDICT_XDB （這表示直接讀取 xdb 文件）、SCWS_XDICT_MEM （這表示將 xdb 文件全部加載到內存中，以 XTree 結構存放）。具體用哪種方式需要根據自己的實際應用來決定。當使用本庫做爲 daemon server 時應當使用 mem 方式，當只是 embed 調用時應該使用 xdb 方式，將 xdb 文件加載進內存不僅佔用了比較多的內存，而且也需要一定的時間（35萬條數據約需要0.3~0.5秒左右）。
若此前 scws 句柄已經加載過詞典，則此調用會先釋放已經加載的詞典。
返回值：無
錯誤： 如果加載失敗，scws_t 結構中的 d 元素爲 NULL，即通過  s->d == NULL 與否來判斷加載失敗或成功。

·void scws_set_rule(scws_t s, const char *fpath);
描述：設定規則集文件。參數 fpath 是規則集文件的路徑。若此前 scws 句柄已經加載過規則集，則此調用會先釋放已經加載的規則集。規則集定義了一些新詞自動識別規則，包括常見的人名、地區、數字年代等。規則編寫方法另行參考其它部分。
返回值：無
錯誤：加載失敗，scws_t 結構中的 r 元素爲 NULL，即通過 s->r == NULL 與否來判斷加載的失敗與成功。

·void scws_set_ignore(scws_t s, int yes);
描述：設定分詞執行過程中是否忽略所有的標點等特殊符號（不會忽略/r和/n）。參數 yes 爲 1 表示忽略，爲0表示不忽略，缺省情況爲不忽略。
返回值：無
錯誤：無

·void scws_set_multi(scws_t s, int yes);
描述：設定分詞執行時是否執行鍼對長詞複合切分。（例如：中國人->中國+人+中國人）。參數 yes 爲 1表示複合分，爲0表示相反。缺省不復合分詞。
返回值：無
錯誤：無

·void scws_set_debug(scws_t s, int yes);
描述：設定分詞時對於疑難多路徑綜合分詞時，是否打印出各條路徑的情況。注意，打印使用的是 fprintf(stderr, ... 故，這項功能不要隨便使用，僅在命令行嵌入式調用時可以使用，參見例子中的 cmd.c 。當庫函數編譯選項中加入 -DLIBSCWS_QUIET 時此項不生效。（參見 php 擴展，PHP擴展裏就是加入此項）
返回值：無
錯誤：無

·void scws_send_text(scws_t s, const char *text, int len);
描述：設定要切分的文本數據，text 指定該串文本的起始位置，而 len 表示這段文本的長度。該函數可安全用於二進制數據，不會因爲字符串中包括 /0 而停止切分。這個函數應該在 scws_get_result 和 scws_get_tops 之前調用。
返回值：無
錯誤：無。
注：scws結構內部維護着該字符串的指針和相應的偏移及長度，故連續調用的話後者會覆蓋前者的設定；不應在多次 scws_get_result 循環中調用 scws_send_text()。

·scws_res_t scws_get_result(scws_t s);
描述：取回一系列分詞結果集，該分詞結果必須調用 scws_free_result() 釋放，傳入鏈表頭指針。
返回值：返回的是結果集鏈表的頭部指針。該函數必須循環調用，當返回值爲 NULL 時表示分詞結束。
錯誤：無

·void scws_free_result(scws_res_t result);
描述：根據結果集的鏈表頭釋放結果集
返回值：無
錯誤：無

·scws_top_t scws_get_tops(scws_t s, int limit, char *xattr);
描述：返回指定的關鍵詞表統計集，系統會自動根據詞語出現的次數及其 idf 值計算排名。參數 limit 指定取回數據的最大條數，若傳入值爲0或負數，則自動重設爲10。參數 xattr 用來描述要排除或參與的統計詞彙詞性，多個詞性之間用逗號隔開。當以~開頭時表示統計結果中不包含這些詞性，否則表示必須包含，傳入 NULL 表示統計全部詞性。
返回值：返回詞表集鏈表的頭指針，該詞表集必須調用 scws_free_tops 釋放
錯誤：無

·void scws_free_tops(scws_top_t tops);
描述：根據詞表集的鏈表頭釋放詞表集
返回值：無
錯誤：無

3. 使用實例
一個簡單的分詞實例：

CODE:
#include <scws.h>
#include <stdlib.h>
main()
{
scws_t s;
scws_res_t res, cur;
char *text = "Hello, 我名字叫李那曲是一箇中國人, 我有時買Q幣來玩, 我還聽說過C#語言";

if (!(s = scws_new())) {
printf("error, can't init the scws_t!/n");
exit(-1);
}
scws_set_charset(s, "gbk");
scws_set_dict(s, "/path/to/dict.xdb", SCWS_XDICT_XDB);
scws_set_rule(s, "/path/to/rules.ini");

scws_send_text(s, text, strlen(text));
while (res = cur = scws_get_result(s))
{
while (cur != NULL)
{
printf("Word: %.*s/%s (IDF = %4.2f)/n", cur->len, text+cur->off, cur->attr, cur->idf);
cur = cur->next;
}
scws_free_result(res);
}

scws_free(s);
}



假設 libscws 被放在 /path/to/libscws/ 中編譯
編譯：gcc -o test -I/path/to/libscws -L/path/to/libscws test.c -lscws -lm
完整的實例請參見相關的源碼：scwsc 命僅行分詞代碼。


引自: http://cws.twomice.net/bbs/viewthread.php?tid=37

相關演示和原碼

到該網站下載
http://www.hightman.cn/bbs/viewthread.php?tid=22

演示地址：
http://www.hightman.cn/demo/scws/v4.php