仓颉编程语言扩展库概述

仓颉编程语言扩展库（stdx）包含若干包，提供相关功能。

标准库为开发者提供了最通用的 API，而扩展库则专注于某一领域。如 compress 包提供压缩与解压缩能力，crypto 包提供加解密相关能力，net 包则专注于提供高效的网络协议解析和网络通信能力。

说明：

目前，官方提供的扩展库不随仓颉编译器、工具链一起发布，需要用户单独下载。

平台支持说明

扩展库提供的 API 支持在如下操作系统上运行：

注意：

部分 API 不支持在特定的操作系统运行，详情请参见对应 API 描述。

使用指导

仓颉编程语言扩展库 stdx 二进制包包含静态（static）和 动态 （dynamic） 两部分，请按需引用。

二进制产物结构

二进制包解压出来的目录包含 dynamic 和 static 两个目录：

dynamic/stdx 是动态产物，包含动态文件、cjo、bc 文件。

static/stdx 是静态产物，包含静态文件、cjo、bc 文件。

使用 Openssl 静态库链接

假设存放 Openssl 静态库的目录为 STATIC_OPENSSL_DIR，则命令如下。

# GNU ld64
cjc -L $STATIC_OPENSSL_DIR --link-option "-Bstatic" --link-option "--whole-archive" -lssl -lcrypto --link-option "--no-whole-archive" --link-option "-Bdynamic" main.cj

# Apple ld64
cjc -L $STATIC_OPENSSL_DIR --link-option "-force_load" --link-option "$STATIC_OPENSSL_DIR/libssl.a" --link-option "-force_load" --link-option "$STATIC_OPENSSL_DIR/libcrypto.a" main.cj

包依赖

代码中导入上述包，用 cjc 命令去编译代码，需要严格按照上述包的依赖的顺序去链接。 如果是用 cjpm 则无需关注。

如果使用静态库，在导入 crypto 和 net 库时，由于需要依赖系统符号，所以 Windows 操作系统 需要额外添加 -lcrypt32，Linux 操作系统 需要额外添加 -ldl。

cjc 使用命令示例

cjc 的介绍和编译请查看 cangjie 用户手册

import stdx.actors.*
import stdx.actors.macros.*
import stdx.aspectCJ.*
import stdx.compress.zlib.*
import stdx.crypto.crypto.*
import stdx.crypto.digest.*
import stdx.crypto.keys.*
import stdx.crypto.x509.*
import stdx.effect.*
import stdx.encoding.hex.*
import stdx.encoding.base64.*
import stdx.encoding.json.*
import stdx.encoding.url.*
import stdx.encoding.json.stream.*
import stdx.net.tls.*
import stdx.net.http.*
import stdx.log.*
import stdx.logger.*
import stdx.syntax.*
import stdx.serialization.serialization.*
main() {
    0
}

Linux 和 mac 的编译命令：

cjc main.cj -L $CANGJIE_STDX_PATH -lstdx.actors -lstdx.aspectCJ -lstdx.effect -lstdx.encoding.json -lstdx.serialization.serialization -lstdx.net.http -lstdx.net.tls -lstdx.net.tls.common -lstdx.logger -lstdx.log -lstdx.encoding.url -lstdx.encoding.json.stream -lstdx.crypto.kit -lstdx.crypto.keys -lstdx.crypto.x509 -lstdx.encoding.hex -lstdx.crypto.crypto -lstdx.crypto.digest -lstdx.crypto.common -lstdx.encoding.base64 -lstdx.compress.zlib -lstdx.compress -lstdx.syntax -lstdx.syntaxFFI -ldl --import-path $CANGJIE_STDX_PATH -o main.out

windows 编译命令：

cjc main.cj -L $CANGJIE_STDX_PATH -lstdx.actors -lstdx.aspectCJ -lstdx.effect -lstdx.encoding.json -lstdx.serialization.serialization -lstdx.net.http -lstdx.net.tls -lstdx.net.tls.common -lstdx.logger -lstdx.log -lstdx.encoding.url -lstdx.encoding.json.stream -lstdx.crypto.kit -lstdx.crypto.keys -lstdx.crypto.x509 -lstdx.encoding.hex -lstdx.crypto.crypto -lstdx.crypto.digest -lstdx.crypto.common -lstdx.encoding.base64 -lstdx.compress.zlib -lstdx.compress -lstdx.syntax -lstdx.syntaxFFI -lcrypt32 --import-path $CANGJIE_STDX_PATH -o main.out

CANGJIE_STDX_PATH 是设置的 stdx 路径。

例如在 linux 系统中设置：

export CANGJIE_STDX_PATH=/target/linux_x86_64_cjnative/dynamic/stdx

运行前 Linux 操作系统需要在 LD_LIBRARY_PATH 中设置扩展库的路径，Windows 操作系统需要在 PATH 中设置扩展库的路径，macOS 操作系统需要在 DYLD_LIBRARY_PATH 中设置扩展库的路径。

例如在 linux 系统中设置：

export LD_LIBRARY_PATH=/target/linux_x86_64_cjnative/dynamic/stdx:$LD_LIBRARY_PATH

cjpm 使用示例

cjpm 的介绍和使用请查看 cjpm 手册。

cjpm.toml 增加如下配置：

[target.x86_64-unknown-linux-gnu]
  [target.x86_64-unknown-linux-gnu.bin-dependencies]
    path-option = ["${CANGJIE_STDX_PATH}"]

上面配置中 x86_64-unknown-linux-gnu 表示的是系统架构信息，需要通过 cjc -v 获取，并替换成自己获取的系统架构信息。 CANGJIE_STDX_PATH 是设置的 stdx 路径。

包列表

stdx 含若干包，提供了丰富的扩展功能：

扩展库源码集成指南

两种集成方式

stdx 有两种源码集成方式：git 源码依赖和本地源码依赖。

git 源码依赖

在工程的 cjpm.toml 文件中，新增如下源码依赖配置：

[dependencies]
  stdx = { git = "https://gitcode.com/Cangjie/cangjie_stdx.git", branch = "dev", output-type = "dynamic" }

在工程的 cjpm.toml 文件所在目录，执行 cjpm update 命令即可同步更新本仓源码。

本地源码依赖

如果不希望通过 git 依赖本仓，开发者可以直接下载本仓库分支的全量源码（包括本仓库的 cjpm.toml 配置文件），然后在工程的 cjpm.toml 文件中添加本地模块依赖。

[dependencies]
  stdx = { path = "/path/to/cangjie_stdx", output-type="dynamic"}

完成本地模块依赖添加之后，即可在项目中使用 stdx。

包范围

目前源码依赖集成的 stdx 不包含 aspectCJ 和 syntax，并且在 Windows 平台上没有 fuzz 包。

支持平台

• Linux
• macOs
• Windows
• 交叉编译 OpenHarmony

交叉编译 OpenHarmony

Linux 和 macOS 平台交叉编译 OpenHarmony 需要配置交叉编译工具链的环境变量（非 DevEco Studio 项目），请参考编译 ohos-x86_64、ohos-aarch64 工具链

1. OHOS_TOOLCHAIN_PATH (编译工具链中 Clang/LLVM 编译器的二进制目录, 如 /opt/buildtools/ohos_root/prebuilts/clang/ohos/linux-x86_64/llvm/bin)

2. OHOS_SYSROOT_PATH (OpenHarmony 系统头文件目录，如 /opt/buildtools/ohos_root/out/sdk/obj/third_party/musl/sysroot)

DevEco Studio 自带 OpenHarmony 交叉编译工具链，无需设置上面的环境变量。

交叉编译命令：cjpm build --target aarch64-linux-ohos 或者 cjpm build --target x86_64-linux-ohos

注意：

部分版本 DevEco Studio 可能缺少 openssl 头文件， 构建过程中报错找不到 openssl 头文件，需要准备 openssl 头文件放入 DevEco Studio 的 sysroot 下。

• Windows 常见路径如 C:\Program Files\Huawei\DevEco Studio\sdk\default\openharmony\native\sysroot\usr\include\openssl。

• macOS 常见路径如 /Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/sysroot/usr/include/openssl。

依赖

由于 stdx 需要拉取并编译外部开源 C 库，也有涉及 C 互操作的包，目前构建有一些额外依赖（使用 DevEco Studio 除外，DevEco Studio 自带了下面的工具），提前准备好下面的依赖，同时配置好环境变量。

• python: > 3.7
• cmake: >= 3.16.5 且 < 4
• ninja: >1.10
• openssl: >= 3 （需要配置环境变量 OPENSSL_ROOT_DIR，指向 OpenSSL 安装的根目录）
• clang: >= 15.0.4 且 < 16 (Linux or macOS)
• mingw-w64 (Windows) 下载地址

stdx.actors

功能介绍

Actor 模型概述

Actor 模型是一种并发编程模型，旨在简化并发任务的处理。

在这个模型中，actor 是基本的并发单元，具备以下特征：

• 每个 actor 都拥有独立的仓颉线程。
• 每个 actor 都拥有自己的成员变量。
• 这些变量只能由该 actor 的线程进行访问和修改。
• Actor 包含一种特殊的成员函数，称为 "接收函数"。当接收函数被调用时，调用请求会被加入到一个队列中，并在该 actor 的线程上按顺序执行。
• 一旦没有任何引用指向该 actor，且所有的接收函数都已执行完毕，它就可以被系统回收。

注意：

Actor 模型的第三项特性还没有被语言强制实施，所以 actor 的成员变量还不具备完全的并发安全性。未来，类型系统可以解决这个问题，确保成员变量的并发安全。

Actor 的主要应用场景是在多线程环境下对同一个对象进行访问和修改。例如，一个银行账户的对象能会被多个线程同时访问，如执行存款或取款。在缺乏任何同步机制的情况下，可能会导致数据竞争：

public class Account {
    public Account(
        private let name: String,
        private var balance: Float64
    ) {}

    public func deposit(amount: Float64): Unit {
        balance += amount
    }

    public func withdraw(amount: Float64): Unit {
        if (balance < amount) {
            throw BalanceNotEnoughException(name)
        }
        balance -= amount
    }

    public func getBalance(): Float64 {
        balance
    }
}

在多线程环境下同时访问和修改该对象，可能会导致数据竞争：

let account = Account("Steven", 0.0)
spawn {
    account.deposit(1000.0)
}
spawn {
    account.withdraw(2000.0)
}

正确使用 Actor 模型可以使并发编程变得更加简洁和高效。

Actor 的声明

引用上述银行账户的例子，为了避免线程安全问题，我们可以使用 Actor 模型来设计一个专门处理账户操作的 actor。

首先，我们可以使用 @Actor 注解将 Account 类标记为一个 actor。然后，使用 @Receiver 注解来标记 deposit ， withdraw 和 getBalance 函数：

@Actor
public class Account {
    public Account(
        private let name: String,
        private var balance: Float64
    ) {}

    @Receiver
    public func deposit(amount: Float64): Unit {
        balance += amount
    }

    @Receiver
    public func withdraw(amount: Float64): Unit {
        if (balance < amount) {
            throw BalanceNotEnoughException(name)
        }
        balance -= amount
    }

    @Receiver
    public func getBalance(): Float64 {
        balance
    }
}

对于 @Actor 和 @Receiver 的使用规则跟限制，请参考对应的文档。

我们可以通过调用该类的构造函数来创建一个 Account 实例，例如：

let stevenAccount: Account = Account("Steven", 0.0)

在创建 Account 实例的同时，系统会自动创建一个与该实例关联的仓颉线程。

调用接收函数

与普通函数不同，接收函数的调用是异步的，并返回一个 ActorFuture<T> 对象。通过该对象，可以等待接收函数执行完成并获取结果，其中 T 是该接收函数的返回类型。例如，调用 getBalance 时，将返回一个 ActorFuture<Float64> 的对象：

let fut: ActorFuture<Float64> = stevenAccount.getBalance()

当接收函数被调用时，调用请求会被加入到一个队列中，并在该 actor 的附属线程上按顺序执行。

随后，我们可以通过调用 ActorFuture<T> 的 get 函数来阻塞当前线程，直到 steven.getBalance() 函数执行完成，并返回一个 T 类型的值。

let stevenBalance: Float64 = fut.get()

stevenBalance 的值将取决于 steven.getBalance() 执行时成员变量 balance 的值。

在多线程环境下，虽然接收函数可能同时被调用，但由于同一个 actor 实例的接收函数是顺序执行的，不会发生交叉执行。因此，我们可以将它们视为原子操作（atomic function），从而避免数据竞争。

let account = Account("Steven", 0.0)
spawn {
    account.deposit(1000.0)
}
spawn {
    account.withdraw(2000.0)
}

注意：

目前 actor 的成员变量还不具备完全的并发安全性。例如在以下的例子当中，public 的成员变量还是可以被直接在外部访问与修改：

@Actor
public class MyActor {
    public var x: Int64 = 0
}

let myActor = MyActor()
spawn {
    myActor.x = 2
}
spawn {
    myActor.x = 3
}

未来，一个新的类型系统可以解决这个问题，确保成员变量的并发安全。

接收函数的执行顺序

在同一线程对同一个 actor 调用接收函数时，这些函数将按调用的顺序执行。例如：

func foo() {
    let account = Account("Federico", 0.0)
    account.deposit(1000.0)
    account.withdraw(500.0)
    let fut = account.getBalance()
    println(fut.get())
}

在没有其他线程的情况下，这段代码必然会输出以下内容，并不会出现 account.withdraw(500.0) 先于 account.deposit(1000.0) 执行的情况：

500.0

不同线程对同一 actor 的调用将不保证执行顺序，比如：

let account = Account("Steven", 0.0)
spawn {
    account.deposit(1000.0)
}
spawn {
    account.withdraw(500.0)
}

以下都是可能出现的执行顺序：

account.deposit(1000.0)
account.withdraw(500.0)

account.withdraw(500.0)
account.deposit(1000.0)

接收函数抛出的异常

接收函数抛出的任何未捕获的异常或错误都将传播到对应的 ActorFuture<T> 对象，类似于 spawn 的处理。

继续应用 Account 的例子，在 withdraw(amount) 函数里面，如果户口里面的 balance 不够会抛出 BalanceNotEnoughException 异常：

@Receiver
public func withdraw(amount: Float64): Unit {
    if (balance < amount) {
        throw BalanceNotEnoughException(name)
    }
    balance -= amount
}

抛出的异常会被传递到对应的 ActorFuture 对象，调用它的 get 函数时会抛出同一个异常：

let account = Account("Hamid", 0.0)
let fut: ActorFuture<Unit> = account.withdraw(500.0)
try {
    let res = fut.get()
} catch (e: BalanceNotEnoughException) {
    println("fut.get() throws BalanceNotEnoughException")
    println()
    e.printStackTrace()
}

由于 account.withdraw(500.0) 抛出了 BalanceNotEnoughException，因此 fut.get() 也会抛出相同的异常。以下是输出内容：

fut.get() throws BalanceNotEnoughException

An exception has occurred:
Exception: Balance for account Hamid is not enough.
         at default.BalanceNotEnoughException::init(std.core::String)(/home/.../main.cj:6)
         at default.Account::withdraw::lambda.0()(/home/.../main.cj:25)
         at stdx.actors.ActorFuture<...>::execute()(stdx/actors/actor_future.cj:90)
         at stdx.actors.SequentialDispatcher::startActorLoop::lambda.0()(stdx/actors/actors.cj:46)

当一个接收函数抛出异常后， 该 actor 的附属线程会继续执行下一个在队列里面的接收函数调用：

let account = Account("Hamid", 0.0)
let fut: ActorFuture<Unit> = account.withdraw(500.0)
let fut2: ActorFuture<Float64> = account.getBalance()
try {
    let res = fut.get()
} catch (e: BalanceNotEnoughException) {
    println("fut.get() throws BalanceNotEnoughException")
    println()
    e.printStackTrace()
    println()
}
let res = fut2.get()
println("Balance = ${res}")

在该 actor 的线程里面， account.withdraw(500.0) 执行并抛出异常后，线程会继续执行 account.getBalance()。以下是输出内容：

fut.get() throws BalanceNotEnoughException

An exception has occurred:
Exception: Balance for account Hamid is not enough.
         at default.BalanceNotEnoughException::init(std.core::String)(/home/.../main.cj:6)
         at default.Account::withdraw::lambda.0()(/home/.../main.cj:25)
         at stdx.actors.ActorFuture<...>::execute()(stdx/actors/actor_future.cj:90)
         at stdx.actors.SequentialDispatcher::startActorLoop::lambda.0()(stdx/actors/actors.cj:46)

Balance = 0.0

Actor 的生命周期

当没有任何引用指向该 actor，并且没有待执行的接收函数调用时，该 actor 就可以被运行时回收：

func test(): Unit {
    let account = Account("Ziming", 0.0)
    let fut = account.deposit(5.0)
    println(fut.get())
}

func bar() {
    test()
    // account 有可能被回收
}

在 test() 返回后，由于已经没有对 account 的引用，且没有待执行的接收函数调用（因为我们在 test() 内部已经等待了 account.deposit(5.0) 的结果），因此 account 所指向的 actor 及其附属仓颉线程将会被系统回收。

接收函数的优先值

用户可以为接收函数指定优先级，从而使高优先级的接收函数有可能在低优先级的接收函数之前执行。

首先，用户需要通过在 @Actor 宏上加上 enableReceiverPriority: true 选项，用于启用 actor 接收函数之间的优先级。例如：

@Actor[enableReceiverPriority: true]
public class Account {
    public Account(
        private let name: String,
        private var balance: Float64
    ) {}
}

如果 enableReceiverPriority 设置为 false 或者 @Actor 宏没有这个选项，那么意味着接收函数的优先级未启用。

接下来我们可以为每个接收函数指定默认的优先级级别，目前我们提供了 10 个优先级级别，用 1 到 10 的整数表示；数字越大，优先级越高，如果未设置 priority 选项，则默认值为 5：

@Actor[enableReceiverPriority: true]
public class Account {
    ...

    @Receiver[priority: 10]
    public func deposit(amount: Float64): Unit {
        balance += amount
    }

    @Receiver[priority: 1]
    public func withdraw(amount: Float64): Unit {
        if (balance < amount) {
            throw BalanceNotEnoughException(name)
        }
        balance -= amount
    }

    @Receiver
    public func getBalance(): Float64 {
        balance
    }
}

通过提高 deposit 的优先级并降低 withdraw 的优先级，当同时有大量 deposit 和 withdraw 调用时，deposit 将优先执行，从而减少 withdraw 抛出 BalanceNotEnoughException 的机会。

此外，在调用接收函数时，可以通过在参数列表末尾传递一个额外的命名参数 priority 来重载该函数的优先级：

func foo(account: Account) {
    account.getBalance()
    account.withdraw(100.0, priority: 10)
}

account.withdraw(100.0, priority: 10) 的调用将有可能被优先执行。

死锁

最后请注意，在 actor 的接收函数中调用 fut.get() 可能会导致死锁，例如：

@Actor
class MyActor {
    @Receiver
    func foo(): Int64 {
        let fut = this.bar()
        // this will deadlock
        fut.get()
    }

    @Receiver
    func bar(): Int64 {
        42
    }
}

调用 this.bar() 会将该接收函数添加到队列末尾。然而在一个接收函数里面阻塞会导致 actor 的线程阻塞，所以 bar() 永远不会被执行。所以在 foo() 里面执行 fut.get() 会永远阻塞。

完整例子

package actorDemo

import std.collection.ArrayList

import stdx.actors.*
import stdx.actors.macros.*

@Actor[enableReceiverPriority: true]
public class Account {
    public Account(
        private let name: String,
        private var balance: Float64
    ) {}

    @Receiver[priority: 10]
    public func deposit(amount: Float64): Unit {
        balance += amount
    }

    @Receiver[priority: 1]
    public func withdraw(amount: Float64): Unit {
        if (balance < amount) {
            throw BalanceNotEnoughException(name)
        }
        balance -= amount
    }

    @Receiver
    public func getBalance(): Float64 {
        balance
    }
}

public class BalanceNotEnoughException <: Exception {
    public init(name: String) {
        super("Balance for account ${name} is not enough.")
    }
}

main() {
    let account = Account("Steven", 0.0)
    let futs = ArrayList<Future<Unit>>()
    for (_ in 0..100) {
        let fut1 = spawn {
            for (_ in 0..10) {
                account.deposit(1000.0)
            }
        }
        let fut2 = spawn {
            for (_ in 0..10) {
                account.withdraw(1000.0)
            }
        }
        futs.add(fut1)
        futs.add(fut2)
    }
    for (f in futs) {
        f.get()
    }
    println("Balance: ${account.getBalance().get()}")
}

API 列表

类

类

class ActorFuture

public class ActorFuture<T> {}

功能：提交给一个 Actor 的闭包的待定结果。

func get()

public func get(): T

功能：阻塞当前线程，直到闭包完成。如果闭包抛出异常或错误，此方法将抛出相同的异常或错误。

返回值：

• T - 对应的闭包的计算结果。

示例：

import stdx.actors.*
import stdx.actors.macros.*

@Actor
public class Counter {
    private var cnt: Int64 = 42

    @Receiver
    public func getCnt(): Int64 {
        cnt
    }
}

main() {
    let counter: Counter = Counter()
    let fut: ActorFuture<Int64> = counter.getCnt()
    let res: Int64 = fut.get()
    println(res)
}

运行结果：

42

func get(Duration)

public func get(timeout: Duration): Option<T>

功能：阻塞当前线程，直到指定的时间段结束或结果准备好。如果结果已经准备好，它将返回结果，否则它将返回 None。如果结果是异常或错误，此方法将抛出相同的异常或错误。如果指定的超时时间为零，则表示没有时间限制。

参数：

• timeout: Duration - 它应该等待的最大时间。

返回值：

• Option<T> - 如果结果在指定超时时间内未准备好，则返回 None，否则返回结果值。

示例：

import stdx.actors.*
import stdx.actors.macros.*

@Actor
public class Counter {
    private var cnt: Int64 = 42

    @Receiver
    public func getCnt(): Int64 {
        cnt
    }
}

main() {
    let counter: Counter = Counter()
    let fut: ActorFuture<Int64> = counter.getCnt()
    let res: Option<Int64> = fut.get(Duration.second)
    println(res)
}

运行结果：

Some(42)

func tryGet()

public func tryGet(): Option<T>

功能：如果结果已经准备好，则立即返回结果；否则返回 None。如果结果是异常或错误，此方法将抛出相同的异常或错误。

返回值：

• Option<T> - 如果结果尚未准备好，则返回 None，否则返回结果值。

示例：

import stdx.actors.*
import stdx.actors.macros.*

@Actor
public class Counter {
    private var cnt: Int64 = 42

    @Receiver
    public func getCnt(): Int64 {
        cnt
    }
}

main() {
    let counter: Counter = Counter()
    let fut: ActorFuture<Int64> = counter.getCnt()
    fut.get()
    let res: Option<Int64> = fut.tryGet()
    println(res)
}

运行结果：

Some(42)

class SequentialDispatcher

public class SequentialDispatcher {
  public init(enableReceiverPriorty!: Bool)
}

功能：一个 SequentialDispatcher 实例代表了一个仓颉的线程，用户可以向一个 SequentialDispatcher 实例提交闭包，这些闭包会在一个仓颉线程上排队执行。

通常用户不需要直接使用这个类，而是应该使用 @Actor 宏。

init(Bool)

public init(enableReceiverPriorty!: Bool)

功能：创建一个 SequentialDispatcher 实例并启动 SequentialDispatcher 的线程来处理用户提交的闭包。

参数：

• enableReceiverPriorty!: Bool - 设置为 true 时提供提供优先值功能，让优先值高的闭包优先执行。

func post<T>(() -> T, Int64)

public func post<T>(task: () -> T, priority!: Int64 = 5): ActorFuture<T>

功能：将一个闭包提交给 dispatcher，该闭包将在 dispatcher 线程上排队并执行。此方法返回一个 ActorFuture<T>，表示闭包的待定结果。如果这个 dispatcher 在构建时如果设置 enableReceiverPriorty 为 true，优先值高的闭包会优先执行；如果设置 enableReceiverPriorty 为 false 时，priority 值将不起作用。

参数：

• task: () -> T - 提交到 actor 的闭包。
• priority!: Int64 - 提交任务的优先级，1 <= priority <= 10，默认为 5。

返回值：

• ActorFuture<T> - 该对象可用于获取闭包的计算结果。

异常：

• IllegalArgumentException - 如果优先级参数 priority 小于 1 或大于 10，则会抛出此异常。

示例：

import stdx.actors.*

main() {
  let seqDispatcher = SequentialDispatcher()
  let fut: ActorFuture<Int64> = seqDispatcher.post<Int64>({ => 40 + 2 })
  let res: Int64 = fut.get()
  println(res)
}

运行结果：

42

示例：

import stdx.actors.*

main() {
  let seqDispatcher = SequentialDispatcher(enableReceiverPriority: true)
  let fut: ActorFuture<Int64> = seqDispatcher.post<Int64>({ => 40 + 2 }, priority: 5)
  let res: Int64 = fut.get()
  println(res)
}

运行结果：

42

stdx.actors.macros

功能介绍

该包为用户提供了一个 @Actor 宏，用于声明一个 actor；以及一个 @Receiver 宏，用于声明一个接收函数。

API 列表

宏

宏

@Actor 宏

public macro Actor(input: Tokens): Tokens

public macro Actor(options: Tokens, input: Tokens): Tokens

功能：把一个 class 类变成一个 actor。

说明：

@Actor 宏的使用有以下限制：

• 它只能用于类；
• 被标注的类不能是 abstract/open/sealed。

违反这些限制会导致宏展开时出现编译错误。

选项：Actor 宏接受以 opt1: value1, opt2: value2 形式的选项列表。例如，

@Actor[option1: value1, option2: value2]

目前可用的选项只有 enableReceiverPriority: value - 指定是否启用接收函数之间的优先级。提供的值必须是 boolean 的字面量，即 true 或 false。如果没有指定此选项，默认为 false。

所有选项只能出现一次，否则在宏展开期间将抛出错误。

示例：

import stdx.actors.*
import stdx.actors.macros.*

@Actor
public class Counter <: ToString {
    private var cnt: Int64 = 0

    public func toString(): String {
        "This is a counter."
    }
}

main() {
    let counter: Counter = Counter()
    println(counter)
}

运行结果：

This is a counter.

@Receiver 宏

public macro Receiver(input: Tokens): Tokens

public macro Receiver(options: Tokens, input: Tokens): Tokens

功能：把一个成员函数变成接收函数。

说明：

@Receiver 宏的使用有以下限制：

• 只能在 @Actor 宏内部使用；
• 被注解的方法必须是非 static 的；
• 被注解的方法必须具有明确声明的返回类型；
• 被注解的方法不能覆盖接口方法，即不能被 override 修饰；
• 如果被注解方法没有显式的 override 修饰符但实际上覆盖了接口方法，则会在宏展开后会导致编译错误；
• 被注解的方法不能是 open 的；
• 当在 @Actor 宏内部使用且 enableReceiverPriority 设置为 true 时，被注解的方法不能具有名为 priority 的参数。

违反这些限制会导致宏展开时出现编译错误。

选项：Receiver 宏接受以 opt1: value1, opt2: value2 形式的选项列表。例如，

@Receiver[option1: value1, option2: value2]

目前可用的选项只有 priority: value - 指定接收函数的默认优先级级别。提供的值必须是介于 1 到 10 之间的整数字面量；否则，在宏展开期间将抛出错误。此选项仅在外层 @Actor 宏具有 enableReceiverPriority: true 选项时才可用。

所有选项只能出现一次，否则在宏展开期间将抛出错误。

示例：

import stdx.actors.*
import stdx.actors.macros.*

@Actor
public class Counter <: ToString {
    private var cnt: Int64 = 0

    @Receiver
    public func inc(): Unit {
        cnt++
    }

    @Receiver
    public func getCnt(): Int64 {
        cnt
    }

    public func toString(): String {
        "This is a counter: cnt = ${getCnt().get()}."
    }
}

main() {
    let counter: Counter = Counter()
    counter.inc()
    counter.inc()
    println(counter)
}

运行结果：

This is a counter: cnt = 2.

stdx.aspectCJ

功能介绍

stdx.aspectCJ 包提供了仓颉中面向切面编程（Aspect Oriented Programming, AOP）的相关注解，配合 libcollect-aspects 和 libwave-aspects 两个编译插件使用，可以对函数进行前后插桩以及替换实现。

API 列表

类

规格和使用

规格

标注范围：

• 注解暂不支持标注在泛型函数上，也不支持织入泛型函数；
• 注解只允许标注在 public 函数上；
• 注解可以标注在全局函数上，支持：
  • 织入另一个全局函数，
  • 织入另一个实例成员函数，
  • 织入另一个静态成员函数；
• 注解可以标注在静态成员函数上，支持：
  • 织入另一个全局函数，
  • 织入另一个实例成员函数，
  • 织入另一个静态成员函数；
• 注解可以标注在实例成员函数上，支持：
  • 织入同类型的其它实例成员函数。

全局变量定义约束：

• 定义了切面的包中，只允许定义基本类型（整型、浮点、Rune、Bool）字面值的全局变量，否则编译报错；若需要使用超规格的全局变量，需要将其定义在另外的包再导入使用，以避免在编译后可能产生的循环依赖；

形参约束：

• 被标注 @InsertAtEntry/@InsertAtExit 的函数，其返回类型只能是 Unit；
• 被标注 @ReplaceFuncBody 的函数，其返回类型应和被织入的函数的返回类型相同；
• 被标注 @InsertAtEntry/@InsertAtExit/@ReplaceFuncBody 的函数如果没有形参，那么其织入后总是被无参调用 ；
• 被标注 @InsertAtEntry/@InsertAtExit/@ReplaceFuncBody 的函数如果有形参，其形参列表应和被织入函数的源码形参列表相同，此外：
  • 特别地，如果被织入的函数是实例成员函数，那么需要将 this 参数显式地写在形参中；
  • 对于被标注 @ReplaceFuncBody 的函数，需要额外添加一个形参，形参的类型和被织入的函数相同，该形参表示被织入函数原始版本的闭包。

使用

要实现 AOP 的完整功能，除了使用上述的注解类来定义切面，还需要两个编译插件：

• libcollect-aspects.so(.dll/.dylib)
• libwave-aspects.so(.dll/.dylib)

这两个编译插件以动态库的形式在 stdx.aspectCJ 中提供，不同平台提供不同版本。

应先使用 libcollect-aspects，在编译时收集所有切面、连接点信息；再使用 libwave-aspects 进行二次编译，把之前收集的切面织入到连接点。

类

class InsertAtEntry

public class InsertAtEntry {
    public const init(packageName!: String, className!: String, methodName!: String, isStatic!: Bool, funcTypeStr!: String, recursive!: Bool)
}

功能：在注解所指定方法的入口，织入对被注解标注的函数的调用。注解所指定的方法和被注解标注的函数，需满足规格限制。

示例：

参考InsertAtEntry 示例教程了解具体调用流程。

const init(String, String, String, Bool, String, Bool)

public const init(packageName!: String, className!: String, methodName!: String, isStatic!: Bool, funcTypeStr!: String, recursive!: Bool)

功能：创建 InsertAtEntry 对象。

示例：

参考InsertAtEntry 示例教程了解具体调用流程。

参数：

• packageName!: String - 被织入的函数的所属包名，如 "default", "std.core"；
• className!: String - 如果被织入的函数是成员函数，则为函数所属类名；如果被织入的函数是全局函数，则为空；
• methodName!: String - 被织入的函数名称，如 "foo"；
• isStatic!: Bool - 被织入的函数是否为静态成员函数；
• funcTypeStr!: String - 被织入的函数的类型字符串，不包括空格。对于自定义类型，类型定义所在的包名不可省略，且和类型名之间使用 . 分隔。不需要包括隐式的 this 形参的类型。如 "(Int64,std.core.Object)->Unit"；
• recursive!: Bool - 当被织入的函数是成员函数时，表示是否对子类里的函数 override 版本也做织入；否则该字段应填 false。

class InsertAtExit

public class InsertAtExit {
    public const init(packageName!: String, className!: String, methodName!: String, isStatic!: Bool, funcTypeStr!: String, recursive!: Bool)
}

功能：在注解所指定方法的退出点，织入对被注解标注的函数的调用。注解所指定的方法和被注解标注的函数，需满足规格限制。

示例：

参考InsertAtExit 示例教程了解具体调用流程。

const init(String, String, String, Bool, String, Bool)

public const init(packageName!: String, className!: String, methodName!: String, isStatic!: Bool, funcTypeStr!: String, recursive!: Bool)

功能：创建 InsertAtExit 对象。

示例：

参考InsertAtExit 示例教程了解具体调用流程。

参数：

• packageName!: String - 被织入的函数的所属包名，如 "default", "std.core"；
• className!: String - 如果被织入的函数是成员函数，则为函数所属类名；如果被织入的函数是全局函数，则为空；
• methodName!: String - 被织入的函数名称，如 "foo"；
• isStatic!: Bool - 被织入的函数是否为静态成员函数；
• funcTypeStr!: String - 被织入的函数的类型字符串，不包括空格。对于自定义类型，类型定义所在的包名不可省略，且和类型名之间使用 . 分隔。不需要包括隐式的 this 形参的类型。如 "(Int64,std.core.Object)->Unit"；
• recursive: Bool - 当被织入的函数是成员函数时，表示是否对子类里的函数 override 版本也做织入；否则该字段应填 false。

class ReplaceFuncBody

public class ReplaceFuncBody {
    public const init(packageName!: String, className!: String, methodName!: String, isStatic!: Bool, recursive!: Bool)
}

功能：将注解所指定方法的方法体，替换为对被注解标注的函数的调用。注解所指定的方法和被注解标注的函数，需满足规格限制。

示例：

参考ReplaceFuncBody 示例教程了解具体调用流程。

const init(String, String, String, Bool, Bool)

public const init(packageName!: String, className!: String, methodName!: String, isStatic!: Bool, recursive!: Bool)

功能：创建 ReplaceFuncBody 对象。

示例：

参考ReplaceFuncBody 示例教程了解具体调用流程。

参数：

• packageName!: String - 被织入的函数的所属包名，如 "default", "std.core"；
• className!: String - 如果被织入的函数是成员函数，则为函数所属类名；如果被织入的函数是全局函数，则为空；
• methodName!: String - 被织入的函数名称，如 "foo"；
• isStatic!: Bool - 被织入的函数是否为静态成员函数；
• recursive!: Bool - 当被织入的函数是成员函数时，表示是否对子类里的函数 override 版本也做织入；否则该字段应填 false。

AOP 开发示例

InsertAtEntry 入口插桩示例

下面是使用 @InsertAtEntry 完成在指定函数入口插桩的示例代码：

package AOP_demo1

import stdx.aspectCJ.*
import std.time.DateTime

@InsertAtEntry[packageName: "AOP_demo1", className: "", methodName: "printCurrentTime", isStatic: false, funcTypeStr: "()->Unit", recursive: false]
public func printCurrentTimeImpl() {
    println("----- ${DateTime.now()} -----")
}

public func printCurrentTime() {
    println("hi")
    println("bye")
}

main() {
    printCurrentTime()
    0
}

linux 平台编译命令：

cjc aop_demo1.cj -L $CANGJIE_STDX_PATH --import-path $CANGJIE_STDX_PATH -lstdx.aspectCJ --plugin=$CANGJIE_STDX_PATH/libcollect-aspects.so -o main # 第一次编译，收集切面
cjc aop_demo1.cj -L $CANGJIE_STDX_PATH --import-path $CANGJIE_STDX_PATH -lstdx.aspectCJ --plugin=$CANGJIE_STDX_PATH/libwave-aspects.so -o main # 第二次编译，织入切面

运行结果可能如下：

----- 2025-06-03T00:00:18.994507-07:00 -----
hi
bye

InsertAtExit 退出插桩示例

下面是使用 @InsertAtExit 完成在指定函数退出前插桩的示例代码：

package AOP_demo2

import stdx.aspectCJ.*
import std.time.DateTime

@InsertAtExit[packageName: "AOP_demo2", className: "", methodName: "printCurrentTime", isStatic: false, funcTypeStr: "()->std.core:String", recursive: false]
public func printCurrentTimeImpl() {
    println("----- ${DateTime.now()} -----")
}

public func printCurrentTime() {
    println("hi")
    println("bye")
    "done"
}

main() {
    println(printCurrentTime())
    0
}

linux 平台编译命令：

cjc aop_demo2.cj -L $CANGJIE_STDX_PATH --import-path $CANGJIE_STDX_PATH -lstdx.aspectCJ --plugin=$CANGJIE_STDX_PATH/libcollect-aspects.so -o main # 第一次编译，收集切面
cjc aop_demo2.cj -L $CANGJIE_STDX_PATH --import-path $CANGJIE_STDX_PATH -lstdx.aspectCJ --plugin=$CANGJIE_STDX_PATH/libwave-aspects.so -o main # 第二次编译，织入切面

运行结果可能如下：

hi
bye
----- 2025-06-03T00:04:59.996469-07:00 -----
done

ReplaceFuncBody 替换函数体示例

下面是使用 @ReplaceFuncBody 完成替换指定函数函数体的示例代码：

package AOP_demo3

import stdx.aspectCJ.*
import std.time.DateTime

@ReplaceFuncBody[packageName: "AOP_demo3", className: "", methodName: "printCurrentTime", isStatic: false, recursive: false]
public func printCurrentTimeImpl(original: (String)->String) {
    println("----- ${DateTime.now()} -----")
    println(original("abc"))
    println("----- end -----")
    "def"
}

public func printCurrentTime(x: String): String {
    println(x)
    "456"
}

main() {
    println(printCurrentTime("123"))
    0
}

linux 平台编译命令：

cjc aop_demo3.cj -L $CANGJIE_STDX_PATH --import-path $CANGJIE_STDX_PATH -lstdx.aspectCJ --plugin=$CANGJIE_STDX_PATH/libcollect-aspects.so -o main # 第一次编译，收集切面
cjc aop_demo3.cj -L $CANGJIE_STDX_PATH --import-path $CANGJIE_STDX_PATH -lstdx.aspectCJ --plugin=$CANGJIE_STDX_PATH/libwave-aspects.so -o main # 第二次编译，织入切面

