Lua標準ライブラリ/文字列ライブラリ

## 文字列ライブラリ

Luaの文字列のインデックス付けは、最初の文字が1の位置である (C、PHP、JavaScriptのように0ではない)。 文字列の末尾から逆方向にマイナス値で指定することもできる。 つまり、最後の文字は -1 の位置で示される。

『待った！』 この文字列ライブラリは1バイト専用と言ってもよく、
**2バイト以上の文字に対応していません**。

2バイト以上の文字を含む場合は、ScribuntoのUstlingライブラリをご利用ください。

### string.byte

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

文字列`s`の`i`番目から`j`番目までの文字コードの値を返します。
省略時`i`は1、`j`は`i`と同じになります。
Identical to `mw.ustring.byte()`.

### string.char

`string.char(...)`

引数の数値と等しい文字コードの文字を連結した文字列を返します

See `mw.ustring.char()` for a similar function that uses Unicode codepoints rather than byte values.

### string.find

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

文字列`s`内でのパターン`p`の最初のマッチの開始位置と終了位置を返します。

マッチしなかった場合はnilを返します。init には検索開始位置を指定します。

plain が true の場合パターンマッチングは行われず、単純な部分文字列検索になります。

パターン内にキャプチャが指定されていた場合、その内容が3番目以降の戻り値として返されます。

See `mw.ustring.find()` for a similar function extended as described in Ustring patterns and where the `init` offset is in characters rather than bytes.

### string.format

`string.format(fmt, ...)`

任意のフォーマットで記述します。書式文字列は標準C関数の`printf`と同じ。

* 認識されるフラグは '-'、'+'、''、'#'、および '0'。
* 最大99までの整数フィールド幅がサポートされています。
* 最大99までの整数精度がサポートされています。
	+ どちらも'\*'は未サポート。
* 長さ指定子は全て未サポート。
* 位置指定子("%2$s"みたいなの)も未サポート。
* それ以外の 'c', 'd', 'i', 'o', 'u', 'x', 'X', 'e', 'E', 'f', 'g', 'G', 's', '%'と'q'はサポートされている。
	+ 未サポート：\*、l、L、n、p、h
	+ 追加：q

q オプションは、Luaインタプリタで安全に読み戻せる適切な形式の文字列に書式化する。この時、文字列はダブルクォートの間に書かれ、文字列中のダブルクォート、改行、埋め込まれたゼロ、バックスラッシュは正しくエスケープされる。

c、d、E、e、f、g、G、i、o、u、X、x はすべて数値の引数を期待し、 q と s は文字列を期待する。

文字列と数値の間の変換はデータ型の指定に従って実行されます。他の型は自動的に文字列に変換されません。 NUL文字（バイト値0）を含む文字列は正しく処理されません。

Identical to `mw.ustring.format()`.

### string.gmatch

`string.gmatch(s, p)`

汎用 for 文で使用します。文字列`s`内の正規表現`p`にマッチする部分文字列を返すイテレータ関数を返します。`pattern`にキャプチャが指定されていない場合は、各呼び出しで完全一致が生成されます。

この関数では、パターンの先頭にある '`^`'は、繰り返しを妨げるので魔法のようなものではありません。それはリテラル文字として扱われます。

See `mw.ustring.gmatch()` for a similar function for which the pattern is extended as described in Ustring patterns.

### string.gsub

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

文字列`s`内のパターン`p`にマッチする部分を`repl`で置換します。

`repl`には文字列、テーブル、関数のいずれかを指定します。`n`には置換が行われる回数を指定します。

返値は実際に置換が行われた回数が入ります。

`repl`が文字列の場合は、その文字列が置換に使われます。文字`%`はエスケープ文字として働きます。`repl`中の`%*n*`(ただし*n*は1から9)はd番目のキャプチャした部分文字列の値(以下参照)を表します。`%0`はマッチ全体を表し、`%%`は単一の`%`を表します。
`repl`がテーブルの場合は、各マッチごとに最初のキャプチャをキーとしてテーブルを引きます。パターンにキャプチャがなければ、マッチ全体をキーとして使います。
`repl`が関数の場合は、その関数はマッチが現れるたびに呼ばれ、すべてのキャプチャされた部分文字列が順番通りに引数として渡されます。パターンにキャプチャがなければ、マッチ全体が単一の引数として渡されます。
テーブル検索または関数呼び出しの戻り値が文字列または数値であれば、それが置換文字列として使われます。そうでなく、falseまたはnilであれば、置換されません(つまり、元のマッチがそのまま文字列中に保たれます)。
See `mw.ustring.gsub()` for a similar function in which the pattern is extended as described in Ustring patterns.

### string.len

`string.len(s)`
string.len(str) 文字列の長さを取得します。`#s`でも代用できます

空文字列 "" の長さは0である。 文字列中のゼロも数えるので、"a\000b\000c" の長さは5である。

See `mw.ustring.len()` for a similar function using Unicode codepoints rather than bytes.

### string.lower

`string.lower(s)`

文字列s中のアルファベットを小文字にした文字列を返します

アルファベットと同じ値の2バイト文字も変換されるので注意

See `mw.ustring.lower()` for a similar function in which all characters with uppercase to lowercase definitions in Unicode are converted.

### string.match

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

文字列`s`内のパターン`p`にマッチする部分文字列を返します。見つからなければ`nil`を返します。

パターン内にキャプチャがあればそれを返します。`init`(省略時は1)は検索開始位置を指定します。

