(接上篇)
--------------------------------------
6 标准库
--------------------------------------
标准库提供了一些有用的函数,这些函数直接由标准 API 实现。因此,它们并非语言必需的部分,并且作为单独的 C 模块被提供。目前,Lua 有以下标准库:
> 基本库;
> 字符串处理;
> 数学函数(sin, log, 等)
> 输入输出(和一些系统功能)
为了能使用这些库,宿主程序必须调用函数 lua_baselibopen, lua_strlibopen, lua_mathlibopen, 和 lua_iolibopen, 这几个都在 lualib.h 中声明。
-------------------
6.1 基本库
-------------------
基本库提供了一些核心功能。因此,如果在你的应该程序中不包含这些库的话,你应该小心地检查你是否需要为一些功能提供一些替代的实现。(例如,没有函数 _ERRORMESSAGE,Lua 就不能显示错误信息。)
_ALERT (message)
在标准错误输出 stderr 上打印它唯一的字符串参数。所有的 Lua 中的错误信息由保存于全局变量(参见 4.7 节)_ALERT 中的函数打印。因此,一个程序可以给这个变量赋另一个函数来改变这样的信息的显示方式(例如,对于没有 stderr 的系统)。
assert (v [, message])
产生一个 ``assertion failed!‘‘ 错误当它的参数 v 是 nil 时。这个函数和下面的 Lua 函数等价:
function assert (v, m) if not v then m = m or "" error("assertion failed! " .. m) end end
call (func, arg [, mode [, errhandler]])
使用由表 arg 给定的参数调用函数 func 。这个调用和下面的等价
func(arg[1], arg[2], ..., arg[n])
这里 n 是 getn(arg) 的结果(参见 6.1 节)。所有的 func 的结果简单的由 call 返回。
默认情况下,在一个错误产生于调用 func 时,这个错误会被传播出去。如果字符串 mode 包含 "x",那么这个调用就是受保护的。在这种模式下,函数 call 不会传播错误,不管调用期间发生了什么。反而,它返回 nil 来标志错误(而且调用适当的错误处理)。
如果 errhandler 提供了,错误函数 _ERRORMESSAGE 临时设置给 errhandler ,当 func 执行时。特别地,如果 errhandler 为 nil,在执行被调用函数期间不会有错误信息被分发。
collectgarbage ([limit])
设置垃圾收集的临界值为给定的 limit(单位为千字节),并对比检查它和字节计数器。如果新的临界值比字节计数器小,那么 Lua 会立刻执行垃圾回收(参见 5.6 节)。如果省略 limit ,它的默认为 0 (因此强制执行一次垃圾回收)。
copytagmethods (tagto, tagfrom)
拷贝所有的标签方法从一个标签到另一个,返回 tagto。
dofile (filename)
接受一个文件名字,打开命名文件,并执行它的内容做为一个 Lua 块,或者做为预编译的块。当无参调用它时,它执行标准输入(stdin)的内容。如果执行文件时出现了任何错误,dofile 返回 nil。否则,它返回块返回的结果,或者一个非 nil 值如果块没有返回值。它会产生一个错误如果用一个非字符串参数调用它。
dostring (string [, chunkname])
执行一个给定的字符串做为一个 Lua 块。如果执行字符串时出现了任何错误,dostring 返回 nil。否则,它返回块返回的结果,或者一个非 nil 值如果块没有返回值。可选的参数 chunkname 是 ``name of the chunk‘‘,被用在错误信息和调试信息中。
error (message)
调用错误处理(参见 4.7 节)并且终止最后一个受保护函数的调用(在 C 里是:lua_dofile, lua_dostring, lua_dobuffer, 或者 lua_callfunction; 在 Lua 里是:dofile, dostring, 或者 call 在保护模式里)。如果 message 是 nil,错误处理不会被调用。函数 error 从不返回。
foreach (table, func)
在表的所有元素上执行给定的 func。对于每一个元素,函数以参数 index 和 value 做为参数被调用。如果函数返回非 nil 的值,那么循环退出,这个值就就作为 foreach 最终的结果。这个函数可以被定义为 Lua:
function foreach (t, f) for i, v in t do local res = f(i, v) if res then return res end end end
foreach 的行为是未定义的如果你在遍历过程中改变了表 t 。
foreachi (table, func)
在表的所有数值索引上执行给定的 func。对于每一个索引,函数以参数 index 和 value 做为参数被调用。索引按顺序被访问,从 1 到 n,这里 n 是 getn(table) 的结果(参见 6.1 节)。如果函数返回非 nil 的值,那么循环退出,这个值就就作为 foreachi 最终的结果。这个函数可以被定义为 Lua:
function foreachi (t, f) for i=1,getn(t) do local res = f(i, t[i]) if res then return res end end end
getglobal (name)
返回全局变量的值,或者调用一个``getglobal‘‘标签方法。它的完整的语义在 4.8 描述。字符串 name 不需要是一个合乎语法的有效的变量名。
getn (table)
返回表的尺寸,当 table 被看作 list 的时候。如果表有一个 n 字段且值是一个数值型,这个值就是表的尺寸。否则,尺寸就是表中值不是 nil 的最大的索引。这个函数可以被定义为 Lua:
function getn (t) if type(t.n) == "number" then return t.n end local max = 0 for i, _ in t do if type(i) == "number" and i>max then max=i end end return max end
gettagmethod (tag, event)
返回一个给定对(tag, event 对)当前的标签方法。这个函数不可以被用来获得 ``gc‘‘ 事件的标签方法。(这样的标签方法只可以由 C 代码来操纵。)
globals ([table])
返回当前的全局表。如果参数 table 给定了,它也把当前的全局表设置为这个参数。
newtag ()
返回一个新的标签。
next (table, [index])
允许一个程序遍历一个表的所有字段。它的第一个参数是一个表,第二个参数是表中的索引。它返回表的下一个索引和索引所对应的值。当用 nil 做为第二个参数调用它时,函数返回表的第一个健值对。当用最后一个索引调用,或者用 nil 调用一个空表,均返回 nil。如果没有第二个参数,它被解释为 nil 。
Lua 中没有字段的声明;在语义上,表中一个字段不存在和字段的值为 nil 没有区别。所以,该函数只考虑非 nil 的字段。索引的枚举顺序没有规定,就算是数字索引的也没有规定(为遍历一个表以数字顺序,使用一个数值型 for 或者函数 foreachi)。
next 的行为是未定义的如果你在遍历过程中改变了表。
print (e1, e2, ...)
可以接受任意数量的参数,以 tostring 返回的字符串打印它们的值。这个函数不是为了格式化输出,只是为了以一种快速的方法显示一个值,例如打印一个调试信息。参见 6.4 节一个格式化输出函数。
rawget (table, index)
返回 table[index] 的真实值,避免唤起任何标签方法。table 必须是一个表,index 是一个不同于 nil 的值。
rawset (table, index, value)
以 value 设置 table[index] 的真实值,避免唤起任何标签方法。table 必须是一个表,index 是一个不同于 nil 的值,value 可以是任何 Lua 值。
setglobal (name, value)
设置具名全局变量为给定值,或者调用一个 ``setglobal‘‘ 的标签方法。它的完整的语义描述在 4.8 节。字符串 name 不需要是一个合乎语法的有效名字。
settag (t, tag)
设置给定表(参见 3 节)的标签。tag 必须是一个收 newtag 生成的值(参见 6.1 节)。settag 返回它的第一个参数的值(表)。为了宿主程序的安全性,在 Lua 中改变一个 userdata 的标签是不可能的。
settagmethod (tag, event, newmethod)
为新定的对(tag, event 对)设置一个新的标签方法并返回老的方法。如果 newmethod 为 nil,那么 settagmethod 恢复给定事件的默认行为。这个函数不可以用来为 ``gc‘‘ 事件设置标签方法。(这样的标签方法只能有 C 代码来操纵。)
sort (table [, comp])
以给定顺序排序表中的元素,就地排序,从 table[1] 到 table[n],这里 n 是 getn(table) 的结果(参见 6.1 节)。如果给定 comp,它就必须是一个函数可以接受两个表的元素,且返回 true (即,一个不同于 nil 的值)当第一个小于第二个的时候(所以 not comp(a[i+1], a[i]) 将为 true 在排序之后)。如果 comp 没有给定,那么标准的 Lua 运算符 < 会被使用。
sort 算法不稳定(即,元素由给定的顺序被认为是相等的可能会被 sort 改变它们的相对位置)。
tag (v)
允许 Lua 程序测试一个值的标签(参见 3 节)。它接受一个参数,返回它的标签(一个数字)。
tonumber (e [, base])
尝试把它的参数转换为一个数字。如果参数已经是一个数字或者是一个可以转换为数字的字符串,它返回那个数字;否则,返回 nil。
一个可选的参数指定解释数字时的 base 。base 可以是 2 到 36 之间的任意整数(含 2 和 36)。如果 base 大于 10,字母 `A‘ (大小写均可)代表 10 ,`B‘ 代表 11,以此类推,`Z‘ 代表 35 。在 base 为 10 (默认的)时,数字可以有一个小数部分,以及一个可选的指数部分(参见 4.2 节)。在其它的 base 的情况下,只可接受无符号整型。
tostring (e)
函数可以接受一个任何类型的值作为参数,并以一个合理的格式把它转化为字符串。可以使用函数 format 来完全控制数字如何转换。
tinsert (table [, pos] , value)
在 table 的位置 pos 插入元素,如果需要的话,移动其它的元素来开辟空间。pos 的默认值是 n+1,这里 n 是 getn(table)(参见 6.1 节)的结果,所以一个调用 tinsert(t,x) 会在表 t 尾部插入 x 。这个函数也会设置或者增加表的字段 n 为 n+1。这个函数和下面的 Lua 函数等价,除了使用表时全部为 raw (即,不唤起标签方法):
function tinsert (t, ...) local pos, value local n = getn(t) if arg.n == 1 then pos, value = n+1, arg[1] else pos, value = arg[1], arg[2] end t.n = n+1; for i=n,pos,-1 do t[i+1] = t[i] end t[pos] = value end
tremove (table [, pos])
在 table 的位置 pos 移除元素,如果需要的话,移动其它的元素来整合空间。返回移除元素的值。pos 的默认值是 n,这里 n 是 getn(table)(参见 6.1 节)的结果,所以一个调用 tremove(t) 会移除表 t 尾部元素 。这个函数也会设置或者减少表的字段 n 为 n-1。
这个函数和下面的 Lua 函数等价,除了使用表时全部为 raw (即,不唤起标签方法):
function tremove (t, pos) local n = getn(t) if n<=0 then return end pos = pos or n local value = t[pos] for i=pos,n-1 do t[i] = t[i+1] end t[n] = nil t.n = n-1 return value end
type (v)
函数允许 Lua 测试一个值的类型。它接受一个参数,返回它的类型,以一个字符串表示。这个函数可能的返回值是:
“nil” (一个字符串,不是 nil 值),“number”, “string”,“table”, “function" 和 "userdata"。
(未完待续)