运行结果可能如下：

----- 2025-06-03T00:04:59.996469-07:00 -----
abc
456
----- end -----
def

stdx.chir

说明：

当前处于开发阶段，尚不具备完整功能。

功能介绍

chir 包提供类型系统的基础类型定义，包括抽象类型基类、内置类型（整数、浮点数、布尔、字符等）以及引用类型等。该包为仓颉语言的类型系统提供核心支持。

API 列表

类

类

class BoolType

public class BoolType <: BuiltinType & Equatable<BoolType>

功能：表示类型系统中的布尔类型。这是一个单例类型，表示 Bool 类型。

父类型：

• BuiltinType
• Equatable<BoolType>

static func get()

public static func get(): BoolType

功能：获取 BoolType 的单例实例。

返回值：

• BoolType - BoolType 实例。

示例：

import stdx.chir.*

main() {
    let boolType = BoolType.get()
    println("布尔类型: ${boolType.toString()}")
}

运行结果：

布尔类型: Bool

operator func==(BoolType)

public operator func==(_: BoolType): Bool

功能：检查该 BoolType 是否与另一个 BoolType 相等。

参数：

• _: BoolType - 要比较的另一个 BoolType（未使用，始终返回 true）。

返回值：

• Bool - 始终返回 true，因为所有 BoolType 实例都相等。

示例：

import stdx.chir.*

main() {
    let boolType1 = BoolType.get()
    let boolType2 = BoolType.get()
    println("两个 BoolType 相等: ${boolType1 == boolType2}")
}

运行结果：

两个 BoolType 相等: true

class CPointerType

public class CPointerType <: BuiltinType & Equatable<CPointerType>

功能：表示类型系统中的 C 指针类型。该类型表示指向 C 类型的指针，用于与 C 代码互操作。该类维护所有 C 指针类型的缓存以确保唯一性。

父类型：

• BuiltinType
• Equatable<CPointerType>

prop elementType

public prop elementType: Type

功能：获取该 C 指针类型所指向的元素类型。

返回值：

• Type - 元素类型。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let cPointerType = CPointerType.get(intType)
    let elementType = cPointerType.elementType
    println("C 指针类型: ${cPointerType.toString()}")
    println("元素类型: ${elementType.toString()}")
}

运行结果：

C 指针类型: CPointer<Int32>
元素类型: Int32

operator func==(CPointerType)

public operator func==(other: CPointerType): Bool

功能：检查该 CPointerType 是否与另一个 CPointerType 相等。

参数：

• other: CPointerType - 要比较的 CPointerType。

返回值：

• Bool - 如果类型相等则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let cPointerType1 = CPointerType.get(intType)
    let cPointerType2 = CPointerType.get(intType)
    println("两个 C 指针类型相等: ${cPointerType1 == cPointerType2}")
}

运行结果：

两个 C 指针类型相等: true

static func get(Type)

public static func get(elementType: Type): CPointerType

功能：获取或创建给定元素类型的 CPointerType。

此方法确保每个元素类型只存在一个 CPointerType 实例。

参数：

• elementType: Type - 指针所指向的类型。

返回值：

• CPointerType - 给定元素类型的 CPointerType 实例。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let cPointerType = CPointerType.get(intType)
    println("C 指针类型: ${cPointerType.toString()}")
}

运行结果：

C 指针类型: CPointer<Int32>

func toString()

public func toString(): String

功能：将该 CPointerType 转换为字符串表示。

返回值：

• String - C 指针类型的字符串表示（CPointer<elementType>）。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let cPointerType = CPointerType.get(intType)
    println("C 指针类型字符串: ${cPointerType.toString()}")
}

运行结果：

C 指针类型字符串: CPointer<Int32>

class CStringType

public class CStringType <: BuiltinType & Equatable<CStringType>

功能：表示类型系统中的 C 字符串类型。该类型表示 C 风格的空终止字符串，用于与 C 代码互操作。这是一个单例类型，表示内置的 C 字符串类型。

父类型：

• BuiltinType
• Equatable<CStringType>

operator func==(CStringType)

public operator func==(_: CStringType): Bool

功能：检查该 CStringType 是否与另一个 CStringType 相等。

参数：

• _: CStringType - 要比较的另一个 CStringType（未使用，始终返回 true）。

返回值：

• Bool - 始终返回 true，因为所有 CStringType 实例都相等。

示例：

import stdx.chir.*

main() {
    let cStringType1 = CStringType.get()
    let cStringType2 = CStringType.get()
    println("两个 CStringType 相等: ${cStringType1 == cStringType2}")
}

运行结果：

两个 CStringType 相等: true

static func get()

public static func get(): CStringType

功能：获取 CStringType 的单例实例。

返回值：

• CStringType - CStringType 实例。

示例：

import stdx.chir.*

main() {
    let cStringType = CStringType.get()
    println("C 字符串类型: ${cStringType.toString()}")
}

运行结果：

C 字符串类型: CString

public operator func==(_: CStringType): Bool

功能：检查该 CStringType 是否与另一个 CStringType 相等。

参数：

• _: CStringType - 要比较的另一个 CStringType（未使用，始终返回 true）。

返回值：

• Bool - 始终返回 true，因为所有 CStringType 实例都相等。

示例：

import stdx.chir.*

main() {
    let cStringType1 = CStringType.get()
    let cStringType2 = CStringType.get()
    println("两个 CStringType 相等: ${cStringType1 == cStringType2}")
}

运行结果：

两个 CStringType 相等: true

class FloatType

public class FloatType <: NumericType & Equatable<FloatType>

功能：表示类型系统中的浮点类型。该类表示三种浮点类型：Float16、Float32 和 Float64。

父类型：

• NumericType
• Equatable<FloatType>

static func getFloat16()

public static func getFloat16(): FloatType

功能：获取 Float16 类型实例。

返回值：

• FloatType - Float16 类型。

示例：

import stdx.chir.*

main() {
    let float16Type = FloatType.getFloat16()
    println("Float16 类型: ${float16Type.toString()}")
}

运行结果：

Float16 类型: Float16

static func getFloat32()

public static func getFloat32(): FloatType

功能：获取 Float32 类型实例。

返回值：

• FloatType - Float32 类型。

示例：

import stdx.chir.*

main() {
    let float32Type = FloatType.getFloat32()
    println("Float32 类型: ${float32Type.toString()}")
}

运行结果：

Float32 类型: Float32

static func getFloat64()

public static func getFloat64(): FloatType

功能：获取 Float64 类型实例。

返回值：

• FloatType - Float64 类型。

示例：

import stdx.chir.*

main() {
    let float64Type = FloatType.getFloat64()
    println("Float64 类型: ${float64Type.toString()}")
}

运行结果：

Float64 类型: Float64

operator func==(FloatType)

public operator func==(other: FloatType): Bool

功能：检查该 FloatType 是否与另一个 FloatType 相等。

参数：

• other: FloatType - 要比较的 FloatType。

返回值：

• Bool - 如果类型相等则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let float32Type1 = FloatType.getFloat32()
    let float32Type2 = FloatType.getFloat32()
    let float64Type = FloatType.getFloat64()
    println("两个 Float32 相等: ${float32Type1 == float32Type2}")
    println("Float32 和 Float64 相等: ${float32Type1 == float64Type}")
}

运行结果：

两个 Float32 相等: true
Float32 和 Float64 相等: false

class IntType

public class IntType <: NumericType & Equatable<IntType>

功能：表示类型系统中的整数类型。该类表示各种大小的有符号和无符号整数类型。

父类型：

• NumericType
• Equatable<IntType>

static func getInt16()

public static func getInt16(): IntType

功能：获取 Int16 类型实例。

返回值：

• IntType - Int16 类型。

示例：

import stdx.chir.*

main() {
    let int16Type = IntType.getInt16()
    println("Int16 类型: ${int16Type.toString()}")
}

运行结果：

Int16 类型: Int16

static func getInt32()

public static func getInt32(): IntType

功能：获取 Int32 类型实例。

返回值：

• IntType - Int32 类型。

示例：

import stdx.chir.*

main() {
    let int32Type = IntType.getInt32()
    println("Int32 类型: ${int32Type.toString()}")
}

运行结果：

Int32 类型: Int32

static func getInt64()

public static func getInt64(): IntType

功能：获取 Int64 类型实例。

返回值：

• IntType - Int64 类型。

示例：

import stdx.chir.*

main() {
    let int64Type = IntType.getInt64()
    println("Int64 类型: ${int64Type.toString()}")
}

运行结果：

Int64 类型: Int64

static func getInt8()

public static func getInt8(): IntType

功能：获取 Int8 类型实例。

返回值：

• IntType - Int8 类型。

示例：

import stdx.chir.*

main() {
    let int8Type = IntType.getInt8()
    println("Int8 类型: ${int8Type.toString()}")
}

运行结果：

Int8 类型: Int8

static func getIntNative()

public static func getIntNative(): IntType

功能：获取 IntNative 类型实例。

返回值：

• IntType - IntNative 类型。

示例：

import stdx.chir.*

main() {
    let intNativeType = IntType.getIntNative()
    println("IntNative 类型: ${intNativeType.toString()}")
}

运行结果：

IntNative 类型: IntNative

static func getUInt16()

public static func getUInt16(): IntType

功能：获取 UInt16 类型实例。

返回值：

• IntType - UInt16 类型。

示例：

import stdx.chir.*

main() {
    let uint16Type = IntType.getUInt16()
    println("UInt16 类型: ${uint16Type.toString()}")
}

运行结果：

UInt16 类型: UInt16

static func getUInt32()

public static func getUInt32(): IntType

功能：获取 UInt32 类型实例。

返回值：

• IntType - UInt32 类型。

示例：

import stdx.chir.*

main() {
    let uint32Type = IntType.getUInt32()
    println("UInt32 类型: ${uint32Type.toString()}")
}

运行结果：

UInt32 类型: UInt32

static func getUInt64()

public static func getUInt64(): IntType

功能：获取 UInt64 类型实例。

返回值：

• IntType - UInt64 类型。

示例：

import stdx.chir.*

main() {
    let uint64Type = IntType.getUInt64()
    println("UInt64 类型: ${uint64Type.toString()}")
}

运行结果：

UInt64 类型: UInt64

static func getUInt8()

public static func getUInt8(): IntType

功能：获取 UInt8 类型实例。

返回值：

• IntType - UInt8 类型。

示例：

import stdx.chir.*

main() {
    let uint8Type = IntType.getUInt8()
    println("UInt8 类型: ${uint8Type.toString()}")
}

运行结果：

UInt8 类型: UInt8

static func getUIntNative()

public static func getUIntNative(): IntType

功能：获取 UIntNative 类型实例。

返回值：

• IntType - UIntNative 类型。

示例：

import stdx.chir.*

main() {
    let uintNativeType = IntType.getUIntNative()
    println("UIntNative 类型: ${uintNativeType.toString()}")
}

运行结果：

UIntNative 类型: UIntNative

operator func==(IntType)

public operator func==(other: IntType): Bool

功能：检查该 IntType 是否与另一个 IntType 相等。

参数：

• other: IntType - 要比较的 IntType。

返回值：

• Bool - 如果类型相等则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let int32Type1 = IntType.getInt32()
    let int32Type2 = IntType.getInt32()
    let int64Type = IntType.getInt64()
    println("两个 Int32 相等: ${int32Type1 == int32Type2}")
    println("Int32 和 Int64 相等: ${int32Type1 == int64Type}")
}

运行结果：

两个 Int32 相等: true
Int32 和 Int64 相等: false

func isSigned()

public func isSigned(): Bool

功能：检查该整数类型是否为有符号类型。

返回值：

• Bool - 如果类型是有符号的则返回 true，如果是无符号的则返回 false。

示例：

import stdx.chir.*

main() {
    let int32Type = IntType.getInt32()
    let uint32Type = IntType.getUInt32()
    println("Int32 是有符号的: ${int32Type.isSigned()}")
    println("UInt32 是有符号的: ${uint32Type.isSigned()}")
}

运行结果：

Int32 是有符号的: true
UInt32 是有符号的: false

class NothingType

public class NothingType <: BuiltinType & Equatable<NothingType>

功能：表示类型系统中的 Nothing 类型（底部类型）。该类型用于表示永远不会返回的表达式。

父类型：

• BuiltinType
• Equatable<NothingType>

static func get()

public static func get(): NothingType

功能：获取 NothingType 的单例实例。

返回值：

• NothingType - NothingType 实例。

示例：

import stdx.chir.*

main() {
    let nothingType = NothingType.get()
    println("Nothing 类型: ${nothingType.toString()}")
}

运行结果：

Nothing 类型: Nothing

operator func==(NothingType)

public operator func==(_: NothingType): Bool

功能：检查该 NothingType 是否与另一个 NothingType 相等。

参数：

• _: NothingType - 要比较的另一个 NothingType（未使用，始终返回 true）。

返回值：

• Bool - 始终返回 true，因为所有 NothingType 实例都相等。

示例：

import stdx.chir.*

main() {
    let nothingType1 = NothingType.get()
    let nothingType2 = NothingType.get()
    println("两个 NothingType 相等: ${nothingType1 == nothingType2}")
}

运行结果：

两个 NothingType 相等: true

class NumericType

sealed abstract class NumericType <: BuiltinType & Equatable<NumericType>

功能：数值类型的抽象基类。该类表示数值类型，包括整数类型和浮点类型。

父类型：

• BuiltinType
• Equatable<NumericType>

operator func==(NumericType)

public operator func==(other: NumericType): Bool

功能：检查该数值类型是否与另一个数值类型相等。

参数：

• other: NumericType - 要比较的数值类型。

返回值：

• Bool - 如果类型相等则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let intType1 = IntType.getInt32()
    let intType2 = IntType.getInt32()
    let floatType = FloatType.getFloat32()
    println("两个 Int32 相等: ${intType1 == intType2}")
    println("Int32 和 Float32 相等: ${intType1 == floatType}")
}

运行结果：

两个 Int32 相等: true
Int32 和 Float32 相等: false

class RefType

public class RefType <: Type & Equatable<RefType>

功能：表示类型系统中的引用类型。该类型包装另一个类型以表示对该类型的引用。该类维护所有引用类型的缓存以确保唯一性。

父类型：

• Type
• Equatable<RefType>

prop baseType

public prop baseType: Type

功能：获取该引用类型所引用的基类型。

返回值：

• Type - 基类型。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let refType = RefType.get(intType)
    let baseType = refType.baseType
    println("引用类型: ${refType.toString()}")
    println("基类型: ${baseType.toString()}")
}

运行结果：

引用类型: Int32&
基类型: Int32

operator func==(RefType)

public operator func==(other: RefType): Bool

功能：检查该 RefType 是否与另一个 RefType 相等。

参数：

• other: RefType - 要比较的 RefType。

返回值：

• Bool - 如果类型相等则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let refType1 = RefType.get(intType)
    let refType2 = RefType.get(intType)
    println("两个引用类型相等: ${refType1 == refType2}")
}

运行结果：

两个引用类型相等: true

static func get(Type)

public static func get(baseType: Type): RefType

功能：获取或创建给定基类型的 RefType。

此方法确保每个基类型只存在一个 RefType 实例。

参数：

• baseType: Type - 要创建引用的基类型。

返回值：

• RefType - 给定基类型的 RefType 实例。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let refType = RefType.get(intType)
    println("引用类型: ${refType.toString()}")
}

运行结果：

引用类型: Int32&

func toString()

public func toString(): String

功能：将该 RefType 转换为字符串表示。

返回值：

• String - 引用类型的字符串表示（基类型后跟 '&'）。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let refType = RefType.get(intType)
    println("引用类型字符串: ${refType.toString()}")
}

运行结果：

引用类型字符串: Int32&

class RuneType

public class RuneType <: BuiltinType & Equatable<RuneType>

功能：表示类型系统中的 Rune 类型。该类型表示字符类型。

父类型：

• BuiltinType
• Equatable<RuneType>

static func get()

public static func get(): RuneType

功能：获取 RuneType 的单例实例。

返回值：

• RuneType - RuneType 实例。

示例：

import stdx.chir.*

main() {
    let runeType = RuneType.get()
    println("Rune 类型: ${runeType.toString()}")
}

运行结果：

Rune 类型: Rune

operator func==(RuneType)

public operator func==(_: RuneType): Bool

功能：检查该 RuneType 是否与另一个 RuneType 相等。

参数：

• _: RuneType - 要比较的另一个 RuneType（未使用，始终返回 true）。

返回值：

• Bool - 始终返回 true，因为所有 RuneType 实例都相等。

示例：

import stdx.chir.*

main() {
    let runeType1 = RuneType.get()
    let runeType2 = RuneType.get()
    println("两个 RuneType 相等: ${runeType1 == runeType2}")
}

运行结果：

两个 RuneType 相等: true

class Type

sealed abstract class Type <: ToString & Hashable & Equatable<Type>

功能：类型系统中所有类型的抽象基类。该类提供了类型的基础功能，包括相等性比较、哈希计算和字符串转换。

父类型：

• ToString
• Hashable
• Equatable<Type>

prop typeArgs

public prop typeArgs: Array<Type>

功能：获取该类型的类型参数。

返回值：

• Array<Type> - 类型参数数组。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    println("类型参数数量: ${intType.typeArgs.size}")
}

运行结果：

类型参数数量: 0

func dump()

public func dump(): Unit

功能：将类型的字符串表示打印到标准输出。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    intType.dump()
}

运行结果：

Int32

func hashCode()

public func hashCode(): Int64

功能：获取该类型的哈希码。

返回值：

• Int64 - 类型的哈希码。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    println("哈希码: ${intType.hashCode()}")
}

运行结果：

哈希码: -7959616418923165251

func isBoolType()

public func isBoolType(): Bool

功能：检查该类型是否为布尔类型。

返回值：

• Bool - 如果类型是 Bool 则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let boolType = BoolType.get()
    let intType = IntType.getInt32()
    println("BoolType 是布尔类型: ${boolType.isBoolType()}")
    println("Int32 是布尔类型: ${intType.isBoolType()}")
}

运行结果：

BoolType 是布尔类型: true
Int32 是布尔类型: false

func isFloatType()

public func isFloatType(): Bool

功能：检查该类型是否为浮点类型。

返回值：

• Bool - 如果类型是 Float16、Float32 或 Float64 则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let floatType = FloatType.getFloat32()
    let intType = IntType.getInt32()
    println("Float32 是浮点类型: ${floatType.isFloatType()}")
    println("Int32 是浮点类型: ${intType.isFloatType()}")
}

运行结果：

Float32 是浮点类型: true
Int32 是浮点类型: false

func isIntType()

public func isIntType(): Bool

功能：检查该类型是否为整数类型（有符号或无符号）。

返回值：

• Bool - 如果类型是任何整数类型则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let floatType = FloatType.getFloat32()
    println("Int32 是整数类型: ${intType.isIntType()}")
    println("Float32 是整数类型: ${floatType.isIntType()}")
}

运行结果：

Int32 是整数类型: true
Float32 是整数类型: false

func isNothingType()

public func isNothingType(): Bool

功能：检查该类型是否为 Nothing 类型。

返回值：

• Bool - 如果类型是 Nothing 则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let nothingType = NothingType.get()
    let intType = IntType.getInt32()
    println("NothingType 是 Nothing 类型: ${nothingType.isNothingType()}")
    println("Int32 是 Nothing 类型: ${intType.isNothingType()}")
}

运行结果：

NothingType 是 Nothing 类型: true
Int32 是 Nothing 类型: false

func isNumericType()

public func isNumericType(): Bool

功能：检查该类型是否为数值类型（整数或浮点数）。

返回值：

• Bool - 如果类型是数值类型则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let floatType = FloatType.getFloat32()
    let boolType = BoolType.get()
    println("Int32 是数值类型: ${intType.isNumericType()}")
    println("Float32 是数值类型: ${floatType.isNumericType()}")
    println("Bool 是数值类型: ${boolType.isNumericType()}")
}

运行结果：

Int32 是数值类型: true
Float32 是数值类型: true
Bool 是数值类型: false

func isPrimitiveType()

public func isPrimitiveType(): Bool

功能：检查该类型是否为原始类型。

返回值：

• Bool - 如果类型是原始类型（int、float、bool、rune、unit 或 nothing）则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let boolType = BoolType.get()
    println("Int32 是原始类型: ${intType.isPrimitiveType()}")
    println("Bool 是原始类型: ${boolType.isPrimitiveType()}")
}

运行结果：

Int32 是原始类型: true
Bool 是原始类型: true

func isRefType()

public func isRefType(): Bool

功能：检查该类型是否为引用类型。

返回值：

• Bool - 如果类型是引用类型则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let refType = RefType.get(intType)
    println("Int32 是引用类型: ${intType.isRefType()}")
    println("Int32& 是引用类型: ${refType.isRefType()}")
}

运行结果：

Int32 是引用类型: false
Int32& 是引用类型: true

func isRuneType()

public func isRuneType(): Bool

功能：检查该类型是否为 Rune 类型。

返回值：

• Bool - 如果类型是 Rune 则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let runeType = RuneType.get()
    let intType = IntType.getInt32()
    println("RuneType 是 Rune 类型: ${runeType.isRuneType()}")
    println("Int32 是 Rune 类型: ${intType.isRuneType()}")
}

运行结果：

RuneType 是 Rune 类型: true
Int32 是 Rune 类型: false

func isSignedIntType()

public func isSignedIntType(): Bool

功能：检查该类型是否为有符号整数类型。

返回值：

• Bool - 如果类型是有符号整数类型则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let uintType = IntType.getUInt32()
    println("Int32 是有符号整数: ${intType.isSignedIntType()}")
    println("UInt32 是有符号整数: ${uintType.isSignedIntType()}")
}

运行结果：

Int32 是有符号整数: true
UInt32 是有符号整数: false

func isUnitType()

public func isUnitType(): Bool

功能：检查该类型是否为 Unit 类型。

返回值：

• Bool - 如果类型是 Unit 则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let unitType = UnitType.get()
    let intType = IntType.getInt32()
    println("UnitType 是 Unit 类型: ${unitType.isUnitType()}")
    println("Int32 是 Unit 类型: ${intType.isUnitType()}")
}

运行结果：

UnitType 是 Unit 类型: true
Int32 是 Unit 类型: false

func isUnsignedIntType()

public func isUnsignedIntType(): Bool

功能：检查该类型是否为无符号整数类型。

返回值：

• Bool - 如果类型是无符号整数类型则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let uintType = IntType.getUInt32()
    println("Int32 是无符号整数: ${intType.isUnsignedIntType()}")
    println("UInt32 是无符号整数: ${uintType.isUnsignedIntType()}")
}

运行结果：

Int32 是无符号整数: false
UInt32 是无符号整数: true

operator func==(Type)

public open operator func==(other: Type): Bool

功能：检查该类型是否与另一个类型相等。

参数：

• other: Type - 要比较的类型。

返回值：

• Bool - 如果类型具有相同的种类和类型参数则返回 true，否则返回 false。

示例：

import stdx.chir.*

main() {
    let type1 = IntType.getInt32()
    let type2 = IntType.getInt32()
    let type3 = IntType.getInt64()
    println("type1 == type2: ${type1 == type2}")
    println("type1 == type3: ${type1 == type3}")
}

运行结果：

type1 == type2: true
type1 == type3: false

func stripAllRefs()

public func stripAllRefs(): Type

功能：去除该类型的所有引用包装。

递归地移除所有 Ref 类型包装，直到到达非引用类型。

返回值：

• Type - 去除所有引用包装后的基类型。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    let refType = RefType.get(intType)
    let baseType = refType.stripAllRefs()
    println("引用类型: ${refType.toString()}")
    println("去除引用后: ${baseType.toString()}")
}

运行结果：

引用类型: Int32&
去除引用后: Int32

func toString()

public open func toString(): String

功能：将类型转换为字符串表示。

返回值：

• String - 类型的字符串表示。

示例：

import stdx.chir.*

main() {
    let intType = IntType.getInt32()
    println("类型: ${intType.toString()}")
}

运行结果：

类型: Int32

class UnitType

public class UnitType <: BuiltinType & Equatable<UnitType>

功能：表示类型系统中的 Unit 类型。该类型表示没有有意义的值，类似于 C 语言中的 void。

父类型：

• BuiltinType
• Equatable<UnitType>

static func get()

public static func get(): UnitType

功能：获取 UnitType 的单例实例。

返回值：

• UnitType - UnitType 实例。

示例：

import stdx.chir.*

main() {
    let unitType = UnitType.get()
    println("Unit 类型: ${unitType.toString()}")
}

运行结果：

Unit 类型: Unit

operator func==(UnitType)

public operator func==(_: UnitType): Bool

功能：检查该 UnitType 是否与另一个 UnitType 相等。

参数：

• _: UnitType - 要比较的另一个 UnitType（未使用，始终返回 true）。

返回值：

• Bool - 始终返回 true，因为所有 UnitType 实例都相等。

示例：

import stdx.chir.*

main() {
    let unitType1 = UnitType.get()
    let unitType2 = UnitType.get()
    println("两个 UnitType 相等: ${unitType1 == unitType2}")
}

运行结果：

两个 UnitType 相等: true

stdx.compress

功能介绍

compress 是一个压缩与归档能力的集合模块，旨在提供流式、高效且易用的压缩与归档工具集，支持单文件压缩、数据流压缩、以及归档（打包）功能的组合使用。

压缩是指用更少的比特表示数据，以便更高效地存储和传输数据。此能力由子模块 stdx.compress.zlib 提供。

归档是将多个文件/目录的元数据与内容打包为一个连续的归档流（不隐含压缩）。此能力由子模块 stdx.compress.tar 提供，支持 V7/USTAR/PAX/GNU 格式。

压缩和归档通常组合使用，常见用法是先归档再压缩（例如 tar.gz）。本包在顶层提供便捷的组合工具（例如 TarGzip），将打包与压缩组合为单步读写接口，方便常见场景使用。

API 列表

类

类

class TarGzip

public class TarGzip {}

功能：压缩和解压目录或流。

static func archive(Path, (Path) -> Bool, Path, Bool)

public static func archive(fromDir!: Path, filter!: (Path) -> Bool, destFile!: Path, includeBaseDirectory!: Bool): Unit

功能：配合过滤函数选择性地将指定目录压缩为 .tar.gz 文件。内部先以 tar 格式归档目录，再以 gzip 压缩归档结果。

参数：

• fromDir!: Path - 待压缩目录。

• filter!: (Path) -> Bool - 过滤函数，会传入遍历到的目录、文件和软链接路径，返回 true 表示保留，否则丢弃。

• destFile!: Path - 输出的 .tar.gz 文件路径。

• includeBaseDirectory!: Bool - 是否包含根目录。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

• ZlibException - 如果 zlib 压缩时发生错误，抛出异常。

示例：

import stdx.compress.*
import std.fs.*

main(): Unit {
    // 测试路径
    let testDir = Path("./test_dir")
    let testFile = Path("./test_dir/test.txt")
    let destFile = Path("./test.tar.gz")

    // 创建目录和文件(创建前清理)
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, TarGzip!".toArray())

    // 使用TarGzip压缩目录，使用过滤函数
    TarGzip.archive(
        fromDir: testDir,
        filter: {path: Path => return path.toString().endsWith(".txt")},
        destFile: destFile,
        includeBaseDirectory: true
    )

    println("Did the TarGzip archive with filter complete successfully? ${exists(destFile)}")

    // 清理测试文件
    removeIfExists(testDir, recursive: true)
    removeIfExists(destFile)
}

运行结果：

Did the TarGzip archive with filter complete successfully? true

static func archive(Path, Path, Bool)

public static func archive(fromDir!: Path, destFile!: Path, includeBaseDirectory!: Bool): Unit

功能：将指定目录压缩为 .tar.gz 文件。内部先以 tar 格式归档目录，再以 gzip 压缩归档结果。

参数：

• fromDir!: Path - 待压缩的目录路径。

• destFile!: Path - 生成的 .tar.gz 文件路径。

• includeBaseDirectory!: Bool - 是否包含目录本身作为顶级目录。若为 true，归档包内包含该目录；若为 false，仅包含其内容。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

• ZlibException - 如果 zlib 压缩时发生错误，抛出异常。

示例：

import stdx.compress.*
import std.fs.*

main(): Unit {
    // 测试路径
    let testDir = Path("./test_dir_simple")
    let testFile = Path("./test_dir_simple/test.txt")
    let destFile = Path("./test_simple.tar.gz")

    // 创建目录和文件(创建前清理)
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, TarGzip Simple Archive!".toArray())

    // 使用TarGzip压缩目录，不使用过滤函数
    TarGzip.archive(
        fromDir: testDir,
        destFile: destFile,
        includeBaseDirectory: true
    )

    println("Did the TarGzip simple archive complete successfully? ${exists(destFile)}")

    // 清理测试文件
    removeIfExists(testDir, recursive: true)
    removeIfExists(destFile)
}

运行结果：

Did the TarGzip simple archive complete successfully? true

static func archive(String, (String) -> Bool, String, Bool)

public static func archive(fromDir!: String, filter!: (String) -> Bool, destFile!: String, includeBaseDirectory!: Bool): Unit

功能：配合过滤函数选择性地将指定目录压缩为 .tar.gz 文件。内部先以 tar 格式归档目录，再以 gzip 压缩归档结果。

参数：

• fromDir!: String - 待压缩目录。

• filter!: (String) -> Bool - 过滤函数，会传入遍历到的目录、文件和软链接路径，返回 true 表示保留，否则丢弃。

• destFile!: String - 输出的 .tar.gz 文件路径。

• includeBaseDirectory!: Bool - 是否包含根目录。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

• ZlibException - 如果 zlib 压缩时发生错误，抛出异常。

示例：

import stdx.compress.*
import std.fs.*

main(): Unit {
    // 测试路径
    let testDir = "./test_dir_str_filter"
    let testFile = "./test_dir_str_filter/test.txt"
    let testLogFile = "./test_dir_str_filter/test.log"
    let destFile = "./test_str_filter.tar.gz"

    // 创建目录和文件(创建前清理)
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, TarGzip String Filter Archive!".toArray())
    File.writeTo(testLogFile, "This is a log file that should be filtered out".toArray())

    // 使用TarGzip压缩目录，使用字符串过滤函数
    TarGzip.archive(
        fromDir: testDir,
        filter: {path: String => return path.endsWith(".txt")},
        destFile: destFile,
        includeBaseDirectory: true
    )

    println("Did the TarGzip archive with string filter complete successfully? ${exists(Path(destFile))}")

    // 清理测试文件
    removeIfExists(testDir, recursive: true)
    removeIfExists(destFile)
}

运行结果：

Did the TarGzip archive with string filter complete successfully? true

static func archive(String, String, Bool)

public static func archive(fromDir!: String, destFile!: String, includeBaseDirectory!: Bool): Unit

功能：将指定目录压缩为 .tar.gz 文件。内部先以 tar 格式归档目录，再以 gzip 压缩归档结果。

参数：

• fromDir!: String - 待压缩的目录路径。

• destFile!: String - 生成的 .tar.gz 文件路径。

• includeBaseDirectory!: Bool - 是否包含目录本身作为顶级目录。若为 true，归档包内包含该目录；若为 false，仅包含其内容。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

• ZlibException - 如果 zlib 压缩时发生错误，抛出异常。

示例：

import stdx.compress.*
import std.fs.*

main(): Unit {
    // 测试路径
    let testDir = "./test_dir_str_simple"
    let testFile = "./test_dir_str_simple/test.txt"
    let destFile = "./test_str_simple.tar.gz"

    // 创建目录和文件(创建前清理)
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, TarGzip String Simple Archive!".toArray())

    // 使用TarGzip压缩目录，使用字符串参数
    TarGzip.archive(
        fromDir: testDir,
        destFile: destFile,
        includeBaseDirectory: true
    )

    println("Did the TarGzip string simple archive complete successfully? ${exists(destFile)}")

    // 清理测试文件
    removeIfExists(testDir, recursive: true)
    removeIfExists(destFile)
}

运行结果：

Did the TarGzip string simple archive complete successfully? true

static func archive<T>(Path, T, Bool) where T <: OutputStream

public static func archive<T>(fromDir!: Path, destStream!: T, includeBaseDirectory!: Bool): Unit where T <: OutputStream

功能：将目录压缩为 .tar.gz 数据并写入指定输出流。

注意：

函数不负责 destStream 资源的释放，调用方需自行管理该输出流的生命周期。

参数：

• fromDir!: Path - 待压缩的目录路径。

• destStream!: T - 压缩后数据的输出流。

• includeBaseDirectory!: Bool - 是否包含根目录。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

• ZlibException - 如果 zlib 压缩时发生错误，抛出异常。

示例：

import stdx.compress.*
import std.fs.*
import std.io.*

main(): Unit {
    // 测试路径
    let testDir = Path("./test_dir_stream")
    let testFile = Path("./test_dir_stream/test.txt")
    let destFile = Path("./test_stream.tar.gz")

    // 创建目录和文件(创建前清理)
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, TarGzip Stream Archive!".toArray())

    // 创建文件输出流
    let fileStream = File(destFile, Write)

    // 使用TarGzip压缩目录到输出流
    TarGzip.archive(
        fromDir: testDir,
        destStream: fileStream,
        includeBaseDirectory: true
    )

    // 关闭流
    fileStream.close()

    println("Did the TarGzip archive to stream complete successfully? ${exists(destFile)}")

    // 清理测试文件
    removeIfExists(testDir, recursive: true)
    removeIfExists(destFile)
}

运行结果：

Did the TarGzip archive to stream complete successfully? true

static func archive<T>(String, T, Bool) where T <: OutputStream

public static func archive<T>(fromDir!: String, destStream!: T, includeBaseDirectory!: Bool): Unit where T <: OutputStream

功能：将目录压缩为 .tar.gz 数据并写入指定输出流。

注意：

函数不负责 destStream 资源的释放，调用方需自行管理该输出流的生命周期。

参数：

• fromDir!: String - 待压缩的目录路径。

• destStream!: T - 压缩后数据的输出流。

• includeBaseDirectory!: Bool - 是否包含根目录。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

• ZlibException - 如果 zlib 压缩时发生错误，抛出异常。

示例：

import stdx.compress.*
import std.fs.*
import std.io.*

main(): Unit {
    // 测试路径
    let testDir = "./test_dir_stream_str"
    let testFile = "./test_dir_stream_str/test.txt"
    let destFile = "./test_stream_str.tar.gz"

    // 创建目录和文件(创建前清理)
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, TarGzip Stream Archive with String Path!".toArray())

    // 创建文件输出流
    let fileStream = File(destFile, Write)

    // 使用TarGzip压缩目录到输出流（使用字符串路径）
    TarGzip.archive(
        fromDir: testDir,
        destStream: fileStream,
        includeBaseDirectory: true
    )

    // 关闭流
    fileStream.close()

    println("Did the TarGzip archive to stream with string path complete successfully? ${exists(destFile)}")

    // 清理测试文件
    removeIfExists(testDir, recursive: true)
    removeIfExists(destFile)
}

运行结果：

Did the TarGzip archive to stream with string path complete successfully? true

static func extract(Path, Path, Bool)

public static func extract(fromTarGzip!: Path, destDir!: Path, overwrite!: Bool): Unit

功能：将 .tar.gz 文件解压至指定目录。内部先以 gzip 解压缩，再以 tar 解包。

参数：

• fromTarGzip!: Path - 待解压的 .tar.gz 文件路径。

• destDir!: Path - 解压目标目录。

• overwrite!: Bool - 若为 true，允许覆盖已存在文件、目录；否则遇到重名文件、目录将抛出异常。

异常：

• TarException - 如果 tar 提取时发生错误，抛出异常。

• ZlibException - 如果 zlib 解压时发生错误，抛出异常。

示例：

import stdx.compress.*
import std.fs.*

main(): Unit {
    // 测试路径
    let testDir = Path("./test_extract_dir")
    let testFile = Path("./test_extract_dir/test.txt")
    let archiveFile = Path("./test_extract.tar.gz")
    let extractDir = Path("./extracted_dir")

    // 创建目录和文件(创建前清理)
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, TarGzip Extract!".toArray())

    // 首先创建一个压缩文件
    TarGzip.archive(
        fromDir: testDir,
        destFile: archiveFile,
        includeBaseDirectory: true
    )

    // 清理测试目录，保留压缩文件
    removeIfExists(testDir, recursive: true)

    // 创建解压目标目录
    removeIfExists(extractDir, recursive: true)
    Directory.create(extractDir)

    // 解压文件
    TarGzip.extract(
        fromTarGzip: archiveFile,
        destDir: extractDir,
        overwrite: true
    )

    println("Did the TarGzip extract complete successfully? ${exists(extractDir)}")

    // 清理测试文件
    removeIfExists(archiveFile)
    removeIfExists(extractDir, recursive: true)
}

运行结果：

Did the TarGzip extract complete successfully? true

static func extract(String, String, Bool)

public static func extract(fromTarGzip!: String, destDir!: String, overwrite!: Bool): Unit

功能：将 .tar.gz 文件解压至指定目录。内部先以 gzip 解压缩，再以 tar 解包。

参数：

• fromTarGzip!: String - 待解压的 .tar.gz 文件路径。

• destDir!: String - 解压目标目录。

• overwrite!: Bool - 若为 true，允许覆盖已存在文件、目录；否则遇到重名文件、目录将抛出异常。

异常：

• TarException - 如果 tar 提取时发生错误，抛出异常。

• ZlibException - 如果 zlib 解压时发生错误，抛出异常。

示例：

import stdx.compress.*
import std.fs.*

