M17N ライブラリ

これらの値のうち一つが MConverter->result に設定される。

列挙型の値:

MCONVERSION_RESULT_SUCCESS	コード変換は成功.
MCONVERSION_RESULT_INVALID_BYTE	デコード時、ソースに不正なバイトが含まれている.
MCONVERSION_RESULT_INVALID_CHAR	エンコード時、指定のコード系でエンコードできない文字がソースに含まれている.
MCONVERSION_RESULT_INSUFFICIENT_SRC	デコード時、不完全なバイト列でソースが終わっている。
MCONVERSION_RESULT_INSUFFICIENT_DST	エンコード時、結果を格納する領域が短かすぎる。
MCONVERSION_RESULT_IO_ERROR	コード変換中に I/O エラーが起こった。

enum MCodingType

列挙型の値:

MCODING_TYPE_CHARSET	このタイプのコード系は文字セットを直接サポートする。各文字セットの次元とは、その文字セットで一文字を表現するために必要なバイト数であり、バイト列は文字のコードポイントを直接表す。 m17n ライブラリはこのタイプ用のデフォルトのエンコード／デコードルーティンを提供する。
MCODING_TYPE_UTF	このタイプのコード系は、UTF 系 (UTF-8, UTF-16, UTF-32) のバイト列をサポートする。 m17n ライブラリはこのタイプ用のデフォルトのエンコード／デコードルーティンを提供する。
MCODING_TYPE_ISO_2022	このタイプのコード系は、ISO-2022 系のバイト列をサポートする。各コード系の構造の詳細は `MCodingInfoISO2022` で指定される。 m17n ライブラリはこのタイプ用のデフォルトのエンコード／デコードルーティンを提供する。
MCODING_TYPE_MISC	このタイプのコード系は、その他の構造のバイト列のためのものである。 m17n ライブラリはこのタイプ用のエンコード／デコードルーティンを提供しないので、アプリケーションプログラム側で準備する必要がある。

enum MCodingFlagISO2022

列挙型の値:

MCODING_ISO_RESET_AT_EOL	エンコードの際、行末で呼び出し (invocation) と指示 (designation) の状態を初期値に戻す。
MCODING_ISO_RESET_AT_CNTL	エンコードの際、すべての制御文字の前で、呼び出し (invocation) と指示 (designation) の状態を初期値に戻す。
MCODING_ISO_EIGHT_BIT	図形文字集合の右側を使う。
MCODING_ISO_LONG_FORM	JISX0208-1978, GB2312, JISX0208-1983 の文字集合に対する指示シークエンスとして、非標準の4バイト形式を用いる。
MCODING_ISO_DESIGNATION_G0	エンコードの際、特に指定されない限り、文字集合を G0 に指示する。
MCODING_ISO_DESIGNATION_G1	エンコードの際、特に指定されない限り、ASCII 以外の文字集合を G1 に指示する。
MCODING_ISO_DESIGNATION_CTEXT	エンコードの際、特に指定されない限り、94文字集合を G0 に、96文字集合を G1 に指示する。
MCODING_ISO_DESIGNATION_CTEXT_EXT	エンコードの際、ISO-2022 に合致しない文字集合を ESC % / ... でエンコードする。サポートされていない Unicode 文字は ESC % G ... ESC % @ でエンコードする。デコードの際、これらのエスケープ・シーケンスを解釈する。
MCODING_ISO_LOCKING_SHIFT	ロッキングシフトを使う。
MCODING_ISO_SINGLE_SHIFT	シングルシフト (SS2 (0x8E or ESC N), SS3 (0x8F or ESC O)) を使う。
MCODING_ISO_SINGLE_SHIFT_7	7ビットシングルシフト 2 (SS2 (0x19)) を使う。
MCODING_ISO_EUC_TW_SHIFT	EUC-TW 風の特別なシフトを使う。
MCODING_ISO_ISO6429	ISO-6429 のエスケープシークエンスで方向を指示する。未実装。
MCODING_ISO_REVISION_NUMBER	エンコードの際、文字セットに revision number があればそれを表わすエスケープシークエンスを生成する。
MCODING_ISO_FULL_SUPPORT	ISO-2022 の全文字集合をサポートする。
MCODING_ISO_FLAG_MAX

