仓颉标准库 std.io 实用函数指南:copy、readString、readStringUnchecked 与 readToEnd 的用法与实现原理

原创2026-10-14 19:31:521,716 阅读
文章标签:编程语言语言运行时标准库内存管理并发编程OpenHarmony

仓颉标准库 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)
    }
}

关键步骤:

  1. 利用 Seekable.remainLength 属性精确获知当前游标到流末尾的剩余字节数,一次性分配等长缓冲区;
  2. 调用 from.read(data) 把剩余数据全部读入;
  3. 通过 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。

七、常见问题与注意事项

  1. to 是标签参数:调用 copy 时必须写作 copy(from, to: targetStream),不能省略 to: 标签。
  2. unsafe 上下文:readStringUnchecked 是 unsafe 函数,只能在 unsafe { } 块内调用;对非法 UTF-8 数据使用它不会抛出 ContentFormatException,而是产生不确定的字符输出。
  3. 泛型约束:readString、readStringUnchecked、readToEnd 均要求入参同时实现 InputStream 与 Seekable;ByteBuffer(定义于 byte_buffer.cj)实现了 IOStream & Seekable,是文档示例与日常开发中最常用的入参类型;若自定义流类型需要传入这些函数,须自行实现 seek 与 length/remainLength 属性。
  4. readToEnd 的返回值是拷贝:文档与源码均明确指出返回的是未读数据的拷贝,修改返回值不会影响流内部数据;同时注意它读取的是"从当前游标位置开始的剩余数据",如需从头读取请先 seek(SeekPosition.Begin(0))。
  5. 异常类型:文本解码相关的异常统一为 ContentFormatException(继承自 Exception,源码见 content_format_exception.cj);流操作相关的底层异常则为 IOException,二者定义见 io_package_exceptions.md。

八、参考文档

登录后查看全文
cangjie_runtime