main(): Unit {
    // 测试路径
    let testDir = "./test_extract_dir_str"
    let testFile = "./test_extract_dir_str/test.txt"
    let archiveFile = "./test_extract_str.tar.gz"
    let extractDir = "./extracted_dir_str"

    // 创建目录和文件(创建前清理)
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, TarGzip Extract with String Paths!".toArray())

    // 首先创建一个压缩文件
    TarGzip.archive(
        fromDir: testDir,
        destFile: archiveFile,
        includeBaseDirectory: true
    )

    // 清理测试目录，保留压缩文件
    removeIfExists(testDir, recursive: true)

    // 创建解压目标目录
    removeIfExists(extractDir, recursive: true)
    Directory.create(extractDir)

    // 解压文件（使用字符串路径）
    TarGzip.extract(
        fromTarGzip: archiveFile,
        destDir: extractDir,
        overwrite: true
    )

    println("Did the TarGzip extract with string paths complete successfully? ${exists(extractDir)}")

    // 清理测试文件
    removeIfExists(archiveFile)
    removeIfExists(extractDir, recursive: true)
}

运行结果：

Did the TarGzip extract with string paths complete successfully? true

static func extract<T>(T, Path, Bool) where T <: InputStream

public static func extract<T>(fromStream!: T, destDir!: Path, overwrite!: Bool): Unit where T <: InputStream

功能：将 .tar.gz 数据从输入流中读取并解压至指定目录。

参数：

• fromStream!: T - 待解压的 .tar.gz 数据输入流。

• destDir!: Path - 解压目标目录。

• overwrite!: Bool - 若为 true，允许覆盖已存在文件、目录；否则遇到重名文件、目录将抛出异常。

异常：

• TarException - 如果 tar 提取时发生错误，抛出异常。

• ZlibException - 如果 zlib 解压时发生错误，抛出异常。

示例：

import stdx.compress.*
import std.fs.*
import std.io.*

main(): Unit {
    // 测试路径
    let testDir = Path("./test_extract_stream_dir")
    let testFile = Path("./test_extract_stream_dir/test.txt")
    let archiveFile = Path("./test_extract_stream.tar.gz")
    let extractDir = Path("./extracted_stream_dir")

    // 创建目录和文件(创建前清理)
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, TarGzip Extract with Stream!".toArray())

    // 首先创建一个压缩文件
    TarGzip.archive(
        fromDir: testDir,
        destFile: archiveFile,
        includeBaseDirectory: true
    )

    // 清理测试目录，保留压缩文件
    removeIfExists(testDir, recursive: true)

    // 创建解压目标目录
    removeIfExists(extractDir, recursive: true)
    Directory.create(extractDir)

    // 创建输入流并从文件读取
    let inputStream = File(archiveFile, Read)

    // 从输入流解压文件
    TarGzip.extract(
        fromStream: inputStream,
        destDir: extractDir,
        overwrite: true
    )

    // 关闭输入流
    inputStream.close()

    println("Did the TarGzip extract from stream complete successfully? ${exists(extractDir)}")

    // 清理测试文件
    removeIfExists(archiveFile)
    removeIfExists(extractDir, recursive: true)
}

运行结果：

Did the TarGzip extract from stream complete successfully? true

static func extract<T>(T, String, Bool) where T <: InputStream

public static func extract<T>(fromStream!: T, destDir!: String, overwrite!: Bool): Unit where T <: InputStream

功能：将 .tar.gz 数据从输入流中读取并解压至指定目录。

参数：

• fromStream!: T - 待解压的 .tar.gz 数据输入流。

• destDir!: String - 解压目标目录。

• overwrite!: Bool - 若为 true，允许覆盖已存在文件、目录；否则遇到重名文件、目录将抛出异常。

异常：

• TarException - 如果 tar 提取时发生错误，抛出异常。

• ZlibException - 如果 zlib 解压时发生错误，抛出异常。

示例：

import stdx.compress.*
import std.fs.*
import std.io.*

main(): Unit {
    // 测试路径
    let testDir = Path("./test_extract_stream_str_dir")
    let testFile = Path("./test_extract_stream_str_dir/test.txt")
    let archiveFile = Path("./test_extract_stream_str.tar.gz")
    let extractDir = "./extracted_stream_str_dir"

    // 创建目录和文件(创建前清理)
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, TarGzip Extract with Stream and String Path!".toArray())

    // 首先创建一个压缩文件
    TarGzip.archive(
        fromDir: testDir,
        destFile: archiveFile,
        includeBaseDirectory: true
    )

    // 清理测试目录，保留压缩文件
    removeIfExists(testDir, recursive: true)

    // 创建解压目标目录
    removeIfExists(extractDir, recursive: true)
    Directory.create(extractDir)

    // 创建输入流并从文件读取
    let inputStream = File(archiveFile, Read)

    // 从输入流解压文件（目标目录使用字符串路径）
    TarGzip.extract(
        fromStream: inputStream,
        destDir: extractDir,
        overwrite: true
    )

    // 关闭输入流
    inputStream.close()

    println("Did the TarGzip extract from stream with string path complete successfully? ${exists(extractDir)}")

    // 清理测试文件
    removeIfExists(archiveFile)
    removeIfExists(extractDir, recursive: true)
}

运行结果：

Did the TarGzip extract from stream with string path complete successfully? true

stdx.compress.tar

功能介绍

compress.tar 提供了归档和读取功能。

归档是一种将多个文件或目录组织成单个文件的方法，通常用于将多个文件或目录压缩成单个文件，并保存在磁盘上。归档文件通常包含文件的元数据（如文件名、权限、时间戳等）以及文件的内容。常见的归档格式有 tar、zip、rar 等。

本包实现了 tar 归档格式，支持 V7、USTAR、PAX 和 GNU 四种格式。tar 格式广泛用于备份和分发文件的场景中。

说明：

要进行文件压缩请使用 stdx.compress.zlib 进行压缩或使用 stdx.compress 的组合工具 TarGzip 进行归档压缩操作。

规格说明

功能限制

本包当前版本存在以下功能限制：

• 不支持 ACL（访问控制列表）：归档和解归档操作不会处理文件的 ACL 信息。
• 不支持 xattr（扩展属性）：归档和解归档操作不会处理文件的扩展属性。
• 暂不支持特殊文件类型：块设备文件、字符设备文件和管道文件（FIFO）暂不支持归档和解归档。

setuid/setgid 权限位处理

解归档时，setuid/setgid 权限位会原样恢复到文件上。但实际是否恢复成功，取决于以下因素：

• 执行解归档操作的用户/进程权限
• 操作系统的安全限制

在大多数 Unix/Linux 系统中，普通用户无法设置 setgid 位，只有 root 用户或具有相应能力的进程才能成功恢复这些权限位。

uid/gid 恢复行为

解归档时，对于文件 uid/gid 的恢复行为如下：

• tar 归档文件中记录的 uid/gid 会被读取并尝试恢复到解压后的文件上
• 实际恢复是否成功，取决于执行进程的权限和操作系统限制
• 普通用户通常只能将文件的所有者设置为自己的 uid/gid，无法设置为其他用户

一键解压的条目数量限制

Tar 的一键解压方法未对解压的条目总数做限制。如果归档文件包含大量条目，可能导致资源耗尽或处理时间过长。

如需对解压条目数量进行限制，建议使用 TarReader，在迭代过程中添加自定义的限制。

API 列表

类

枚举

异常类

类

class GnuTarEntry

public class GnuTarEntry <: PosixTarEntry {
    public init(path: String)
    public init(path: Path)
}

功能：表示 Gnu tar 文件条目。

父类型：

• PosixTarEntry

prop accessTime

public prop accessTime: DateTime

功能：获取当前条目的访问时间。

类型：DateTime

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 GnuTarEntry
    var entry = GnuTarEntry(testFile)

    println("访问时间: ${entry.accessTime}")

    // 清理测试文件
    removeIfExists(testFile)
}

可能的运行结果：

访问时间: 2025-12-19T03:42:59Z

prop changeTime

public prop changeTime: DateTime

功能：获取当前条目的修改时间。

类型：DateTime

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 GnuTarEntry
    var entry = GnuTarEntry(testFile)

    println("修改时间: ${entry.changeTime}")

    // 清理测试文件
    removeIfExists(testFile)
}

可能的运行结果：

修改时间: 2025-12-19T03:45:31Z

init(Path)

public init(path: Path)

功能：从文件、目录、软链接构造一个 Gnu tar 文件条目。

参数：

• path: Path - 文件、目录、软链接的路径。

异常：

• TarException - 如果 path 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 GnuTarEntry
    var gnuEntry = GnuTarEntry(testFile)

    println("GnuTarEntry created successfully")
    println("Entry name: ${gnuEntry.name}")
    println("Entry size: ${gnuEntry.size}")

    // 清理测试文件
    removeIfExists(testFile)
}

运行结果：

GnuTarEntry created successfully
Entry name: test.txt
Entry size: 11

init(String)

public init(path: String)

功能：从文件、目录、软链接构造一个 Gnu tar 文件条目。

参数：

• path: String - 文件、目录、软链接的路径。

异常：

• TarException - 如果 path 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = "./test.txt"
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 GnuTarEntry
    var gnuEntry = GnuTarEntry(testFile)

    println("GnuTarEntry created successfully from string path")
    println("Entry name: ${gnuEntry.name}")
    println("Entry size: ${gnuEntry.size}")

    // 清理测试文件
    removeIfExists(testFile)
}

运行结果：

GnuTarEntry created successfully from string path
Entry name: test.txt
Entry size: 11

func writeTo(OutputStream)

public override func writeTo(target: OutputStream): Unit

功能：将当前条目写入到指定的输出流中。

参数：

• target: OutputStream - 指定输出流。

异常：

• TarException - 如果字段超出格式要求或写入失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 GnuTarEntry
    var entry = GnuTarEntry(testFile)

    // 创建输出流
    let outFile = File("./output.tar", Write)

    // 将条目写入输出流
    entry.writeTo(outFile)

    println("GnuTarEntry written to stream successfully")

    // 清理文件
    outFile.close()
    removeIfExists(testFile)
    removeIfExists("./output.tar")
}

运行结果：

GnuTarEntry written to stream successfully

class PaxTarEntry

public class PaxTarEntry <: PosixTarEntry {
    public init(path: String)
    public init(path: Path)
}

功能：表示 Pax tar 文件条目。

父类型：

• PosixTarEntry

init(Path)

public init(path: Path)

功能：从文件、目录、软链接构造一个 Pax tar 文件条目。

参数：

• path: Path - 文件、目录、软链接的路径。

异常：

• TarException - 如果 path 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 PaxTarEntry
    var entry = PaxTarEntry(testFile)

    println("PaxTarEntry 创建成功")
    println("条目名称: ${entry.name}")
    println("条目大小: ${entry.size}")

    // 清理测试文件
    removeIfExists(testFile)
}

运行结果：

PaxTarEntry 创建成功
条目名称: test.txt
条目大小: 11

init(String)

public init(path: String)

功能：从文件、目录、软链接构造一个 Pax tar 文件条目。

参数：

• path: String - 文件、目录、软链接的路径。

异常：

• TarException - 如果 path 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = "./test.txt"
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 使用字符串路径创建 PaxTarEntry
    var entry = PaxTarEntry(testFile)

    println("PaxTarEntry 通过字符串路径创建成功")
    println("条目名称: ${entry.name}")
    println("条目大小: ${entry.size}")

    // 清理测试文件
    removeIfExists(testFile)
}

运行结果：

PaxTarEntry 通过字符串路径创建成功
条目名称: test.txt
条目大小: 11

func getPaxData(String)

public func getPaxData(key: String): ?String

功能：获取当前条目的 Pax 数据。

参数：

• key: String - Pax 数据的键。

返回值：

• Option<String> - 如果存在对应键的 Pax 数据，则返回其值，否则返回 None。

示例：

import std.process.*
import stdx.compress.tar.*
import std.fs.*

main(): Int64 {
    // 设定路径
    let testFile = "./testFile.txt"
    let testPax = "./test.pax"

    // 创建测试文件
    File.writeTo(testFile, "文件数据...".toArray())

    // 创建 pax 文件，执行命令 "tar --format=pax --pax-option=yourKey=yourValue -cf test.pax testFile.txt"
    executeWithOutput(
        "tar",
        ["--format=pax", "--pax-option=yourKey=yourValue", "-cf", testPax, testFile]
    )

    // 创建输入流
    let inFile = File(testPax, Read)

    // 创建 TarReader
    var reader = TarReader(inFile)

    for (entry in reader) {
        if (let Some(paxEntry) <- (entry as PaxTarEntry)) {
            // 获取 Pax 数据
            let paxData = paxEntry.getPaxData("yourKey")
            println("Pax 数据: ${paxData}")
        }
    }
    // 清理测试文件
    removeIfExists(testFile)
    removeIfExists(testPax)

    return 0
}

运行结果：

Pax 数据: Some(yourValue)

func writeTo(OutputStream)

public override func writeTo(target: OutputStream): Unit

功能：将当前条目写入到指定的输出流中。

参数：

• target: OutputStream - 指定输出流。

异常：

• TarException - 如果字段超出格式要求或写入失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 PaxTarEntry
    var entry = PaxTarEntry(testFile)

    // 创建输出流
    let outFile = File("./output.tar", Write)

    // 将条目写入输出流
    entry.writeTo(outFile)

    println("PaxTarEntry 成功写入流")

    // 清理文件
    outFile.close()
    removeIfExists(testFile)
    removeIfExists("./output.tar")
}

运行结果：

PaxTarEntry 成功写入流

class PosixTarEntry

public abstract class PosixTarEntry <: TarEntry {
    protected init(path: String)
    protected init(path: Path)
}

功能：表示含有 Ustar Gnu Pax 格式共有字段的 tar 文件条目。

父类型：

• TarEntry

prop deviceMajor

public prop deviceMajor: Int32

功能：获取当前条目的设备主编号。

类型：Int32

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 PosixTarEntry
    var entry: PosixTarEntry = PaxTarEntry(testFile)

    println("Entry device major: ${entry.deviceMajor}")

    // 清理测试文件
    removeIfExists(testFile)
}

运行结果：

Entry device major: 0

prop deviceMinor

public prop deviceMinor: Int32

功能：获取当前条目的设备次编号。

类型：Int32

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 PosixTarEntry
    var entry: PosixTarEntry = PaxTarEntry(testFile)

    println("Entry device minor: ${entry.deviceMinor}")

    // 清理测试文件
    removeIfExists(testFile)
}

运行结果：

Entry device minor: 0

prop groupName

public prop groupName: String

功能：获取当前条目的组名。

类型：String

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 PosixTarEntry
    var entry: PosixTarEntry = PaxTarEntry(testFile)

    println("Entry group name: ${entry.groupName}")

    // 清理测试文件
    removeIfExists(testFile)
}

可能的运行结果：

Entry group name: yourName

prop userName

public prop userName: String

功能：获取当前条目的用户名。

类型：String

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 PosixTarEntry
    var entry: PosixTarEntry = PaxTarEntry(testFile)

    println("Entry user name: ${entry.userName}")

    // 清理测试文件
    removeIfExists(testFile)
}

可能的运行结果：

Entry user name: yourName

init(Path)

public init(path: Path)

功能：从文件、目录、软链接构造一个 tar 文件条目。

参数：

• path: Path - 文件、目录、软链接的路径。

异常：

• TarException - 如果 path 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 PosixTarEntry（PosixTarEntry本身是抽象类，不能直接实例化）
    var entry: PosixTarEntry = PaxTarEntry(testFile)

    // 清理测试文件
    removeIfExists(testFile)
}

init(String)

public init(path: String)

功能：从文件、目录、软链接构造一个 tar 文件条目。

参数：

• path: String - 文件、目录、软链接的路径。

异常：

• TarException - 如果 path 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = "./test.txt"
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 PosixTarEntry（PosixTarEntry本身是抽象类，不能直接实例化）
    var entry: PosixTarEntry = PaxTarEntry(testFile)

    // 清理测试文件
    removeIfExists(testFile)
}

class Tar

public class Tar {}

功能：归档和提取目录或流。

static func archive(Path, (Path) -> Bool, Path, Bool)

public static func archive(fromDir!: Path, filter!: (Path) -> Bool, destFile!: Path, includeBaseDirectory!: Bool): Unit

功能：配合过滤函数选择性地将指定目录归档为 .tar 文件。

参数：

• fromDir!: Path - 待归档目录。

• filter!: (Path) -> Bool - 过滤函数，会传入遍历到的目录、文件和软链接路径，返回 true 表示保留，否则丢弃。

• destFile!: Path - 输出的 .tar 文件路径。

• includeBaseDirectory!: Bool - 是否包含根目录。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 设定测试路径
    let testDir = Path("./test_dir")
    let testFile = Path("./test_dir/test.txt")

    // 创建测试目录和文件
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 归档目录
    let archiveFile = Path("./test_archive.tar")
    Tar.archive(fromDir: testDir, filter: {_: Path => true}, destFile: archiveFile, includeBaseDirectory: true)

    println("归档文件: ${archiveFile}")

    // 清理测试文件
    removeIfExists(testFile)
    removeIfExists(testDir, recursive: true)
    removeIfExists(archiveFile)
}

运行结果：

归档文件: ./test_archive.tar

static func archive(Path, Path, Bool)

public static func archive(fromDir!: Path, destFile!: Path, includeBaseDirectory!: Bool): Unit

功能：将指定目录归档为 .tar 文件。

参数：

• fromDir!: Path - 待归档的目录路径。

• destFile!: Path - 生成的 .tar 文件路径。

• includeBaseDirectory!: Bool - 是否包含目录本身作为顶级目录。若为 true，归档包内包含该目录；若为 false，仅包含其内容。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 设定测试路径
    let testDir = Path("./test_dir")
    let testFile = Path("./test_dir/test.txt")

    // 创建测试目录和文件
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 归档目录
    let archiveFile = Path("./test_archive.tar")
    Tar.archive(fromDir: testDir, destFile: archiveFile, includeBaseDirectory: true)

    println("目录归档成功")
    println("归档文件: ${archiveFile}")

    // 清理测试文件
    removeIfExists(testFile)
    removeIfExists(testDir, recursive: true)
    removeIfExists(archiveFile)
}

运行结果：

目录归档成功
归档文件: ./test_archive.tar

static func archive(String, (String) -> Bool, String, Bool)

public static func archive(fromDir!: String, filter!: (String) -> Bool, destFile!: String, includeBaseDirectory!: Bool): Unit

功能：配合过滤函数选择性地将指定目录归档为 .tar 文件。

参数：

• fromDir!: String - 待归档目录。

• filter!: (String) -> Bool - 过滤函数，会传入遍历到的目录、文件和软链接路径，返回 true 表示保留，否则丢弃。

• destFile!: String - 输出的 .tar 文件路径。

• includeBaseDirectory!: Bool - 是否包含根目录。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 设定测试路径
    let testDir = "./test_dir"
    let testFile = "./test_dir/test.txt"

    // 创建测试目录和文件
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 使用字符串路径和过滤函数归档目录
    let archiveFile = "./test_archive_filtered.tar"
    Tar.archive(fromDir: testDir, filter: {_: String => true}, destFile: archiveFile, includeBaseDirectory: true)

    println("带过滤函数的目录归档成功")
    println("归档文件: ${archiveFile}")

    // 清理测试文件
    removeIfExists(testFile)
    removeIfExists(testDir, recursive: true)
    removeIfExists(archiveFile)
}

运行结果：

带过滤函数的目录归档成功
归档文件: ./test_archive_filtered.tar

static func archive(String, String, Bool)

public static func archive(fromDir!: String, destFile!: String, includeBaseDirectory!: Bool): Unit

功能：将指定目录归档为 .tar 文件。

参数：

• fromDir!: String - 待归档的目录路径。

• destFile!: String - 生成的 .tar 文件路径。

• includeBaseDirectory!: Bool - 是否包含目录本身作为顶级目录。若为 true，归档包内包含该目录；若为 false，仅包含其内容。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 设定测试路径
    let testDir = "./test_dir"
    let testFile = "./test_dir/test.txt"

    // 创建测试目录和文件
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 使用字符串路径归档目录
    let archiveFile = "./test_archive_string.tar"
    Tar.archive(fromDir: testDir, destFile: archiveFile, includeBaseDirectory: true)

    println("使用字符串路径的目录归档成功")
    println("归档文件: ${archiveFile}")

    // 清理测试文件
    removeIfExists(testFile)
    removeIfExists(testDir, recursive: true)
    removeIfExists(archiveFile)
}

运行结果：

使用字符串路径的目录归档成功
归档文件: ./test_archive_string.tar

static func archive<T>(Path, T, Bool) where T <: OutputStream

public static func archive<T>(fromDir!: Path, destStream!: T, includeBaseDirectory!: Bool): Unit where T <: OutputStream

功能：将目录归档为 .tar 数据并写入指定输出流。

注意：

函数不负责 destStream 资源的释放，调用方需自行管理该输出流的生命周期。

参数：

• fromDir!: Path - 待归档的目录路径。

• destStream!: T - 归档后数据的输出流。

• includeBaseDirectory!: Bool - 是否包含根目录。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 设定测试路径
    let testDir = Path("./test_dir")
    let testFile = Path("./test_dir/test.txt")
    let testFileStream = Path("./test_archive_stream.tar")

    // 创建测试目录和文件
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建输出流
    let outputStream = File(testFileStream, Write)

    // 将目录归档到输出流
    Tar.archive(fromDir: testDir, destStream: outputStream, includeBaseDirectory: true)

    println("目录归档到输出流成功")

    // 清理测试文件
    outputStream.close()
    removeIfExists(testFile)
    removeIfExists(testDir, recursive: true)
    removeIfExists(testFileStream)
}

运行结果：

目录归档到输出流成功

static func archive<T>(String, T, Bool) where T <: OutputStream

public static func archive<T>(fromDir!: String, destStream!: T, includeBaseDirectory!: Bool): Unit where T <: OutputStream

功能：将目录归档为 .tar 数据并写入指定输出流。

注意：

函数不负责 destStream 资源的释放，调用方需自行管理该输出流的生命周期。

参数：

• fromDir!: String - 待归档的目录路径。

• destStream!: T - 归档后数据的输出流。

• includeBaseDirectory!: Bool - 是否包含根目录。

异常：

• TarException - 如果 tar 归档时发生错误，抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 设定测试路径
    let testDir = "./test_dir"
    let testFile = Path("./test_dir/test.txt")
    let testFileStream = Path("./test_archive_string_stream.tar")

    // 创建测试目录和文件
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建输出流
    let outputStream = File(testFileStream, Write)

    // 使用字符串路径将目录归档到输出流
    Tar.archive(fromDir: testDir, destStream: outputStream, includeBaseDirectory: true)

    println("使用字符串路径归档到输出流成功")

    // 清理测试文件
    outputStream.close()
    removeIfExists(testFile)
    removeIfExists(testDir, recursive: true)
    removeIfExists(testFileStream)
}

运行结果：

使用字符串路径归档到输出流成功

static func extract(Path, Path, Bool)

public static func extract(fromTar!: Path, destDir!: Path, overwrite!: Bool): Unit

功能：将 .tar 文件提取至指定目录。

参数：

• fromTar!: Path - 待提取的 .tar 文件路径。

• destDir!: Path - 提取目标目录。

• overwrite!: Bool - 若为 true，允许覆盖已存在文件、目录；否则遇到重名文件、目录将抛出异常。

异常：

• TarException - 如果 tar 提取时发生错误，抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 设定测试路径
    let testDir = Path("./test_dir")
    let testFile = Path("./test_dir/test.txt")

    // 创建测试目录和文件
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 归档目录
    let archiveFile = Path("./test_archive.tar")
    Tar.archive(fromDir: testDir, destFile: archiveFile, includeBaseDirectory: false)

    println("tar 归档成功")
    println("归档文件: ${archiveFile}")

    // 删除源文件
    removeIfExists(testFile)
    removeIfExists(testDir, recursive: true)

    // 解压目录
    Tar.extract(fromTar: archiveFile, destDir: testDir, overwrite: true)
    println("tar 解压成功")
    println("解压目录: ${testDir}")

    // 清理测试文件和目录
    removeIfExists(testDir, recursive: true)
    removeIfExists(archiveFile)
}

运行结果：

tar 归档成功
归档文件: ./test_archive.tar
tar 解压成功
解压目录: ./test_dir

static func extract(String, String, Bool)

public static func extract(fromTar!: String, destDir!: String, overwrite!: Bool): Unit

功能：将 .tar 文件提取至指定目录。

参数：

• fromTar!: String - 待提取的 .tar 文件路径。

• destDir!: String - 提取目标目录。

• overwrite!: Bool - 若为 true，允许覆盖已存在文件、目录；否则遇到重名文件、目录将抛出异常。

异常：

• TarException - 如果 tar 提取时发生错误，抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 设定测试路径
    let testDir = "./test_dir"
    let testFile = Path("./test_dir/test.txt")

    // 创建测试目录和文件
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 归档目录
    let archiveFile = "./test_archive.tar"
    Tar.archive(fromDir: testDir, destFile: archiveFile, includeBaseDirectory: false)

    println("tar 归档成功")
    println("归档文件: ${archiveFile}")

    // 删除源文件
    removeIfExists(testFile)
    removeIfExists(testDir, recursive: true)

    // 解压目录
    Tar.extract(fromTar: archiveFile, destDir: testDir, overwrite: true)
    println("tar 解压成功")
    println("解压目录: ${testDir}")

    // 清理测试文件和目录
    removeIfExists(testDir, recursive: true)
    removeIfExists(archiveFile)
}

运行结果：

tar 归档成功
归档文件: ./test_archive.tar
tar 解压成功
解压目录: ./test_dir

static func extract<T>(T, Path, Bool) where T <: InputStream

public static func extract<T>(fromStream!: T, destDir!: Path, overwrite!: Bool): Unit where T <: InputStream

功能：将 .tar 数据从输入流中读取并提取至指定目录。

参数：

• fromStream!: T - 待提取的 .tar 数据输入流。

• destDir!: Path - 提取目标目录。

• overwrite!: Bool - 若为 true，允许覆盖已存在文件、目录；否则遇到重名文件、目录将抛出异常。

异常：

• TarException - 如果 tar 提取时发生错误，抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 设定测试路径
    let testDir = Path("./test_dir")
    let testFile = Path("./test_dir/test.txt")
    let testFileStream = Path("./test_archive_string_stream.tar")

    // 创建测试目录和文件
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建输出流
    let outputStream = File(testFileStream, Write)

    // 将目录归档到输出流
    Tar.archive(fromDir: testDir, destStream: outputStream, includeBaseDirectory: false)

    println("归档到输出流成功")

    // 清理测试文件
    outputStream.close()
    removeIfExists(testFile)
    removeIfExists(testDir, recursive: true)

    // 创建输入流
    let inputStream = File(testFileStream, Read)
    // 提取目录
    Tar.extract(fromStream: inputStream, destDir: testDir, overwrite: true)

    println("提取目录: ${testDir}")
    println("提取完成")

    // 清理测试文件和目录
    removeIfExists(testDir, recursive: true)
    removeIfExists(testFileStream)
}

运行结果：

归档到输出流成功
提取目录: ./test_dir
提取完成

static func extract<T>(T, String, Bool) where T <: InputStream

public static func extract<T>(fromStream!: T, destDir!: String, overwrite!: Bool): Unit where T <: InputStream

功能：将 .tar 数据从输入流中读取并提取至指定目录。

参数：

• fromStream!: T - 待提取的 .tar 数据输入流。

• destDir!: String - 提取目标目录。

• overwrite!: Bool - 若为 true，允许覆盖已存在文件、目录；否则遇到重名文件、目录将抛出异常。

异常：

• TarException - 如果 tar 提取时发生错误，抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 设定测试路径
    let testDir = "./test_dir"
    let testFile = Path("./test_dir/test.txt")
    let testFileStream = Path("./test_archive_string_stream.tar")

    // 创建测试目录和文件
    removeIfExists(testDir, recursive: true)
    Directory.create(testDir)
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建输出流
    let outputStream = File(testFileStream, Write)

    // 将目录归档到输出流
    Tar.archive(fromDir: testDir, destStream: outputStream, includeBaseDirectory: false)

    println("归档到输出流成功")

    // 清理测试文件
    outputStream.close()
    removeIfExists(testFile)
    removeIfExists(testDir, recursive: true)

    // 创建输入流
    let inputStream = File(testFileStream, Read)
    // 提取目录
    Tar.extract(fromStream: inputStream, destDir: testDir, overwrite: true)

    println("提取目录: ${testDir}")
    println("提取完成")

    // 清理测试文件和目录
    removeIfExists(testDir, recursive: true)
    removeIfExists(testFileStream)
}

运行结果：

归档到输出流成功
提取目录: ./test_dir
提取完成

class TarEntry

public abstract class TarEntry {
    protected init(path: String)
    protected init(path: Path)
}

功能：表示一个 tar 文件中的条目，用于和 TarReader 和 TarWriter 进行交互。可从 TarReader 中获取 TarEntry 实例，表示 tar 归档文件中的一个条目。也可通过 TarWriter 将其写入到 tar 归档文件中。

prop entryType

public prop entryType: TarEntryType

功能：获取当前条目的条目类型。

类型：TarEntryType

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 TarEntry 实例 (使用 PaxTarEntry，因为 TarEntry 是抽象类)
    var entry: TarEntry = PaxTarEntry(testFile)

    // 获取 entryType 属性
    let entryType = entry.entryType
    println("条目类型: ${entryType}")

    // 清理测试文件
    removeIfExists(testFile)
}

运行结果：

条目类型: TarEntryType.RegularFile

prop gid

public mut prop gid: Int32

功能：获取当前条目的组 ID。

类型：Int32

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 TarEntry 实例 (使用 PaxTarEntry，因为 TarEntry 是抽象类)
    var entry: TarEntry = PaxTarEntry(testFile)

    // 获取 gid 属性
    let gid = entry.gid
    println("组ID: ${gid}")

    // 清理测试文件
    removeIfExists(testFile)
}

可能的运行结果：

组ID: 1000

prop mode

public mut prop mode: Int32

功能：获取当前条目的权限模式。

类型：Int32

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 TarEntry 实例 (使用 PaxTarEntry，因为 TarEntry 是抽象类)
    var entry: TarEntry = PaxTarEntry(testFile)

    // 获取 mode 属性
    let mode = entry.mode
    println("权限模式: ${mode}")

    // 清理测试文件
    removeIfExists(testFile)
}

可能的运行结果：

权限模式: 420

prop modificationTime

public prop modificationTime: DateTime

功能：获取当前条目的最后修改时间。

类型：DateTime

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 TarEntry 实例 (使用 PaxTarEntry，因为 TarEntry 是抽象类)
    var entry: TarEntry = PaxTarEntry(testFile)

    // 获取 modificationTime 属性
    let modTime = entry.modificationTime
    println("最后修改时间: ${modTime}")

    // 清理测试文件
    removeIfExists(testFile)
}

可能的运行结果：

最后修改时间: 2025-12-23T03:20:02Z

prop name

public mut prop name: String

功能：获取当前条目的文件名。

类型：String

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 TarEntry 实例 (使用 PaxTarEntry，因为 TarEntry 是抽象类)
    var entry: TarEntry = PaxTarEntry(testFile)

    // 获取 name 属性
    let name = entry.name
    println("文件名: ${name}")

    // 清理测试文件
    removeIfExists(testFile)
}

可能的运行结果：

文件名: test.txt

prop size

public prop size: Int64

功能：获取当前条目的大小。

类型：Int64

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 TarEntry 实例 (使用 PaxTarEntry，因为 TarEntry 是抽象类)
    var entry: TarEntry = PaxTarEntry(testFile)

    // 获取 size 属性
    let size = entry.size
    println("大小: ${size}")

    // 清理测试文件
    removeIfExists(testFile)
}

运行结果：

大小: 11

prop stream

public prop stream: ?InputStream

功能：获取当前条目的输入流。如果实例由 TarReader 创建，则本属性返回流中为条目的数据，若条目没有数据则返回 None。如果实例由构造函数创建，则本属性返回的是创建的文件流，传入 TarWriter 时会调用该属性用于写入条目数据。

类型：Option<InputStream>

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 TarEntry 实例 (使用 PaxTarEntry，因为 TarEntry 是抽象类)
    var entry: TarEntry = PaxTarEntry(testFile)

    // 获取 stream 属性
    let stream = entry.stream

    // 清理测试文件
    removeIfExists(testFile)
}

prop uid

public mut prop uid: Int32

功能：获取当前条目的用户 ID。

类型：Int32

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 TarEntry 实例 (使用 PaxTarEntry，因为 TarEntry 是抽象类)
    var entry: TarEntry = PaxTarEntry(testFile)

    // 获取 uid 属性
    let uid = entry.uid
    println("用户ID: ${uid}")

    // 清理测试文件
    removeIfExists(testFile)
}

可能的运行结果：

用户ID: 1000

init(Path)

protected init(path: Path)

功能：从文件、目录、软链接构造一个 tar 文件条目。

参数：

• path: Path - 文件、目录、软链接的路径。

异常：

• TarException - 如果 path 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 使用 Path 参数构造一个 TarEntry 实例 (使用 PaxTarEntry，因为 TarEntry 是抽象类)
    var entry: TarEntry = PaxTarEntry(testFile)

    println("TarEntry 使用 Path 构造成功")
    println("文件名: ${entry.name}")

    // 清理测试文件
    removeIfExists(testFile)
}

运行结果：

TarEntry 使用 Path 构造成功
文件名: test.txt

init(String)

protected init(path: String)

功能：从文件、目录、软链接构造一个 tar 文件条目。

参数：

• path: String - 文件、目录、软链接的路径。

异常：

• TarException - 如果 path 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = "./test.txt"
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 使用 String 参数构造一个 TarEntry 实例 (使用 PaxTarEntry，因为 TarEntry 是抽象类)
    var entry: TarEntry = PaxTarEntry(testFile)

    println("TarEntry 使用 String 构造成功")
    println("文件名: ${entry.name}")

    // 清理测试文件
    removeIfExists(testFile)
}

运行结果：

TarEntry 使用 String 构造成功
文件名: test.txt

func writeTo(OutputStream)

public open func writeTo(target: OutputStream): Unit

功能：将当前条目写入到指定的输出流中。

参数：

• target: OutputStream - 指定输出流。

异常：

• TarException - 如果字段超出格式要求或写入失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建一个 TarEntry 实例 (使用 PaxTarEntry，因为 TarEntry 是抽象类)
    var entry: TarEntry = PaxTarEntry(testFile)

    // 创建输出流
    let outputFile = Path("./output.tar")
    let outputStream = File(outputFile, Write)

    // 调用 writeTo 方法
    entry.writeTo(outputStream)

    println("writeTo 方法调用成功")

    // 清理流和文件
    outputStream.close()

    // 清理测试文件
    removeIfExists(testFile)
    removeIfExists(outputFile)
}

运行结果：

writeTo 方法调用成功

class TarReader

public class TarReader<T> <: Iterable<TarEntry> where T <: InputStream {
    public init(stream: T)
}

功能：从流中按照 tar 格式读取条目。

init(T)

public init(stream: T)

功能：从指定的流中创建一个 tar 文件读取器。

参数：

• stream: T - 指定的输入流。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.process.*

main(): Unit {
    // 设定路径
    let testFile01 = "./testFile01.txt"
    let testFile02 = "./testFile02.txt"
    let testTar = "./test.tar"

    // 创建测试文件
    File.writeTo(testFile01, "文件数据...123".toArray())
    File.writeTo(testFile02, "文件数据...123456".toArray())

    // 创建 tar 文件，执行命令 "tar -cf test.tar testFile.txt"
    executeWithOutput("tar", ["-cf", testTar, testFile01, testFile02])

    // 创建一个 TarReader 实例
    let fileStream = File(testTar, Read)
    var reader = TarReader(fileStream)

    println("TarReader 创建成功")

    // 清理测试文件
    fileStream.close()
    removeIfExists(testFile01)
    removeIfExists(testFile02)
}

运行结果：

TarReader 创建成功

func iterator()

public func iterator(): Iterator<TarEntry>

功能：返回一个迭代器，迭代 tar 文件中的条目。

返回值：

• Iterator<TarEntry> - 一个 TarEntry 的迭代器。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.process.*

main(): Unit {
    // 设定路径
    let testFile01 = "./testFile01.txt"
    let testFile02 = "./testFile02.txt"
    let testTar = "./test.tar"

    // 创建测试文件
    File.writeTo(testFile01, "文件数据...123".toArray())
    File.writeTo(testFile02, "文件数据...123456".toArray())

    // 创建 tar 文件，执行命令 "tar -cf test.tar testFile.txt"
    executeWithOutput("tar", ["-cf", testTar, testFile01, testFile02])

    // 创建一个 TarReader 实例
    let fileStream = File(testTar, Read)
    var reader = TarReader(fileStream)

    // 获取迭代器
    var iterator = reader.iterator()

    for (entry in iterator) {
        println("条目名称: ${entry.name}")
        println("条目大小: ${entry.size}")
    }
    // 清理测试文件
    fileStream.close()
    removeIfExists(testFile01)
    removeIfExists(testFile02)
}

运行结果：

条目名称: testFile01.txt
条目大小: 18
条目名称: testFile02.txt
条目大小: 21

extend<T> TarReader<T> <: Resource where T <: Resource

extend<T> TarReader<T> <: Resource where T <: Resource

功能：为 TarReader 实现 Resource 接口，该类型对象可在 try-with-resource 语法上下文中实现自动资源释放。

父类型：

• Resource

func close()

public func close(): Unit

功能：关闭内部流。

注意：

调用此方法后不可再调用 TarReader 的其他接口，否则会造成不可期现象。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.InputStream
import std.process.*

main(): Unit {
    // 设定路径
    let testFile01 = "./testFile01.txt"
    let testFile02 = "./testFile02.txt"
    let testTar = "./test.tar"

    // 创建测试文件
    File.writeTo(testFile01, "文件数据...123".toArray())
    File.writeTo(testFile02, "文件数据...123456".toArray())

    // 创建 tar 文件，执行命令 "tar -cf test.tar testFile.txt"
    executeWithOutput("tar", ["-cf", testTar, testFile01, testFile02])

    // 创建一个 TarReader 实例
    let fileStream = File(testTar, Read)
    var reader = TarReader(fileStream)

    // 关闭 TarReader
    reader.close()

    println("TarReader 关闭成功")

    // 清理测试文件
    removeIfExists(testFile01)
    removeIfExists(testFile02)
}