MSymbol mconv_define_coding	(	const char *	name,
		MPlist *	plist,
		int()(MConverter )	resetter,
		int()(const unsigned char , int, MText , MConverter )	decoder,
		int()(MText , int, int, unsigned char , int, MConverter )	encoder,
		void *	extra_info
	)

関数 mconv_define_coding() は、新しいコード系を定義し、それを name という名前のシンボル経由でアクセスできるようにする。 plist では定義するコード系のパラメータを以下のように指定する。

キーが Mtype で値がシンボルの時
値はコード系のタイプを表し、Mcharset, Mutf, Miso_2022, Mnil のいずれかでなくてはならない。
タイプが Mcharset ならば extra_info は無視される。
タイプが Mutf ならば extra_info は MCodingInfoUTF へのポインタでなくてはならない。
タイプが Miso_2022ならば extra_info は MCodingInfoISO2022 へのポインタでなくてはならない。
タイプが Mnil ならば、引数 resetter, decoder, encoder を与えなくてはならない。extra_info は無視される。それ以外の場合にはこれらは NULL でよく、 m17n ライブラリが適切なデフォルト値を与える。
キーが Mcharsets で値が plist の時
値はこのコード系でサポートされる文字セットのリストである。plistのキーは Msymbol、値は文字セットを示すシンボルでなくてはならない。
キーが Mflags 値が plist の時
タイプが Miso_2022 ならば、この値は, ISO 2022 インタプリタ用の制御フラッグを示す。plist のキーは Msymbol であり、値は以下のいずれかである。
- Mreset_at_eol
  このフラグがあれば、図形文字集合の指示や呼出は行末でリセットされて当初の状態に戻る。
- Mreset_at_cntl
  このフラグがあれば、図形文字集合の指示や呼出は制御文字に出会った時点でリセットされて当初の状態に戻る。
- Meight_bit
  このフラグがあれば、図形文字集合の右半面が用いられる。
- Mlong_form
  このフラグがあれば、文字集合 JISX0208.1978, GB2312, JISX0208 を指示する際に over-long エスケープシーケンス (ESC '$' '(' <final_byte>) が用いられる。
- Mdesignation_g0
  このフラグと Mfull_support があれば、文字セットリストに現われない文字セットを G0 集合に指示する。
- Mdesignation_g1
  このフラグと Mfull_support があれば、文字セットリストに現われない文字セットを G1 集合に指示する。
- Mdesignation_ctext
  このフラグと Mfull_support があれば、文字セットリストに現われない文字セットを G0 集合または G1 集合に、コンパウンドテキストの基準にそって指示する。
- Mdesignation_ctext_ext
  このフラグと Mfull_support があれば、文字セットリストに現われない文字セットを G0 集合または G1 集合に、あるいは拡張セグメントにコンパウンドテキストの基準にそって指示する。
- Mlocking_shift
  このフラグがあれば、ロッキングシフトを用いる。
- Msingle_shift
  このフラグがあれば、シングルシフトを用いる。
- Msingle_shift_7
  このフラグがあれば、7-bit シングルシフトコード (0x19) を用いる。
- Meuc_tw_shift
  このフラグがあれば、EUC-TW に沿った特別なシフトを用いる。
- Miso_6429
  現時点では用いられていない。
- Mrevision_number
  このフラグがあれば、revision number を持つ文字セットを指示する際に revision number エスケープシークエンスを用いる。
- Mfull_support
  このフラグがあれば、the International Registry に登録されている全文字セットをサポートする。
