한자 사전 검색 기능

타입정의
typedef struct _Hanja	Hanja
	한자 사전 검색 결과의 최소 단위 더 자세히 ...
typedef struct _HanjaList	HanjaList
	한자 사전의 검색 결과를 전달하는데 사용하는 오브젝트 더 자세히 ...
typedef struct _HanjaTable	HanjaTable
	한자 사전을 관리하는데 사용하는 오브젝트 더 자세히 ...

함수
const char *	hanja_get_key (const Hanja *hanja)
	Hanja 의 키를 찾아본다. 더 자세히 ...
const char *	hanja_get_value (const Hanja *hanja)
	Hanja 의 값을 찾아본다. 더 자세히 ...
const char *	hanja_get_comment (const Hanja *hanja)
	Hanja 의 설명을 찾아본다. 더 자세히 ...
HanjaTable *	hanja_table_load (const char *filename)
	한자 사전 파일을 로딩하는 함수 더 자세히 ...
void	hanja_table_delete (HanjaTable *table)
	한자 사전 object를 free하는 함수 더 자세히 ...
HanjaList *	hanja_table_match_exact (const HanjaTable *table, const char *key)
	한자 사전에서 매치되는 키를 가진 엔트리를 찾는 함수 더 자세히 ...
HanjaList *	hanja_table_match_prefix (const HanjaTable *table, const char *key)
	한자 사전에서 앞부분이 매치되는 키를 가진 엔트리를 찾는 함수 더 자세히 ...
HanjaList *	hanja_table_match_suffix (const HanjaTable *table, const char *key)
	한자 사전에서 뒷부분이 매치되는 키를 가진 엔트리를 찾는 함수 더 자세히 ...
int	hanja_list_get_size (const HanjaList *list)
	HanjaList 가 가지고 있는 아이템의 갯수를 구하는 함수
const char *	hanja_list_get_key (const HanjaList *list)
	HanjaList 가 생성될때 검색함수에서 사용한 키를 구하는 함수 더 자세히 ...
const Hanja *	hanja_list_get_nth (const HanjaList *list, unsigned int n)
	HanjaList 의 n번째 Hanja 아이템의 포인터를 구하는 함수 더 자세히 ...
const char *	hanja_list_get_nth_key (const HanjaList *list, unsigned int n)
	HanjaList 의 n번째 아이템의 키를 구하는 함수 더 자세히 ...
const char *	hanja_list_get_nth_value (const HanjaList *list, unsigned int n)
	HanjaList 의 n번째 아이템의 값를 구하는 함수 더 자세히 ...
const char *	hanja_list_get_nth_comment (const HanjaList *list, unsigned int n)
	HanjaList 의 n번째 아이템의 설명을 구하는 함수 더 자세히 ...
void	hanja_list_delete (HanjaList *list)
	한자 사전 검색 함수가 리턴한 결과를 free하는 함수 더 자세히 ...

상세한 설명

한자 사전 루틴의 사용 방법

libhangul에서는 한자 사전 파일과 그 사전 파일을 검색할 수 있는 몇가지 함수의 셋을 제공한다. 여기에서 사용되는 모든 스트링은 UTF-8 인코딩을 사용한다. libhangul에서 사용하는 한자 사전 파일의 포맷은 HanjaTable 섹션을 참조한다.

그 개략적인 사용 방법은 다음과 같다.

// 지정된 위치의 한자 사전 파일을 로딩한다.
// 아래 코드에서는 libhangul의 한자 사전 파일을 로딩하기 위해서
// NULL을 argument로 준다.
HanjaTable* table = hanja_table_load(NULL);

// "삼국사기"에 해당하는 한자를 찾는다.
HanjaList* list = hanja_table_match_exact(table, "삼국사기");
if (list != NULL) {
    int i;
    int n = hanja_list_get_size(list);
    for (i = 0; i < n; ++i) {
        const char* hanja = hanja_list_get_nth_value(list);
        printf("한자: %s\n", hanja);
    }
    hanja_list_delete(list);
}