运行结果：

TarReader 关闭成功

func isClosed()

public func isClosed(): Bool

功能：判断内部流是否关闭。

返回值：

• Bool - 如果内部流已经被关闭，返回 true，否则返回 false。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.InputStream
import std.process.*

main(): Unit {
    // 设定路径
    let testFile01 = "./testFile01.txt"
    let testFile02 = "./testFile02.txt"
    let testTar = "./test.tar"

    // 创建测试文件
    File.writeTo(testFile01, "文件数据...123".toArray())
    File.writeTo(testFile02, "文件数据...123456".toArray())

    // 创建 tar 文件，执行命令 "tar -cf test.tar testFile.txt"
    executeWithOutput("tar", ["-cf", testTar, testFile01, testFile02])

    // 创建一个 TarReader 实例
    let fileStream = File(testTar, Read)
    var reader = TarReader(fileStream)

    // 检查是否已关闭
    let isClosedBefore = reader.isClosed()
    println("关闭前状态: ${isClosedBefore}")

    // 关闭 TarReader
    reader.close()

    // 再次检查是否已关闭
    let isClosedAfter = reader.isClosed()
    println("关闭后状态: ${isClosedAfter}")

    // 清理测试文件
    removeIfExists(testFile01)
    removeIfExists(testFile02)
}

运行结果：

关闭前状态: false
关闭后状态: true

class TarWriter

public class TarWriter<T> where T <: OutputStream {
    public init(stream: T)
    public init(stream: T, format: TarEntryFormat)
}

功能：将条目写入到流中，并完成 tar 文件的写入。

prop format

public prop format: TarEntryFormat

功能：获取当前 tar 文件的条目格式。

类型：TarEntryFormat

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建输出流
    let outputFile = Path("./test.tar")
    let outputStream = File(outputFile, Write)

    // 创建一个 TarWriter 实例
    var writer = TarWriter(outputStream)

    // 获取 format 属性
    let format = writer.format
    println("TarWriter 格式: ${format}")

    // 清理资源
    writer.close()

    // 清理测试文件
    removeIfExists(outputFile)
}

运行结果：

TarWriter 格式: TarEntryFormat.Pax

init(T)

public init(stream: T)

功能：从指定的流中创建一个 tar 文件写入器，默认为 Pax 格式。

参数：

• stream: T - 指定的输出流。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建输出流
    let outputFile = Path("./test.tar")
    let outputStream = File(outputFile, Write)

    // 创建一个 TarWriter 实例（使用默认格式）
    var writer = TarWriter(outputStream)

    println("TarWriter 创建成功")

    // 清理资源
    writer.close()

    // 清理测试文件
    removeIfExists(outputFile)
}

运行结果：

TarWriter 创建成功

init(T, TarEntryFormat)

public init(stream: T, format: TarEntryFormat)

功能：从指定的流中创建一个 tar 文件写入器。

参数：

• stream: T - 指定的输出流。

• format: TarEntryFormat - tar 文件的条目格式。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建输出流
    let outputFile = Path("./test.tar")
    let outputStream = File(outputFile, Write)

    // 创建一个 TarWriter 实例（指定格式）
    var writer = TarWriter(outputStream, TarEntryFormat.Gnu)

    println("TarWriter 指定格式创建成功")
    println("格式: ${writer.format}")

    // 清理资源
    writer.close()

    // 清理测试文件
    removeIfExists(outputFile)
}

运行结果：

TarWriter 指定格式创建成功
格式: TarEntryFormat.Gnu

func finish()

public func finish(): Unit

功能：写入 tar 结尾标志，即 1024 个空字节，结束 tar 格式的写入。

异常：

• TarException - 如果写入已结束，或者写入失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 TarWriter
    let outFile = File("./test.tar", ReadWrite)
    var writer = TarWriter(outFile)

    // 写入文件
    writer.write(testFile, entryName: "test_entry.txt")
    println("File size before finish: ${outFile.info.size}")
    writer.finish()
    println("File size after finish: ${outFile.info.size}")

    // 清理测试文件
    writer.close()
    removeIfExists(testFile)
    removeIfExists("./test.tar")
}

运行结果：

File size before finish: 1024
File size after finish: 2048

func flush()

public func flush(): Unit

功能：刷新内部流。

异常：

• TarException - 如果写入已结束（调用 finish() 之后），则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建输出流
    let outputFile = Path("./test.tar")
    let outputStream = File(outputFile, Write)

    // 创建一个 TarWriter 实例
    var writer = TarWriter(outputStream)

    // 刷新内部流
    writer.flush()

    println("TarWriter flush() 调用成功")

    // 清理资源
    writer.close()

    // 清理测试文件
    removeIfExists(outputFile)
}

运行结果：

TarWriter flush() 调用成功

func write(FileInfo, String)

public func write(info: FileInfo, entryName!: String): Unit

功能：将指定文件、目录、软链接写入到内部流中。

参数：

• info: FileInfo - 待写入的文件、目录、软链接信息。

• entryName!: String - tar 文件中的条目名。

异常：

• TarException - 如果写入已结束，或者创建或写入条目失败，则抛出异常。

• FSException - 如果创建文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())
    let file = File(testFile, Read)

    // 创建 TarWriter
    let outFile = File("./test.tar", ReadWrite)
    var writer = TarWriter(outFile)

    // 通过文件信息info写入文件
    writer.write(file.info, entryName: "test_entry.txt")
    writer.finish()

    // 清理测试文件
    writer.close()
    removeIfExists(testFile)
    removeIfExists("./test.tar")
}

func write(Iterable<TarEntry>)

public func write(it: Iterable<TarEntry>): Unit

功能：将指定 tar 文件条目列表写入到内部流中。

参数：

• it: Iterable<TarEntry> - 待写入的 tar 文件条目列表。

异常：

• TarException - 如果写入已结束，或者写入条目失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.collection.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建输出流
    let outputFile = Path("./test.tar")
    let outputStream = File(outputFile, Write)

    // 创建一个 TarWriter 实例
    var writer = TarWriter(outputStream)

    // 创建 TarEntry 列表
    var entry = PaxTarEntry(testFile)
    var entries = ArrayList<TarEntry>()
    entries.add(entry)

    // 写入 TarEntry 列表
    writer.write(entries)

    println("write(Iterable<TarEntry>) 调用成功，写入了 ${outputFile}")

    // 清理资源
    writer.finish()
    writer.close()

    // 清理测试文件
    removeIfExists(testFile)
    removeIfExists(outputFile)
}

运行结果：

write(Iterable<TarEntry>) 调用成功，写入了 ./test.tar

func write(Path, String)

public func write(path: Path, entryName!: String): Unit

功能：将指定文件、目录、软链接写入到内部流中。

参数：

• path: Path - 指定文件、目录、软链接路径。

• entryName!: String - tar 文件中的条目名。

异常：

• TarException - 如果写入已结束，或者创建或写入条目失败，则抛出异常。

• FSException - 如果创建文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 TarWriter
    let outFile = File("./test.tar", ReadWrite)
    var writer = TarWriter(outFile)

    // 通过路径写入文件
    writer.write(testFile, entryName: "test_entry.txt")
    writer.finish()

    // 清理测试文件
    writer.close()
    removeIfExists(testFile)
    removeIfExists("./test.tar")
}

func write(String, String)

public func write(path!: String, entryName!: String): Unit

功能：将指定文件、目录、软链接写入到内部流中。

参数：

• path!: String - 指定文件、目录、软链接的路径。

• entryName!: String - tar 文件中的条目名。

异常：

• TarException - 如果写入已结束，或者创建或写入条目失败，则抛出异常。

• FSException - 如果创建文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建测试文件
    let testFile = "./test.txt"
    File.writeTo(Path(testFile), "Hello, Tar!".toArray())

    // 创建 TarWriter 并写入文件
    let outFile = File("./test.tar", Write)
    var writer = TarWriter(outFile)

    // 通过路径字符串写入
    writer.write(path: testFile, entryName: "test_entry.txt")
    writer.finish()

    // 清理测试文件
    writer.close()
    removeIfExists(testFile)
    removeIfExists("./test.tar")
}

func write(TarEntry)

public func write(entry: TarEntry): Unit

功能：将指定 tar 文件条目写入到内部流中。

参数：

• entry: TarEntry - 待写入的 tar 文件条目。

异常：

• TarException - 如果写入已结束，或者写入条目失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建输出流
    let outputFile = Path("./test.tar")
    let outputStream = File(outputFile, Write)

    // 创建一个 TarWriter 实例
    var writer = TarWriter(outputStream)

    // 创建一个 TarEntry
    var entry = PaxTarEntry(testFile)

    // 写入 TarEntry
    writer.write(entry)

    println("TarWriter write(TarEntry) 调用成功")

    // 清理资源
    writer.finish()
    writer.close()

    // 清理测试文件
    removeIfExists(testFile)
    removeIfExists(outputFile)
}

运行结果：

TarWriter write(TarEntry) 调用成功

extend<T> TarWriter<T> <: Resource where T <: Resource

extend<T> TarWriter<T> <: Resource where T <: Resource

功能：为 TarWriter 实现 Resource 接口，该类型对象可在 try-with-resource 语法上下文中实现自动资源释放。

父类型：

• Resource

func close()

public func close(): Unit

功能：写入 tar 结尾标志，并关闭内部流。

注意：

调用此方法后不可再调用 TarWriter 的其他接口，否则会造成不可期现象。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建输出流
    let outputFile = Path("./test.tar")
    let outputStream = File(outputFile, Write)

    // 创建一个 TarWriter 实例
    var writer = TarWriter(outputStream)

    // 关闭 TarWriter
    writer.close()

    println("TarWriter close() 调用成功")

    // 清理测试文件
    removeIfExists(outputFile)
}

运行结果：

TarWriter close() 调用成功

func isClosed()

public func isClosed(): Bool

功能：判断内部流是否关闭。

返回值：

• Bool - 如果内部流已经被关闭，返回 true，否则返回 false。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建输出流
    let outputFile = Path("./test.tar")
    let outputStream = File(outputFile, Write)

    // 创建一个 TarWriter 实例
    var writer = TarWriter(outputStream)

    // 检查是否已关闭
    let isClosedBefore = writer.isClosed()
    println("关闭前状态: ${isClosedBefore}")

    // 关闭 TarWriter
    writer.close()

    // 再次检查是否已关闭
    let isClosedAfter = writer.isClosed()
    println("关闭后状态: ${isClosedAfter}")

    // 清理测试文件
    removeIfExists(outputFile)
}

运行结果：

关闭前状态: false
关闭后状态: true

class UstarTarEntry

public class UstarTarEntry <: PosixTarEntry {
    public init(path: String)
    public init(path: Path)
}

功能：表示 Ustar tar 文件条目。

父类型：

• PosixTarEntry

init(Path)

public init(path: Path)

功能：从文件、目录、软链接构造一个 Ustar tar 文件条目。

参数：

• path: Path - 文件、目录、软链接的路径。

异常：

• TarException - 如果 path 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 UstarTarEntry
    var ustarEntry = UstarTarEntry(testFile)

    println("UstarTarEntry created successfully")
    println("Entry name: ${ustarEntry.name}")
    println("Entry size: ${ustarEntry.size}")

    // 清理测试文件
    remove(testFile)
}

运行结果：

UstarTarEntry created successfully
Entry name: test.txt
Entry size: 11

init(String)

public init(path: String)

功能：从文件、目录、软链接构造一个 Ustar tar 文件条目。

参数：

• path: String - 文件、目录、软链接的路径。

异常：

• TarException - 如果 path 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = "./test.txt"
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 UstarTarEntry
    var ustarEntry = UstarTarEntry(testFile)

    println("UstarTarEntry created successfully from string path")
    println("Entry name: ${ustarEntry.name}")
    println("Entry size: ${ustarEntry.size}")

    // 清理测试文件
    remove(testFile)
}

运行结果：

UstarTarEntry created successfully from string path
Entry name: test.txt
Entry size: 11

func writeTo(OutputStream)

public override func writeTo(target: OutputStream): Unit

功能：将当前条目写入到指定的输出流中。

参数：

• target: OutputStream - 指定输出流。

异常：

• TarException - 如果字段超出格式要求或写入失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 UstarTarEntry
    var entry = UstarTarEntry(testFile)

    // 创建输出流
    let outFile = File("./output.tar", Write)

    // 将条目写入输出流
    entry.writeTo(outFile)

    println("UstarTarEntry written to stream successfully")

    // 清理文件
    outFile.close()
    remove(testFile)
    remove("./output.tar")
}

运行结果：

UstarTarEntry written to stream successfully

class V7TarEntry

public class V7TarEntry <: TarEntry {
    public init(filePath: String)
    public init(filePath: Path)
}

功能：表示 V7 tar 文件条目。

父类型：

• TarEntry

init(Path)

public init(filePath: Path)

功能：从文件、目录、软链接构造一个 V7 tar 文件条目。

参数：

• filePath: Path - 文件、目录、软链接的路径。

异常：

• TarException - 如果 filePath 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = Path("./test.txt")
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 V7TarEntry
    var v7Entry = V7TarEntry(testFile)

    println("V7TarEntry created successfully")
    println("Entry name: ${v7Entry.name}")
    println("Entry size: ${v7Entry.size}")

    // 清理测试文件
    remove(testFile)
}

运行结果：

V7TarEntry created successfully
Entry name: test.txt
Entry size: 11

init(String)

public init(filePath: String)

功能：从文件、目录、软链接构造一个 V7 tar 文件条目。

参数：

• filePath: String - 文件、目录、软链接的路径。

异常：

• TarException - 如果 filePath 参数指定的目标不存在或不是文件、目录、软链接，则抛出异常。

• FSException - 如果读取目标信息或创建目标文件流失败，则抛出异常。

示例：

import stdx.compress.tar.*
import std.fs.*

main(): Unit {
    // 创建测试文件
    let testFile = "./test.txt"
    File.writeTo(testFile, "Hello, Tar!".toArray())

    // 创建 V7TarEntry
    var v7Entry = V7TarEntry(testFile)

    println("V7TarEntry created successfully from string path")
    println("Entry name: ${v7Entry.name}")
    println("Entry size: ${v7Entry.size}")

    // 清理测试文件
    remove(testFile)
}

运行结果：

V7TarEntry created successfully from string path
Entry name: test.txt
Entry size: 11

枚举

enum TarEntryFormat

public enum TarEntryFormat {
    | V7
    | Ustar
    | Pax
    | Gnu
}

功能：tar 条目格式。

该枚举表示不同版本的 tar 文件头部格式，用于区分各格式在元数据与扩展字段上的支持程度。

Gnu

Gnu

功能：构造一个 GNU 扩展格式枚举实例。

Pax

Pax

功能：构造一个 PAX 格式枚举实例，表示 POSIX.1-2001 扩展格式，兼容 USTAR，并可通过扩展头记录额外元数据。

Ustar

Ustar

功能：构造一个 USTAR 格式枚举实例，表示 POSIX.1-1988 定义的标准格式。

V7

V7

功能：构造一个 V7 格式枚举实例，表示最初的 UNIX 第七版 tar 格式（1979）。

func toString(): String

public func toString(): String

功能：返回当前 tar 文件头部格式枚举实例的 字符串表示。

返回值：

• String - 当前 tar 文件头部格式枚举实例的 字符串表示。

示例：

import stdx.compress.tar.*

main(): Unit {
    let format = TarEntryFormat.Pax
    println("Tar entry format: ${format}")
}

运行结果：

Tar entry format: TarEntryFormat.Pax

operator func !=(TarEntryFormat): Bool

operator func !=(rhs: TarEntryFormat): Bool

功能：判断当前 tar 文件头部格式枚举实例是否与传入的 tar 文件头部格式枚举实例不相等。

参数：

• rhs: TarEntryFormat - 要比较的 tar 文件头部格式枚举实例。

返回值：

• Bool - 如果两个 tar 文件头部格式枚举实例不相等，则返回 true；否则返回 false。

示例：

import stdx.compress.tar.*

main(): Unit {
    let format1 = TarEntryFormat.Pax
    let format2 = TarEntryFormat.Gnu

    if (format1 != format2) {
        println("${format1} is not equal to ${format2}")
    } else {
        println("${format1} is equal to ${format2}")
    }
}

运行结果：

TarEntryFormat.Pax is not equal to TarEntryFormat.Gnu

operator func ==(TarEntryFormat): Bool

operator func ==(rhs: TarEntryFormat): Bool

功能：判断当前 tar 文件头部格式枚举实例是否与传入的 tar 文件头部格式枚举实例相等。

参数：

• rhs: TarEntryFormat - 要比较的 tar 文件头部格式枚举实例。

返回值：

• Bool - 如果两个 tar 文件头部格式枚举实例相等，则返回 true；否则返回 false。

示例：

import stdx.compress.tar.*

main(): Unit {
    let format1 = TarEntryFormat.Pax
    let format2 = TarEntryFormat.Pax
    let format3 = TarEntryFormat.Gnu

    if (format1 == format2) {
        println("${format1} is equal to ${format2}")
    } else {
        println("${format1} is not equal to ${format2}")
    }

    if (format1 == format3) {
        println("${format1} is equal to ${format3}")
    } else {
        println("${format1} is not equal to ${format3}")
    }
}

运行结果：

TarEntryFormat.Pax is equal to TarEntryFormat.Pax
TarEntryFormat.Pax is not equal to TarEntryFormat.Gnu

enum TarEntryType

public enum TarEntryType {
    | V7RegularFile
    | RegularFile
    | ContiguousFile
    | HardLink
    | Symlink
    | CharDevice
    | BlockDevice
    | Directory
    | Fifo
    | ExtendedHeader
    | GlobalExtendedHeader
    | GnuLongName
    | GnuLongLink
    | GnuSparse
    | GnuDumpDir
    | GnuMultiVolume
    | GnuName
    | GnuVolumeHeader
    | Unknown(UInt8)
}

功能：tar 条目类型。

该枚举定义了所有 tar 文件条目的类型，对应 tar 头部中的 typeflag 字段。

BlockDevice

BlockDevice

功能：构造一个块设备文件类型枚举实例，对应 typeflag '4'。

CharDevice

CharDevice

功能：构造一个字符设备文件类型枚举实例，对应 typeflag '3'。

ContiguousFile

ContiguousFile

功能：构造一个连续文件类型枚举实例，用于表示数据在存储介质上连续排列的文件（typeflag '7'）。

Directory

Directory

功能：构造一个目录类型枚举实例，对应 typeflag '5'。

ExtendedHeader

ExtendedHeader

功能：构造一个 PAX 扩展头类型枚举实例，对应 typeflag 'x'，用于存储附加元数据。

Fifo

Fifo

功能：构造一个命名管道（FIFO）类型枚举实例，对应 typeflag '6'。

GlobalExtendedHeader

GlobalExtendedHeader

功能：构造一个 PAX 全局扩展头类型枚举实例，对应 typeflag 'g'，适用于作用于整个归档的全局元信息。

GnuDumpDir

GnuDumpDir

功能：构造一个 GNU Dump 目录类型枚举实例，对应 typeflag 'D'。

GnuLongLink

GnuLongLink

功能：构造一个 GNU 长链接名扩展类型枚举实例，对应 typeflag 'K'。

GnuLongName

GnuLongName

功能：构造一个 GNU 长文件名扩展类型枚举实例，对应 typeflag 'L'。

GnuMultiVolume

GnuMultiVolume

功能：构造一个 GNU 多卷归档条目类型枚举实例，对应 typeflag 'M'。

GnuName

GnuName

功能：构造一个 GNU 文件名表条目类型枚举实例，对应 typeflag 'N'。

GnuSparse

GnuSparse

功能：构造一个 GNU 稀疏文件类型枚举实例，对应 typeflag 'S'。

GnuVolumeHeader

GnuVolumeHeader

功能：构造一个 GNU 卷头条目类型枚举实例，对应 typeflag 'V'。

HardLink

HardLink

功能：构造一个硬链接类型枚举实例，对应 typeflag '1'。

RegularFile

RegularFile

功能：构造一个标准普通文件类型枚举实例，对应 POSIX/USTAR 格式中的普通文件（typeflag '0'）。

Symlink

Symlink

功能：构造一个符号链接类型枚举实例，对应 typeflag '2'。

Unknown(UInt8)

Unknown(UInt8)

功能：构造一个未知类型条目枚举实例，用于保留无法识别或自定义的 typeflag 字节值。

V7RegularFile

V7RegularFile

功能：构造一个 V7 格式的普通文件类型枚举实例，对应早期 Unix V7 格式（typeflag \0）。

prop flag

public prop flag: UInt8

功能：获取当前条目的 typeflag 字节值。

类型：UInt8

示例：

import stdx.compress.tar.*

main(): Unit {
    let fileType = TarEntryType.RegularFile
    println("Tar entry type flag: ${fileType.flag}")
}

运行结果：

Tar entry type flag: 48

static func fromFlag(UInt8)

public static func fromFlag(flag: UInt8): TarEntryType

功能：根据传入的 typeflag 字节值构造对应的 TarEntryType 枚举实例。

参数：

• flag: UInt8 - tar 头部中 typeflag 的字节值。

返回值：

• TarEntryType - 对应的条目类型枚举实例。如果无法识别，将返回 Unknown(flag)。

示例：

import stdx.compress.tar.*

main(): Unit {
    let fileType = TarEntryType.fromFlag(48) // 48 is the flag for RegularFile
    println("Tar entry type from flag 48: ${fileType}")

    let unknownType = TarEntryType.fromFlag(99) // 99 is an unknown flag
    println("Tar entry type from unknown flag 99: ${unknownType}")
}

运行结果：

Tar entry type from flag 48: TarEntryType.RegularFile
Tar entry type from unknown flag 99: TarEntryType.Unknown(99)

func toString(): String

public func toString(): String

功能：返回当前条目类型枚举实例的字符串表示。

返回值：

• String - 当前条目类型枚举实例的字符串表示。

示例：

import stdx.compress.tar.*

main(): Unit {
    let fileType = TarEntryType.RegularFile
    println("Tar entry type: ${fileType.toString()}")

    let dirType = TarEntryType.Directory
    println("Tar entry type: ${dirType.toString()}")
}

运行结果：

Tar entry type: TarEntryType.RegularFile
Tar entry type: TarEntryType.Directory

operator func !=(TarEntryType): Bool

operator func !=(rhs: TarEntryType): Bool

功能：判断当前条目类型枚举实例是否与传入的条目类型枚举实例不相等。

参数：

• rhs: TarEntryType - 要比较的条目类型枚举实例。

返回值：

• Bool - 如果两个条目类型枚举实例不相等，则返回 true；否则返回 false。

示例：

import stdx.compress.tar.*

main(): Unit {
    let fileType = TarEntryType.RegularFile
    let dirType = TarEntryType.Directory

    if (fileType != dirType) {
        println("${fileType} is not equal to ${dirType}")
    } else {
        println("${fileType} is equal to ${dirType}")
    }
}

运行结果：

TarEntryType.RegularFile is not equal to TarEntryType.Directory

operator func ==(TarEntryType): Bool

operator func ==(rhs: TarEntryType): Bool

功能：判断当前条目类型枚举实例是否与传入的条目类型枚举实例相等。

参数：

• rhs: TarEntryType - 要比较的条目类型枚举实例。

返回值：

• Bool - 如果两个条目类型枚举实例相等，则返回 true；否则返回 false。

示例：

import stdx.compress.tar.*

main(): Unit {
    let fileType1 = TarEntryType.RegularFile
    let fileType2 = TarEntryType.RegularFile
    let dirType = TarEntryType.Directory

    if (fileType1 == fileType2) {
        println("${fileType1} is equal to ${fileType2}")
    } else {
        println("${fileType1} is not equal to ${fileType2}")
    }

    if (fileType1 == dirType) {
        println("${fileType1} is equal to ${dirType}")
    } else {
        println("${fileType1} is not equal to ${dirType}")
    }
}

运行结果：

TarEntryType.RegularFile is equal to TarEntryType.RegularFile
TarEntryType.RegularFile is not equal to TarEntryType.Directory

异常类

class TarException

public class TarException <: Exception {
    public init(message: String)
}

功能：tar 包的异常类。

父类型：

• Exception

init(String)

public init(message: String)

功能：根据异常信息创建 TarException 实例。

参数：

• message: String - 异常提示信息。

示例：

import stdx.compress.tar.*

main(): Unit {
    try {
        throw TarException("This is a test exception")
    } catch (e: TarException) {
        println("捕获到 TarException: ${e.message}")
    }
}

运行结果：

捕获到 TarException: This is a test exception

Tar 格式数据的归档与提取

示例：

import stdx.compress.tar.*
import std.fs.*
import std.io.*

main() {
    let originalFile = Path("./tgz_src.txt")
    let archiveFile = Path("./archive.tar")
    let extractedFile = Path("./tgz_dst.txt")
    let size = 1024 * 1024

    createFile(originalFile, size)

    let tgzSize = archive(originalFile, archiveFile)
    if (tgzSize > 0) {
        println("Pack(.tar) size: ${tgzSize}")
    } else {
        println("Failed to pack .tar!")
    }

    let extractedBytes = extract(archiveFile, extractedFile)
    if (extractedBytes > 0) {
        println("Unpacked bytes: ${extractedBytes}")
    } else {
        println("Failed to unpack .tar!")
    }

    if (compareFile(originalFile, extractedFile)) {
        println("success")
    } else {
        println("failed")
    }

    remove(originalFile)
    remove(archiveFile)
    remove(extractedFile)
    return 0
}

func archive(srcFileName: Path, tarFileName: Path): Int64 {
    try (outFile: File = File(tarFileName, Write)) {
        var tar = TarWriter(outFile)

        tar.write(srcFileName, entryName: srcFileName.fileName)
        tar.finish()

        return outFile.length
    }
    return 0
}

func extract(tarFileName: Path, destFileName: Path): Int64 {
    var written: Int64 = 0
    try (inFile: File = File(tarFileName, Read), outFile: File = File(destFileName, Write)) {
        var reader = TarReader(inFile)
        for (entry in reader) {
            if (entry.entryType == TarEntryType.RegularFile) {
                if (let Some(data) <- entry.stream) {
                    written = copy(data, to: outFile)
                    break
                }
            }
        }
    }
    return written
}

func createFile(file: Path, size: Int64) {
    File.writeTo(file, Array<Byte>(size, {i => UInt8(i % 256)}))
}

func compareFile(fileName1: Path, fileName2: Path): Bool {
    return File.readFrom(fileName1) == File.readFrom(fileName2)
}

运行结果：

Pack(.tar) size: 1050112
Unpacked bytes: 1048576
success

stdx.compress.zlib

功能介绍

compress.zlib 提供压缩解压功能。

压缩是指用更少的比特表示数据，以便更高效地存储和传输数据。在实际应用中，压缩广泛应用于文件压缩、网页压缩、数据库备份等。

压缩功能的实现依赖于压缩算法，主流的压缩算法有 deflate、lz77、lzw 等，这些算法可以将数据中的冗余信息去除或者替换成更紧凑的表示形式，从而实现数据压缩的目的。目前使用 deflate 算法。

基于 deflate 压缩算法，给压缩后数据加上首部和尾部，可封装成不同格式的压缩文件，如 deflate-raw（无封装）、gzip、zip、png 等。其中 zip 可用于多个文件的压缩和打包，gzip 仅包含一个压缩文件。目前支持的数据格式有 deflate-raw 和 gzip，暂不支持文件打包功能。

此外，支持设置压缩级别，更高的压缩级别对应着更高的压缩率和更慢的压缩速度，反之，更低的压缩级别对应着更低的压缩率和更快的压缩速度。

特别地，zlib 指的是压缩功能的一个实现库，zlib 包实现了 deflate 算法，并支持 deflate-raw 和 gzip 压缩格式。

本包基于开源库 zlib，使用 deflate 算法，支持 deflate-raw 和 gzip 数据格式，支持快速、默认、高压缩率三种压缩等级，压缩速度依次下降，压缩率依次提升。

本包提供流式压缩和解压功能，即支持从输入流读取数据，将其压缩或解压，并写入字节数组，或从字节数组中读取数据，将其压缩或解压，并写入输出流。

说明：

要进行文件打包请使用 stdx.compress.tar 进行归档或使用 stdx.compress 的组合工具 TarGzip 进行归档压缩操作。

API 列表

类

枚举

异常类

类

class CompressInputStream

public class CompressInputStream <: InputStream {
    public init(inputStream: InputStream, wrap!: WrapType = DeflateFormat, compressLevel!: CompressLevel = DefaultCompression, bufLen!: Int64 = 512)
}

功能：压缩输入流。

可将 CompressInputStream 实例通过构造函数绑定到任意 InputStream 类型输入流，通过循环调用 read(outBuf: Array<Byte>) 函数，将该输入流中的数据压缩，并将压缩后的数据输出到传入的字节数组。

父类型：

• InputStream

init(InputStream, WrapType, CompressLevel, Int64)

public init(inputStream: InputStream, wrap!: WrapType = DeflateFormat, compressLevel!: CompressLevel = DefaultCompression, bufLen!: Int64 = 512)

功能：构造一个压缩输入流。

需绑定一个输入流，可设置压缩数据格式、压缩等级、内部缓冲区大小（每次从输入流中读取多少数据进行压缩）。

参数：

• inputStream: InputStream - 待压缩的输入流。
• wrap!: WrapType - 压缩数据格式，默认值为 DeflateFormat。
• compressLevel!: CompressLevel - 压缩等级，默认值为 DefaultCompression。
• bufLen!: Int64 - 输入流缓冲区的大小，取值范围为 (0, Int64.Max]，默认 512 字节。

异常：

• ZlibException - 当 bufLen 小于等于 0，输入流分配内存失败，或压缩资源初始化失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.io.*

main(): Unit {
    let arr1 = "Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!".toArray()
    let byteBuffer = ByteBuffer(arr1)
    let bufferedInputStream = BufferedInputStream(byteBuffer)
    var compressInputStream: CompressInputStream = CompressInputStream(bufferedInputStream)
    compressInputStream.close()
}

func close()

public func close(): Unit

功能：关闭压缩输入流。

当前 CompressInputStream 实例使用完毕后必须调用此函数来释放其所占内存资源，以免造成内存泄漏。调用该函数前需确保 read 函数已返回 0，否则可能导致绑定的 InputStream 并未被全部压缩。

异常：

• ZlibException - 如果释放压缩资源失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.io.*

main(): Unit {
    let arr1 = "Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!".toArray()
    let byteBuffer = ByteBuffer(arr1)
    let bufferedInputStream = BufferedInputStream(byteBuffer)
    var compressInputStream: CompressInputStream = CompressInputStream(bufferedInputStream)
    // 使用压缩输入流进行一些操作
    var arr: Array<Byte> = Array<Byte>(1024, repeat: 0)
    var len = compressInputStream.read(arr)
    println("Read ${len} bytes.")
    // 关闭压缩输入流
    compressInputStream.close()
}

运行结果：

Read 18 bytes.

func read(Array<Byte>)

public func read(outBuf: Array<Byte>): Int64

功能：从绑定的输入流中读取数据并压缩，压缩后数据放入指定的字节数组中。

参数：

• outBuf: Array<Byte> - 用来存放压缩后数据的缓冲区。

返回值：

• Int64 - 如果压缩成功，返回压缩后字节数，如果绑定的输入流中数据已经全部压缩完成，或者该压缩输入流被关闭，返回 0。

异常：

• ZlibException - 当 outBuf 为空，或压缩数据失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.io.*

main(): Unit {
    let arr1 = "Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!".toArray()
    let byteBuffer = ByteBuffer(arr1)
    let bufferedInputStream = BufferedInputStream(byteBuffer)
    var compressInputStream: CompressInputStream = CompressInputStream(bufferedInputStream)
    var arr: Array<Byte> = Array<Byte>(1024, repeat: 0)
    println("原始数据长度: ${arr1.size}")
    var len = compressInputStream.read(arr)
    println("压缩后的数据长度: ${len}")
    compressInputStream.close()
}

运行结果：

原始数据长度: 65
压缩后的数据长度: 18

class CompressOutputStream

public class CompressOutputStream <: OutputStream {
    public init(outputStream: OutputStream, wrap!: WrapType = DeflateFormat, compressLevel!: CompressLevel = DefaultCompression, bufLen!: Int64 = 512)
}

功能：压缩输出流。

可将 CompressOutputStream 实例通过构造函数绑定到任意 OutputStream 类型输出流，调用 write(inBuf: Array<Byte>) 函数读取、压缩指定字节数组中的数据，并将压缩后的数据输出到绑定的输出流。

父类型：

• OutputStream

init(OutputStream, WrapType, CompressLevel, Int64)

public init(outputStream: OutputStream, wrap!: WrapType = DeflateFormat, compressLevel!: CompressLevel = DefaultCompression, bufLen!: Int64 = 512)

功能：构造一个压缩输出流，需绑定一个输出流，可设置压缩数据类型、压缩等级、内部缓冲区大小（每得到多少压缩后数据往输出流写出）。

参数：

• outputStream: OutputStream - 绑定的输出流，压缩后数据将写入该输出流。
• wrap!: WrapType - 压缩数据格式，默认值为 DeflateFormat。
• compressLevel!: CompressLevel - 压缩等级，默认值为 DefaultCompression。
• bufLen!: Int64 - 输出流缓冲区的大小，取值范围为 (0, Int64.Max]，默认 512 字节。

异常：

• ZlibException - 如果 bufLen 小于等于 0，输出流分配内存失败，或压缩资源初始化失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.io.*

main(): Unit {
    var byteBuffer = ByteBuffer()
    var compressOutputStream: CompressOutputStream = CompressOutputStream(byteBuffer, wrap: GzipFormat,
        compressLevel: BestCompression, bufLen: 1024)
    compressOutputStream.close()
}

func close()

public func close(): Unit

功能：关闭当前压缩输出流实例。

关闭时，将写入剩余压缩数据（包括缓冲区中数据，以及压缩尾部信息），并释放其所占内存资源。当前压缩输出流使用完毕后必须调用此函数来释放其所占内存资源，以免造成内存泄漏。在调用 close 函数前，绑定的输出流里已写入的数据并不是一段完整的压缩数据，调用 close 函数后，才会把剩余压缩数据写入绑定的输出流，使其完整。

异常：

• ZlibException - 如果当前压缩输出流已经被关闭，或释放压缩资源失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.io.*

main(): Unit {
    var byteBuffer = ByteBuffer()
    var compressOutputStream: CompressOutputStream = CompressOutputStream(byteBuffer, bufLen: 39)

    var arr = "Hello, World!Hello, World!Hello, World!".toArray()

    /* 将字节数组压缩后写入压缩输出流的缓冲区 */
    compressOutputStream.write(arr)

    /* 将内部缓冲区里已压缩的数据刷出并写入绑定的输出流，然后刷新绑定的输出流 */
    compressOutputStream.flush()

    /* 关闭压缩输出流 */
    compressOutputStream.close()
}

func flush()

public func flush(): Unit

功能：刷新压缩输出流。将内部缓冲区里已压缩的数据刷出并写入绑定的输出流，然后刷新绑定的输出流。

异常：

• ZlibException - 如果当前压缩输出流已经被关闭，抛出异常。

示例：

import stdx.compress.zlib.*
import std.io.*

main(): Unit {
    var byteBuffer = ByteBuffer()
    var compressOutputStream: CompressOutputStream = CompressOutputStream(byteBuffer, bufLen: 39)

    var arr = "Hello, World!Hello, World!Hello, World!".toArray()

    /* 将字节数组压缩后写入压缩输出流的缓冲区 */
    compressOutputStream.write(arr)

    /* 将内部缓冲区里已压缩的数据刷出并写入绑定的输出流，然后刷新绑定的输出流 */
    compressOutputStream.flush()

    /* 关闭压缩输出流 */
    compressOutputStream.close()
}

func write(Array<Byte>)

public func write(inBuf: Array<Byte>): Unit

功能：将指定字节数组中的数据进行压缩，并写入输出流，当数据全部压缩完成并写入输出流，函数返回。

参数：

• inBuf: Array<Byte> - 待压缩的字节数组。

异常：

• ZlibException - 如果当前压缩输出流已经被关闭，或压缩数据失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.io.*

main(): Unit {
    var byteBuffer = ByteBuffer()
    var compressOutputStream: CompressOutputStream = CompressOutputStream(byteBuffer, bufLen: 39)

    var arr = "Hello, World!Hello, World!Hello, World!".toArray()

    /* 将字节数组压缩后写入压缩输出流的缓冲区 */
    compressOutputStream.write(arr)

    /* 将内部缓冲区里已压缩的数据刷出并写入绑定的输出流，然后刷新绑定的输出流 */
    compressOutputStream.flush()

    /* 关闭压缩输出流 */
    compressOutputStream.close()
}

class DecompressInputStream

public class DecompressInputStream <: InputStream {
    public init(inputStream: InputStream, wrap!: WrapType = DeflateFormat, bufLen!: Int64 = 512)
}

功能：解压输入流。

可将 DecompressInputStream 实例通过构造函数绑定到任意 InputStream 输入流，通过循环调用 read(outBuf: Array<Byte>) 函数读取、解压输入流中的数据，并将解压后数据输出到指定字节数组。

父类型：

• InputStream

init(InputStream, WrapType, Int64)

public init(inputStream: InputStream, wrap!: WrapType = DeflateFormat, bufLen!: Int64 = 512)

功能：构造一个解压输入流。

需绑定一个输入流，可设置待解压数据格式、内部缓冲区大小（每次从输入流中读取多少数据进行解压）。

参数：

• inputStream: InputStream - 待压缩的输入流。
• wrap!: WrapType - 待解压数据格式，默认值为 DeflateFormat。
• bufLen!: Int64 - 输入流缓冲区的大小，取值范围为 (0, Int64.Max]，默认 512 字节。

异常：

• ZlibException - 如果 bufLen 小于等于 0，输入流分配内存失败，或待解压资源初始化失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.io.*

