6.5 UTF-8 サポート

このライブラリは基本的な UTF-8 エンコーディングのサポートを提供します。全ての関数は utf8 テーブルに公開されます。このライブラリに含まれる Unicode のサポートはエンコーディング処理だけであり、文字種の識別といった文字の意味が必要となる操作は対象外です。

特に断っていない限り、パラメータにバイト位置を取る全ての関数はその位置がバイトシーケンスの始まりまたは対象文字列の長さに 1 を加えた値であることを仮定します。また文字列ライブラリと同様、負のインデックスは文字列の最後から数えます。

バイトシーケンスを作成する関数は 0x7FFFFFFF までの全ての値を受け取ります。これはバイトシーケンスを最大 6 バイトで表すオリジナルの UTF-8 仕様の定義に従っています。

バイトシーケンスを解釈する関数は正当な (well-formed かつオーバーロングでない) シーケンスだけを受け付けます。デフォルトでは正当な Unicode 符号位置を表すシーケンスだけが受理され、10FFFF より大きい値およびサロゲートペアは拒否されます。利用可能な場合には真偽値引数 lax を true にすることでこのチェックを無効化し、0x7FFFFFFF までの全ての値を受理させることができます (この場合でも well-formed でないシーケンスおよびオーバーロングなシーケンスは拒否されます)。

utf8.char (...)

ゼロ個以上の整数を受け取り、それぞれを対応する UTF-8 バイトシーケンスに変換し、それらのシーケンスを連結した文字列を返します。

utf8.charpattern

パターン "[\0-\x7F\xC2-\xFD][\x80-\xBF]*" です。文字列であり、関数ではありません。正当な UTF-8 文字列をこのパターンで検索すると、ちょうど一つの UTF-8 バイトシーケンスがマッチします。

utf8.codes (s [, lax])

文字列 s に含まれる全ての UTF-8 文字を次のコードでイテレートできるような値を返します:

for p, c in utf8.codes(s) do body end

ここで p は位置 (バイト数) で、c は文字の符号位置です。不当なバイトシーケンスに遭遇した場合にはエラーを送出します。

utf8.codepoint (s [, i [, j [, lax]]])

文字列 s の i バイト目から j バイト目まで (両端含む) に含まれる UTF-8 文字の符号位置を整数として返します。デフォルトでは i は 1 および j は i です。不当なバイトシーケンスに遭遇した場合にはエラーを送出します。

utf8.len (s [, i [, j [, lax]]])

文字列 s の i バイト目から j バイト目まで (両端含む) に含まれる UTF-8 文字の数を返します。デフォルトでは i は 1 および j は -1 です。不当なバイトシーケンスを見つけた場合には fail と不当なバイトの位置を返します。

utf8.offset (s, n [, i])

s に含まれる n 文字目の UTF-8 文字が始まる位置 (バイト数) を i から数えた値として返します。n を負とすれば i より前にある文字の位置が返ります。i のデフォルト値は n が非負のとき 1 で、n が負のとき #s + 1 です。このため utf8.offset(s, -n) は文字列の最後から n 個目の UTF-8 文字へのオフセットを返します。指定された文字が対象の文字列に存在せず、文字列の終わりの次の文字でもない場合には fail を返します。

特別な場合として n を 0 とすると、この関数は s の i バイト目を含む UTF-8 文字が始まる位置を返します。

この関数は s が正当な UTF-8 文字列であることを仮定します。