hanja_table_delete(table);

타입정의 문서화

Hanja

Hanja

한자 사전 검색 결과의 최소 단위

Hanja 오브젝트는 한자 사전 파일의 각 엔트리에 해당한다. 각 엔트리는 키(key), 밸류(value) 페어로 볼 수 있는데, libhangul에서는 약간 확장을 하여 설명(comment)도 포함하고 있다. 한자 사전 포맷은 HanjaTable 부분을 참조한다.

한자 사전을 검색하면 결과는 Hanja 오브젝트의 리스트 형태로 전달된다. HanjaList 에서 각 엔트리의 내용을 하나씩 확인할 수 있다. Hanja 의 멤버는 직접 참조할 수 없고, hanja_get_key(), hanja_get_value(), hanja_get_comment() 함수로 찾아볼 수 있다. char 스트링으로 전달되는 내용은 모두 UTF-8 인코딩으로 되어 있다.

HanjaList

HanjaList

한자 사전의 검색 결과를 전달하는데 사용하는 오브젝트

한자 사전의 검색 함수를 사용하면 이 타입으로 결과를 리턴한다. 이 오브젝트에서 hanja_list_get_nth()함수를 이용하여 검색 결과를 이터레이션할 수 있다. 내부 구현 내용은 외부로 노출되어 있지 않다. HanjaList 가 가지고 있는 아이템들은 accessor 함수들을 이용해서 참조한다.

참조: hanja_list_get_nth(), hanja_list_get_nth_key(), hanja_list_get_nth_value(), hanja_list_get_nth_comment()

HanjaTable

HanjaTable

한자 사전을 관리하는데 사용하는 오브젝트

libhangul에서 한자 사전을 관리하는데 사용하는 오브젝트로 내부 구현 내용은 외부로 노출되어 있지 않다.

libhangul에서 사용하는 한자 사전 파일의 포맷은 다음과 같은 형식이다.

# comment
key1:value1:comment1
key2:value2:comment2
key3:value3:comment3
...

각 필드는 : 으로 구분하고, 첫번째 필드는 각 한자를 찾을 키값이고 두번째 필드는 그 키값에 해당하는 한자 스트링, 세번째 필드는 이 키와 값에 대한 설명이다. # 으로 시작하는 라인은 주석으로 무시된다.

실제 예를 들면 다음과 같은 식이다.

삼국사기:三國史記:삼국사기
한자:漢字:한자

그 내용은 키값에 대해서 sorting 되어야 있어야 한다. 파일의 인코딩은 UTF-8이어야 한다.

함수 문서화

hanja_get_comment()

const char* hanja_get_comment

(

const Hanja *

hanja

)

Hanja 의 설명을 찾아본다.

반환값

hanja 오브젝트의 comment 필드, UTF-8

일반적으로 Hanja 아이템의 설명은 한글과 그 한자에 대한 설명이다. 파일에 따라서 내용이 없을 수 있다. 리턴되는 스트링은 hanja 오브젝트 내부적으로 관리하는 데이터로 수정하거나 free되어서는 안된다.

다음에 의해서 참조됨 : hanja_list_get_nth_comment().

hanja_get_key()

const char* hanja_get_key

(

const Hanja *

hanja

)

Hanja 의 키를 찾아본다.

반환값

hanja 오브젝트의 키, UTF-8

일반적으로 Hanja 아이템의 키는 한글이다. 리턴되는 스트링은 hanja 오브젝트 내부적으로 관리하는 데이터로 수정하거나 free 되어서는 안된다.

다음에 의해서 참조됨 : hanja_list_get_nth_key().

hanja_get_value()

const char* hanja_get_value

(

const Hanja *

hanja

)

Hanja 의 값을 찾아본다.

반환값

hanja 오브젝트의 값, UTF-8