main(): Unit {
    let arr1 = "Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!".toArray()

    /* 使用压缩输入流进行数据压缩 */
    let byteBuffer = ByteBuffer(arr1)
    var compressInputStream: CompressInputStream = CompressInputStream(byteBuffer)
    var arr2: Array<Byte> = Array<Byte>(1024, repeat: 0)
    var len1 = compressInputStream.read(arr2)

    /* 使用解压缩输入流进行数据解压 */
    var decompressInputStream: DecompressInputStream = DecompressInputStream(ByteBuffer(arr2[..len1]), wrap: GzipFormat,
        bufLen: 1024)

    /* 关闭输入流 */
    compressInputStream.close()
    decompressInputStream.close()
}

func close()

public func close(): Unit

功能：关闭解压输入流。

当前 DecompressInputStream 实例使用完毕后必须调用此函数来释放其所占内存资源，以免造成内存泄漏。调用该函数前需确保 read 函数已返回 0，否则可能导致绑定的 InputStream 并未被全部解压。

异常：

• ZlibException - 如果释放解压资源失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.io.*

main(): Unit {
    let arr1 = "Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!".toArray()

    /* 使用压缩输入流进行数据压缩 */
    let byteBuffer = ByteBuffer(arr1)
    var compressInputStream: CompressInputStream = CompressInputStream(byteBuffer)
    var arr2: Array<Byte> = Array<Byte>(1024, repeat: 0)
    var len1 = compressInputStream.read(arr2)

    /* 使用解压缩输入流进行数据解压 */
    var decompressInputStream: DecompressInputStream = DecompressInputStream(ByteBuffer(arr2[..len1]))
    var arr3: Array<Byte> = Array<Byte>(1024, repeat: 0)
    var len2 = decompressInputStream.read(arr3)
    println(String.fromUtf8(arr3[..len2]))

    /* 关闭输入流 */
    compressInputStream.close()
    decompressInputStream.close()
    println("DecompressInputStream closed successfully.")
}

运行结果：

Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!
DecompressInputStream closed successfully.

func read(Array<Byte>)

public func read(outBuf: Array<Byte>): Int64

功能：从绑定的输入流中读取数据并解压，解压后数据放入指定的字节数组中。

参数：

• outBuf: Array<Byte> - 用来存放解压后数据的缓冲区。

返回值：

• Int64 - 如果解压成功，返回解压后字节数，如果绑定的输入流中数据已经全部解压完成，或者该解压输入流被关闭，返回 0。

异常：

• ZlibException - 当 outBuf 为空，或解压数据失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.io.*

main(): Unit {
    let arr1 = "Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!".toArray()

    /* 使用压缩输入流进行数据压缩 */
    let byteBuffer = ByteBuffer(arr1)
    var compressInputStream: CompressInputStream = CompressInputStream(byteBuffer)
    var arr2: Array<Byte> = Array<Byte>(1024, repeat: 0)
    /* 原始数据长度 */
    println("原始数据长度: ${arr1.size}")
    var len1 = compressInputStream.read(arr2)
    /* 压缩后的数据长度 */
    println("压缩后的数据长度: ${len1}")

    /* 使用解压缩输入流进行数据解压 */
    var decompressInputStream: DecompressInputStream = DecompressInputStream(ByteBuffer(arr2[..len1]))
    var arr3: Array<Byte> = Array<Byte>(1024, repeat: 0)
    var len2 = decompressInputStream.read(arr3)
    println("解压后的数据长度: ${len2}")
    println("解压后数据: ${String.fromUtf8(arr3[..len2])}")

    /* 关闭输入流 */
    compressInputStream.close()
    decompressInputStream.close()
}

运行结果：

原始数据长度: 65
压缩后的数据长度: 18
解压后的数据长度: 65
解压后数据: Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!

class DecompressOutputStream

public class DecompressOutputStream <: OutputStream {
    public init(outputStream: OutputStream, wrap!: WrapType = DeflateFormat, bufLen!: Int64 = 512)
}

功能：解压输出流。

可将 DecompressOutputStream 实例通过构造函数绑定到指定的 OutputStream 类型输出流，通过调用 write(inBuf: Array<Byte>) 函数读取、解压指定字节数组中的数据，并将解压后数据输出到绑定的输出流中。

父类型：

• OutputStream

init(OutputStream, WrapType, Int64)

public init(outputStream: OutputStream, wrap!: WrapType = DeflateFormat, bufLen!: Int64 = 512)

功能：构造一个解压输出流。

需绑定一个输出流，可设置压缩数据类型、压缩等级、内部缓冲区大小（解压后数据会存入内部缓冲区，缓冲区存满后再写到输出流）。

参数：

• outputStream: OutputStream - 绑定的输出流，解压后数据将写入该输出流。
• wrap!: WrapType - 待解压数据格式，默认值为 DeflateFormat。
• bufLen!: Int64 - 输出流缓冲区的大小，取值范围为 (0, Int64.Max]，默认 512 字节。

异常：

• ZlibException - 如果 bufLen 小于等于 0，输出流分配内存失败，或解压资源初始化失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.fs.*

main(): Unit {
    let arr1 = "Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!".toArray()

    // 创建一个临时文件用于压缩
    File.writeTo("./temp_input.txt", arr1)

    // 压缩文件
    compressFile("./temp_input.txt", "./temp_compressed.gz")

    // 读取压缩后的数据
    let compressedData = File.readFrom("./temp_compressed.gz")

    /* 使用解压缩输出流进行数据解压后，将数据写入文件，文件的内容为原始数据 */
    var file = File("./file.text", ReadWrite)
    var decompressOutputStream: DecompressOutputStream = DecompressOutputStream(file, wrap: GzipFormat, bufLen: 1024)

    decompressOutputStream.write(compressedData)
    decompressOutputStream.flush()

    /* 关闭输出流和文件 */
    decompressOutputStream.close()

    println("解压后文件数据字节数和压缩前数据字节数是否相等: ${file.length == arr1.size}")
    file.close()

    // 清理临时文件
    removeIfExists("./temp_input.txt")
    removeIfExists("./temp_compressed.gz")
    removeIfExists("./file.text")
}

func compressFile(srcFileName: String, destFileName: String): Int64 {
    var count: Int64 = 0
    var srcFile: File = File(srcFileName, Read)
    var destFile: File = File(destFileName, Write)

    var tempBuf: Array<UInt8> = Array<UInt8>(1024, repeat: 0)
    var compressOutputStream: CompressOutputStream = CompressOutputStream(destFile, wrap: GzipFormat, bufLen: 10000)
    while (true) {
        var readNum = srcFile.read(tempBuf)
        if (readNum > 0) {
            compressOutputStream.write(tempBuf.slice(0, readNum).toArray())
            count += readNum
        } else {
            break
        }
    }
    compressOutputStream.flush()
    compressOutputStream.close()

    srcFile.close()
    destFile.close()
    return count
}

运行结果：

解压后文件数据字节数和压缩前数据字节数是否相等: true

func close()

public func close(): Unit

功能：关闭当前解压输出流实例。

关闭时，将写入剩余解压后数据，并释放其所占内存资源。当前压缩输出流使用完毕后必须调用此函数来释放其所占内存资源，以免造成内存泄漏。如果之前 write 函数已处理的压缩数据不完整，调用 close 函数时会因为解压数据不全而抛出异常。

异常：

• ZlibException - 如果当前压缩输出流已经被关闭，通过 write 函数传入的待解压数据不完整，或释放压缩资源失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.fs.*

main(): Unit {
    let arr1 = "Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!".toArray()

    // 创建一个临时文件用于压缩
    File.writeTo("./temp_input.txt", arr1)

    // 压缩文件
    compressFile("./temp_input.txt", "./temp_compressed.gz")

    // 读取压缩后的数据
    let compressedData = File.readFrom("./temp_compressed.gz")

    /* 使用解压缩输出流进行数据解压后，将数据写入文件，文件的内容为原始数据 */
    var file = File("./file.text", ReadWrite)
    var decompressOutputStream: DecompressOutputStream = DecompressOutputStream(file, wrap: GzipFormat, bufLen: 1024)

    decompressOutputStream.write(compressedData)
    decompressOutputStream.flush()

    /* 关闭输出流和文件 */
    decompressOutputStream.close()

    println("解压后文件数据字节数和压缩前数据字节数是否相等: ${file.length == arr1.size}")
    file.close()

    // 清理临时文件
    removeIfExists("./temp_input.txt")
    removeIfExists("./temp_compressed.gz")
    removeIfExists("./file.text")
}

func compressFile(srcFileName: String, destFileName: String): Int64 {
    var count: Int64 = 0
    var srcFile: File = File(srcFileName, Read)
    var destFile: File = File(destFileName, Write)

    var tempBuf: Array<UInt8> = Array<UInt8>(1024, repeat: 0)
    var compressOutputStream: CompressOutputStream = CompressOutputStream(destFile, wrap: GzipFormat, bufLen: 10000)
    while (true) {
        var readNum = srcFile.read(tempBuf)
        if (readNum > 0) {
            compressOutputStream.write(tempBuf.slice(0, readNum).toArray())
            count += readNum
        } else {
            break
        }
    }
    compressOutputStream.flush()
    compressOutputStream.close()

    srcFile.close()
    destFile.close()
    return count
}

运行结果：

解压后文件数据字节数和压缩前数据字节数是否相等: true

func flush()

public func flush(): Unit

功能：刷新解压输出流。将内部缓冲区里已解压的数据写入绑定的输出流，然后刷新绑定的输出流。

异常：

• ZlibException - 如果当前解压输出流已经被关闭，抛出异常。

示例：

import stdx.compress.zlib.*
import std.fs.*

main(): Unit {
    let arr1 = "Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!".toArray()

    // 创建一个临时文件用于压缩
    File.writeTo("./temp_input.txt", arr1)

    // 压缩文件
    compressFile("./temp_input.txt", "./temp_compressed.gz")

    // 读取压缩后的数据
    let compressedData = File.readFrom("./temp_compressed.gz")

    /* 使用解压缩输出流进行数据解压后，将数据写入文件，文件的内容为原始数据 */
    var file = File("./file.text", ReadWrite)
    var decompressOutputStream: DecompressOutputStream = DecompressOutputStream(file, wrap: GzipFormat, bufLen: 1024)

    decompressOutputStream.write(compressedData)
    decompressOutputStream.flush()

    /* 关闭输出流和文件 */
    decompressOutputStream.close()

    println("解压后文件数据字节数和压缩前数据字节数是否相等: ${file.length == arr1.size}")
    file.close()

    // 清理临时文件
    removeIfExists("./temp_input.txt")
    removeIfExists("./temp_compressed.gz")
    removeIfExists("./file.text")
}

func compressFile(srcFileName: String, destFileName: String): Int64 {
    var count: Int64 = 0
    var srcFile: File = File(srcFileName, Read)
    var destFile: File = File(destFileName, Write)

    var tempBuf: Array<UInt8> = Array<UInt8>(1024, repeat: 0)
    var compressOutputStream: CompressOutputStream = CompressOutputStream(destFile, wrap: GzipFormat, bufLen: 10000)
    while (true) {
        var readNum = srcFile.read(tempBuf)
        if (readNum > 0) {
            compressOutputStream.write(tempBuf.slice(0, readNum).toArray())
            count += readNum
        } else {
            break
        }
    }
    compressOutputStream.flush()
    compressOutputStream.close()

    srcFile.close()
    destFile.close()
    return count
}

运行结果：

解压后文件数据字节数和压缩前数据字节数是否相等: true

func write(Array<Byte>)

public func write(inBuf: Array<Byte>): Unit

功能：将指定字节数组中的数据进行解压，并写入输出流，当数据全部解压完成并写入输出流，函数返回。

参数：

• inBuf: Array<Byte> - 待解压的字节数组。

异常：

• ZlibException - 如果当前解压输出流已经被关闭，或解压数据失败，抛出异常。

示例：

import stdx.compress.zlib.*
import std.io.*
import std.fs.*

main(): Unit {
    let arr1 = "Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!".toArray()

    /* 使用压缩输入流进行数据压缩 */
    let byteBuffer = ByteBuffer(arr1)
    var compressInputStream: CompressInputStream = CompressInputStream(byteBuffer)
    var arr2: Array<Byte> = Array<Byte>(1024, repeat: 0)
    /* 原始数据长度 */
    println("原始数据长度: ${arr1.size}")
    var len1 = compressInputStream.read(arr2)
    /* 压缩后的数据长度 */
    println("压缩后的数据长度: ${len1}")

    /* 使用解压缩输出流进行数据解压后，将数据写入文件，文件的内容为原始数据 */
    var file = File("./file.text", ReadWrite)
    var decompressOutputStream: DecompressOutputStream = DecompressOutputStream(file)
    decompressOutputStream.write(arr2[..len1])
    decompressOutputStream.flush()

    /* 关闭输入流和输出流 */
    compressInputStream.close()
    decompressOutputStream.close()
    println("解压后文件数据字节数和压缩前数据字节数是否相等: ${file.length == arr1.size}")
    file.close()
    removeIfExists("./file.text")
}

运行结果：

原始数据长度: 65
压缩后的数据长度: 18
解压后文件数据字节数和压缩前数据字节数是否相等: true

枚举

enum CompressLevel

public enum CompressLevel {
    | BestCompression
    | BestSpeed
    | DefaultCompression
}

功能：压缩等级。

压缩等级决定了压缩率和压缩速度，目前支持三种压缩等级，压缩率由小到大，压缩速度由快到慢依次为：BestSpeed、DefaultCompression、BestCompression。

BestCompression

BestCompression

功能：构造一个压缩率优先的压缩等级枚举实例，表示压缩率最高，压缩速度相对降低。

BestSpeed

BestSpeed

功能：构造一个压缩速度优先的压缩等级枚举实例，表示压缩速度最快，压缩率相对较低。

DefaultCompression

DefaultCompression

功能：构造一个压缩等级枚举实例，表示默认压缩等级。

enum WrapType

public enum WrapType {
    | DeflateFormat
    | GzipFormat
}

功能：压缩数据格式。

目前支持 DeflateFormat 和 GzipFormat 两种格式。

DeflateFormat

DeflateFormat

功能：构造一个表示 Deflate 压缩数据格式的枚举实例。

GzipFormat

GzipFormat

功能：构造一个表示 Gzip 压缩数据格式的枚举实例。

异常类

class ZlibException

public class ZlibException <: Exception {
    public init(message: String)
}

功能：zlib 包的异常类。

父类型：

• Exception

init(String)

public init(message: String)

功能：根据异常信息创建 ZlibException 实例。

参数：

• message: String - 异常提示信息。

示例：

import stdx.compress.zlib.*

main(): Unit {
    try {
        throw ZlibException("This is a test exception.")
    } catch (e: ZlibException) {
        println("捕获到 ZlibException: ${e.message}")
    }
}

运行结果：

捕获到 ZlibException: This is a test exception.

Deflate 格式数据的压缩和解压

示例：

import stdx.compress.zlib.*
import std.fs.*

main() {
    var arr: Array<Byte> = Array<Byte>(1024 * 1024, {i => UInt8(i % 256)})
    File.writeTo("./zlib1.txt", arr)

    if (compressFile("./zlib1.txt", "./zlib_copmressed1.zlib") <= 0) {
        println("Failed to compress file!")
    }

    if (decompressFile("./zlib_copmressed1.zlib", "./zlib_decopmressed1.txt") != arr.size) {
        println("Failed to decompress file!")
    }

    if (compareFile("./zlib1.txt", "./zlib_decopmressed1.txt")) {
        println("success")
    } else {
        println("failed")
    }

    remove("./zlib1.txt")
    remove("./zlib_copmressed1.zlib")
    remove("./zlib_decopmressed1.txt")
    return 0
}

func compressFile(srcFileName: String, destFileName: String): Int64 {
    var count: Int64 = 0
    var srcFile: File = File(srcFileName, Read)
    var destFile: File = File(destFileName, Write)

    var tempBuf: Array<UInt8> = Array<UInt8>(1024, repeat: 0)
    var compressOutputStream: CompressOutputStream = CompressOutputStream(destFile, wrap: DeflateFormat)
    while (true) {
        var readNum = srcFile.read(tempBuf)
        if (readNum > 0) {
            compressOutputStream.write(tempBuf.slice(0, readNum).toArray())
            count += readNum
        } else {
            break
        }
    }
    compressOutputStream.flush()
    compressOutputStream.close()

    srcFile.close()
    destFile.close()
    return count
}

func decompressFile(srcFileName: String, destFileName: String): Int64 {
    var count: Int64 = 0
    var srcFile: File = File(srcFileName, Read)
    var destFile: File = File(destFileName, Write)

    var tempBuf: Array<UInt8> = Array<UInt8>(1024, repeat: 0)
    var decompressInputStream: DecompressInputStream = DecompressInputStream(srcFile, wrap: DeflateFormat)
    while (true) {
        var readNum = decompressInputStream.read(tempBuf)
        if (readNum <= 0) {
            break
        }
        destFile.write(tempBuf.slice(0, readNum).toArray())
        count += readNum
    }
    decompressInputStream.close()

    srcFile.close()
    destFile.close()
    return count
}

func compareFile(fileName1: String, fileName2: String): Bool {
    return File.readFrom(fileName1) == File.readFrom(fileName2)
}

运行结果：

success

Gzip 格式数据的压缩和解压

示例：

import stdx.compress.zlib.*
import std.fs.*

main() {
    var arr: Array<Byte> = Array<Byte>(1024 * 1024, {i => UInt8(i % 256)})
    File.writeTo("./zlib.txt", arr)

    if (compressFile("./zlib.txt", "./zlib_copmressed.zlib") <= 0) {
        println("Failed to compress file!")
    }

    if (decompressFile("./zlib_copmressed.zlib", "./zlib_decopmressed.txt") != arr.size) {
        println("Failed to decompress file!")
    }

    if (compareFile("./zlib.txt", "./zlib_decopmressed.txt")) {
        println("success")
    } else {
        println("failed")
    }

    remove("./zlib.txt")
    remove("./zlib_copmressed.zlib")
    remove("./zlib_decopmressed.txt")
    return 0
}

func compressFile(srcFileName: String, destFileName: String): Int64 {
    var count: Int64 = 0
    var srcFile: File = File(srcFileName, Read)
    var destFile: File = File(destFileName, Write)

    var tempBuf: Array<UInt8> = Array<UInt8>(1024, repeat: 0)
    var compressOutputStream: CompressOutputStream = CompressOutputStream(destFile, wrap: GzipFormat, bufLen: 10000)
    while (true) {
        var readNum = srcFile.read(tempBuf)
        if (readNum > 0) {
            compressOutputStream.write(tempBuf.slice(0, readNum).toArray())
            count += readNum
        } else {
            break
        }
    }
    compressOutputStream.flush()
    compressOutputStream.close()

    srcFile.close()
    destFile.close()
    return count
}

func decompressFile(srcFileName: String, destFileName: String): Int64 {
    var count: Int64 = 0
    var srcFile: File = File(srcFileName, Read)
    var destFile: File = File(destFileName, Write)

    var tempBuf: Array<UInt8> = Array<UInt8>(1024, repeat: 0)
    var decompressInputStream: DecompressInputStream = DecompressInputStream(srcFile, wrap: GzipFormat, bufLen: 10000)
    while (true) {
        var readNum = decompressInputStream.read(tempBuf)
        if (readNum <= 0) {
            break
        }
        destFile.write(tempBuf.slice(0, readNum).toArray())
        count += readNum
    }
    decompressInputStream.close()

    srcFile.close()
    destFile.close()
    return count
}

func compareFile(fileName1: String, fileName2: String): Bool {
    return File.readFrom(fileName1) == File.readFrom(fileName2)
}

运行结果：

success

stdx.crypto.common

功能介绍

crypto.common 包提供了加解密相关接口。

API 列表

函数

接口

结构体

异常类

函数

func getGlobalCryptoKit()

public func getGlobalCryptoKit(): CryptoKit

功能：获取当前全局使用的加密套件。

返回值：

• CryptoKit - 当前全局使用的加密套件。

异常：

• CryptoException - 若未设置全局加密套件，则会抛出异常。

示例：

import stdx.crypto.common.*

// 导入stdx.crypto.kit包，将使用默认全局加密套件
import stdx.crypto.kit.*

main() {
    // 没有设置全局加密套件将会抛出异常
    let cryptoKit = getGlobalCryptoKit()
    return 0
}

func setGlobalCryptoKit(CryptoKit)

public func setGlobalCryptoKit(kit: CryptoKit): Unit

功能：设置全局使用的加密套件。

参数：

• kit: CryptoKit - 全局加密套件。

示例：

import stdx.crypto.common.*
import stdx.crypto.kit.*

main() {
    // 创建一个默认的加密套件
    let defaultKit = DefaultCryptoKit()

    // 设置全局加密套件
    setGlobalCryptoKit(defaultKit)
    return 0
}

接口

interface Certificate

public interface Certificate {}

功能：证书接口，用于适配不同的加密套件。

interface CryptoKit

public interface CryptoKit {
    func getRandomGen(): RandomGenerator
    func publicKeyFromDer(encoded: DerBlob): PublicKey
    func publicKeyFromPem(text: String): PublicKey
    func privateKeyFromDer(encoded: DerBlob): PrivateKey
    func privateKeyFromPem(text: String): PrivateKey
    func privateKeyFromDer(encoded: DerBlob, password!: ?String): PrivateKey
    func privateKeyFromPem(text: String, password!: ?String): PrivateKey
    func dhParametersFromDer(encoded: DerBlob): DHParameters
    func dhParametersFromPem(text: String): DHParameters
    func certificateFromDer(encoded: DerBlob): Certificate
    func certificateFromPem(text: String): Array<Certificate>
}

功能：加密套件接口。提供随机数生成器及解码 DER、PEM 的能力。

说明：

PEM 是一种基于 Base64 的编码格式。

func certificateFromDer(DerBlob)

func certificateFromDer(encoded: DerBlob): Certificate

功能：将证书从 DER 格式解码。

参数：

• encoded: DerBlob - 待解码的 DerBlob 对象。

返回值：

• Certificate - 解码得到的证书。

func certificateFromPem(String)

func certificateFromPem(text: String): Array<Certificate>

功能：将证书从 PEM 格式解码。

参数：

• text: String - 待解码的 PEM 格式字符串。

返回值：

• Array<Certificate> - 解码得到的证书集合。

func dhParametersFromDer(DerBlob)

func dhParametersFromDer(encoded: DerBlob): DHParameters

功能：将 DH 密钥参数从 DER 格式解码。

参数：

• encoded: DerBlob - 待解码的 DerBlob 对象。

返回值：

• DHParameters - 解码得到的 DH 密钥参数。

func dhParametersFromPem(String)

func dhParametersFromPem(text: String): DHParameters

功能：将 DH 密钥参数从 PEM 格式解码。

参数：

• text: String - 待解码的 PEM 格式字符串。

返回值：

• DHParameters - 解码得到的 DH 密钥参数。

func getRandomGen()

func getRandomGen(): RandomGenerator

功能：获取随机数生成器。

返回值：

• RandomGenerator - 随机数生成器。

func privateKeyFromDer(DerBlob)

func privateKeyFromDer(encoded: DerBlob): PrivateKey

功能：将私钥从 DER 格式解码。

参数：

• encoded: DerBlob - 待解码的 DerBlob 对象。

返回值：

• PrivateKey - 解码得到的私钥。

func privateKeyFromDer(DerBlob, ?String)

func privateKeyFromDer(encoded: DerBlob, password!: ?String): PrivateKey

功能：将私钥从 DER 格式解密解码。密码为 None 时则不解密。

参数：

• encoded: DerBlob - 待解密解码的 DerBlob 对象。
• password!: ?String - 解密密码。

返回值：

• PrivateKey - 解密解码得到的私钥。

func privateKeyFromPem(String)

func privateKeyFromPem(text: String): PrivateKey

功能：将私钥从 PEM 格式解码。

参数：

• text: String - 待解码的 PEM 格式字符串。

返回值：

• PrivateKey - 解码得到的私钥。

func privateKeyFromPem(String, ?String)

func privateKeyFromPem(text: String, password!: ?String): PrivateKey

功能：将私钥从 PEM 格式解密解码。密码为 None 时则不解密。

参数：

• text: String - 待解密解码的 PEM 格式字符串。
• password!: ?String - 解密密码。

返回值：

• PrivateKey - 解密解码得到的私钥。

func publicKeyFromDer(DerBlob)

func publicKeyFromDer(encoded: DerBlob): PublicKey

功能：将公钥从 DER 格式解码。

参数：

• encoded: DerBlob - 待解码的 DerBlob 对象。

返回值：

• PublicKey - 解码得到的公钥。

func publicKeyFromPem(String)

func publicKeyFromPem(text: String): PublicKey

功能：将公钥从 PEM 格式解码。

参数：

• text: String - 待解码的 PEM 格式字符串。

返回值：

• PublicKey - 解码得到的公钥。

interface DHParameters

public interface DHParameters <: Key {
    static func decodeDer(encoded: DerBlob): DHParameters
    static func decodeFromPem(text: String): DHParameters
}

功能：DH 密钥参数接口。

父类型：

• Key

static func decodeDer(DerBlob)

static func decodeDer(encoded: DerBlob): DHParameters

功能：将 DH 密钥参数从 DER 格式解码。

说明：

• DH（Diffie-Hellman）密钥交换协议是一种确保共享 KEY 安全穿越不安全网络的方法。
• DER 和 PEM 是两种常见的编码格式。

参数：

• encoded: DerBlob - DER 格式的 DH 密钥参数对象。

返回值：

• DHParameters - 由 DER 格式解码出的 DH 密钥参数。

static func decodeFromPem(String)

static func decodeFromPem(text: String): DHParameters

功能：将 DH 密钥参数从 PEM 格式解码。

参数：

• text: String - PEM 格式的 DH 密钥参数字符流。

返回值：

• DHParameters - 由 PEM 格式解码出的 DH 密钥参数。

interface Key

public interface Key <: ToString {
    func encodeToDer(): DerBlob
    func encodeToPem(): PemEntry
    static func decodeDer(encoded: DerBlob): Key
    static func decodeFromPem(text: String): Key
}

功能：密钥接口。公钥用于签名验证或加密，私钥用于签名或解密，公钥和私钥必须相互匹配并形成一对。该类为密钥类，无具体实现，供 PrivateKey/PublicKey 及用户扩展接口。

父类型：

• ToString

static func decodeDer(DerBlob)

static func decodeDer(encoded: DerBlob): Key

功能：将密钥从 DER 格式解码。

参数：

• encoded: DerBlob - DER 格式的对象。

返回值：

• Key - 由 DER 格式解码出的密钥。

static func decodeFromPem(String)

static func decodeFromPem(text: String): Key

功能：将密钥从 PEM 格式解码。

参数：

• text: String - PEM 格式的字符流。

返回值：

• Key - 由 PEM 格式解码出的密钥。

func encodeToDer()

func encodeToDer(): DerBlob

功能：将密钥编码为 DER 格式。

返回值：

• DerBlob - 密钥数据 DER 格式编码生成的对象。

func encodeToPem()

func encodeToPem(): PemEntry

功能：将密钥编码为 PEM 格式。

返回值：

• PemEntry - 密钥数据 PEM 格式编码生成的对象。

interface PrivateKey

public interface PrivateKey <: Key {
    func encodeToDer(password!: ?String): DerBlob
    func encodeToPem(password!: ?String): PemEntry
    static func decodeDer(encoded: DerBlob): PrivateKey
    static func decodeFromPem(text: String): PrivateKey
    static func decodeDer(encoded: DerBlob, password!: ?String): PrivateKey
    static func decodeFromPem(text: String, password!: ?String): PrivateKey
}

功能：私钥接口。

父类型：

• Key

static func decodeDer(DerBlob)

static func decodeDer(encoded: DerBlob): PrivateKey

功能：将私钥从 DER 格式解码。

参数：

• encoded: DerBlob - DER 格式的私钥对象。

返回值：

• PrivateKey - 由 DER 格式解码出的私钥。

static func decodeDer(DerBlob, ?String)

static func decodeDer(encoded: DerBlob, password!: ?String): PrivateKey

功能：将 DER 格式的私钥解密解码成 PrivateKey 对象，密码为 None 时则不解密。

参数：

• encoded: DerBlob - DER 格式的私钥。
• password!: ?String - 解密密码。

返回值：

• PrivateKey - 解密解码后的私钥对象。

static func decodeFromPem(String)

static func decodeFromPem(text: String): PrivateKey

功能：将私钥从 PEM 格式解码。

参数：

• text: String - PEM 格式的私钥字符流。

返回值：

• PrivateKey - 由 PEM 格式解码出的私钥。

static func decodeFromPem(String, ?String)

static func decodeFromPem(text: String, password!: ?String): PrivateKey

功能：将 PEM 格式的私钥解密解码成 PrivateKey 对象，密码为 None 时则不解密。

参数：

• text: String - PEM 格式的私钥。
• password!: ?String - 解密密码。

返回值：

• PrivateKey - 解密解码后的私钥对象。

func encodeToDer(?String)

func encodeToDer(password!: ?String): DerBlob

功能：将私钥加密编码成 DER 格式，密码为 None 时则不加密。

参数：

• password!: ?String - 加密密码。

返回值：

• DerBlob - 加密后的 DER 格式的私钥。

func encodeToPem(?String)

func encodeToPem(password!: ?String): PemEntry

功能：将私钥加密编码成 PEM 格式，密码为 None 时则不加密。

参数：

• password!: ?String - 加密密码。

返回值：

• PemEntry - 加密后的 PEM 格式的私钥。

interface PublicKey

public interface PublicKey <: Key {
    static func decodeDer(encoded: DerBlob): PublicKey
    static func decodeFromPem(text: String): PublicKey
}

功能：公钥接口。

父类型：

• Key

static func decodeDer(DerBlob)

static func decodeDer(encoded: DerBlob): PublicKey

功能：将公钥从 DER 格式解码。

参数：

• encoded: DerBlob - DER 格式的公钥对象。

返回值：

• PublicKey - 由 DER 格式解码出的公钥。

static func decodeFromPem(String)

static func decodeFromPem(text: String): PublicKey

功能：将公钥从 PEM 格式解码。

参数：

• text: String - PEM 格式的公钥字符流。

返回值：

• PublicKey - 由 PEM 格式解码出的公钥。

interface RandomGenerator

public interface RandomGenerator {
    public func nextBits(bits: UInt64): UInt64
    public func nextBytes(bytes: Array<Byte>): Unit
}

功能：安全随机数生成器接口。

func nextBits(UInt64)

public func nextBits(bits: UInt64): UInt64

功能：生成一个指定位长的随机整数。

参数：

• bits: UInt64 - 要生成的随机数的位数，取值范围 (0, 64]。

返回值：

• UInt64 - 生成的指定位长的随机数。

func nextBytes(Array<Byte>)

public func nextBytes(bytes: Array<Byte>): Unit

功能：生成随机数替换入参数组中的每个元素。

参数：

• bytes: Array<Byte> - 被替换的数组。

结构体

struct DerBlob

public struct DerBlob <: Equatable<DerBlob> & Hashable {
    public init(content: Array<Byte>)
}

功能：Crypto 支持配置二进制证书流，用户读取二进制证书数据并创建 DerBlob 对象后可将其解析成 X509Certificate / X509CertificateRequest / PublicKey / PrivateKey 对象。

父类型：

• Equatable<DerBlob>
• Hashable

prop body

public prop body: Array<Byte>

功能：DerBlob 对象中的字符序列。

类型：Array<Byte>

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let content = "Hello, DerBlob!".toArray()
    let derBlob = DerBlob(content)

    // 访问 body 属性
    let body = derBlob.body
    println("DerBlob body UTF-8: ${String.fromUtf8(body)}")
    println("DerBlob body: ${body}")
}

运行结果：

DerBlob body UTF-8: Hello, DerBlob!
DerBlob body: [72, 101, 108, 108, 111, 44, 32, 68, 101, 114, 66, 108, 111, 98, 33]

prop size

public prop size: Int64

功能：DerBlob 对象中字符序列的大小。

类型：Int64

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let content = "Hello, DerBlob!".toArray()
    let derBlob = DerBlob(content)

    // 访问 size 属性
    let size = derBlob.size
    println("DerBlob size: ${size}")
}

运行结果：

DerBlob size: 15

init(Array<Byte>)

public init(content: Array<Byte>)

功能：构造 DerBlob 对象。

参数：

• content: Array<Byte> - 二进制字符序列。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let content = "Hello, DerBlob!".toArray()
    let derBlob = DerBlob(content)

    println("DerBlob对象创建成功")
}

运行结果：

DerBlob对象创建成功

func hashCode()

public override func hashCode(): Int64

功能：返回 DerBlob 对象哈希值。

返回值：

• Int64 - 对 DerBlob 对象进行哈希计算后得到的结果。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let content = "Hello, DerBlob!".toArray()
    let derBlob = DerBlob(content)

    // 获取哈希值
    let hashCode = derBlob.hashCode()
    println("DerBlob hashCode: ${hashCode}")
}

运行结果：

DerBlob hashCode: -1740040550816916903

operator func !=(DerBlob)

public override operator func !=(other: DerBlob): Bool

功能：判不等。

参数：

• other: DerBlob - 被比较的 DerBlob 对象。

返回值：

• Bool - 若对象不同，返回 true；否则，返回 false。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建两个不同的 DerBlob 对象（仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let content1 = "Hello, DerBlob1!".toArray()
    let content2 = "Hello, DerBlob2!".toArray()
    let derBlob1 = DerBlob(content1)
    let derBlob2 = DerBlob(content2)

    // 测试不等操作符
    let notEqual = derBlob1 != derBlob2
    println("DerBlob1 != DerBlob2: ${notEqual}")

    // 测试相同对象
    let derBlob3 = DerBlob(content1)
    let notEqual2 = derBlob1 != derBlob3
    println("DerBlob1 != DerBlob3: ${notEqual2}")
}

运行结果：

DerBlob1 != DerBlob2: true
DerBlob1 != DerBlob3: false

operator func ==(DerBlob)

public override operator func ==(other: DerBlob): Bool

功能：判等。

参数：

• other: DerBlob - 被比较的 DerBlob 对象。

返回值：

• Bool - 若对象相同，返回 true；否则，返回 false。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建两个相同的 DerBlob 对象（仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let content1 = "Hello, DerBlob!".toArray()
    let content2 = "Hello, DerBlob!".toArray()
    let derBlob1 = DerBlob(content1)
    let derBlob2 = DerBlob(content2)

    // 测试相等操作符
    let equal = derBlob1 == derBlob2
    println("DerBlob1 == DerBlob2: ${equal}")

    // 测试不同对象
    let derBlob3 = DerBlob("Hello, DerBlob3!".toArray())
    let equal2 = derBlob1 == derBlob3
    println("DerBlob1 == DerBlob3: ${equal2}")
}

运行结果：

DerBlob1 == DerBlob2: true
DerBlob1 == DerBlob3: false

struct Pem

public struct Pem <: Collection<PemEntry> & ToString {
    public Pem(private let items: Array<PemEntry>)
}

功能：结构体 Pem 为条目序列，可以包含多个 PemEntry。

父类型：

• Collection<PemEntry>
• ToString

Pem(Array<PemEntry>)

public Pem(private let items: Array<PemEntry>)

功能：构造 Pem 对象。

参数：

• items: Array<PemEntry> - 多个 PemEntry 对象。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 PemEntry 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM!".toArray())
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, [("HeaderKey", "HeaderValue")], derBlob)

    // 创建 Pem 对象
    let pem = Pem([pemEntry])

    println("Pem对象创建成功")
}

运行结果：

Pem对象创建成功

prop size

public override prop size: Int64

功能：条目序列的数量。

类型：Int64

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 PemEntry 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM!".toArray())
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, [("HeaderKey", "HeaderValue")], derBlob)

    // 创建 Pem 对象
    let pem = Pem([pemEntry])

    // 访问 size 属性
    println("Pem对象大小: ${pem.size}")
}

运行结果：

Pem对象大小: 1

static func decode(String)

public static func decode(text: String): Pem

功能：将 PEM 文本解码为条目序列。

参数：

• text: String - PEM 字符串。

返回值：

• Pem - PEM 条目序列。

异常：

• X509Exception - 数据为空时，或解码失败抛出异常。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 PemEntry 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM!".toArray())
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, [("HeaderKey", "HeaderValue")], derBlob)

    // 创建 Pem 对象
    let pem = Pem([pemEntry])

    // 编码为 PEM 格式
    let encoded = pem.encode()
    println("编码后的PEM字符串: \n${encoded}")

    println("解码PEM字符串，获得Pem对象")
    let decoded = Pem.decode(encoded)
    println("解码后的Pem对象大小: ${decoded.size}")
}

运行结果：

编码后的PEM字符串: 
-----BEGIN CERTIFICATE-----
HeaderKey: HeaderValue

SGVsbG8sIFBFTSE=
-----END CERTIFICATE-----

解码PEM字符串，获得Pem对象
解码后的Pem对象大小: 1

func encode()

public func encode(): String

功能：返回 PEM 格式的字符串。行结束符将根据当前操作系统生成。

返回值：

• String - PEM 格式的字符串。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 PemEntry 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM!".toArray())
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, [("HeaderKey", "HeaderValue")], derBlob)

    // 创建 Pem 对象
    let pem = Pem([pemEntry])

    // 编码为 PEM 格式
    let encoded = pem.encode()
    println("编码后的PEM字符串: \n${encoded}")
}

运行结果：

编码后的PEM字符串: 
-----BEGIN CERTIFICATE-----
HeaderKey: HeaderValue

SGVsbG8sIFBFTSE=
-----END CERTIFICATE-----

func isEmpty()

public override func isEmpty(): Bool

功能：判断 PEM 文本解码为条目序列是否为空。

返回值：

