This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
api:buffer:zh [2023/11/29 03:20] hfsr [实例方法] |
api:buffer:zh [2023/11/29 05:36] (current) hfsr [接口方法] |
||
---|---|---|---|
Line 26: | Line 26: | ||
设定缓冲区的模式(`mode`)和大小(`size`),并返回修改后的模式(`mode`)和大小(`size`)。`size`指定了缓冲的数据量,默认范围为[512, 8192]字节,根据可用系统内存而变化。`mode`和`size`可以为nil,此时将会沿用先前的值。`size`还被用于对流的`read(n)`调用。 | 设定缓冲区的模式(`mode`)和大小(`size`),并返回修改后的模式(`mode`)和大小(`size`)。`size`指定了缓冲的数据量,默认范围为[512, 8192]字节,根据可用系统内存而变化。`mode`和`size`可以为nil,此时将会沿用先前的值。`size`还被用于对流的`read(n)`调用。 | ||
模式只影响`write`方法,可用值包括: | 模式只影响`write`方法,可用值包括: | ||
- | * "no" 写入数据被立即推送进IO流。 | + | * `no`:写入数据被立即推送进IO流。 |
- | * "full" 写入数据会被缓存,直到尺寸到达`size`字节。这是默认模式。 | + | * `full`:写入数据会被缓存,直到尺寸到达`size`字节。这是默认模式。 |
- | * "line" 写入数据会被缓存,直到出现换行或达到`size`上限。\\ | + | * `line`:写入数据会被缓存,直到出现换行或达到`size`上限。\\ |
\\ | \\ | ||
- `b:write([values...])` | - `b:write([values...])` | ||
Line 52: | Line 52: | ||
- `b:read([formats...]) string...` | - `b:read([formats...]) string...` | ||
- | 先进的读取器,可支持多种格式。首先,如果不指定`format`调用,即参数列表留空,它会从流中读取下一行,等价于`read("*l")`。 | + | 比较高级的读取器,可支持多种格式。首先,如果不指定`format`调用,即参数列表留空,它会从流中读取下一行,等价于`read("*l")`。 |
- | 每个`format`值都会先从IO流中读出,再一次性以多个返回值的形式返回。请注意格式字符串都有 \* 前缀,而且只有字符串的第一个字符有意义,其余字符将会被忽略。下列是支持的格式: | + | 每个`format`值都会先从IO流中读出,再一次性以多个返回值的形式返回。请注意格式字符串都有 \* 前缀,而且只有字符串的第一个字符有意义,其余字符将会被忽略。 |
- | * 一个数字值,例如`10` | + | 下列是支持的格式: |
+ | * 一个数字值,例如`10` | ||
从IO流读取**n**个字节(以二进制模式)或字符(以文本模式),结果将以字符串形式返回。参见[[api:non-standard-lua-libs#input_and_output_facilities|io.open]]以获取有关如何以不同模式打开文件的更多信息。 | 从IO流读取**n**个字节(以二进制模式)或字符(以文本模式),结果将以字符串形式返回。参见[[api:non-standard-lua-libs#input_and_output_facilities|io.open]]以获取有关如何以不同模式打开文件的更多信息。 | ||
- | `local chars = b:read(10)` | + | 示例:`local chars = b:read(10)` |
\\ | \\ | ||
- | * "\*n" 或 "\*number" | + | * `*n`或者`*number` |
从IO流中读取下一组可被解释为数字的字节。请注意读取到的数字会受到打开模式为二进制还是文本的影响。参见[[api:non-standard-lua-libs#input_and_output_facilities|io.open]]以获取有关如何以不同模式打开文件的更多信息。 | 从IO流中读取下一组可被解释为数字的字节。请注意读取到的数字会受到打开模式为二进制还是文本的影响。参见[[api:non-standard-lua-libs#input_and_output_facilities|io.open]]以获取有关如何以不同模式打开文件的更多信息。 | ||
- | `local number = b:read("*n")` | + | 示例:`local number = b:read("*n")` |
\\ | \\ | ||
- | * "\*l"或者"\*line" | + | * `*l`或者`*line` |
从IO流中读取下一行,截掉换行标记(可能是 \n,、\r或\r\n)。 | 从IO流中读取下一行,截掉换行标记(可能是 \n,、\r或\r\n)。 | ||
- | `local line = b:read("*l")` | + | 示例:`local line = b:read("*l")` |
\\ | \\ | ||
- | * "\*L"或者"\*Line" | + | * `*L`或者`*Line` |
- | 从IO流中读取下一行,类似"*line",但是在结果中保留换行标记。 | + | 从IO流中读取下一行,类似`*line`,但是在结果中保留换行标记。 |
- | `local whole_line = b:read("*L")` | + | 示例:`local whole_line = b:read("*L")` |
\\ | \\ | ||
- | * "\*a"或者"\*all" | + | * `*a`或者`*all` |
从IO流中读取所有剩余内容,直到遇到nil。在此读取格式后再指定其他格式没有意义。 | 从IO流中读取所有剩余内容,直到遇到nil。在此读取格式后再指定其他格式没有意义。 | ||
- | `local the_whole_file = b:read("*a")` | + | 示例:`local the_whole_file = b:read("*a")`\\ |
- | \\ | + | \\ |
- | | + | |
- `b:getTimeout() number` | - `b:getTimeout() number` | ||
返回当前带缓冲流设定的超时时间(单位为秒)。默认超时时间为`math.huge`。参阅`setTimeout`以获取有关于带缓冲流超时时间影响的更多信息。 | 返回当前带缓冲流设定的超时时间(单位为秒)。默认超时时间为`math.huge`。参阅`setTimeout`以获取有关于带缓冲流超时时间影响的更多信息。 | ||
Line 103: | Line 103: | ||
下列方法应当在打算传给`buffer.new`的带缓冲IO流上实现。 | 下列方法应当在打算传给`buffer.new`的带缓冲IO流上实现。 | ||
- | - `close() ok, reason` | + | - `close() ok, reason` |
- | + | 关闭句柄,释放资源,断开连接。并返回是否成功。 | |
- | 关闭句柄,释放资源,断开连接。并返回是否成功 | + | \\ |
- | + | - `write(arg: string) ok, reason` | |
- | - `write(arg: string) ok, reason` | + | 以字节形式写入`arg`,假定提供的是不加修饰的未格式化字符。失败时返回假值和原因。 |
- | + | \\ | |
- | 以字节形式写入`arg`,假定提供的是不加修饰的未格式化字符。失败时返回假值和原因。 | + | - `read(n: number) ok, reason` |
- | + | 返回`n`个字节,而**不是**`n`个考虑Unicode的字符。我们假设你的数据为二进制数据,并且让buffer库管理IO模式与Unicode字符串打包(如果可用)。请注意这就是[[api:filesystem|filesystem]]库的工作方式。直到返回`nil`前,此方法的调用者都会假定还有更多数据可读取。空字符串或长度短于`n`的字符串也是合法返回值,但调用者可能假定在返回`nil`前仍可请求更多数据。 | |
- | - `read(n: number) ok, reason` | + | \\ |
- | + | - `seek([whence: string], [offset: number]) [offset from start] or falsey, reason` | |
- | 返回`n`个字节,而**不是**`n`个考虑Unicode的字符。我们假设你的数据为二进制数据,并且让buffer库管理IO模式与Unicode字符串打包(如果可用)。请注意这就是[[api:filesystem|filesystem]]库的工作方式。此方法的调用者会假定还有更多数据可以读取,直到返回`nil`。空字符串或长度短于`n`的字符串也是合法返回值,但调用者可能假定在`nil`返回前仍有更多数据可以请求。 | + | |
- | + | ||
- | - `seek([whence: string], [offset: number]) [offset from start] or falsey, reason` | + | |
请查看`b:seek()`以获取细节。简而言之,从`whence`起将IO流位置移动`offset`,并返回从IO流开始位置到seek操作结束后的位置之间的`offset`值。请注意,`seek("cur", 0)`也是合法请求,被用于调用者想获取IO流当前位置的情况下。你的自定义IO流不需要一定支持`seek`,这种情况下(以及任何失败情况下)你需要返回nil和失败原因(以字符串形式)。 | 请查看`b:seek()`以获取细节。简而言之,从`whence`起将IO流位置移动`offset`,并返回从IO流开始位置到seek操作结束后的位置之间的`offset`值。请注意,`seek("cur", 0)`也是合法请求,被用于调用者想获取IO流当前位置的情况下。你的自定义IO流不需要一定支持`seek`,这种情况下(以及任何失败情况下)你需要返回nil和失败原因(以字符串形式)。 | ||