仓颉 std.io 流函数实战指南:copy / readString / readStringUnchecked / readToEnd 全解析
仓颉 std.io 流函数实战指南:copy / readString / readStringUnchecked / readToEnd 全解析
本指南以仓颉标准库 std.io 包的四个顶层流函数为核心,系统讲解 copy、readString、readStringUnchecked、readToEnd 的签名、参数语义、返回值与异常行为,并结合仓库内接口定义与可运行示例,给出字节流拷贝、UTF-8 文本读取与剩余数据提取的完整实战方案。读完本文,你将能够熟练运用这四个函数完成流间数据搬运、流内文本解码与流尾数据回收,并理解它们对 InputStream、OutputStream、Seekable 约束背后的设计意图。
std.io 包与流式 I/O 概览
std.io 包提供程序与外部设备进行数据交换的能力。在仓颉语言中,I/O 操作被抽象为"流":输入输出流类似一个数据通道,承载一段有序数据,程序从输入流读取数据(数据来自文件、网络等),向输出流写入数据(数据通往文件、网络等)。包的整体结构见 io_package_overview.md,其中与本主题直接相关的三类基础设施为:
- 接口:
InputStream(输入流)、OutputStream(输出流)、IOStream(兼具读写能力)、Seekable(支持定位光标),定义见 io_package_interfaces.md; - 实现类:
ByteBuffer(基于内存字节数组的读写缓冲)、BufferedInputStream/BufferedOutputStream(带缓冲区包装流)、StringReader/StringWriter(字符级读写)等,定义见 io_package_classes.md; - 异常类:
ContentFormatException(字符格式异常)、IOException(IO 流异常),定义见 io_package_exceptions.md。
本文讨论的四个函数正是"流操作"与"数据读写"两条主线上的顶层工具函数,API 分类可对照 io_package_readme.json 中的"流操作""数据读写"分组。
四个函数速览
| 函数 | 签名 | 功能 |
|---|---|---|
| copy | copy(from: InputStream, to!: OutputStream): Int64 |
将一个输入流中未被读取的数据拷贝到另一个输出流中,返回拷贝字节数 |
| readString | readString<T>(from: T): String where T <: InputStream & Seekable |
读取入参中的所有剩余内容,返回字符串(校验 UTF-8 合法性) |
| readStringUnchecked | unsafe readStringUnchecked<T>(from: T): String where T <: InputStream & Seekable |
读取所有剩余内容返回字符串(不校验合法性,unsafe 函数) |
| readToEnd | readToEnd<T>(from: T): Array<Byte> where T <: InputStream & Seekable |
获取入参中未被读取的数据,返回字节数组拷贝 |
可以看到,readString 与 readToEnd 都要求类型参数 T 同时满足 InputStream & Seekable 约束,而 copy 只要求标准的输入/输出流接口。下文逐一展开。
copy:流间数据搬运
签名与语义
public func copy(from: InputStream, to!: OutputStream): Int64
from:待读取数据的输入流(InputStream);to!:数据将要拷贝到的输出流(OutputStream,命名参数,!表示必须显式传参);- 返回值:
Int64,表示实际拷贝的数据字节数。
该函数将输入流中尚未被读取的数据完整搬运到输出流中,内部实现可理解为循环执行 InputStream.read 与 OutputStream.write,直至输入流数据耗尽,因此目标流中写入的字节数与返回值一致。由于只依赖两个基础接口,任何实现了 InputStream / OutputStream 的类型(如 ByteBuffer、BufferedInputStream、BufferedOutputStream 等)都可以作为入参,这也让 copy 成为流与流之间最通用的搬运工具。
完整示例
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!
几点实战说明:
- 示例中的
ByteBuffer同时实现了IOStream与Seekable(见 io_package_classes.md),因此它既能作为copy的from,也能作为to,还能继续用read回读数据; copy的返回值(13)恰好等于"Hello, World!"的字节数,可用于校验拷贝是否完整;- 若需要将内存缓冲数据刷入真实设备流(如文件、网络),可配合
OutputStream.flush()确保数据落盘或发送完成——flush是OutputStream接口的成员方法,默认实现为空(见 io_package_interfaces.md)。
readString:安全读取 UTF-8 文本
签名与语义
public func readString<T>(from: T): String where T <: InputStream & Seekable
from:要读取数据的对象,要求同时实现InputStream与Seekable;- 返回值:
String,读取到的结果字符串; - 异常:当剩余字节不符合 UTF-8 编码规则时,抛出
ContentFormatException。
readString 一次性消费输入流中所有剩余字节,并尝试按 UTF-8 规则将其解码为仓颉 String。Seekable 约束保证了读取过程能够感知流的总长度、当前光标位置与剩余长度(length / position / remainLength 三个属性),从而准确界定"剩余内容"的边界;这也意味着传入的流必须支持定位操作。
完整示例
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 unicode scalar value.
实战要点:
- 正常数据直接解码成功;非法字节序列(示例中的
0xC3 0x28无法构成合法 UTF-8 字符)会触发ContentFormatException,异常提示信息为Invalid unicode scalar value.; ContentFormatException继承自Exception,支持无参init()与带message的init(message: String)两种构造方式(见 io_package_exceptions.md),捕获时通过e.message获取错误详情;- 建议在对文本内容合法性有要求的场景(如解析协议报文、处理用户输入文件)优先使用本函数,以便在解码阶段及时暴露数据损坏问题。
readStringUnchecked:跳过校验的高风险读取
签名与语义
public unsafe func readStringUnchecked<T>(from: T): String where T <: InputStream & Seekable
from:要读取数据的对象,同样要求InputStream & Seekable;- 返回值:
String,读取到的结果字符串; - 与
readString的区别:不会检查字符串(UTF-8)的合法性,且声明为unsafe函数。
正因为跳过合法性校验,调用该函数必须显式放在 unsafe 代码块中。它适用于"确信数据合法、追求极致性能"的场景;一旦数据中含有非法 UTF-8 字节,返回的字符串将包含不可预期的字符,且不会有异常抛出。
完整示例
import std.io.ByteBuffer
import std.io.readStringUnchecked
import std.io.ContentFormatException
main(): Unit {
let inputStream = ByteBuffer()
/* 向输入流写入数据 */
let sourceData = "Hello, World!".toArray()
inputStream.write(sourceData)
/* 使用 readString 函数读取输入流中的所有剩余内容,可以正常输出:Read string: Hello, World! */
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)
/* 使用 readString 函数读取输入流中的所有剩余内容,由于 inputStream 的第一位是不合法的UTF-8字符,所以将产生不可期的输出字符 */
unsafe {
let result = readStringUnchecked(inputStream)
println("Read string: ${result}")
}
}
实战要点:
- 调用必须包裹在
unsafe { ... }块内,否则编译无法通过; - 第二次读取时,由于首字节
0xC3是非法 UTF-8 起始字节,程序不会抛出异常,但输出内容不可预期——这正是"Unchecked"命名与unsafe标记的含义; - 选择原则:数据来源可信(如内部生成的字节流)且对吞吐敏感时可用;数据来自外部且可能被篡改/损坏时,请使用带校验的
readString。
readToEnd:提取剩余原始字节
签名与语义
public func readToEnd<T>(from: T): Array<Byte> where T <: InputStream & Seekable
from:要读取数据的对象,要求InputStream & Seekable;- 返回值:
Array<Byte>,即未被读取的数据的拷贝。
与 readString 不同,readToEnd 不做任何文本解码,原样返回剩余字节的拷贝,因此适用于二进制数据处理、需要自行控制解码时机(如指定编码)或只想移动数据而不关心内容的场景。注意返回值是"拷贝",后续对流本身的读写操作不会影响已取回的数组。
完整示例
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!
实战要点:
- 返回的
Array<Byte>可直接交给String.fromUtf8转字符串,也可用于其他二进制处理逻辑; - 结合
seek移动光标后调用readToEnd,可实现"从指定位置读取到流尾"的切片效果(见下文综合示例)。
综合实战:seek 定位 + readString / readToEnd
四个函数并非孤立存在,它们与 Seekable 接口配合可以组合出丰富用法。Seekable 接口定义如下(见 io_package_interfaces.md):
public interface Seekable {
prop length: Int64 // 当前流中的总数据量
prop position: Int64 // 当前光标位置
prop remainLength: Int64 // 当前流中未读的数据量
func seek(sp: SeekPosition): Int64 // 移动光标,返回起点到新位置的字节偏移
}
其中 SeekPosition 枚举提供三种定位基准(见 io_package_enums.md):
Begin(Int64):从数据起点开始移动;Current(Int64):从当前位置开始移动;End(Int64):从数据末尾开始移动。
仓库中的 byte_buffer.md 示例完整展示了"定位 + 读取"的组合套路:
import std.io.*
main(): Unit {
let arr1 = "test case".toArray()
let byteBuffer = ByteBuffer()
/* 将 arr1 中的数据写入到流中 */
byteBuffer.write(arr1)
/* 读取前 4 个字节的数据到 arr2 中 */
let arr2 = Array<Byte>(4, repeat: 0)
byteBuffer.read(arr2)
println(String.fromUtf8(arr2))
/* 将流的索引指向起点 */
byteBuffer.seek(Begin(0))
/* 读取流中全部数据 */
let arr3 = readToEnd(byteBuffer)
println(String.fromUtf8(arr3))
/* 将流的索引指向字母 'c' 的位置 */
byteBuffer.seek(End(-4))
/* 读取流中剩余数据 */
let str = readString(byteBuffer)
println(str)
}
运行结果:
test
test case
case
该示例体现了三个关键用法:
read按需读取定长字节(前 4 字节得到test);seek(Begin(0))将光标回退到起点后,readToEnd取回全部数据(test case);seek(End(-4))将光标定位到距末尾 4 字节处(字母c的位置),readString解码剩余内容得到case——注意seek允许目标位置超过流末尾,但不允许位于数据头部之前(越界会抛IOException,见 io_package_classes.md)。
类似的定位读取模式还出现在 io_samples/string_reader.md 中——StringReader 类自身提供了 read、readln、readUntil、readToEnd 等字符级读取方法,适合逐字符/逐行处理文本流的场景,可作为包级 readToEnd 的补充手段。
异常与约束小结
| 函数 | 类型约束 | 可能异常 | 说明 |
|---|---|---|---|
copy |
InputStream / OutputStream |
视底层流实现而定 | 循环读写,返回拷贝字节数 |
readString |
InputStream & Seekable |
ContentFormatException |
校验 UTF-8,非法字节抛异常 |
readStringUnchecked |
InputStream & Seekable |
无(行为不可预期) | 需 unsafe 块包裹,跳过校验 |
readToEnd |
InputStream & Seekable |
视底层流实现而定 | 返回剩余字节拷贝,不解码 |
ContentFormatException与IOException均继承自Exception,可通过message获取错误详情(见 io_package_exceptions.md);- 若底层流实现有异常(如
ByteBuffer.read对空缓冲区抛IllegalArgumentException),copy/readToEnd也可能向上传播对应异常,实际行为以具体流实现为准; - 需要缓冲包装时,可先用
BufferedInputStream/BufferedOutputStream包装底层流再交给这些函数,以减少与底层设备的交互次数;包装类默认缓冲区容量为 4096,也支持自定义容量或复用缓冲区(见 io_package_classes.md)。
综上,copy 解决"流到流"的搬运问题,readString / readStringUnchecked 解决"流到文本"的解码问题(区别在于是否校验 UTF-8),readToEnd 解决"流到原始字节"的回收问题。将这四个函数与 Seekable 定位能力、ByteBuffer 内存流结合,即可覆盖仓颉标准库中最常见的流式 I/O 数据处理需求。进一步可参考 io_samples 目录下的完整示例与 readme.md 的 API 总览进行扩展学习。