• Bool - PEM 文本解码为条目序列为空返回 true；否则，返回 false。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 PemEntry 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM!".toArray())
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, [("HeaderKey", "HeaderValue")], derBlob)

    // 创建 Pem 对象
    let pem = Pem([pemEntry])

    // 检查是否为空
    println("Pem对象是否为空: ${pem.isEmpty()}")

    // 创建 Pem 对象
    let pemEmpty = Pem([])
    // 检查是否为空
    println("Pem对象是否为空: ${pemEmpty.isEmpty()}")
}

运行结果：

Pem对象是否为空: false
Pem对象是否为空: true

func iterator()

public override func iterator(): Iterator<PemEntry>

功能：生成 PEM 文本解码为条目序列的迭代器。

返回值：

• Iterator<PemEntry> - PEM 文本解码为条目序列的迭代器。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 PemEntry 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob01 = DerBlob("Hello, PEM01!".toArray())
    let pemEntry01 = PemEntry("CERTIFICATE01", [("HeaderKey01", "HeaderValue01"), ("HeaderKey02", "HeaderValue02")],
        derBlob01)

    // 创建另一个 PemEntry 对象
    let derBlob02 = DerBlob("Hello!!, PEM02!".toArray())
    let pemEntry02 = PemEntry("CERTIFICATE02", [("HeaderKey03", "HeaderValue03"), ("HeaderKey04", "HeaderValue04")],
        derBlob02)

    // 创建 Pem 对象
    let pem = Pem([pemEntry01, pemEntry02])

    // 获取迭代器
    let iter = pem.iterator()
    for (entry in iter) {
        println("PemEntry: ${entry}")
        println("PemEntry.headers: ")
        for (header in entry.headers) {
            println("  ${header[0]}: ${header[1]}")
        }
        println("PemEntry.body: ${entry.body?.body ?? []}")
    }
    println("Pem迭代器获取成功")
}

运行结果：

PemEntry: PEM CERTIFICATE01 (13 bytes)
PemEntry.headers: 
  HeaderKey01: HeaderValue01
  HeaderKey02: HeaderValue02
PemEntry.body: [72, 101, 108, 108, 111, 44, 32, 80, 69, 77, 48, 49, 33]
PemEntry: PEM CERTIFICATE02 (15 bytes)
PemEntry.headers: 
  HeaderKey03: HeaderValue03
  HeaderKey04: HeaderValue04
PemEntry.body: [72, 101, 108, 108, 111, 33, 33, 44, 32, 80, 69, 77, 48, 50, 33]
Pem迭代器获取成功

func toString()

public override func toString(): String

功能：返回一个字符串，字符串内容是包含每个条目序列的标签。

返回值：

• String - 包含每个条目序列的标签的字符串。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 PemEntry 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM!".toArray())
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, [("HeaderKey", "HeaderValue")], derBlob)

    // 创建 Pem 对象
    let pem = Pem([pemEntry])

    // 转换为字符串
    let str = pem.toString()
    println("Pem对象字符串表示: ${str}")
}

运行结果：

Pem对象字符串表示: CERTIFICATE

struct PemEntry

public struct PemEntry <: ToString {
    public static let LABEL_CERTIFICATE = "CERTIFICATE"
    public static let LABEL_X509_CRL = "X509 CRL"
    public static let LABEL_CERTIFICATE_REQUEST = "CERTIFICATE REQUEST"
    public static let LABEL_PRIVATE_KEY = "PRIVATE KEY"
    public static let LABEL_EC_PRIVATE_KEY = "EC PRIVATE KEY"
    public static let LABEL_ENCRYPTED_PRIVATE_KEY = "ENCRYPTED PRIVATE KEY"
    public static let LABEL_RSA_PRIVATE_KEY = "RSA PRIVATE KEY"
    public static let LABEL_SM2_PRIVATE_KEY = "SM2 PRIVATE KEY"
    public static let LABEL_PUBLIC_KEY = "PUBLIC KEY"
    public static let LABEL_EC_PARAMETERS = "EC PARAMETERS"
    public static let LABEL_DH_PARAMETERS = "DH PARAMETERS"
    public PemEntry(
        public let label: String,
        public let headers: Array<(String, String)>,
        public let body: ?DerBlob
    )
    public init(label: String, body: DerBlob)
}

功能：PEM 文本格式经常用于存储证书和密钥，PEM 编码结构包含以下几个部分：

第一行是 “-----BEGIN”，标签和 “-----” 组成的 utf8 编码的字符串； 中间是正文，是实际二进制内容经过 base64 编码得到的可打印字符串，详细的 PEM 编码规范可参考 RFC 7468； 最后一行是 “-----END”，标签和 “-----” 组成的 utf8 编码的字符串，详见 RFC 1421。 在旧版的 PEM 编码标准中在第一行和正文之间还包含条目头。

为了支持不同的用户场景，我们提供了 PemEntry 和 Pem 类型，PemEntry 用于存储单个 PEM 基础结构。

父类型：

• ToString

PemEntry(String, Array<(String, String)>, ?DerBlob)

public PemEntry(
    public let label: String,
    public let headers: Array<(String, String)>,
    public let body: ?DerBlob
)

功能：构造 PemEntry 对象。

参数：

• label: String - 标签。
• headers: Array<(String, String)> - 条目头。
• body: ?DerBlob - 二进制内容。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM Entry!".toArray())

    // 创建一个 PemEntry 对象
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, [("HeaderKey", "HeaderValue")], derBlob)

    println("PemEntry对象创建成功")
}

运行结果：

PemEntry对象创建成功

static let LABEL_CERTIFICATE

public static let LABEL_CERTIFICATE: String = "CERTIFICATE"

功能：记录条目类型为证书。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 使用预定义的标签常量
    let label = PemEntry.LABEL_CERTIFICATE
    println("证书标签: ${label}")
}

运行结果：

证书标签: CERTIFICATE

static let LABEL_CERTIFICATE_REQUEST

public static let LABEL_CERTIFICATE_REQUEST: String = "CERTIFICATE REQUEST"

功能：记录条目类型为证书签名请求。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 使用预定义的标签常量
    let label = PemEntry.LABEL_CERTIFICATE_REQUEST
    println("证书请求标签: ${label}")
}

运行结果：

证书请求标签: CERTIFICATE REQUEST

static let LABEL_DH_PARAMETERS

public static let LABEL_DH_PARAMETERS: String = "DH PARAMETERS"

功能：记录条目类型为 DH 密钥参数。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 使用预定义的标签常量
    let label = PemEntry.LABEL_DH_PARAMETERS
    println("DH参数标签: ${label}")
}

运行结果：

DH参数标签: DH PARAMETERS

static let LABEL_EC_PARAMETERS

public static let LABEL_EC_PARAMETERS: String = "EC PARAMETERS"

功能：记录条目类型为椭圆曲线参数。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 使用预定义的标签常量
    let label = PemEntry.LABEL_EC_PARAMETERS
    println("椭圆曲线参数标签: ${label}")
}

运行结果：

椭圆曲线参数标签: EC PARAMETERS

static let LABEL_EC_PRIVATE_KEY

public static let LABEL_EC_PRIVATE_KEY: String = "EC PRIVATE KEY"

功能：记录条目类型为椭圆曲线私钥。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 使用预定义的标签常量
    let label = PemEntry.LABEL_EC_PRIVATE_KEY
    println("椭圆曲线私钥标签: ${label}")
}

运行结果：

椭圆曲线私钥标签: EC PRIVATE KEY

static let LABEL_ENCRYPTED_PRIVATE_KEY

public static let LABEL_ENCRYPTED_PRIVATE_KEY: String = "ENCRYPTED PRIVATE KEY"

功能：记录条目类型为 PKCS #8 标准加密的私钥。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 使用预定义的标签常量
    let label = PemEntry.LABEL_ENCRYPTED_PRIVATE_KEY
    println("加密私钥标签: ${label}")
}

运行结果：

加密私钥标签: ENCRYPTED PRIVATE KEY

static let LABEL_PRIVATE_KEY

public static let LABEL_PRIVATE_KEY: String = "PRIVATE KEY"

功能：记录条目类型为 PKCS #8 标准未加密的私钥。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 使用预定义的标签常量
    let label = PemEntry.LABEL_PRIVATE_KEY
    println("私钥标签: ${label}")
}

运行结果：

私钥标签: PRIVATE KEY

static let LABEL_PUBLIC_KEY

public static let LABEL_PUBLIC_KEY: String = "PUBLIC KEY"

功能：记录条目类型为公钥。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 使用预定义的标签常量
    let label = PemEntry.LABEL_PUBLIC_KEY
    println("公钥标签: ${label}")
}

运行结果：

公钥标签: PUBLIC KEY

static let LABEL_RSA_PRIVATE_KEY

public static let LABEL_RSA_PRIVATE_KEY: String = "RSA PRIVATE KEY"

功能：记录条目类型为 RSA 私钥。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 使用预定义的标签常量
    let label = PemEntry.LABEL_RSA_PRIVATE_KEY
    println("RSA私钥标签: ${label}")
}

运行结果：

RSA私钥标签: RSA PRIVATE KEY

static let LABEL_SM2_PRIVATE_KEY

public static let LABEL_SM2_PRIVATE_KEY: String = "SM2 PRIVATE KEY"

功能：记录条目类型为 SM2 私钥。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 使用预定义的标签常量
    let label = PemEntry.LABEL_SM2_PRIVATE_KEY
    println("SM2私钥标签: ${label}")
}

运行结果：

SM2私钥标签: SM2 PRIVATE KEY

static let LABEL_X509_CRL

public static let LABEL_X509_CRL: String = "X509 CRL"

功能：记录条目类型为证书吊销列表。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 使用预定义的标签常量
    let label = PemEntry.LABEL_X509_CRL
    println("证书吊销列表标签: ${label}")
}

运行结果：

证书吊销列表标签: X509 CRL

let body

public let body: ?DerBlob

功能：PemEntry 实例的二进制内容。

类型：?DerBlob

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM Entry!".toArray())

    // 创建一个 PemEntry 对象
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, derBlob)

    // 访问 body 属性
    match (pemEntry.body) {
        case Some(blob) => println("PemEntry包含二进制内容，大小: ${blob.size}")
        case None => println("PemEntry不包含二进制内容")
    }
}

运行结果：

PemEntry包含二进制内容，大小: 17

let headers

public let headers: Array<(String, String)>

功能：PemEntry 实例的条目头。

类型：Array<(String, String)>

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM Entry!".toArray())

    // 创建一个 PemEntry 对象，包含头部信息
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, [("HeaderKey", "HeaderValue"), ("AnotherKey", "AnotherValue")],
        derBlob)

    // 访问 headers 属性
    println("PemEntry头部数量: ${pemEntry.headers.size}")

    // 遍历头部
    for (header in pemEntry.headers) {
        println("头部: ${header[0]} = ${header[1]}")
    }
}

运行结果：

PemEntry头部数量: 2
头部: HeaderKey = HeaderValue
头部: AnotherKey = AnotherValue

let label

public let label: String

功能：PemEntry 实例的标签。

类型：String

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM Entry!".toArray())

    // 创建一个 PemEntry 对象
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, derBlob)

    // 访问 label 属性
    println("PemEntry标签: ${pemEntry.label}")
}

运行结果：

PemEntry标签: CERTIFICATE

init(String, DerBlob)

public init(label: String, body: DerBlob)

功能：构造 PemEntry 对象。

参数：

• label: String - 标签
• body: DerBlob - 二进制内容

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM Entry!".toArray())

    // 创建一个 PemEntry 对象（使用简化构造函数）
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, derBlob)

    println("PemEntry对象创建成功")
}

运行结果：

PemEntry对象创建成功

func encode()

public func encode(): String

功能：返回 PEM 格式的字符串。行结束符将根据当前操作系统生成。

返回值：

• String - PEM 格式的字符串。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM Entry!".toArray())

    // 创建一个 PemEntry 对象
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, derBlob)

    // 编码为 PEM 格式
    let encoded = pemEntry.encode()
    println("编码后字符串长度: ${encoded.size}")
    print("编码后字符串: \n${encoded}")
}

运行结果：

编码后字符串长度: 79
编码后字符串: 
-----BEGIN CERTIFICATE-----
SGVsbG8sIFBFTSBFbnRyeSE=
-----END CERTIFICATE-----

func header(String)

public func header(name: String): Iterator<String>

功能：通过条目头名称，找到对应条目内容。

参数：

• name: String - 条目头名称。

返回值：

• Iterator<String> - 条目头名称对应内容的迭代器。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM Entry!".toArray())

    // 创建一个 PemEntry 对象，包含头部信息
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, [("HeaderKey", "HeaderValue"), ("HeaderKey", "AnotherValue")],
        derBlob)

    // 获取特定头部
    let headerValueIter = pemEntry.header("HeaderKey")
    println("头部键迭代器获取成功")
    for (HeaderValue in headerValueIter) {
        println("头部键: ${HeaderValue}")
    }
}

运行结果：

头部键迭代器获取成功
头部键: HeaderValue
头部键: AnotherValue

func toString()

public override func toString(): String

功能：返回 PEM 对象的标签和二进制内容的长度。

返回值：

• String - PEM 对象的标签和二进制内容的长度。

示例：

import stdx.crypto.common.*

main(): Unit {
    // 创建一个 DerBlob 对象（DerBlob 仅演示二进制容器能力，数据无 ASN.1/DER 加密规范格式）
    let derBlob = DerBlob("Hello, PEM Entry!".toArray())

    // 创建一个 PemEntry 对象
    let pemEntry = PemEntry(PemEntry.LABEL_CERTIFICATE, derBlob)

    // 转换为字符串
    let str = pemEntry.toString()
    println("PemEntry字符串表示: ${str}")
}

运行结果：

PemEntry字符串表示: PEM CERTIFICATE (17 bytes)

异常类

class CryptoException

public class CryptoException <: Exception {
    public init()
    public init(message: String)
}

功能：此类为加解密出现错误时抛出的异常。

父类型：

• Exception

init()

public init()

功能：无参构造函数，构造 CryptoException 异常。

示例：

import stdx.crypto.common.*

main(): Unit {
    try {
        // 抛出一个无参的CryptoException异常
        throw CryptoException()
    } catch (e: CryptoException) {
        println("捕获到加解密异常")
    }
}

运行结果：

捕获到加解密异常

init(String)

public init(message: String)

功能：根据异常信息构造 CryptoException 异常类对象。

参数：

• message: String - 异常信息。

示例：

import stdx.crypto.common.*

main(): Unit {
    try {
        // 抛出一个带消息的CryptoException异常
        throw CryptoException("这是一个加密异常")
    } catch (e: CryptoException) {
        println("捕获到加密异常: ${e.message}")
    }
}

运行结果：

捕获到加密异常: 这是一个加密异常

stdx.crypto.crypto

功能介绍

crypto 包提供安全随机数功能和提供国密 SM4 对称加解密。

使用本包需要外部依赖 OpenSSL 3 的 crypto 动态库文件，故使用前需安装相关工具。

• 对于 Linux 操作系统，可参考以下方式：

  • 如果系统的包管理工具支持安装 OpenSSL 3 开发工具包，可通过这个方式安装，并确保系统安装目录下含有 libcrypto.so 和 libcrypto.so.3 这两个动态库文件，例如 Ubuntu 22.04 系统上可使用 sudo apt install libssl-dev 命令安装 libssl-dev 工具包；
  • 如果无法通过上面的方式安装，可自行下载 OpenSSL 3.x.x 源码编译安装软件包，并确保安装目录下含有 libcrypto.so 和 libcrypto.so.3 这两个动态库文件，然后可选择下面任意一种方式来保证系统链接器可以找到这些文件：
    • 在系统未安装 OpenSSL 的场景，安装时选择直接安装到系统路径下；
    • 安装在自定义目录的场景，将这些文件所在目录设置到环境变量 LD_LIBRARY_PATH 以及 LIBRARY_PATH 中。

• 对于 Windows 操作系统，可按照以下步骤：

  • 自行下载 OpenSSL 3.x.x 源码编译安装 x64 架构软件包或者自行下载安装第三方预编译的供开发人员使用的 OpenSSL 3.x.x 软件包；
  • 确保安装目录下含有 libcrypto.dll.a（或 libcrypto.lib）、libcrypto-3-x64.dll 这两个库文件；
  • 将 libcrypto.dll.a（或 libcrypto.lib）所在的目录路径设置到环境变量 LIBRARY_PATH 中，将 libcrypto-3-x64.dll 所在的目录路径设置到环境变量 PATH 中。

• 对于 macOS 操作系统，可参考以下方式：

  • 使用 brew install openssl@3 安装，并确保系统安装目录下含有 libcrypto.dylib 和 libcrypto.3.dylib 这两个动态库文件；
  • 如果无法通过上面的方式安装，可自行下载 OpenSSL 3.x.x 源码编译安装软件包，并确保安装目录下含有 libcrypto.dylib 和 libcrypto.3.dylib 这两个动态库文件，然后可选择下面任意一种方式来保证系统链接器可以找到这些文件：
    • 在系统未安装 OpenSSL 的场景，安装时选择直接安装到系统路径下；
    • 安装在自定义目录的场景，将这些文件所在目录设置到环境变量 DYLD_LIBRARY_PATH 以及 LIBRARY_PATH 中。

• 对于 Android 操作系统，可参考以下方式：

  • 由于 Android 系统默认自带的 OpenSSL 是裁剪版本，部分接口可能找不到符号而抛出异常，因此需要用户自行编译安装完整的 OpenSSL 3.x.x 版本；
  • 可自行下载 OpenSSL 3.x.x 源码，使用 Android NDK 交叉编译生成对应架构（当前只支持 arm64-v8a）的动态库文件，确保编译产物中含有 libcrypto.so 和 libcrypto.so.3 这些动态库文件；
  • 将这些文件所在目录设置到环境变量 LD_LIBRARY_PATH 中。

说明：

如果未安装 OpenSSL 3 软件包或者安装低版本的软件包，程序可能无法使用并抛出相关异常 SecureRandomException：Can not load openssl library or function xxx。

API 列表

类

结构体

异常类

类

class SecureRandom

public class SecureRandom <: RandomGenerator {
    public init(priv!: Bool = false)
}

父类型：

• RandomGenerator

功能：用于生成加密安全的伪随机数。

和 Random 相比，主要有三个方面不同：

• 随机数种子： Random 使用系统时钟作为默认的种子，时间戳一样，结果就相同；SecureRandom 使用操作系统或者硬件提供的随机数种子，生成的是真随机数。
• 随机数生成： Random 使用了梅森旋转伪随机生成器；SecureRandom 则使用了 openssl 库提供的 MD5 等随机算法，使用熵源生成真随机数；如果硬件支持，还可以使用硬件随机数生成器来生成安全性更强的随机数。
• 安全性： Random 不能用于加密安全的应用或者隐私数据的保护，可以使用 SecureRandom。

使用示例见 SecureRandom 使用。

init(Bool)

public init(priv!: Bool = false)

功能：创建 SecureRandom 实例，可指定是否使用更加安全的加密安全伪随机生成器，加密安全伪随机生成器可用于会话密钥和证书私钥等加密场景。

参数：

• priv!: Bool - 设置为 true 表示使用加密安全伪随机生成器。

示例：

import stdx.crypto.crypto.*

main() {
    // 创建一个默认的SecureRandom实例
    let random1 = SecureRandom()
    println("创建默认SecureRandom实例成功")

    // 创建一个使用更加安全的SecureRandom实例
    let random2 = SecureRandom(priv: true)
    println("创建使用更加安全的SecureRandom实例成功")

    return 0
}

可能的运行结果：

创建默认SecureRandom实例成功
创建使用更加安全的SecureRandom实例成功

func nextBits(UInt64)

public func nextBits(bits: UInt64): UInt64

功能：生成一个指定位长的随机整数。

参数：

• bits: UInt64 - 要生成的随机数的位数，取值范围 (0, 64]。

返回值：

• UInt64 - 生成的用户指定位长的随机数。

异常：

• IllegalArgumentException - 如果 bits 等于 0，或大于 64，超过所能截取的 UInt64 长度，则抛出异常。
• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个指定位数的随机数
    let num1 = random.nextBits(8) // 生成8位的随机数
    println("生成的8位随机数: ${num1}")

    let num2 = random.nextBits(16) // 生成16位的随机数
    println("生成的16位随机数: ${num2}")

    let num3 = random.nextBits(32) // 生成32位的随机数
    println("生成的32位随机数: ${num3}")

    return 0
}

可能的运行结果：

生成的8位随机数: 17
生成的16位随机数: 45263
生成的32位随机数: 2128153426

func nextBool()

public func nextBool(): Bool

功能：获取一个随机的 Bool 类型实例。

返回值：

• Bool - 一个随机的 Bool 类型实例。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个布尔类型的随机数
    let bool1 = random.nextBool()
    println("生成的布尔随机数1: ${bool1}")

    let bool2 = random.nextBool()
    println("生成的布尔随机数2: ${bool2}")
    return 0
}

可能的运行结果：

生成的布尔随机数1: false
生成的布尔随机数2: false

func nextBytes(Array<Byte>)

public func nextBytes(bytes: Array<Byte>): Unit

功能：生成随机数替换入参数组中的每个元素。

参数：

• bytes: Array<Byte> - 被替换的数组。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 创建一个字节数组并用随机数填充
    let bytes = Array<Byte>(10, repeat: 0) // 创建包含10个字节的数组，初始值为0
    println("填充前的数组: ${bytes}")

    random.nextBytes(bytes) // 用随机数填充数组
    println("填充后的数组: ${bytes}")

    return 0
}

可能的运行结果：

填充前的数组: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
填充后的数组: [120, 13, 17, 140, 252, 106, 71, 121, 211, 28]

func nextBytes(Int32)

public func nextBytes(length: Int32): Array<Byte>

功能：获取一个指定长度的随机字节的数组。

参数：

• length: Int32 - 要生成的随机字节数组的长度。

返回值：

• Array<Byte> - 一个随机字节数组。

异常：

• IllegalArgumentException - 当参数 length 小于等于 0，抛出异常。
• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成一个包含5个随机字节的数组
    let bytes1 = random.nextBytes(5)
    println("成功生成5个随机字节的数组: ${bytes1}")

    // 生成一个包含10个随机字节的数组
    let bytes2 = random.nextBytes(10)
    println("成功生成10个随机字节的数组: ${bytes2}")

    return 0
}

可能的运行结果：

成功生成5个随机字节的数组: [89, 31, 206, 132, 25]
成功生成10个随机字节的数组: [232, 228, 56, 119, 208, 142, 53, 221, 166, 96]

func nextFloat16()

public func nextFloat16(): Float16

功能：获取一个 Float16 类型且在区间 [0.0, 1.0) 内的随机数。

返回值：

• Float16 - 一个 Float16 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个Float16类型的随机数
    let num1 = random.nextFloat16()
    println("生成的Float16随机数1: ${num1}")

    let num2 = random.nextFloat16()
    println("生成的Float16随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的Float16随机数1: 0.237305
生成的Float16随机数2: 0.362305

func nextFloat32()

public func nextFloat32(): Float32

功能：获取一个 Float32 类型且在区间 [0.0, 1.0) 内的随机数。

返回值：

• Float32 - 一个 Float32 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个Float32类型的随机数
    let num1 = random.nextFloat32()
    println("生成的Float32随机数1: ${num1}")

    let num2 = random.nextFloat32()
    println("生成的Float32随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的Float32随机数1: 0.830997
生成的Float32随机数2: 0.599951

func nextFloat64()

public func nextFloat64(): Float64

功能：获取一个 Float64 类型且在区间 [0.0, 1.0) 内的随机数。

返回值：

• Float64 - 一个 Float64 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个Float64类型的随机数
    let num1 = random.nextFloat64()
    println("生成的Float64随机数1: ${num1}")

    let num2 = random.nextFloat64()
    println("生成的Float64随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的Float64随机数1: 0.665093
生成的Float64随机数2: 0.026271

func nextGaussianFloat16(Float16, Float16)

public func nextGaussianFloat16(mean!: Float16 = 0.0, sigma!: Float16 = 1.0): Float16

功能：默认获取一个 Float16 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数，其中均值是期望值，可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。

参数：

• mean!: Float16 - 均值。
• sigma!: Float16 - 标准差。

返回值：

• Float16 - 一个 Float16 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个高斯分布的Float16类型的随机数，均值为0.5，标准差为0.1
    let num1 = random.nextGaussianFloat16(mean: 0.5, sigma: 0.1)
    println("生成的高斯Float16随机数1: ${num1}")

    let num2 = random.nextGaussianFloat16(mean: 0.5, sigma: 0.1)
    println("生成的高斯Float16随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的高斯Float16随机数1: 0.597168
生成的高斯Float16随机数2: 0.659668

func nextGaussianFloat32(Float32, Float32)

public func nextGaussianFloat32(mean!: Float32 = 0.0, sigma!: Float32 = 1.0): Float32

功能：默认获取一个 Float32 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数，其中均值是期望值，可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。

参数：

• mean!: Float32 - 均值。
• sigma!: Float32 - 标准差。

返回值：

• Float32 - 一个 Float32 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个高斯分布的Float32类型的随机数，均值为0.5，标准差为0.1
    let num1 = random.nextGaussianFloat32(mean: 0.5, sigma: 0.1)
    println("生成的高斯Float32随机数1: ${num1}")

    let num2 = random.nextGaussianFloat32(mean: 0.5, sigma: 0.1)
    println("生成的高斯Float32随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的高斯Float32随机数1: 0.512646
生成的高斯Float32随机数2: 0.457472

func nextGaussianFloat64(Float64, Float64)

public func nextGaussianFloat64(mean!: Float64 = 0.0, sigma!: Float64 = 1.0): Float64

功能：默认获取一个 Float64 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数，其中均值是期望值，可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。

参数：

• mean!: Float64 - 均值。
• sigma!: Float64 - 标准差。

返回值：

• Float64 - 一个 Float64 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个高斯分布的Float64类型的随机数，均值为0.5，标准差为0.1
    let num1 = random.nextGaussianFloat64(mean: 0.5, sigma: 0.1)
    println("生成的高斯Float64随机数1: ${num1}")

    let num2 = random.nextGaussianFloat64(mean: 0.5, sigma: 0.1)
    println("生成的高斯Float64随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的高斯Float64随机数1: 0.411050
生成的高斯Float64随机数2: 0.531717

func nextInt16()

public func nextInt16(): Int16

功能：获取一个 Int16 类型的随机数。

返回值：

• Int16 - 一个 Int16 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个Int16类型的随机数
    let num1 = random.nextInt16()
    println("生成的Int16随机数1: ${num1}")

    let num2 = random.nextInt16()
    println("生成的Int16随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的Int16随机数1: -30796
生成的Int16随机数2: -23424

func nextInt16(Int16)

public func nextInt16(max: Int16): Int16

功能：获取一个 Int16 类型且在区间 [0, max) 内的随机数。

参数：

• max: Int16 - 区间最大值。

返回值：

• Int16 - 一个 Int16 类型的随机数。

异常：

• IllegalArgumentException - 当 max 为非正数时，抛出异常。
• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个在指定范围内的Int16类型的随机数
    let num1 = random.nextInt16(100)
    println("生成的Int16随机数1 (0-100): ${num1}")

    let num2 = random.nextInt16(100)
    println("生成的Int16随机数2 (0-100): ${num2}")
    return 0
}

可能的运行结果：

生成的Int16随机数1 (0-100): 27
生成的Int16随机数2 (0-100): 23

func nextInt32()

public func nextInt32(): Int32

功能：获取一个 Int32 类型的随机数。

返回值：

• Int32 - 一个 Int32 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个Int32类型的随机数
    let num1 = random.nextInt32()
    println("生成的Int32随机数1: ${num1}")

    let num2 = random.nextInt32()
    println("生成的Int32随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的Int32随机数1: -33263071
生成的Int32随机数2: -853238350

func nextInt32(Int32)

public func nextInt32(max: Int32): Int32

功能：获取一个 Int32 类型且在区间 [0, max) 内的随机数。

参数：

• max: Int32 - 区间最大值。

返回值：

• Int32 - 一个 Int32 类型的随机数。

异常：

• IllegalArgumentException - 当 max 为非正数时，抛出异常。
• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个在指定范围内的Int32类型的随机数
    let num1 = random.nextInt32(1000)
    println("生成的Int32随机数1 (0-1000): ${num1}")

    let num2 = random.nextInt32(1000)
    println("生成的Int32随机数2 (0-1000): ${num2}")
    return 0
}

可能的运行结果：

生成的Int32随机数1 (0-1000): 469
生成的Int32随机数2 (0-1000): 47

func nextInt64()

public func nextInt64(): Int64

功能：获取一个 Int64 类型的随机数。

返回值：

• Int64 - 一个 Int64 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个Int64类型的随机数
    let num1 = random.nextInt64()
    println("生成的Int64随机数1: ${num1}")

    let num2 = random.nextInt64()
    println("生成的Int64随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的Int64随机数1: -3331154220163065762
生成的Int64随机数2: 6412631069792762051

func nextInt64(Int64)

public func nextInt64(max: Int64): Int64

功能：获取一个 Int64 类型且在区间 [0, max) 内的随机数。

参数：

• max: Int64 - 区间最大值。

返回值：

• Int64 - 一个 Int64 类型的随机数。

异常：

• IllegalArgumentException - 当 max 为非正数时，抛出异常。
• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个在指定范围内的Int64类型的随机数
    let num1 = random.nextInt64(1000000)
    println("生成的Int64随机数1 (0-1000000): ${num1}")

    let num2 = random.nextInt64(1000000)
    println("生成的Int64随机数2 (0-1000000): ${num2}")
    return 0
}

可能的运行结果：

生成的Int64随机数1 (0-1000000): 874128
生成的Int64随机数2 (0-1000000): 129569

func nextInt8()

public func nextInt8(): Int8

功能：获取一个 Int8 类型的随机数。

返回值：

• Int8 - 一个 Int8 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个Int8类型的随机数
    let num1 = random.nextInt8()
    println("生成的Int8随机数1: ${num1}")

    let num2 = random.nextInt8()
    println("生成的Int8随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的Int8随机数1: -21
生成的Int8随机数2: 70

func nextInt8(Int8)

public func nextInt8(max: Int8): Int8

功能：获取一个 Int8 类型且在区间 [0, max) 内的随机数。

参数：

• max: Int8 - 区间最大值。

返回值：

• Int8 - 一个 Int8 类型的随机数。

异常：

• IllegalArgumentException - 当 max 为非正数时，抛出异常。
• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个在指定范围内的Int8类型的随机数
    let num1 = random.nextInt8(100)
    println("生成的Int8随机数1 (0-100): ${num1}")

    let num2 = random.nextInt8(100)
    println("生成的Int8随机数2 (0-100): ${num2}")
    return 0
}

可能的运行结果：

生成的Int8随机数1 (0-100): 72
生成的Int8随机数2 (0-100): 35

func nextUInt16()

public func nextUInt16(): UInt16

功能：获取一个 UInt16 类型的随机数。

返回值：

• UInt16 - 一个 UInt16 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个UInt16类型的随机数
    let num1 = random.nextUInt16()
    println("生成的UInt16随机数1: ${num1}")

    let num2 = random.nextUInt16()
    println("生成的UInt16随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的UInt16随机数1: 23354
生成的UInt16随机数2: 46516

func nextUInt16(UInt16)

public func nextUInt16(max: UInt16): UInt16

功能：获取一个 UInt16 类型且在区间 [0, max) 内的随机数。

参数：

• max: UInt16 - 区间最大值。

返回值：

• UInt16 - 一个 UInt16 类型的随机数。

异常：

• IllegalArgumentException - 当 max 为 0 时，抛出异常。
• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个UInt16范围内的随机数
    let num1 = random.nextUInt16(1000) // 生成0-999之间的随机数
    println("生成的UInt16随机数(0-999): ${num1}")

    let num2 = random.nextUInt16(5000) // 生成0-4999之间的随机数
    println("生成的UInt16随机数(0-4999): ${num2}")
    return 0
}

可能的运行结果：

生成的UInt16随机数(0-999): 674
生成的UInt16随机数(0-4999): 3879

func nextUInt32()

public func nextUInt32(): UInt32

功能：获取一个 UInt32 类型的随机数。

返回值：

• UInt32 - 一个 UInt32 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个UInt32类型的随机数
    let num1 = random.nextUInt32()
    println("生成的UInt32随机数1: ${num1}")

    let num2 = random.nextUInt32()
    println("生成的UInt32随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的UInt32随机数1: 2512231137
生成的UInt32随机数2: 1654221431

func nextUInt32(UInt32)

public func nextUInt32(max: UInt32): UInt32

功能：获取一个 UInt32 类型且在区间 [0, max) 内的随机数。

参数：

• max: UInt32 - 区间最大值。

返回值：

• UInt32 - 一个 UInt32 类型的随机数。

异常：

• IllegalArgumentException - 当 max 为 0 时，抛出异常。
• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个UInt32范围内的随机数
    let num1 = random.nextUInt32(100000) // 生成0-99999之间的随机数
    println("生成的UInt32随机数(0-99999): ${num1}")

    let num2 = random.nextUInt32(1000000) // 生成0-999999之间的随机数
    println("生成的UInt32随机数(0-999999): ${num2}")
    return 0
}

可能的运行结果：

生成的UInt32随机数(0-99999): 99820
生成的UInt32随机数(0-999999): 661325

func nextUInt64()

public func nextUInt64(): UInt64

功能：获取一个 UInt64 类型的随机数。

返回值：

• UInt64 - 一个 UInt64 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个UInt64类型的随机数
    let num1 = random.nextUInt64()
    println("生成的UInt64随机数1: ${num1}")

    let num2 = random.nextUInt64()
    println("生成的UInt64随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的UInt64随机数1: 11677076453013864441
生成的UInt64随机数2: 4153549476048086930

func nextUInt64(UInt64)

public func nextUInt64(max: UInt64): UInt64

功能：获取一个 UInt64 类型且在区间 [0, max) 内的随机数。

参数：

• max: UInt64 - 区间最大值。

返回值：

• UInt64 - 一个 UInt64 类型的随机数。

异常：

• IllegalArgumentException - 当 max 为 0 时，抛出异常。
• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个UInt64范围内的随机数
    let num1 = random.nextUInt64(1000000000000) // 生成0-999999999999之间的随机数
    println("生成的UInt64随机数(0-999999999999): ${num1}")

    let num2 = random.nextUInt64(100000000000000) // 生成0-99999999999999之间的随机数
    println("生成的UInt64随机数(0-99999999999999): ${num2}")
    return 0
}

可能的运行结果：

生成的UInt64随机数(0-999999999999): 606328247182
生成的UInt64随机数(0-99999999999999): 24041701587638

func nextUInt8()

public func nextUInt8(): UInt8

功能：获取一个 UInt8 类型的随机数。

返回值：

• UInt8 - 一个 UInt8 类型的随机数。

异常：

• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个UInt8类型的随机数
    let num1 = random.nextUInt8()
    println("生成的UInt8随机数1: ${num1}")

    let num2 = random.nextUInt8()
    println("生成的UInt8随机数2: ${num2}")
    return 0
}

可能的运行结果：

生成的UInt8随机数1: 21
生成的UInt8随机数2: 160

func nextUInt8(UInt8)

public func nextUInt8(max: UInt8): UInt8

功能：获取一个 UInt8 类型且在区间 [0, max) 内的随机数。

参数：

• max: UInt8 - 区间最大值。

返回值：

• UInt8 - 一个 UInt8 类型的随机数。

异常：

• IllegalArgumentException - 当 max 为 0 时，抛出异常。
• SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom()

    // 生成几个UInt8范围内的随机数
    let num1 = random.nextUInt8(100) // 生成0-99之间的随机数
    println("生成的UInt8随机数(0-99): ${num1}")

    let num2 = random.nextUInt8(50) // 生成0-49之间的随机数
    println("生成的UInt8随机数(0-49): ${num2}")
    return 0
}

可能的运行结果：

生成的UInt8随机数(0-99): 60
生成的UInt8随机数(0-49): 30

class SM4

public class SM4 <: BlockCipher {
    public init(
        optMode: OperationMode,
        key: Array<Byte>,
        iv!: Array<Byte> = Array<Byte>(),
        paddingMode!: PaddingMode = PaddingMode.PKCS7Padding,
        aad!: Array<Byte> = Array<Byte>(),
        tagSize!: Int64 = 16
    )
}

功能：提供国密 SM4 对称加解密。

目前 SM4 支持的加解密工作模式由 OperationMode 定义，目前支持 ECB、CBC、OFB、CFB、CTR、GCM 模式。

不同的工作模式可能对应的加解密实现不同，安全性也不同。需要选择和场景适配的加解密工作模式。

iv 初始化向量在 GCM 模式下可以设置推荐长度是 12 字节，在 CBC、OFB、CFB、CTR 模式下 iv 长度是 16 字节，在 ECB 模式下 iv 可以不设置。

paddingMode 填充模式模式由 PaddingMode 定义， 目前支持 NoPadding 非填充、PKCS7Padding PKCS7 填充。默认是 PKCS7 填充。

paddingMode 设置对 ECB 和 CBC 有效，ECB 和 CBC 分组加解密需要分组长度等于 blockSize。会根据填充模式进行填充。 paddingMode 设置对 OFB、CFB、CTR、GCM 工作模式无效，这些工作模式均无需填充。

如果选择 NoPadding 模式，即不填充。则在 ECB 和 CBC 工作模式下用户需要对数据是否可以分组负责，如果数据不能分组，或者最后一组数据长度不足 blockSize 则会报错。

aad 附加数据，仅在 GCM 模式下使用，由用户填充，参与摘要计算，默认为空。

tagSize 设置摘要长度，仅在 GCM 模式下使用，默认值为 SM4_GCM_TAG_SIZE 16 字节，最小不能低于 12 字节，最大不能超过 16 字节。

如果是 GCM 工作模式。加密结果的后 tagSize 字节是摘要数据。

使用示例见 SM4 使用。

注意：

GCM 模式需要 OpenSSL 3.2 或者以上版本。

父类型：

• BlockCipher

prop aad

public prop aad: Array<Byte>

功能：附加数据。

类型：Array<Byte>

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(12) // GCM推荐12字节IV
    let aad = "additional authenticated data".toArray() // 附加认证数据

    // 创建SM4实例（仅GCM模式下aad参数生效，需要 OpenSSL 3.2 或者以上版本）
    let sm4 = SM4(OperationMode.GCM, key, iv: iv, aad: aad)

    // 获取附加数据
    let retrievedAad = sm4.aad
    println("附加数据长度: ${retrievedAad.size}")

    return 0
}

运行结果：

附加数据长度: 29

prop algorithm

public prop algorithm: String

功能：获取分组加解密算法的算法名称。

类型：String

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 获取算法名称
    let algorithm = sm4.algorithm
    println("SM4算法名称: ${algorithm}")

    return 0
}

运行结果：

SM4算法名称: SM4

prop blockSize

public prop blockSize: Int64

功能：分组长度，单位字节。

类型：Int64

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 获取分组长度
    let blockSize = sm4.blockSize
    println("SM4分组长度: ${blockSize}")

    return 0
}

运行结果：

SM4分组长度: 16

prop iv

public prop iv: Array<Byte>

功能：初始化向量。

类型：Array<Byte>

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 获取初始化向量
    let ivValue = sm4.iv
    println("初始化向量长度: ${ivValue.size}")

    return 0
}

