Help:Lua/string

Lua的string库提供了一系列用于处理字符串的函数。需要注意的是，这些函数都是单字节字符串编码，不能正确地处理Unicode字符，如需对Unicode字符进行操作，请参考mw.ustring库。

在Lua中，第一个字符的索引（index）是1，而不是0。索引可以是负的，表示从字符串最末开始倒数，比如-1表示最后一个字符，-2表示倒数第二个，等等（数组不能这样索引）。

所有的字符串都是不可变值，对字符串的所有修改都会生成新的字符串对象。此外，所有字符串都共用一个元表，该元表具有__index元方法，使得字符串可以面向对象使用，例如string.byte(s, i, j)就可以等价于s:byte(i, j)（其中s必须是字符串）。

byte

用法：string.byte(s, i, j)或s:byte(i, j)，i和j可选

将字符串看作字节的数组，返回s[i]、s[i+1]、···、s[j]的字节值。i的默认值为1；j的默认值为i。这里使用交互式界面做演示：

> string.byte('Rolling Sky', 1, -1)
82      111     108     108     105     110     103     32      83      107     121
> string.byte('滚动的天空', 1, -1)
185     246     182     175     181     196     204     236     191     213

char

用法：string.char(...)

接收零个或更多个整数。返回和长度与参数个数相同的字符串，每个字符的字节值等于其对应的参数。每个整数的值都不能小于0且不能超过255。

print(string.char(0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x21)) --输出Hello!

find

用法：string.find(s, pattern, init, plain)或者s:find(pattern, init, plain)，其中init和plain可选。

在字符串s中，查找正则表达式pattern的第一个匹配（match）。如果找到一个匹配，返回该匹配在s中的起止点所在的索引，否则返回nil。如果正则表达式有捕获（capture），则被捕获的值也会被返回在两个索引之后。

第三个参数init是可选的，指定从哪里开始搜索，默认值是1，可以是负数。

第四个参数plain也是可选的，如果是true，则会关闭正则表达式机制，则函数做的只是简单的“找子串”操作，pattern中的字符就不会被看作正则表达式。

这里用交互式界面作演示：

> string.find('Rolling Sky','Sky')
9       11
> string.find('Rolling Sky','Rolling (.+)')
1       11      Sky
> string.find('Rolling Sky','Minecraft')
nil

format

该段落内容需要扩展。

用法：string.format(s, ...)或s:format(...)

根据指定的格式化字符串s以及对应的参数对字符串进行格式化，返回格式化后的字符串。格式化字符串遵循ISO C函数sprintf的规则。不同点在于部分选项不支持。

参数的数量应当与格式化字符串对应。例如，如果s是"The %s of %s is %s"，则其后应该是3个参数，如果少于或者多于3个，则会抛出错误。

对于需要接受字符串的参数，如果不是字符串，则会将其转化为字符串。对于需要接受数字的参数，如果是字符串，则会尝试将其转化为数字（例如string.format('%o', '114')等价于string.format('%o', 114)），如果无法转换则会抛出错误。

以下为可以使用的字符串格式：

%s

接受一个字符串，并返回它本身。这是最常用的格式。例如：string.format('%s is in %s', 'Weiting', 'Suzhou')会返回Weiting is in Suzhou。对于其他类型的值，会先将其转化为字符串。

%c

接受一个整数，并将其转化为对应的字符。例如，string.format('%c', 117)会返回字符串u。

%o

接受一个整数并将其转化为八进制数格式。对于负数，会将其转化为正数，例如string.format('%o', -114514)返回1777777777777777440256。

%u

接受一个整数并将其转化为无符号整数格式。如果不是整数，则会抛出错误。如果是负数，则会将其转化为正数。例如，string.format('%u', -114514)会返回字符串18446744073709437102。

%x

接受一个数字并将其转化为十六进制数格式（使用小写字母）。对于负数，会将其转化为正数。

%X

和%x类似，不过是使用大写字母。

%e

接受一个数字并将其转化为科学记数法格式，使用小写字母e。例如，string.format('%e', 114514)返回1.145140e+005。

%E

类似于%e，不过是使用大写字母E。

%f

接受一个数字，并将其转化为浮点数格式。

%g

接受一个数字，并将其转化为%e和%f中较短的一种格式。例如，string.format('%g', 114514)返回114514，而string.format('%g', 1919810)则会返回1.91981e+006。

%G

接受一个数字，并将其转化为%E和%f中较短的一种格式。

%q

