Differences

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

--- api:buffer:zh [2023/11/29 02:59]
hfsr [静态方法]
+++ api:buffer:zh [2023/11/29 05:36] (current)
hfsr [接口方法]
@@ Line 15: / Line 15: @@
 实例方法
 -----------
-下列方法只能从`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]]以获取有关如何以不同模式打开文件的更多信息。
-  从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`
+  从IO流中读取下一组可被解释为数字的字节。请注意读取到的数字会受到打开模式为二进制还是文本的影响。参见[[api:non-standard-lua-libs#input_and_output_facilities|io.open]]以获取有关如何以不同模式打开文件的更多信息。
-    * "\*n" 或 "\*number"
+  示例：`local number = b:read("*n")`
+\\
-  从IO流中读取下一组可被解释为数字的字节。请注意读取到的数字会受到打开模式为二进制还是文本的影响。参见[[api:non-standard-lua-libs#input_and_output_facilities|io.open]]以获取有关如何以不同模式打开文件的更多信息。
+  * `*l`或者`*line`
+  从IO流中读取下一行，截掉换行标记（可能是 \n,、\r或\r\n）。
-    `local number = b:read("*n")`
+  示例：`local line = b:read("*l")`
+\\
-    * "\*l" or "\*line"
+  * `*L`或者`*Line`
+  从IO流中读取下一行，类似`*line`，但是在结果中保留换行标记。
-  从IO流中读取下一行，截掉换行标记（可能是 \n,、\r或\r\n）。
+  示例：`local whole_line = b:read("*L")`
+\\
-    `local line = b:read("*l")`
+  * `*a`或者`*all`
+  从IO流中读取所有剩余内容，直到遇到nil。在此读取格式后再指定其他格式没有意义。
-    * "\*L" or "\*Line"
+  示例：`local the_whole_file = b:read("*a")`\\
+  \\
-  从IO流中读取下一行，类似"*line"，但是在结果中保留换行标记。
+- `b:getTimeout() number`
+  返回当前带缓冲流设定的超时时间（单位为秒）。默认超时时间为`math.huge`。参阅`setTimeout`以获取有关于带缓冲流超时时间影响的更多信息。
-    `local whole_line = b:read("*L")`
+\\
-    * "\*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 106: / Line 90: @@
 ```
 - `b:seek([whence:string], [offset:number])`
   从`whence`开始移动IO流位置，共移动`offset`字节，两个参数都是可选的。`whence`默认为"cur"，'offset'默认为0。
   可用的`whence`值：
@@ Line 120: / Line 103: @@
 下列方法应当在打算传给`buffer.new`的带缓冲IO流上实现。
 - `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和失败原因（以字符串形式）。