运行结果：

初始化向量长度: 16

prop ivSize

public prop ivSize: Int64

功能：初始化向量长度。

类型：Int64

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 获取初始化向量长度
    let ivSize = sm4.ivSize
    println("初始化向量长度: ${ivSize}")

    return 0
}

运行结果：

初始化向量长度: 16

prop key

public prop key: Array<Byte>

功能：密钥。

类型：Array<Byte>

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 获取密钥
    let keyValue = sm4.key
    println("密钥长度: ${keyValue.size}")

    return 0
}

运行结果：

密钥长度: 16

prop keySize

public prop keySize: Int64

功能：密钥长度。

类型：Int64

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 获取密钥长度
    let keySize = sm4.keySize
    println("密钥长度: ${keySize}")

    return 0
}

运行结果：

密钥长度: 16

prop optMode

public prop optMode: OperationMode

功能：工作模式。

类型：OperationMode

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 获取工作模式
    let optMode = sm4.optMode
    println("工作模式: ${optMode}")

    return 0
}

运行结果：

工作模式: CBC

prop paddingMode

public prop paddingMode: PaddingMode

功能：填充模式。

类型：PaddingMode

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv, paddingMode: PaddingMode.PKCS7Padding)

    // 获取填充模式
    let paddingMode = sm4.paddingMode
    return 0
}

prop tagSize

public prop tagSize: Int64

功能：摘要长度。

类型：Int64

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例（GCM模式，需要 OpenSSL 3.2 或者以上版本）
    let sm4 = SM4(OperationMode.GCM, key, iv: iv, tagSize: 16)

    // 获取摘要长度
    let tagSize = sm4.tagSize
    println("摘要长度: ${tagSize}")

    return 0
}

运行结果：

摘要长度: 16

init(OperationMode, Array<Byte>, Array<Byte>, PaddingMode, Array<Byte>, Int64)

public init(
    optMode: OperationMode,
    key: Array<Byte>,
    iv!: Array<Byte> = Array<Byte>(),
    paddingMode!: PaddingMode = PaddingMode.PKCS7Padding,
    aad!: Array<Byte> = Array<Byte>(),
    tagSize!: Int64 = 16
)

功能：创建 SM4 实例，可指定在不同工作模式下参数。

参数：

• optMode: OperationMode - 设置加解密工作模式。
• key: Array<Byte> - 密钥，长度为 16 字节。
• iv!: Array<Byte> - 初始化向量。
• paddingMode!: PaddingMode - 设置填充模式。
• aad!: Array<Byte> - 设置附加数据。
• tagSize!: Int64 - 设置摘要长度。

异常：

• CryptoException - 参数设置不正确，实例化失败。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 使用CBC模式创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    println("SM4算法名称: ${sm4.algorithm}")
    println("分组长度: ${sm4.blockSize}")
    println("密钥长度: ${sm4.keySize}")

    return 0
}

运行结果：

SM4算法名称: SM4
分组长度: 16
密钥长度: 16

func decrypt(Array<Byte>)

public func decrypt(input: Array<Byte>): Array<Byte>

功能：解密一段数据数据。

参数：

• input: Array<Byte> - 输入字节序列。

返回值：

• Array<Byte> - 解密后的结果。

异常：

• CryptoException - 解密失败，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 要加密的数据
    let plainText = "Hello, Cangjie!".toArray()

    // 加密数据
    let encrypted = sm4.encrypt(plainText)
    println("加密成功，密文长度: ${encrypted.size}")

    // 解密数据
    let decrypted = sm4.decrypt(encrypted)
    let result = String.fromUtf8(decrypted)
    println("解密结果: ${result}")

    return 0
}

运行结果：

加密成功，密文长度: 16
解密结果: Hello, Cangjie!

func decrypt(Array<Byte>, Array<Byte>)

public func decrypt(input: Array<Byte>,  to!: Array<Byte>): Int64

功能：解密一段数据，将密文解密后的明文写入指定的输出字节数组，返回值为实际写入到输出数组的明文字节长度。数组长度不足时不会报错，仅会对解密后的明文进行截断处理。为保证能接收完整明文，建议输出数组的长度不小于密文数组的长度。

参数：

• input: Array<Byte> - 待进行解密的数据。
• to!: Array<Byte> - 输出数组。

返回值：

• Int64 - 输出长度。

异常：

• CryptoException - 解密失败，抛出异常。
• IllegalArgumentException - 当 to 的 size = 0 时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 要加密的数据
    let plainText = "Hello, Cangjie!".toArray()

    // 加密数据
    let encrypted = sm4.encrypt(plainText)
    println("加密成功，密文长度: ${encrypted.size}")

    // 准备输出数组，长度为密文长度
    var output = Array<Byte>(encrypted.size, repeat: 0)

    // 解密数据到指定输出数组
    let outputLen = sm4.decrypt(encrypted, to: output)
    println("解密成功，输出长度: ${outputLen}")
    println("解密成功，输出: ${String.fromUtf8(output.slice(0, outputLen))}")

    // 准备输出数组，长度为3（会发生截断）
    var output01 = Array<Byte>(3, repeat: 0)

    // 解密数据到指定输出数组
    let outputLen01 = sm4.decrypt(encrypted, to: output01)
    println("解密成功，输出长度: ${outputLen01}")
    println("解密成功，输出（发生截断）: ${String.fromUtf8(output01)}")
    return 0
}

运行结果：

加密成功，密文长度: 16
解密成功，输出长度: 15
解密成功，输出: Hello, Cangjie!
解密成功，输出长度: 3
解密成功，输出（发生截断）: Hel

func decrypt(InputStream, OutputStream)

public func decrypt(input: InputStream, output: OutputStream): Unit

功能：对输入流进行解密，如果数据过大无法一次对其解密，可以通过数据流进行解密。

参数：

• input:InputStream - 待解密的输入数据流。
• output: OutputStream - 解密后的输出数据流。

异常：

• CryptoException - 解密失败，抛出异常。

示例：

import stdx.crypto.crypto.*
import std.fs.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 要加密的数据
    let plainText = "Hello, Cangjie!".toArray()

    // 创建一个测试文件里面放入加密数据
    let testEncrypt = Path("./test_encrypt.txt")
    removeIfExists(testEncrypt, recursive: true)
    let encrypted = sm4.encrypt(plainText)
    File.writeTo(testEncrypt, encrypted)

    // 从文件中读取加密数据并解密到文件中（File是文件流）
    let testDecrypt = Path("./test_decrypt.txt")
    removeIfExists(testDecrypt, recursive: true)
    sm4.decrypt(File(testEncrypt, Read), File(testDecrypt, Write))

    let decrypted = File.readFrom(testDecrypt)
    let result = String.fromUtf8(decrypted)
    println("从文件中解密结果: ${result}")

    // 清理临时文件
    removeIfExists(testEncrypt, recursive: true)
    removeIfExists(testDecrypt, recursive: true)
    return 0
}

运行结果：

从文件中解密结果: Hello, Cangjie!

func encrypt(Array<Byte>)

public func encrypt(input: Array<Byte>): Array<Byte>

功能：加密一段数据数据。

参数：

• input: Array<Byte> - 输入字节序列。

返回值：

• Array<Byte> - 加密后的结果。

异常：

• CryptoException - 加密失败，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 要加密的数据
    let plainText = "Hello, Cangjie!".toArray()

    // 加密数据
    let encrypted = sm4.encrypt(plainText)
    println("加密成功，密文字节数组（长度 ${encrypted.size}）: ${encrypted}")

    return 0
}

可能的运行结果：

加密成功，密文字节数组（长度 16）: [130, 245, 173, 223, 95, 40, 68, 161, 234, 44, 26, 22, 39, 217, 140, 138]

func encrypt(Array<Byte>, Array<Byte>)

public func encrypt(input: Array<Byte>, to!: Array<Byte>): Int64

功能：加密一段明文数据，将加密后的密文写入调用者预先创建的输出字节数组，返回值为实际写入到输出数组的密文字节长度。明文数组长度加上一个 blockSize（16），可适配所有填充场景。

注意：

• 输出数组长度仅影响加密结果，不影响后续解密流程；数组长度不足时不会报错，若无法容纳完整密文，加密会失败或仅写入部分密文（返回值为实际写入长度）。
• 填充模式（CBC/ECB）：SM4 分组加密需填充，密文长度为 16 字节的整数倍，建议输出数组长度≥向上取整 (明文长度 / 16)×16（blockSize=16）；最简方案为输出数组长度 = 明文长度 + 16，可适配所有填充场景。
• 无填充模式（GCM/CTR/OFB/CFB）：流加密无需填充，密文长度与明文长度一致，建议输出数组长度与明文长度一致。
• 本接口为高性能底层实现，不做自动扩容与长度校验，需调用者自行保证输出数组长度足够。

参数：

• input: Array<Byte> - 待进行加密的数据。
• to!: Array<Byte> - 输出数组。

返回值：

• Int64 - 输出长度。

异常：

• CryptoException - 加密失败，抛出异常。
• IllegalArgumentException - 当 to 的 size = 0 时，抛出异常。

示例：

import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 要加密的数据
    let plainText = "Hello, Cangjie!".toArray()

    // 准备输出数组，长度应足够存储加密结果
    var output = Array<Byte>(plainText.size + 16, repeat: 0)

    // 加密数据到指定输出数组
    let outputLen = sm4.encrypt(plainText, to: output)
    println("加密成功，输出长度: ${outputLen}")

    return 0
}

运行结果：

加密成功，输出长度: 16

func encrypt(InputStream, OutputStream)

public func encrypt(input: InputStream, output: OutputStream): Unit

功能：对输入流进行加密，如果数据过大无法一次对其加密，可以通过数据流进行加密。

参数：

• input:InputStream - 待加密的输入数据流。
• output: OutputStream - 解密后的输出数据流。

异常：

• CryptoException - 加密失败，抛出异常。

示例：

import stdx.crypto.crypto.*
import std.fs.*

main() {
    let random = SecureRandom(priv: true)

    let key = random.nextBytes(16) // 16字节密钥，生产环节从KMS密钥管理系统获取
    let iv = random.nextBytes(16) // 16字节IV

    // 创建SM4实例
    let sm4 = SM4(OperationMode.CBC, key, iv: iv)

    // 要加密的数据
    let plainText = "Hello, Cangjie!"
    println("要加密的数据: ${plainText}")

    // 测试文件里面放入要加密的数据
    let testData = Path("./test_data.txt")
    removeIfExists(testData, recursive: true)
    File.writeTo(testData, plainText.toArray())

    // 加密的数据被写入到文件中
    let testEncrypt = Path("./test_encrypt.txt")
    removeIfExists(testEncrypt, recursive: true)
    sm4.encrypt(File(testData, Read), File(testEncrypt, Write))
    let encrypted = File.readFrom(testEncrypt)
    println("加密结果的大小: ${encrypted.size}")

    // 解密的数据被写入到文件中
    let testDecrypt = Path("./test_decrypt.txt")
    removeIfExists(testDecrypt, recursive: true)
    sm4.decrypt(File(testEncrypt, Read), File(testDecrypt, Write))

    let decrypted = File.readFrom(testDecrypt)
    let result = String.fromUtf8(decrypted)
    println("从文件中解密结果: ${result}")

    // 清理临时文件
    removeIfExists(testEncrypt, recursive: true)
    removeIfExists(testDecrypt, recursive: true)
    removeIfExists(testData, recursive: true)
    return 0
}

运行结果：

要加密的数据: Hello, Cangjie!
加密结果的大小: 16
从文件中解密结果: Hello, Cangjie!

结构体

struct OperationMode

public struct OperationMode <: ToString & Equatable<OperationMode> {
    public static let ECB: OperationMode
    public static let CBC: OperationMode
    public static let OFB: OperationMode
    public static let CFB: OperationMode
    public static let CTR: OperationMode
    public static let GCM: OperationMode
    public let mode: String
}

功能：对称加解密算法的工作模式。

父类型：

• ToString
• Equatable<OperationMode>

static let CBC

public static let CBC: OperationMode

功能：Cipher Block Chaining（密码分组链接）工作模式，CBC 初始值是 OperationMode("CBC")。

类型：OperationMode

示例：

import stdx.crypto.crypto.*

main() {
    let mode = OperationMode.CBC
    println("工作模式: ${mode}")
    return 0
}

运行结果：

工作模式: CBC

static let CFB

public static let CFB: OperationMode

功能：Cipher FeedBack（密文反馈）工作模式，CFB 初始值是 OperationMode("CFB")。

类型：OperationMode

示例：

import stdx.crypto.crypto.*

main() {
    let mode = OperationMode.CFB
    println("工作模式: ${mode}")
    return 0
}

运行结果：

工作模式: CFB

static let CTR

public static let CTR: OperationMode

功能：CounTeR（计数器）工作模式，CTR 初始值是 OperationMode("CTR")。

类型：OperationMode

示例：

import stdx.crypto.crypto.*

main() {
    let mode = OperationMode.CTR
    println("工作模式: ${mode}")
    return 0
}

运行结果：

工作模式: CTR

static let ECB

public static let ECB: OperationMode

功能：Electronic CodeBook（单子密码本）工作模式， ECB 初始值是 OperationMode("ECB")。

类型：OperationMode

示例：

import stdx.crypto.crypto.*

main() {
    let mode = OperationMode.ECB
    println("工作模式: ${mode}")
    return 0
}

运行结果：

工作模式: ECB

static let GCM

public static let GCM: OperationMode

功能：Galois Counter（伽罗瓦计数器）工作模式，GCM 初始值是 OperationMode("GCM")。

类型：OperationMode

示例：

import stdx.crypto.crypto.*

main() {
    let mode = OperationMode.GCM
    println("工作模式: ${mode}")
    return 0
}

运行结果：

工作模式: GCM

static let OFB

public static let OFB: OperationMode

功能：Output FeedBack（输出反馈）工作模式，OFB 初始值是 OperationMode("OFB")。

类型：OperationMode

示例：

import stdx.crypto.crypto.*

main() {
    let mode = OperationMode.OFB
    println("工作模式: ${mode}")
    return 0
}

运行结果：

工作模式: OFB

let mode

public let mode: String

功能：operation 分组加解密的工作模式，目前支持 ECB、CBC CFB OFB CTR GCM。

类型：String

示例：

import stdx.crypto.crypto.*

main() {
    let mode = OperationMode.CBC
    println("模式字符串: ${mode.mode}")
    return 0
}

运行结果：

模式字符串: CBC

func toString()

public override func toString(): String

功能：获取工作模式字符串。

返回值：

• String - 工作模式字符串。

示例：

import stdx.crypto.crypto.*

main() {
    let modeStr = OperationMode.OFB.toString()
    println("OFB模式toString: ${modeStr}")
    return 0
}

运行结果：

OFB模式toString: OFB

operator func !=(OperationMode)

public override operator func !=(other: OperationMode): Bool

功能：工作模式比较是否不相同。

参数：

• other: OperationMode - 工作模式。

返回值：

• Bool - true 不相同，false 相同。

示例：

import stdx.crypto.crypto.*

main() {
    let mode1 = OperationMode.CBC
    let mode2 = OperationMode.ECB
    let mode3 = OperationMode.CBC

    let isNotEqual1 = mode1 != mode2
    let isNotEqual2 = mode1 != mode3

    println("CBC != ECB: ${isNotEqual1}")
    println("CBC != CBC: ${isNotEqual2}")
    return 0
}

运行结果：

CBC != ECB: true
CBC != CBC: false

operator func ==(OperationMode)

public override operator func ==(other: OperationMode): Bool

功能：工作模式比较是否相同。

参数：

• other: OperationMode - 工作模式。

返回值：

• Bool - true 相同，false 不相同。

示例：

import stdx.crypto.crypto.*

main() {
    let mode1 = OperationMode.CBC
    let mode2 = OperationMode.ECB
    let mode3 = OperationMode.CBC

    let isEqual1 = mode1 == mode2
    let isEqual2 = mode1 == mode3

    println("CBC == ECB: ${isEqual1}")
    println("CBC == CBC: ${isEqual2}")
    return 0
}

运行结果：

CBC == ECB: false
CBC == CBC: true

struct PaddingMode

public struct PaddingMode <: Equatable<PaddingMode> {
    public static let NoPadding: PaddingMode
    public static let PKCS7Padding: PaddingMode
    public let paddingType: Int64
}

功能：对称加解密算法的填充模式。

父类型：

• Equatable<PaddingMode>

static let NoPadding

public static let NoPadding: PaddingMode

功能：不填充，NoPadding 初始值是 PaddingMode(0)。

类型：PaddingMode

示例：

import stdx.crypto.crypto.*

main() {
    let padding = PaddingMode.NoPadding
    println("NoPadding模式的paddingType: ${padding.paddingType}")
    return 0
}

运行结果：

NoPadding模式的paddingType: 0

static let PKCS7Padding

public static let PKCS7Padding: PaddingMode

功能：采用 PKCS7 协议填充，PKCS7Padding 初始值是 PaddingMode(1)。

类型：PaddingMode

示例：

import stdx.crypto.crypto.*

main() {
    let padding = PaddingMode.PKCS7Padding
    println("PKCS7Padding模式的paddingType: ${padding.paddingType}")
    return 0
}

运行结果：

PKCS7Padding模式的paddingType: 1

let paddingType

public let paddingType: Int64

功能：分组加解密填充方式，目前支持非填充和 pkcs7 填充。

类型：Int64

示例：

import stdx.crypto.crypto.*

main() {
    let padding = PaddingMode.PKCS7Padding
    println("PKCS7Padding模式的paddingType: ${padding.paddingType}")
    return 0
}

运行结果：

PKCS7Padding模式的paddingType: 1

operator func !=(PaddingMode)

public override operator func !=(other: PaddingMode): Bool

功能：工作模式比较是否不相同。

参数：

• other: PaddingMode - 填充模式。

返回值：

• Bool - true 不相同，false 相同。

示例：

import stdx.crypto.crypto.*

main() {
    let padding1 = PaddingMode.NoPadding
    let padding2 = PaddingMode.PKCS7Padding
    let padding3 = PaddingMode.NoPadding

    let isNotEqual1 = padding1 != padding2
    let isNotEqual2 = padding1 != padding3

    println("NoPadding != PKCS7Padding: ${isNotEqual1}")
    println("NoPadding != NoPadding: ${isNotEqual2}")
    return 0
}

运行结果：

NoPadding != PKCS7Padding: true
NoPadding != NoPadding: false

operator func ==(PaddingMode)

public override operator func ==(other: PaddingMode): Bool

功能：填充模式比较是否相同。

参数：

• other: PaddingMode - 填充模式。

返回值：

• Bool - true 相同，false 不相同。

示例：

import stdx.crypto.crypto.*

main() {
    let padding1 = PaddingMode.NoPadding
    let padding2 = PaddingMode.PKCS7Padding
    let padding3 = PaddingMode.NoPadding

    let isEqual1 = padding1 == padding2
    let isEqual2 = padding1 == padding3

    println("NoPadding == PKCS7Padding: ${isEqual1}")
    println("NoPadding == NoPadding: ${isEqual2}")
    return 0
}

运行结果：

NoPadding == PKCS7Padding: false
NoPadding == NoPadding: true

异常类

class SecureRandomException

public class SecureRandomException <: Exception {
    public init()
    public init(message: String)
}

功能：crypto 包安全随机数的异常类。

父类型：

• Exception

init()

public init()

功能：创建默认的 SecureRandomException 实例，异常提示消息为空。

示例：

import stdx.crypto.crypto.*

main(): Unit {
    try {
        // 抛出一个无参的SecureRandomException异常
        throw SecureRandomException()
    } catch (e: SecureRandomException) {
        println("捕获到安全随机数异常")
    }
}

运行结果：

捕获到安全随机数异常

init(String)

public init(message: String)

功能：根据异常信息创建 SecureRandomException 实例。

参数：

• message: String - 异常提示信息。

示例：

import stdx.crypto.crypto.*

main(): Unit {
    try {
        // 抛出一个带消息的SecureRandomException异常
        throw SecureRandomException("安全随机数生成失败")
    } catch (e: SecureRandomException) {
        println("捕获到安全随机数异常: ${e.message}")
    }
}

运行结果：

捕获到安全随机数异常: 安全随机数生成失败

SecureRandom 使用

Random 创建随机数对象。

示例：

import stdx.crypto.crypto.*

main() {
    let r = SecureRandom()
    for (_ in 0..10) {
        let flip = r.nextBool()
        println(flip)
    }
    return 0
}

运行结果：

说明

可能出现的运行结果如下（true/false 的选择是随机的）。

false
true
false
false
false
true
true
false
false
true

SM4 使用

SM4 加解密数据。

示例：

import stdx.crypto.crypto.*

main() {
    var plains = "hello cangjie!"
    var key = "YOUR_KEYYYYYYYYY" // 16 bytes key for SM4
    var iv = "YOUR_IVVVVVVVVVV" // 16 bytes IV for CBC mode
    var sm4 = SM4(OperationMode.CBC, key.toArray(), iv: iv.toArray())
    var enRe = sm4.encrypt(plains.toArray())
    var dd = sm4.decrypt(enRe)
    println(String.fromUtf8(dd))
}

运行结果：

hello cangjie!

stdx.crypto.digest

功能介绍

digest 包提供常用的消息摘要算法，包括 MD5、SHA1、SHA224、SHA256、SHA384、SHA512、HMAC、SM3 等。

使用本包需要外部依赖 OpenSSL 3 的 crypto 动态库文件，故使用前需安装相关工具。

• 对于 Linux 操作系统，可参考以下方式：

  • 如果系统的包管理工具支持安装 OpenSSL 3 开发工具包，可通过这个方式安装，并确保系统安装目录下含有 libcrypto.so 和 libcrypto.so.3 这两个动态库文件，例如 Ubuntu 22.04 系统上可使用 sudo apt install libssl-dev 命令安装 libssl-dev 工具包；
  • 如果无法通过上面的方式安装，可自行下载 OpenSSL 3.x.x 源码编译安装软件包，并确保安装目录下含有 libcrypto.so 和 libcrypto.so.3 这两个动态库文件，然后可选择下面任意一种方式来保证系统链接器可以找到这些文件：
    • 在系统未安装 OpenSSL 的场景，安装时选择直接安装到系统路径下；
    • 安装在自定义目录的场景，将这些文件所在目录设置到环境变量 LD_LIBRARY_PATH 以及 LIBRARY_PATH 中。

• 对于 Windows 操作系统，可按照以下步骤：

  • 自行下载 OpenSSL 3.x.x 源码编译安装 x64 架构软件包或者自行下载安装第三方预编译的供开发人员使用的 OpenSSL 3.x.x 软件包；
  • 确保安装目录下含有 libcrypto.dll.a（或 libcrypto.lib）、libcrypto-3-x64.dll 这两个库文件；
  • 将 libcrypto.dll.a（或 libcrypto.lib）所在的目录路径设置到环境变量 LIBRARY_PATH 中，将 libcrypto-3-x64.dll 所在的目录路径设置到环境变量 PATH 中。

• 对于 macOS 操作系统，可参考以下方式：

  • 使用 brew install openssl@3 安装，并确保系统安装目录下含有 libcrypto.dylib 和 libcrypto.3.dylib 这两个动态库文件；
  • 如果无法通过上面的方式安装，可自行下载 OpenSSL 3.x.x 源码编译安装软件包，并确保安装目录下含有 libcrypto.dylib 和 libcrypto.3.dylib 这两个动态库文件，然后可选择下面任意一种方式来保证系统链接器可以找到这些文件：
    • 在系统未安装 OpenSSL 的场景，安装时选择直接安装到系统路径下；
    • 安装在自定义目录的场景，将这些文件所在目录设置到环境变量 DYLD_LIBRARY_PATH 以及 LIBRARY_PATH 中。

• 对于 Android 操作系统，可参考以下方式：

  • 由于 Android 系统默认自带的 OpenSSL 是裁剪版本，部分接口可能找不到符号而抛出异常，因此需要用户自行编译安装完整的 OpenSSL 3.x.x 版本；
  • 可自行下载 OpenSSL 3.x.x 源码，使用 Android NDK 交叉编译生成对应架构（当前只支持 arm64-v8a）的动态库文件，确保编译产物中含有 libcrypto.so 和 libcrypto.so.3 这些动态库文件；
  • 将这些文件所在目录设置到环境变量 LD_LIBRARY_PATH 中。

说明：

如果未安装 OpenSSL 3 软件包或者安装低版本的软件包，程序可能无法使用并抛出相关异常 CryptoException：Can not load openssl library or function xxx。

API 列表

类

结构体

类

class HMAC

public class HMAC <: Digest {
    public init(key: Array<Byte>, digest: () -> Digest)
    public init(key: Array<Byte>, algorithm: HashType)
}

功能：提供 HMAC 算法的实现。目前支持的摘要算法包括 MD5、SHA1、SHA224、SHA256、SHA384、SHA512、SM3。

父类型：

• Digest

prop algorithm

public prop algorithm: String

功能：HMAC 所选 Hash 算法的算法名称。

类型：String

示例：

import stdx.crypto.digest.*
import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)
    let key = random.nextBytes(32)

    let hmac = HMAC(key, HashType.SHA256)

    let algorithm = hmac.algorithm
    println("HMAC算法: ${algorithm}")

    return 0
}

运行结果：

HMAC算法: HMAC-SHA256

prop blockSize

public prop blockSize: Int64

功能：HMAC 所选 Hash 算法信息块长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*
import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)
    let key = random.nextBytes(32)

    let hmac = HMAC(key, HashType.SHA256)

    let blockSize = hmac.blockSize
    println("块大小: ${blockSize}")

    return 0
}

运行结果：

块大小: 64

prop size

public prop size: Int64

功能：HMAC 所选 Hash 算法的摘要信息长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*
import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)
    let key = random.nextBytes(32)

    let hmac = HMAC(key, HashType.SHA256)

    let size = hmac.size
    println("摘要长度: ${size}")

    return 0
}

运行结果：

摘要长度: 32

init(Array<Byte>, () -> Digest)

public init(key: Array<Byte>, digest: () -> Digest)

功能：构造函数，创建 HMAC 对象。

参数：

• key: Array<Byte> - 密钥，建议该参数不小于所选 Hash 算法摘要的长度。
• digest: () -> Digest - hash 算法。

异常：

• CryptoException - key 值为空时，抛出异常。

示例：

import stdx.crypto.digest.*
import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)
    let key = random.nextBytes(32)
    let hmac = HMAC(key, {=> SHA256()})

    println("HMAC算法: ${hmac.algorithm}")
    println("摘要长度: ${hmac.size}")
    println("密钥长度: ${key.size}")
    println("密钥长度不小于摘要长度: ${key.size >= hmac.size}")
    return 0
}

运行结果：

HMAC算法: HMAC-SHA256
摘要长度: 32
密钥长度: 32
密钥长度不小于摘要长度: true

init(Array<Byte>, HashType)

public init(key: Array<Byte>, algorithm: HashType)

功能：构造函数，创建 HMAC 对象。

参数：

• key: Array<Byte> - 密钥，建议该参数不小于所选 Hash 算法摘要的长度。
• algorithm: HashType - hash 算法。

异常：

• CryptoException - key 值为空时，抛出异常。

示例：

import stdx.crypto.digest.*
import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)
    let key = random.nextBytes(32)
    let hmac = HMAC(key, HashType.SHA256)

    println("HMAC算法: ${hmac.algorithm}")
    println("摘要长度: ${hmac.size}")
    println("密钥长度: ${key.size}")
    println("密钥长度不小于摘要长度: ${key.size >= hmac.size}")
    return 0
}

运行结果：

HMAC算法: HMAC-SHA256
摘要长度: 32
密钥长度: 32
密钥长度不小于摘要长度: true

static func equal(Array<Byte>, Array<Byte>)

public static func equal(mac1: Array<Byte>, mac2: Array<Byte>): Bool

功能：比较两个信息摘要是否相等，且不泄露比较时间，即比较不采用传统短路原则，从而防止 timing attack 类型的攻击。

参数：

• mac1: Array<Byte> - 需要比较的信息摘要序列。
• mac2: Array<Byte> - 需要比较的信息摘要序列。

返回值：

• Bool - 信息摘要是否相同，true 相同，false 不相同。

示例：

import stdx.crypto.digest.*
import stdx.crypto.crypto.*

main() {
    let key1 = "mySecretKey".toArray()
    let key2 = "mySecretKey".toArray()
    let data1 = "Hello, World!".toArray()
    let data2 = "Hello, World!".toArray()

    let hmac1 = HMAC(key1, HashType.SHA256)
    let hmac2 = HMAC(key2, HashType.SHA256)

    hmac1.write(data1)
    hmac2.write(data2)

    let mac1 = hmac1.finish()
    let mac2 = hmac2.finish()

    let isEqual = HMAC.equal(mac1, mac2)
    println("摘要是否相同: ${isEqual}")

    return 0
}

运行结果：

摘要是否相同: true

func finish()

public func finish(): Array<Byte>

功能：返回生成的信息摘要值，注意调用 finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

返回值：

• Array<Byte> - 生成的信息摘要字节序列。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)
    let key = random.nextBytes(32)
    let data = "Hello, World!".toArray()

    let hmac = HMAC(key, HashType.MD5)
    hmac.write(data)

    let result = hmac.finish()
    println("${hmac.algorithm}摘要: ${result}")

    return 0
}

可能的运行结果：

HMAC-MD5摘要: [22, 198, 33, 44, 225, 231, 29, 141, 214, 143, 8, 188, 108, 114, 150, 21]

func finish(Array<Byte>)

public func finish(to!: Array<Byte>): Unit

功能：获取生成的信息摘要值，注意调用 finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

参数：

• to!: Array<Byte> - 目标数组。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算或者指定输出数组大小不等于摘要算法信息长度，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)
    let key = random.nextBytes(32)
    let data = "Hello, World!".toArray()

    let hmac = HMAC(key, HashType.MD5)
    hmac.write(data)

    let output = Array<Byte>(hmac.size, repeat: 0)
    hmac.finish(to: output)
    println("输出数组: ${output}")

    return 0
}

可能的运行结果：

输出数组: [253, 224, 17, 238, 0, 31, 114, 118, 132, 239, 222, 219, 11, 248, 114, 169]

func reset()

public func reset(): Unit

功能：重置 HMAC 对象到初始状态，清理 HMAC 上下文。

异常：

• CryptoException - 当内部错误，重置失败，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)
    let key = random.nextBytes(32)
    let data1 = "Hello".toArray()
    let data2 = "World".toArray()

    let hmac = HMAC(key, HashType.MD5)
    hmac.write(data1)

    let result1 = hmac.finish()
    println("${hmac.algorithm}第一次摘要: ${result1}")

    hmac.reset() // 重置HMAC对象
    println("保留密钥和算法，可重新计算新数据的摘要")

    hmac.write(data2)

    let result2 = hmac.finish()
    println("${hmac.algorithm}重置后摘要: ${result2}")

    return 0
}

运行结果：

HMAC-MD5第一次摘要: [138, 105, 2, 119, 31, 115, 202, 188, 146, 122, 244, 175, 173, 233, 58, 189]
保留密钥和算法，可重新计算新数据的摘要
HMAC-MD5重置后摘要: [108, 167, 54, 164, 167, 9, 223, 48, 21, 26, 111, 32, 217, 239, 25, 57]

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能：使用给定的 buffer 更新 HMAC 对象，在调用 finish 前可以多次更新。

参数：

• buffer: Array<Byte> - 需要追加的字节序列。

异常：

• CryptoException - 当 buffer 为空、finish 已经调用生成信息摘要场景，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.crypto.crypto.*

main() {
    let random = SecureRandom(priv: true)
    let key = random.nextBytes(32)
    let data1 = "Hello".toArray()
    let data2 = " ".toArray()
    let data3 = "World".toArray()

    let hmac = HMAC(key, HashType.MD5)
    hmac.write(data1) // 写入第一部分数据
    hmac.write(data2) // 写入第二部分数据
    hmac.write(data3) // 写入第三部分数据

    let result = hmac.finish()
    println("${hmac.algorithm}摘要: ${result}")

    return 0
}

可能的运行结果：

HMAC-MD5摘要: [99, 114, 182, 143, 83, 216, 88, 65, 50, 42, 136, 210, 128, 83, 39, 229]

class MD5

public class MD5 <: Digest {
    public init()
}

功能：提供 MD5 算法的实现接口。使用示例见 MD5 算法示例。

父类型：

• Digest

prop algorithm

public prop algorithm: String

功能：MD5 摘要算法的算法名称。

类型：String

示例：

import stdx.crypto.digest.*

main() {
    let md5 = MD5()

    let algorithm = md5.algorithm
    println("MD5算法: ${algorithm}")

    return 0
}

运行结果：

MD5算法: MD5

prop blockSize

public prop blockSize: Int64

功能：MD5 信息块长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let md5 = MD5()

    let blockSize = md5.blockSize
    println("块大小: ${blockSize}")

    return 0
}

运行结果：

块大小: 64

prop size

public prop size: Int64

功能：MD5 摘要信息长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let md5 = MD5()

    let size = md5.size
    println("摘要长度: ${size}")

    return 0
}

运行结果：

摘要长度: 16

init()

public init()

功能：无参构造函数，创建 MD5 对象。

示例：

import stdx.crypto.digest.*

main() {
    let md5 = MD5()

    println("MD5对象创建成功")
    println("算法: ${md5.algorithm}")
    println("块大小: ${md5.blockSize}")
    println("摘要长度: ${md5.size}")

    return 0
}

运行结果：

MD5对象创建成功
算法: MD5
块大小: 64
摘要长度: 16

func finish()

public func finish(): Array<Byte>

功能：返回生成的 MD5 值，注意调用 finish 后 MD5 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

返回值：

• Array<Byte> - 生成的 MD5 字节序列。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。

示例：

import stdx.crypto.digest.*

main() {
    let md5 = MD5()
    let data = "Hello, World!".toArray()

    md5.write(data)

    let result = md5.finish()
    println("MD5摘要: ${result}")

    return 0
}

运行结果：

MD5摘要: [101, 168, 226, 125, 136, 121, 40, 56, 49, 182, 100, 189, 139, 127, 10, 212]

func finish(Array<Byte>)

public func finish(to!: Array<Byte>): Unit

功能：获取生成的信息摘要值，注意调用 finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

参数：

• to!: Array<Byte> - 目标数组。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算或者指定输出数组大小不等于摘要算法信息长度，抛此异常。

示例：

import stdx.crypto.digest.*

main() {
    let md5 = MD5()
    let data = "Hello, World!".toArray()

    md5.write(data)

    var output = Array<Byte>(md5.size, repeat: 0)
    md5.finish(to: output)
    println("输出数组: ${output}")

    return 0
}

运行结果：

输出数组: [101, 168, 226, 125, 136, 121, 40, 56, 49, 182, 100, 189, 139, 127, 10, 212]

func reset()

public func reset(): Unit

功能：重置 MD5 对象到初始状态，清理 MD5 上下文。

示例：

import stdx.crypto.digest.*

main() {
    let md5 = MD5()
    let data1 = "Hello".toArray()
    let data2 = "World".toArray()

    md5.write(data1)
    let result1 = md5.finish()
    println("第一次摘要: ${result1}")

    md5.reset() // 重置MD5对象
    md5.write(data2)
    let result2 = md5.finish()
    println("重置后摘要: ${result2}")

    return 0
}

运行结果：

第一次摘要: [139, 26, 153, 83, 196, 97, 18, 150, 168, 39, 171, 248, 196, 120, 4, 215]
重置后摘要: [245, 167, 146, 78, 98, 30, 132, 201, 40, 10, 154, 39, 225, 188, 183, 246]

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能：使用给定的 buffer 更新 MD5 对象，在调用 finish 前可以多次更新。

参数：

• buffer: Array<Byte> - 输入字节序列。

异常：

• CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。

示例：

import stdx.crypto.digest.*

main() {
    let md5 = MD5()
    let data1 = "Hello".toArray()
    let data2 = " ".toArray()
    let data3 = "World".toArray()

    md5.write(data1) // 写入第一部分数据
    md5.write(data2) // 写入第二部分数据
    md5.write(data3) // 写入第三部分数据

    let result = md5.finish()
    println("MD5摘要: ${result}")

    return 0
}

运行结果：

MD5摘要: [177, 10, 141, 177, 100, 224, 117, 65, 5, 183, 169, 155, 231, 46, 63, 229]

class SHA1

public class SHA1 <: Digest {
    public init()
}

功能：提供 SHA1 算法的实现接口。使用示例见 SHA1 算法示例。

父类型：

• Digest

prop algorithm

public prop algorithm: String

功能：SHA1 摘要算法的算法名称。

类型：String

示例：

import stdx.crypto.digest.*

main() {
    let sha1 = SHA1()

    let algorithm = sha1.algorithm
    println("SHA1算法: ${algorithm}")

    return 0
}

运行结果：

SHA1算法: SHA1

prop blockSize