일반적으로 Hanja 아이템의 값은 key에 대응되는 한자다. 리턴되는 스트링은 hanja 오브젝트 내부적으로 관리하는 데이터로 수정하거나 free되어서는 안된다.

다음에 의해서 참조됨 : hanja_list_get_nth_value().

hanja_list_delete()

void hanja_list_delete

(

HanjaList *

list

)

한자 사전 검색 함수가 리턴한 결과를 free하는 함수

매개변수

list	free할 HanjaList

libhangul의 모든 한자 사전 검색 루틴이 리턴한 결과는 반드시 이 함수로 free해야 한다.

hanja_list_get_key()

const char* hanja_list_get_key

(

const HanjaList *

list

)

HanjaList 가 생성될때 검색함수에서 사용한 키를 구하는 함수

반환값

HanjaList 의 key 스트링

한자 사전 검색 함수로 HanjaList 를 생성하면 HanjaList 는 그 검색할때 사용한 키를 기억하고 있다. 이 값을 확인할때 사용한다. 주의할 점은, 각 Hanja 아이템들은 각각의 키를 가지고 있지만, 이것이 반드시 HanjaList 와 일치하지는 않는다는 것이다. 검색할 당시에 사용한 함수가 prefix나 suffix계열이면 더 짧은 키로도 검색하기 때문에 HanjaList 의 키와 검색 결과의 키와 다른 것들도 가지고 있게 된다.

리턴된 스트링 포인터는 HanjaList 에서 관리하는 스트링으로 수정하거나 free해서는 안된다.

hanja_list_get_nth()

const Hanja* hanja_list_get_nth	(	const HanjaList *	list,
		unsigned int	n
	)

HanjaList 의 n번째 Hanja 아이템의 포인터를 구하는 함수

매개변수

list	HanjaList 를 가리키는 포인터
n	참조할 아이템의 인덱스

반환값

Hanja 를 가리키는 포인터

이 함수는 list가 가리키는 HanjaList 의 n번째 Hanja 오브젝트를 가리키는 포인터를 리턴한다. HanjaList 의 각 아이템은 정수형 인덱스로 각각 참조할 수 있다. HanjaList 가 가진 엔트리 갯수를 넘어서는 인덱스를 주면 NULL을 리턴한다. 리턴된 Hanja 오브젝트는 HanjaList 가 관리하는 오브젝트로 free하거나 수정해서는 안된다.

다음의 예제는 list로 주어진 HanjaList 의 모든 값을 프린트 하는 코드다.

int i;
int n = hanja_list_get_size(list);
for (i = 0; i < n; i++) {
     Hanja* hanja = hanja_list_get_nth(i);
     const char* value = hanja_get_value(hanja);
     printf("Hanja: %s\n", value);
     // 또는 hanja에서 다른 정보를 참조하거나
     // 다른 작업을 할 수도 있다.
}

다음에 의해서 참조됨 : hanja_list_get_nth_comment(), hanja_list_get_nth_key(), hanja_list_get_nth_value().

hanja_list_get_nth_comment()

const char* hanja_list_get_nth_comment	(	const HanjaList *	list,
		unsigned int	n
	)

HanjaList 의 n번째 아이템의 설명을 구하는 함수

반환값

n번째 아이템의 설명(comment), UTF-8

HanjaList_get_nth()의 convenient 함수

다음을 참조함 : hanja_get_comment(), hanja_list_get_nth().

hanja_list_get_nth_key()

const char* hanja_list_get_nth_key	(	const HanjaList *	list,
		unsigned int	n
	)

HanjaList 의 n번째 아이템의 키를 구하는 함수

반환값

n번째 아이템의 키, UTF-8

HanjaList_get_nth()의 convenient 함수

다음을 참조함 : hanja_get_key(), hanja_list_get_nth().

hanja_list_get_nth_value()

const char* hanja_list_get_nth_value	(	const HanjaList *	list,
		unsigned int	n
	)

