6.5 – 文字列操作

このライブラリは、部分文字列の検索と抽出、パターンマッチングなど、文字列操作の汎用関数を提供します。Luaで文字列へインデックスを付けるとき、先頭文字の位置は（Cのような0ではなく）1です。負のインデックスも使用でき、文字列の末尾から逆向きに数えるものとして解釈されます。したがって、末尾文字の位置は-1となります。

文字列ライブラリは、すべての関数をテーブルstring内に提供します。また、文字列には__indexフィールドがstringテーブルを指すメタテーブルを設定します。そのため、文字列関数をオブジェクト指向形式で使えます。たとえば、string.byte(s,i)はs:byte(i)と書けます。

文字列ライブラリは1バイト文字エンコーディングを前提とします。

`string.byte (s [, i [, j]])`

文字s[i]、s[i+1]、…、s[j]の内部数値コードを返します。iの既定値は1、jの既定値はiです。これらのインデックスは関数string.subと同じ規則で補正されます。

数値コードがプラットフォーム間で移植可能とは限りません。

`string.char (···)`

0個以上の整数を受け取ります。引数の個数と等しい長さを持ち、各文字の内部数値コードが対応する引数と等しい文字列を返します。

数値コードがプラットフォーム間で移植可能とは限りません。

`string.dump (function [, strip])`

指定した関数のバイナリ表現（バイナリチャンク）を含む文字列を返します。後でこの文字列をloadすると、新しいアップバリューを持つ関数のコピーが返されます。stripが真値なら、領域節約のため、バイナリ表現に関数のデバッグ情報がすべて含まれないことがあります。

アップバリューを持つ関数では、その個数だけが保存されます。（再）ロード時には、それらのアップバリューに新しい実体が与えられます。初期化方法の詳細はload関数を参照してください。デバッグライブラリを使えば、必要に合った方法で関数のアップバリューをシリアライズして再ロードできます。

`string.find (s, pattern [, init [, plain]])`

文字列s内でpattern（§6.5.1を参照）に最初にマッチする箇所を探します。見つかった場合、findはその箇所がs内で始まる位置と終わる位置のインデックスを返し、それ以外ではfailを返します。省略可能な第3数値引数initは検索開始位置を指定します。既定値は1で、負数も指定できます。省略可能な第4引数plainをtrueにするとパターンマッチング機能が無効になり、pattern内のどの文字も特殊文字とはみなさず、単純な「部分文字列の検索」を行います。

パターンにキャプチャがある場合、マッチに成功すると、2つのインデックスに続いてキャプチャされた値も返します。

`string.format (formatstring, ···)`

文字列でなければならない第1引数の記述に従い、可変個の引数を整形した結果を返します。書式文字列はISO C関数sprintfと同じ規則に従います。使用できる変換指定子はA、a、c、d、E、e、f、G、g、i、o、p、s、u、X、x、および「%」に加え、Cにはないqです。使用できるフラグは「-」、「+」、「#」、「0」、「“」（空白）です。幅と精度は、指定する場合、いずれも2桁までに制限されます。

指定子qは、結果がLuaソースコード内で有効な定数になるように真偽値、nil、数値、文字列を整形します。真偽値とnilは通常どおり（true、false、nil）に書かれます。浮動小数点数は完全な精度を保つため16進数で書かれます。文字列は二重引用符で囲まれ、Luaインタープリターで安全に読み戻せるよう、必要に応じてエスケープシーケンスを使います。たとえば、次の呼び出しは

     string.format('%q', 'a string with "quotes" and \n new line')

次の文字列を生成することがあります。

     "a string with \"quotes\" and \
      new line"

この指定子は修飾子（フラグ、幅、精度）をサポートしません。

変換指定子A、a、E、e、f、G、gはいずれも数値を引数として要求します。指定子c、d、i、o、u、X、xは整数を要求します。LuaをC89コンパイラーでコンパイルした場合、指定子Aとa（16進浮動小数点数）は修飾子をサポートしません。

指定子sは文字列を要求します。引数が文字列でなければ、tostringと同じ規則で文字列へ変換されます。指定子に修飾子がある場合、対応する文字列引数に埋め込みゼロを含めるべきではありません。

指定子pはlua_topointerが返すポインターを整形します。これはテーブル、ユーザーデータ、スレッド、文字列、関数に一意な文字列識別子を与えます。そのほかの値（数値、nil、真偽値）では、この指定子はポインターNULLを表す文字列になります。

`string.gmatch (s, pattern [, init])`

