6.1 – 基础函数

基础库提供了 Lua 核心函数。如果你不将这个库包含在你的程序中,你就需要小心检查程序是否需要自己提供其中一些特性的实现。


assert (v [, message])

如果其参数 v 的值为假(nilfalse),它就调用 error;否则,返回所有的参数。在错误情况时,message 指那个错误对象;如果不提供这个参数,参数默认为 "assertion failed!" 。


collectgarbage ([opt [, arg]])

这个函数是垃圾收集器的通用接口。通过参数 opt 它提供了一组不同的功能:

  • "collect": 做一次完整的垃圾收集循环。这是默认选项。
  • "stop": 停止垃圾收集器的运行。在调用重启前,收集器只会因显式的调用运行。
  • "restart": 重启垃圾收集器的自动运行。
  • "count": 以 K 字节数为单位返回 Lua 使用的总内存数。这个值有小数部分,所以只需要乘上 1024 就能得到Lua 使用的准确字节数(除非溢出)。
  • "step": 单步运行垃圾收集器。步长“大小”由 arg 控制。传入 0 时,收集器步进(不可分割的)一步。传入非 0 值,收集器收集相当于 Lua 分配这些多(K 字节)内存的工作。如果收集器结束一个循环将返回 true
  • "setpause": arg 设为收集器的 间歇率(参见 §2.5)。返回 间歇率 的前一个值。
  • "setstepmul": arg 设为收集器的 步进倍率(参见 §2.5)。返回 步进倍率 的前一个值。
  • "isrunning": 返回表示收集器是否在工作的布尔值(即未被停止)。

dofile ([filename])

打开该名字的文件,并执行文件中的 Lua 代码块。不带参数调用时, dofile 执行标准输入的内容(stdin)。返回该代码块的所有返回值。对于有错误的情况,dofile 将错误反馈给调用者(即,dofile 没有运行在保护模式下)。


error (message [, level])

中止上一次保护函数调用,将错误对象 message 返回。函数 error 永远不会返回。 当 message 是一个字符串时,通常 error 会把一些有关出错位置的信息附加在消息的前头。level 参数指明了怎样获得出错位置。对于 level 1 (默认值),出错位置指 error 函数调用的位置。Level 2 将出错位置指向调用 error的函数的函数;以此类推。传入 level 0 可以避免在消息前添加出错位置信息。


_G

一个全局变量(非函数),内部储存有全局环境(参见 §2.2)。Lua 自己不使用这个变量;改变这个变量的值不会对任何环境造成影响,反之亦然。


getmetatable (object)

如果 object 不包含元表,返回 nil 。否则,如果在该对象的元表中有 "__metatable" 域时返回其关联值,没有时返回该对象的元表。


ipairs (t)

返回三个值(迭代函数、表 t 以及 0 ),如此,以下代码

  1. for i,v in ipairs(t) do body end

将迭代键值对(1,t[1]) ,(2,t[2]), … ,直到第一个空值。


load (chunk [, chunkname [, mode [, env]]])

加载一个代码块。

如果 chunk 是一个字符串,代码块指这个字符串。如果 chunk 是一个函数,load 不断地调用它获取代码块的片断。每次对 chunk 的调用都必须返回一个字符串紧紧连接在上次调用的返回串之后。当返回空串、nil、或是不返回值时,都表示代码块结束。

如果没有语法错误,则以函数形式返回编译好的代码块;否则,返回 nil 加上错误消息。

如果结果函数有上值,env 被设为第一个上值。若不提供此参数,将全局环境替代它。所有其它上值初始化为 nil。(当你加载主代码块时候,结果函数一定有且仅有一个上值 _ENV (参见 §2.2))。然而,如果你加载一个用函数(参见 string.dump,结果函数可以有任意数量的上值)创建出来的二进制代码块时,所有的上值都是新创建出来的。也就是说它们不会和别的任何函数共享。

chunkname 在错误消息和调试消息中(参见 §4.9),用于代码块的名字。如果不提供此参数,它默认为字符串chunkchunk 不是字符串时,则为 "=(load)" 。

字符串 mode 用于控制代码块是文本还是二进制(即预编译代码块)。它可以是字符串 "b" (只能是二进制代码块),"t" (只能是文本代码块),或 "bt" (可以是二进制也可以是文本)。默认值为 "bt"。

Lua 不会对二进制代码块做健壮性检查。恶意构造一个二进制块有可能把解释器弄崩溃。


loadfile ([filename [, mode [, env]]])