HanjaList 의 n번째 아이템의 값를 구하는 함수

반환값

n번째 아이템의 값(value), UTF-8

HanjaList_get_nth()의 convenient 함수

다음을 참조함 : hanja_get_value(), hanja_list_get_nth().

hanja_table_delete()

void hanja_table_delete

(

HanjaTable *

table

)

한자 사전 object를 free하는 함수

매개변수

table

free할 한자 사전 object

hanja_table_load()

HanjaTable* hanja_table_load

(

const char *

filename

)

한자 사전 파일을 로딩하는 함수

매개변수

filename

로딩할 사전 파일의 위치, 또는 NULL

반환값

한자 사전 object 또는 NULL

이 함수는 한자 사전 파일을 로딩하는 함수로 filename으로 지정된 파일을 로딩한다. 한자 사전 파일은 libhangul에서 사용하는 포맷이어야 한다. 한자 사전 파일의 포맷에 대한 정보는 HanjaTable을 참조한다.

filename은 locale에 따른 인코딩으로 되어 있어야 한다. UTF-8이 아닐 수 있으므로 주의한다.

filename 에 NULL을 주면 libhangul에서 디폴트로 배포하는 사전을 로딩한다. 파일이 없거나, 포맷이 맞지 않으면 로딩에 실패하고 NULL을 리턴한다. 한자 사전이 더이상 필요없으면 hanja_table_delete() 함수로 삭제해야 한다.

hanja_table_match_exact()

HanjaList* hanja_table_match_exact	(	const HanjaTable *	table,
		const char *	key
	)

한자 사전에서 매치되는 키를 가진 엔트리를 찾는 함수

매개변수

table	한자 사전 object
key	찾을 키, UTF-8 인코딩

반환값

찾은 결과를 HanjaList object로 리턴한다. 찾은 것이 없거나 에러가 있으면 NULL을 리턴한다.

key 값과 같은 키를 가진 엔트리를 검색한다. 리턴된 결과는 다 사용하고 나면 반드시 hanja_list_delete() 함수로 free해야 한다.

hanja_table_match_prefix()

HanjaList* hanja_table_match_prefix	(	const HanjaTable *	table,
		const char *	key
	)

한자 사전에서 앞부분이 매치되는 키를 가진 엔트리를 찾는 함수

매개변수

table	한자 사전 object
key	찾을 키, UTF-8 인코딩

반환값

찾은 결과를 HanjaList object로 리턴한다. 찾은 것이 없거나 에러가 있으면 NULL을 리턴한다.

key 값과 같거나 앞부분이 같은 키를 가진 엔트리를 검색한다. 그리고 key를 뒤에서부터 한자씩 줄여가면서 검색을 계속한다. 예로 들면 "삼국사기"를 검색하면 "삼국사기", "삼국사", "삼국", "삼"을 각각 모두 검색한다. 리턴된 결과는 다 사용하고 나면 반드시 hanja_list_delete() 함수로 free해야 한다.

hanja_table_match_suffix()

HanjaList* hanja_table_match_suffix	(	const HanjaTable *	table,
		const char *	key
	)

한자 사전에서 뒷부분이 매치되는 키를 가진 엔트리를 찾는 함수

매개변수

table	한자 사전 object
key	찾을 키, UTF-8 인코딩

반환값

찾은 결과를 HanjaList object로 리턴한다. 찾은 것이 없거나 에러가 있으면 NULL을 리턴한다.

key 값과 같거나 뒷부분이 같은 키를 가진 엔트리를 검색한다. 그리고 key를 앞에서부터 한자씩 줄여가면서 검색을 계속한다. 예로 들면 "삼국사기"를 검색하면 "삼국사기", "국사기", "사기", "기"를 각각 모두 검색한다. 리턴된 결과는 다 사용하고 나면 반드시 hanja_list_delete() 함수로 free해야 한다.