仓颉编程语言 std.io 流操作函数完全指南:copy、readString 与 readToEnd 实战解析

原创2026-10-13 18:19:061,349 阅读
文章标签:文档知识库

仓颉编程语言 std.io 流操作函数完全指南:copy、readString 与 readToEnd 实战解析

在仓颉编程语言(Cangjie)中,std.io 包为程序与外部设备的数据交换提供了统一的流式 I/O 抽象:输入输出流类似一条承载有序数据的通道,程序从输入流(文件、网络等)读取数据,往输出流写入数据。本文以 std.io 包函数 API 文档 为核心,系统讲解 std.io 提供的 4 个顶层流操作函数——copy、readString、readStringUnchecked、readToEnd——的签名语义、参数与返回值、异常行为及完整可运行示例,并结合 InputStream、OutputStream、Seekable 等底层接口与 ByteBuffer、BufferedInputStream、文件流等具体实现,帮助读者掌握"读取整个输入流""流间数据拷贝""字节流转字符串"这三大高频场景的推荐写法与边界约束。

函数总览:std.io 的 4 个顶层流工具函数

std.io 包在接口与类之外,还提供了一批顶层函数,专门用于处理"整流级"操作。依据 io_package_overview.md 中的 API 列表,这些函数如下:

函数签名 功能
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 获取入参中未被读取的数据

可以看出,这 4 个函数存在明确的分工:

  • readToEnd 是基础原语:把流中剩余字节一次性读出,返回 Array<Byte>,不做任何编码层面的解释;
  • readString 建立在 readToEnd 之上:把剩余字节按 UTF-8 解码为 String,并校验合法性;
  • readStringUnchecked:与 readString 语义相同,但跳过合法性检查(unsafe 上下文),追求极致性能、放弃正确性保障;
  • copy 是唯一涉及双流(输入 + 输出)的函数:相当于把"读完整流"与"写入目标流"两步合并成一个原子操作。

值得注意的是,这三个读取类函数的泛型约束都是 T <: InputStream & Seekable,即要求入参同时实现输入流接口和可移动光标接口。这与 readString、readToEnd 需要"读取全部剩余内容"的语义直接相关:函数内部需要通过 Seekable 提供的 remainLength 等属性确定待读取数据量。可支持的类型包括 ByteBuffer(实现了 IOStream & Seekable)、File(实现了 Resource & IOStream & Seekable,参见 manual 文件流章节)以及 BufferedInputStream(当被绑定的底层流满足 Seekable 约束时)。

前置基础:读懂这 4 个函数所依赖的流接口

在使用上述函数之前,需要先理解 std.io 包定义的三个核心接口(完整定义见 io_package_interfaces.md)。

InputStream:输入流

public interface InputStream {
    func read(buffer: Array<Byte>): Int64
}

read 函数将流中可读的数据写入 buffer,返回值表示本次读取的字节总数。手动循环读取可以这样写(示例源自 Basic_IO 概述):

import std.io.InputStream

main() {
    let input: InputStream = ...
    let buf = Array<Byte>(256, repeat: 0)
    while (input.read(buf) > 0) {
        println(buf)
    }
}

OutputStream:输出流

public interface OutputStream {
    func write(buffer: Array<Byte>): Unit
    func flush(): Unit
}

其中 flush() 提供默认实现(默认空实现),用于抹平"带缓冲输出流需要主动刷新"与"普通输出流直接写入"之间的 API 差异。这也是 copy 函数在写入目标流后能够统一生效的前提之一。

Seekable:可移动光标接口

public interface Seekable {
    prop length: Int64      // 返回当前流中的总数据量
    prop position: Int64    // 返回当前光标位置
    prop remainLength: Int64 // 返回当前流中未读的数据量
    func seek(sp: SeekPosition): Int64
}

seek 函数用于移动光标到指定位置,参数 sp 为 SeekPosition 枚举:

public enum SeekPosition {
    | Begin(Int64)   // 从起点开始移动
    | Current(Int64) // 从当前位置开始移动
    | End(Int64)     // 从末尾开始移动
}

seek 返回值是"流中数据的起点到移动后位置的偏移量(以字节为单位)"。位置可以超过流中数据末尾(合法),但不能位于数据头部之前(此时抛出 IOException)。ByteBuffer 对 seek 的完整行为演示见 io_package_classes.md 中的 ByteBuffer.seek 示例。

copy:在输入流与输出流之间搬运数据

函数签名与语义