キーが Mdesignationで値が plist の時
タイプが Miso_2022 ならば、値は各文字をどのように指示するかを示す。 plist のキーは Minteger、値は集合（graphic register）を示す数字である。N番目の要素の値は、文字セットリストの N 番目の文字セットに対応する。値が 0..3 であれば、文字セットがすでに G0..G3 に指示されている。
値が負(-4..-1) であれば、初期状態では文字セットがどこにも指示されていないこと、必要な際には G0..G3 のそれぞれに指示することを意味する。
キーが Minvocationで値が plist の時
タイプが Miso_2022 ならば、値は各集合をどのように呼び出すかを示す。 plist の長さは 1 ないし 2 である。plist のキーは Minteger、値は集合（graphic register)を示す数字である。最初の要素の値が図形文字集合左半面に呼び出される集合を示す。 plist の長さが 1 ならば、右半面には何も呼び出されない。そうでければ、２つめの要素の値が図形文字集合右半面に呼び出される集合を示す。
キーが Mcode_unit で値が整数値の時
タイプが Mutf ならば、値はコードユニットのビット長であり、8, 16, 32 のいずれかである。
キーが Mbom で値がシンボルの時
タイプが Mutf でコードユニットのビット長が 16 か 32ならば、値は BOM (Byte Order Mark) を使用するかどうかを示す。値がデフォルト値の Mnil ならば、使用しない。値が Mmaybe ならばデコード時に BOM があるかどうかを調べる。それ以外ならば使用する。
キーが Mlittle_endian で値がシンボルの時
タイプが Mutf でコードユニットのビット長が 16 か 32 ならば、値はエンコードが little endian かどうかを示す。値がデフォルト値の Mnil ならば big endian であり、そうでなければ little endian である。

resetter はこのコード系用のコンバータを初期状態にリセットする関数へのポインタである。この関数はコンバータオブジェクトへのポインタという１引数をとる。

decoder はバイト列をこのコード系に従ってデコードする関数へのポインタである。この関数は以下の４引数をとる。

デコードするバイト列へのポインタ
デコードすべきバイト数
デコード結果の文字を付加する M-text へのポインタ
コンバータオブジェクトへのポインタ

decoder は成功したときには 0 を、失敗したときには -1 を返さなくてはならない。

encoder は M-text をこのコード系に従ってエンコードする関数へのポインタである。この関数は以下の６引数をとる。

エンコードするM-text へのポインタ
M-text のエンコード開始位置
M-text のエンコード終了位置
生成したバイトを保持するメモリ領域へのポインタ
メモリ領域のサイズ
コンバータオブジェクトへのポインタ

encoder は成功したときには 0 を、失敗したときには -1 を返さなくてはならない。

extra_info はコーディグシステムに関する追加情報を含むデータ構造へのポインタである。このデータ構造の型 type に依存する。

戻り値:

処理に成功すれば mconv_define_coding() は name という名前のシンボルを返す。エラーが検出された場合は Mnil を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_CODING

MSymbol mconv_resolve_coding ( MSymbol symbol )

関数 mconv_resolve_coding() は symbol がコード系を示していればそれを返す。そうでなければコード系の名前として symbol を正規化し、それがコード系を表していれば正規化した symbol を返す。そうでなければMnil を返す。

int mconv_list_codings ( MSymbol ** symbols )

関数 mchar_list_codings() は、コード系を示すシンボルを並べた配列を作り、 symbols でポイントされた場所にこの配列へのポインタを置き、配列の長さを返す。

MConverter* mconv_buffer_converter	(	MSymbol	name,
		const unsigned char *	buf,
		int	n
	)

関数 mconv_buffer_converter() は、コード系 name 用のコードコンバータを作る。このコードコンバータは、buf で示される大きさ n バイトのバッファ領域に結び付けられる。これ以降のデコードおよびエンコードは、このバッファ領域に対して行なわれる。

name は Mnil であってもよい。この場合は現在のロケール (LC_CTYPE) に関連付けられたコード系が使われる。

戻り値:: もし処理が成功すれば mconv_buffer_converter() は作成したコードコンバータを返す。そうでなければ NULL を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_SYMBOL, MERROR_CODING

参照:: mconv_stream_converter()

MConverter* mconv_stream_converter	(	MSymbol	name,
		FILE *	fp
	)

