@havonz
2017-05-23T17:41:16.000000Z
字数 25620
阅读 13031
Lua
XXTouch
声明
ret, ... = assert(v[, message])
参数及返回值
- v, message
- 任意类型
- 如果这个值为 nil 或 false,则会调用
error
错误信息为 message- 否则,assert 将返回所有的参数
说明
如果其参数 v 的值为假(nil 或 false), 它就调用
error
; 否则,返回所有的参数。 在错误情况时, message 指那个错误对象; 如果不提供这个参数,参数默认为 "assertion failed!" 。
示例
假设 /var/mobile/Media/1ferver/lua/scripts/test.txt
的内容为:
Hello XXTouch
执行:
local f = assert(io.open("/var/mobile/Media/1ferver/lua/scripts/test.txt", "r"))
sys.toast(f:read("*a"))
f:close()
将输出:
Hello XXTouch
假设 /var/mobile/Media/1ferver/lua/scripts/test.txt
文件不存在将输出:
并抛出一个错误:
...: 1: /var/mobile/Media/1ferver/lua/scripts/test.txt: No such file or directory
声明
collectgarbage([opt[, arg]])
参数及返回值
- opt, arg
- 文本型,通过这个参数提供了一组不同的功能
"collect"
: 做一次完整的垃圾收集循环。 这是默认选项。"stop"
: 停止垃圾收集器的运行。 在调用重启前,收集器只会因显式的调用运行。"restart"
: 重启垃圾收集器的自动运行。"count"
: 以 K 字节数为单位返回 Lua 使用的总内存数。 这个值有小数部分,所以只需要乘上1024
就能得到 Lua 使用的准确字节数(除非溢出)。"step"
: 单步运行垃圾收集器。 步长“大小”由 arg 控制。 传入0
时,收集器步进(不可分割的)一步。 传入非0
值, 收集器收集相当于 Lua 分配这些多(K 字节)内存的工作。 如果收集器结束一个循环将返回true
。"setpause"
: 将 arg 设为收集器的 间歇率。 返回 间歇率 的前一个值。"setstepmul"
: 将 arg 设为收集器的 步进倍率。 返回 步进倍率 的前一个值。"isrunning"
: 返回表示收集器是否在工作的布尔值 (即未被停止)。
说明
这个函数是垃圾收集器的通用接口
示例
collectgarbage("collect")
声明
ret, ... = dofile([filename])
参数及返回值
- filename
文本型,需要执行的文件名- ret, ...
返回该文件中代码块的所有返回值
说明
打开该名字的文件,并执行文件中的 Lua 代码块。 不带参数调用时, dofile 执行标准输入的内容(stdin)。 返回该代码块的所有返回值。 对于有错误的情况,dofile 将错误反馈给调用者 (即,dofile 没有运行在保护模式下)。
示例
假设 /var/mobile/Media/1ferver/lua/scripts/test.lua
的内容为:
return "Hello dofile"
执行:
h = dofile("/var/mobile/Media/1ferver/lua/scripts/test.lua")
print(h)
将输出:
Hello dofile
声明
error(message[, level])
参数及返回值
- message
文本型,错误信息- level
整数型,可选参数,错误抛出的层,默认为1
说明
中止上一次保护函数调用, 将错误对象 message 返回。 函数 error 永远不会返回。
当 message 是一个字符串时,通常 error 会把一些有关出错位置的信息附加在消息的前头。 level 参数指明了怎样获得出错位置。 对于 level 1 (默认值),出错位置指 error 函数调用的位置。 Level 2 将出错位置指向调用 error的函数的函数;以此类推。 传入 level 0 可以避免在消息前添加出错位置信息。
示例
error("呵呵")
将输出:
并抛出一个错误:
...: 1: 呵呵
声明
mt = getmetatable(object)
参数及返回值
- object
对象,类型可以是 table、userdata- mt
表型 |nil
,如果 object 不包含元表,返回nil
,否则返回对象的元表
说明
如果 object 不包含元表,返回 nil 。 否则,如果在该对象的元表中有 "__metatable" 域时返回其关联值, 没有时返回该对象的元表。
示例
mt = getmetatable("") -- 获得字符串的元表
print(mt.__index.sub("XXTouch", 3, 5))
将输出:
Tou
声明
it, t, 0 = ipairs(t)
参数及返回值
- t(参数)
表型,需要迭代的表- it
函数型,返回一个迭代函数- t(返回值)
表型,这个表原封不动返回参数 t0
常量0
(零) 不用多说吧?
说明
返回三个值(迭代函数、表 t 以及 0 ), 如此,以下代码
for i,v in ipairs(t) do ... end
将迭代键值对(1,t[1]) ,(2,t[2]), ... ,直到第一个空值。
示例
for i,v in ipairs({5, 7, 8}) do
print(i, v)
end
将输出:
1 5
2 7
3 8
声明
func, err = load(chunk[, chunkname[, mode[, env]]])
参数及返回值
- chunk
字符串型,需要加载的代码块- chunkname
字符串型,可选参数,代码块的名字,默认为第一个参数 chunk- mode
"b"
只能是二进制代码块模式"t"
只能是文本代码块模式"bt"
可以是二进制也可以是文本模式- env
表型,如果结果函数有上值,env 被设为第一个上值。若不提供此参数,将全局环境替代它。- func, err
函数型 |nil
,如果代码块没有语法错误,则以函数形式返回编译好的代码块;否则,返回nil
加上错误消息
说明
加载一个代码块。
如果 chunk 是一个字符串,代码块指这个字符串。 如果 chunk 是一个函数, load 不断地调用它获取代码块的片断。 每次对 chunk 的调用都必须返回一个字符串紧紧连接在上次调用的返回串之后。 当返回空串、nil、或是不返回值时,都表示代码块结束。
如果没有语法错误, 则以函数形式返回编译好的代码块; 否则,返回 nil 加上错误消息。
如果结果函数有上值, env 被设为第一个上值。 若不提供此参数,将全局环境替代它。 所有其它上值初始化为 nil。 (当你加载主代码块时候,结果函数一定有且仅有一个上值 _ENV )。 然而,如果你加载一个用函数(参见
string.dump
, 结果函数可以有任意数量的上值) 创建出来的二进制代码块时,所有的上值都是新创建出来的。 也就是说它们不会和别的任何函数共享。chunkname 在错误消息和调试消息中,用于代码块的名字。 如果不提供此参数,它默认为字符串chunk 。 chunk 不是字符串时,则为 "=(load)" 。
字符串 mode 用于控制代码块是文本还是二进制(即预编译代码块)。 它可以是字符串 "b" (只能是二进制代码块), "t" (只能是文本代码块), 或 "bt" (可以是二进制也可以是文本)。 默认值为 "bt"。
Lua 不会对二进制代码块做健壮性检查。 恶意构造一个二进制块有可能把解释器弄崩溃。
示例
f = load("print('XXTouch')")
print('Hello')
f()
将输出:
Hello
XXTouch
声明
func, err = loadfile([filename[, mode[, env]]])
参数及返回值
- filename
字符串型,需要加载的代码块所属的文件的文件名- mode
"b"
只能是二进制代码块模式"t"
只能是文本代码块模式"bt"
可以是二进制也可以是文本模式- env
表型,如果结果函数有上值,env 被设为第一个上值。若不提供此参数,将全局环境替代它。- func, err
函数型 |nil
,如果文件中代码块没有语法错误,则以函数形式返回编译好的代码块;否则,返回nil
加上错误消息
说明
和
load
类似, 不过是从文件 filename 或标准输入(如果文件名未提供)中获取代码块。
示例
假设 /var/mobile/Media/1ferver/lua/scripts/test.lua
的内容为:
print('XXTouch')
return "Hello again"
执行:
f = loadfile("/var/mobile/Media/1ferver/lua/scripts/test.lua")
print('Hello')
print(f())
将输出:
Hello
XXTouch
Hello again
声明
idx, value = next(t[, index])
参数及返回值
- t
表型,需要操作的表- index
任意类型,可选参数,当前域的键,默认为nil
- idx, value
任意类型 |nil
,返回 index 键的下一个键 idx 及其关联的值,如果没有下一个键,返回nil
说明
运行程序来遍历表中的所有域。 第一个参数是要遍历的表,第二个参数是表中的某个键。 next 返回该键的下一个键及其关联的值。 如果用 nil 作为第二个参数调用 next 将返回初始键及其关联值。 当以最后一个键去调用,或是以 nil 调用一张空表时, next 返回 nil。 如果不提供第二个参数,将认为它就是 nil。 特别指出,你可以用 next(t) 来判断一张表是否是空的。
索引在遍历过程中的次序无定义, 即使是数字索引也是这样。 (如果想按数字次序遍历表,可以使用数字形式的 for 。)
当在遍历过程中你给表中并不存在的域赋值, next 的行为是未定义的。 然而你可以去修改那些已存在的域。 特别指出,你可以清除一些已存在的域。
示例
local t = {
a = 1,
b = 2,
c = 3,
}
local k, v = nil, nil
for k, v in next, t, k do
print(k, v)
end
可能的输出:
c 3
a 1
b 2
声明
next, idx, value = pairs(t[, index])
参数及返回值
- t
表型,需要遍历的表- next
函数型,t 的 __pairs 元方法或者next
函数- idx, value
任意类型 |nil
,返回 index 键的下一个键 idx 及其关联的值,如果没有下一个键,返回nil
说明
如果 t 有元方法 __pairs, 以 t 为参数调用它,并返回其返回的前三个值。
否则,返回三个值:
next
函数, 表 t,以及 nil。 因此以下代码
for k,v in pairs(t) do body end
能迭代表 t 中的所有键值对。参见函数
next
中关于迭代过程中修改表的风险。
示例
t = {
a = 1,
b = 2,
c = 3,
}
for k, v in pairs(t) do
print(k, v)
end
可能的输出:
c 3
a 1
b 2
声明
noerr, ... = pcall(f[, arg1, ···])
参数及返回值
- f
函数型,需要以保护模式调用的函数- arg1, ...
任意类型,传给 f 的参数们- noerr, ...
布尔型, ...,如果 f 的调用没有发生运行期错误,则返回true
并附带 f 的返回值,否则返回false
附带错误信息
说明
传入参数,以 保护模式 调用函数 f 。 这意味着 f 中的任何错误不会抛出; 取而代之的是,pcall 会将错误捕获到,并返回一个状态码。 第一个返回值是状态码(一个布尔量), 当没有错误时,其为真。 此时,pcall 同样会在状态码后返回所有调用的结果。 在有错误时,pcall 返回
false
加错误消息。
示例
function has_a_err(arg1, arg2)
print(arg1)
arg1 = nil + arg1
print(arg2)
end
print(pcall(has_a_err, "XXT", "Terrible"))
将输出:
XXT
false [string ""]:3: attempt to perform arithmetic on a nil value
声明
print(···)
参数及返回值
- ...
任意类型,接收任意数量的参数
说明
接收任意数量的参数,并将它们的值打印到 stdout。 它用
tostring
函数将每个参数都转换为字符串。 print 不用于做格式化输出。仅作为看一下某个值的快捷方式。 多用于调试。 完整的对输出的控制,请使用 string.format 以及 io.write。
示例
print("Hello XXT")
将输出:
Hello XXT
声明
b = rawequal(v1, v2)
参数及返回值
- v1, v2
任意类型,需要判断是否相等的两个值- b
布尔型,如果 v1 原等于 v2,返回true
,否则返回false
说明
在不触发任何元方法的情况下 检查 v1 是否和 v2 相等。
示例
mt = {
__eq = function(self, v)
return true
end
}
t1 = {}
t2 = {}
setmetatable(t1, mt)
setmetatable(t2, mt)
print(t1==t2)
print(rawequal(t1, t2))
将输出:
true
false
声明
value = rawget(tab, index)
参数及返回值
- tab
表型,一张表- index
任意类型,索引- value
任意类型,索引到的值
说明
在不触发任何元方法的情况下 获取 tab[index] 的值。 tab 必须是一张表; index 可以是任何值。
示例
t = {
a = 3,
b = 7,
}
mt = {
__index = function(self, key)
return "XXTouch "..key
end
}
setmetatable(t, mt)
print(t["c"])
print(t["d"])
print(rawget(t, "c"))
print(rawget(t, "d"))
print(rawget(t, "b"))
print(rawget(t, "a"))
将输出:
XXTouch c
XXTouch d
nil
nil
7
3
声明
len = rawlen(object)
参数及返回值
- object
对象,类型可以是 string、table- len
整数型,返回对象的长度信息
说明
在不触发任何元方法的情况下 返回对象 v 的长度。 v 可以是表或字符串。
示例
t = {1, "XXTouch", 2, 3}
mt = {
__len = function(self)
return 9999999
end
}
setmetatable(t, mt)
print(#t)
print(rawlen(t))
将输出:
9999999
4
声明
rawset(tab, index, value)
参数及返回值
- tab
表型,需要设置值的表- index
任意类型,键,不能是nil
或NaN
- value
任意类型,需要设置的值
说明
在不触发任何元方法的情况下 将 tab[index] 设为 value。 tab 必须是一张表, index 可以是 nil 与 NaN 之外的任何值。 value 可以是任何 Lua 值。
示例
t = {}
mt = {
__newindex = function(self, key, value)
print("XXTouch deny")
end
}
setmetatable(t, mt)
t.a = 1
print(t.a)
rawset(t, "a", 2)
print(t.a)
将输出:
XXTouch deny
nil
2
声明
arg1, ... = select(index, ···)
参数及返回值
- index
整数型 |"#"
,参数索引- arg1, ...
整数型 | 任意类型, ...,如果 index 为"#"
则返回参数个数,否则返回从 index 个参数开始的所有参数
说明
如果 index 是个数字, 那么返回参数中第 index 个之后的部分; 负的数字会从后向前索引(-1 指最后一个参数)。 否则,index 必须是字符串 "#", 此时 select 返回参数的个数。
示例
function var_args(...)
print("有 "..select("#", ...).." 个参数")
print(select(2, ...))
end
var_args("XXTouch", 1, 2, 3, 4)
var_args(1, "XXTouch", 2, 3)
将输出:
有 5 个参数
1 2 3 4
有 4 个参数
XXTouch 2 3
声明
tab = setmetatable(tab, metatable)
参数及返回值
- tab
表型,需要设置元表的表- metatable
表型,元表
说明
给指定表设置元表。 (你不能在 Lua 中改变其它类型值的元表,那些只能在 C 里做。) 如果 metatable 是 nil, 将指定表的元表移除。 如果原来那张元表有 "__metatable" 域,抛出一个错误。
这个函数返回 tab。
示例
mt = {
awesome = function(self)
print("Hello!")
print(self.hello)
end
}
mt.__index = mt
xxt = {}
xxt.hello = "XXTouch Awesome!"
setmetatable(xxt, mt)
xxt:awesome()
将输出:
Hello!
XXTouch Awesome!
声明
n = tonumber(e[, base])
参数及返回值
- e
文本型 | 实数型,需要转换为数字的值- base
整数型,进制- n
实数型 |nil
,转换成功返回数字,否则返回nil
说明
如果调用的时候没有 base, tonumber 尝试把参数转换为一个数字。 如果参数已经是一个数字,或是一个可以转换为数字的字符串, tonumber 就返回这个数字; 否则返回 nil。
字符串的转换结果可能是整数也可能是浮点数, 这取决于 Lua 的转换文法。 (字符串可以有前置和后置的空格,可以带符号。)
当传入 base 调用它时, e 必须是一个以该进制表示的整数字符串。 进制可以是 2 到 36 (包含 2 和 36)之间的任何整数。 大于 10 进制时,字母 'A' (大小写均可)表示 10 , 'B' 表示 11,依次到 'Z' 表示 35 。 如果字符串 e 不是该进制下的合法数字, 函数返回 nil。
示例
print(tonumber("not a number"))
print(tonumber(" 12444 "))
print(tonumber("ff", 16))
将输出:
nil
12444
255
声明
s = tostring(v)
参数及返回值
- v
任意类型,需要转换为字符串的值- s
字符串型,转换后的字符串值
说明
可以接收任何类型,它将其转换为人可阅读的字符串形式。 浮点数总被转换为浮点数的表现形式(小数点形式或是指数形式)。 (如果想完全控制数字如何被转换,可以使用 string.format。)
如果 v 有 "__tostring" 域的元表, tostring 会以 v 为参数调用它。 并用它的结果作为返回值。
示例
print(tostring(nil))
print(tostring(true))
print(tostring(1*1.0))
将输出:
nil
true
1.0
声明
y = type(v)
参数及返回值
- v
任意类型,需要转换为字符串的值- y
"nil"
: 表示值为nil
"number"
: 表示值为数字型
"string"
: 表示值为字符串型
"boolean"
: 表示值为布尔型
"table"
: 表示值为表型
"function"
: 表示值为函数型
"thread"
: 表示值为 thread 型
"userdata"
: 表示值为 userdata 型
说明
将参数的类型编码为一个字符串返回
示例
print(type(nil))
print(type(true))
print(type(1*1.0))
将输出:
nil
boolean
number
声明
noerr = xpcall(f, msgh[, arg1, ···])
参数及返回值
- f
函数型,需要以保护模式调用的函数- msgh
函数型,错误回调函数,当函数 f 调用发生错误的时候错误信息会当作第一个参数调用这个函数- arg1, ...
任意类型,传给 f 的参数们- noerr
布尔型,如果 f 的调用没有发生运行期错误,则返回true
并附带 f 的返回值,否则返回false
说明
这个函数和
pcall
类似。 不过它可以额外设置一个消息处理器 msgh。
示例
function has_a_err(arg1, arg2)
print(arg1)
arg1 = nil + arg1
print(arg2)
end
function msgh(err)
print(err)
end
print(xpcall(has_a_err, msgh, "XXT", "Terrible"))
将输出:
XXT
[string ""]:3: attempt to perform arithmetic on a nil value
false nil
声明
co = coroutine.create(f)
参数及返回值
- f
函数型,一个函数- co
协程型,创建的协程
说明
创建一个主体函数为 f 的新协程。 f 必须是一个 Lua 的函数。 返回这个新协程,它是一个类型为 "thread" 的对象。
示例
将输出:
声明
ret, ... = require(modname)
参数及返回值
- modname
文本型,模块名- ret, ...
任意类型,返回模块返回值
说明
require 调用返回之前,不允许让出
加载一个模块。 这个函数首先查找 package.loaded 表, 检测 modname 是否被加载过。 如果被加载过,require 返回 package.loaded[modname] 中保存的值。 否则,它试着为模块寻找 加载器 。
require 遵循 package.searchers 序列的指引来查找加载器。 如果改变这个序列,我们可以改变 require 如何查找一个模块。 下列说明基于 package.searchers 的默认配置。
首先 require 查找 package.preload[modname] 。 如果这里有一个值,这个值(必须是一个函数)就是那个加载器。 否则 require 使用 Lua 加载器去查找 package.path 的路径。 如果查找失败,接着使用 C 加载器去查找 package.cpath 的路径。 如果都失败了,再尝试 一体化 加载器 (参见 package.searchers)。
每次找到一个加载器,require 都用两个参数调用加载器: modname 和一个在获取加载器过程中得到的参数。 (如果通过查找文件得到的加载器,这个额外参数是文件名。) 如果加载器返回非空值, require 将这个值赋给 package.loaded[modname]。 如果加载器没能返回一个非空值用于赋给 package.loaded[modname], require 会在那里设入 true 。 无论是什么情况,require 都会返回 package.loaded[modname] 的最终值。
如果在加载或运行模块时有错误, 或是无法为模块找到加载器, require 都会抛出错误。
示例
假设 /var/mobile/Media/1ferver/lua/scripts/test.lua
的内容为:
print('XXTouch')
return "Hello again"
执行:
package.path = package.path..";/var/mobile/Media/1ferver/lua/scripts/"
print(require("test"))
print(require("test"))
将输出:
XXTouch
Hello again
Hello again
声明
func = package.loadlib(libname, funcname)
参数及返回值
- libname
文本型,C 库的绝对路径- funcname
文本型,C 函数名- func
函数型,返回一个可以调用的函数
说明
让宿主程序动态链接 C 库 libname 。
当 funcname 为 "*", 它仅仅连接该库,让库中的符号都导出给其它动态链接库使用。 否则,它查找库中的函数 funcname ,以 C 函数的形式返回这个函数。 因此,funcname 必须遵循原型 lua_CFunction 。
这是一个低阶函数。 它完全绕过了包模块系统。 和 require 不同, 它不会做任何路径查询,也不会自动加扩展名。 libname 必须是一个 C 库需要的完整的文件名,如果有必要,需要提供路径和扩展名。 funcname 必须是 C 库需要的准确名字 (这取决于使用的 C 编译器和链接器)。
这个函数在标准 C 中不支持。 因此,它只在部分平台有效 ( Windows ,Linux ,Mac OS X, Solaris, BSD, 加上支持 dlfcn 标准的 Unix 系统)。
示例
local cjson_func = package.loadlib("/var/mobile/Media/1ferver/lib/cjson.so","luaopen_cjson")
local cjson = cjson_func()
将输出:
声明
fullpath, err = package.searchpath(name, path[, sep[, rep]])
参数及返回值
- name
文本型,需要搜索的模块名- path
文本型,搜索路径- sep
文本型,可选参数,默认是"."
- rep
文本型,可选参数,默认是系统的目录分割符(Windows 下是"\\"
,*nix 系统是"/"
)- fullpath, err
文本型,如果搜索到指定模块,则 fullpath 返回模块文件名,否则 fullpath 返回nil
并附带错误信息 err
说明
在指定 path 中搜索指定的 name 。
路径是一个包含有一系列以分号分割的 模板 构成的字符串。 对于每个模板,都会用 name 替换其中的每个问号(如果有的话)。 且将其中的 sep (默认是点)替换为 rep (默认是系统的目录分割符)。 然后尝试打开这个文件名。
例如,如果路径是字符串
"./?.lua;./?.lc;/usr/local/?/init.lua"
搜索 foo.a 这个名字将 依次尝试打开文件 ./foo/a.lua, ./foo/a.lc ,以及 /usr/local/foo/a/init.lua。
返回第一个可以用读模式打开(并马上关闭该文件)的文件的名字。 如果不存在这样的文件,返回 nil 加上错误消息。 (这条错误消息列出了所有尝试打开的文件名。)
示例
print(package.searchpath("dm", "/var/mobile/Media/1ferver/lua/?.lua"))
如果 /var/mobile/Media/1ferver/lua/dm.lua
文件存在,将输出:
/var/mobile/Media/1ferver/lua/dm.lua
如果 /var/mobile/Media/1ferver/lua/dm.lua
文件不存在,将输出:
nil
no file '/var/mobile/Media/1ferver/lua/dm.lua'
这个库提供了字符串处理的通用函数。 例如字符串查找、子串、模式匹配等。 当在 Lua 中对字符串做索引时,第一个字符从 1
开始计算(而不是 C 里的 0
)。 索引可以是负数,它指从字符串末尾反向解析。 即,最后一个字符在 -1
位置处,等等。
字符串库中的所有函数都在表 string 中。 它还将其设置为字符串元表的 __index 域。 因此,你可以以面向对象的形式使用字符串函数。 例如,string.byte(s,i) 可以写成 s:byte(i)。
字符串库假定采用单字节字符编码。
声明
... = string.byte(s[, i[, j]])
参数及返回值
- s
字符串型,字符串本体- i, j
整数型,可选参数,i 为需要操作的字符串索引起始位置,j 为需要操作的字符串索引终止位置,默认都为1
- ...
整数型,返回一个或多个数字(i 到 j 有多少个字节就返回多少个)
说明
返回字符 s[i], s[i+1], ... ,s[j] 的内部数字编码。 i 的默认值是 1 ; j 的默认值是 i。 这些索引以函数
string.sub
的规则修正。
数字编码没有必要跨平台。
示例
以下例子的编码为 UTF-8
s = "XXTouch"
print(string.byte(s))
print(string.byte(s, 1, -1))
print(s:byte())
print(s:byte(1, -1))
将输出:
88
88 88 84 111 117 99 104
88
88 88 84 111 117 99 104
声明
s = string.char(···)
参数及返回值
- ...
整数型,需要转换成字符串的数字编码,可以有多个参数- s
字符串型,返回转换后的字符串
说明
接收零或更多的整数。 返回和参数数量相同长度的字符串。 其中每个字符的内部编码值等于对应的参数值。
数字编码没有必要跨平台。
示例
以下例子的编码为 UTF-8
print(string.char(88, 88, 84, 111, 117, 99, 104))
将输出:
XXTouch
声明
s = string.dump(func[, strip])
参数及返回值
- func
函数型,需要序列化的函数- strip
布尔型,如果 strip 为真值, 二进制代码块不携带该函数的调试信息 (局部变量名,行号,等等。)- s
字符串型,返回包含有以二进制方式表示的(一个 二进制代码块 )指定函数的字符串
说明
返回包含有以二进制方式表示的(一个 二进制代码块 )指定函数的字符串。 之后可以用
load
调用这个字符串获得 该函数的副本(但是绑定新的上值)。 如果 strip 为真值, 二进制代码块不携带该函数的调试信息 (局部变量名,行号,等等。)。带上值的函数只保存上值的数目。 当(再次)加载时,这些上值被更新为 nil 的实例。 (你可以使用调试库按你需要的方式来序列化上值,并重载到函数中)
示例
function hello()
print('Hello XXTouch')
end
s = string.dump(hello)
f = load(s)
f()
将输出:
Hello XXTouch
声明
sp, ep = string.find(s, pattern[, init[, plain]])
参数及返回值
- s
字符串型,在这个字符串中查找- pattern
字符串型,用于描述一个匹配模式,或需要查找的字符串- init
整数型,可选参数,查找在字符串 s 的开始位置,默认为1
- plain
布尔型,可选参数,关闭模式匹配机制,默认为false
- sp, ep
整数型 |nil
,如果查找成功,则 sp 为找到的串在 s 中的起始位置,ep 为结束位置;否则返回nil
说明
查找第一个字符串 s 中匹配到的 pattern。 如果找到一个匹配,find 会返回 s 中关于它起始及终点位置的索引; 否则,返回 nil。 第三个可选数字参数 init 指明从哪里开始搜索; 默认值为 1 ,同时可以是负值。 第四个可选参数 plain 为 true 时, 关闭模式匹配机制。 此时函数仅做直接的 “查找子串”的操作, 而 pattern 中没有字符被看作魔法字符。 注意,如果给定了 plain,就必须写上 init 。
示例
s = "XXTouch."
print(string.find(s, "Tou"))
print(string.find(s, "."))
print(string.find(s, ".", 1, true))
print(string.find(s, "%."))
将输出:
3 5
1 1
8 8
8 8
声明
s = string.format(fmt, ···)
参数及返回值
- fmt
字符串型,格式化模式- ...
任意类型,将会被填充到 fmt 中的值- s
字符串型,返回格式化后的字符串
说明
返回不定数量参数的格式化版本, 格式化串为第一个参数(必须是一个字符串)。 格式化字符串遵循 ISO C 函数 sprintf 的规则。 不同点在于选项 *, h, L, l, n, p 不支持, 另外还增加了一个选项 q。 q 选项将一个字符串格式化为两个双引号括起,对内部字符做恰当的转义处理的字符串。 该字符串可以安全的被 Lua 解释器读回来。 例如,调用
string.format('%q', 'a string with "quotes" and \n new line')
会产生字符串:
"a string with \"quotes\" and \
new line"
选项 A and a (如果有的话), E, e, f, G, and g 都期待一个对应的数字参数。 选项 c, d, i, o, u, X, and x 则期待一个整数。 选项 q 期待一个字符串; 选项 s 期待一个没有内嵌零的字符串。 如果选项 s 对应的参数不是字符串,它会用和
tostring
一致的规则转换成字符串。
示例
print(string.format("%d + %d = %d", 100, 200, 100+200))
print(string.format("%f * %f = %f", 100, 200, 100*200))
print(string.format("%x + %x = %x", 100, 200, 100+200))
将输出:
100 + 200 = 300
100.000000 * 200.000000 = 20000.000000
64 + c8 = 12c
声明
it = string.gmatch(s, pattern)
参数及返回值
- s
字符串型,需要迭代匹配的源字符串- pattern
字符串型,匹配的模式(参见匹配模式
)- it
函数型,一个迭代器函数,每次调用都会返回 s 中下一个 pattern 匹配的所有值,如果没有下一个匹配则调用返回 nil
说明
返回一个迭代器函数。 每次调用这个函数都会继续以 pattern(参见
匹配模式
) 对 s 做匹配,并返回所有捕获到的值。 如果 pattern 中没有指定捕获,则每次捕获整个 pattern。
下面这个例子会循环迭代字符串 s 中所有的单词, 并逐行打印:
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
对这个函数来说,模板前开始的 '^' 不会当成锚点。因为这样会阻止迭代。
示例1
for k,v in string.gmatch("k=XXTouch,v=awesome#k=Soze,v=a goodman#", "k=(.-),v=(.-)#") do
print(k, "is", v)
end
将输出:
XXTouch is awesome
Soze is a goodman
示例2
local it = string.gmatch("k=XXTouch,v=Awesome#k=Soze,v=a Goodman#", "k=(.-),v=(.-)#")
while (true) do
local k, v = it()
if (k) then
print(k, v)
else
break
end
end
将输出:
XXTouch Awesome
Soze a Goodman
声明
ts, count = string.gsub(s, pattern, repl[, n])
参数及返回值
- s
字符串型,需要迭代替换的源字符串- pattern
字符串型,匹配的模式(参见匹配模式
)- ts, count
字符串型, 整数型,ts 为替换后的字符串,count 是当前调用替换匹配发生的次数
说明
将字符串 s 中,所有的(或是在 n 给出时的前 n 个) pattern(参见
匹配模式
) 都替换成 repl ,并返回其副本。 repl 可以是字符串、表、或函数。 gsub 还会在第二个返回值返回一共发生了多少次匹配。 gsub 这个名字来源于 Global SUBstitution 。
如果 repl 是一个字符串,那么把这个字符串作为替换品。 字符 % 是一个转义符: repl 中的所有形式为 %d 的串表示 第 d 个捕获到的子串,d 可以是 1 到 9 。 串 %0 表示整个匹配。 串 %% 表示单个 %。如果 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.3"}
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
--> x="lua-5.3.tar.gz"
示例
print(string.gsub("k=XXTouch,v=Awesome#k=Soze,v=a Goodman#", "k=(.-),v=(.-)#", "%1 %2\n"))
将输出:
XXTouch Awesome
Soze a Goodman
2
声明
l = string.len(s)
参数及返回值
- s
字符串型,一个字符串- l
整数型,返回字符串的长度
说明
接收一个字符串,返回其长度。 空串 "" 的长度为 0 。 内嵌零也统计在内,因此 "a\000bc\000" 的长度为 5 。
示例
print(string.len("XXTouch"))
将输出:
7
声明
ls = string.lower(s)
参数及返回值
- s
字符串型,源字符串- ls
字符串型,转换成小写的字符串
说明
接收一个字符串,将其中的大写字符都转为小写后返回其副本。 其它的字符串不会更改。 对大写字符的定义取决于当前的区域设置。
示例
print(string.lower("XXTouch"))
将输出:
xxtouch
声明
us = string.upper(s)
参数及返回值
- s
字符串型,源字符串- us
字符串型,转换成大写的字符串
说明
接收一个字符串,将其中的小写字符都转为大写后返回其副本。 其它的字符串不会更改。 对小写字符的定义取决于当前的区域设置。
示例
print(string.lower("XXTouch"))
将输出:
XXTOUCH
声明
ms = string.match(s, pattern[, init])
参数及返回值
- s
字符串型,源字符串- pattern
字符串型,模式串(参见匹配模式
)- init
整数型,可选参数,匹配于字符串 s 中的开始位置,默认为1
- ms
字符串型 |nil
,以模式 pattern 在 s 中匹配到的串,没有匹配到则返回nil
说明
在字符串 s 中找到第一个能用 pattern(参见
匹配模式
) 匹配到的部分。 如果能找到,match 返回其中的捕获物; 否则返回 nil 。 如果 pattern 中未指定捕获, 返回整个 pattern 捕获到的串。 第三个可选数字参数 init 指明从哪里开始搜索; 它默认为 1 且可以是负数。
示例
print(string.match("XXTouch", "%d"))
print(string.match("XXT0uch", "%d"))
将输出:
nil
0
声明
ss = string.sub(s, i[, j])
参数及返回值
- s
字符串型,源字符串- i
整数型,需要取出的子字符串在字符串 s 的起始位置- j
整数型,可选参数,需要取出的子字符串在字符串 s 的终止位置,默认为-1
- ss
字符串型,从 s 中取出的子字符串
说明
返回 s 的子串, 该子串从 i 开始到 j 为止; i 和 j 都可以为负数。 如果不给出 j ,就当它是 -1 (和字符串长度相同)。 特别是, 调用 string.sub(s,1,j) 可以返回 s 的长度为 j 的前缀串, 而 string.sub(s, -i) 返回长度为 i 的后缀串。
如果在对负数索引转义后 i 小于 1 的话,就修正回 1 。 如果 j 比字符串的长度还大,就修正为字符串长度。 如果在修正之后,i 大于 j, 函数返回空串。
示例
print(string.sub("XXTouch", 3))
print(string.sub("XXT0uch", 3, 5))
将输出:
Touch
T0u
声明
rs = string.rep(s, n[, sep])
参数及返回值
- s
字符串型,源字符串- n
整数型,需要重复的次数- sep
字符串型,可选参数,连接每个 s 的分隔符,默认为""
- rs
字符串型,构造出的字符串
说明
返回 n 个字符串 s 以字符串 sep 为分割符连在一起的字符串。 默认的 sep 值为空字符串(即没有分割符)。 如果 n 不是正数则返回空串。
示例
print(string.rep("XXTouch", 3))
print(string.rep("XXTouch", 4, ","))
将输出:
XXTouchXXTouchXXTouch
XXTouch,XXTouch,XXTouch,XXTouch
声明
rs = string.reverse(s)
参数及返回值
- s
字符串型,源字符串- rs
字符串型,翻转后的字符串
说明
返回字符串 s 的翻转串。
示例
print(string.reverse("XXTouch"))
将输出:
hcuoTXX
声明
ps = string.pack(fmt, v1, v2, ···)
参数及返回值
- fmt
字符串型,打包的格式模式(参见打包和解包用到的格式串
)- v1, v2, ...
任意类型,需要格式化打包的值- ps
字符串型,返回打包好可以用于传输的二进制串
说明
返回一个打包了(即以二进制形式序列化) v1, v2 等值的二进制字符串。 字符串 fmt 为打包格式(参见
打包和解包用到的格式串
)。
示例
--
声明
..., epos = string.unpack(fmt, s[, pos])
参数及返回值
- fmt
字符串型,需要解包字符串的打包的格式模式(参见打包和解包用到的格式串
)- s
字符串型,需要解包的二进制串- pos
整数型,本次解包从 s 中开始的位置- ...
任意类型,返回解包出来的数据们- epos
整数型,返回本次解包完毕终止于 s 中的位置
说明
返回以格式 fmt(参见
打包和解包用到的格式串
) 打包在字符串 s (参见string.pack
) 中的值。 选项 pos(默认为 1 )标记了从 s 中哪里开始读起。 读完所有的值后,函数返回 s 中第一个未读字节的位置。
示例
--
声明
size = string.packsize(fmt)
参数及返回值
- fmt
字符串型,打包的格式模式(参见打包和解包用到的格式串
)- size
整数型,返回这个格式化模式打包的数据的尺寸(单位:字节)
说明
返回以指定格式用
string.pack
打包的字符串的长度。 格式化字符串中不可以有变长选项 's' 或 'z' 。
示例
--
Lua 中的匹配模式直接用常规的字符串来描述。 它用于模式匹配函数 string.find
, string.gmatch
, string.gsub
, string.match
。 这一节表述了这些字符串的语法及含义(即它能匹配到什么)。
字符类
字符类 用于表示一个字符集合。 下列组合可用于字符类:
所有单个字母表示的类别(%a,%c,等), 若将其字母改为大写,均表示对应的补集。 例如,%S 表示所有非空格的字符。
如何定义字母、空格、或是其他字符组取决于当前的区域设置。 特别注意:[a-z] 未必等价于 %l 。
模式条目
模式条目 可以是
单个字符类匹配该类别中任意单个字符;
单个字符类跟一个 '*', 将匹配零或多个该类的字符。 这个条目总是匹配尽可能长的串;
单个字符类跟一个 '+', 将匹配一或更多个该类的字符。 这个条目总是匹配尽可能长的串;
单个字符类跟一个 '-', 将匹配零或更多个该类的字符。 和 '*' 不同, 这个条目总是匹配尽可能短的串;
单个字符类跟一个 '?', 将匹配零或一个该类的字符。 只要有可能,它会匹配一个;
%n, 这里的 n 可以从 1 到 9; 这个条目匹配一个等于 n 号捕获物(后面有描述)的子串。
%bxy, 这里的 x 和 y 是两个明确的字符; 这个条目匹配以 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 ); 由 "." 匹配到的字符是 2 号捕获物, 匹配到 "%s*" 的那部分是 3 号。
作为一个特例,空的捕获 () 将捕获到当前字符串的位置(它是一个数字)。 例如,如果将模式 "()aa()" 作用到字符串 "flaaap" 上,将产生两个捕获物: 3 和 5 。
用于 string.pack
, string.packsize
, string.unpack
的第一个参数。 它是一个描述了需要创建或读取的结构之布局。
格式串是由转换选项构成的序列。
( "[n]" 表示一个可选的整数。) 除填充、空格、配置项(选项 "xX <=>!")外, 每个选项都关联一个参数(对于 string.pack
) 或结果(对于 string.unpack
)。
对于选项 "!n", "sn", "in", "In", n 可以是 1 到 16 间的整数。 所有的整数选项都将做溢出检查; string.pack
检查提供的值是否能用指定的字长表示; string.unpack
检查读出的值能否置入 Lua 整数中。
任何格式串都假设有一个 "!1=" 前缀, 即最大对齐为 1 (无对齐)且采用本地大小端设置。
对齐行为按如下规则工作: 对每个选项,格式化时都会填充一些字节直到数据从一个特定偏移处开始, 这个位置是该选项的大小和最大对齐数中较小的那个数的倍数; 这个较小值必须是 2 个整数次方。 选项 "c" 及 "z" 不做对齐处理; 选项 "s" 对对齐遵循其开头的整数。
string.pack
用零去填充 (string.unpack
则忽略它)。
这个库提供了表处理的通用函数。 所有函数都放在表 table 中。
记住,无论何时,若一个操作需要取表的长度, 这张表必须是一个真序列(顺序表),或是拥有 __len 元方法。 所有的函数都忽略传入参数的那张表中的非数字键。
声明
s = table.concat (list[, sep[, i[, j]]])
参数及返回值
- list
顺序表型,需要拼接成字符串的源表- sep
字符串型,字符串连接符- i
整数型,可选参数,需要拼接的项在表 list 中的起始索引,默认1
- j
整数型,可选参数,需要拼接的项在表 list 中的终止索引,默认 #list- s
字符串型,返回拼接好的字符串
说明
提供一个列表,其所有元素都是字符串或数字,返回字符串 list[i]..sep..list[i+1] ··· sep..list[j]。 sep 的默认值是空串, i 的默认值是 1 , j 的默认值是 #list 。 如果 i 比 j 大,返回空串。
示例
t = {
"I", "will", "do", "whatever", "it",
"takes", "to", "serve", "my", "country",
"even", "at", "the", "cost", "of", "my",
"own", "life",
}
print(table.concat(t, " "))
将输出:
I will do whatever it takes to serve my country even at the cost of my own life
声明
s = table.insert(list, [pos,] value)
参数及返回值
- list
顺序表型,需要插入值的源表- pos
整数型,可选参数,需要插入值到表 list 中的位置,默认 #list+1 (表最后项之后)- value
任意类型,需要插入到 pos 位置之前的值
说明
在 list 的位置 pos 处插入元素 value , 并后移元素 list[pos], list[pos+1], ···, list[#list] 。 pos 的默认值为 #list+1 , 因此调用 table.insert(t,x) 会将 x 插在列表 t 的末尾。
示例
t = {
"will", "do",
}
table.insert(t, "whatever")
table.insert(t, 1, "I")
print(table.concat(t, " "))
将输出:
I will do whatever
声明
a3 = table.move(a1, f, e, t [,a2])
参数及返回值
- a1
顺序表型,数据源表- f
整数型,数据源表 a1 中的起始索引- e
整数型,数据源表 a1 中的终止索引- t
整数型,目标表 a2 中的起始索引- a2
顺序表型,可选参数,目标表,默认为 a1- a3
顺序表型,如果有 a2 参数,则返回 a2,否则返回 a1
说明
将元素从表 a1 移到表 a2。 这个函数做了次等价于后面这个多重赋值的等价操作: a2[t],··· = a1[f],···,a1[e]。 a2 的默认值为 a1。 目标区间可以和源区间重叠。 索引 f 必须是正数。
示例
t = {
7, 2, 8
}
table.move(t, 1, #t, 2)
for i,v in ipairs(t) do
print(i, v)
end
将输出:
1 7
2 7
3 2
4 8
声明
item = table.remove(list[, pos])
参数及返回值
- list
顺序表型,数据源表- pos
整数型,需要删除的项在表 list 中的索引- item
任意类型,返回被从表中移除的项
说明
移除 list 中 pos 位置上的元素,并返回这个被移除的值。 当 pos 是在 1 到 #list 之间的整数时, 它向前移动元素 list[pos+1], list[pos+2], ···, list[#list] 并删除元素 list[#list]; 索引 pos 可以是 #list + 1 ,或在 #list 为 0 时可以是 0 ; 在这些情况下,函数删除元素 list[pos]。
示例
t = {
7, 2, 8, 3
}
print(table.remove(t, 3))
print(table.remove(t))
print(table.remove(t))
print(table.remove(t))
print(table.remove(t))
将输出:
8
3
2
7
nil
声明
table.sort(list[, comp])
参数及返回值
- list
顺序表型,数据源表- comp
函数型,可选参数,比较函数,默认将使用标准 Lua 操作 < 作为替代品
说明
在表内从 list[1] 到 list[#list] 原地 对其间元素按指定次序排序。 如果提供了 comp , 它必须是一个可以接收两个列表内元素为参数的函数。 当第一个元素需要排在第二个元素之前时,返回真 (因此 not comp(list[i+1],list[i]) 在排序结束后将为真)。 如果没有提供 comp, 将使用标准 Lua 操作 < 作为替代品。
如果 not comp(a, b) 结果与 comp(a, b) 可能一样,那么排序将无法完成,应当避免写出这种排序函数
示例
t = {
7, 4, 3, 1, 3, 9, 3, 6
}
table.sort(t)
print(table.concat(t, ", "))
table.sort(t, function(a, b)
return a > b
end)
print(table.concat(t, ", "))
-- 以下为不严谨的排序函数,在当前示例中将会抛出错误
-- 但是它在很多情况下都会正常运行,注意避免写出这样的排序函数
table.sort(t, function(a, b)
return a >= b
end)
print(table.concat(t, ", "))
将输出:
1, 3, 3, 3, 4, 6, 7, 9
9, 7, 6, 4, 3, 3, 3, 1
并抛出错误:
...: 15: invalid order function for sorting
声明
... = table.unpack (list[, i [, j]])
参数及返回值
- list
顺序表型,数据源表- i
整数型,可选参数,需要解包的项集合在表 list 的起始位置,默认1
- j
整数型,可选参数,需要解包的项集合在表 list 的终止位置,默认 #list- ...
任意类型,可选参数,比较函数,默认将使用标准 Lua 操作 < 作为替代品
说明
返回顺序表中的元素。这个函数等价于
return list[i], list[i+1], ···, list[j]
i 默认为 1 ,j 默认为 #list。
示例
t = {
7, 4, 3, 1, 3, 9, 3, 6
}
print(table.unpack(t))
print(table.unpack(t, 3, 7))
将输出:
7 4 3 1 3 9 3 6
3 1 3 9 3
这个库提供了基本的数学函数。 所以函数都放在表 math 中。 注解有 "integer/float" 的函数会对整数参数返回整数结果, 对浮点(或混合)参数返回浮点结果。 圆整函数(math.ceil, math.floor, math.modf) 在结果在整数范围内时返回整数,否则返回浮点数。
声明
y = math.abs(x)
参数及返回值
- x
实数型,源数字- y
实数型,返回源数字 x 的绝对值
说明
返回 x 的绝对值。(integer/float)
示例
print(math.abs(100))
print(math.abs(-100))
print(math.abs(-100.99))
将输出:
100
100
100.99
声明
y = math.acos(x)
参数及返回值
- x
实数型,源数字- y
实数型,返回源数字 x 的反余弦值
说明
返回 x 的反余弦值(用弧度表示)。
示例
print(math.acos(0.5))
将输出:
1.0471975511966
声明
y = math.asin(x)
参数及返回值
- x
实数型,源数字- y
实数型,返回源数字 x 的反正弦值
说明
返回 x 的反正弦值(用弧度表示)。
示例
print(math.asin(0.5))
将输出:
0.5235987755983
声明
z = math.atan(y[, x])
参数及返回值
- y, x
实数型,源数字,x 为可选参数,默认1
- z
实数型,返回 y/x 的反正切值(用弧度表示)
说明
返回 y/x 的反正切值(用弧度表示)。 它会使用两个参数的符号来找到结果落在哪个象限中。(即使 x 为零时,也可以正确的处理。)
默认的 x 是 1 , 因此调用 math.atan(y) 将返回 y 的反正切值。
示例
print(math.atan(0.5))
print(math.atan(0.5, 0.7))
将输出:
0.46364760900081
0.62024948598282
声明
y = math.ceil(x)
参数及返回值
- x
实数型,源数字- y
整数型,返回不小于 x 的最小整数值
说明
返回不小于 x 的最小整数值。
示例
print(math.ceil(0.5))
print(math.ceil(1))
将输出:
1
1
声明
y = math.cos(x)
参数及返回值
- x
实数型,源数字- y
实数型,返回 x 的余弦(假定参数是弧度)
说明
返回 x 的余弦(假定参数是弧度)。
示例
print(math.cos(0.5))
将输出:
0.87758256189037
声明
y = math.deg(x)
参数及返回值
- x
实数型,源数字- y
实数型,返回弧度 x 对应的角度
说明
将角 x 从弧度转换为角度。
示例
print(math.deg(3.1415926535))
print(math.deg(math.pi))
将输出:
179.99999999486
180.0
声明
y = math.floor(x)
参数及返回值
- x
实数型,源数字- y
整数型,返回不大于 x 的最大整数值
说明
返回不大于 x 的最大整数值。
示例
print(math.ceil(0.5))
print(math.ceil(1))
将输出:
0
1