public func copy(from: InputStream, to!: OutputStream): Int64
  • 功能:将一个输入流中未被读取的数据拷贝到另一个输出流中。所谓"未被读取",指的是从当前光标位置开始到流末尾的数据。
  • 参数:
    • from: InputStream —— 待读取数据的输入流;
    • to!: OutputStream —— 数据将要拷贝到的输出流(命名参数,调用时需写作 to: xxx)。
  • 返回值:Int64,拷贝数据的字节数。

copy 是 std.io 提供的唯一一个"双流操作"函数,它屏蔽了"循环读取输入流 → 写入输出流 → 刷新"的样板代码,适合流式转发场景,例如把文件内容导入内存缓冲、或把缓冲数据写入标准输出。

完整示例:ByteBuffer 之间的数据拷贝

下面的示例(源自 io_package_funcs.md)展示了 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 类的实现 可以更好地理解这个流程:ByteBuffer 同时实现了 IOStream(即 InputStream & OutputStream)与 Seekable,因此它既可以作为 copy 的数据源,也可以作为拷贝目标。示例中 sourceStream.write(sourceData) 先把字节写入缓冲,随后 copy 一次性把 13 个字节搬运到 targetStream,返回值 copiedBytes 即为搬运的字节数,随后从目标流中读回数据验证拷贝结果。

实战扩展:把文件内容拷贝到内存缓冲

由于 File 实现了 Resource & IOStream & Seekable,我们可以把 copy 用于"文件 → 内存缓冲"的场景——这是实际业务中读取小文件的最简洁写法之一:

import std.fs.*
import std.io.*

main() {
    let file = File("./data.txt", Read)
    let buf = ByteBuffer()
    let copied = copy(file, to: buf)   // 将文件中剩余内容全部拷贝进 buf
    file.close()
    println("Copied ${copied} bytes: ${String.fromUtf8(buf.bytes())}")
}

readToEnd:一次性读取流中全部剩余字节

函数签名与语义

public func readToEnd<T>(from: T): Array<Byte> where T <: InputStream & Seekable
  • 功能:获取入参中未被读取的数据,即从当前光标位置读到流末尾。
  • 参数:from: T —— 要读取数据的对象。
  • 返回值:Array<Byte> —— 未被读取的数据的拷贝。注意是拷贝,对返回数组的修改不会影响原流。

完整示例

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!

在文件读取中的应用

readToEnd 与文件流组合是"读完整文件"的最常用写法。在 file_samples.md 的示例中,将文件游标重置到文件头后,直接调用 readToEnd(file) 即可取回全部内容:

import std.fs.*
import std.io.*

main() {
    let filePath: Path = Path("./tempFile.txt")
    var file: File = File(filePath, ReadWrite)
    file.setLength(0)                    // 截断文件大小为 0
    file.write("The file was truncated to an empty file!".toArray())
    file.seek(SeekPosition.Begin(0))     // 重置游标到文件头
    let allBytes: Array<Byte> = readToEnd(file)  // 读取文件内容
    file.close()
    println("Data written newly: ${String.fromUtf8(allBytes)}")
}

运行结果:

Data written newly: The file was truncated to an empty file!

这里体现了 Seekable 约束的价值:写入后游标位于文件末尾,若不先 seek(SeekPosition.Begin(0)) 重置游标,readToEnd 读到的将是空数据;这正是读取类函数要求 T <: InputStream & Seekable 的原因。

readString 与 readStringUnchecked:字节流转字符串

readString:带 UTF-8 校验的安全读取

public func readString<T>(from: T): String where T <: InputStream & Seekable
  • 功能:读取入参中的所有剩余内容,并返回一个字符串(按 UTF-8 编码解码)。
  • 参数:from: T —— 要读取数据的对象。
  • 返回值:String —— 读取到的结果字符串。
  • 异常:当剩余字节不符合 UTF-8 编码规则时,抛出 ContentFormatException。

完整示例:

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 是 UTF-8 多字节序列的前导字节,而紧跟其后的 0x28(即 '(')是 ASCII 字节,两者拼接不成合法的 UTF-8 编码序列,因此 readString 抛出 ContentFormatException,错误信息为 Invalid unicode scalar value.。

readStringUnchecked:跳过校验的不安全读取

public unsafe func readStringUnchecked<T>(from: T): String where T <: InputStream & Seekable
  • 功能:读取入参中的所有剩余内容并返回字符串,但不会检查字符串的合法性。
  • 参数:from: T —— 要读取数据的对象。
  • 返回值:String —— 读取到的结果字符串。

与 readString 最大的不同在于两点:

  1. 函数本身声明为 public unsafe,调用时必须在 unsafe { ... } 代码块中(或处于其他 unsafe 上下文);
  2. 不做 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}")
    }
}