関数 mconv_stream_converter() は、コード系 name 用のコードコンバータを作る。このコードコンバータは、ストリーム fp に結び付けられる。これ以降のデコードおよびエンコードは、このストリームに対して行なわれる。

name は Mnil であってもよい。この場合は現在のロケール (LC_CTYPE) に関連付けられたコード系が使われる。

戻り値:: もし処理が成功すれば、mconv_stream_converter() は作成したコードコンバータを返す。そうでなければ NULL を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_SYMBOL, MERROR_CODING

参照:: mconv_buffer_converter()

int mconv_reset_converter ( MConverter * converter )

関数 mconv_reset_converter() はコードコンバータ converter を初期状態に戻す。

戻り値:: もし converter->coding にリセット用の関数が定義されているならば、 mconv_reset_converter() はその関数に converter を適用した結果を返し、そうでなければ0を返す。

void mconv_free_converter ( MConverter * converter )

関数 mconv_free_converter() はコードコンバータ converter を解放する。

MConverter* mconv_rebind_buffer	(	MConverter *	converter,
		const unsigned char *	buf,
		int	n
	)

関数 mconv_rebind_buffer() は、buf によって指された大きさ n バイトのバッファ領域をコードコンバータ converter に結び付ける。これ以降のデコードおよびエンコードは、この新たに結び付けられたバッファ領域に対して行なわれるようになる。

戻り値:: この関数は常に converter を返す。

参照:: mconv_rebind_stream()

MConverter* mconv_rebind_stream	(	MConverter *	converter,
		FILE *	fp
	)

関数 mconv_rebind_stream() は、ストリーム fp をコードコンバータ converter に結び付ける。これ以降のデコードおよびエンコードは、この新たに結び付けられたストリームに対して行なわれるようになる。

戻り値:: この関数は常に converter を返す。

参照:: mconv_rebind_buffer()

MText* mconv_decode	(	MConverter *	converter,
		MText *	mt
	)

関数 mconv_decode() は、バイト列をデコードしてその結果を M-text mt の末尾に追加する。デコード元のバイト列は、converter に現在結び付けられているバッファ領域あるいはストリームから取られる。

戻り値:: もし処理が成功すれば、mconv_decode() は更新された mt を返す。そうでなければ NULL を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_IO, MERROR_CODING

参照:: mconv_rebind_buffer(), mconv_rebind_stream(), mconv_encode(), mconv_encode_range(), mconv_decode_buffer(), mconv_decode_stream()

MText* mconv_decode_buffer	(	MSymbol	name,
		const unsigned char *	buf,
		int	n
	)

関数 mconv_decode_buffer() は、buf によって指された n バイトのバッファ領域を、コード系 name に基づいてデコードする。デコードに必要なコードコンバータの作成と解放は自動的に行なわれる。

戻り値:: もし処理が成功すれば、mconv_decode_buffer() は得られた M-text を返す。そうでなければ NULL を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_IO, MERROR_CODING

参照:: mconv_decode(), mconv_decode_stream()

MText* mconv_decode_stream	(	MSymbol	name,
		FILE *	fp
	)

関数 mconv_decode_stream() は、ストリーム fp から読み込まれるバイト列全体を、コード系 name に基づいてデコードする。デコードに必要なコードコンバータの作成と解放は自動的に行なわれる。

戻り値:: もし処理が成功すれば、mconv_decode_stream() は得られた M-text を返す。そうでなければ NULL を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_IO, MERROR_CODING

参照:: mconv_decode(), mconv_decode_buffer()

int mconv_encode	(	MConverter *	converter,
		MText *	mt
	)

関数 mconv_encode() は、M-text mt をエンコードして、コードコンバータ converter に現在結び付けられているバッファ領域あるいはストリームに得られたバイト列を書き込む。

戻り値:: もし処理が成功すれば、mconv_encode() は書き込まれたバイト数を返す。そうでなければ -1 を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_IO, MERROR_CODING

参照:: mconv_rebind_buffer(), mconv_rebind_stream(), mconv_decode(), mconv_encode_range()

int mconv_encode_range	(	MConverter *	converter,
		MText *	mt,
		int	from,
		int	to
	)

