"EUC_codes": Count up the EUC-JP string utility in C
 Happy Hacking!

EUC_codes: EUC-JP 文字列の文字数を計数し文字数指定で部分文字列を切り出すユーティリティ

この C 言語ユーティリティは、EUC-JP 文字列中の文字数を計数することと文字数指定による EUC-JP 部分文字列の切り出しも行えます。部分文字列の切り出しには、部分文字列を表示する際の表示桁数を指定することも出来ます。この場合は、指定した表示桁数から溢れない最大長の部分文字列を切り出します。

trim_EUCJP_spaces: EUC-JP 文字列から全角空白 "\xa1\xa1" と ASCII 空白文字を取り除くユーティリティ

trim_EUCJP_spacesは、EUC-JP 文字列の先頭あるいは末尾に連続して存在している全角空白文字 "\xa1\xa1" と ASCII コードセットの空白文字 (isspace() が真を返す文字) を取り除きます。

strcpy_EUCJP: EUC-JP 文字列を文字化けしないように文字列コピーするユーティリティ

strcpy_EUCJPは、EUC-JP 文字列を文字化けしないように文字列コピーします。

API を使用するためのヘッダは EUC_code_counter.h で、API の実装は EUC_code_counter.c です。API の説明は、この文書で後述しています。

テスト・プログラム unit_test.c そして make ファイル Makefile を記述しました。テストは、

        $ make clean; make; make test

API の説明

1. EUC-JP 文字列中の文字数を計数する count_euc_code_characters()
   

   size_t count_euc_code_characters(unsigned char *str
                      , size_t                          str_sz
                      , EUC_code_character_class_counts *counts
                      )
   

   size_t count_euc_characters_as_sjis(unsigned char *str
                      , size_t                          str_sz
                      , EUC_code_character_class_counts *counts
                      )
   

   count_euc_characters_as_sjis() は EUC-JP 文字列を SJIS に変換した結果の文字列長を返すマクロです。EUC-JP 文字列を SJIS 文字コードに変換する際に必要なメモリ領域サイズは、このマクロの結果値に 1 を加えた値になります。

   str には計数の対象となる EUC-JP 文字列を指定します。str_sz には str の指すメモリ領域のサイズを指定します。counts には EUC-JP 文字コード体系のどの種類の文字区分にいくつの文字が含まれているかについての情報を出力します。

   EUC_code_character_class_counts 構造体の詳細は、以下のとおりです。

   • size_t length_of_bytes : EUC-JP 文字列長
   • size_t count_of_new_lines : 改行コード数
   • size_t count_of_controls : ASCII 制御コード数
   • size_t count_of_ASCII : EUC G0 区分 (ASCII コード相当) の文字数
   • size_t count_of_JIS_X_0208_1983 : EUC G1 区分 (JIS X 0208-1983 相当、日本語漢字第 1 および第 2 水準) の文字数
   • size_t count_of_JIS_X_0201_1976 : EUC G2 区分 (JIS X 0201-1976 相当、日本語半角カナ文字) の文字数
   • size_t count_of_JIS_X_0212_1990 : EUC G3 区分 (JIS X 0212-1990 相当、日本語外字 (機種依存文字など)) の文字数
   • size_t count_of_UNKNOWN : EUC-JP 以外の文字コードのバイト数。この値が 0 でない場合は、str に指定した文字列は EUC-JP 文字コードでないことになります。
   
   

   戻り値に計数した文字数を返します。が、str に指定した文字列が EUC-JP でない場合や不正な引数が渡された場合は、 errno に EINVAL を出力します。

