6.6 – UTF-8サポート

このライブラリはUTF-8エンコーディングの基本的なサポートを提供します。すべての関数はテーブルutf8内にあります。このライブラリは、エンコーディングの処理を除き、Unicodeをサポートしません。文字の分類など、文字の意味を必要とする操作は対象外です。

特に記載がない限り、バイト位置を引数として受け取るすべての関数は、指定された位置がバイト列の先頭か、対象文字列の長さに1を加えた位置であると仮定します。文字列ライブラリと同様に、負のインデックスは文字列の末尾から数えます。

バイト列を作成する関数は、元のUTF-8仕様で定義されている0x7FFFFFFFまでのすべての値を受け入れます。これは最大6バイトのバイト列を意味します。

バイト列を解釈する関数は、有効な列（整形式で、過長ではないもの）のみを受け入れます。デフォルトでは、有効なUnicodeコードポイントになるバイト列のみを受け入れ、10FFFFより大きい値とサロゲートを拒否します。利用できる場合は、ブール引数laxによってこれらの検査を解除し、0x7FFFFFFFまでのすべての値を受け入れられます。（整形式でない列と過長な列は引き続き拒否されます。）

utf8.char (···)

0個以上の整数を受け取り、それぞれを対応するUTF-8バイト列に変換し、それらすべてを連結した文字列を返します。

utf8.charpattern

パターン（関数ではなく文字列）“[\0-\x7F\xC2-\xFD][\x80-\xBF]*”（§6.5.1を参照）です。対象が有効なUTF-8文字列であると仮定したとき、ちょうど1つのUTF-8バイト列にマッチします。

utf8.codes (s [, lax])

次の構文が

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

文字列s内のすべてのUTF-8文字を反復処理するような値を返します。pは各文字の位置（バイト単位）、cはコードポイントです。無効なバイト列に遭遇するとエラーを発生させます。

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

s内で、バイト位置iからjまで（両端を含む）の間で始まるすべての文字のコードポイントを整数として返します。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番目の文字（バイト位置iから数える）の位置を2つの整数、つまりエンコーディングが始まるインデックス（バイト単位）と終わるインデックス（バイト単位）として返します。

指定した文字がsの末尾の直後にある場合、この関数はそこに’\0’があるかのように動作します。指定した文字が対象内にも末尾の直後にもない場合、関数はfailを返します。

負のnは位置iより前の文字を取得します。iのデフォルトは、nが非負なら1、それ以外なら#s + 1です。そのため、utf8.offset(s,-n)は文字列の末尾からn番目の文字のオフセットを取得します。

特殊な場合として、nが0なら、関数はsのi番目のバイトを含む文字について、エンコーディングの先頭と末尾を返します。

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