呼び出すたびに、文字列sに対するpattern（§6.5.1）の次のキャプチャを返すイテレーター関数を返します。patternがキャプチャを指定しない場合、各呼び出しでマッチ全体を生成します。省略可能な第3数値引数initは検索開始位置を指定します。既定値は1で、負数も指定できます。

例として、次のループは文字列s内のすべての単語を反復し、1行に1つずつ表示します。

     s = "hello world from Lua"
     for w in string.gmatch(s, "%a+") do
       print(w)
     end

次の例は、指定した文字列内のすべてのkey=valueペアをテーブルへ集めます。

     t = {}
     s = "from=world, to=Lua"
     for k, v in string.gmatch(s, "(%w+)=(%w+)") do
       t[k] = v
     end

この関数では、パターン先頭のキャレット「^」はアンカーとして機能しません。アンカーにすると反復できなくなるためです。

`string.gsub (s, pattern, repl [, n])`

s内にあるpattern（§6.5.1）のすべての出現箇所（nを指定した場合は先頭からその個数）を、replで指定した置換文字列へ置き換えたコピーを返します。置換引数には文字列、テーブル、関数を指定できます。

gsubは第2の値として、発生したマッチの総数も返します。gsubという名前はGlobal SUBstitution（大域的置換）に由来します。

replが文字列なら、その値を置換に使います。文字%はエスケープ文字として機能します。repl内の%dという形式の並び（dは1から9）はd番目にキャプチャされた部分文字列の値を表し、%0はマッチ全体、%%は1つの%を表します。

replがテーブルなら、各マッチについて、最初のキャプチャをキーとしてテーブルを検索します。

replが関数なら、マッチするたびにすべてのキャプチャされた部分文字列を順番に引数として、その関数を呼び出します。

いずれの場合も、パターンがキャプチャを指定していなければ、パターン全体がキャプチャ内にあるものとして動作します。

テーブル検索または関数呼び出しが返した値が文字列か数値なら、それを置換文字列として使います。それ以外でfalseまたはnilなら置換せず、元のマッチを文字列内に残します。

例を示します。

     x = string.gsub("hello world", "(%w+)", "%1 %1")
     -- x="hello hello world world"
     
     x = string.gsub("hello world", "%w+", "%0 %0", 1)
     -- x="hello hello world"
     
     x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
     -- x="world hello Lua from"
     
     x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
     -- x="home = /home/roberto, user = roberto"
     
     x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
           return load(s)()
         end)
     -- x="4+5 = 9"
     
     local t = {name="lua", version="5.5"}
     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
     -- x="lua-5.5.tar.gz"

`string.len (s)`

文字列を受け取り、その長さを返します。空文字列""の長さは0です。埋め込みゼロも数えるため、"a\000bc\000"の長さは5です。

`string.lower (s)`

文字列を受け取り、そのすべての大文字を小文字へ変更したコピーを返します。そのほかの文字は変更しません。何を大文字とするかの定義は現在のロケールに依存します。

`string.match (s, pattern [, init])`

文字列s内でpattern（§6.5.1を参照）に最初にマッチする箇所を探します。見つかった場合、matchはパターンのキャプチャを返し、それ以外ではfailを返します。patternがキャプチャを指定しない場合、マッチ全体を返します。省略可能な第3数値引数initは検索開始位置を指定します。既定値は1で、負数も指定できます。

`string.pack (fmt, v1, v2, ···)`

書式文字列fmt（§6.5.2を参照）に従い、値v1、v2などをバイナリ形式にシリアライズ（パック）して含むバイナリ文字列を返します。

`string.packsize (fmt)`

指定した書式でstring.packを行った結果の文字列長を返します。書式文字列には可変長の選択肢「s」または「z」を含められません（§6.5.2を参照）。

`string.rep (s, n [, sep])`

文字列sepを区切りとして文字列sをn個連結した文字列を返します。sepの既定値は空文字列、すなわち区切りなしです。nが正でなければ空文字列を返します。

（この関数を1回呼び出すだけで、非常に簡単にコンピューターのメモリを使い果たせる点に注意してください。）

`string.reverse (s)`

文字列sを逆順にした文字列を返します。

`string.sub (s, i [, j])`

sのiから始まりjまで続く部分文字列を返します。iとjには負数も指定できます。jを省略した場合は-1、すなわち文字列長と同じものとみなします。特に、呼び出しstring.sub(s,1,j)はsの長さjの接頭部を返し、string.sub(s,-i)（正のiについて）はsの長さiの接尾部を返します。