See `mw.ustring.match()` for a similar function in which the pattern is extended as described in Ustring patterns and the `init` offset is in characters rather than bytes.

### string.rep

`string.rep(s, n)`

文字列`s`を`n`回繰り返した文字列を返します。Identical to `mw.ustring.rep()`.

### string.reverse

`string.reverse(s)`

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

2バイト文字は正しく処理されません

### string.sub

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

文字列`s`の`i`番目から`j`番目の文字までの部分文字列を返します。
`j`省略時は文字列の末尾になります。

特に、`string.sub(s,1,j)`は`s`の先頭から`j`文字を取り出し、`string.sub(s, -i)`は`s`の最後の`i`文字を取り出す。

See `mw.ustring.sub()` for a similar function in which the offsets are characters rather than bytes.

### string.upper

`string.upper(s)`

文字列`s`中のアルファベットを大文字にした文字列を返します

アルファベットと同じ値の2バイト文字も変換されるので注意

See `mw.ustring.upper()` for a similar function in which all characters with uppercase to lowercase definitions in Unicode are converted.

### Luaパターン

Luaパターンは正規表現のようでそうでない。特に、正規表現やPCREとの以下の違いに注意するように:

* メタ文字にPerlなどの「`\`」ではなく、「`%`」を使う。
* ドット(`.`)は改行コードもマッチ対象。
* 文字クラスの小文字と大文字の関係は補集合となる。
* 「複数の正規表現のいずれかにマッチ」する `|` は実装されていない。
* 量指定子（`*`、`+`、`?`、および`-` ）はグループを捕らえず、個々の文字または文字クラスにのみ適用できます。
* -は0回以上の最短マッチ。(-は既存の正規表現でいうところの｢\*?｣と思っておけばよいだろう。)
* 一般化された有限数量詞はありません（例えば、PCREの `{*n*、 *m*}` 数量詞）。
* 幅がゼロのアサーションは、`^`、`$`、および`％f[set]` "frontier"パターンのみです。 PCREの`\b`や`(?=···)`などのアサーションは存在しません。
* パターン自体は '\''ddd'''のような文字エスケープを認識しません。ただし、パターンはstringsなので、これらの種類のエスケープは、pattern-stringを作成するために使用される文字列リテラルで使用できます。

パターンには途中にゼロ(ASCII NUL、`"\0"`)を含むことができない。代わりに`%z`を使う。

Also see Ustring patterns for a similar pattern-matching scheme using Unicode characters.

#### 文字クラス

*文字クラス* は文字の集合を表すために使われます。 文字クラスの記述では以下の組み合わせが使用できます。

#### パターンの要素

*パターンの要素* は以下のいずれかである。

* 単一の文字クラス
* 単一の文字クラスに'`*`'が続いたもの。そのクラスの文字の0以上の繰り返しにマッチする。可能な限り長いシーケンスにマッチする。
* 単一の文字クラスに'`+`'が続いたもの。そのクラスの文字の1以上の繰り返しにマッチする。可能な限り長いシーケンスにマッチする。
* 単一の文字クラスに'`-`'が続いたもの。そのクラスの文字の0以上の繰り返しにマッチする。'`*`'と異なり、可能な限り*短い*シーケンスにマッチする。
* 単一の文字クラスに'`?`'が続いたもの。そのクラスの文字の0回または1回の出現にマッチする。
* `%*n*`(*n*は1から9)。これは、*n*番目にキャプチャされた文字列にマッチするような要素である (下の説明を参照)。
* `%b*xy*`(*x*と*y*は異なる文字)。これは*x*で始まって*y*で終わる文字列にマッチするような要素である。*x*と*y*は対応が取れる。つまり、文字列を左から右に読んでいって、*x*が現れるたびにカウントを +1 し、*y*では -1 したとき、最後の*y*はカウントが0になる最初の*y*である。例えば、要素`%b()`はカッコの対応が取れた式にマッチする。
* `%f[*set*]`(*境界パターン*)。この項目は、次の文字が*set*に属し前の文字が*set*に属さない場所で、空文字列にマッチします。集合*set*は上で述べたように解釈されます。対象の先頭および末尾では、文字 '\0' が存在するかのように扱われます。
※このパターンはLua5.1ではリファレンスに載っていなかったが、Lu5.2で追加された。ソース解析でこれを見つけた人に感謝。

#### ^Pattern$

*pattern*はパターン要素の列である。

パターンの最初に現れる'`^`'は対象文字列の先頭にマッチを固定する。パターンの最後に現れる'`$`'は対象文字列の最後にマッチを固定する。他の位置では、'`^`'や'`$`'は特別な意味を持たず、それ自身を表す。

#### キャプチャ

パターンは、カッコで囲まれたサブパターンを含むことができ、これをキャプチャと呼びます。パターンが合致したときには、キャプチャに相当する部分文字列は保存され、後で使用することができるようになります。キャプチャの順序は開きカッコの出現順です。たとえば、パターン"`(a*(.)%w(%s*))`,"において、最初のキャプチャは`a*(.)%w(%s*)`に相当する部分文字列であり、2番目のキャプチャは`.`に、3番目のキャプチャは`%s*`に相当する部分文字列となります。

Luaパターンの特殊なケースとして、空っぽのキャプチャ`()`は、その場所の文字列の中での位置をキャプチャします。たとえば、パターン`"()aa()"`を文字列`"flaaap"`に適用した場合、3と5がキャプチャされます。この空っぽのキャプチャは正規表現では使えません。