関数 mconv_encode_range() は、M-text mt の from （from 自体も含む）から to （to自体は含まない） までの範囲のテキストをエンコードして、コードコンバータ converter に現在結び付けられているバッファ領域あるいはストリームに得られたバイト列を書き込む。

戻り値:: もし処理が成功すれば、mconv_encode_range() は書き込まれたバイト数を返す。そうでなければ -1 を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_RANGE, MERROR_IO, MERROR_CODING

参照:: mconv_rebind_buffer(), mconv_rebind_stream(), mconv_decode(), mconv_encode()

int mconv_encode_buffer	(	MSymbol	name,
		MText *	mt,
		unsigned char *	buf,
		int	n
	)

関数 mconv_encode_buffer() はM-text mt をコード系 name に基づいてエンコードし、得られたバイト列を buf の指すバッファ領域に書き込む。 n は書き込む最大バイト数である。エンコードに必要なコードコンバータの作成と解放は自動的に行なわれる。

戻り値:: もし処理が成功すれば、mconv_encode_buffer() は書き込まれたバイト数を返す。そうでなければ-1を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_IO, MERROR_CODING

参照:: mconv_encode(), mconv_encode_stream()

int mconv_encode_stream	(	MSymbol	name,
		MText *	mt,
		FILE *	fp
	)

関数 mconv_encode_stream() はM-text mt をコード系 name に基づいてエンコードし、得られたバイト列をストリーム fp に書き出す。エンコードに必要なコードコンバータの作成と解放は自動的に行なわれる。

戻り値:: もし処理が成功すれば、mconv_encode_stream() は書き込まれたバイト数を返す。そうでなければ -1 を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_IO, MERROR_CODING

参照:: mconv_encode(), mconv_encode_buffer(), mconv_encode_file()

int mconv_getc ( MConverter * converter )

関数 mconv_getc() は、コードコンバータ converter に現在結び付けられているバッファ領域あるいはストリームから文字を一つ読み込む。バイト列のデコードには converter のデコーダが用いられる。 converter の内部状態は必要に応じて更新される。

戻り値:: 処理が成功すれば、mconv_getc() は読み込まれた文字を返す。入力源が EOF に達した場合は、外部変数 merror_code を変えずに EOF を返す。エラーが検出された場合は EOF を返し、merror_code にエラーコードを設定する。

エラー:: MERROR_CODING

参照:: mconv_ungetc(), mconv_putc(), mconv_gets()

int mconv_ungetc	(	MConverter *	converter,
		int	c
	)

関数 mconv_ungetc() は、コードコンバータ converter に文字 c を押し戻す。戻される文字数に制限はない。この後で mconv_getc() を呼び出した際には、最後に戻された文字が最初に読まれる。戻された文字は converter の内部に蓄えられるだけであり、実際に入力源に書き込まれるわけではない。 converter の内部状態は必要に応じて更新される。

戻り値:: 処理が成功すれば、mconv_ungetc() は c を返す。そうでなければ EOF を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_CODING, MERROR_CHAR

参照:: mconv_getc(), mconv_putc(), mconv_gets()

int mconv_putc	(	MConverter *	converter,
		int	c
	)

関数 mconv_putc() は、コードコンバータ converter に現在結び付けられているバッファ領域あるいはストリームに文字 c を書き出す。文字のエンコードには converter のエンコーダが用いられる。実際に書き出されたバイト数は、converter のメンバー nbytes にセットされる。converter の内部状態は必要に応じて更新される。

戻り値:: 処理が成功すれば、mconv_putc() は c を返す。エラーが検出された場合は EOF を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_CODING, MERROR_IO, MERROR_CHAR

参照:: mconv_getc(), mconv_ungetc(), mconv_gets()

MText* mconv_gets	(	MConverter *	converter,
		MText *	mt
	)

関数 mconv_gets() は、コードコンバータ converter に現在結び付けられているバッファ領域あるいはストリームから 1 行を読み込む。バイト列のデコードには converter のデコーダが用いられる。デコードされた文字列は M-text mt の末尾に追加される。元のバイト列の終端改行文字は追加されない。 converter の内部状態は必要に応じて更新される。