負のインデックスを変換した後でiが1未満なら1へ補正します。jが文字列長を超えるなら、その長さへ補正します。これらの補正後にiがjを超える場合、関数は空文字列を返します。

`string.unpack (fmt, s [, pos])`

書式文字列fmt（§6.5.2を参照）に従い、文字列sにパックされた値（string.packを参照）を返します。省略可能なposはs内で読み始める位置を示し、既定値は1です。この関数は読み取った値の後に、s内で最初の未読バイトのインデックスも返します。

`string.upper (s)`

文字列を受け取り、そのすべての小文字を大文字へ変更したコピーを返します。そのほかの文字は変更しません。何を小文字とするかの定義は現在のロケールに依存します。

6.5.1 – パターン

Luaのパターンは通常の文字列で記述され、パターンマッチング関数string.find、string.gmatch、string.gsub、string.matchがパターンとして解釈します。この節では、これらの文字列の構文と意味、すなわち何にマッチするかを説明します。

文字クラス：

文字クラスは文字の集合を表します。文字クラスの記述では、次の組み合わせを使用できます。

x: xが特殊文字^$()%.[]*+-?のいずれでもない場合、文字xそのものを表します。
.: ピリオドはすべての文字を表します。
%a: すべての英字を表します。
%c: すべての制御文字を表します。
%d: すべての数字を表します。
%g: 空白を除くすべての表示可能文字を表します。
%l: すべての小文字を表します。
%p: すべての句読文字を表します。
%s: すべての空白文字を表します。
%u: すべての大文字を表します。
%w: すべての英数字を表します。
%x: すべての16進数字を表します。
%x: xが英数字以外の任意の文字である場合、文字xを表します。これは特殊文字をエスケープする標準的な方法です。英数字以外の任意の文字は、特殊文字でない句読文字も含め、前に「%」を置くとパターン内でその文字自体を表せます。
[set]: set内のすべての文字の和集合であるクラスを表します。範囲の両端の文字を昇順に「-」で区切ると、文字範囲を指定できます。前述のすべてのクラス%xもsetの要素として使えます。set内のほかの文字は、それ自体を表します。たとえば、[%w_]（または[_%w]）は英数字とアンダースコア、[0-7]は8進数字、[0-7%l%-]は8進数字、小文字、「-」を表します。集合の最初の文字にすれば閉じ角括弧を、最初または最後の文字にすればハイフンを集合へ含められます。どちらもエスケープすることもできます。範囲とクラスの相互作用は未定義なので、[%a-z]や[a-%%]のようなパターンに意味はありません。
[^set]: 前述のように解釈したsetの補集合を表します。

単一の英字で表すすべてのクラス（%a、%cなど）では、対応する大文字がそのクラスの補集合を表します。たとえば、%Sは空白以外のすべての文字を表します。

英字、空白、そのほかの文字グループの定義は現在のロケールに依存します。特に、クラス[a-z]が%lと等価とは限りません。

パターン項目：

パターン項目には次のものがあります。

1つの文字クラス。クラス内の任意の1文字にマッチします。
1つの文字クラスの後に「*」を付けたもの。クラス内の文字が0個以上続く並びにマッチし、常に可能な限り長い並びへマッチします。
1つの文字クラスの後に「+」を付けたもの。クラス内の文字が1個以上続く並びにマッチし、常に可能な限り長い並びへマッチします。
1つの文字クラスの後に「-」を付けたもの。これもクラス内の文字が0個以上続く並びにマッチしますが、「*」とは異なり、常に可能な限り短い並びへマッチします。
1つの文字クラスの後に「?」を付けたもの。クラス内の文字の0回または1回の出現にマッチし、可能なら常に1回の出現へマッチします。
%n。nは1から9で、n番目にキャプチャされた文字列と等しい部分文字列にマッチします（後述）。
%bxy。xとyは異なる2文字で、xで始まりyで終わり、xとyの対応が均衡している文字列にマッチします。左から右へ読み、xで*+1*、yで*-1と数えたとき、末尾のyがカウントが0になる最初のy*です。たとえば、項目%b()は括弧が均衡した式にマッチします。
%f[set]という境界パターン。次の文字がsetに属し、前の文字がsetに属さない位置の空文字列へマッチします。集合setは前述のとおり解釈します。対象の先頭と末尾は文字「\0」があるものとして扱います。

パターン：