public prop blockSize: Int64

功能：SHA1 信息块长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sha1 = SHA1()

    let blockSize = sha1.blockSize
    println("块大小: ${blockSize}")

    return 0
}

运行结果：

块大小: 64

prop size

public prop size: Int64

功能：SHA1 摘要信息长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sha1 = SHA1()

    let size = sha1.size
    println("摘要长度: ${size}")

    return 0
}

运行结果：

摘要长度: 20

init()

public init()

功能：无参构造函数，创建 SHA1 对象。

示例：

import stdx.crypto.digest.*

main() {
    let sha1 = SHA1()

    println("SHA1对象创建成功")
    println("算法: ${sha1.algorithm}")
    println("块大小: ${sha1.blockSize}")
    println("摘要长度: ${sha1.size}")

    return 0
}

运行结果：

SHA1对象创建成功
算法: SHA1
块大小: 64
摘要长度: 20

func finish()

public func finish(): Array<Byte>

功能：返回生成的 SHA1 值，注意调用 finish 后 SHA1 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

返回值：

• Array<Byte> - 生成的 SHA1 字节序列。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha1 = SHA1()
    let data = "Hello, World!".toArray()

    sha1.write(data)

    let result = sha1.finish()
    let hexResult = toHexString(result)
    println("SHA1摘要: ${hexResult}")

    return 0
}

运行结果：

SHA1摘要: 0a0a9f2a6772942557ab5355d76af442f8f65e01

func finish(Array<Byte>)

public func finish(to!: Array<Byte>): Unit

功能：获取生成的信息摘要值，注意调用 finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

参数：

• to!: Array<Byte> - 目标数组。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算或者指定输出数组大小不等于摘要算法信息长度，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha1 = SHA1()
    let data = "Hello, World!".toArray()

    sha1.write(data)

    var output = Array<Byte>(sha1.size, repeat: 0)
    sha1.finish(to: output)
    let hexOutput = toHexString(output)
    println("输出摘要: ${hexOutput}")

    return 0
}

运行结果：

输出摘要: 0a0a9f2a6772942557ab5355d76af442f8f65e01

func reset()

public func reset(): Unit

功能：重置 SHA1 对象到初始状态，清理 SHA1 上下文。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha1 = SHA1()
    let data1 = "Hello".toArray()
    let data2 = "World".toArray()

    sha1.write(data1)
    let result1 = sha1.finish()
    let hexResult1 = toHexString(result1)
    println("第一次摘要: ${hexResult1}")

    sha1.reset() // 重置SHA1对象
    sha1.write(data2)
    let result2 = sha1.finish()
    let hexResult2 = toHexString(result2)
    println("重置后摘要: ${hexResult2}")

    return 0
}

运行结果：

第一次摘要: f7ff9e8b7bb2e09b70935a5d785e0cc5d9d0abf0
重置后摘要: 70c07ec18ef89c5309bbb0937f3a6342411e1fdd

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能：使用给定的 buffer 更新 SHA1 对象，在调用 finish 前可以多次更新。

参数：

• buffer: Array<Byte> - 输入字节序列。

异常：

• CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha1 = SHA1()
    let data1 = "Hello".toArray()
    let data2 = " ".toArray()
    let data3 = "World".toArray()

    sha1.write(data1) // 写入第一部分数据
    sha1.write(data2) // 写入第二部分数据
    sha1.write(data3) // 写入第三部分数据

    let result = sha1.finish()
    let hexResult = toHexString(result)
    println("SHA1摘要: ${hexResult}")

    return 0
}

运行结果：

SHA1摘要: 0a4d55a8d778e5022fab701977c5d840bbc486d0

class SHA224

public class SHA224 <: Digest {
    public init()
}

功能：提供 SHA224 算法的实现接口。使用示例见 SHA224 算法示例。

父类型：

• Digest

prop algorithm

public prop algorithm: String

功能：SHA224 摘要算法的算法名称。

类型：String

示例：

import stdx.crypto.digest.*

main() {
    let sha224 = SHA224()

    let algorithm = sha224.algorithm
    println("SHA224算法: ${algorithm}")

    return 0
}

运行结果：

SHA224算法: SHA224

prop blockSize

public prop blockSize: Int64

功能：SHA224 信息块长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sha224 = SHA224()

    let blockSize = sha224.blockSize
    println("块大小: ${blockSize}")

    return 0
}

运行结果：

块大小: 64

prop size

public prop size: Int64

功能：SHA224 摘要信息长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sha224 = SHA224()

    let size = sha224.size
    println("摘要长度: ${size}")

    return 0
}

运行结果：

摘要长度: 28

init()

public init()

功能：无参构造函数，创建 SHA224 对象。

示例：

import stdx.crypto.digest.*

main() {
    let sha224 = SHA224()

    println("SHA224对象创建成功")
    println("算法: ${sha224.algorithm}")
    println("块大小: ${sha224.blockSize}")
    println("摘要长度: ${sha224.size}")

    return 0
}

运行结果：

SHA224对象创建成功
算法: SHA224
块大小: 64
摘要长度: 28

func finish()

public func finish(): Array<Byte>

功能：返回生成的 SHA224 值，注意调用 finish 后 SHA224 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

返回值：

• Array<Byte> - 生成的 SHA224 字节序列。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha224 = SHA224()
    let data = "Hello, World!".toArray()

    sha224.write(data)

    let result = sha224.finish()
    let hexResult = toHexString(result)
    println("SHA224摘要: ${hexResult}")

    return 0
}

运行结果：

SHA224摘要: 72a23dfa411ba6fde01dbfabf3b00a709c93ebf273dc29e2d8b261ff

func finish(Array<Byte>)

public func finish(to!: Array<Byte>): Unit

功能：获取生成的信息摘要值，注意调用 finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

参数：

• to!: Array<Byte> - 目标数组。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算或者指定输出数组大小不等于摘要算法信息长度，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha224 = SHA224()
    let data = "Hello, World!".toArray()

    sha224.write(data)

    var output = Array<Byte>(sha224.size, repeat: 0)
    sha224.finish(to: output)
    let hexOutput = toHexString(output)
    println("输出摘要: ${hexOutput}")

    return 0
}

运行结果：

输出摘要: 72a23dfa411ba6fde01dbfabf3b00a709c93ebf273dc29e2d8b261ff

func reset()

public func reset(): Unit

功能：重置 SHA224 对象到初始状态，清理 SHA224 上下文。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha224 = SHA224()
    let data1 = "Hello".toArray()
    let data2 = "World".toArray()

    sha224.write(data1)
    let result1 = sha224.finish()
    let hexResult1 = toHexString(result1)
    println("第一次摘要: ${hexResult1}")

    sha224.reset() // 重置SHA224对象
    sha224.write(data2)
    let result2 = sha224.finish()
    let hexResult2 = toHexString(result2)
    println("重置后摘要: ${hexResult2}")

    return 0
}

运行结果：

第一次摘要: 4149da18aa8bfc2b1e382c6c26556d01a92c261b6436dad5e3be3fcc
重置后摘要: 12972632b6d3b6aa52bd6434552f08c1303d56b817119406466e9236

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能：使用给定的 buffer 更新 SHA224 对象，在调用 finish 前可以多次更新。

参数：

• buffer: Array<Byte> - 输入字节序列。

异常：

• CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha224 = SHA224()
    let data1 = "Hello".toArray()
    let data2 = " ".toArray()
    let data3 = "World".toArray()

    sha224.write(data1) // 写入第一部分数据
    sha224.write(data2) // 写入第二部分数据
    sha224.write(data3) // 写入第三部分数据

    let result = sha224.finish()
    let hexResult = toHexString(result)
    println("SHA224摘要: ${hexResult}")

    return 0
}

运行结果：

SHA224摘要: c4890faffdb0105d991a461e668e276685401b02eab1ef4372795047

class SHA256

public class SHA256 <: Digest {
    public init()
}

功能：提供 SHA256 算法的实现接口。使用示例见 SHA256 算法示例。

父类型：

• Digest

prop algorithm

public prop algorithm: String

功能：SHA256 摘要算法的算法名称。

类型：String

示例：

import stdx.crypto.digest.*

main() {
    let sha256 = SHA256()

    let algorithm = sha256.algorithm
    println("SHA256算法: ${algorithm}")

    return 0
}

运行结果：

SHA256算法: SHA256

prop blockSize

public prop blockSize: Int64

功能：SHA256 信息块长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sha256 = SHA256()

    let blockSize = sha256.blockSize
    println("块大小: ${blockSize}")

    return 0
}

运行结果：

块大小: 64

prop size

public prop size: Int64

功能：SHA256 摘要信息长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sha256 = SHA256()

    let size = sha256.size
    println("摘要长度: ${size}")

    return 0
}

运行结果：

摘要长度: 32

init()

public init()

功能：无参构造函数，创建 SHA256 对象。

示例：

import stdx.crypto.digest.*

main() {
    let sha256 = SHA256()

    println("SHA256对象创建成功")
    println("算法: ${sha256.algorithm}")
    println("块大小: ${sha256.blockSize}")
    println("摘要长度: ${sha256.size}")

    return 0
}

运行结果：

SHA256对象创建成功
算法: SHA256
块大小: 64
摘要长度: 32

func finish()

public func finish(): Array<Byte>

功能：返回生成的 SHA256 值，注意调用 finish 后 SHA256 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

返回值：

• Array<Byte> - 生成的 SHA256 字节序列。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha256 = SHA256()
    let data = "Hello, World!".toArray()

    sha256.write(data)

    let result = sha256.finish()
    let hexResult = toHexString(result)
    println("SHA256摘要: ${hexResult}")

    return 0
}

运行结果：

SHA256摘要: dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f

func finish(Array<Byte>)

public func finish(to!: Array<Byte>): Unit

功能：获取生成的信息摘要值，注意调用 finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

参数：

• to!: Array<Byte> - 目标数组。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算或者指定输出数组大小不等于摘要算法信息长度，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha256 = SHA256()
    let data = "Hello, World!".toArray()

    sha256.write(data)

    var output = Array<Byte>(sha256.size, repeat: 0)
    sha256.finish(to: output)
    let hexOutput = toHexString(output)
    println("输出摘要: ${hexOutput}")

    return 0
}

运行结果：

输出摘要: dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f

func reset()

public func reset(): Unit

功能：重置 SHA256 对象到初始状态，清理 SHA256 上下文。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha256 = SHA256()
    let data1 = "Hello".toArray()
    let data2 = "World".toArray()

    sha256.write(data1)
    let result1 = sha256.finish()
    let hexResult1 = toHexString(result1)
    println("第一次摘要: ${hexResult1}")

    sha256.reset() // 重置SHA256对象
    sha256.write(data2)
    let result2 = sha256.finish()
    let hexResult2 = toHexString(result2)
    println("重置后摘要: ${hexResult2}")

    return 0
}

运行结果：

第一次摘要: 185f8db32271fe25f561a6fc938b2e264306ec304eda518007d1764826381969
重置后摘要: 78ae647dc5544d227130a0682a51e30bc7777fbb6d8a8f17007463a3ecd1d524

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能：使用给定的 buffer 更新 SHA256 对象，在调用 finish 前可以多次更新。

参数：

• buffer: Array<Byte> - 输入字节序列。

异常：

• CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha256 = SHA256()
    let data1 = "Hello".toArray()
    let data2 = " ".toArray()
    let data3 = "World".toArray()

    sha256.write(data1) // 写入第一部分数据
    sha256.write(data2) // 写入第二部分数据
    sha256.write(data3) // 写入第三部分数据

    let result = sha256.finish()
    let hexResult = toHexString(result)
    println("SHA256摘要: ${hexResult}")

    return 0
}

运行结果：

SHA256摘要: a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e

class SHA384

public class SHA384 <: Digest {
    public init()
}

功能：提供 SHA384 算法的实现接口。使用示例见 SHA384 算法示例。

父类型：

• Digest

prop algorithm

public prop algorithm: String

功能：SHA384 摘要算法的算法名称。

类型：String

示例：

import stdx.crypto.digest.*

main() {
    let sha384 = SHA384()

    let algorithm = sha384.algorithm
    println("SHA384算法: ${algorithm}")

    return 0
}

运行结果：

SHA384算法: SHA384

prop blockSize

public prop blockSize: Int64

功能：SHA384 信息块长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sha384 = SHA384()

    let blockSize = sha384.blockSize
    println("块大小: ${blockSize}")

    return 0
}

运行结果：

块大小: 128

prop size

public prop size: Int64

功能：SHA384 摘要信息长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sha384 = SHA384()

    let size = sha384.size
    println("摘要长度: ${size}")

    return 0
}

运行结果：

摘要长度: 48

init()

public init()

功能：无参构造函数，创建 SHA384 对象。

示例：

import stdx.crypto.digest.*

main() {
    let sha384 = SHA384()

    println("SHA384对象创建成功")
    println("算法: ${sha384.algorithm}")
    println("块大小: ${sha384.blockSize}")
    println("摘要长度: ${sha384.size}")

    return 0
}

运行结果：

SHA384对象创建成功
算法: SHA384
块大小: 128
摘要长度: 48

func finish()

public func finish(): Array<Byte>

功能：返回生成的 SHA384 值，注意调用 finish 后 SHA384 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

返回值：

• Array<Byte> - 生成的 SHA384 字节序列。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha384 = SHA384()
    let data = "Hello, World!".toArray()

    sha384.write(data)

    let result = sha384.finish()
    let hexResult = toHexString(result)
    println("SHA384摘要: ${hexResult}")

    return 0
}

运行结果：

SHA384摘要: 5485cc9b3365b4305dfb4e8337e0a598a574f8242bf17289e0dd6c20a3cd44a089de16ab4ab308f63e44b1170eb5f515

func finish(Array<Byte>)

public func finish(to!: Array<Byte>): Unit

功能：获取生成的信息摘要值，注意调用 finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

参数：

• to!: Array<Byte> - 目标数组。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算或者指定输出数组大小不等于摘要算法信息长度，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha384 = SHA384()
    let data = "Hello, World!".toArray()

    sha384.write(data)

    var output = Array<Byte>(sha384.size, repeat: 0)
    sha384.finish(to: output)
    let hexOutput = toHexString(output)
    println("输出摘要: ${hexOutput}")

    return 0
}

运行结果：

输出摘要: 5485cc9b3365b4305dfb4e8337e0a598a574f8242bf17289e0dd6c20a3cd44a089de16ab4ab308f63e44b1170eb5f515

func reset()

public func reset(): Unit

功能：重置 SHA384 对象到初始状态，清理 SHA384 上下文。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha384 = SHA384()
    let data1 = "Hello".toArray()
    let data2 = "World".toArray()

    sha384.write(data1)
    let result1 = sha384.finish()
    let hexResult1 = toHexString(result1)
    println("第一次摘要: ${hexResult1}")

    sha384.reset() // 重置SHA384对象
    sha384.write(data2)
    let result2 = sha384.finish()
    let hexResult2 = toHexString(result2)
    println("重置后摘要: ${hexResult2}")

    return 0
}

运行结果：

第一次摘要: 3519fe5ad2c596efe3e276a6f351b8fc0b03db861782490d45f7598ebd0ab5fd5520ed102f38c4a5ec834e98668035fc
重置后摘要: ed7ced84875773603af90402e42c65f3b48a5e77f84adc7a19e8f3e8d310101022f552aec70e9e1087b225930c1d260a

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能：使用给定的 buffer 更新 SHA384 对象，在调用 finish 前可以多次更新。

参数：

• buffer: Array<Byte> - 输入字节序列。

异常：

• CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha384 = SHA384()
    let data1 = "Hello".toArray()
    let data2 = " ".toArray()
    let data3 = "World".toArray()

    sha384.write(data1) // 写入第一部分数据
    sha384.write(data2) // 写入第二部分数据
    sha384.write(data3) // 写入第三部分数据

    let result = sha384.finish()
    let hexResult = toHexString(result)
    println("SHA384摘要: ${hexResult}")

    return 0
}

运行结果：

SHA384摘要: 99514329186b2f6ae4a1329e7ee6c610a729636335174ac6b740f9028396fcc803d0e93863a7c3d90f86beee782f4f3f

class SHA512

public class SHA512 <: Digest {
    public init()
}

功能：提供 SHA512 算法的实现接口。使用示例见 SHA512 算法示例。

父类型：

• Digest

prop algorithm

public prop algorithm: String

功能：SHA512 摘要算法的算法名称。

类型：String

示例：

import stdx.crypto.digest.*

main() {
    let sha512 = SHA512()

    let algorithm = sha512.algorithm
    println("SHA512算法: ${algorithm}")

    return 0
}

运行结果：

SHA512算法: SHA512

prop blockSize

public prop blockSize: Int64

功能：SHA512 信息块长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sha512 = SHA512()

    let blockSize = sha512.blockSize
    println("块大小: ${blockSize}")

    return 0
}

运行结果：

块大小: 128

prop size

public prop size: Int64

功能：SHA512 摘要信息长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sha512 = SHA512()

    let size = sha512.size
    println("摘要长度: ${size}")

    return 0
}

运行结果：

摘要长度: 64

init()

public init()

功能：无参构造函数，创建 SHA512 对象。

示例：

import stdx.crypto.digest.*

main() {
    let sha512 = SHA512()

    println("SHA512对象创建成功")
    println("算法: ${sha512.algorithm}")
    println("块大小: ${sha512.blockSize}")
    println("摘要长度: ${sha512.size}")

    return 0
}

运行结果：

SHA512对象创建成功
算法: SHA512
块大小: 128
摘要长度: 64

func finish()

public func finish(): Array<Byte>

功能：返回生成的 SHA512 值，注意调用 finish 后 SHA512 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

返回值：

• Array<Byte> - 生成的 SHA512 字节序列。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha512 = SHA512()
    let data = "Hello, World!".toArray()

    sha512.write(data)

    let result = sha512.finish()
    let hexResult = toHexString(result)
    println("SHA512摘要: ${hexResult}")

    return 0
}

运行结果：

SHA512摘要: 374d794a95cdcfd8b35993185fef9ba368f160d8daf432d08ba9f1ed1e5abe6cc69291e0fa2fe0006a52570ef18c19def4e617c33ce52ef0a6e5fbe318cb0387

func finish(Array<Byte>)

public func finish(to!: Array<Byte>): Unit

功能：获取生成的信息摘要值，注意调用 finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

参数：

• to!: Array<Byte> - 目标数组。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算或者指定输出数组大小不等于摘要算法信息长度，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha512 = SHA512()
    let data = "Hello, World!".toArray()

    sha512.write(data)

    var output = Array<Byte>(sha512.size, repeat: 0)
    sha512.finish(to: output)
    let hexOutput = toHexString(output)
    println("输出摘要: ${hexOutput}")

    return 0
}

运行结果：

输出摘要: 374d794a95cdcfd8b35993185fef9ba368f160d8daf432d08ba9f1ed1e5abe6cc69291e0fa2fe0006a52570ef18c19def4e617c33ce52ef0a6e5fbe318cb0387

func reset()

public func reset(): Unit

功能：重置 SHA512 对象到初始状态，清理 SHA512 上下文。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha512 = SHA512()
    let data1 = "Hello".toArray()
    let data2 = "World".toArray()

    sha512.write(data1)
    let result1 = sha512.finish()
    let hexResult1 = toHexString(result1)
    println("第一次摘要: ${hexResult1}")

    sha512.reset() // 重置SHA512对象
    sha512.write(data2)
    let result2 = sha512.finish()
    let hexResult2 = toHexString(result2)
    println("重置后摘要: ${hexResult2}")

    return 0
}

运行结果：

第一次摘要: 3615f80c9d293ed7402687f94b22d58e529b8cc7916f8fac7fddf7fbd5af4cf777d3d795a7a00a16bf7e7f3fb9561ee9baae480da9fe7a18769e71886b03f315
重置后摘要: 8ea77393a42ab8fa92500fb077a9509cc32bc95e72712efa116edaf2edfae34fbb682efdd6c5dd13c117e08bd4aaef71291d8aace2f890273081d0677c16df0f

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能：使用给定的 buffer 更新 SHA512 对象，在调用 finish 前可以多次更新。

参数：

• buffer: Array<Byte> - 输入字节序列。

异常：

• CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sha512 = SHA512()
    let data1 = "Hello".toArray()
    let data2 = " ".toArray()
    let data3 = "World".toArray()

    sha512.write(data1) // 写入第一部分数据
    sha512.write(data2) // 写入第二部分数据
    sha512.write(data3) // 写入第三部分数据

    let result = sha512.finish()
    let hexResult = toHexString(result)
    println("SHA512摘要: ${hexResult}")

    return 0
}

运行结果：

SHA512摘要: 2c74fd17edafd80e8447b0d46741ee243b7eb74dd2149a0ab1b9246fb30382f27e853d8585719e0e67cbda0daa8f51671064615d645ae27acb15bfb1447f459b

class SM3

public class SM3 <: Digest {
    public init()
}

功能：提供 SM3 算法的实现接口。使用示例见 SM3 算法示例。

父类型：

• Digest

prop algorithm

public prop algorithm: String

功能：SM3 摘要算法的算法名称。

类型：String

示例：

import stdx.crypto.digest.*

main() {
    let sm3 = SM3()

    let algorithm = sm3.algorithm
    println("SM3算法: ${algorithm}")

    return 0
}

运行结果：

SM3算法: SM3

prop blockSize

public prop blockSize: Int64

功能：SM3 信息块长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sm3 = SM3()

    let blockSize = sm3.blockSize
    println("块大小: ${blockSize}")

    return 0
}

运行结果：

块大小: 64

prop size

public prop size: Int64

功能：SM3 摘要信息长度，单位字节。

类型：Int64

示例：

import stdx.crypto.digest.*

main() {
    let sm3 = SM3()

    let size = sm3.size
    println("摘要长度: ${size}")

    return 0
}

运行结果：

摘要长度: 32

init()

public init()

功能：无参构造函数，创建 SM3 对象。

示例：

import stdx.crypto.digest.*

main() {
    let sm3 = SM3()

    println("SM3对象创建成功")
    println("算法: ${sm3.algorithm}")
    println("块大小: ${sm3.blockSize}")
    println("摘要长度: ${sm3.size}")

    return 0
}

运行结果：

SM3对象创建成功
算法: SM3
块大小: 64
摘要长度: 32

func finish()

public func finish(): Array<Byte>

功能：返回生成的 SM3 值，注意调用 finish 后 SM3 上下文会发生改变，finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

返回值：

• Array<Byte> - 生成的 SM3 字节序列。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sm3 = SM3()
    let data = "Hello, World!".toArray()

    sm3.write(data)

    let result = sm3.finish()
    let hexResult = toHexString(result)
    println("SM3摘要: ${hexResult}")

    return 0
}

运行结果：

SM3摘要: 7ed26cbf0bee4ca7d55c1e64714c4aa7d1f163089ef5ceb603cd102c81fbcbc5

func finish(Array<Byte>)

public func finish(to!: Array<Byte>): Unit

功能：获取生成的信息摘要值，注意调用 finish 后不可以再进行摘要计算，如重新计算需要 reset 重置上下文。

参数：

• to!: Array<Byte> - 目标数组。

异常：

• CryptoException - 未重置上下文再次调用 finish 进行摘要计算或者指定输出数组大小不等于摘要算法信息长度，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sm3 = SM3()
    let data = "Hello, World!".toArray()

    sm3.write(data)

    var output = Array<Byte>(sm3.size, repeat: 0)
    sm3.finish(to: output)
    let hexOutput = toHexString(output)
    println("输出摘要: ${hexOutput}")

    return 0
}

运行结果：

输出摘要: 7ed26cbf0bee4ca7d55c1e64714c4aa7d1f163089ef5ceb603cd102c81fbcbc5

func reset()

public func reset(): Unit

功能：重置 SM3 对象到初始状态，清理 SM3 上下文。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sm3 = SM3()
    let data1 = "Hello".toArray()
    let data2 = "World".toArray()

    sm3.write(data1)
    let result1 = sm3.finish()
    let hexResult1 = toHexString(result1)
    println("第一次摘要: ${hexResult1}")

    sm3.reset() // 重置SM3对象
    sm3.write(data2)
    let result2 = sm3.finish()
    let hexResult2 = toHexString(result2)
    println("重置后摘要: ${hexResult2}")

    return 0
}

运行结果：

第一次摘要: dc74f051ad5bc19ba721bf0023e10de03bae29bbe013c43988bae55828bcebbc
重置后摘要: 5c54fe15f19a6b15bb0dcf4d1aef6b6c6439d95aacfea9e86bb7e6ba569b081a

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能：使用给定的 buffer 更新 SM3 对象，在调用 finish 前可以多次更新。

参数：

• buffer: Array<Byte> - 输入字节序列。

异常：

• CryptoException - 已经调用 finish 进行摘要计算后未重置上下文，抛此异常。

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    let sm3 = SM3()
    let data1 = "Hello".toArray()
    let data2 = " ".toArray()
    let data3 = "World".toArray()

    sm3.write(data1) // 写入第一部分数据
    sm3.write(data2) // 写入第二部分数据
    sm3.write(data3) // 写入第三部分数据

    let result = sm3.finish()
    let hexResult = toHexString(result)
    println("SM3摘要: ${hexResult}")

    return 0
}

运行结果：

SM3摘要: 77015816143ee627f4fa410b6dad2bdb9fcbdf1e061a452a686b8711a484c5d7

结构体

struct HashType

public struct HashType <: ToString & Equatable<HashType>

功能：此类为 Hash 算法类别结构体，MD5、SHA1、SHA224、SHA256、SHA384、SHA512 均为常用摘要算法。

父类型：

• ToString
• Equatable<HashType>

prop MD5

public static prop MD5: HashType

功能：返回 MD5 类型。

类型：HashType

示例：

import stdx.crypto.digest.*

main() {
    let md5Type = HashType.MD5
    println("MD5类型: ${md5Type}")

    return 0
}

运行结果：

MD5类型: MD5

prop SHA1

public static prop SHA1: HashType

功能：返回 SHA1 类型。

类型：HashType

示例：

import stdx.crypto.digest.*

main() {
    let sha1Type = HashType.SHA1
    println("SHA1类型: ${sha1Type}")

    return 0
}

运行结果：

SHA1类型: SHA1

prop SHA224

public static prop SHA224: HashType

功能：返回 SHA224 类型。

类型：HashType

示例：

import stdx.crypto.digest.*

main() {
    let sha224Type = HashType.SHA224
    println("SHA224类型: ${sha224Type}")

    return 0
}

运行结果：

SHA224类型: SHA224

prop SHA256

public static prop SHA256: HashType

功能：返回 SHA256 类型。

类型：HashType

示例：

import stdx.crypto.digest.*

main() {
    let sha256Type = HashType.SHA256
    println("SHA256类型: ${sha256Type}")

    return 0
}

运行结果：

SHA256类型: SHA256

prop SHA384

public static prop SHA384: HashType

功能：返回 SHA384 类型。

类型：HashType

示例：

import stdx.crypto.digest.*

main() {
    let sha384Type = HashType.SHA384
    println("SHA384类型: ${sha384Type}")

    return 0
}

运行结果：

SHA384类型: SHA384

prop SHA512

public static prop SHA512: HashType

功能：返回 SHA512 类型。

类型：HashType

示例：

import stdx.crypto.digest.*

main() {
    let sha512Type = HashType.SHA512
    println("SHA512类型: ${sha512Type}")

    return 0
}

运行结果：

SHA512类型: SHA512

prop SM3

public static prop SM3: HashType

功能：返回 SM3 类型。

类型：HashType

示例：

import stdx.crypto.digest.*

main() {
    let sm3Type = HashType.SM3
    println("SM3类型: ${sm3Type}")

    return 0
}

运行结果：

SM3类型: SM3

func toString()

public func toString(): String

功能：获取 Hash 算法名称。

返回值：

• String - Hash 算法名称。

示例：

import stdx.crypto.digest.*

main() {
    let md5Type = HashType.MD5
    let sha1Type = HashType.SHA1

    let md5Name = md5Type.toString()
    let sha1Name = sha1Type.toString()

    println("MD5名称: ${md5Name}")
    println("SHA1名称: ${sha1Name}")

    return 0
}

运行结果：

MD5名称: MD5
SHA1名称: SHA1

operator func !=(HashType)

public override operator func !=(other: HashType): Bool

功能：判断两 HashType 是否引用不同实例。

参数：

• other: HashType - 对比的 HashType。

返回值：

• Bool - 不相同返回 true；否则，返回 false。

示例：

import stdx.crypto.digest.*

main() {
    let md5Type = HashType.MD5
    let sha1Type = HashType.SHA1
    let anotherMd5Type = HashType.MD5

    let isNotEqual1 = md5Type != sha1Type
    let isNotEqual2 = md5Type != anotherMd5Type

    println("MD5 != SHA1: ${isNotEqual1}")
    println("MD5 != MD5: ${isNotEqual2}")

    return 0
}

运行结果：

MD5 != SHA1: true
MD5 != MD5: false

operator func ==(HashType)

public override operator func ==(other: HashType): Bool

功能：判断两 HashType 是否引用同一实例。

参数：

• other: HashType - 对比的 HashType。

返回值：

• Bool - 相同返回 true；否则，返回 false。

示例：

import stdx.crypto.digest.*

main() {
    let md5Type = HashType.MD5
    let sha1Type = HashType.SHA1
    let anotherMd5Type = HashType.MD5

    let isEqual1 = md5Type == sha1Type
    let isEqual2 = md5Type == anotherMd5Type

    println("MD5 == SHA1: ${isEqual1}")
    println("MD5 == MD5: ${isEqual2}")

    return 0
}

运行结果：

MD5 == SHA1: false
MD5 == MD5: true

digest 使用

MD5 算法示例

调用 MD5 成员函数

示例：

import stdx.crypto.digest.*
import std.convert.*
import std.crypto.digest.*
import stdx.encoding.hex.*

main() {
    var str: String = "helloworld"
    var md5Instance = MD5()
    md5Instance.write(str.toArray())
    var md: Array<Byte> = md5Instance.finish()
    var result: String = toHexString(md)
    println(result)
    return 0
}

运行结果：

fc5e038d38a57032085441e7fe7010b0

SHA1 算法示例

调用 SHA1 成员函数

示例：

import stdx.crypto.digest.*
import std.convert.*
import std.crypto.digest.*
import stdx.encoding.hex.*

main() {
    var str: String = "helloworld"
    var sha1Instance = SHA1()
    sha1Instance.write(str.toArray())
    var md: Array<Byte> = sha1Instance.finish()
    var result: String = toHexString(md)
    println(result)
    return 0
}

运行结果：

6adfb183a4a2c94a2f92dab5ade762a47889a5a1

SHA224 算法示例

调用 SHA224 成员函数

示例：

import stdx.crypto.digest.*
import std.convert.*
import std.crypto.digest.*
import stdx.encoding.hex.*

main() {
    var str: String = "helloworld"
    var sha224Instance = SHA224()
    sha224Instance.write(str.toArray())
    var md: Array<Byte> = sha224Instance.finish()
    var result: String = toHexString(md)
    println(result)
    return 0
}

运行结果：

b033d770602994efa135c5248af300d81567ad5b59cec4bccbf15bcc

SHA256 算法示例

调用 SHA256 成员函数

示例：

import stdx.crypto.digest.*
import std.convert.*
import std.crypto.digest.*
import stdx.encoding.hex.*

main() {
    var str: String = "helloworld"
    var sha256Instance = SHA256()
    sha256Instance.write(str.toArray())
    var md: Array<Byte> = sha256Instance.finish()
    var result: String = toHexString(md)
    println(result)
    return 0
}

运行结果：

936a185caaa266bb9cbe981e9e05cb78cd732b0b3280eb944412bb6f8f8f07af

SHA384 算法示例

调用 SHA384 成员函数

示例：

import stdx.crypto.digest.*
import std.convert.*
import std.crypto.digest.*
import stdx.encoding.hex.*

main() {
    var str: String = "helloworld"
    var sha384Instance = SHA384()
    sha384Instance.write(str.toArray())
    var md: Array<Byte> = sha384Instance.finish()
    var result: String = toHexString(md)
    println(result)
    return 0
}

运行结果：

97982a5b1414b9078103a1c008c4e3526c27b41cdbcf80790560a40f2a9bf2ed4427ab1428789915ed4b3dc07c454bd9

SHA512 算法示例

调用 SHA512 成员函数

示例：

import stdx.crypto.digest.*
import std.convert.*
import std.crypto.digest.*
import stdx.encoding.hex.*

main() {
    var str: String = "helloworld"
    var sha512Instance = SHA512()
    sha512Instance.write(str.toArray())
    var md: Array<Byte> = sha512Instance.finish()
    var result: String = toHexString(md)
    println(result)
    return 0
}

运行结果：

1594244d52f2d8c12b142bb61f47bc2eaf503d6d9ca8480cae9fcf112f66e4967dc5e8fa98285e36db8af1b8ffa8b84cb15e0fbcf836c3deb803c13f37659a60

HMAC 算法示例

说明

目前只支持 HMAC-SHA512。

调用 HMAC-SHA512 成员函数

示例：

import stdx.crypto.digest.*
import stdx.encoding.hex.*

main() {
    var algorithm: HashType = HashType.SHA512
    var key: Array<UInt8> = "cangjie".toArray()
    var data1: Array<UInt8> = "123".toArray()
    var data2: Array<UInt8> = "456".toArray()
    var data3: Array<UInt8> = "789".toArray()
    var data4: Array<UInt8> = "123456789".toArray()
    var hmac = HMAC(key, algorithm)
    hmac.write(data1)
    hmac.write(data2)
    hmac.write(data3)
    var md1: Array<Byte> = hmac.finish()
    var result1: String = toHexString(md1)
    println(result1)

    hmac.reset()
    hmac.write(data4)
    var md2: Array<Byte> = hmac.finish()
    var result2: String = toHexString(md2)
    println(result2)
    println(HMAC.equal(md1, md2))
    return 0
}

运行结果：

2bafeb53b60a119d38793a886c7744f5027d7eaa3702351e75e4ff9bf255e3ce296bf41f80adda2861e81bd8efc52219df821852d84a17fb625e3965ebf2fdd9
2bafeb53b60a119d38793a886c7744f5027d7eaa3702351e75e4ff9bf255e3ce296bf41f80adda2861e81bd8efc52219df821852d84a17fb625e3965ebf2fdd9
true

SM3 算法示例

调用 SM3 成员函数

示例：

import stdx.crypto.digest.*
import std.convert.*
import std.crypto.digest.*
import stdx.encoding.hex.*

main() {
    var str: String = "helloworld"
    var sm3Instance = SM3()
    sm3Instance.write(str.toArray())
    var md: Array<Byte> = sm3Instance.finish()
    var result: String = toHexString(md)
    println(result)
    return 0
}

运行结果：

c70c5f73da4e8b8b73478af54241469566f6497e16c053a03a0170fa00078283

stdx.crypto.keys

功能介绍

keys 包提供非对称加密和签名算法，包括 RSA 和 SM2 非对称加密算法以及 ECDSA 签名算法。

使用本包需要外部依赖 OpenSSL 3 的 crypto 动态库文件，故使用前需安装相关工具。

• 对于 Linux 操作系统，可参考以下方式：

  • 如果系统的包管理工具支持安装 OpenSSL 3 开发工具包，可通过这个方式安装，并确保系统安装目录下含有 libcrypto.so 和 libcrypto.so.3 这两个动态库文件，例如 Ubuntu 22.04 系统上可使用 sudo apt install libssl-dev 命令安装 libssl-dev 工具包；
  • 如果无法通过上面的方式安装，可自行下载 OpenSSL 3.x.x 源码编译安装软件包，并确保安装目录下含有 libcrypto.so 和 libcrypto.so.3 这两个动态库文件，然后可选择下面任意一种方式来保证系统链接器可以找到这些文件：
    • 在系统未安装 OpenSSL 的场景，安装时选择直接安装到系统路径下；
    • 安装在自定义目录的场景，将这些文件所在目录设置到环境变量 LD_LIBRARY_PATH 以及 LIBRARY_PATH 中。

• 对于 Windows 操作系统，可按照以下步骤：

  • 自行下载 OpenSSL 3.x.x 源码编译安装 x64 架构软件包或者自行下载安装第三方预编译的供开发人员使用的 OpenSSL 3.x.x 软件包；
  • 确保安装目录下含有 libcrypto.dll.a（或 libcrypto.lib）、libcrypto-3-x64.dll 这两个库文件；
  • 将 libcrypto.dll.a（或 libcrypto.lib）所在的目录路径设置到环境变量 LIBRARY_PATH 中，将 libcrypto-3-x64.dll 所在的目录路径设置到环境变量 PATH 中。

• 对于 macOS 操作系统，可参考以下方式：

  • 使用 brew install openssl@3 安装，并确保系统安装目录下含有 libcrypto.dylib 和 libcrypto.3.dylib 这两个动态库文件；
  • 如果无法通过上面的方式安装，可自行下载 OpenSSL 3.x.x 源码编译安装软件包，并确保安装目录下含有 libcrypto.dylib 和 libcrypto.3.dylib 这两个动态库文件，然后可选择下面任意一种方式来保证系统链接器可以找到这些文件：
    • 在系统未安装 OpenSSL 的场景，安装时选择直接安装到系统路径下；
    • 安装在自定义目录的场景，将这些文件所在目录设置到环境变量 DYLD_LIBRARY_PATH 以及 LIBRARY_PATH 中。

• 对于 Android 操作系统，可参考以下方式：

  • 由于 Android 系统默认自带的 OpenSSL 是裁剪版本，部分接口可能找不到符号而抛出异常，因此需要用户自行编译安装完整的 OpenSSL 3.x.x 版本；
  • 可自行下载 OpenSSL 3.x.x 源码，使用 Android NDK 交叉编译生成对应架构（当前只支持 arm64-v8a）的动态库文件，确保编译产物中含有 libcrypto.so 和 libcrypto.so.3 这些动态库文件；
  • 将这些文件所在目录设置到环境变量 LD_LIBRARY_PATH 中。