运行该程序,第一段输出 Read string: Hello, World!,第二段则不会抛异常,而是直接输出包含乱码/异常字符的结果。使用建议:仅在能确定流中数据必然是合法 UTF-8(例如由程序自身写入、或来自可信数据源)且对性能敏感的场景下使用 readStringUnchecked;对来源不可控的数据(如网络报文、用户文件),应优先使用带校验的 readString,并捕获 ContentFormatException 做降级处理。

与 StringReader 的对比

需要区分"函数级"与"类级"两套 API:本文的 readString/readToEnd 是 std.io 的顶层函数,而 StringReader 则是提供字符级读取能力的类(内部默认缓冲区容量 4096 字节,仅支持 UTF-8 编码,详见 io_package_classes.md 中 StringReader 一节)。StringReader 提供了 read()(按字符读取 ?Rune)、readln()(按行读取)、readUntil(读到指定字符)、lines()/runes()(迭代器)等更细粒度的接口。在 StringReader 示例 中可以看到两者可以衔接使用——先以 StringReader 做逐字符/逐行解析,需要整体内容时再取 readToEnd()。

综合实战:结合 BufferedInputStream 与文件流的完整读取方案

以上函数可以直接作用于原始流,也可以作用于带缓冲的包装流。BufferedInputStream 将其他 InputStream(如 ByteBuffer)绑定到内部缓冲区,读取时先把数据从被绑定的流读入缓冲区暂存,再从缓冲区供用户读取(默认缓冲区容量 4096,构造函数与读写行为见 io_package_classes.md 中 BufferedInputStream 一节)。当被绑定的底层流满足 Seekable 时,BufferedInputStream<T> <: Seekable,此时它同样可以作为 readToEnd、readString 的入参。

一个"带缓冲读文件 → 转字符串"的综合示例:

import std.fs.*
import std.io.*

main(): Unit {
    /* 准备测试文件 */
    let path = Path("./hello.txt")
    let f = File.create(path)
    f.write("Hello, World!".toArray())
    f.close()

    /* 带缓冲地读取文件流 */
    let file = File(path, Read)
    let buffered = BufferedInputStream(file)
    let content = readString(buffered)      // 带 UTF-8 校验,读取全部剩余内容
    println(content)
    file.close()
    remove(path)
}

运行结果:

Hello, World!

提示:copy 的目标流若为带缓冲的输出流(BufferedOutputStream),拷贝完成后需要调用 flush() 才能真正把数据写入底层流;readToEnd/readString 则只涉及读方向,不存在该问题。BufferedOutputStream 的 flush 语义与示例可参考 io_package_classes.md 中 BufferedOutputStream.flush 一节。

异常与边界行为速查

使用这 4 个函数时,需要特别留意以下边界行为(均可在上文源码示例的运行结果中得到验证):

场景 行为
流中剩余字节为合法 UTF-8 readString 正常返回字符串
流中剩余字节含非法 UTF-8 序列 readString 抛出 ContentFormatException,消息示例为 Invalid unicode scalar value.
同上,但使用 readStringUnchecked 不抛异常,产生不可期输出字符
光标不在流头部时调用读取类函数 只读取"当前光标位置 → 流末尾"的剩余数据(这正是"未被读取的数据"的含义)
位置移动到数据头部之前 seek 抛出 IOException(如 Can't move the position before the beginning of the stream.)
位置超过流末尾 合法,seek 正常返回偏移量

ContentFormatException 与 IOException 的定义分别见 io_package_exceptions.md 与 io_package_exceptions.md,两者都继承自核心库的 Exception,支持无参构造与带 message: String 构造,便于在 catch 分支中输出错误信息。

小结

std.io 的四个顶层函数构成了仓颉流式 I/O 中"整流操作"的基础能力:

  • 需要原样转发流数据时,使用 copy(from, to:),一步完成读取与写入;
  • 需要原始字节时,使用 readToEnd,返回剩余数据的拷贝;
  • 需要文本字符串且要求数据安全时,使用 readString,配合捕获 ContentFormatException 处理非法 UTF-8;
  • 仅当数据来源可信、追求极致性能时,才在 unsafe 上下文中使用 readStringUnchecked。

这 4 个函数与 ByteBuffer、BufferedInputStream、StringReader、File 等类共同构成了一套自洽的流式 I/O 体系。更完整的接口、类与异常定义可继续查阅 io_package_overview.md 以及 std.io API 目录,更多可运行示例见 io_samples 目录。

登录后查看全文
CangjieCorpus