パターンはパターン項目の並びです。パターン先頭のキャレット「^」は対象文字列の先頭へマッチを固定します。パターン末尾の「$」は対象文字列の末尾へマッチを固定します。それ以外の位置では「^」と「$」に特別な意味はなく、それ自体を表します。

キャプチャ：

パターンには括弧で囲んだ部分パターンを含めることができ、これをキャプチャと呼びます。マッチに成功すると、キャプチャにマッチした対象文字列の部分文字列が後で使うために保存（キャプチャ）されます。キャプチャには左括弧の順に番号が付きます。たとえば、パターン"(a*(.)%w(%s*))"では、"a*(.)%w(%s*)"へマッチした部分が第1キャプチャで番号1、文字「.」へマッチした部分が番号2、「%s*」へマッチした部分が番号3です。

特別な場合として、キャプチャ()は現在の文字列位置（数値）をキャプチャします。たとえば、文字列"flaaap"へパターン"()aa()"を適用すると、3と5の2つをキャプチャします。

複数のマッチ：

関数string.gsubとイテレーターstring.gmatchは、対象内で指定したパターンの複数の出現へマッチします。これらの関数では、新しいマッチは前のマッチの末尾から少なくとも1バイト後で終わる場合だけ有効です。言い換えると、パターン機構は別のマッチの直後に空文字列をマッチとして受け入れません。次のコードの結果を例に示します。

     > string.gsub("abc", "()a*()", print);
     --> 1   2
     --> 3   3
     --> 4   4

第2、第3の結果は、「b」の後と「c」の後の空文字列へLuaがマッチしたものです。「a」の後の空文字列は前のマッチと同じ位置で終わるため、Luaはそこへマッチしません。

6.5.2 – packとunpackの書式文字列

string.pack、string.packsize、string.unpackの第1引数は、作成または読み取り対象の構造体の配置を記述する書式文字列です。

書式文字列は変換選択肢の並びです。変換選択肢は次のとおりです。

<: リトルエンディアンに設定します。
>: ビッグエンディアンに設定します。
=: ネイティブエンディアンに設定します。
![n]: 最大アラインメントをnに設定します（既定値はネイティブのアラインメント）。
b: 符号付きバイト（char）。
B: 符号なしバイト（char）。
h: 符号付きshort（ネイティブサイズ）。
H: 符号なしshort（ネイティブサイズ）。
l: 符号付きlong（ネイティブサイズ）。
L: 符号なしlong（ネイティブサイズ）。
j: lua_Integer。
J: lua_Unsigned。
T: size_t（ネイティブサイズ）。
i[n]: nバイトの符号付きint（既定値はネイティブサイズ）。
I[n]: nバイトの符号なしint（既定値はネイティブサイズ）。
f: float（ネイティブサイズ）。
d: double（ネイティブサイズ）。
n: lua_Number。
cn: nバイトの固定長文字列。
z: ゼロ終端文字列。
s[n]: 前にnバイトの符号なし整数として符号化された長さを持つ文字列（既定値はsize_t）。
x: 1バイトのパディング。
Xop: 選択肢opに従って整列する空の項目（それ以外ではその選択肢を無視）。
「“」: 空白。無視します。

「[n]」は省略可能な整数値を意味します。パディング、空白、設定（選択肢「xX <=>!」）を除き、各選択肢はstring.packの引数またはstring.unpackの結果に対応します。

選択肢「!n」、「sn」、「in」、「In」では、nに1から16までの任意の整数を指定できます。すべての整数選択肢はオーバーフローを検査します。string.packは指定した値が指定サイズへ収まるかを検査し、string.unpackは読み取った値がLua整数へ収まるかを検査します。符号なしの選択肢では、Lua整数も符号なし値として扱います。

すべての書式文字列は「!1=」が前置されているものとして始まります。すなわち、最大アラインメントは1（アラインメントなし）で、ネイティブエンディアンです。

ネイティブエンディアンでは、システム全体がビッグエンディアンまたはリトルエンディアンのいずれかであることを前提とします。パック関数は、混在エンディアン形式の動作を正しく再現しません。

アラインメントは次のように働きます。各選択肢について、データの開始オフセットが、選択肢のサイズと最大アラインメントの小さい方の倍数になるまで、書式に追加のパディングが入ります。この最小値は2の累乗でなければなりません。選択肢「c」と「z」は整列されません。選択肢「s」は先頭の整数のアラインメントに従います。

すべてのパディングはstring.packによってゼロで埋められ、string.unpackでは無視されます。