load 类似,不过是从文件 filename 或标准输入(如果文件名未提供)中获取代码块。


next (table [, index])

运行程序来遍历表中的所有域。第一个参数是要遍历的表,第二个参数是表中的某个键。next 返回该键的下一个键及其关联的值。如果用 nil 作为第二个参数调用 next将返回初始键及其关联值。当以最后一个键去调用,或是以 nil 调用一张空表时,next 返回 nil。如果不提供第二个参数,将认为它就是 nil。特别指出,你可以用 next(t) 来判断一张表是否是空的。

索引在遍历过程中的次序无定义,即使是数字索引也是这样。(如果想按数字次序遍历表,可以使用数字形式的 for 。)

当在遍历过程中你给表中并不存在的域赋值,next 的行为是未定义的。然而你可以去修改那些已存在的域。特别指出,你可以清除一些已存在的域。


pairs (t)

如果 t 有元方法 __pairs,以 t 为参数调用它,并返回其返回的前三个值。

否则,返回三个值:next 函数,表 t,以及 nil。因此以下代码

  1. for k,v in pairs(t) do body end

能迭代表 t 中的所有键值对。

参见函数 next 中关于迭代过程中修改表的风险。


pcall (f [, arg1, ···])

传入参数,以 保护模式 调用函数 f 。这意味着 f 中的任何错误不会抛出;取而代之的是,pcall 会将错误捕获到,并返回一个状态码。第一个返回值是状态码(一个布尔量),当没有错误时,其为真。此时,pcall 同样会在状态码后返回所有调用的结果。在有错误时,pcall 返回 false 加错误消息。


print (···)

接收任意数量的参数,并将它们的值打印到 stdout。它用 tostring 函数将每个参数都转换为字符串。print 不用于做格式化输出。仅作为看一下某个值的快捷方式。多用于调试。完整的对输出的控制,请使用 string.format 以及 io.write


rawequal (v1, v2)

在不触发任何元方法的情况下检查 v1 是否和 v2 相等。返回一个布尔量。


rawget (table, index)

在不触发任何元方法的情况下获取 table[index] 的值。table 必须是一张表;index 可以是任何值。


rawlen (v)

在不触发任何元方法的情况下返回对象 v 的长度。v 可以是表或字符串。它返回一个整数。


rawset (table, index, value)

在不触发任何元方法的情况下将 table[index] 设为 valuetable 必须是一张表,index 可以是 nil 与 NaN 之外的任何值。value 可以是任何 Lua 值。 这个函数返回 table


select (index, ···)

如果 index 是个数字,那么返回参数中第 index 个之后的部分;负的数字会从后向前索引(-1 指最后一个参数)。否则,index 必须是字符串 "#",此时 select 返回参数的个数。


setmetatable (table, metatable)

给指定表设置元表。(你不能在 Lua 中改变其它类型值的元表,那些只能在 C 里做。)如果 metatablenil,将指定表的元表移除。如果原来那张元表有 "__metatable" 域,抛出一个错误。

这个函数返回 table


tonumber (e [, base])

如果调用的时候没有 basetonumber 尝试把参数转换为一个数字。如果参数已经是一个数字,或是一个可以转换为数字的字符串,tonumber 就返回这个数字;否则返回 nil

字符串的转换结果可能是整数也可能是浮点数,这取决于 Lua 的转换文法(参见 §3.1)。(字符串可以有前置和后置的空格,可以带符号。)

当传入 base 调用它时,e 必须是一个以该进制表示的整数字符串。进制可以是 2 到 36 (包含 2 和 36)之间的任何整数。大于 10 进制时,字母 'A' (大小写均可)表示 10 ,'B' 表示 11,依次到 'Z' 表示 35 。如果字符串 e 不是该进制下的合法数字,函数返回 nil


tostring (v)

可以接收任何类型,它将其转换为人可阅读的字符串形式。浮点数总被转换为浮点数的表现形式(小数点形式或是指数形式)。(如果想完全控制数字如何被转换,可以使用string.format。) 如果 v"__tostring" 域的元表,tostring 会以 v 为参数调用它。并用它的结果作为返回值。


type (v)

将参数的类型编码为一个字符串返回。函数可能的返回值有"nil" (一个字符串,而不是 nil 值),"number","string","boolean","table","function","thread","userdata"。


_VERSION

一个包含有当前解释器版本号的全局变量(并非函数)。当前这个变量的值为 "Lua 5.3"。


xpcall (f, msgh [, arg1, ···])

这个函数和 pcall 类似。不过它可以额外设置一个消息处理器 msgh