戻り値:: 処理が成功すれば、mconv_gets() は変更された mt を返す。もし1文字も読まずに EOF に遭遇した場合は、mt を変更せずにそのまま返す。エラーが検出された場合は NULL を返し、 merror_code にエラーコードを設定する。

エラー:: MERROR_CODING

参照:: mconv_getc(), mconv_ungetc(), mconv_putc()

MSymbol Mcoding_us_ascii

シンボル Mcoding_us_ascii は "us-ascii" という名前を持ち、 CES US-ASCII 用のコード系を示す。

MSymbol Mcoding_iso_8859_1

シンボル Mcoding_iso_8859_1 は "iso-8859-1" という名前を持ち、CES ISO-8859-1 用のコード系を示す。

MSymbol Mcoding_utf_8

シンボル Mcoding_utf_8 は "utf-8" という名前を持ち、CES UTF-8 用のコード系を示す。

MSymbol Mcoding_utf_8_full

シンボル Mcoding_utf_8_full は "utf-8-full" という名前を持ち、"UTF-8" の拡張であるコード系を示す。このコード系は UTF-8 と同じエンコーディングアルゴリズムを用いるが、対象は Unicode 文字には限定されない。またm17n ライブラリが扱う全ての文字をエンコードすることができる。

MSymbol Mcoding_utf_16

シンボル Mcoding_utf_16 は "utf-16" という名前を持ち、 CES UTF-16 (RFC 2279) 用のコード系を示す。

MSymbol Mcoding_utf_16be

シンボル Mcoding_utf_16be は "utf-16be" という名前を持ち、 CES UTF-16BE (RFC 2279) 用のコード系を示す。

MSymbol Mcoding_utf_16le

シンボル Mcoding_utf_16le は "utf-16le" という名前を持ち、 CES UTF-16LE (RFC 2279) 用のコード系を示す。

MSymbol Mcoding_utf_32

シンボル Mcoding_utf_32 は "utf-32" という名前を持ち、 CES UTF-32 (RFC 2279) 用のコード系を示す。

MSymbol Mcoding_utf_32be

シンボル Mcoding_utf_32be は "utf-32be" という名前を持ち、 CES UTF-32BE (RFC 2279) 用のコード系を示す。

MSymbol Mcoding_utf_32le

シンボル Mcoding_utf_32le は "utf-32le" という名前を持ち、 CES UTF-32LE (RFC 2279) 用のコード系を示す。

MSymbol Mcoding_sjis

シンボル Mcoding_sjis has は "sjis" という名前を持ち、 CES Shift-JIS用のコード系を示す。

MSymbol Mtype

mconv_define_coding() 用パラメータキー (詳細は mconv_define_coding()参照).

MSymbol Mcharsets

mconv_define_coding() 用パラメータキー (詳細は mconv_define_coding()参照).

MSymbol Mflags

mconv_define_coding() 用パラメータキー (詳細は mconv_define_coding()参照).

MSymbol Mdesignation

mconv_define_coding() 用パラメータキー (詳細は mconv_define_coding()参照).

MSymbol Minvocation

mconv_define_coding() 用パラメータキー (詳細は mconv_define_coding()参照).

MSymbol Mcode_unit

mconv_define_coding() 用パラメータキー (詳細は mconv_define_coding()参照).

MSymbol Mbom

mconv_define_coding() 用パラメータキー (詳細は mconv_define_coding()参照).

MSymbol Mlittle_endian

mconv_define_coding() 用パラメータキー (詳細は mconv_define_coding()参照).

MSymbol Mutf

関数 mconv_define_coding() の引数として用いられるコード系のパラメータ Mtype の値となり得るシンボル。(詳細は mconv_define_coding()参照)。

MSymbol Miso_2022

関数 mconv_define_coding() の引数として用いられるコード系のパラメータ Mtype の値となり得るシンボル。(詳細は mconv_define_coding()参照)。

MSymbol Mreset_at_eol