仓颉标准库 std.io 实用函数指南:copy、readString、readStringUnchecked 与 readToEnd 的用法与实现原理
仓颉标准库 std.io 实用函数指南:copy、readString、readStringUnchecked 与 readToEnd 的用法与实现原理
导读
本文聚焦仓颉(Cangjie)标准库 std.io 包中四个顶层实用函数:copy、readString、readStringUnchecked 与 readToEnd。它们是流式 I/O 编程中最常用的"一站式"工具函数,覆盖了从字节流拷贝、整流读成字符串到剩余数据批量取回等典型场景。读完本文,你将掌握这四个函数的完整签名、参数语义、异常行为、可复制的完整示例代码,并能结合标准库源码(io_utils.cj)理解其底层实现原理与实际工程应用方式。
一、函数总览:std.io 的四个顶层工具函数
在仓颉标准库 std.io 包中,除了 InputStream / OutputStream / Seekable 等接口与 ByteBuffer、BufferedInputStream 等类之外,还提供了四个直接可用的顶层函数,统一实现在 io_utils.cj 中:
| 函数签名 | 功能 |
|---|---|
copy(from: InputStream, to!: OutputStream): Int64 |
将一个输入流中未被读取的数据拷贝到另一个输出流,返回拷贝的字节数 |
readString<T>(from: T): String where T <: InputStream & Seekable |
读取入参流中的所有剩余内容,校验后返回字符串 |
readStringUnchecked<T>(from: T): String where T <: InputStream & Seekable |
读取入参流中的所有剩余内容,不校验字符串合法性 |
readToEnd<T>(from: T): Array<Byte> where T <: InputStream & Seekable |
获取入参流中所有未被读取的数据,返回字节数组拷贝 |
从签名可以看出,后三个函数都对泛型参数 T 施加了 T <: InputStream & Seekable 的约束:既要是输入流(具备 read 能力),又要支持游标定位(具备 seek 与 length/remainLength 等属性)。这也决定了它们的入参通常是 ByteBuffer 这类同时实现了 IOStream 与 Seekable 的流类型,或其他自定义的"可定位输入流"。关于这些接口的完整定义,可参考 io_package_interfaces.md;std.io 包的完整 API 清单见 io_package_overview.md。
1.1 接口前提:InputStream 与 Seekable
readString 系列函数与 readToEnd 依赖的两个接口定义在 stream.cj:
InputStream接口只声明一个方法func read(buffer: Array<Byte>): Int64,返回实际读入缓冲区的字节数;Seekable接口声明func seek(sp: SeekPosition): Int64以及三个只读属性length(流中数据总量)、position(当前游标位置)、remainLength(当前游标到流末尾的剩余字节数)。
SeekPosition 枚举(定义于 io_utils.cj)用于描述游标移动的三种基准位置:
| 枚举值 | 含义 |
|---|---|
Begin(Int64) |
从流起点开始移动指定字节数 |
Current(Int64) |
从当前位置开始移动指定字节数 |
End(Int64) |
从流末尾开始移动指定字节数 |
二、copy:输入流到输出流的高效数据搬运
2.1 函数签名与参数
public func copy(from: InputStream, to!: OutputStream): Int64
from:待读取数据的输入流,拷贝操作会消费其中未被读取的数据;to(标签参数):数据将要拷贝到的输出流;- 返回值:实际拷贝的字节数。
注意 to 是标签参数(声明为 to!),调用时必须写成 copy(sourceStream, to: targetStream) 的形式。
2.2 完整示例
import std.io.ByteBuffer
import std.io.copy
main(): Unit {
let sourceStream = ByteBuffer()
let targetStream = ByteBuffer()
/* 向源输入流写入数据 */
let sourceData = "Hello, World!".toArray()
sourceStream.write(sourceData)
/* 使用 copy 函数将源输入流的数据拷贝到目标输出流 */
let copiedBytes = copy(sourceStream, to: targetStream)
println("Copied ${copiedBytes} bytes.")
/* 读取目标输出流中的数据 */
let targetData: Array<Byte> = Array<Byte>(sourceData.size, repeat: 0)
targetStream.read(targetData)
println("Data copied to target stream: ${String.fromUtf8(targetData)}")
}
运行结果:
Copied 13 bytes.
Data copied to target stream: Hello, World!
2.3 实现原理:4096 字节分块搬运
从源码(io_utils.cj)看,copy 的实现是一个基于固定大小临时缓冲区的循环搬运过程:
let BLOCK_SIZE = 4096
...
public func copy(from: InputStream, to!: OutputStream): Int64 {
let tempArr = Array<Byte>(BLOCK_SIZE, repeat: 0)
var readCount = 0
while (true) {
let readRet = from.read(tempArr)
if (readRet > 0) {
to.write(tempArr.slice(0, readRet))
} else {
break
}
readCount += readRet
}
readCount
}
实现要点:
- 定义了
BLOCK_SIZE = 4096(4 KB)作为默认分块大小,避免为整块数据一次性分配过大内存; - 循环调用
from.read(tempArr),当返回 0(流结束)时终止循环; - 每次只把实际读到的字节区间
tempArr.slice(0, readRet)写入目标输出流,保证不把缓冲区中未填满的脏数据写出去; - 累计返回值即为总拷贝字节数。
copy 在仓颉标准库中已被实际用于文件系统层的文件复制:在 file.cj 的 File.copy 非覆盖实现中,正是通过 try (srcFile = File(sourcePath, Read), dstFile = File(destinationPath, Write)) { copy(srcFile, to: dstFile) } 完成的,可见它是"流式复制"这一通用场景的标准工具。
三、readString:将剩余流内容安全读取为字符串
3.1 函数签名与异常
public func readString<T>(from: T): String where T <: InputStream & Seekable
from:要读取数据的对象(须同时实现InputStream与Seekable);- 返回值:读取到的结果字符串;
- 异常:当剩余字节不符合 UTF-8 编码规则时,抛出 ContentFormatException。
3.2 完整示例:正常数据与非法 UTF-8 数据
import std.io.ByteBuffer
import std.io.readString
import std.io.ContentFormatException
main(): Unit {
let inputStream = ByteBuffer()
/* 向输入流写入数据 */
let sourceData = "Hello, World!".toArray()
inputStream.write(sourceData)
/* 使用 readString 函数读取输入流中的所有剩余内容 */
try {
let result = readString(inputStream)
println("Read string: ${result}")
} catch (e: ContentFormatException) {
println("Error: ${e.message}")
}
/* 向输入流写入一个不合法的 UTF-8 字节序列 */
let sourceDataError: Array<UInt8> = [0xC3, 0x28, 0x48, 0x65, 0x6C, 0x6C, 0x6F]
inputStream.write(sourceDataError)
/* 使用 readString 函数读取输入流中的所有剩余内容 */
try {
let result = readString(inputStream)
println("Read string: ${result}")
} catch (e: ContentFormatException) {
println("Error: ${e.message}")
}
}
运行结果:
Read string: Hello, World!
Error: Invalid UTF-8: byte sequence starting at index '0' is not a valid 2-byte UTF-8 encoding.
示例中第二段数据 0xC3 0x28 ... 故意构造了一个非法的 UTF-8 序列(0xC3 作为双字节编码的首字节,但紧随其后的 0x28 不是合法的续字节),因此 readString 会抛出 ContentFormatException,而不是返回一个包含乱码的字符串。
3.3 实现原理:先定容、后读取、再校验
readString 的实现(io_utils.cj)非常简洁:
public func readString<T>(from: T): String where T <: InputStream & Seekable {
var data = Array<Byte>(from.remainLength, repeat: 0)
return try {
from.read(data)
String.fromUtf8(data)
} catch (e: IllegalArgumentException) {
throw ContentFormatException(e.message)
}
}
关键步骤:
- 利用
Seekable.remainLength属性精确获知当前游标到流末尾的剩余字节数,一次性分配等长缓冲区; - 调用
from.read(data)把剩余数据全部读入; - 通过
String.fromUtf8(data)进行 UTF-8 解码校验;若底层解码抛出IllegalArgumentException,则转换为ContentFormatException重新抛出。
这里体现了 T <: InputStream & Seekable 约束的价值:没有 remainLength 就无法在读取前确定缓冲区大小,这也是该函数要求"可定位输入流"的根本原因。ContentFormatException 的定义与用法见 content_format_exception.cj。
四、readStringUnchecked:跳过校验的高速读取
4.1 函数签名
public unsafe func readStringUnchecked<T>(from: T): String where T <: InputStream & Seekable
该函数被声明为 unsafe,调用时必须在 unsafe { } 块内进行。它的语义与 readString 相同——读取入参流中所有剩余内容并返回字符串——但不会校验字符串的合法性。
4.2 完整示例
import std.io.ByteBuffer
import std.io.readStringUnchecked
main(): Unit {
let inputStream = ByteBuffer()
/* 向输入流写入数据 */
let sourceData = "Hello, World!".toArray()
inputStream.write(sourceData)
/* 在 unsafe 块内使用 readStringUnchecked 读取所有剩余内容 */
unsafe {
let result = readStringUnchecked(inputStream)
println("Read string: ${result}")
}
/* 向输入流写入一个不合法的 UTF-8 字节序列 */
let sourceDataError: Array<UInt8> = [0xC3, 0x28, 0x48, 0x65, 0x6C, 0x6C, 0x6F]
inputStream.write(sourceDataError)
/* 对非法 UTF-8 数据不做校验直接读取,会产生无法预期的输出字符 */
unsafe {
let result = readStringUnchecked(inputStream)
println("Read string: ${result}")
}
}
4.3 实现原理与使用边界
源码实现(io_utils.cj):
public unsafe func readStringUnchecked<T>(from: T): String where T <: InputStream & Seekable {
var data = Array<Byte>(from.remainLength, repeat: 0)
from.read(data)
String.fromUtf8Unchecked(data)
}
与 readString 的唯一区别是最后一步使用 String.fromUtf8Unchecked(data) 而非 String.fromUtf8(data)。这意味着:
- 优点:省去了逐字节的 UTF-8 合法性校验,在确认数据必然合法(例如数据来源可信、事先已验证)的高吞吐场景下可减少解码开销;
- 风险:如果数据确实包含非法 UTF-8 序列,返回的字符串可能包含无法预期的输出字符,且该行为不受
ContentFormatException保护,因此只应在能确保数据合法性的场景下使用。
五、readToEnd:批量取回全部剩余字节
5.1 函数签名
public func readToEnd<T>(from: T): Array<Byte> where T <: InputStream & Seekable
from:要读取数据的对象(同样要求InputStream & Seekable);- 返回值:未被读取的数据的拷贝(
Array<Byte>)。
5.2 完整示例
import std.io.ByteBuffer
import std.io.readToEnd
main(): Unit {
let inputStream = ByteBuffer()
/* 向输入流写入数据 */
let sourceData = "Hello, World!".toArray()
inputStream.write(sourceData)
/* 使用 readToEnd 读取输入流中的所有剩余内容 */
let data = readToEnd(inputStream)
println("${String.fromUtf8(data)}")
}
运行结果:
Hello, World!
5.3 实现原理:按数据规模分派的两条路径
readToEnd 的实现(io_utils.cj)相比前两者更为复杂,它根据流中剩余数据的规模选择了两种策略:
路径一:数据规模不可知或超大时,使用 4 KB 分块循环读取
let sum = from.length
const MAX_DIRECT_ALLOC_SIZE: Int64 = 1 << 30 // 1 GB
if (sum <= 0 || sum > MAX_DIRECT_ALLOC_SIZE) {
let tempSize: Int64 = BLOCK_SIZE
let temp: Array<Byte> = Array<Byte>(tempSize, repeat: 0)
var buffer: ByteBuffer = ByteBuffer(tempSize)
while (true) {
let readLen = from.read(temp)
if (readLen == 0) {
break
} else if (readLen == tempSize) {
buffer.write(temp)
} else {
buffer.write(temp.slice(0, readLen))
}
}
...
}
该路径适用于 length <= 0(例如流尚未定位、长度未知)或 length > 1 GB 的极端情况,避免一次性申请超大内存。
路径二:数据规模已知且适中,按剩余长度直接分配
let arr: Array<Byte> = Array<Byte>(sum, repeat: 0)
let onceMax = 1 << 30
var readSize = 0
var emptySize = arr.size
while (readSize < sum) {
let oneSize = if (emptySize > onceMax) { onceMax } else { emptySize }
let len = from.read(arr.slice(readSize, oneSize))
if (len == 0) { break }
readSize += len
emptySize -= len
}
arr.slice(0, readSize)
该路径按 from.length 一次性分配目标数组,但单次 read 以 1 GB(onceMax)为上限分片读取,避免单次调用拷贝过大区间;最终返回 arr.slice(0, readSize),即只包含实际读到的字节。
实际应用证据:readToEnd 是仓颉文件读取的核心工具,file.cj 的 File.readFrom(path: String) 实现即为:
var file = File(path, Read)
try {
return readToEnd(file)
} finally {
file.close()
}
也就是说,读取整个文件内容到 Array<Byte> 的底层操作正是由 readToEnd 完成的;它也被 console_reader.cj 等实现所复用。
六、四个函数的对比与选型建议
| 函数 | 返回值类型 | 是否校验 UTF-8 | 是否要求 Seekable |
典型场景 |
|---|---|---|---|---|
copy |
Int64(字节数) |
不适用(纯字节搬运) | 否(仅需 InputStream/OutputStream) |
流复制、文件复制 |
readString |
String |
是,非法时抛 ContentFormatException |
是 | 读取文本流剩余内容 |
readStringUnchecked |
String |
否 | 是 | 数据已确认合法的高吞吐文本读取 |
readToEnd |
Array<Byte> |
不适用(返回原始字节) | 是 | 读取整个文件/流的剩余字节 |
选型建议:
- 需要把数据"搬"到另一个流(如内存流、文件、网络流)时,使用
copy,它不要求源流可定位,适用面最广; - 需要把剩余内容作为文本处理,且对数据合法性有要求(如解析用户输入、网络报文)时,使用
readString以获得ContentFormatException的异常保护; - 在性能敏感且数据来源完全可信(例如内部协议已知编码)的场景下,才考虑在
unsafe块中使用readStringUnchecked; - 需要拿到原始字节做进一步二进制处理(如图片、加密数据),或底层需要把整个流读入内存时,使用
readToEnd。
七、常见问题与注意事项
to是标签参数:调用copy时必须写作copy(from, to: targetStream),不能省略to:标签。unsafe上下文:readStringUnchecked是unsafe函数,只能在unsafe { }块内调用;对非法 UTF-8 数据使用它不会抛出ContentFormatException,而是产生不确定的字符输出。- 泛型约束:
readString、readStringUnchecked、readToEnd均要求入参同时实现InputStream与Seekable;ByteBuffer(定义于 byte_buffer.cj)实现了IOStream & Seekable,是文档示例与日常开发中最常用的入参类型;若自定义流类型需要传入这些函数,须自行实现seek与length/remainLength属性。 readToEnd的返回值是拷贝:文档与源码均明确指出返回的是未读数据的拷贝,修改返回值不会影响流内部数据;同时注意它读取的是"从当前游标位置开始的剩余数据",如需从头读取请先seek(SeekPosition.Begin(0))。- 异常类型:文本解码相关的异常统一为
ContentFormatException(继承自Exception,源码见 content_format_exception.cj);流操作相关的底层异常则为IOException,二者定义见 io_package_exceptions.md。
八、参考文档
- 本文对应 API 文档:io_package_funcs.md(中文版:io_package_funcs.md)
std.io包总览与完整 API 列表:io_package_overview.md- 流接口定义(
InputStream/OutputStream/Seekable):io_package_interfaces.md - 函数与枚举源码实现:io_utils.cj、stream.cj
- 最常用的流实现类:byte_buffer.cj、buffered_input_stream.cj、buffered_output_stream.cj
- 实际调用
readToEnd/copy的标准库上层模块:file.cj、console_reader.cj