Differences

This shows you the differences between two versions of the page.

--- api:buffer:zh [2023/10/16 10:33]
hfsr [静态方法]
+++ api:buffer:zh [2023/11/29 05:24]
hfsr [实例方法]
@@ Line 1: / Line 1: @@
 Buffer(缓冲) API
 ===========
-`buffer`库提供了便于使用的IO流。本库提供的流更像是`io`库提供的，由`io.open`返回的流，**不像**`filesystem.open`返回的原始流，后者支持的方法没有前者那么多。下文的[[api:buffer:zh#实例方法|实例方法]]板块列出的方法可被用于从`io.open`函数获取的文件句柄。因此就算你没打算构建自定义带缓冲IO流，此API文档也会大有裨益。
+`buffer`库提供了便于使用的IO流。本库提供的流更像是`io`库提供的，由`io.open`返回的流，**不像**`filesystem.open`返回的原始流，后者支持的方法没有前者那么多。下文[[api:buffer:zh#实例方法|实例方法]]板块列出的方法也可用于从`io.open`函数获取的文件句柄，因此就算你没打算构建自定义带缓冲流，此API文档也会大有裨益。
-此外，该API还允许你创建带缓冲IO流。你需要提供后端的流式读取和流式写入，buffer库提供数据缓冲与格式化。一般而言，用户无需构建自己的带缓冲输入输出流。以备参考，io库就使用了带缓冲IO流（包含文件io和控制台io）。
+此外，该API还能让你创建带缓冲流。你需要提供后端的流式读取和流式写入，buffer库提供数据缓冲与格式化。一般而言，用户无需构建自己的带缓冲流。以备参考，io库就使用了带缓冲流（包含文件io和控制台io）。
 静态方法
@@ Line 11: / Line 11: @@
 - `buffer.new([mode: string], stream: table)`
- 用读写模式(`mode`)来修饰传入的流(`stream`)，以创建一个带缓冲IO流。模式(`mode`)可以为只读（r或`nil`）、读写（rw）或仅写入（w）。请查看`stream`对象所需的流[[api:buffer:zh#实例方法|实例方法]]有关内容。
+  将传入的流(`stream`)封装上读写模式(`mode`)，以创建一个带缓冲IO流。模式(`mode`)可以为只读（r或`nil`）、读写（rw）或仅写入（w）。请查看`stream`对象所需流的[[api:buffer:zh#实例方法|实例方法]]有关内容。
 实例方法
 -----------
-下列方法只能从`buffer.new`创建的实例处调用（**注意：**`io.open`返回的文件句柄也是`buffer.new`创建的带缓冲IO流）这些方法均为实例方法，需要实例调用符号`:`。为了有助于区分这些实例方法与静态方法（例如`buffer.new`），这些方法名将会加上`b:`作为前缀。
+下列方法只能在`buffer.new`创建的实例上调用（**注意：**`io.open`返回的文件句柄也是`buffer.new`创建的带缓冲流）。这些方法均为实例方法，需要实例调用符号`:`。为了有助于区分这些实例方法与静态方法（例如`buffer.new`），这些方法名将会加上`b:`作为前缀。
 - `b:flush()`
+  如果缓冲区存在任何数据，立即将其写入到IO流并释放。
-  如果缓冲区存在任何数据，立即将其写入到IO流并释放。
+\\
 - `b:close()`
+  清空缓冲区并关闭封装的流。
-  清空缓冲区并关闭修饰的流。
+\\
 - `b:setvbuf([mode: string], [size: number]) mode, size`
+  设定缓冲区的模式（`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`方法，可用值包括：
-  * "no" 写入数据被立即推送进IO流。
+  * `no`：写入数据被立即推送进IO流。
-  * "full" 写入数据会被缓存，直到尺寸到达`size`字节。这是默认模式。
+  * `full`：写入数据会被缓存，直到尺寸到达`size`字节。这是默认模式。
-  * "line" 写入数据会被缓存，直到出现换行或达到`size`上限。
+  * `line`：写入数据会被缓存，直到出现换行或达到`size`上限。\\
+  \\
 - `b:write([values...])`
+  将所有的`value`写入到IO流，首先会依据缓冲模式和缓冲区大小（参见`setvbuf`）进行缓存。请注意要写入文件的话，需要将文件以**可写入**模式打开。\\
-  将所有的`value`写入到IO流，首先依据缓冲模式和缓冲区大小（参见`setvbuf`）。请注意要写入文件的话，需要将文件以*可写入*模式打开。
 ```lua
@@ Line 43: / Line 40: @@
 ```
+- `b:lines([line_formats...]) string array`
-- `b:lines([line_formats...]) string array`
+  返回一个迭代器，其会从IO流进行读取，直到读取到`nil`。每次读取时，都会将参数列表`line_formmats`传递给`stream:read(...)`。绝大多数使用情况下都不需要定义`line_format`，也就是不给`line()`传参。迭代器的默认行为（即没有`line_format`时）是每次从流中读取一行内容。
-  返回一个迭代器，其会从IO流进行读取，直到读取到nil。每次读取时，都会将参数列表`line_formmats`传递给`stream:read(...)`。绝大多数使用情况下都不需要定义`line_format`，也就是不给`line()`传参。迭代器的默认行为（即没有`line_format`时）是每次从IO流中读取一行内容。
 ```lua
@@ Line 56: / Line 51: @@
 ```
 - `b:read([formats...]) string...`
+  比较高级的读取器，可支持多种格式。首先，如果不指定`format`调用，即参数列表留空，它会从流中读取下一行，等价于`read("*l")`。
-  相当先进的读取器，可支持多种格式。首先，如果不指定`format`调用，即参数列表留空，它会从IO流中读取下一行，等价于`read("*l")`。
+每个`format`值都会先从IO流中读出，再一次性以多个返回值的形式返回。请注意格式字符串都有 \* 前缀，而且只有字符串的第一个字符有意义，其余字符将会被忽略。
-`format`指定的每个值都会先从IO流中读出，结果一次性以多个返回值的形式返回。请注意格式字符串都有 \* 前缀，而且只有字符串的第一个字符有意义，其余字符将会被忽略。下列是支持的格式：
+  下列是支持的格式：
-    * 一个数字值，例如`10`
+  * 一个数字值，例如`10`
   从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]]以获取有关如何以不同模式打开文件的更多信息。
+  示例：`local number = b:read("*n")`
-  从IO流中读取下一组可被解释为数字的字节。请注意读取到的数字会受到打开模式为二进制还是文本的影响。参见[[api:non-standard-lua-libs#input_and_output_facilities|io.open]]以获取有关如何以不同模式打开文件的更多信息。
+\\
+  * `*l`或者`*line`
-    `local number = b:read("*n")`
+  从IO流中读取下一行，截掉换行标记（可能是 \n,、\r或\r\n）。
+  示例：`local line = b:read("*l")`
-    * "\*l" or "\*line"
+\\
+  * `*L`或者`*Line`
-  从IO流中读取下一行，截掉换行标记（可能是 \n,、\r或\r\n）。
+  从IO流中读取下一行，类似`*line`，但是在结果中保留换行标记。
+  示例：`local whole_line = b:read("*L")`
-    `local line = b:read("*l")`
+\\
+  * `*a`或者`*all`
-    * "\*L" or "\*Line"
+  从IO流中读取所有剩余内容，直到遇到nil。在此读取格式后再指定其他格式没有意义。
+  示例：`local the_whole_file = b:read("*a")`\\
-  从IO流中读取下一行，类似"*line"，但是在结果中保留换行标记。
+  \\
+- `b:getTimeout() number`
-    `local whole_line = b:read("*L")`
+  返回当前带缓冲流设定的超时时间（单位为秒）。默认超时时间为`math.huge`。参阅`setTimeout`以获取有关于带缓冲流超时时间影响的更多信息。
+\\
-    * "\*a" or "\*all"
-  从IO流中读取所有剩余内容，直到遇到nil。在此读取格式后再指定其他格式没有意义。
-    `local the_whole_file = b:read("*a")`
-- `b:getTimeout() number`
-  返回当前带缓冲IO流设定的超时时间（单位为秒）。默认超时时间为`math.huge`。参阅`setTimeout`以获取有关于带缓冲IO流超时时间影响的更多信息。
 - `b:setTimeout(timeout)`
+  设定带缓冲流限制`read`操作的时长，单位为秒。请注意此超时值无法被严格遵守。只需一次`readChunk`（实际调用`read`方法的内部方法）即可完成的读取操作中不会检查`timeout`的限制。只有在流读取操作的间隔才会检查是否超时（下附一份样例）。因此，如果一次读取操作中需要多次块读取，并且首次块读取开始和最后一次块读取开始之间的时长大于等于超时时间，IO流会出错。再次强调，超时时间默认为`math.huge`。
-  设定带缓冲IO流限制`read`操作的时长，单位为秒。请注意此超时值无法被严格遵守。只需一次`readChunk`（支持`read`方法的内部方法）即可完成的读取操作中不会检查`timeout`的限制。只有在流读取操作的间隔才会检查是否超时（下附一份样例）。因此，如果一次读取操作中需要多次块读取，并且首次块读取开始和最后一次块读取开始之间的时长大于等于超时时间，IO流会出错。再次强调，超时时间默认为`math.huge`。
@@ Line 105: / Line 90: @@
 ```
 - `b:seek([whence:string], [offset:number])`
   从`whence`开始移动IO流位置，共移动`offset`字节，两个参数都是可选的。`whence`默认为"cur"，'offset'默认为0。
   可用的`whence`值：