2. 文字数あるいは表示文字桁数で指定した EUC-JP 部分文字列を切り出す substr_of_euc_code_string()
   

   char *substr_of_euc_code_string(
                  unsigned char *str
                , size_t         str_sz
                , size_t         nth_char
                , size_t         n_chars
                , size_t         w_chars
                , char          *delimits
                , size_t        (*metrics)(
                                         unsigned char *str
                                       , size_t        sz
                                       , void          *usrdata
                                       )
                , void           *usrdata
                , size_t         *size
                , size_t         *width
                )
   

   str には EUC-JP 文字列を指定します。str_sz には str の指すメモリ領域のサイズを指定します。nth_char には切り出す部分文字列の先頭にあたる文字の文字位置を 0 以上の値で指定します。

   切り出す部分文字列を文字数で指定する場合は、 n_chars に部分文字列の文字数を 1 以上の値で指定します。w_chars には 0 を指定します。また、delimits は無視されます。

   切り出す部分文字列を表示文字桁数で指定する場合は、w_chars に表示桁数を 1 以上の値で指定します。delimits には文字終端コード '\0' と同じ扱いをする区切り文字を文字列で指定します。通常、delimits には "\n" として改行文字を指定することになります。n_chars には 0 を指定します。

   metrics と usrdata に NULL を指定することでデフォルトの EUC-JP 文字表示桁数算出 (単純に半角文字の表示桁数で文字桁数を算出する) を行います。が、このデフォルトの算出法とは異なる文字ごとの表示桁数算出を行う場合のために、metrics には EUC-JP 文字ごとの表示桁数を返す関数を指定できます。metrics 関数には、str 文字列中のある 1 文字のアドレス位置とその文字のバイトサイズ、そして文字表示桁数を求めるために自由に使用できるコンテキスト情報 usrdata が渡されます。usrdata の扱い方は metrics 関数の実装に依存します。metrics 関数の戻り値は size_t 型です。

   size には切り出した部分文字列のサイズを出力します。
   n_chars にゼロを指定した場合は、width には切り出した部分文字列の表示桁数あるいは metric 関数で求めた表示幅の総和 (最大 w_chars まで) を出力します。n_chars に正整数を指定した場合は、width のには size と同じ値を出力します。

   部分文字列が正常に切り出せた場合は、str の指すメモリ領域中の部分文字列先頭アドレスを返します。不正な引数や EUC-JP 以外の文字コードが見つかった場合には、NULL を返し errno にエラー原因を出力します。errno に出力されるエラー原因の詳細は以下のとおりです。

   • EINVAL : 不正な引数あるいは EUC-JP 以外の文字コードが str に含まれている場合
   • EDOM : nth_char が str の指す文字列メモリ領域を越えている場合
   
   
3. 文字列先頭あるいは末尾に連続して存在している全角空白文字と ASCII コードセットの空白文字を取り除く trim_EUCJP_spaces()
   

   char *trim_EUCJP_spaces(
                  Trim_EUCJP_spaces_direction_t direct
                , char                          *str
                )
   

   direct には Trim_EUCJP_spaces_LEFT (文字列先頭) と Trim_EUCJP_spaces_RIGHT (文字列末尾) のいずれかあるいは両方の論理和に、ASCII コードセット中のすべての空白文字コード (isspace() が真を返す) を取り除く場合は Trim_ASCII_all_space_codes との論理和を指定できます。

   str には空白文字を取り除く対象の文字列を指定します。

   正常に空白文字を取り除けた場合は str の値を返します。不正な引数を渡された場合には NULL を返し errno に EINVAL を出力します。

4. EUC-JP 文字列を文字化けしないように文字列コピーする strcpy_EUCJP()
   

   char *strcpy_EUCJP(
                  unsigned char *src
                , char          *dst
                , size_t        dst_sz
                )
   

   src には EUC-JP エンコーディングされたコピー元の文字列を指定します。
   dst にはコピー先のバッファのアドレスを指定します。
   dst_sz には dst の指すバッファのサイズ (1 以上) を指定します。

   正常に文字列をコピーできた場合は、 dst の値を返します。不正な引数あるいは EUC-JP エンコーディングされていない文字列を渡された場合には NULL を返し errno に EINVAL を出力します。