Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
api:buffer:zh [2023/11/29 05:00]
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` ​  
 +  从IO流读取**n**个字节（以二进制模式）或字符（以文本模式），结果将以字符串形式返回。参见[[api:​non-standard-lua-libs#​input_and_output_facilities|io.open]]以获取有关如何以不同模式打开文件的更多信息。 ​  
 +  示例：`local chars = b:​read(10)` ​ 
 \\ \\
 +  * `*n`或者`*number`  ​
 +  从IO流中读取下一组可被解释为数字的字节。请注意读取到的数字会受到打开模式为二进制还是文本的影响。参见[[api:​non-standard-lua-libs#​input_and_output_facilities|io.open]]以获取有关如何以不同模式打开文件的更多信息。  ​
 +  示例：`local number = b:​read("​*n"​)`  ​
 +\\
 +  * `*l`或者`*line`  ​
 +  从IO流中读取下一行，截掉换行标记（可能是 \n,​、\r或\r\n）。  ​
 +  示例：`local line = b:​read("​*l"​)`  ​
 +\\
 +  * `*L`或者`*Line`  ​
 +  从IO流中读取下一行，类似`*line`，但是在结果中保留换行标记。  ​
 +  示例：`local whole_line = b:​read("​*L"​)`  ​
 +\\
 +  * `*a`或者`*all`  ​
 +  从IO流中读取所有剩余内容，直到遇到nil。在此读取格式后再指定其他格式没有意义。  ​
 +  示例：`local the_whole_file = b:​read("​*a"​)`\\
 +  \\
 - `b:​getTimeout() number`  ​ - `b:​getTimeout() number`  ​
   返回当前带缓冲流设定的超时时间（单位为秒）。默认超时时间为`math.huge`。参阅`setTimeout`以获取有关于带缓冲流超时时间影响的更多信息。  ​   返回当前带缓冲流设定的超时时间（单位为秒）。默认超时时间为`math.huge`。参阅`setTimeout`以获取有关于带缓冲流超时时间影响的更多信息。  ​
Line 83: 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和失败原因（以字符串形式）。