类似于%s，不过会将字符串用引号包围并进行转义，以将其转化为可安全地被Lua编译器读入的格式。string.format('The value is %q', '含有"引号"、\n换行以及\t制表符的字符串')会返回The value is "含有\"引号\"、\
换行以及\9制表符的字符串"。

Lua的字符串函数不支持像%2$s %1$s这样指定位置。

gmatch

用法：string.gmatch(s, patter)或s:gmatch(pattern)

返回一个迭代器函数，每次调用该迭代器函数时，都会从字符串s中的正则表达式pattern返回下一个捕获。如果pattern不会指定捕获，则每次调用都会产生整个匹配。例如：

for w in string.gmatch("The quick brown fox jumps over the lazy dog", "%w+") do
    print(w)
end

会依次返回：

The
quick
brown
fox
jumps
over
the
lazy
dog

对于这个函数，pattern开头如果有^，则该字符不会用来表示整个字符串的开头（因为这个会避免迭代）。它被看做是普通字符。

gsub

用法：string.gsub(s, pattern, repl, n)或s:gsub(pattern, repl, n)，其中n可选

在字符串s中根据正则表达式pattern进行查找，并将其替换为repl。如果指定了n，则只会替换n次。返回替换后的字符串以及替换次数。

如果repl是字符串，则直接将被匹配的部分替换为该字符串。如果正则表达式指定了捕获，则%1、%2、%3这样的格式可以表示特定序列的捕获，例如%1表示第1个捕获。%0表示整个匹配。%%表示单个%。

例如：

s = "The quick brown fox jumps over the lazy dog."
print(s:gsub("fox", "chicken"))
print(s:gsub("%w+", "[%0]"))
print(s:gsub("(%w+) (%w+)", "%2 %1"))

分别输出：

The quick brown chicken jumps over the lazy dog.        1
[The] [quick] [brown] [fox] [jumps] [over] [the] [lazy] [dog].  9
quick The fox brown over jumps lazy the dog.    4

如果repl是表，则将被匹配的部分作为表的键，替换为对应的值。（如果指定了捕获，则第一个捕获作为键。）例如：

s = "The quick brown fox jumps over the lazy dog."
print(s:gsub("%w+", {fox='chicken', dog='cat'}))

会输出：

The quick brown chicken jumps over the lazy cat.        9

如果repl是函数，调用此函数，并将被匹配的部分替换为函数返回的值。调用函数时，会将所有的捕获作为参数，如果没有指定捕获，则将整个匹配作为参数。例如：

s = "The quick brown fox jumps over the lazy dog."
print(s:gsub("%w+", string.reverse))
print(s:gsub("%w+", string.len))

分别输出：

ehT kciuq nworb xof spmuj revo eht yzal god.    9
3 5 5 3 5 4 3 4 3.      9

在repl是表或者函数的情况下，如果表中对应的值或者函数返回的值是数字，则会转化为字符串。如果是nil或false，则不进行此次转换。如果是true或其他类型的值，则会抛出错误。

len

用法：string.len(s)或s:len()

返回字符串s的字节长度，相当于#s。

lower

用法：string.lower(s)或s:lower()

将字符串的所有ASCII大写字符转为小写后返回。所有其他字符不改变。

match

用法：string.match(s, pattern, init)或s:match(pattern, init)，其中init可选

在字符串s中查找正则表达式pattern对应的匹配。如果找到一个，则match返回捕获，否则返回nil。如果正则表达式pattern不指定捕获，则返回整个字符串。第三个参数init是可选的，用来表示从哪里开始搜索，其默认值为1，可以是负数。

rep

用法：string.rep(s, n)或s:rep(n)

返回将字符串s重复n次后的字符串。例如string.rep('Lua', 3)返回LuaLuaLua。n必须是整数，可以是0或负数（会返回空字符串）。

reverse

用法：string.reverse(s)或s:reverse()

返回字符串s被逆转后的字符串（按字节逆转）。例如，string.reverse 'Rolling Sky'返回ykS gnilloR，string.reverse '滚动的天空'返回湛焯牡龉。

sub

用法：string.sub(s, i, j)或s:sub(s, i, j)，j可选

返回字符串s的从第i个字符到第j个字符的子串（substring）。i和j可以是负的。如果j是nil或未指定，则会一直到字符串末尾。

特别地，调用string.sub(s,1,j)会返回字符串s的长度j的前缀，而string.sub(s, -i)会返回字符串s的长度为i的后缀。

upper

用法：string.upper(s)或s:upper()

将字符串的所有ASCII小写字符转为大写后返回。所有其他字符不改变。