仓颉 std.io 流函数实战指南:copy / readString / readStringUnchecked / readToEnd 全解析

原创2026-10-14 13:34:101,663 阅读
文章标签:人工智能AI 技能文档开发工具

仓颉 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

该示例体现了三个关键用法:

  1. read 按需读取定长字节(前 4 字节得到 test);
  2. seek(Begin(0)) 将光标回退到起点后,readToEnd 取回全部数据(test case);
  3. 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 总览进行扩展学习。

登录后查看全文
DocAgent