仓颉编程语言库 API

仓颉编程语言库包括 std 模块(标准库模块)和一些常用的扩展模块,每个模块下包含若干包,提供与该模块相关的具体而丰富的功能。

标准库为开发者提供了最通用的 API,包括输入输出功能、基础数据结构和算法、日期和时间表示等。扩展库则专注于某一领域,如 compress 模块提供压缩解压能力,crypto 模块提供加解密相关的能力,net 模块专注于提供高效的网络协议解析和网络通信能力。

标准库和官方提供的扩展库均遵守仓颉语言编程规范,在功能、性能、安全等方面符合官方标准。

说明:

  • 标准库和官方提供的扩展库目前都随仓颉编译器、工具链一起发布,不需要用户单独下载。
  • 根据后续演进计划,扩展库可能会从仓颉编译器、工具链发布件中剥离,放入专门的仓库管理。

使用介绍

在仓颉编程语言中,包是编译的最小单元,每个包可以单独输出 AST 文件、静态库文件、动态库文件等产物。包可以定义子包,从而构成树形结构。没有父包的包称为 root 包,root 包及其子包(包括子包的子包)构成的整棵树称为模块(module)。模块的名称与 root 包相同,是第三方开发者发布的最小单元。

包的导入规则如下:

  • 可以导入某个包中的一个顶层声明或定义,语法如下:

    import fullPackageName.itemName
    

    其中 fullPackageName 为完整路径包名,itemName 为声明的名字,例如:

    import std.collection.ArrayList
    
  • 如果要导入的多个 itemName 同属于一个 fullPackageName,可以使用:

    import fullPackageName.{itemName[, itemName]*}
    

    例如:

    import std.collection.{ArrayList, HashMap}
    
  • 还可以将 fullPackageName 包中所有 public 修饰的顶层声明或定义全部导入,语法如下:

    import fullPackageName.*
    

    例如:

    import std.collection.*
    

模块列表

当前仓颉标准库提供了如下模块:

模块名功能
stdstd 模块意指标准库,标准库是指在编程语言中预先定义的一组函数、类、结构体等,旨在提供常用的功能和工具,以便开发者能够更快速、更高效地编写程序。
compresscompress 模块提供压缩解压功能。
cryptocrypto 模块提供安全加密能力。
encodingencoding 模块提供字符编解码功能。
fuzzfuzz 模块提供基于覆盖率反馈的模糊测试能力。
loglog 模块提供了日志记录相关的能力。
loggerlogger 模块提供文本格式和 JSON 格式日志打印功能。
netnet 模块提供了网络通信相关的能力。
serializationserialization 模块提供了序列化和反序列化能力。

std 模块

std 功能介绍

std 模块意指标准库,标准库是指在编程语言中预先定义的一组函数、类、结构体等,旨在提供常用的功能和工具,以便开发者能够更快速、更高效地编写程序。

仓颉标准库提供的能力包括(不限于):

  • 输入输出:控制台输入输出、文件输入输出等。
  • 数据结构:数组、链表、哈希表等。
  • 算法:排序、求和、求幂、求对数等。
  • 日期和时间:获取时间、格式化时间、设置定时任务等。
  • 并发编程:锁、原子操作等。

仓颉标准库有其三项特点和追求:

  • 使用方便:标准库随编译器、工具链一起发布,不需要用户另外下载,开箱即用。
  • 功能通用:标准库提供了开发者最常使用的一些库能力,旨在为开发者解决大部分基础问题。
  • 质量标杆:标准库追求在性能、代码风格等方面为其他仓颉库树立范例和标杆。

std 模块的包列表

std 模块提供了如下包:

包名功能
corecore 包是标准库的核心包,提供了适用仓颉语言编程最基本的一些 API 能力。
argoptargopt 包提供从命令行参数字符串解析出参数名和参数值的相关能力。
astast 包主要包含了仓颉源码的语法解析器和仓颉语法树节点,提供语法解析函数。
binarybinary 包提供了基础数据类型和二进制字节数组的不同端序转换接口,以及端序反转接口。
collectioncollection 包提供了常见数据结构的高效实现、相关抽象的接口的定义以及在集合类型中常用的函数功能。
collection.concurrentcollection.concurrent 包提供了并发安全的集合类型实现。
consoleconsole 包提供和标准输入、标准输出、标准错误进行交互的方法。
convertconvert 包提供从字符串转到特定类型的 Convert 系列函数。
crypto.ciphercrypto.cipher 包提供对称加解密通用接口。
crypto.digestcrypto.digest 包提供常用摘要算法的通用接口,包括 MD5、SHA1、SHA224、SHA256、SHA384、SHA512、HMAC、SM3。
database.sqldatabase.sql 包提供仓颉访问数据库的接口。
derivingderiving 包提供一组宏来自动生成接口实现。
ffi.pythonffi.python 包提供仓颉与 Python 语言互操作调用的能力,以兼容强大的计算和 AI 生态。
formatformat 包提供格式化能力,主要为将仓颉类型实例转换为格式化字符串。
fsfs(file system)包提供对文件、文件夹、路径、文件元数据信息的一些操作函数。
ioio 包提供程序与外部设备进行数据交换的能力。
loglog 包提供日志管理和打印功能。
mathmath 包提供常见的数学运算,常数定义,浮点数处理等功能。
math.numericmath.numeric 包对基础类型可表达范围之外提供扩展能力。
netnet 包提供常见的网络通信功能。
objectpoolobjectpool 包提供了对象缓存和复用的功能。
posixposix 包主要适配 POSIX 系统接口。
processprocess 包主要提供 Process 进程操作接口,主要包括进程创建,标准流获取,进程等待,进程信息查询等。
overflowoverflow 包提供了溢出处理相关能力。
randomrandom 包提供生成伪随机数的能力。
reflectreflect 包提供了反射功能,使得程序在运行时能够获取到各种实例的类型信息,并进行各种读写和调用操作。
regexregex 包使用正则表达式分析处理文本的能力(仅支持 Ascii 编码字符串),支持查找、分割、替换、验证等功能。
runtimeruntime 包的作用是与程序的运行时环境进行交互,提供了一系列函数和变量,用于控制、管理和监视程序的执行。
socketsocket 包用于进行网络通信,提供启动 Socket 服务器、连接 Socket 服务器、发送数据、接收数据等功能。
sortsort 包提供数组类型的排序函数。
syncsync 包提供并发编程相关的能力。
timetime 包提供了与时间相关的类型,包括日期时间,时间间隔,单调时间和时区等,并提供了计算和比较的功能。
unicodeunicode 包提供了按 unicode 编码标准处理字符的能力。
unittestunittest 包用于编写仓颉项目单元测试代码,提供包括代码编写、运行和调测在内的基本功能。
unittest.mockunittest.mock 包提供仓颉单元测试的mock 框架,提供 API 用于创建和配置mock 对象 ,这些 mock 对象与真实对象拥有签名一致的 API 。
unittest.testmacrounittest.testmacro 为单元测试框架提供了用户所需的宏。
unittest.mock.mockmacrounittest.mock.mockmacro 为 mock 框架提供了用户所需的宏。
unittest.commonunittest.common 为单元测试框架提供了打印所需的类型和一些通用方法。
unittest.diffunittest.diff 为单元测试框架提供了打印差异对比信息所需的 API 。
unittest.prop_testunittest.prop_test 为单元测试框架提供了参数化测试所需的类型和一些通用方法。

std.core 包

功能介绍

core 包是标准库的核心包,提供了适用仓颉语言编程最基本的一些 API 能力。

提供了内置类型(有符号整型、无符号整型、浮点型等)、常用函数(print、println、eprint 等)、常用接口(ToString、Hashable、Equatable、Collection 等)、常用类和结构体(Array、String、Range 等)、常用异常类(Error、Exception 以及它们的一些细分子类)。

说明:

core 包不需要显式导入,默认导入。

API 列表

函数

函数名功能
acquireArrayRawData(Array<T>) where T <: CType获取 Array<T> 中数据的原始指针实例,T 需要满足 CType 约束。
alignOf<T>() where T <: CType获取类型 T 的内存对齐值。
eprint(String, Bool)将指定字符串打印到标准错误文本流。
eprintln(String)将指定字符串打印到标准错误文本流,末尾添加换行。
eprint<T>(T, Bool) where T <: ToString将指定 T 类型实例的字符串表示打印到标准错误文本流。
eprintln<T>(T) where T <: ToString将指定 T 类型实例的字符串表示打印到标准错误文本流,末尾添加换行。
ifNone(Option<T>, () -> Unit)如果输入是 Option.None 类型数据,则执行 action 函数。
ifSome(Option<T>, (T) -> Unit)如果输入是 Option.Some 类型数据,则执行 action 函数。
max<T>(T, T, Array<T>) where T <: Comparable<T>获取一组数据中的最大值
min<T>(T, T, Array<T>) where T <: Comparable<T>获取一组数据中的最小值
print(Bool, Bool)向控制台输出 Bool 类型数据的字符串表达。
print(Float16, Bool)向控制台输出 Float16 类型数据的字符串表达。
print(Float32, Bool)向控制台输出 Float32 类型数据的字符串表达。
print(Float64, Bool)向控制台输出 Float64 类型数据的字符串表达。
print(Int16, Bool)向控制台输出 Int16 类型数据的字符串表达。
print(Int32, Bool)向控制台输出 Int32 类型数据的字符串表达。
print(Int64, Bool)向控制台输出 Int64 类型数据的字符串表达。
print(Int8, Bool)向控制台输出 Int8 类型数据的字符串表达。
print(Rune, Bool)向控制台输出 Rune 类型数据的字符串表达。
print(String, Bool)向控制台输出指定字符串。
print(UInt16, Bool)向控制台输出 UInt16 类型数据的字符串表达。
print(UInt32, Bool)向控制台输出 UInt32 类型数据的字符串表达。
print(UInt64, Bool)向控制台输出 UInt64 类型数据的字符串表达。
print(UInt8, Bool)向控制台输出 UInt8 类型数据的字符串表达。
print<T>(T, Bool) where T <: ToString向控制台输出 T 类型实例的字符串表示。
println()向标准输出(stdout)输出换行符。
println(Bool)向控制台输出 Bool 类型数据的字符串表达,末尾添加换行。
println(Float16)向控制台输出 Float16 类型数据的字符串表达,末尾添加换行。
println(Float32)向控制台输出 Float32 类型数据的字符串表达,末尾添加换行。
println(Float64)向控制台输出 Float64 类型数据的字符串表达,末尾添加换行。
println(Int16)向控制台输出 Int16 类型数据的字符串表达,末尾添加换行。
println(Int32)向控制台输出 Int32 类型数据的字符串表达,末尾添加换行。
println(Int64)向控制台输出 Int64 类型数据的字符串表达,末尾添加换行。
println(Int8)向控制台输出 Int8 类型数据的字符串表达,末尾添加换行。
println(Rune)向控制台输出 Rune 类型数据的字符串表达,末尾添加换行。
println(String)向控制台输出指定字符串,末尾添加换行。
println(UInt16)向控制台输出 UInt16 类型数据的字符串表达,末尾添加换行。
println(UInt32)向控制台输出 UInt32 类型数据的字符串表达,末尾添加换行。
println(UInt64)向控制台输出 UInt64 类型数据的字符串表达,末尾添加换行。
println(UInt8)向控制台输出 UInt8 类型数据的字符串表达,末尾添加换行。
println<T>(T) where T <: ToString向控制台输出 T 类型实例的字符串表示,末尾添加换行。
refEq(Object, Object)判断两个 Object 实例的内存地址是否相同。
releaseArrayRawData(CPointerHandle<T>) where T <: CType释放原始指针实例,该实例通过 acquireArrayRawData 获取。
sizeOf<T>() where T <: CType获取类型 T 所占用的内存空间大小。
sleep(Duration)休眠当前线程。
zeroValue<T>()获取一个已全零初始化的 T 类型实例。

类型别名

类型别名功能
ByteByte 类型是内置类型 UInt8 的别名。
IntInt 类型是内置类型 Int64 的别名。
UIntUInt 类型是内置类型 UInt64 的别名。

内置类型

内置类型名功能
Int8表示 8 位有符号整型,表示范围为 [-2^7, 2^7 - 1]。
Int16表示 16 位有符号整型,表示范围为 [-2^{15}, 2^{15} - 1]。
Int32表示 32 位有符号整型,表示范围为 [-2^{31}, 2^{31} - 1]。
Int64表示 64 位有符号整型,表示范围为 [-2^{63}, 2^{63} - 1]。
IntNative表示平台相关的有符号整型,其长度与当前系统的位宽一致。
UInt8表示 8 位无符号整型,表示范围为 [0 ~ 2^8 - 1]。
UInt16表示 16 位无符号整型,表示范围为 [0 ~ 2^{16} - 1]。
UInt32表示 32 位无符号整型,表示范围为 [0 ~ 2^{32} - 1]。
UInt64表示 64 位无符号整型,表示范围为 [0 ~ 2^{64} - 1]。
UIntNative表示平台相关的无符号整型,其长度与当前系统的位宽一致。
Float16表示 16 位浮点数,符合 IEEE 754 中的半精度格式(binary16)。
Float32表示 32 位浮点数,符合 IEEE 754 中的单精度格式(binary32)。
Float64表示 64 位浮点数,符合 IEEE 754 中的双精度格式(binary64)。
Bool表示布尔类型,有 truefalse 两种取值。
Rune表示 unicode 字符集中的字符。
Unit表示仓颉语言中只关心副作用而不关心值的表达式的类型。
CPointer<T>表示 T 类型实例的指针,在与 C 语言互操作的场景下使用,对应 C 语言的 T*
CString表示 C 风格字符串,在与 C 语言互操作的场景下使用。

接口

接口名功能
AnyAny 是所有类型的父类型,所有 interface 都默认继承它,所有非 interface 类型都默认实现它。
RuneExtension该接口用于为 Rune 类型实现扩展方法,接口本身为不包含任何属性、方法。
Hasher该接口用于处理哈希组合运算。
ThreadContext仓颉线程上下文接口。
ByteExtension该接口用于为 Byte 类型实现扩展方法,接口本身为不包含任何属性、方法。
Countable<T>该接口表示类型可数。
Collection<T>该接口用来表示集合,通常容器类型应该实现该接口。
FloatToBits该接口用于扩展 Float 类型与以位表示的整形数值转换。
Less<T>该接口表示小于计算。
Greater<T>该接口表示大于计算。
LessOrEqual<T>该接口表示小于等于计算。
GreaterOrEqual<T>该接口表示大于等于计算。
Comparable<T>该接口表示比较运算,是等于、小于、大于、小于等于、大于等于接口的集合体。
Equal<T>该接口用于支持判等操作。
NotEqual<T>该接口用于支持判不等操作。
Equatable<T>该接口是判等和判不等两个接口的集合体。
Hashable该接口用于计算哈希值。
Iterable<E>该接口表示可迭代,实现了该接口的类型(通常为容器类型)可以在 for-in 语句中实现迭代,也可以获取其对应的迭代器类型实例,调用 next 函数实现迭代。
Resource该接口用于资源管理,通常用于内存、句柄等资源的关闭和释放。
ToString该接口用来提供具体类型的字符串表示。
CType表示支持与 C 语言互操作的接口。
DurationExtension用于拓展 Duration 实例作为右操作数时,返回乘积为新 Duration 实例的乘法运算。

类名功能
ArrayIterator<T>数组迭代器,迭代功能详述见 IterableIterator 接口说明。
Box<T>Box 类型提供了为其他类型添加一层 class 封装的能力。
Future<T>Future<T> 实例代表一个仓颉线程任务,可用于获取仓颉线程的计算结果,向仓颉线程发送取消信号。
Iterator<T>该类表示迭代器,提供 next 方法支持对容器内的成员进行迭代遍历。
Object构造一个 object 实例。
RangeIterator<T> <: Iterator<T> where T <: Countable<T> & Comparable<T> & Equatable<T>Range 类型的迭代器,迭代功能详述见 IterableIterator 接口说明。
StackTraceElement表示一个异常堆栈的具体信息,包括异常发生的类名、函数名、文件名、行号。
StringBuilder该类主要用于字符串的构建。
ThreadThread 类代表一个仓颉类,可用于获取线程 ID 及名字、查询线程是否存在取消请求、注册线程未处理异常的处理函数等。
ThreadLocal<T>该类表示仓颉线程局部变量。

枚举

枚举名功能
AnnotationKind表示自定义注解希望支持的位置。
Endian枚举类型 Endian 表示运行平台的端序,分为大端序和小端序。
OrderingOrdering 表示比较大小的结果,它包含三种情况:小于,大于和等于。
Option<T>Option<T> 是对 T 类型的封装,表示可能有值也可能无值。

结构体

结构体名功能
Array<T>仓颉数组类型,用来表示单一类型的元素构成的有序序列。
CPointerHandle<T> where T <: CType表示 Array 数组的原始指针,该类型中的泛型参数应该满足 CType 约束。
CPointerResource<T> where T <: CType该结构体表示 CPointer 对应的资源管理类型,其实例可以通过 CPointer 的成员函数 asResource 获取。
CStringResource该结构体表示 CString 对应的资源管理类型,其实例可以通过 CString 的成员函数 asResource 获取。
DefaultHasher该结构体提供了默认哈希算法实现。
LibC提供了仓颉中较为高频使用的 C 接口,如申请、释放堆上 CType 实例。
Range<T> where T <: Countable<T> & Comparable<T> & Equatable<T>该类是区间类型,用于表示一个拥有固定范围和步长的 T 的序列,要求 T 是可数的,有序的。
String该结构体表示仓颉字符串,提供了构造、查找、拼接等一系列字符串操作。
Duration表示时间间隔,是一个描述一段时间的时间类型,提供了常用的静态实例,以及计算、比较等功能。

异常类

异常类名功能
ErrorError 是所有错误类的父类。该类不可被继承,不可初始化,但是可以被捕获到。
InternalError表示内部错误的错误类,该类不可初始化,但是可以被捕获到。
OutOfMemoryError表示内存不足错误的错误类,该类不可被继承,不可初始化,但是可以被捕获到。
StackOverflowError表示堆栈溢出错误的错误类,该类不可被继承,不可初始化,但是可以被捕获到。
ExceptionException 是所有异常类的父类。
SpawnException线程异常类,表示线程处理过程中发生异常。
TimeoutException当阻塞操作超时时引发异常。
IllegalArgumentException表示参数非法的异常类。
IllegalFormatException表示变量的格式无效或不标准时的异常类。
IllegalStateException表示状态非法的异常类。
IndexOutOfBoundsException表示索引越界的异常类。
NegativeArraySizeException表示数组大小为负数的异常类。
NoneValueException表示 Option<T> 实例的值为 None 的异常类,通常在 getOrThrow 函数中被抛出。
UnsupportedException表示功能未支持的异常类。
OverflowException表示算术运算溢出的异常类。
IllegalMemoryException表示内存操作错误的异常类。
ArithmeticException算术异常类,发生算术异常时使用。

函数

func acquireArrayRawData<T>(Array<T>) where T <: CType

public unsafe func acquireArrayRawData<T>(arr: Array<T>): CPointerHandle<T> where T <: CType

功能:获取 Array<T> 中数据的原始指针实例,T 需要满足 CType 约束。

注意:

指针使用完后需要及时用 releaseArrayRawData 函数释放该指针。 指针的获取和释放之间仅可包含简单的 foreign C 函数调用等逻辑,不构造例如 CString 等的仓颉对象,否则可能造成不可预期现象。

参数:

  • arr: Array<T> - 待获取原始指针的数组。

返回值:

func alignOf<T>() where T <: CType

public func alignOf<T>(): UIntNative where T <: CType

功能:获取类型 T 的内存对齐值。

返回值:

  • UIntNative - 对类型 T 做内存对齐的字节数。

func eprint(String, Bool)

public func eprint(str: String, flush!: Bool = true): Unit

功能:将指定字符串打印到标准错误文本流。

如抛出异常时,消息将打印到标准错误文本流(stderr),而不是标准输出(stdout)。

参数:

  • str: String - 待输出的字符串。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func eprintln(String)

public func eprintln(str: String): Unit

功能:将指定字符串打印到标准错误文本流,末尾添加换行。

如抛出异常时,消息将打印到标准错误文本流(stderr),而不是标准输出(stdout)。

参数:

  • str: String - 待输出的字符串。

func eprint<T>(T, Bool) where T <: ToString

public func eprint<T>(arg: T, flush!: Bool = false): Unit where T <: ToString

功能:将指定 T 类型实例的字符串表示打印到标准错误文本流。

如抛出异常时,消息将打印到标准错误文本流(stderr),而不是标准输出(stdout)。

参数:

  • arg: T - 待打印的 T 类型实例,该函数将打印其 toString 的返回值。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func eprintln<T>(T) where T <: ToString

public func eprintln<T>(arg: T): Unit where T <: ToString

功能:将指定 T 类型实例的字符串表示打印到标准错误文本流,末尾添加换行。

如抛出异常时,消息将打印到标准错误文本流(stderr),而不是标准输出(stdout)。

参数:

  • arg: T - 待打印的 T 类型实例,该函数将打印其 toString 的返回值。

func ifNone<T>(Option<T>, () -> Unit)

public func ifNone<T>(o: Option<T>, action: () -> Unit): Unit

功能:如果输入是 Option.None 类型数据,则执行 action 函数。

参数:

  • o: Option<T> - 待判断是否为 Option.None 的 Option<T> 类型实例。
  • action: () ->Unit - 待执行函数。

func ifSome<T>(Option<T>, (T) -> Unit)

public func ifSome<T>(o: Option<T>, action: (T) -> Unit): Unit

功能:如果输入是 Option.Some 类型数据,则执行 action 函数。

参数:

  • o: Option<T> - 待判断是否为 Option.Some 的 Option<T> 类型实例,同时其封装的 T 类型实例将作为 action 函数的输入。
  • action: (T) ->Unit - 待执行函数。

func max<T>(T, T, Array<T>) where T <: Comparable<T>

public func max<T>(a: T, b: T, others: Array<T>): T where T <: Comparable<T>

功能:根据 T 类型的 Comparable 接口实现,返回一组数据中的最大值,由于此函数的第三个参数是一个变长参数,支持获取二个以上的数据的比较。

注意:

浮点数类型的比较也将按照Comparable的结果进行比较,如果浮点书中有非数NaN,结果将不正确,此时建议使用 Float16Float32Float64static func max方法。

参数:

  • a: T - 第一个待比较的数。
  • b: T - 第一个待比较的数。
  • others: Array<T> - 其它待比较的数。

返回值:

  • T - 返回参数中的最大值。

func min<T>(T, T, Array<T>) where T <: Comparable<T>

public func min<T>(a: T, b: T, others: Array<T>): T where T <: Comparable<T>

功能:根据 T 类型的 Comparable 接口实现,返回一组数据中的最小值,由于此函数的第三个参数是一个变长参数,支持获取二个以上的数据的比较。

注意:

浮点数类型的比较也将按照Comparable的结果进行比较,如果浮点书中有非数NaN,结果将不正确,此时建议使用 Float16Float32Float64static func min方法。

参数:

  • a: T - 第一个待比较的数。
  • b: T - 第一个待比较的数。
  • others: Array<T> - 其它待比较的数。

返回值:

  • T - 返回参数中的最小值。

func print(Bool, Bool)

public func print(b: Bool, flush!: Bool = false): Unit

功能:向控制台输出 Bool 类型数据的字符串表达。

注意:

下列 printprintlneprinteprintln 函数默认为 UTF-8 编码。 Windows 环境需在 cmd 控制台手动执行命令 chcp 65001,将 cmd 控制台编码改为 UTF-8。

参数:

  • b: Bool - 待输出的 Bool 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(Float16, Bool)

public func print(f: Float16, flush!: Bool = false): Unit

功能:向控制台输出 Float16 类型数据的字符串表达。

参数:

  • f: Float16 - 待输出的 Float16 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(Float32, Bool)

public func print(f: Float32, flush!: Bool = false): Unit

功能:向控制台输出 Float32 类型数据的字符串表达。

参数:

  • f: Float32 - 待输出的 Float32 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(Float64, Bool)

public func print(f: Float64, flush!: Bool = false): Unit

功能:向控制台输出 Float64 类型数据的字符串表达。

参数:

  • f: Float64 - 待输出的 Float64 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(Int16, Bool)

public func print(i: Int16, flush!: Bool = false): Unit

功能:向控制台输出 Int16 类型数据的字符串表达。

参数:

  • i: Int16 - 待输出的 Int16 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(Int32, Bool)

public func print(i: Int32, flush!: Bool = false): Unit

功能:向控制台输出 Int32 类型数据的字符串表达。

参数:

  • i: Int32 - 待输出的 Int32 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(Int64, Bool)

public func print(i: Int64, flush!: Bool = false): Unit

功能:向控制台输出 Int64 类型数据的字符串表达。

参数:

  • i: Int64 - 待输出的 Int64 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(Int8, Bool)

public func print(i: Int8, flush!: Bool = false): Unit

功能:向控制台输出 Int8 类型数据的字符串表达。

参数:

  • i: Int8 - 待输出的 Int8 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(Rune, Bool)

public func print(c: Rune, flush!: Bool = false): Unit

功能:向控制台输出 Rune 类型数据的字符串表达。

参数:

  • c: Rune - 待输出的 Rune 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(String, Bool)

public func print(str: String, flush!: Bool = false): Unit

功能:向控制台输出指定字符串。

参数:

  • str: String - 待输出的字符串。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(UInt16, Bool)

public func print(i: UInt16, flush!: Bool = false): Unit

功能:向控制台输出 UInt16 类型数据的字符串表达。

参数:

  • i: UInt16 - 待输出的 UInt16 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(UInt32, Bool)

public func print(i: UInt32, flush!: Bool = false): Unit

功能:向控制台输出 UInt32 类型数据的字符串表达。

参数:

  • i: UInt32 - 待输出的 UInt32 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(UInt64, Bool)

public func print(i: UInt64, flush!: Bool = false): Unit

功能:向控制台输出 UInt64 类型数据的字符串表达。

参数:

  • i: UInt64 - 待输出的 UInt64 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print(UInt8, Bool)

public func print(i: UInt8, flush!: Bool = false): Unit

功能:向控制台输出 UInt8 类型数据的字符串表达。

参数:

  • i: UInt8 - 待输出的 UInt8 类型数据。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func print<T>(T, Bool) where T <: ToString

public func print<T>(arg: T, flush!: Bool = false): Unit where T <: ToString

功能:向控制台输出 T 类型实例的字符串表示。

参数:

  • arg: T - 待输出的数据,支持实现了 ToString 接口的类型。
  • flush!: Bool - 是否清空缓存,true 清空,false 不清空,默认 false。

func println()

public func println(): Unit

功能:向标准输出(stdout)输出换行符。

func println(Bool)

public func println(b: Bool): Unit

功能:向控制台输出 Bool 类型数据的字符串表达,末尾添加换行。

参数:

  • b: Bool - 待输出的 Bool 类型数据。

func println(Float16)

public func println(f: Float16): Unit

功能:向控制台输出 Float16 类型数据的字符串表达,末尾添加换行。

参数:

func println(Float32)

public func println(f: Float32): Unit

功能:向控制台输出 Float32 类型数据的字符串表达,末尾添加换行。

参数:

func println(Float64)

public func println(f: Float64): Unit

功能:向控制台输出 Float64 类型数据的字符串表达,末尾添加换行。

参数:

func println(Int16)

public func println(i: Int16): Unit

功能:向控制台输出 Int16 类型数据的字符串表达,末尾添加换行。

参数:

func println(Int32)

public func println(i: Int32): Unit

功能:向控制台输出 Int32 类型数据的字符串表达,末尾添加换行。

参数:

func println(Int64)

public func println(i: Int64): Unit

功能:向控制台输出 Int64 类型数据的字符串表达,末尾添加换行。

参数:

func println(Int8)

public func println(i: Int8): Unit

功能:向控制台输出 Int8 类型数据的字符串表达,末尾添加换行。

参数:

  • i: Int8 - 待输出的 Int8 类型数据。

func println(Rune)

public func println(c: Rune): Unit

功能:向控制台输出 Rune 类型数据的字符串表达,末尾添加换行。

参数:

  • c: Rune - 待输出的 Rune 类型数据。

func println(String)

public func println(str: String): Unit

功能:向控制台输出指定字符串,末尾添加换行。

参数:

  • str: String - 待输出的字符串。

func println(UInt16)

public func println(i: UInt16): Unit

功能:向控制台输出 UInt16 类型数据的字符串表达,末尾添加换行。

参数:

func println(UInt32)

public func println(i: UInt32): Unit

功能:向控制台输出 UInt32 类型数据的字符串表达,末尾添加换行。

参数:

func println(UInt64)

public func println(i: UInt64): Unit

功能:向控制台输出 UInt64 类型数据的字符串表达,末尾添加换行。

参数:

func println(UInt8)

public func println(i: UInt8): Unit

功能:向控制台输出 UInt8 类型数据的字符串表达,末尾添加换行。

参数:

func println<T>(T) where T <: ToString

public func println<T>(arg: T): Unit where T <: ToString

功能:向控制台输出 T 类型实例的字符串表示,末尾添加换行。

参数:

  • arg: T - 待输出的数据,支持实现了 ToString 接口的类型。

func refEq(Object, Object)

public func refEq(a: Object, b: Object): Bool

功能:判断两个 Object 实例的内存地址是否相同。

参数:

返回值:

  • Bool - 如果两个 Object 实例的内存地址相同,返回 true,否则返回 false。

func releaseArrayRawData<T>(CPointerHandle<T>) where T <: CType

public unsafe func releaseArrayRawData<T>(handle: CPointerHandle<T>): Unit where T <: CType

功能:释放原始指针实例,该实例通过 acquireArrayRawData 获取。

参数:

func sizeOf<T>() where T <: CType

public func sizeOf<T>(): UIntNative where T <: CType

功能:获取类型 T 所占用的内存空间大小。

返回值:

  • UIntNative - 类型 T 所占用内存空间的字节数。

func sleep(Duration)

public func sleep(dur: Duration): Unit

功能:休眠当前线程。

dur 小于等于 Duration.Zero,当前线程会让出运行权。

参数:

  • dur: Duration - 线程休眠的时长。

func zeroValue<T>()

public unsafe func zeroValue<T>(): T

功能:获取一个已全零初始化的 T 类型实例。

注意:

这个实例一定要赋值为正常初始化的值再使用,否则将引发程序崩溃。

返回值:

  • T - 一个已全零初始化的 T 类型实例。

类型别名

type Byte

public type Byte = UInt8

功能:Byte 类型是内置类型 UInt8 的别名。

type Int

public type Int = Int64

功能:Int 类型是内置类型 Int64 的别名。

type UInt

public type UInt = UInt64

功能:UInt 类型是内置类型 UInt64 的别名。

内置类型

Bool

功能:表示布尔类型,有 truefalse 两种取值。

extend Bool <: Equatable<Bool>

extend Bool <: Equatable<Bool>

功能:为 Bool 类型扩展 Equatable<Bool> 接口,支持判等操作。

父类型:

extend Bool <: Hashable

extend Bool <: Hashable

功能:为 Bool 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend Bool <: ToString

extend Bool <: ToString

功能:为 Bool 类型其扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 Bool 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

CPointer<T>

功能:表示 T 类型实例的指针,在与 C 语言互操作的场景下使用,对应 C 语言的 T*

其中 T 必须满足 CType 约束。

CPointer 类型必须满足:

  • 大小和对齐与平台相关。
  • 对它做加减法算术运算、读写内存,是需要在 unsafe 上下文操作的。
  • CPointer<T1> 可以在 unsafe 上下文中使用类型强制转换,变成 CPointer<T2> 类型。

extend<T> CPointer<T>

extend<T> CPointer<T>

功能:为 CPointer<T> 扩展一些必要的指针使用相关接口,包含判空、读写数据等接口。

其中泛型 T 为指针类型,其满足 CType 约束。对 CPointer 做运算需要在 unsafe 上下文中进行。

func asResource()

public func asResource(): CPointerResource<T>

功能:获取该指针 CPointerResource 实例,后者可以在 try-with-resource 语法上下文中实现内容自动释放。

返回值:

func isNotNull()

public func isNotNull(): Bool

功能:判断指针是否不为空。

返回值:

  • Bool - 如果不为空返回 true,否则返回 false。

func isNull()

public func isNull(): Bool

功能:判断指针是否为空。

返回值:

  • Bool - 如果为空返回 true,否则返回 false。

func read()

public unsafe func read(): T

功能:读取第一个数据,该接口需要用户保证指针的合法性,否则发生未定义行为。

返回值:

  • T - 该对象类型的第一个数据。

func read(Int64)

public unsafe func read(idx: Int64): T

功能:根据下标读取对应的数据,该接口需要用户保证指针的合法性,否则发生未定义行为。

参数:

  • idx: Int64 - 要获取数据的下标。

返回值:

  • T - 输入下标对应的数据。

func toUIntNative()

public func toUIntNative(): UIntNative

功能:获取该指针的整型形式。

返回值:

func write(Int64, T)

public unsafe func write(idx: Int64, value: T): Unit

功能:在指定下标位置写入一个数据,该接口需要用户保证指针的合法性,否则发生未定义行为。

参数:

  • idx: Int64 - 指定的下标位置。
  • value: T - 写入的数据。

func write(T)

public unsafe func write(value: T): Unit

功能:写入一个数据,该数据总是在第一个,该接口需要用户保证指针的合法性,否则发生未定义行为。

参数:

  • value: T - 要写入的数据。

operator func +(Int64)

public unsafe operator func +(offset: Int64): CPointer<T>

功能:CPointer 对象指针后移,同 C 语言的指针加法操作。

参数:

  • offset: Int64 - 偏移量。

返回值:

  • CPointer<T> - 返回偏移后的指针。

operator func -(Int64)

public unsafe operator func -(offset: Int64): CPointer<T>

功能:CPointer 对象指针前移,同 C 语言的指针减法操作。

参数:

  • offset: Int64 - 偏移量。

返回值:

  • CPointer<T> - 返回偏移后的指针。

CString

功能:表示 C 风格字符串,在与 C 语言互操作的场景下使用。

可以通过 CString 的构造函数或 LibCmallocCString 创建 C 风格字符串,如需在仓颉端释放,则调用 LibC 的 free 方法。

extend CString <: ToString

extend CString <: ToString

功能:为 CString 类型扩展一些字符串指针常用方法,包括判空、获取长度、判等、获取子串等。

父类型:

func asResource()

public func asResource(): CStringResource

功能:获取当前 CString 实例对应的 CStringResource C 字符串资源类型实例。

CStringResource 实现了 Resource 接口,可以在 try-with-resource 语法上下文中实现资源自动释放。

返回值:

func compare(CString)

public func compare(str: CString): Int32

功能:按字典序比较两个字符串,同 C 语言中的 strcmp

参数:

  • str: CString - 比较的目标字符串。

返回值:

  • Int32 - 两者相等返回 0,如果当前字符串比参数 str 小,返回 -1,否则返回 1。

异常:

  • Exception - 如果被比较的两个 CString 中存在空指针,抛出异常。

func endsWith(CString)

public func endsWith(suffix: CString): Bool

功能:判断字符串是否包含指定后缀。

参数:

  • suffix: CString - 匹配的目标后缀字符串。

返回值:

  • Bool - 如果该字符串包含 suffix 后缀,返回 true,如果该字符串不包含 suffix 后缀,返回 false,特别地,如果原字符串或者 suffix 后缀字符串指针为空,均返回 false。

func equals(CString)

public func equals(rhs: CString): Bool

功能:判断两个字符串是否相等。

参数:

  • rhs: CString - 比较的目标字符串。

返回值:

  • Bool - 如果两个字符串相等,返回 true,否则返回 false。

func equalsLower(CString)

public func equalsLower(rhs: CString): Bool

功能:判断两个字符串是否相等,忽略大小写。

参数:

  • rhs: CString - 匹配的目标字符串。

返回值:

  • Bool - 如果两个字符串忽略大小写相等,返回 true,否则返回 false。

func getChars()

public func getChars(): CPointer<UInt8>

功能:获取该字符串的指针。

返回值:

func isEmpty()

public func isEmpty(): Bool

功能:判断字符串是否为空字符串。

返回值:

  • Bool - 如果为空字符串或字符串指针为空,返回 true,否则返回 false。

func isNotEmpty()

public func isNotEmpty(): Bool

功能:判断字符串是否不为空字符串。

返回值:

  • Bool - 如果不为空字符串,返回 true,如果字符串指针为空,返回 false。

func isNull()

public func isNull(): Bool

功能:判断字符串指针是否为空。

返回值:

  • Bool - 如果字符串指针为空,返回 true,否则返回 false。

func size()

public func size(): Int64

功能:返回该字符串长度,同 C 语言中的 strlen

返回值:

  • Int64 - 字符串长度。

func startsWith(CString)

public func startsWith(prefix: CString): Bool

功能:判断字符串是否包含指定前缀。

参数:

  • prefix: CString - 匹配的目标前缀字符串。

返回值:

  • Bool - 如果该字符串包含 prefix 前缀,返回 true,如果该字符串不包含 prefix 前缀,返回 false,特别地,如果原字符串或者 prefix 前缀字符串指针为空,均返回 false。

func subCString(UIntNative)

public func subCString(beginIndex: UIntNative): CString

功能:截取指定位置开始至字符串结束的子串。

注意:

  1. 该接口返回为字符串的副本,返回的子串使用完后需要手动 free。
  2. 如果 beginIndex 与字符串长度相等,将返回空指针。

参数:

  • beginIndex: UIntNative - 截取的起始位置,取值范围为 [0, this.size()]。

返回值:

异常:

func subCString(UIntNative, UIntNative)

public func subCString(beginIndex: UIntNative, subLen: UIntNative): CString

功能:截取字符串的子串,指定起始位置和截取长度。

如果截取的末尾位置超出字符串长度,截取至字符串末尾。

注意:

  1. 该接口返回为字符串的副本,返回的子串使用完后需要手动 free。
  2. 如果 beginIndex 等于于字符串长度,或 subLen 等于 0,返回空指针。

参数:

  • beginIndex: UIntNative - 截取的起始位置,取值范围为 [0, this.size()]。
  • subLen: UIntNative - 截取长度,取值范围为 [0, UIntNative.Max]。

返回值:

异常:

func toString()

public func toString(): String

功能:将 CString 类型转为仓颉的 String 类型。

返回值:

  • String - 转换后的字符串。

Float16

功能:表示 16 位浮点数,符合 IEEE 754 中的半精度格式(binary16)。

extend Float16

extend Float16

功能:拓展半精度浮点数以支持一些数学常数。

static prop Inf

public static prop Inf: Float16

功能:获取半精度浮点数的无穷数。

类型:Float16

static prop Max

public static prop Max: Float16

功能:获取半精度浮点数的最大值。

类型:Float16

static prop Min

public static prop Min: Float16

功能:获取半精度浮点数的最小值。

类型:Float16

static prop MinDenormal

public static prop MinDenormal: Float16

功能:获取半精度浮点数的最小次正规数。最小正次正规数是以 IEEE 双精度格式表示的最小正数。

类型:Float16

static prop MinNormal

public static prop MinNormal: Float16

功能:获取半精度浮点数的最小正规数。

类型:Float16

static prop NaN

public static prop NaN: Float16

功能:获取半精度浮点数的非数。

类型:Float16

static func max(Float16, Float16, Array<Float16>)

public static func max(a: Float16, b: Float16, others: Array<Float16>): Float16

功能:返回一组Float16中的最大值,此函数的第三个参数是一个变长参数,可以获取二个以上的Float16最大值,如果参数中有 NaN,该函数会返回 NaN

参数:

  • a: Float16 - 第一个待比较的数。
  • b: Float16 - 第一个待比较的数。
  • others: Array<Float16> - 其它待比较的数。

返回值:

  • Float16 - 返回参数中的最大值。

static func min(Float16, Float16, Array<Float16>)

public static func min(a: Float16, b: Float16, others: Array<Float16>): Float16

功能:返回一组Float16中的最小值,此函数的第三个参数是一个变长参数,可以获取二个以上的Float16最小值,如果参数中有 NaN,该函数会返回 NaN

参数:

  • a: Float16 - 第一个待比较的数。
  • b: Float16 - 第一个待比较的数。
  • others: Array<Float16> - 其它待比较的数。

返回值:

  • Float16 - 返回参数中的最小值。

func isInf()

public func isInf(): Bool

功能:判断某个浮点数 Float16 是否为无穷数值。

返回值:

  • Bool - 如果 Float16 的值正无穷大或负无穷大,则返回 true;否则,返回 false

func isNaN()

public func isNaN(): Bool

功能:判断某个浮点数 Float16 是否为非数值。

返回值:

  • Bool - 如果 Float16 的值为非数值,则返回 true;否则,返回 false

func isNormal()

public func isNormal(): Bool

功能:判断某个浮点数 Float16 是否为常规数值。

返回值:

  • Bool - 如果 Float16 的值是正常的浮点数,返回 true;否则,返回 false

extend Float16 <: Comparable<Float16>

extend Float16 <: Comparable<Float16>

功能:为 Float16 类型扩展 Comparable<Float16> 接口,支持比较操作。

父类型:

func compare(Float16)

public func compare(rhs: Float16): Ordering

功能:判断当前 Float16 值与指定 Float16 值的大小关系。

参数:

返回值:

extend Float16 <: FloatToBits

extend Float16 <: FloatToBits

功能:为 Float16 实现 FloatToBits 接口,支持与 UInt16 互相转换。

父类型:

static func fromBits(UInt16)

public static func fromBits(bits: UInt16): Float16

功能:将指定的 UInt16 数转换为 Float16 数。

参数:

  • bits: UInt16 - 要转换的数字。

返回值:

  • Float16 - 转换结果,其位与参数 bits 值相同。

示例:

import std.unittest.*
import std.unittest.testmacro.*

main() {
    let v = Float16.fromBits(0x4A40)
    @Assert(v, 12.5)
}

func toBits()

public func toBits(): UInt16

功能:将指定的 Float16 数转换为以位表示的对应 UInt16 数。

返回值:

  • UInt16 - 转换结果,其值与 Float16 的位表示相同。

示例:

import std.unittest.*
import std.unittest.testmacro.*

main() {
    @Assert(12.5f16.toBits(), 0x4A40)
}

extend Float16 <: Hashable

extend Float16 <: Hashable

功能:为 Float16 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend Float16 <: ToString

extend Float16 <: ToString

功能:为 Float16 类型其扩展 ToString 接口,实现向 String 类型的转换。

默认保留 6 位小数,如需其他精度 String 请参考 Formatter 扩展。

父类型:

func toString()

public func toString(): String

功能:将 Float16 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

Float32

功能:表示 32 位浮点数,符合 IEEE 754 中的单精度格式(binary32)。

extend Float32

extend Float32

功能:拓展单精度浮点数以支持一些数学常数。

static prop Inf

public static prop Inf: Float32

功能:获取单精度浮点数的无穷数。

类型:Float32

static prop Max

public static prop Max: Float32

功能:获取单精度浮点数的最大值。

类型:Float32

static prop Min

public static prop Min: Float32

功能:获取单精度浮点数的最小值。

类型:Float32

static prop MinDenormal

public static prop MinDenormal: Float32

功能:获取单精度浮点数的最小次正规数。

类型:Float32

static prop MinNormal

public static prop MinNormal: Float32

功能:获取单精度浮点数的最小正规数。

类型:Float32

static prop NaN

public static prop NaN: Float32

功能:获取单精度浮点数的非数。

类型:Float32

static func max(Float32, Float32, Array<Float32>)

public static func max(a: Float32, b: Float32, others: Array<Float32>): Float32

功能:返回一组Float32中的最大值,此函数的第三个参数是一个变长参数,可以获取二个以上的Float32最大值,如果参数中有 NaN,该函数会返回 NaN

参数:

  • a: Float32 - 第一个待比较的数。
  • b: Float32 - 第一个待比较的数。
  • others: Array<Float32> - 其它待比较的数。

返回值:

  • Float32 - 返回参数中的最大值。

static func min(Float32, Float32, Array<Float32>)

public static func min(a: Float32, b: Float32, others: Array<Float32>): Float32

功能:返回一组Float32中的最小值,此函数的第三个参数是一个变长参数,可以获取二个以上的Float32最小值,如果参数中有 NaN,该函数会返回 NaN

参数:

  • a: Float32 - 第一个待比较的数。
  • b: Float32 - 第一个待比较的数。
  • others: Array<Float32> - 其它待比较的数。

返回值:

  • Float32 - 返回参数中的最小值。

func isInf()

public func isInf(): Bool

功能:判断某个浮点数 Float32 是否为无穷数值。

返回值:

  • Bool - 如果 Float32 的值正无穷大或负无穷大,则返回 true;否则,返回 false

func isNaN()

public func isNaN(): Bool

功能:判断某个浮点数 Float32 是否为非数值。

返回值:

  • Bool - 如果 Float32 的值为非数值,则返回 true;否则,返回 false

func isNormal()

public func isNormal(): Bool

功能:判断某个浮点数 Float32 是否为常规数值。

返回值:

  • Bool - 如果 Float32 的值是正常的浮点数,返回 true;否则,返回 false

extend Float32 <: Comparable<Float32>

extend Float32 <: Comparable<Float32>

功能:为 Float32 类型扩展 Comparable<Float32> 接口,支持比较操作。

父类型:

func compare(Float32)

public func compare(rhs: Float32): Ordering

功能:判断当前 Float32 值与指定 Float32 值的大小关系。

参数:

返回值:

extend Float32 <: FloatToBits

extend Float32 <: FloatToBits

功能:为 Float32 实现 FloatToBits 接口,支持与 UInt32 互相转换。

父类型:

static func fromBits(UInt32)

public static func fromBits(bits: UInt32): Float32

功能:将指定的 UInt32 数转换为 Float32 数。

参数:

  • bits: UInt32 - 要转换的数字。

返回值:

  • Float32 - 转换结果,其位与参数 bits 值相同。

示例:

import std.unittest.*
import std.unittest.testmacro.*

main() {
    let v = Float32.fromBits(0x41480000)
    @Assert(v, 12.5)
}

func toBits()

public func toBits(): UInt32

功能:将指定的 Float32 数转换为以位表示的对应 UInt32 数。

返回值:

  • UInt32 - 转换结果,其值与 Float32 的位表示相同。

示例:

import std.unittest.*
import std.unittest.testmacro.*

main() {
    @Assert(12.5f32.toBits(), 0x41480000)
}

extend Float32 <: Hashable

extend Float32 <: Hashable

功能:为 Float32 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend Float32 <: ToString

extend Float32 <: ToString

功能:为 Float32 类型其扩展 ToString 接口,实现向 String 类型的转换。

默认保留 6 位小数,如需其他精度 String 请参考 Formatter 扩展。

父类型:

func toString()

public func toString(): String

功能:将 Float32 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

Float64

功能:表示 64 位浮点数,符合 IEEE 754 中的双精度格式(binary64)。

extend Float64

extend Float64

功能:拓展双精度浮点数以支持一些数学常数。

static prop Inf

public static prop Inf: Float64

功能:获取双精度浮点数的无穷数。

类型:Float64

static prop Max

public static prop Max: Float64

功能:获取双精度浮点数的最大值。

类型:Float64

static prop Min

public static prop Min: Float64

功能:获取双精度浮点数的最小值。

类型:Float64

static prop MinDenormal

public static prop MinDenormal: Float64

功能:获取双精度浮点数的最小次正规数。

类型:Float64

static prop MinNormal

public static prop MinNormal: Float64

功能:获取双精度浮点数的最小正规数。

类型:Float64

static prop NaN

public static prop NaN: Float64

功能:获取双精度浮点数的非数。

类型:Float64

static func max(Float64, Float64, Array<Float64>)

public static func max(a: Float64, b: Float64, others: Array<Float64>): Float64

功能:返回一组Float64中的最大值,此函数的第三个参数是一个变长参数,可以获取二个以上的Float64最大值,如果参数中有 NaN,该函数会返回 NaN

参数:

  • a: Float64 - 第一个待比较的数。
  • b: Float64 - 第一个待比较的数。
  • others: Array<Float64> - 其它待比较的数。

返回值:

  • Float64 - 返回参数中的最大值。

static func min(Float64, Float64, Array<Float64>)

public static func min(a: Float64, b: Float64, others: Array<Float64>): Float64

功能:返回一组Float64中的最小值,此函数的第三个参数是一个变长参数,可以获取二个以上的Float64最小值,如果参数中有 NaN,该函数会返回 NaN

参数:

  • a: Float64 - 第一个待比较的数。
  • b: Float64 - 第一个待比较的数。
  • others: Array<Float64> - 其它待比较的数。

返回值:

  • Float64 - 返回参数中的最小值。

func isInf()

public func isInf(): Bool

功能:判断某个浮点数 Float64 是否为无穷数值。

返回值:

  • Bool - 如果 Float64 的值正无穷大或负无穷大,则返回 true;否则,返回 false

func isNaN()

public func isNaN(): Bool

功能:判断某个浮点数 Float64 是否为非数值。

返回值:

  • Bool - 如果 Float64 的值为非数值,则返回 true;否则,返回 false

func isNormal()

public func isNormal(): Bool

功能:判断某个浮点数 Float64 是否为常规数值。

返回值:

  • Bool - 如果 Float64 的值是正常的浮点数,返回 true;否则,返回 false

extend Float64 <: Comparable<Float64>

extend Float64 <: Comparable<Float64>

功能:为 Float64 类型扩展 Comparable<Float64> 接口,支持比较操作。

父类型:

func compare(Float64)

public func compare(rhs: Float64): Ordering

功能:判断当前 Float64 值与指定 Float64 值的大小关系。

参数:

返回值:

extend Float64 <: FloatToBits

extend Float64 <: FloatToBits

功能:为 Float64 实现 FloatToBits 接口,支持与 UInt64 互相转换。

父类型:

static func fromBits(UInt64)

public static func fromBits(bits: UInt64): Float64

功能:将指定的 UInt64 数转换为 Float64 数。

参数:

  • bits: UInt64 - 要转换的数字。

返回值:

  • Float64 - 转换结果,其位与参数 bits 值相同。

示例:

import std.unittest.*
import std.unittest.testmacro.*

main() {
    let v = Float64.fromBits(0x4029000000000000)
    @Assert(v, 12.5)
}

func toBits()

public func toBits(): UInt64

功能:将指定的 Float64 数转换为以位表示的对应 UInt64 数。

返回值:

  • UInt64 - 转换结果,其值与 Float64 的位表示相同。

示例:

import std.unittest.*
import std.unittest.testmacro.*

main() {
    @Assert(12.5f64.toBits(), 0x4029000000000000)
}

extend Float64 <: Hashable

extend Float64 <: Hashable

功能:为 Float64 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend Float64 <: ToString

extend Float64 <: ToString

功能:为 Float64 类型其扩展 ToString 接口,实现向 String 类型的转换。

默认保留 6 位小数,如需其他精度 String 请参考 Formatter 扩展。

父类型:

func toString()

public func toString(): String

功能:将 Float64 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

Int16

功能:表示 16 位有符号整型,表示范围为 [-2^{15}, 2^{15} - 1]。

extend Int16

extend Int16

功能:拓展 16 位有符号整数以支持一些数学常数。

static prop Max

public static prop Max: Int16

功能:获取 16 位有符号整数的最大值。

类型:Int16

static prop Min

public static prop Min: Int16

功能:获取 16 位有符号整数的最小值。

类型:Int16

extend Int16 <: Comparable<Int16>

extend Int16 <: Comparable<Int16>

功能:为 Int16 类型扩展 Comparable<Int16> 接口,支持比较操作。

父类型:

func compare(Int16)

public func compare(rhs: Int16): Ordering

功能:判断当前 Int16 值与指定 Int16 值的大小关系。

参数:

返回值:

extend Int16 <: Countable<Int16>

extend Int16 <: Countable<Int16>

功能:为 Int16 类型扩展 Countable<Int16> 接口,支持计数操作。

父类型:

func next(Int64)

public func next(right: Int64): Int16

功能:获取当前 Int16 值往右数 right 后所到位置的 Int16 值。

参数:

  • right: Int64 - 往右数的个数。

返回值:

  • Int16 - 往右数 right 后所到位置的 Int16 值。

func position()

public func position(): Int64

功能:获取当前 Int16 值的位置信息,即将该 Int16 转换为 Int64 值。

返回值:

extend Int16 <: Hashable

extend Int16 <: Hashable

功能:为 Int16 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend Int16 <: ToString

extend Int16 <: ToString

功能:这里为 Int16 类型扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 Int16 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

Int32

功能:表示 32 位有符号整型,表示范围为 [-2^{31}, 2^{31} - 1]。

extend Int32

extend Int32

功能:拓展 32 位有符号整数以支持一些数学常数。

static prop Max

public static prop Max: Int32

功能:获取 32 位有符号整数的最大值。

类型:Int32

static prop Min

public static prop Min: Int32

功能:获取 32 位有符号整数的最小值。

类型:Int32

extend Int32 <: Comparable<Int32>

extend Int32 <: Comparable<Int32>

功能:为 Int32 类型扩展 Comparable<Int32> 接口,支持比较操作。

父类型:

func compare(Int32)

public func compare(rhs: Int32): Ordering

功能:判断当前 Int32 值与指定 Int32 值的大小关系。

参数:

返回值:

extend Int32 <: Countable<Int32>

extend Int32 <: Countable<Int32>

功能:为 Int32 类型扩展 Countable<Int32> 接口,支持计数操作。

父类型:

func next(Int64)

public func next(right: Int64): Int32

功能:获取当前 Int32 值往右数 right 后所到位置的 Int32 值。

参数:

  • right: Int64 - 往右数的个数。

返回值:

  • Int32 - 往右数 right 后所到位置的 Int32 值。

func position()

public func position(): Int64

功能:获取当前 Int32 值的位置信息,即将该 Int32 转换为 Int64 值。

返回值:

extend Int32 <: Hashable

extend Int32 <: Hashable

功能:为 Int32 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend Int32 <: ToString

extend Int32 <: ToString

功能:这里为 Int32 类型扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 Int32 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

Int64

功能:表示 64 位有符号整型,表示范围为 [-2^{63}, 2^{63} - 1]。

extend Int64

extend Int64

功能:拓展 64 位有符号整数以支持一些数学常数。

static prop Max

public static prop Max: Int64

功能:获取 64 位有符号整数的最大值。

类型:Int64

static prop Min

public static prop Min: Int64

功能:获取 64 位有符号整数的最小值。

类型:Int64

extend Int64 <: Comparable<Int64>

extend Int64 <: Comparable<Int64>

功能:为 Int64 类型扩展 Comparable<Int64> 接口,支持比较操作。

父类型:

func compare(Int64)

public func compare(rhs: Int64): Ordering

功能:判断当前 Int64 值与指定 Int64 值的大小关系。

参数:

返回值:

extend Int64 <: Countable<Int64>

extend Int64 <: Countable<Int64>

功能:为 Int64 类型扩展 Countable<Int64> 接口,支持计数操作。

父类型:

func next(Int64)

public func next(right: Int64): Int64

功能:获取当前 Int64 值往右数 right 后所到位置的 Int64 值。

参数:

  • right: Int64 - 往右数的个数。

返回值:

  • Int64 - 往右数 right 后所到位置的 Int64 值。

func position()

public func position(): Int64

功能:获取当前 Int64 值的位置信息,即返回该 Int64 值本身。

返回值:

extend Int64 <: Hashable

extend Int64 <: Hashable

功能:为 Int64 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend Int64 <: ToString

extend Int64 <: ToString

功能:这里为 Int64 类型扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 Int64 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

Int8

功能:表示 8 位有符号整型,表示范围为 [-2^7, 2^7 - 1]。

extend Int8

extend Int8

功能:拓展 8 位有符号整数以支持一些数学常数。

static prop Max

public static prop Max: Int8

功能:获取 8 位有符号整数的最大值。

类型:Int8

static prop Min

public static prop Min: Int8

功能:获取 8 位有符号整数的最小值。

类型:Int8

extend Int8 <: Comparable<Int8>

extend Int8 <: Comparable<Int8>

功能:为 Int8 类型扩展 Comparable<Int8> 接口,支持比较操作。

父类型:

func compare(Int8)

public func compare(rhs: Int8): Ordering

功能:判断当前 Int8 值与指定 Int8 值的大小关系。

参数:

  • rhs: Int8 - 待比较的另一个 Int8 值。

返回值:

extend Int8 <: Countable<Int8>

extend Int8 <: Countable<Int8>

功能:为 Int8 类型扩展 Countable<Int8> 接口,支持计数操作。

父类型:

func next(Int64)

public func next(right: Int64): Int8

功能:获取当前 Int8 值往右数 right 后所到位置的 Int8 值。

参数:

  • right: Int64 - 往右数的个数。

返回值:

  • Int8 - 往右数 right 后所到位置的 Int8 值。

func position()

public func position(): Int64

功能:获取当前 Int8 值的位置信息,即将该 Int8 转换为 Int64 值。

返回值:

extend Int8 <: Hashable

extend Int8 <: Hashable

功能:为 Int8 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend Int8 <: ToString

extend Int8 <: ToString

功能:这里为 Int8 类型扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 Int8 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

IntNative

功能:表示平台相关的有符号整型,其长度与当前系统的位宽一致。

extend IntNative

extend IntNative

功能:拓展平台相关有符号整数以支持一些数学常数。

static prop Max

public static prop Max: IntNative

功能:获取平台相关有符号整数的最大值。

类型:IntNative

static prop Min

public static prop Min: IntNative

功能:获取平台相关有符号整数的最小值。

类型:IntNative

extend IntNative <: Comparable<IntNative>

extend IntNative <: Comparable<IntNative>

功能:为 IntNative 类型扩展 Comparable<IntNative> 接口,支持比较操作。

父类型:

func compare(IntNative)

public func compare(rhs: IntNative): Ordering

功能:判断当前 IntNative 值与指定 IntNative 值的大小关系。

参数:

返回值:

extend IntNative <: Countable<IntNative>

extend IntNative <: Countable<IntNative>

功能:为 IntNative 类型扩展 Countable<IntNative> 接口,支持计数操作。

父类型:

func next(Int64)

public func next(right: Int64): IntNative

功能:获取当前 IntNative 值往右数 right 后所到位置的 IntNative 值。

参数:

  • right: Int64 - 往右数的个数。

返回值:

func position()

public func position(): Int64

功能:获取当前 IntNative 值的位置信息,即将该 IntNative 转换为 Int64 值。

返回值:

extend IntNative <: Hashable

extend IntNative <: Hashable

功能:为 IntNative 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend IntNative <: ToString

extend IntNative <: ToString

功能:这里为 IntNative 类型扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 IntNative 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

Rune

功能:表示 unicode 字符集中的字符。

表示范围为 Unicode scalar value,即从 \u{0000}\u{D7FF},以及从 \u{E000}\u{10FFF} 的字符。

extend Rune <: RuneExtension

extend Rune <: RuneExtension

功能:为 Rune 类型实现一系列扩展方法,主要为在 Ascii 字符集范围内的一些字符判断、转换等操作。

父类型:

static func fromUtf8(Array<UInt8>, Int64)

public static func fromUtf8(arr: Array<UInt8>, index: Int64): (Rune, Int64)

功能:将字节数组中的指定元素,根据 UTF-8 编码规则转换成字符,并告知字符占用字节长度。

参数:

  • arr: Array<UInt8> - 待转换字节所在的字节数组。
  • index: Int64 - 待转换字节在数组中的下标。

返回值:

  • (Rune, Int64) - 转换得到的字符,以及该字符占用的字节长度。

static func getPreviousFromUtf8(Array<UInt8>, Int64)

public static func getPreviousFromUtf8(arr: Array<UInt8>, index: Int64): (Rune, Int64)

功能:获取字节数组中指定索引对应的字节所在的 UTF-8 编码字符,同时返回该字符首位字节码在数组中的索引。

当指定了一个索引,那么函数会找到数组对应索引位置并且根据 UTF-8 规则,查看该字节码是否是字符的首位字节码,如果不是就继续向前遍历,直到该字节码是首位字节码,然后利用字节码序列找到对应的字符。

参数:

  • arr: Array<UInt8> - 待从中获取字符的字节数组。
  • index: Int64 - 待查找字符在数组中的索引。

返回值:

  • (Rune, Int64) - 找到的字符,以及该字符首位字节码在数组中的索引。

异常:

  • IllegalArgumentException - 如果找不到对应首位字节码,即指定字节所在位置的字节不符合 UTF-8 编码,抛出异常。

static func intoUtf8Array(Rune, Array<UInt8>, Int64)

public static func intoUtf8Array(c: Rune, arr: Array<UInt8>, index: Int64): Int64

功能:该函数会把字符转成字节码序列然后覆盖 Array 数组内指定位置的字节码。

参数:

  • c: Rune - 待转换的字符。
  • arr: Array<UInt8> - 待覆盖的 Array 数组。
  • index: Int64 - 目标位置的起始索引。

返回值:

  • Int64 - 字符的字节码长度,例如中文是三个字节码长度。

static func utf8Size(Array<UInt8>, Int64)

public static func utf8Size(arr: Array<UInt8>, index: Int64): Int64

功能:该函数会返回字节数组指定索引位置为起始的字符占用的字节数。

在 UTF-8 编码中,ASCII 码首位字节第一位不为 1,其他长度的字符首位字节开头 1 的个数表明了该字符对应的字节码长度,该函数通过扫描首位,判断字节码长度。如果索引对应的不是首位字节码,就会抛出异常。

参数:

  • arr: Array<UInt8> - 待获取字符的字节数组。
  • index: Int64 - 指定字符的索引。

返回值:

  • Int64 - 字符的字节码长度,例如中文是三个字节码长度。

异常:

static func utf8Size(Rune)

public static func utf8Size(c: Rune): Int64

功能:返回字符对应的 UTF-8 编码的字节码长度,例如中文字符的字节码长度是 3。

参数:

  • c: Rune - 待计算 UTF-8 字节码长度的字符。

返回值:

  • Int64 - 字符的 UTF-8 字节码长度。

func isAscii()

public func isAscii(): Bool

功能:判断字符是否是 Ascii 中的字符。

返回值:

  • Bool - 如果是 Ascii 字符返回 true,否则返回 false。

func isAsciiControl()

public func isAsciiControl(): Bool

功能:判断字符是否是 Ascii 控制字符。其取值范围为 [00, 1F] 和 {7F} 的并集。

返回值:

  • Bool - 如果是 Ascii 控制字符返回 true,否则返回 false。

func isAsciiGraphic()

public func isAsciiGraphic(): Bool

功能:判断字符是否是 Ascii 图形字符。其取值范围为 [21, 7E]。

返回值:

  • Bool - 如果是 Ascii 图形字符返回 true,否则返回 false。

func isAsciiHex()

public func isAsciiHex(): Bool

功能:判断字符是否是 Ascii 十六进制字符。

返回值:

  • Bool - 如果是 Ascii 十六进制字符返回 true,否则返回 false。

func isAsciiLetter()

public func isAsciiLetter(): Bool

功能:判断字符是否是 Ascii 字母字符。

返回值:

  • Bool - 如果是 Ascii 字母字符返回 true,否则返回 false。

func isAsciiLowerCase()

public func isAsciiLowerCase(): Bool

功能:判断字符是否是 Ascii 小写字符。

返回值:

  • Bool - 如果是 Ascii 小写字符返回 true,否则返回 false。

func isAsciiNumber()

public func isAsciiNumber(): Bool

功能:判断字符是否是 Ascii 数字字符。

返回值:

  • Bool - 如果是 Ascii 数字字符返回 true,否则返回 false。

func isAsciiNumberOrLetter()

public func isAsciiNumberOrLetter(): Bool

功能:判断字符是否是 Ascii 数字或拉丁字母字符。

返回值:

  • Bool - 如果是 Ascii 数字或拉丁字母字符返回 true,否则返回 false。

func isAsciiOct()

public func isAsciiOct(): Bool

功能:判断字符是否是 Ascii 八进制字符。

返回值:

  • Bool - 如果是 Ascii 八进制字符返回 true,否则返回 false。

func isAsciiPunctuation()

public func isAsciiPunctuation(): Bool

功能:判断字符是否是 Ascii 标点符号字符。其取值范围为 [21, 2F]、[3A, 40]、[5B, 60] 和 [7B, 7E] 的并集。

返回值:

  • Bool - 如果是 Ascii 标点符号字符返回 true,否则返回 false。

func isAsciiUpperCase()

public func isAsciiUpperCase(): Bool

功能:判断字符是否是 Ascii 大写字符。

返回值:

  • Bool - 如果是 Ascii 大写字符返回 true,否则返回 false。

func isAsciiWhiteSpace()

public func isAsciiWhiteSpace(): Bool

功能:判断字符是否是 Ascii 空白字符。其取值范围为 [09, 0D] 和 {20} 的并集。

返回值:

  • Bool - 如果是 Ascii 空白字符返回 true,否则返回 false。

func toAsciiLowerCase()

public func toAsciiLowerCase(): Rune

功能:将字符转换为 Ascii 小写字符,如果无法转换则保持现状。

返回值:

  • Rune - 转换后的字符,如果无法转换则返回原来的 Rune

func toAsciiUpperCase()

public func toAsciiUpperCase(): Rune

功能:将字符转换为 Ascii 大写字符,如果无法转换则保持现状。

返回值:

  • Rune - 转换后的字符,如果无法转换则返回原来的 Rune

extend Rune <: Comparable<Rune>

extend Rune <: Comparable<Rune>

功能:为 Rune 类型扩展 Comparable<Rune> 接口,支持比较操作。

父类型:

func compare(Rune)

public func compare(rhs: Rune): Ordering

功能:判断当前 Rune 实例与指定 Rune 实例的大小关系。

Rune 的大小关系指的是它们对应的 unicode 码点的大小关系。

参数:

  • rhs: Rune - 待比较的另一个 Rune 实例。

返回值:

extend Rune <: Countable<Rune>

extend Rune <: Countable<Rune>

功能:为 Rune 类型扩展 Countable<Rune> 接口,支持计数操作。

父类型:

func next(Int64)

public func next(right: Int64): Rune

功能:获取当前 Rune 值往右数 right 后所到位置的 Rune 值。

参数:

  • right: Int64 - 往右数的个数。

返回值:

  • Rune - 往右数 right 后所到位置的 Rune 值。

异常:

func position()

public func position(): Int64

功能:获取当前 Rune 值的位置信息,即将该 Rune 转换为 Int64 值。

返回值:

extend Rune <: Hashable

extend Rune <: Hashable

功能:为 Rune 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend Rune <: ToString

extend Rune <: ToString

功能:这里为 Rune 类型扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 Rune 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

UInt16

功能:表示 16 位无符号整型,表示范围为 [0, 2^{16} - 1]。

extend UInt16

extend UInt16

功能:拓展 16 位无符号整数以支持一些数学常数。

static prop Max

public static prop Max: UInt16

功能:获取 16 位无符号整数的最大值。

类型:UInt16

static prop Min

public static prop Min: UInt16

功能:获取 16 位无符号整数的最小值。

类型:UInt16

extend UInt16 <: Comparable<UInt16>

extend UInt16 <: Comparable<UInt16>

功能:为 UInt16 类型扩展 Comparable<UInt16> 接口,支持比较操作。

父类型:

func compare(UInt16)

public func compare(rhs: UInt16): Ordering

功能:判断当前 UInt16 值与指定 UInt16 值的大小关系。

参数:

返回值:

extend UInt16 <: Countable<UInt16>

extend UInt16 <: Countable<UInt16>

功能:为 UInt16 类型扩展 Countable<UInt16> 接口,支持计数操作。

父类型:

func next(Int64)

public func next(right: Int64): UInt16

功能:获取当前 UInt16 值往右数 right 后所到位置的 UInt16 值。

参数:

  • right: Int64 - 往右数的个数。

返回值:

func position()

public func position(): Int64

功能:获取当前 UInt16 值的位置信息,即将该 UInt16 转换为 Int64 值。

返回值:

extend UInt16 <: Hashable

extend UInt16 <: Hashable

功能:为 UInt16 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend UInt16 <: ToString

extend UInt16 <: ToString

功能:这里为 UInt16 类型扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 UInt16 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

UInt32

功能:表示 32 位无符号整型,表示范围为 [0, 2^{32} - 1]。

extend UInt32

extend UInt32

功能:拓展 32 位无符号整数以支持一些数学常数。

static prop Max

public static prop Max: UInt32

功能:获取 32 位无符号整数的最大值。

类型:UInt32

static prop Min

public static prop Min: UInt32

功能:获取 32 位无符号整数的最小值。

类型:UInt32

extend UInt32 <: Comparable<UInt32>

extend UInt32 <: Comparable<UInt32>

功能:为 UInt32 类型扩展 Comparable<UInt32> 接口,支持比较操作。

父类型:

func compare(UInt32)

public func compare(rhs: UInt32): Ordering

功能:判断当前 UInt32 值与指定 UInt32 值的大小关系。

参数:

返回值:

extend UInt32 <: Countable<UInt32>

extend UInt32 <: Countable<UInt32>

功能:为 UInt32 类型扩展 Countable<UInt32> 接口,支持计数操作。

父类型:

func next(Int64)

public func next(right: Int64): UInt32

功能:获取当前 UInt32 值往右数 right 后所到位置的 UInt32 值。

参数:

  • right: Int64 - 往右数的个数。

返回值:

func position()

public func position(): Int64

功能:获取当前 UInt32 值的位置信息,即将该 UInt32 转换为 UInt64 值。

返回值:

extend UInt32 <: Hashable

extend UInt32 <: Hashable

功能:为 UInt32 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend UInt32 <: ToString

extend UInt32 <: ToString

功能:这里为 UInt32 类型扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 UInt32 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

UInt64

功能:表示 64 位无符号整型,表示范围为 [0, 2^{64} - 1]。

extend UInt64

extend UInt64

功能:拓展 64 位无符号整数以支持一些数学常数。

static prop Max

public static prop Max: UInt64

功能:获取 64 位无符号整数的最大值。

类型:UInt64

static prop Min

public static prop Min: UInt64

功能:获取 64 位无符号整数的最小值。

类型:UInt64

extend UInt64 <: Comparable<UInt64>

extend UInt64 <: Comparable<UInt64>

功能:为 UInt64 类型扩展 Comparable<UInt64> 接口,支持比较操作。

父类型:

func compare(UInt64)

public func compare(rhs: UInt64): Ordering

功能:判断当前 UInt64 值与指定 UInt64 值的大小关系。

参数:

返回值:

extend UInt64 <: Countable<UInt64>

extend UInt64 <: Countable<UInt64>

功能:为 UInt64 类型扩展 Countable<UInt64> 接口,支持计数操作。

父类型:

func next(Int64)

public func next(right: Int64): UInt64

功能:获取当前 UInt64 值往右数 right 后所到位置的 UInt64 值。

参数:

  • right: Int64 - 往右数的个数。

返回值:

func position()

public func position(): Int64

功能:获取当前 UInt64 值的位置信息,即将该 UInt64 转换为 Int64 值。

返回值:

extend UInt64 <: Hashable

extend UInt64 <: Hashable

功能:为 UInt64 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend UInt64 <: ToString

extend UInt64 <: ToString

功能:这里为 UInt64 类型扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 UInt64 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

UInt8

功能:表示 8 位无符号整型,表示范围为 [0, 2^8 - 1]。

extend UInt8

extend UInt8

功能:拓展 8 位无符号整数以支持一些数学常数。

static prop Max

public static prop Max: UInt8

功能:获取 8 位无符号整数的最大值。

类型:UInt8

static prop Min

public static prop Min: UInt8

功能:获取 8 位无符号整数的最小值。

类型:UInt8

extend UInt8 <: Comparable<UInt8>

extend UInt8 <: Comparable<UInt8>

功能:为 UInt8 类型扩展 Comparable<UInt8> 接口,支持比较操作。

父类型:

func compare(UInt8)

public func compare(rhs: UInt8): Ordering

功能:判断当前 UInt8 值与指定 UInt8 值的大小关系。

参数:

返回值:

extend UInt8 <: Countable<UInt8>

extend UInt8 <: Countable<UInt8>

功能:为 UInt8 类型扩展 Countable<UInt8> 接口,支持计数操作。

父类型:

func next(Int64)

public func next(right: Int64): UInt8

功能:获取当前 UInt8 值往右数 right 后所到位置的 UInt8 值。

参数:

  • right: Int64 - 往右数的个数。

返回值:

  • UInt8 - 往右数 right 后所到位置的 UInt8 值。

func position()

public func position(): Int64

功能:获取当前 UInt8 值的位置信息,即将该 UInt8 转换为 Int64 值。

返回值:

extend UInt8 <: Hashable

extend UInt8 <: Hashable

功能:为 UInt8 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend UInt8 <: ToString

extend UInt8 <: ToString

功能:这里为 UInt8 类型扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 UInt8 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

UIntNative

功能:表示平台相关的无符号整型,其长度与当前系统的位宽一致。

extend UIntNative

extend UIntNative

功能:拓展平台相关无符号整数以支持一些数学常数。

static prop Max

public static prop Max: UIntNative

功能:获取平台相关无符号整数的最大值。

类型:类型:UIntNative

static prop Min

public static prop Min: UIntNative

功能:获取平台相关无符号整数的最小值。

类型:UIntNative

extend UIntNative <: Comparable<UIntNative>

extend UIntNative <: Comparable<UIntNative>

功能:为 UIntNative 类型扩展 Comparable<UIntNative> 接口,支持比较操作。

父类型:

func compare(UIntNative)

public func compare(rhs: UIntNative): Ordering

功能:判断当前 UIntNative 值与指定 UIntNative 值的大小关系。

参数:

返回值:

extend UIntNative <: Countable

extend UIntNative <: Countable<UIntNative>

功能:为 UIntNative 类型扩展 Countable<UIntNative> 接口,支持计数操作。

父类型:

func next(Int64)

public func next(right: Int64): UIntNative

功能:获取当前 UIntNative 值往右数 right 后所到位置的 UIntNative 值。

参数:

  • right: Int64 - 往右数的个数。

返回值:

func position()

public func position(): Int64

功能:获取当前 UIntNative 值的位置信息,即将该 UIntNative 转换为 Int64 值。

返回值:

extend UIntNative <: Hashable

extend UIntNative <: Hashable

功能:为 UIntNative 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend UIntNative <: ToString

extend UIntNative <: ToString

功能:这里为 UIntNative 类型扩展 ToString 接口,实现向 String 类型的转换。

父类型:

func toString()

public func toString(): String

功能:将 UIntNative 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

Unit

功能:表示仓颉语言中只关心副作用而不关心值的表达式的类型。

例如,print 函数、赋值表达式、复合赋值表达式、自增和自减表达式、循环表达式,它们的类型都是 Unit

Unit 类型只有一个值,也是它的字面量:()。除了赋值、判等和判不等外,Unit 类型不支持其他操作。

extend Unit <: Equatable<Unit>

extend Unit <: Equatable<Unit>

功能:为 Unit 类型扩展 Equatable<Unit> 接口。

父类型:

extend Unit <: Hashable

extend Unit <: Hashable

功能:为 Unit 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值,Unit 的哈希值为 0。

返回值:

extend Unit <: ToString

extend Unit <: ToString

功能:为 Unit 类型其扩展 ToString 接口,实现向 String 类型的转换。

Unit 的字符串表示是 "()"。

父类型:

func toString()

public func toString(): String

功能:将 Unit 值转换为可输出的字符串。

返回值:

  • String - 转化后的字符串。

接口

interface Any

public interface Any

功能:Any 是所有类型的父类型,所有 interface 都默认继承它,所有非 interface 类型都默认实现它。

interface ByteExtension

public interface ByteExtension

功能:该接口用于为 Byte 类型实现扩展方法,接口本身为不包含任何属性、方法。

extend Byte <: ByteExtension

extend Byte <: ByteExtension

功能:为 Byte 类型实现一系列扩展方法,主要为在 Ascii 字符集范围内的一些字符判断、转换等操作。

父类型:

func isAscii()

public func isAscii(): Bool

功能:判断 Byte 是否是在 Ascii 范围内。

返回值:

  • Bool - 如果 Byte 在 Ascii 范围内返回 true,否则返回 false。

func isAsciiControl()

public func isAsciiControl(): Bool

功能:判断 Byte 是否是在 Ascii 控制字符范围内。其取值范围为 [00, 1F] 和 {7F} 的并集。

返回值:

  • Bool - 如果 Byte 在 Ascii 控制字符范围内返回 true,否则返回 false。

func isAsciiGraphic()

public func isAsciiGraphic(): Bool

功能:判断 Byte 是否是在 Ascii 图形字符范围内。其取值范围为 [21, 7E]。

返回值:

  • Bool - 如果 Byte 在 Ascii 图形字符范围内返回 true,否则返回 false。

func isAsciiHex()

public func isAsciiHex(): Bool

功能:判断 Byte 是否是在 Ascii 十六进制数字范围内。

返回值:

  • Bool - 如果 Byte 在 Ascii 十六进制数字范围内返回 true,否则返回 false。

func isAsciiLetter()

public func isAsciiLetter(): Bool

功能:判断 Byte 是否是在 Ascii 拉丁字母范围内。

返回值:

  • Bool - 如果 Byte 在 Ascii 拉丁字母范围内返回 true,否则返回 false。

func isAsciiLowerCase()

public func isAsciiLowerCase(): Bool

功能:判断 Byte 是否是在 Ascii 小写拉丁字母范围内。

返回值:

  • Bool - 如果 Byte 在 Ascii 小写拉丁字母范围内返回 true,否则返回 false。

func isAsciiNumber()

public func isAsciiNumber(): Bool

功能:判断 Byte 是否是在 Ascii 十进制数字范围内。

返回值:

  • Bool - 如果 Byte 在 Ascii 十进制数字范围内返回 true,否则返回 false。

func isAsciiNumberOrLetter()

public func isAsciiNumberOrLetter(): Bool

功能:判断 Byte 是否是在 Ascii 十进制数字和拉丁字母范围内。

返回值:

  • Bool - 如果 Byte 在 Ascii 十进制数字和拉丁字母范围内返回 true,否则返回 false。

func isAsciiOct()

public func isAsciiOct(): Bool

功能:判断 Byte 是否是在 Ascii 八进制数字范围内。

返回值:

  • Bool - 如果 Byte 在 Ascii 八进制数字范围内返回 true,否则返回 false。

func isAsciiPunctuation()

public func isAsciiPunctuation(): Bool

功能:判断 Byte 是否是在 Ascii 标点符号范围内。其取值范围为 [21, 2F]、[3A, 40]、[5B, 60] 和 [7B, 7E] 的并集。

返回值:

  • Bool - 如果 Byte 在 Ascii 标点符号范围内返回 true,否则返回 false。

func isAsciiUpperCase()

public func isAsciiUpperCase(): Bool

功能:判断 Byte 是否是在 Ascii 大写拉丁字母范围内。

返回值:

  • Bool - 如果 Byte 在 Ascii 大写拉丁字母范围内返回 true,否则返回 false。

func isAsciiWhiteSpace()

public func isAsciiWhiteSpace(): Bool

功能:判断 Byte 是否是在 Ascii 空白字符范围内。其取值范围为 [09, 0D] 和 {20} 的并集。

返回值:

  • Bool - 如果 Byte 在 Ascii 空白字符范围内返回 true,否则返回 false。

func toAsciiLowerCase()

public func toAsciiLowerCase(): Byte

功能:将 Byte 换为对应的 Ascii 小写字符 Byte,如果无法转换则保持现状。

返回值:

  • Byte - 转换后的 Byte,如果无法转换则返回原来的 Byte

func toAsciiUpperCase()

public func toAsciiUpperCase(): Byte

功能:将 Byte 换为对应的 Ascii 大写字符 Byte,如果无法转换则保持现状。

返回值:

  • Byte - 转换后的 Byte,如果无法转换则返回原来的 Byte

interface CType

sealed interface CType

功能:表示支持与 C 语言互操作的接口。

CType 接口是一个语言内置的空接口,它是 CType 约束的具体实现,所有 C 互操作支持的类型都隐式地实现了该接口,因此所有 C 互操作支持的类型都可以作为 CType 类型的子类型使用。

注意:

  • CType 接口是仓颉中的一个接口类型,它本身不满足 CType 约束。
  • CType 接口不允许被用户继承、扩展。
  • CType 接口不会突破子类型的使用限制。

示例:

@C
struct Data {}

@C
func foo() {}

main() {
    var c: CType = Data() // ok
    c = 0 // ok
    c = true // ok
    c = CString(CPointer<UInt8>()) // ok
    c = CPointer<Int8>() // ok
    c = foo // ok
}

interface Collection<T>

public interface Collection<T> <: Iterable<T> {
    prop size: Int64
    func isEmpty(): Bool
    func toArray(): Array<T>
}

功能:该接口用来表示集合,通常容器类型应该实现该接口。

父类型:

prop size

prop size: Int64

功能:获取当前集合的大小,即容器的容量。

类型:Int64

func isEmpty()

func isEmpty(): Bool

功能:判断当前集合是否为空。

返回值:

  • Bool - 如果为空返回 true,否则返回 false。

func toArray()

func toArray(): Array<T>

功能:将当前集合转为数组类型。

返回值:

  • Array<T> - 转换得到的数组。

interface Comparable<T>

public interface Comparable<T> <: Equatable<T> & Less<T> & Greater<T> & LessOrEqual<T> & GreaterOrEqual<T> {
    func compare(that: T): Ordering
}

功能:该接口表示比较运算,是等于、不等于、小于、大于、小于等于、大于等于接口的集合体。

该接口中提供运算符 ==、!=、<、<=、>、>= 重载的默认实现,默认实现根据 compare 函数的返回值来确定其返回值。例如:如果 a.compare(b) 的返回值为 EQ,则 a == b 返回 true,否则返回 false。

父类型:

func compare(T)

func compare(that: T): Ordering

功能:判断当前 T 类型实例与参数指向的 T 类型实例的大小关系。

参数:

  • that: T - 待与当前实例比较的另一个实例。

返回值:

interface Countable<T>

public interface Countable<T> {
    func next(right: Int64): T
    func position(): Int64
}

功能:该接口表示类型可数。

可数类型的每一个实例都对应一个位置信息(Int64 值),可以通过往后数数得到其他的该类型实例。

func next(Int64)

func next(right: Int64): T

功能:获取当前实例往右数 right 后所到位置的 T 类型实例。

参数:

  • right: Int64 - 往右数的个数。

返回值:

  • T - 往右数 right 后所到位置的 T 类型实例。

func position()

func position(): Int64

功能:获取当前可数实例的位置信息,即将当前实例转为 Int64 类型。

返回值:

interface DurationExtension

public interface DurationExtension {
    operator func *(r: Duration): Duration
}

功能: 用于拓展 Duration 实例作为右操作数时,返回乘积为新 Duration 实例的乘法运算。

operator func *(Duration)

operator func *(r: Duration): Duration

功能:实现 T 类型(T 是实现 DurationExtension 接口的类型)和 Duration 类型的乘法,即 T * Duration 运算。

参数:

  • r: Duration - 乘法的右操作数。

返回值:

  • Duration - T 类型实例和 r 的乘积。

异常:

extend Float64 <: DurationExtension

extend Float64 <: DurationExtension

功能:拓展了 Float64 类型作为左操作数和 Duration 类型作为右操作数的乘法运算。

父类型:

operator func *(Duration)

public operator func *(r: Duration): Duration

功能:实现 Float64 类型和 Duration 类型的乘法,即 Float64 * Duration 运算。

参数:

返回值:

异常:

extend Int64 <: DurationExtension

extend Int64 <: DurationExtension

功能:拓展了 Int64 类型作为左操作数和 Duration 类型作为右操作数的乘法运算。

父类型:

operator func *(Duration)

public operator func *(r: Duration): Duration

功能:实现 Int64 类型和 Duration 类型的乘法,即 Int64 * Duration 运算。

例如 2 * Duration.second 返回表示时间间隔为 2 秒的 Duration 实例。

参数:

  • r: Duration - 乘法的右操作数。

返回值:

异常:

interface Equal<T>

public interface Equal<T> {
    operator func ==(rhs: T): Bool
}

功能:该接口用于支持判等操作。

operator func ==(T)

operator func ==(rhs: T): Bool

功能:判断两个实例是否相等。

参数:

  • rhs: T - 待比较的另一个实例。

返回值:

  • Bool - 如果相等,返回 true,否则返回 false。

interface Equatable<T>

public interface Equatable<T> <: Equal<T> & NotEqual<T>

功能:该接口是判等和判不等两个接口的集合体。

该接口中提供运算符 != 重载的默认实现,默认实现根据 == 运算的返回值来确定其返回值。例如:如果 a == b 的返回值为 true,则 a != b 返回 false,否则返回 true。

已为部分仓颉类型实现该接口,包括:UnitBoolRuneInt64Int32Int16Int8UIntNativeUInt64UInt32UInt16UInt8Float64Float32Float16StringArrayBoxArrayListHashSet

父类型:

interface FloatToBits

public interface FloatToBits

功能:该接口用于扩展 Float 类型与以位表示的整形数值转换。

interface GreaterOrEqual<T>

public interface GreaterOrEqual<T> {
    operator func >=(rhs: T): Bool
}

功能:该接口表示大于等于计算。

operator func >=(T)

operator func >=(rhs: T): Bool

功能:判断当前 T 类型实例是否大于等于参数指向的 T 类型实例。

参数:

  • rhs: T - 待与当前实例比较的另一个实例。

返回值:

  • Bool - 如果大于等于,返回 true,否则返回 false。

interface Greater<T>

public interface Greater<T> {
    operator func >(rhs: T): Bool
}

功能:该接口表示大于计算。

operator func >(T)

operator func >(rhs: T): Bool

功能:判断当前 T 类型实例是否大于参数指向的 T 类型实例。

参数:

  • rhs: T - 待与当前实例比较的另一个实例。

返回值:

  • Bool - 如果大于,返回 true,否则返回 false。

interface Hashable

public interface Hashable {
    func hashCode(): Int64
}

功能:该接口用于计算哈希值。

已为部分仓颉类型实现该接口,包括:BoolRuneIntNativeInt64Int32Int16Int8UIntNativeUInt64UInt32UInt16UInt8Float64Float32Float16StringBox

func hashCode()

func hashCode(): Int64

功能:获得实例类型的哈希值。

返回值:

  • Int64 - 返回实例类型的哈希值。

interface Hasher

public interface Hasher {
    func finish(): Int64
    mut func reset(): Unit
    mut func write(value: Bool): Unit
    mut func write(value: Rune): Unit
    mut func write(value: Int8): Unit
    mut func write(value: Int16): Unit
    mut func write(value: Int32): Unit
    mut func write(value: Int64): Unit
    mut func write(value: UInt8): Unit
    mut func write(value: UInt16): Unit
    mut func write(value: UInt32): Unit
    mut func write(value: UInt64): Unit
    mut func write(value: Float16): Unit
    mut func write(value: Float32): Unit
    mut func write(value: Float64): Unit
    mut func write(value: String): Unit
}

功能:该接口用于处理哈希组合运算。

可以使用一系列 write 函数传入不同数据类型实例,并计算他们的组合哈希值。

func finish()

func finish(): Int64

功能:获取哈希运算的结果。

返回值:

  • Int64 - 经过计算后的哈希值。

func reset()

mut func reset(): Unit

功能:重置哈希值到 0。

func write(Bool)

mut func write(value: Bool): Unit

功能:把想要哈希运算的 Bool 值传入,然后进行哈希组合运算。

参数:

  • value: Bool - 待运算的值。

func write(Float16)

mut func write(value: Float16): Unit

功能:通过该函数把想要哈希运算的 Float16 值传入,然后进行哈希组合运算。

参数:

  • value: Float16 - 待运算的值。

func write(Float32)

mut func write(value: Float32): Unit

功能:通过该函数把想要哈希运算的 Float32 值传入,然后进行哈希组合运算。

参数:

  • value: Float32 - 待运算的值。

func write(Float64)

mut func write(value: Float64): Unit

功能:通过该函数把想要哈希运算的 Float64 值传入,然后进行哈希组合运算。

参数:

  • value: Float64 - 待运算的值。

func write(Int16)

mut func write(value: Int16): Unit

功能:通过该函数把想要哈希运算的 Int16 值传入,然后进行哈希组合运算。

参数:

  • value: Int16 - 待运算的值。

func write(Int32)

mut func write(value: Int32): Unit

功能:通过该函数把想要哈希运算的 Int32 值传入,然后进行哈希组合运算。

参数:

  • value: Int32 - 待运算的值。

func write(Int64)

mut func write(value: Int64): Unit

功能:通过该函数把想要哈希运算的 Int64 值传入,然后进行哈希组合运算。

参数:

  • value: Int64 - 待运算的值。

func write(Int8)

mut func write(value: Int8): Unit

功能:通过该函数把想要哈希运算的 Int8 值传入,然后进行哈希组合运算。

参数:

  • value: Int8 - 待运算的值

func write(Rune)

mut func write(value: Rune): Unit

功能:通过该函数把想要哈希运算的 Rune 值传入,然后进行哈希组合运算。

参数:

  • value: Rune - 待运算的值。

func write(String)

mut func write(value: String): Unit

功能:通过该函数把想要哈希运算的 String 值传入,然后进行哈希组合运算。

参数:

  • value: String - 待运算的值。

func write(UInt16)

mut func write(value: UInt16): Unit

功能:通过该函数把想要哈希运算的 UInt16 值传入,然后进行哈希组合运算。

参数:

  • value: UInt16 - 待运算的值。

func write(UInt32)

mut func write(value: UInt32): Unit

功能:通过该函数把想要哈希运算的 UInt32 值传入,然后进行哈希组合运算。

参数:

  • value: UInt32 - 待运算的值。

func write(UInt64)

mut func write(value: UInt64): Unit

功能:通过该函数把想要哈希运算的 UInt64 值传入,然后进行哈希组合运算。

参数:

  • value: UInt64 - 待运算的值。

func write(UInt8)

mut func write(value: UInt8): Unit

功能:通过该函数把想要哈希运算的 UInt8 值传入,然后进行哈希组合运算。

参数:

  • value: UInt8 - 待运算的值。

interface Iterable<E>

public interface Iterable<E> {
    func iterator(): Iterator<E>
}

功能:该接口表示可迭代,实现了该接口的类型(通常为容器类型)可以在 for-in 语句中实现迭代,也可以获取其对应的迭代器类型实例,调用 next 函数实现迭代。

本包已经为 ArrayArrayListHashMap 等基础容器类型实现了该接口,用户可以为其他类型实现该接口,使之支持迭代遍历的功能。

func iterator()

func iterator(): Iterator<E>

功能:获取迭代器。

返回值:

interface LessOrEqual<T>

public interface LessOrEqual<T> {
    operator func <=(rhs: T): Bool
}

功能:该接口表示小于等于计算。

operator func <=(T)

operator func <=(rhs: T): Bool

功能:判断当前 T 类型实例是否小于等于参数指向的 T 类型实例。

参数:

  • rhs: T - 待与当前实例比较的另一个实例。

返回值:

  • Bool - 如果小于等于,返回 true,否则返回 false。

interface Less<T>

public interface Less<T> {
    operator func <(rhs: T): Bool
}

功能:该接口表示小于计算。

operator func <(T)

operator func <(rhs: T): Bool

功能:判断当前 T 类型实例是否小于参数指向的 T 类型实例。

参数:

  • rhs: T - 待与当前实例比较的另一个实例。

返回值:

  • Bool - 如果小于,返回 true,否则返回 false。

interface NotEqual<T>

public interface NotEqual<T> {
    operator func !=(rhs: T): Bool
}

功能:该接口用于支持判不等操作。

operator func !=(T)

operator func !=(rhs: T): Bool

功能:判断两个实例是否不相等。

参数:

  • rhs: T - 待比较的另一个实例。

返回值:

  • Bool - 如果不相等,返回 true,否则返回 false。

interface Resource

public interface Resource {
    func close(): Unit
    func isClosed(): Bool
}

功能:该接口用于资源管理,通常用于内存、句柄等资源的关闭和释放。

实现了该接口的类型可以在 try-with-resource 语法上下文中实现自动资源释放。

func isClosed()

func isClosed(): Bool

功能:判断资源是否已经关闭。

返回值:

  • Bool - 如果已经关闭返回 true,否则返回 false。

func close()

func close(): Unit

功能:关闭资源。

interface RuneExtension

public interface RuneExtension

功能:该接口用于为 Rune 类型实现扩展方法,接口本身为不包含任何属性、方法。

interface ThreadContext

public interface ThreadContext {
    func end(): Unit
    func hasEnded(): Bool
}

功能:仓颉线程上下文接口。

用户创建 thread 时,除了缺省 spawn 表达式入参,也可以通过传入不同 ThreadContext 类型的实例,选择不同的线程上下文,然后一定程度上控制并发行为。

目前不允许用户自行实现 ThreadContext 接口,仓颉语言根据使用场景,提供了 MainThreadContext, 具体定义可在终端框架库中查阅。

注意:

在 cjvm 后端,spawn 传入 ThreadContext 类型的参数时,无任何作用。

func end()

func end(): Unit

功能:结束方法,用于向当前 context 发送结束请求。

func hasEnded()

func hasEnded(): Bool

功能:检查方法,用于检查当前 context 是否已结束。

返回值:

  • Bool - 如果结束返回 true,否则返回 false。

interface ToString

public interface ToString {
    func toString(): String
}

功能:该接口用来提供具体类型的字符串表示。

func toString()

func toString(): String

功能:获取实例类型的字符串表示。

返回值:

  • String - 返回实例类型的字符串表示。

class ArrayIterator<T>

public class ArrayIterator<T> <: Iterator<T> {
    public init(data: Array<T>)
}

功能:数组迭代器,迭代功能详述见 IterableIterator 说明。

父类型:

init(Array<T>)

public init(data: Array<T>)

功能:给定一个 Array 数组实例,创建其对应的迭代器,用来迭代遍历该数组实例中全部对象。

参数:

  • data: Array<T> - 数组实例。

func iterator()

public func iterator(): Iterator<T>

功能:获取当前迭代器实例本身。

返回值:

  • Iterator<T> - 当前迭代器实例本身。

func next()

public func next(): Option<T>

功能:返回数组迭代器中的下一个值。

返回值:

  • Option<T> - 数组迭代器中的下一个成员,用 Option 封装,迭代到末尾时返回 None

class Box<T>

public class Box<T> {
    public var value: T
    public init(v: T)
}

功能:Box 类型提供了为其他类型添加一层 class 封装的能力。

如果 T 类型本身不具备引用能力,如 struct 类型,封装后 Box<T> 类型将可被引用。

var value

public var value: T

功能:获取或修改被包装的值。

类型:T

init(T)

public init(v: T)

功能:给定 T 类型实例,构造对应的 Box<T> 实例。

参数:

  • v: T - 任意类型实例。

extend<T> Box<T> <: Comparable<Box<T>> where T <: Comparable<T>

extend<T> Box<T> <: Comparable<Box<T>> where T <: Comparable<T>

功能:为 Box<T> 类扩展 Comparable<Box<T>> 接口,提供比较大小的能力。

Box<T> 实例的大小关系与其封装的 T 实例大小关系相同。

父类型:

func compare(Box<T>)

public func compare(that: Box<T>): Ordering

功能:判断当前 Box 实例与另一个 Box 实例的大小关系。

参数:

  • that: Box<T> - 比较的另外一个 Box 对象。

返回值:

operator func !=(Box<T>)

public operator func !=(that: Box<T>): Bool

功能:比较 Box 对象是否不相等。

参数:

  • that: Box<T> - 比较的另外一个 Box 对象。

返回值:

  • Bool - 当前 Box 对象不等于参数 Box 对象返回 true,否则返回 false。

operator func <(Box<T>)

public operator func <(that: Box<T>): Bool

功能:比较 Box 对象的大小。

参数:

  • that: Box<T> - 比较的另外一个 Box 对象。

返回值:

  • Bool - 当前 Box 对象小于参数 Box 对象返回 true,否则返回 false。

operator func <=(Box<T>)

public operator func <=(that: Box<T>): Bool

功能:比较 Box 对象的大小。

参数:

  • that: Box<T> - 比较的另外一个 Box 对象。

返回值:

  • Bool - 当前 Box 对象小于等于参数 Box 对象返回 true,否则返回 false。

operator func ==(Box<T>)

public operator func ==(that: Box<T>): Bool

功能:比较 Box 对象是否相等。

参数:

  • that: Box<T> - 比较的另外一个 Box 对象。

返回值:

  • Bool - 当前 Box 对象等于参数 Box 对象返回 true,否则返回 false。

operator func >(Box<T>)

public operator func >(that: Box<T>): Bool

功能:比较 Box 对象的大小。

参数:

  • that: Box<T> - 比较的另外一个 Box 对象。

返回值:

  • Bool - 当前 Box 对象大于参数 Box 对象返回 true,否则返回 false。

operator func >=(Box<T>)

public operator func >=(that: Box<T>): Bool

功能:比较 Box 对象的大小。

参数:

  • that: Box<T> - 比较的另外一个 Box 对象。

返回值:

  • Bool - 当前 Box 对象大于等于参数 Box 对象返回 true,否则返回 false。

extend<T> Box<T> <: Hashable where T <: Hashable

extend<T> Box<T> <: Hashable where T <: Hashable

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取 Box 对象的哈希值。

实际上该值为 Box 中封装的 T 类型实例的哈希值。

返回值:

  • Int64 - 当前 Box 对象的哈希值。

extend<T> Box<T> <: ToString where T <: ToString

extend<T> Box<T> <: ToString where T <: ToString

功能:为 Box<T> 类型扩展 ToString 接口,支持转字符串操作。

父类型:

func toString()

public func toString(): String

功能:获取 Box 对象的字符串表示,字符串内容为当前实例封装的 T 类型实例的字符串表示。

返回值:

  • String - 转换后的字符串。

class Future<T>

public class Future<T>

功能:Future<T> 实例代表一个仓颉线程任务,可用于获取仓颉线程的计算结果,向仓颉线程发送取消信号。

spawn 表达式的返回类型是 Future<T>,其中 T 的类型取决于 spawn 表达式中的闭包的返回值类型。

prop thread

public prop thread: Thread

功能:获得对应仓颉线程的 Thread 实例。

类型:Thread

func cancel()

public func cancel(): Unit

功能:给当前 Future 实例对应的仓颉线程发送取消请求。该方法不会立即停止线程执行,仅发送请求,相应地,Thread 类的函数 hasPendingCancellation 可用于检查线程是否存在取消请求,用户可以通过该检查来自行决定是否提前终止线程以及如何终止线程。

func get()

public func get(): T

功能:阻塞当前线程,等待并获取当前 Future<T> 对象对应的线程的结果。

返回值:

  • T - 当前 Future<T> 实例代表的线程运行结束后的返回值。

func get(Duration)

public func get(timeout: Duration): T

功能:阻塞当前线程,等待指定时长并获取当前 Future<T> 对象对应的线程的返回值。

需指定等待的超时时间,如果相应的线程在指定时间内未完成执行,则该函数将抛出异常TimeoutException。如果 timeout <= Duration.Zero,等同于 get(),即不限制等待时长。如果线程抛出异常退出执行,在 get 调用处将继续抛出该异常。

参数:

返回值:

  • T - 返回指定时长后仓颉线程执行结果。

异常:

  • TimeoutException - 如果相应的线程在指定时间内未完成执行,则该函数将抛出此异常。

func tryGet()

public func tryGet(): Option<T>

功能:尝试获取执行结果,不会阻塞当前线程。如果相应的线程未完成,则该函数返回 None

返回值:

  • Option<T> - 如果当前仓颉线程未完成返回 None,否则返回执行结果。

class Iterator<T>

public abstract class Iterator<T> <: Iterable<T>

功能:该类表示迭代器,提供 next 方法支持对容器内的成员进行迭代遍历。

父类型:

func iterator()

public func iterator() : Iterator<T>

功能:返回迭代器自身。

返回值:

func next()

public func next(): Option<T>

功能:获取迭代过程中的下一个元素。

返回值:

  • Option<T> - 迭代过程中的下一个元素。

extend<T> Iterator<T>

extend<T> Iterator<T>

功能:扩展 Iterator<T> 类型。

func all((T) -> Bool)

public func all(predicate: (T)-> Bool): Bool

功能:判断迭代器所有元素是否都满足条件。

参数:

  • predicate: (T) -> Bool - 给定的条件。

返回值:

  • Bool - 元素是否都满足条件。

func any((T) -> Bool)

public func any(predicate: (T)-> Bool): Bool

功能:判断迭代器是否存在任意一个满足条件的元素。

参数:

  • predicate: (T) -> Bool - 给定的条件。

返回值:

  • Bool - 是否存在任意满足条件的元素。

func at(Int64)

public func at(n: Int64): Option<T>

功能:获取当前迭代器第 n 个元素。

参数:

  • n: Int64 - 给定的个数。

返回值:

  • Option<T> - 返回对应位置元素,若 n 大于剩余元素数量则返回 None。

func concat(Iterator<T>)

public func concat(other: Iterator<T>): Iterator<T>

功能:串联两个迭代器,当前迭代器在先,参数表示的迭代器在后。

参数:

  • other: Iterator<T> - 要串联在后面的迭代器。

返回值:

  • Iterator<T> - 返回串联后的新迭代器。

func count()

public func count(): Int64

功能:统计当前迭代器包含元素数量。

返回值:

  • Int64 - 返回迭代器包含元素数量。

func enumerate()

public func enumerate(): Iterator<(Int64, T)>

功能:用于获取带索引的迭代器。

返回值:

func filter((T) -> Bool)

public func filter(predicate: (T)-> Bool): Iterator<T>

功能:筛选出满足条件的元素。

参数:

  • predicate: (T) -> Bool - 给定的条件,条件为 true 的元素会按顺序出现在返回的迭代器里。

返回值:

  • Iterator<T> - 返回一个新迭代器。

func filterMap<R>((T) -> Option<R>)

public func filterMap<R>(transform: (T)-> Option<R>): Iterator<R>

功能:同时进行筛选操作和映射操作,返回一个新的迭代器。

参数:

  • transform: (T) -> Option<T> - 给定的映射函数。函数返回值为 Some 对应 filter 的 predicate 为 true,反之表示 false。

返回值:

  • Iterator<R> - 返回一个新迭代器。

func first()

public func first(): Option<T>

功能:获取当前迭代器的头部元素。

返回值:

  • Option<T> - 返回头部元素,若为空则返回 None。

func flatMap<R>((T) -> Iterator<R>)

public func flatMap<R>(transform: (T)-> Iterator<R>): Iterator<R>

功能:创建一个带 flatten 功能的映射。

参数:

  • transform: (T) -> Iterable<R> - 给定的映射函数。

返回值:

func fold<R>(R, (R, T) -> R)

public func fold<R>(initial: R, operation: (R, T)->R): R

功能:使用指定初始值,从左向右计算。

参数:

  • initial: R - 给定的 R 类型的初始值。
  • operation: (R, T) -> R - 给定的计算函数。

返回值:

  • R - 返回最终计算得到的值。

func forEach((T) -> Unit)

public func forEach(action: (T)-> Unit): Unit

功能:遍历当前迭代器所有元素,对每个元素执行给定的操作。

参数:

  • action: (T) -> Unit - 给定的操作函数。

func inspect((T) -> Unit)

public func inspect(action: (T) -> Unit): Iterator<T>

功能:迭代器每次调用 next() 对当前元素执行额外操作(不会消耗迭代器中元素)。

参数:

  • action: (T) -> Unit - 给定的操作函数。

返回值:

  • Iterator<T> - 返回一个新迭代器。

func isEmpty()

public func isEmpty(): Bool

功能:判断当前迭代器是否为空。

返回值:

  • Bool - 返回当前迭代器是否为空。

func last()

public func last(): Option<T>

功能:获取当前迭代器尾部元素。

返回值:

  • Option<T> - 返回尾部元素,若为空则返回 None。

func map<R>((T) -> R)

public func map<R>(transform: (T)-> R): Iterator<R>

功能:创建一个映射。

参数:

  • transform: (T) ->R - 给定的映射函数。

返回值:

func none((T) -> Bool)

public func none(predicate: (T)-> Bool): Bool

功能:判断当前迭代器中所有元素是否都不满足条件。

参数:

  • predicate: (T) -> Bool - 给定的条件。

返回值:

  • Bool - 当前迭代器中元素是否都不满足条件。

func reduce((T, T) -> T)

public func reduce(operation: (T, T) -> T): Option<T>

功能:使用第一个元素作为初始值,从左向右计算。

参数:

  • operation: (T, T) -> T - 给定的计算函数。

返回值:

  • Option<T> - 返回计算结果。

func skip(Int64)

public func skip(count: Int64): Iterator<T>

功能:从前往后从当前迭代器跳过特定个数。

当 count 小于 0 时,抛异常。当 count 等于 0 时,相当没有跳过任何元素,返回原迭代器。当 count 大于0并且count小于迭代器的大小时,跳过 count 个元素后,返回含有剩下的元素的新迭代器。当 count 大于等于迭代器的大小时,跳过所有元素,返回空迭代器。

参数:

  • count: Int64 - 要跳过的个数。

返回值:

  • Iterator<T> - 返回一个跳过指定数量元素的迭代器。

异常:

func step(Int64)

public func step(count: Int64): Iterator<T>

功能:迭代器每次调用 next() 跳过特定个数。

当 count 小于等于 0 时,抛异常。当 count 大于 0 时,每次调用 next() 跳过 count 次,直到迭代器为空。

参数:

  • count: Int64 - 每次调用 next() 要跳过的个数。

返回值:

  • Iterator<T> - 返回一个新迭代器,这个迭代器每次调用 next() 会跳过特定个数。

异常:

func take(Int64)

public func take(count: Int64): Iterator<T>

功能:从当前迭代器取出特定个数。

从后往前取出当前迭代器特定个数的元素。当 count 小于 0 时,抛异常。当 count 等于 0 时,不取元素,返回空迭代器。当 count 大于 0 小于迭代器的大小时,取前 count 个元素,返回新迭代器。当 count 大于等于迭代器的大小时,取所有元素,返回原迭代器。

参数:

  • count: Int64 - 要取出的个数。

返回值:

  • Iterator<T> - 返回一个取出指定数量元素的迭代器。

异常:

func zip<R>(Iterator<R>)

public func zip<R>(it: Iterator<R>): Iterator<(T, R)>

功能:将两个迭代器合并成一个(长度取决于短的那个迭代器)。

参数:

  • it: Iterable<R> - 要合并的其中一个迭代器。

返回值:

  • Iterator <(T, R)> - 返回一个新迭代器。

extend<T> Iterator<T> where T <: Comparable<T>

extend<T> Iterator<T> where T <: Comparable<T>

功能:为 Iterator<T> 类型扩展 Comparable<T> 接口,支持比较操作。

func max()

public func max(): Option<T>

功能:筛选最大的元素。

返回值:

  • Option<T> - 返回最大的元素,若为空则返回 None。

func min()

public func min(): Option<T>

功能:筛选最小的元素。

返回值:

  • Option<T> - 返回最小的元素,若为空则返回 None。

extend<T> Iterator<T> where T <: Equatable<T>

extend<T> Iterator<T> where T <: Equatable<T>

功能:为 Iterator<T> 类型扩展 扩展 Equatable<T> 接口,支持判等操作。

func contains(T)

public func contains(element: T): Bool

功能:遍历所有元素,判断是否包含指定元素。

参数:

  • element: T - 要查找的元素。

返回值:

  • Bool - 是否包含指定元素。

class Object

public open class Object <: Any {
    public const init()
}

Object 是所有 class 的父类,所有 class 都默认继承它。Object 类中不包含任何成员,即 Object 是一个“空”的类。

父类型:

init()

public const init()

功能:构造一个 object 实例。

class RangeIterator<T> <: Iterator<T> where T <: Countable<T> & Comparable<T> & Equatable<T>

public class RangeIterator<T> <: Iterator<T> where T <: Countable<T> & Comparable<T> & Equatable<T>

功能:Range 类型的迭代器,迭代功能详述见 IterableIterator 接口说明。

父类型:

func iterator()

public func iterator(): Iterator<T>

功能:获取当前迭代器实例。

返回值:

  • Iterator<T> - 当前迭代器实例。

func next()

public func next(): Option<T>

功能:获取 Range 迭代器中的下一个值。

返回值:Range 迭代器中的下一个成员,用 Option 封装,迭代到末尾时返回 None

class StackTraceElement

public open class StackTraceElement {
    public let declaringClass: String
    public let methodName: String
    public let fileName: String
    public let lineNumber: Int64
    public init(declaringClass: String, methodName: String, fileName: String, lineNumber: Int64)
}

功能:表示一个异常堆栈的具体信息,包括异常发生的类名、函数名、文件名、行号。

let declaringClass

public let declaringClass: String

功能:获取异常发生的类名。

类型:String

let fileName

public let fileName: String

功能:获取异常发生的文件名。

类型:String

let lineNumber

public let lineNumber: Int64

功能:获取异常发生的行号。

类型:Int64

let methodName

public let methodName: String

功能:获取异常发生的函数名。

类型:String

init(String, String, String, Int64)

public init(declaringClass: String, methodName: String, fileName: String, lineNumber: Int64)

功能:构造一个异常堆栈实例,指定类名、函数名、文件名、行号。

参数:

  • declaringClass: String - 类名。
  • methodName: String - 函数名。
  • fileName: String - 文件名。
  • lineNumber: Int64 - 行号。

class StringBuilder

public class StringBuilder <: ToString {
    public init()
    public init(str: String)
    public init(r: Rune, n: Int64)
    public init(value: Array<Rune>)
    public init(capacity: Int64)
}

功能:该类主要用于字符串的构建。

StringBuilder 在字符串的构建上效率高于 String

  • 在功能上支持传入多个类型的值,该类将自动将其转换为 String 类型对象,并追加到构造的字符串中。
  • 在性能上使用动态扩容算法,减少内存申请频率,构造字符串的速度更快,占用内存资源通常更少。

注意:

StringBuilder 仅支持 UTF-8 编码的字符数据。

父类型:

prop capacity

public prop capacity: Int64

功能:获取 StringBuilder 实例此时能容纳字符串的长度,该值会随扩容的发生而变大。

类型:Int64

prop size

public prop size: Int64

功能:获取 StringBuilder 实例中字符串长度。

类型:Int64

init()

public init()

功能:构造一个初始容量为 32 的空 StringBuilder 实例。

init(Array<Rune>)

public init(value: Array<Rune>)

功能:使用参数 value 指定的字符数组初始化一个 StringBuilder 实例,该实例的初始容量为 value 大小,初始内容为 value 包含的字符内容。

参数:

init(Int64)

public init(capacity: Int64)

功能:使用参数 capacity 指定的容量初始化一个空 StringBuilder 实例,该实例的初始容量为 value 大小,初始内容为若干 \0 字符。

参数:

异常:

init(Rune, Int64)

public init(r: Rune, n: Int64)

功能:使用 nr 字符初始化 StringBuilder 实例,该实例的初始容量为 n,初始内容为 nr 字符。

参数:

异常:

init(String)

public init(str: String)

功能:根据指定初始字符串构造 StringBuilder 实例,该实例的初始容量为指定字符串的大小,初始内容为指定字符串。

参数:

func append(Array<Rune>)

public func append(runeArr: Array<Rune>): Unit

功能:在 StringBuilder 末尾插入一个 Rune 数组中所有字符。

参数:

  • runeArr: Array<Rune> - 插入的 Rune 数组。

func append<T>(Array<T>) where T <: ToString

public func append<T>(val: Array<T>): Unit where T <: ToString

功能:在 StringBuilder 末尾插入参数 val 指定的 Array<T> 的字符串表示,类型 T 需要实现 ToString 接口。

参数:

  • val: Array<T> - 插入的 Array<T> 类型实例。

func append(Bool)

public func append(b: Bool): Unit

功能:在 StringBuilder 末尾插入参数 b 的字符串表示。

参数:

  • b: Bool - 插入的 Bool 类型的值。

func append(CString)

public func append(cstr: CString): Unit

功能:在 StringBuilder 末尾插入参数 cstr 指定 CString 中的内容。

参数:

func append(Float16)

public func append(n: Float16): Unit

功能:在 StringBuilder 末尾插入参数 n 的字符串表示。

参数:

func append(Float32)

public func append(n: Float32): Unit

功能:在 StringBuilder 末尾插入参数 n 的字符串表示。

参数:

func append(Float64)

public func append(n: Float64): Unit

功能:在 StringBuilder 末尾插入参数 n 的字符串表示。

参数:

func append(Int16)

public func append(n: Int16): Unit

功能:在 StringBuilder 末尾插入参数 n 的字符串表示。

参数:

func append(Int32)

public func append(n: Int32): Unit

功能:在 StringBuilder 末尾插入参数 n 的字符串表示。

参数:

func append(Int64)

public func append(n: Int64): Unit

功能:在 StringBuilder 末尾插入参数 n 的字符串表示。

参数:

func append(Int8)

public func append(n: Int8): Unit

功能:在 StringBuilder 末尾插入参数 n 的字符串表示。

参数:

  • n: Int8 - 插入的 Int8 类型的值。

func append(Rune)

public func append(r: Rune): Unit

功能:在 StringBuilder 末尾插入参数 r 指定的字符。

参数:

  • r: Rune - 插入的字符。

func append(String)

public func append(str: String): Unit

功能:在 StringBuilder 末尾插入参数 str 指定的字符串。

参数:

  • str: String - 插入的字符串。

func append(StringBuilder)

public func append(sb: StringBuilder): Unit

功能:在 StringBuilder 末尾插入参数 sb 指定的 StringBuilder 中的内容。

参数:

func append<T>(T) where T <: ToString

public func append<T>(v: T): Unit where T <: ToString

功能:在 StringBuilder 末尾插入参数 v 指定 T 类型的字符串表示,类型 T 需要实现 ToString 接口。

参数:

  • v: T - 插入的 T 类型实例。

func append(UInt16)

public func append(n: UInt16): Unit

功能:在 StringBuilder 末尾插入参数 n 的字符串表示。

参数:

func append(UInt32)

public func append(n: UInt32): Unit

功能:在 StringBuilder 末尾插入参数 n 的字符串表示。

参数:

func append(UInt64)

public func append(n: UInt64): Unit

功能:在 StringBuilder 末尾插入参数 n 的字符串表示。

参数:

func append(UInt8)

public func append(n: UInt8): Unit

功能:在 StringBuilder 末尾插入参数 n 的字符串表示。

参数:

func appendFromUtf8(Array<Byte>)

public func appendFromUtf8(arr: Array<Byte>): Unit

功能:在 StringBuilder 末尾插入参数 arr 指向的字节数组。

该函数要求参数 arr 符合 UTF-8 编码,如果不符合,将抛出异常。

参数:

  • arr: Array<Byte> - 插入的字节数组。

异常:

func appendFromUtf8Unchecked(Array<Byte>)

public unsafe func appendFromUtf8Unchecked(arr: Array<Byte>): Unit

功能:在 StringBuilder 末尾插入参数 arr 指向的字节数组。

相较于 appendFromUtf8 函数,它并没有针对于字节数组进行 UTF-8 相关规则的检查,所以它所构建的字符串并不一定保证是合法的,甚至出现非预期的异常,如果不是某些场景下的速度考虑,请优先使用安全的 appendFromUtf8 函数。

参数:

  • arr: Array<Byte> - 插入的字节数组。

func reserve(Int64)

public func reserve(additional: Int64): Unit

功能:将 StringBuilder 扩容 additional 大小。

additional 小于等于零,或剩余容量大于等于 additional 时,不发生扩容;当剩余容量小于 additional 时,扩容至当前容量的 1.5 倍(向下取整)与 size + additional 的最大值。

参数:

func reset(?Int64)

public func reset(capacity!: Option<Int64> = None): Unit

功能:清空当前 StringBuilder,并将容量重置为 capacity 指定的值。

参数:

  • capacity!: Option<Int64> - 重置后 StringBuilder 实例的容量大小,取值范围为 None 和 (Some(0), Some(Int64.Max)],默认值 None 表示采用默认大小容量(32)。

异常:

func toString()

public func toString(): String

功能:获取 StringBuilder 实例中的字符串。

注意:

该函数不会将字符串数据进行拷贝。

返回值:

class Thread

public class Thread

功能:Thread 类代表一个仓颉类,可用于获取线程 ID 及名字、查询线程是否存在取消请求、注册线程未处理异常的处理函数等。

该类型实例无法通过构造得到,仅能通过 Future 对象的 thread 属性或是 Thread 类的 currentThread 静态属性获取。

static prop currentThread

public static prop currentThread: Thread

功能:获取当前执行线程的 Thread 对象。

类型:Thread

prop hasPendingCancellation

public prop hasPendingCancellation: Bool

功能:线程是否存在取消请求,即是否通过 future.cancel() 发送过取消请求,常见使用方为 Thread.currentThread.hasPendingCancellation。

类型:Bool

prop id

public prop id: Int64

功能:获取当前执行线程的标识,以 Int64 表示,所有存活的线程都有不同标识,但不保证当线程执行结束后复用它的标识。

类型:Int64

prop name

public mut prop name: String

功能:获取或设置线程的名称,获取设置都具有原子性。

类型:String

static func handleUncaughtExceptionBy((Thread, Exception) -> Unit)

public static func handleUncaughtExceptionBy(exHandler: (Thread, Exception) -> Unit): Unit

功能:注册线程未处理异常的处理函数。

当某一线程因异常而提前终止后,如果全局的未处理异常函数被注册,那么将调用该函数并结束线程,在该函数内抛出异常时,将向终端打印提示信息并结束线程,但不会打印异常调用栈信息;如果没有注册全局异常处理函数,那么默认会向终端打印异常调用栈信息。

多次注册处理函数时,后续的注册函数将覆盖之前的处理函数。

当有多个线程同时因异常而终止时,处理函数将被并发执行,因而开发者需要在处理函数中确保并发正确性。

处理函数的参数第一个参数类型为 Thread,是发生异常的线程,第二个参数类型为 Exception,是线程未处理的异常。

参数:

class ThreadLocal<T>

public class ThreadLocal<T>

功能:该类表示仓颉线程局部变量。

和普通变量相比,线程局部变量有不同的访问语义。当多个线程共享使用同一线程局部变量时,每个线程都有各自的一份值拷贝。线程对变量的访问会读写线程本地的值,而不会影响其他线程中变量的值。

func get()

public func get(): ?T

功能:获得仓颉线程局部变量的值。

返回值:

  • ?T - 如果当前线程局部变量不为空值,返回该值,如果为空值,返回 None

func set(?T)

public func set(value: ?T): Unit

功能:通过 value 设置仓颉线程局部变量的值,如果传入 None,该局部变量的值将被删除,在线程后续操作中将无法获取。

参数:

  • value: ?T - 需要设置的局部变量的值。

枚举

enum AnnotationKind

public enum AnnotationKind {
    | Init
    | MemberFunction
    | MemberProperty
    | MemberVariable
    | Parameter
    | Type
}

功能:表示自定义注解希望支持的位置。

Init

Init

功能:构造函数声明。

MemberFunction

MemberFunction

功能:成员函数声明。

MemberProperty

MemberProperty

功能:成员属性声明。

MemberVariable

MemberVariable

功能:成员变量声明。

Parameter

Parameter

功能:成员函数/构造函数中的参数。

Type

Type

功能:类型声明(class、struct、enum、interface)。

enum Endian

public enum Endian {
    | Big
    | Little
}

功能:枚举类型 Endian 表示运行平台的端序,分为大端序和小端序。

Big

Big

功能:表示大端序。

Little

Little

功能:表示小端序。

static prop Platform

public static prop Platform: Endian

功能:获取所在运行平台的端序。

类型:Endian

异常:

示例:

main() {
    let e = Endian.Platform
    match (e) {
        case Big => println("BigEndian")
        case Little => println("LittleEndian")
    }
}

enum Option<T>

public enum Option<T> {
    | Some(T)
    | None
}

功能:Option<T> 是对 T 类型的封装,表示可能有值也可能无值。

它包含两个构造器:SomeNone。其中,Some 会携带一个参数,表示有值,None 不带参数,表示无值。当需要表示某个类型可能有值,也可能没有值的时候,可选择使用 Option 类型。

Option 类型的另一种写法是在类型名前加 ?,即对于任意类型 Type?Type 等价于 Option<Type>。

None

None

功能:构造一个不带参数的 Option<T> 实例,表示无值。

Some(T)

Some(T)

功能:构造一个携带参数的 Option<T> 实例,表示有值。

func filter((T)->Bool)

public func filter(predicate: (T) -> Bool): Option<T>

功能:提供 Option 类型的 '过滤' 功能。

参数:

  • predicate: (T) -> Bool - 过滤函数。

返回值:

  • Option<T> - 如果 Option 值是 Some(v),并且 v 满足 predicate(v) = true 时,返回 Some(v), 否则返回 None

func flatMap<R>((T) -> Option<R>)

public func flatMap<R>(transform: (T) -> Option<R>): Option<R>

功能:提供从 Option<T> 类型到 Option<R> 类型的映射函数,如果当前实例值是 Some,执行 transform 函数,并且返回结果,否则返回 None

参数:

  • transform: (T) -> Option<R> - 映射函数。

返回值:

  • Option<R> - 如果当前实例值是 Some,执行 transform 函数并返回,否则返回 None

func getOrDefault(() -> T)

public func getOrDefault(other: () -> T): T

功能:获得值或返回默认值。如果 Option 值是 Some,则返回类型为 T 的实例,如果 Option 值是 None,则调用入参,返回类型 T 的值。

参数:

  • other: () -> T - 默认函数,如果当前实例的值是 None,调用该函数得到类型为 T 的实例,并将其返回。

返回值:

  • T - 如果当前实例的值是 Some<T>,则返回当前实例携带的类型为 T 的实例,如果 Option 值是 None,调用入参指定的函数,得到类型为 T 的实例,并将其返回。

func getOrThrow(() -> Exception)

public func getOrThrow(exception: ()->Exception): T

功能:获得值或抛出指定异常。

参数:

  • exception: () ->Exception - 异常函数,如果当前实例值是 None,将执行该函数并将其返回值作为异常抛出。

返回值:

  • T - 如果当前实例值是 Some<T>,返回类型为 T 的实例。

异常:

  • Exception - 如果当前实例是 None,抛出异常函数返回的异常。

func getOrThrow()

public func getOrThrow(): T

功能:获得值或抛出异常。

返回值:

  • T - 如果当前实例值是 Some<T>,返回类型为 T 的实例。

异常:

func isNone()

public func isNone(): Bool

功能:判断当前实例值是否为 None

返回值:

  • Bool - 如果当前实例值是 None,则返回 true,否则返回 false。

func isSome()

public func isSome(): Bool

功能:判断当前实例值是否为 Some

返回值:

  • Bool - 如果当前实例值是 Some,则返回 true,否则返回 false。

func map<R>((T)->R)

public func map<R>(transform: (T)-> R): Option<R>

功能:提供从 Option<T> 类型到 Option<R> 类型的映射函数,如果当前实例值是 Some,执行 transform 函数,并且返回 Some 封装的结果,否则返回 None

参数:

  • transform: (T)-> R - 映射函数。

返回值:

  • Option<R> - 如果当前实例值是 Some,执行 transform 函数,并且返回 Option 类型的结果,否则返回 None

extend<T> Option<T> <: Equatable<Option<T>> where T <: Equatable<T>

extend<T> Option<T> <: Equatable<Option<T>> where T <: Equatable<T>

功能:为 Option<T> 枚举扩展 Equatable<Option<T>> 接口,支持判等操作。

父类型:

operator func !=(?T)

public operator func !=(that: Option<T>): Bool

功能:判断当前实例与参数指向的 Option<T> 实例是否不等。

参数:

返回值:

  • Bool - 如果不相等,则返回 true,否则返回 false。

operator func ==(?T)

public operator func ==(that: Option<T>): Bool

功能:判断当前实例与参数指向的 Option<T> 实例是否相等。

如果两者同为 None,则相等;如果两者为 Some(v1) 和 Some(v2),且 v1 和 v2 相等,则相等。

参数:

返回值:

  • Bool - 如果相等,则返回 true,否则返回 false。

extend<T> Option<T> <: Hashable where T <: Hashable

extend<T> Option<T> <: Hashable where T <: Hashable

功能:为 Option 类型扩展 Hashable 接口。

Some<T> 的哈希值等于 T 的值对应的哈希值,None 的哈希值等于 Int64(0)。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值。

返回值:

extend<T> Option<T> <: ToString where T <: ToString

extend<T> Option<T> <: ToString where T <: ToString

功能:为 Option<T> 枚举实现 ToString 接口,支持转字符串操作。

父类型:

func toString()

public func toString(): String

功能:将 Option 转换为可输出的字符串,字符串内容为 "Some(${T.toString()})" 或 "None"。

返回值:

  • String - 转化后的字符串。

extend<T> Option<Option<T>>

extend<T> Option<Option<T>>

功能:为 Option<Option<T>> 类型扩展实现某些功能。

func flatten()

public func flatten(): Option<T>

功能:将 Option <Option <T>> 类型展开,如果当前实例是 Some(Option <T>.Some(v)), 展开后的结果为 Some(v)。

返回值:

enum Ordering

public enum Ordering {
    | LT
    | GT
    | EQ
}

功能:Ordering 表示比较大小的结果,它包含三种情况:小于,大于和等于。

EQ

EQ

功能:构造一个 Ordering 实例,表示等于。

GT

GT

功能:构造一个 Ordering 实例,表示大于。

LT

LT

功能:构造一个 Ordering 实例,表示小于。

extend Ordering <: Comparable

extend Ordering <: Comparable<Ordering>

功能:为 Ordering 类型其扩展 Comparable<Ordering> 接口,支持比较操作。

父类型:

func compare(Ordering)

public func compare(that: Ordering): Ordering

功能:判断当前 Ordering 实例与参数指定的 Ordering 实例的大小关系。

Ordering 枚举的大小关系为:GT > EQ > LT。

参数:

返回值:

  • Ordering - 如果大于,返回 GT,如果等于,返回 EQ,如果小于,返回 LT。

operator func !=(Ordering)

public operator func !=(that: Ordering): Bool

功能:判断两个 Ordering 实例是否不相等。

参数:

返回值:

  • Bool - 如果不相等,则返回 true,否则返回 false。

operator func <(Ordering)

public operator func <(that: Ordering): Bool

功能:判断当前 Ordering 实例是否小于参数指向的 Ordering 实例。

参数:

返回值:

  • Bool - 如果当前 Ordering 实例小于参数指向的 Ordering 实例,则返回 true,否则返回 false。

operator func <=(Ordering)

public operator func <=(that: Ordering): Bool

功能:判断当前 Ordering 实例是否小于等于参数指向的 Ordering 实例。

参数:

返回值:

  • Bool - 如果当前 Ordering 实例小于等于参数指向的 Ordering 实例,则返回 true,否则返回 false。

operator func ==(Ordering)

public operator func ==(that: Ordering): Bool

功能:判断两个 Ordering 实例是否相等。

参数:

返回值:

  • Bool - 如果相等,则返回 true,否则返回 false。

operator func >(Ordering)

public operator func >(that: Ordering): Bool

功能:判断当前 Ordering 实例是否大于参数指向的 Ordering 实例。

参数:

返回值:

  • Bool - 如果当前 Ordering 实例大于参数指向的 Ordering 实例,则返回 true,否则返回 false。

operator func >=(Ordering)

public operator func >=(that: Ordering): Bool

功能:判断当前 Ordering 实例是否大于等于参数指向的 Ordering 实例。

参数:

返回值:

  • Bool - 如果当前 Ordering 实例大于等于参数指向的 Ordering 实例,则返回 true,否则返回 false。

extend Ordering <: Hashable

extend Ordering <: Hashable

功能:为 Ordering 类型其扩展 Hashable 接口。

父类型:

func hashCode

public func hashCode(): Int64

功能:获取哈希值,GT 的哈希值是 3,EQ 的哈希值是 2,LT 的哈希值是 1。

返回值:

extend Ordering <: ToString

extend Ordering <: ToString

功能:为 Ordering 类型其扩展 ToString 接口,支持转字符串操作。

父类型:

func toString()

public func toString(): String

功能:将 Ordering 转换为可输出的字符串。

转换结果如下:

返回值:

  • String - 转化后的字符串。

结构体

struct Array<T>

public struct Array<T> {
    public const init()
    public init(size: Int64, repeat!: T)
    public init(size: Int64, initElement: (Int64) -> T)
}

功能:仓颉数组类型,用来表示单一类型的元素构成的有序序列。

T 表示数组的元素类型,T 可以是任意类型。

prop first

public prop first: ?T

功能:获取当前数组的第一个元素,如果当前数组为空,返回 None。

类型:?T

prop last

public prop last: ?T

功能:获取当前数组的最后一个元素,如果当前数组为空,返回 None。

类型:?T

init()

public const init()

功能:构造一个空数组。

init(Int64, (Int64) -> T)

public init(size: Int64, initElement: (Int64) -> T)

功能:创建指定长度的数组,其中元素根据初始化函数计算获取。

即:将 [0, size) 范围内的值分别传入初始化函数 initElement,执行得到数组对应下标的元素。

参数:

  • size: Int64 - 数组大小。
  • initElement: (Int64) ->T - 初始化函数。

异常:

init(Int64, T)

public init(size: Int64, repeat!: T)

功能:构造一个指定长度的数组,其中元素都用指定初始值进行初始化。

注意:

该构造函数不会拷贝 repeat, 如果 repeat 是一个引用类型,构造后数组的每一个元素都将指向相同的引用。

参数:

  • size: Int64 - 数组大小,取值范围为 [0, Int64.Max]。
  • repeat!: T - 数组元素初始值。

异常:

func clone()

public func clone(): Array<T>

功能:克隆数组,将对数组数据进行深拷贝。

返回值:

  • Array<T> - 克隆得到的新数组。

func clone(Range<Int64>)

public func clone(range: Range<Int64>) : Array<T>

功能:克隆数组的指定区间。

注意:

  1. 如果参数 range 是使用 Range 构造函数构造的 Range 实例,有如下行为:
    • start 的值就是构造函数传入的值本身,不受构造时传入的 hasStart 的值的影响。
    • hasEnd 为 false 时,end 值不生效,且不受构造时传入的 isClosed 的值的影响,数组切片取到原数组最后一个元素。
  2. range 的步长只能为 1。

参数:

返回值:

  • Array<T> - 克隆得到的新数组。

异常:

示例:

main() {
    let arr = [0, 1, 2, 3, 4, 5]
    let new = arr.clone(1..4)
    println(new)
}

运行结果:

[1, 2, 3]

func concat(Array<T>)

public func concat(other: Array<T>): Array<T>

功能:该函数将创建一个新的数组,数组内容是当前数组后面串联 other 指向的数组。

参数:

  • other: Array<T> - 串联到当前数组末尾的数组。

返回值:

  • Array<T> - 串联得到的新数组。

示例:

main() {
    let arr = [0, 1, 2, 3, 4, 5]
    let new = arr.concat([6, 7, 8, 9, 10])
    println(new)
}

运行结果:

[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

func copyTo(Array<T>)

public func copyTo(dst: Array<T>): Unit

功能:将当前数组的全部元素拷贝到目标数组 dst 中。

拷贝长度为当前数组的长度,从目标数组的起始位置开始写入,要求当前数组的长度不大于目标数组的长度。

参数:

  • dst: Array<T> - 目标数组。

异常:

func copyTo(Array<T>, Int64, Int64, Int64)

public func copyTo(dst: Array<T>, srcStart: Int64, dstStart: Int64, copyLen: Int64): Unit

功能:将当前数组中的一段数据拷贝到目标数组中。

参数:

  • dst: Array<T> - 目标数组。
  • srcStart: Int64 - 从 this 数组的 srcStart 下标开始拷贝,取值范围为 [0, this.size)。
  • dstStart: Int64 - 从目标数组的 dstStart 下标开始写入,取值范围为 [0, dst.size)。
  • copyLen: Int64 - 拷贝数组的长度,取值要求为 copyLen + srcStart < this.size,copyLen + dstStart < dst.size。

异常:

示例:

main() {
    let arr = [0, 1, 2, 3, 4, 5]
    let new = [0, 0, 0, 0, 0, 0]
    arr.copyTo(new, 2, 2, 4)
    println(new)
}

运行结果:

[0, 0, 2, 3, 4, 5]

func fill(T)

public func fill(value: T): Unit

功能:将当前数组内所有元素都替换成指定的 value。

参数:

  • value: T - 修改的目标值。

示例:

main() {
    let arr = [0, 1, 2]
    arr[1..3].fill(-1)
    println(arr)
}

运行结果:

[0, -1, -1]

func get(Int64)

public func get(index: Int64): Option<T>

功能:获取数组中下标 index 对应的元素。

该函数结果将用 Option 封装,如果 index 越界,将返回 None。

也可以通过 [] 操作符获取数组指定下标的元素,该接口将在 index 越界时抛出异常。

参数:

  • index: Int64 - 要获取的值的下标。

返回值:

  • Option<T> - 当前数组中下标 index 对应的值。

func map<R>((T)->R)

public func map<R>(transform: (T)->R): Array<R>

功能:将当前数组内所有 T 类型元素根据 transform 映射为 R 类型的元素,组成新的数组。

参数:

  • transform: (T)->R - 映射函数。

返回值:

  • Array<R> - 原数组中所有元素映射后得到的元素组成的新数组。

func repeat(Int64)

public func repeat(n: Int64): Array<T>

功能:重复当前数组若干次,得到新数组。

参数:

  • n: Int64 - 重复次数。

返回值:

  • Array<T> - 重复当前数组 n 次得到的新数组。

func reverse()

public func reverse(): Unit

功能:反转数组,将数组中元素的顺序进行反转。

示例:

main() {
    let arr = [0, 1, 2, 3, 4, 5]
    arr.reverse()
    println(arr)
}

运行结果:

[5, 4, 3, 2, 1, 0]

func slice(Int64, Int64)

public func slice(start: Int64, len: Int64): Array<T>

功能:获取数组切片。

注意:

切片不会对数组数据进行拷贝,是对原数据特定区间的引用。

参数:

  • start: Int64 - 切片的起始位置,取值需大于 0,且 start + len 小于等于当前 Array 实例的长度。
  • len: Int64 - 切片的长度,取值需大于 0。

返回值:

  • Array<T> - 返回切片后的数组。

异常:

func splitAt(Int64)

public func splitAt(mid: Int64): (Array<T>, Array<T>)

功能:从指定位置 mid 处分割数组。

得到的两个数组是原数组的切片,取值范围为 [0, mid), [mid, this.size)。

参数:

  • mid:Int64 - 分割的位置,取值范围为 [0, this.size]。

返回值:

  • (Array<T>, Array<T>) - 分割原数组得到的两个切片。

异常:

func swap(Int64, Int64)

public func swap(index1: Int64, index2: Int64): Unit

功能:交换指定位置的两个元素。

如果 index1 和 index2 指向同一个位置,将不做交换。

参数:

  • index1: Int64 - 需要交换的两个元素的下标之一,取值范围为 [0, this.size)。
  • index2: Int64 - 需要交换的两个元素的下标之一,取值范围为 [0, this.size)。

异常:

operator func [](Int64)

public operator func [](index: Int64): T

功能:获取数组下标 index 对应的值。

该函数中如果 index 越界,将抛出异常。

也可以通过 get 函数获取数组指定下标的元素,get 函数将在 index 越界时返回 None。

参数:

  • index: Int64 - 要获取的值的下标,取值范围为 [0, Int64.Max]。

返回值:

  • T - 数组中下标 index 对应的值。

异常:

operator func [](Int64, T)

public operator func [](index: Int64, value!: T): Unit

功能:修改数组中下标 index 对应的值。

参数:

  • index: Int64 - 需要修改值的下标,取值范围为 [0, Int64.Max]。
  • value!: T - 修改的目标值。

异常:

operator func [](Range<Int64>)

public operator func [](range: Range<Int64>): Array<T>

功能:根据给定区间获取数组切片。

注意:

  1. 如果参数 range 是使用 Range 构造函数构造的 Range 实例,有如下行为:
    • start 的值就是构造函数传入的值本身,不受构造时传入的 hasStart 的值的影响。
    • hasEnd 为 false 时,end 值不生效,且不受构造时传入的 isClosed 的值的影响,该数组切片取到原数组最后一个元素。
  2. range 的步长只能为 1。

参数:

  • range: Range<Int64> - 切片的范围,range 表示的范围不能超过数组范围。

返回值:

  • Array<T> - 数组切片。

异常:

示例:

main() {
    let arr = [0, 1, 2, 3, 4, 5]
    let slice = arr[1..4]
    arr[3] = 10
    println(slice)
}

运行结果:

[1, 2, 10]

operator func [](Range<Int64>, Array<T>)

public operator func [](range: Range<Int64>, value!: Array<T>): Unit

功能:用指定的数组对本数组一个连续范围的元素赋值。

range 表示的区见的长度和目标数组 value 的大小需相等。

注意:

  1. 如果参数 range 是使用 Range 构造函数构造的 Range 实例,有如下行为:
    • start 的值就是构造函数传入的值本身,不受构造时传入的 hasStart 的值的影响。
    • hasEnd 为 false 时,end 值不生效,且不受构造时传入的 isClosed 的值的影响,该数组切片取到原数组最后一个元素。
  2. range 的步长只能为 1。

参数:

  • range: Range<Int64> - 需要修改的数组范围,range 表示的范围不能超过数组范围。
  • value!: Array<T> - 修改的目标值。

异常:

示例:

main() {
    let arr = [0, 1, 2, 3, 4, 5]
    arr[1..3] = [10, 11]
    println(arr)
}

运行结果:

[0, 10, 11, 3, 4, 5]

extend<T> Array<T> <: Collection<T>

extend<T> Array<T> <: Collection<T>

父类型:

prop size

public prop size: Int64

功能:获取元素数量。

类型:Int64

func isEmpty()

public func isEmpty(): Bool

功能:判断数组是否为空。

返回值:

  • Bool - 如果数组为空,返回 true,否则,返回 false。

func iterator()

public func iterator(): Iterator<T>

功能:获取当前数组的迭代器,用于遍历数组。

返回值:

  • Iterator<T> - 当前数组的迭代器。

func toArray()

public func toArray(): Array<T>

功能:根据当前 Array 实例拷贝一个新的 Array 实例。

返回值:

  • Array<T> - 拷贝得到的新的 Array 实例。

extend<T> Array<T> <: Equatable<Array<T>> where T <: Equatable<T>

extend<T> Array<T> <: Equatable<Array<T>> where T <: Equatable<T>

功能:为 Array<T> 类型扩展 Equatable<Array<T>> 接口实现,支持判等操作。

父类型:

func contains(T)

public func contains(element: T): Bool

功能:查找当前数组是否包含指定元素。

参数:

  • element: T - 需要查找的目标元素。

返回值:

  • Bool - 如果存在,则返回 true,否则返回 false。

func indexOf(Array<T>)

public func indexOf(elements: Array<T>): Option<Int64>

功能:返回数组中子数组 elements 出现的第一个位置,如果数组中不包含此数组,返回 None。

注意:

当 T 的类型是 Int64 时,此函数的变长参数语法糖版本可能会和 public func indexOf(element: T, fromIndex: Int64): Option<Int64> 产生歧义,根据优先级,当参数数量是 2 个时,会优先调用 public func indexOf(element: T, fromIndex: Int64): Option<Int64>

参数:

  • elements: Array<T> - 需要定位的目标数组。

返回值:

  • Option<Int64> - 数组中子数组 elements 出现的第一个位置,如果数组中不包含此数组,返回 None。

func indexOf(Array<T>, Int64)

public func indexOf(elements: Array<T>, fromIndex: Int64): Option<Int64>

功能:返回数组中在 fromIndex之后,子数组elements 出现的第一个位置,未找到返回 None。

函数会对 fromIndex 范围进行检查,fromIndex 小于 0 时,将会从第 0 位开始搜索,当 fromIndex 大于等于本数组的大小时,结果为 None。

参数:

  • elements: Array<T> - 需要定位的元素。
  • fromIndex: Int64 - 开始搜索的起始位置。

返回值:

  • Option<Int64> - 数组中在 fromIndex之后,子数组 elements 出现的第一个位置,未找到返回 None。

func indexOf(T)

public func indexOf(element: T): Option<Int64>

功能:获取数组中 element 出现的第一个位置,如果数组中不包含此元素,返回 None。

参数:

  • element: T - 需要定位的元素。

返回值:

  • Option<Int64> - 数组中 element 出现的第一个位置,如果数组中不包含此元素,返回 None。

func indexOf(T, Int64)

public func indexOf(element: T, fromIndex: Int64): Option<Int64>

功能:返回数组中在 fromIndex之后, element 出现的第一个位置,未找到返回 None。

函数会从下标 fromIndex 开始查找,fromIndex 小于 0 时,将会从第 0 位开始搜索,当 fromIndex 大于等于本数组的大小时,结果为 None。

参数:

  • element: T - 需要定位的元素。
  • fromIndex: Int64 - 查找的起始位置。

返回值:

  • Option<Int64> - 返回数组中在 fromIndex之后, element 出现的第一个位置,未找到返回 None。

func lastIndexOf(Array<T>)

public func lastIndexOf(elements: Array<T>): Option<Int64>

功能:返回数组中子数组 elements 出现的最后一个位置,如果数组中不存在此子数组,返回 None。

参数:

  • elements: Array<T> - 需要定位的目标数组。

返回值:

  • Option<Int64> - 数组中 elements 出现的最后一个位置,如果数组中不存在此子数组,返回 None。

func lastIndexOf(Array<T>, Int64)

public func lastIndexOf(elements: Array<T>, fromIndex: Int64): Option<Int64>

功能:从 fromIndex 开始向后搜索,返回数组中子数组 elements 出现的最后一个位置,如果数组中不存在此子数组,返回 None。

函数会对 fromIndex 范围进行检查,fromIndex 小于 0 时,将会从第 0 位开始搜索,当 fromIndex 大于等于本数组的大小时,结果为 None。

参数:

  • elements: Array<T> - 需要定位的目标数组。
  • fromIndex: Int64 - 搜索开始的位置。

返回值:

  • Option<Int64> - 从 fromIndex 开始向后搜索,数组中子数组 elements 出现的最后一个位置,如果数组中不存在此子数组,返回 None。

func lastIndexOf(T)

public func lastIndexOf(element: T): Option<Int64>

功能:返回数组中 element 出现的最后一个位置,如果数组中不存在此元素,返回 None。

参数:

  • element: T - 需要定位的目标元素。

返回值:

  • Option<Int64> - 数组中 element 出现的最后一个位置,如果数组中不存在此元素,返回 None

func lastIndexOf(T, Int64)

public func lastIndexOf(element: T, fromIndex: Int64): Option<Int64>

功能:从 fromIndex 开始向后搜索,返回数组中 element 出现的最后一个位置,如果数组中不存在此元素,返回 None。

函数会对 fromIndex 范围进行检查,fromIndex 小于 0 时,将会从第 0 位开始搜索,当 fromIndex 大于等于本数组的大小时,结果为 None。

参数:

  • element: T - 需要定位的目标元素。
  • fromIndex: Int64 - 搜索开始的位置。

返回值:

  • Option<Int64> - 从 fromIndex 开始向后搜索,返回数组中 element 出现的最后一个位置,如果数组中不存在此元素,返回 None。

func removePrefix(Array<T>)

public func removePrefix(prefix: Array<T>): Array<T>

功能:删除前缀。

如果当前数组开头与 prefix 完全匹配,删除其前缀。返回值为当前数组删除前缀后得到的切片。

例如 [1, 2, 1, 2, 3].removePrefix([1, 2]) = [1, 2, 3]。

参数:

  • prefix: Array<T> - 待删除的前缀。

返回值:

  • Array<T> - 删除前缀后得到的原数组切片。

func removeSuffix(Array<T>)

public func removeSuffix(suffix: Array<T>): Array<T>

功能:删除后缀。

如果当前数组结尾与 suffix 完全匹配,删除其后缀。返回值为当前数组删除后缀后得到的切片。

例如 [1, 2, 3, 2, 3].removeSuffix([2, 3]) = [1, 2, 3]。

参数:

  • suffix: Array<T> - 待删除的后缀。

返回值:

  • Array<T> - 删除后缀后得到的原数组切片。

func trimEnd(Array<T>)

public func trimEnd(set: Array<T>): Array<T>

功能:修剪当前数组,从尾开始删除在指定集合 set 中的元素,直到第一个不在 set 中的元素为止,并返回当前数组的切片。

例如 [2, 1, 2, 2, 3].trimEnd([2, 3]) = [2, 1]。

参数:

  • set: Array<T> - 待删除的元素的集合。

返回值:

  • Array<T> - 修剪后的数组切片。

func trimEnd((T)->Bool)

public func trimEnd(predicate: (T)->Bool): Array<T>

功能:修剪当前数组,从尾开始删除符合过滤条件的函数,直到第一个不符合的元素为止,并返回当前数组的切片。

参数:

  • predicate: (T)->Bool - 过滤条件。

返回值:

  • Array<T> - 修剪后的数组切片。

func trimStart(Array<T>)

public func trimStart(set: Array<T>): Array<T>

功能:修剪当前数组,从头开始删除在指定集合 set 中的元素,直到第一个不在 set 中的元素为止,并返回当前数组的切片。

例如 [1, 2, 1, 3, 1].trimStart([1, 2]) = [3, 1]。

参数:

  • set: Array<T> - 待删除的元素的集合。

返回值:

  • Array<T> - 修剪后的数组切片。

func trimStart((T)->Bool)

public func trimStart(predicate: (T)->Bool): Array<T>

功能:修剪当前数组,从头开始删除符合过滤条件的函数,直到第一个不符合的元素为止,并返回当前数组的切片。

参数:

  • predicate: (T)->Bool - 过滤条件。

返回值:

  • Array<T> - 修剪后的数组切片。

operator func !=(Array<T>)

public operator const func !=(that: Array<T>): Bool

功能:判断当前实例与指定 Array<T> 实例是否不等。

参数:

  • that: Array<T> - 用于与当前实例比较的另一个 Array<T> 实例。

返回值:

  • Bool - 如果不相等,则返回 true;相等则返回 false。

operator func ==(Array<T>)

public operator const func ==(that: Array<T>): Bool

功能:判断当前实例与指定 Array<T> 实例是否相等。

两个 Array<T> 相等指的是其中的每个元素都相等。

参数:

  • that: Array<T> - 用于与当前实例比较的另一个 Array<T> 实例。

返回值:

  • Bool - 如果相等,则返回 true,否则返回 false。

extend<T> Array<T> where T <: ToString

extend<T> Array<T> <: ToString where T <: ToString

功能:为 Array<T> 类型扩展 ToString 接口,支持转字符串操作。

父类型:

func toString()

public func toString(): String

功能:将数组转换为可输出的字符串。

字符串形如 "[1, 2, 3, 4, 5]"

返回值:

  • String - 转化后的字符串。

extend<T> Array<Array<T>>

extend<T> Array<Array<T>>

功能:为二维数组进行扩展,提供将其展开为一维数组的的方法。

func flatten()

public func flatten(): Array<T>

功能:将当前二维数组展开为一维数组。

例如将 [[1, 2], [3, 4]] 展开为 [1, 2, 3, 4]。

返回值:

  • Array<T> - 展开后的一维数组。

struct CPointerHandle<T> where T <: CType

public struct CPointerHandle<T> where T <: CType {
    public let array: Array<T>
    public let pointer: CPointer<T>
    public init()
    public init(ptr: CPointer<T>, arr: Array<T>)
}

功能:表示 Array 数组的原始指针,该类型中的泛型参数应该满足 CType 约束。

let array

public let array: Array<T>

功能:原始指针对应的 Array 数组实例。

类型:Array<T>

let pointer

public let pointer: CPointer<T>

功能:获取指定 Array 数组对应的原始指针。

类型:CPointer<T>

init()

public init()

功能:构造一个默认 CPointerHandle 实例,其中原始指针为空指针,仓颉数组为空数组。

init(CPointer<T>, Array<T>)

public init(ptr: CPointer<T>, arr: Array<T>)

功能:通过传入的 CPointerArray 初始化一个 CPointerHandle

参数:

  • ptr: CPointer<T> - 数组原始指针。
  • arr: Array<T> - 指针对应的仓颉数组。

struct CPointerResource<T> where T <: CType

public struct CPointerResource<T> <: Resource where T <: CType {
    public let value: CPointer<T>
}

功能:该结构体表示 CPointer 对应的资源管理类型,其实例可以通过 CPointer 的成员函数 asResource 获取。

父类型:

let value

public let value: CPointer<T>

功能:表示当前实例管理的 CPointer<T> 类型实例。

类型:CPointer<T>

func close()

public func close(): Unit

功能:释放其管理的 CPointer<T> 实例指向的内容。

func isClosed()

public func isClosed(): Bool

功能:判断该指针内容是否已被释放。

返回值:

  • Bool - 返回 true 为已释放。

struct CStringResource

public struct CStringResource <: Resource {
    public let value: CString
}

功能:该结构体表示 CString 对应的资源管理类型,其实例可以通过 CString 的成员函数 asResource 获取。

父类型:

let value

public let value: CString

功能:表示当前实例管理的 CString 资源。

类型:CString

func close()

public func close(): Unit

功能:释放当前实例管理的 CString 类型实例指向的内容。

func isClosed()

public func isClosed(): Bool

功能:判断该字符串是否被释放。

返回值:

  • Bool - 返回 true 为已释放。

struct DefaultHasher

public struct DefaultHasher <: Hasher {
 public init(res!: Int64 = 0)
}

功能:该结构体提供了默认哈希算法实现。

可以使用一系列 write 函数传入不同数据类型实例,并计算他们的组合哈希值。

父类型:

init(Int64)

public init(res!: Int64 = 0)

功能:构造函数,创建一个 DefaultHasher

参数:

  • res!: Int64 - 初始哈希值,默认为 0。

func finish()

public func finish(): Int64

功能:获取哈希运算的结果。

返回值:

  • Int64 - 哈希运算的结果。

func reset()

public mut func reset(): Unit

功能:重置哈希值为 0。

func write(Bool)

public mut func write(value: Bool): Unit

功能:通过该函数把想要哈希运算的 Bool 值传入,然后进行哈希组合运算。

参数:

  • value: Bool - 待运算的值。

func write(Float16)

public mut func write(value: Float16): Unit

功能:通过该函数把想要哈希运算的 Float16 值传入,然后进行哈希组合运算。

参数:

  • value: Float16 - 待运算的值。

func write(Float32)

public mut func write(value: Float32): Unit

功能:通过该函数把想要哈希运算的 Float32 值传入,然后进行哈希组合运算。

参数:

  • value: Float32 - 待运算的值。

func write(Float64)

public mut func write(value: Float64): Unit

功能:通过该函数把想要哈希运算的 Float64 值传入,然后进行哈希组合运算。

参数:

  • value: Float64 - 待运算的值。

func write(Int16)

public mut func write(value: Int16): Unit

功能:通过该函数把想要哈希运算的 Int16 值传入,然后进行哈希组合运算。

参数:

  • value: Int16 - 待运算的值。

func write(Int32)

public mut func write(value: Int32): Unit

功能:通过该函数把想要哈希运算的 Int32 值传入,然后进行哈希组合运算。

参数:

  • value: Int32 - 待运算的值。

func write(Int64)

public mut func write(value: Int64): Unit

功能:通过该函数把想要哈希运算的 Int64 值传入,然后进行哈希组合运算。

参数:

  • value: Int64 - 待运算的值。

func write(Int8)

public mut func write(value: Int8): Unit

功能:通过该函数把想要哈希运算的 Int8 值传入,然后进行哈希组合运算。

参数:

  • value: Int8 - 待运算的值。

func write(Rune)

public mut func write(value: Rune): Unit

功能:通过该函数把想要哈希运算的 Rune 值传入,然后进行哈希组合运算。

参数:

  • value: Rune - 待运算的值。

func write(String)

public mut func write(value: String): Unit

功能:通过该函数把想要哈希运算的 String 值传入,然后进行哈希组合运算。

参数:

  • value: String - 待运算的值。

func write(UInt16)

public mut func write(value: UInt16): Unit

功能:通过该函数把想要哈希运算的 UInt16 值传入,然后进行哈希组合运算。

参数:

  • value: UInt16 - 待运算的值。

func write(UInt32)

public mut func write(value: UInt32): Unit

功能:通过该函数把想要哈希运算的 UInt32 值传入,然后进行哈希组合运算。

参数:

  • value: UInt32 - 待运算的值。

func write(UInt64)

public mut func write(value: UInt64): Unit

功能:通过该函数把想要哈希运算的 UInt64 值传入,然后进行哈希组合运算。

参数:

  • value: UInt64 - 待运算的值。

func write(UInt8)

public mut func write(value: UInt8): Unit

功能:通过该函数把想要哈希运算的 UInt8 值传入,然后进行哈希组合运算。

参数:

  • value: UInt8 - 待运算的值。

struct Duration

public struct Duration <: ToString & Hashable & Comparable<Duration>

功能:Duration 表示时间间隔,是一个描述一段时间的时间类型,提供了常用的静态实例,以及计算、比较等功能。

说明:

  • Duration 表示范围为 Duration.Min 至 Duration.Max,数值表示为[-263, 263)(单位为秒),精度为纳秒。
  • Duration 每个时间单位均用整数表示,如果实际值不为整数,则向绝对值小的方向取整。例如表示 1小时30分46秒Duration 实例调用 toHours 方法,将返回结果 1 而不是 1.5 或 2。

父类型:

static const Max

public static const Max: Duration

功能:表示最大时间间隔的 Duration 实例。

类型:Duration

static const Min

public static const Min: Duration

功能:表示最小时间间隔的 Duration 实例。

类型:Duration

static const Zero

public static const Zero: Duration

功能:表示 0 纳秒时间间隔的 Duration 实例。

类型:Duration

static const day

public static const day: Duration

功能:表示 1 天时间间隔的 Duration 实例。

类型:Duration

static const hour

public static const hour: Duration

功能:表示 1 小时时间间隔的 Duration 实例。

类型:Duration

static const microsecond

public static const microsecond: Duration

功能:表示 1 微秒时间间隔的 Duration 实例。

类型:Duration

static const millisecond

public static const millisecond: Duration

功能:表示 1 毫秒时间间隔的 Duration 实例。

类型:Duration

static const minute

public static const minute: Duration

功能:表示 1 分钟时间间隔的 Duration 实例。

类型:Duration

static const nanosecond

public static const nanosecond: Duration

功能:表示 1 纳秒时间间隔的 Duration 实例。

类型:Duration

static const second

public static const second: Duration

功能:表示 1 秒时间间隔的 Duration 实例。

类型:Duration

func abs()

public func abs(): Duration

功能:返回一个新的 Duration 实例,其值大小为当前 Duration 实例绝对值。

返回值:

异常:

func compare(Duration)

public func compare(rhs: Duration): Ordering

功能:比较当前 Duration 实例与另一个 Duration 实例的关系,如果大于,返回 Ordering.GT;如果等于,返回 Ordering.EQ;如果小于,返回 Ordering.LT。

参数:

返回值:

func hashCode()

public func hashCode(): Int64

功能:获得当前 Duration 实例的哈希值。

返回值:

func toDays()

public func toDays(): Int64

功能:获得当前 Duration 实例以天为单位的整数大小。

返回值:

func toHours()

public func toHours(): Int64

功能:获得当前 Duration 实例以小时为单位的整数大小。

返回值:

func toMicroseconds()

public func toMicroseconds(): Int64

功能:获得当前 Duration 实例以微秒为单位的整数大小。

返回值:

异常:

func toMilliseconds()

public func toMilliseconds(): Int64

功能:获得当前 Duration 实例以毫秒为单位的整数大小。

返回值:

异常:

func toMinutes()

public func toMinutes(): Int64

功能:获得当前 Duration 实例以分钟为单位的整数大小。

返回值:

func toNanoseconds()

public func toNanoseconds(): Int64

功能:获得当前 Duration 实例以纳秒为单位的整数大小,向绝对值小的方向取整。

返回值:

异常:

func toSeconds()

public func toSeconds(): Int64

功能:获得当前 Duration 实例以秒为单位的整数大小。

返回值:

func toString()

public func toString(): String

功能:获得当前 Duration 实例的字符串表示,格式形如:"1d2h3m4s5ms6us7ns",表示“1天2小时3分钟4秒5毫秒6微秒7纳秒”。某个单位下数值为 0 时此项会被省略,特别地,当所有单位下数值都为 0 时,返回 "0s"。

返回值:

operator func !=(Duration)

public operator func !=(r: Duration): Bool

功能:判断当前 Duration 实例是否不等于 r

参数:

返回值:

  • Bool - truefalse。当前 Duration 实例不等于 r 时,返回 true;否则,返回 false

operator func *(Float64)

public operator func *(r: Float64): Duration

功能:实现 Duration 类型与 Float64 类型的乘法,即 Duration * Float64 运算。

参数:

  • r: Float64 - 乘法的右操作数。

返回值:

异常:

operator func *(Int64)

public operator func *(r: Int64): Duration

功能:实现 Duration 类型与 Int64 类型的乘法,即 Duration * Int64 运算。

参数:

  • r: Int64 - 乘法的右操作数。

返回值:

异常:

operator func +(Duration)

public operator func +(r: Duration): Duration

功能:实现 Duration 类型之间的加法,即 Duration + Duration 运算。

参数:

  • r: Duration - 加法的右操作数。

返回值:

异常:

operator func -(Duration)

public operator func -(r: Duration): Duration

功能:实现 Duration 类型之间的减法,即 Duration - Duration 运算。

参数:

  • r: Duration - 减法的右操作数。

返回值:

异常:

operator func /(Duration)

public operator func /(r: Duration): Float64

功能:实现 Duration 类型与 Duration 类型的除法,即 Duration / Duration 运算。

参数:

返回值:

异常:

operator func /(Float64)

public operator func /(r: Float64): Duration

功能:实现 Duration 类型与 Float64 类型的除法,即 Duration / Float64 运算。

参数:

返回值:

异常:

operator func /(Int64)

public operator func /(r: Int64): Duration

功能:实现 Duration 类型与 Int64 类型的除法,即 Duration / Int64 运算。

参数:

返回值:

异常:

operator func <(Duration)

public operator func <(r: Duration): Bool

功能:判断当前 Duration 实例是否小于 r

参数:

返回值:

  • Bool - truefalse。当前 Duration 实例小于 r 时,返回 true;否则,返回 false

operator func <=(Duration)

public operator func <=(r: Duration): Bool

功能:判断当前 Duration 实例是否小于等于 r

参数:

返回值:

  • Bool - truefalse。当前 Duration 实例小于等于 r 时,返回 true;否则,返回 false

operator func ==(Duration)

public operator func ==(r: Duration): Bool

功能:判断当前 Duration 实例是否等于 r

参数:

返回值:

  • Bool - truefalse。当前 Duration 实例等于 r 时,返回 true;否则,返回 false

operator func >(Duration)

public operator func >(r: Duration): Bool

功能:判断当前 Duration 实例是否大于 r

参数:

返回值:

  • Bool - truefalse。当前 Duration 实例大于 r 时,返回 true;否则,返回 false

operator func >=(Duration)

public operator func >=(r: Duration): Bool

功能:判断当前 Duration 实例是否大于等于 r

参数:

返回值:

  • Bool - truefalse。当前 Duration 实例大于等于 r 时,返回 true;否则,返回 false

struct LibC

public struct LibC

功能:提供了仓颉中较为高频使用的 C 接口,如申请、释放堆上 CType 实例。

static func free<T>(CPointer<T>) where T <: CType

public static unsafe func free<T>(p: CPointer<T>): Unit where T <: CType

功能:释放指针 p 指向的堆内存。

参数:

  • p: CPointer<T> - 表示需要被释放的内存地址。

static func free(CString)

public static unsafe func free(cstr: CString): Unit

功能:释放 C 风格字符串。

参数:

  • cstr: CString - 需要释放的 C 风格字符串。

static func mallocCString(String)

public static unsafe func mallocCString(str: String): CString

功能:通过 String 申请与之字符内容相同的 C 风格字符串。

构造的 C 风格字符串将以 '\0' 结束。

参数:

  • str: String - 根据该仓颉字符串构造 C 字符串。

返回值:

  • CString - 新构造的 C 风格字符串。

异常:

static func malloc<T>(Int64) where T <: CType

public static func malloc<T>(count!: Int64 = 1): CPointer<T> where T <: CType

功能:在堆中申请指定个数的 T 实例,并返回其起始指针。

申请内存长度为 sizeOf<T>() * count

参数:

  • count!: Int64 - 为可选参数,默认为1,表示申请 T 类型的个数。

返回值:

  • CPointer<T> - 申请的 T 类型指针。

异常:

struct Range<T> where T <: Countable<T> & Comparable<T> & Equatable<T>

public struct Range<T> <: Iterable<T> where T <: Countable<T> & Comparable<T> & Equatable<T> {
    public let end: T
    public let hasEnd: Bool
    public let hasStart: Bool
    public let isClosed: Bool
    public let start: T
    public let step: Int64
    public const init(start: T, end: T, step: Int64, hasStart: Bool, hasEnd: Bool, isClosed: Bool)
}

功能:该类是区间类型,用于表示一个拥有固定范围和步长的 T 的序列,要求 T 是可数的,有序的。

区间类型有对应的字面量表示,其格式为:

  • 左闭右开区间:start..end : step,它表示一个从 start 开始,以 step 为步长,到 end(不包含 end)为止的区间。
  • 左闭右闭区间:start..=end : step,它表示一个从 start 开始,以 step 为步长,到 end(包含 end)为止的区间。

注意:

  • step > 0 且 start >= end,或者 step < 0 且 start <= end 时,该 Range 实例将是一个空区间。
  • step > 0 且 start > end,或者 step < 0 且 start < end 时,该 Range 实例将是一个空区间。

父类型:

let end

public let end: T

功能:表示结束值。

类型:T

let hasEnd

public let hasEnd: Bool

功能:表示是否包含结束值。

类型:Bool

let hasStart

public let hasStart: Bool

功能:表示是否包含开始值。

类型:Bool

let isClosed

public let isClosed: Bool

功能:表示区间开闭情况,为 true 表示左闭右闭,为 false 表示左闭右开。

类型:Bool

let start

public let start: T

功能:表示开始值。

类型:T

let step

public let step: Int64

功能:表示步长。

类型:Int64

init(T, T, Int64, Bool, Bool, Bool)

public const init(start: T, end: T, step: Int64, hasStart: Bool, hasEnd: Bool, isClosed: Bool)

功能:使用该构造函数创建 Range 序列。

参数:

  • start: T - 开始值。
  • end: T - 结束值。
  • step: Int64 - 步长,取值不能为 0。
  • hasStart: Bool - 是否有开始值。
  • hasEnd: Bool - 是否有结束值。
  • isClosed: Bool - true 代表左闭右闭,false 代表左闭右开。

异常:

func isEmpty()

public const func isEmpty(): Bool

功能:判断该区间是否为空。

返回值:

  • Bool - 如果为空,返回 true,否则返回 false。

func iterator()

public func iterator(): Iterator<T>

功能:获取当前区间的迭代器。

返回值:

  • Iterator<T> - 当前区间的迭代器。

extend<T> Range<T> <: Equatable<Range<T>> where T <: Countable<T> & Comparable<T> & Equatable<T>

extend<T> Range<T> <: Equatable<Range<T>> where T <: Countable<T> & Comparable<T> & Equatable<T>

功能:为 Range<T> 类型扩展 Equatable<Range<T>> 接口。

父类型:

operator func !=(Range<T>)

public operator func !=(that: Range<T>): Bool

功能:判断两个 Range 是否不相等。

参数:

返回值:

  • Bool - true 代表不相等,false 代表相等。

operator func ==(Range<T>)

public operator func ==(that: Range<T>): Bool

功能:判断两个 Range 实例是否相等。

两个 Range 实例相等指的是它们表示同一个区间,即 startendstepisClosed 值相等。

参数:

返回值:

  • Bool - true 代表相等,false 代表不相等。

extend<T> Range<T> <: Hashable where T <: Hashable & Countable<T> & Comparable<T> & Equatable<T>

extend<T> Range<T> <: Hashable where T <: Hashable & Countable<T> & Comparable<T> & Equatable<T>

功能:为 Range 类型扩展 Hashable 接口,支持计算哈希值。

父类型:

func hashCode()

public func hashCode(): Int64

功能:获取哈希值,该值为 startendstepisClosed 的组合哈希运算结果。

返回值:

struct String

public struct String <: Collection<Byte> & Equatable<String> & Comparable<String> & Hashable & ToString {
    public static const empty: String
    public const init()
    public init(value: Array<Rune>)
    public init(value: Collection<Rune>)
}

功能:该结构体表示仓颉字符串,提供了构造、查找、拼接等一系列字符串操作。

注意:

String 类型仅支持 UTF-8 编码。

父类型:

static const empty

public static const empty: String = String()

功能:创建一个空的字符串并返回。

类型:String

prop size

public prop size: Int64

功能:获取字符串 UTF-8 编码后的字节长度。

类型:Int64

init()

public const init()

功能:构造一个空的字符串。

init(Array<Rune>)

public init(value: Array<Rune>)

功能:根据字符数组构造一个字符串,字符串内容为数组中的所有字符。

参数:

  • value: Array<Rune> - 根据该字符数组构造字符串。

init(Collection<Rune>)

public init(value: Collection<Rune>)

功能:据字符集合构造一个字符串,字符串内容为集合中的所有字符。

参数:

  • value: Collection<Rune> - 根据该字符集合构造字符串。

static func fromUtf8(Array<UInt8>)

public static func fromUtf8(utf8Data: Array<UInt8>): String

功能:根据 UTF-8 编码的字节数组构造一个字符串。

参数:

  • utf8Data: Array<UInt8> - 根据该字节数组构造字符串。

返回值:

  • String - 构造的字符串。

异常:

static func fromUtf8Unchecked(Array<UInt8>)

public static unsafe func fromUtf8Unchecked(utf8Data: Array<UInt8>): String

功能:根据字节数组构造一个字符串。

相较于 fromUtf8 函数,它并没有针对于字节数组进行 UTF-8 相关规则的检查,所以它所构建的字符串并不一定保证是合法的,甚至出现非预期的异常,如果不是某些场景下的性能考虑,请优先使用安全的 fromUtf8 函数。

参数:

  • utf8Data: Array<UInt8> - 根据该字节数组构造字符串。

返回值:

  • String - 构造的字符串。

static func join(Array<String>, String)

public static func join(strArray: Array<String>, delimiter!: String = String.empty): String

功能:连接字符串列表中的所有字符串,以指定分隔符分隔。

参数:

  • strArray: Array<String> - 需要被连接的字符串数组,当数组为空时,返回空字符串。
  • delimiter!: String - 用于连接的中间字符串,其默认值为 String.empty。

返回值:

  • String - 连接后的新字符串。

func clone()

public func clone(): String

功能:返回原字符串的拷贝。

返回值:

  • String - 拷贝得到的新字符串。

func compare(String)

public func compare(str: String): Ordering

功能:按字典序比较当前字符串和参数指定的字符串。

参数:

  • str: String - 被比较的字符串。

返回值:

  • Ordering - 返回 enum 值 Ordering 表示结果,Ordering.GT 表示当前字符串字典序大于 str 字符串,Ordering.LT 表示当前字符串字典序小于 str 字符串,Ordering.EQ 表示两个字符串字典序相等。

异常:

func contains(String)

public func contains(str: String): Bool

功能:判断原字符串中是否包含字符串 str。

参数:

  • str: String - 待搜索的字符串。

返回值:

  • Bool - 如果字符串 str 在原字符串中,返回 true,否则返回 false。特别地,如果 str 字符串长度为 0,返回 true。

func count(String)

public func count(str: String): Int64

功能:返回子字符串 str 在原字符串中出现的次数。

参数:

  • str: String - 被搜索的子字符串。

返回值:

  • Int64 - 出现的次数,当 str 为空字符串时,返回原字符串中 Rune 的数量加一。

func endsWith(String)

public func endsWith(suffix: String): Bool

功能:判断原字符串是否以 suffix 字符串为后缀结尾。

参数:

  • suffix: String - 被判断的后缀字符串。

返回值:

  • Bool - 如果字符串 str 是原字符串的后缀,返回 true,否则返回 false,特别地,如果 str 字符串长度为 0,返回 true。

func equalsIgnoreAsciiCase(String): Bool

public func equalsIgnoreAsciiCase(that: String): Bool

功能:判断当前字符串和指定字符串是否相等,忽略大小写。

参数:

  • that: String - 待比较的字符串。

返回值:

  • Bool - 如果当前字符串与待比较字符串相等,返回 true,否则返回 false。

func get(Int64)

public func get(index: Int64): Option<Byte>

功能:返回字符串下标 index 对应的 UTF-8 编码字节值。

参数:

  • index: Int64 - 要获取的字节值的下标。

返回值:

  • Option<Byte> - 获取得到下标对应的 UTF-8 编码字节值,当 index 小于 0 或者大于等于字符串长度,则返回 Option<Byte>.None。

func hashCode()

public func hashCode(): Int64

功能:获取字符串的哈希值。

返回值:

  • Int64 - 返回字符串的哈希值。

func indexOf(Byte)

public func indexOf(b: Byte): Option<Int64>

功能:获取指定字节 b 第一次出现的在原字符串内的索引。

参数:

  • b: Byte - 待搜索的字节。

返回值:

  • Option<Int64> - 如果原字符串中包含指定字节,返回其第一次出现的索引,如果原字符串中没有此字节,返回 None

func indexOf(Byte, Int64)

public func indexOf(b: Byte, fromIndex: Int64): Option<Int64>

功能:从原字符串指定索引开始搜索,获取指定字节第一次出现的在原字符串内的索引。

参数:

  • b: Byte - 待搜索的字节。
  • fromIndex: Int64 - 以指定的索引 fromIndex 开始搜索。

返回值:

  • Option<Int64> - 如果搜索成功,返回指定字节第一次出现的索引,否则返回 None。特别地,当 fromIndex 小于零,效果同 0,当 fromIndex 大于等于原字符串长度,返回 None

func indexOf(String)

public func indexOf(str: String): Option<Int64>

功能:返回指定字符串 str 在原字符串中第一次出现的起始索引。

参数:

  • str: String - 待搜索的字符串。

返回值:

  • Option<Int64> - 如果原字符串包含 str 字符串,返回其第一次出现的索引,如果原字符串中没有 str 字符串,返回 None。

func indexOf(String, Int64)

public func indexOf(str: String, fromIndex: Int64): Option<Int64>

功能:从原字符串 fromIndex 索引开始搜索,获取指定字符串 str 第一次出现的在原字符串的起始索引。

参数:

  • str: String - 待搜索的字符串。
  • fromIndex: Int64 - 以指定的索引 fromIndex 开始搜索。

返回值:

  • Option<Int64> - 如果搜索成功,返回 str 第一次出现的索引,否则返回 None。特别地,当 str 是空字符串时,如果fromIndex 大于 0,返回 None,否则返回 Some(0)。当 fromIndex 小于零,效果同 0,当 fromIndex 大于等于原字符串长度返回 None。

func isAscii()

public func isAscii(): Bool

功能:判断字符串是否是一个 Ascii 字符串,如果字符串为空或没有 Ascii 以外的字符,则返回 true。

返回值:

  • Bool - 是则返回 true,不是则返回 false。

func isAsciiBlank()

public func isAsciiBlank(): Bool

功能:判断字符串是否为空或者字符串中的所有 Rune 都是 ascii 码的空白字符(包括:0x09、0x10、0x11、0x12、0x13、0x20)。

返回值:

  • Bool - 如果是返回 true,否则返回 false。

func isEmpty()

public func isEmpty(): Bool

功能:判断原字符串是否为空字符串。

返回值:

  • Bool - 如果为空返回 true,否则返回 false。

func iterator()

public func iterator(): Iterator<Byte>

功能:获取字符串的 UTF-8 编码字节迭代器,可用于支持 for-in 循环。

返回值:

  • Iterator<Byte> - 字符串的 UTF-8 编码字节迭代器。

func lastIndexOf(Byte)

public func lastIndexOf(b: Byte): Option<Int64>

功能:返回指定字节 b 最后一次出现的在原字符串内的索引。

参数:

  • b: Byte - 待搜索的字节。

返回值:

  • Option<Int64> - 如果原字符串中包含此字节,返回其最后一次出现的索引,否则返回 None

func lastIndexOf(Byte, Int64)

public func lastIndexOf(b: Byte, fromIndex: Int64): Option<Int64>

功能:从原字符串 fromIndex 索引开始搜索,返回指定 UTF-8 编码字节 b 最后一次出现的在原字符串内的索引。

参数:

  • b: Byte - 待搜索的字节。
  • fromIndex: Int64 - 以指定的索引 fromIndex 开始搜索。

返回值:

  • Option<Int64> - 如果搜索成功,返回指定字节最后一次出现的索引,否则返回 None。特别地,当 fromIndex 小于零,效果同 0,当 fromIndex 大于等于原字符串长度,返回 None

func lastIndexOf(String)

public func lastIndexOf(str: String): Option<Int64>

功能:返回指定字符串 str 最后一次出现的在原字符串的起始索引。

参数:

  • str: String - 待搜索的字符串。

返回值:

  • Option<Int64> - 如果原字符串中包含 str 字符串,返回其最后一次出现的索引,否则返回 None

func lastIndexOf(String, Int64)

public func lastIndexOf(str: String, fromIndex: Int64): Option<Int64>

功能:从原字符串指定索引开始搜索,获取指定字符串 str 最后一次出现的在原字符串的起始索引。

参数:

  • str: String - 待搜索的字符串。
  • fromIndex: Int64 - 以指定的索引 fromIndex 开始搜索。

返回值:

  • Option<Int64> - 如果这个字符串在位置 fromIndex 及其之后没有出现,则返回 None。特别地,当 str 是空字符串时,如果 fromIndex 大于 0,返回 None,否则返回 Some(0),当 fromIndex 小于零,效果同 0,当 fromIndex 大于等于原字符串长度返回 None

func lazySplit(String, Bool)

public func lazySplit(str: String, removeEmpty!: Bool = false): Iterator<String>

功能:对原字符串按照字符串 str 分隔符分割,该函数不立即对字符串进行分割,而是返回迭代器,使用迭代器进行遍历时再实际执行分隔操作。

当 str 未出现在原字符串中,返回大小为 1 的字符串迭代器,唯一的元素为原字符串。

参数:

  • str: String - 字符串分隔符。
  • removeEmpty!: Bool - 移除分割结果中的空字符串,默认值为 false。

返回值:

func lazySplit(String, Int64, Bool)

public func lazySplit(str: String, maxSplits: Int64, removeEmpty!: Bool = false): Iterator<String>

功能:对原字符串按照字符串 str 分隔符分割,该函数不立即对字符串进行分割,而是返回迭代器,使用迭代器进行遍历时再实际执行分隔操作。

  • 当 maxSplit 为 0 时,返回空的字符串迭代器;
  • 当 maxSplit 为 1 时,返回大小为 1 的字符串迭代器,唯一的元素为原字符串;
  • 当 maxSplit 为负数时,直接返回分割后的字符串迭代器;
  • 当 maxSplit 大于完整分割出来的子字符串数量时,返回完整分割的字符串迭代器;
  • 当 str 未出现在原字符串中,返回大小为 1 的字符串迭代器,唯一的元素为原字符串;
  • 当 str 为空时,对每个字符进行分割;当原字符串和分隔符都为空时,返回空字符串迭代器。

参数:

  • str: String - 字符串分隔符。
  • maxSplits: Int64 - 最多分割为 maxSplit 个子字符串。
  • removeEmpty!: Bool - 移除分割结果中的空字符串,默认值为 false。

返回值:

func lines()

public func lines(): Iterator<String>

功能:获取字符串的行迭代器,每行都由换行符进行分隔,换行符是 \n \r \r\n 之一,结果中每行不包括换行符。

返回值:

func padEnd(Int64, String)

public func padEnd(totalWidth: Int64, padding!: String = " "): String

功能:按指定长度左对齐原字符串,如果原字符串长度小于指定长度,在其右侧添加指定字符串。

当指定长度小于字符串长度时,返回字符串本身,不会发生截断;当指定长度大于字符串长度时,在右侧添加 padding 字符串,当 padding 长度大于 1 时,返回字符串的长度可能大于指定长度。

参数:

  • totalWidth: Int64 - 指定对齐后字符串长度,取值需大于等于 0。
  • padding!: String - 当长度不够时,在右侧用指定的字符串 padding 进行填充。

返回值:

  • String - 填充后的字符串。

异常:

func padStart(Int64, String)

public func padStart(totalWidth: Int64, padding!: String = " "): String

功能:按指定长度右对齐原字符串,如果原字符串长度小于指定长度,在其左侧添加指定字符串。

当指定长度小于字符串长度时,返回字符串本身,不会发生截断;当指定长度大于字符串长度时,在左侧添加 padding 字符串,当 padding 长度大于 1 时,返回字符串的长度可能大于指定长度。

参数:

  • totalWidth: Int64 - 指定对齐后字符串长度,取值需大于等于 0。
  • padding!: String - 当长度不够时,在左侧用指定的字符串 padding 进行填充

返回值:

  • String - 填充后的字符串。

异常:

func rawData()

public unsafe func rawData(): Array<Byte>

功能:获取字符串的 UTF-8 编码的原始字节数组。

注意:

用户不应该对获取的数组进行修改,这将破坏字符串的不可变性。

返回值:

  • Array<Byte> - 当前字符串对应的原始字节数组。

func removePrefix(String)

public func removePrefix(prefix: String): String

功能:去除字符串的 prefix 前缀。

参数:

  • prefix: String - 待去除的前缀。

返回值:

  • String - 去除前缀后得到的新字符串。

func removeSuffix(String)

public func removeSuffix(suffix: String): String

功能:去除字符串的 suffix 后缀。

参数:

  • suffix: String - 待去除的后缀。

返回值:

  • String - 去除后缀后得到的新字符串。

func replace(String, String)

public func replace(old: String, new: String): String

功能:使用新字符串替换原字符串中旧字符串。

参数:

  • old: String - 旧字符串。
  • new: String - 新字符串。

返回值:

  • String - 替换后的新字符串。

异常:

  • OutOfMemoryError - 如果此函数分配内存时产生错误,抛出异常。

func runes()

public func runes(): Iterator<Rune>

功能:获取字符串的 Rune 迭代器。

返回值:

  • Iterator<Rune> - 字符串的 Rune 迭代器。

异常:

  • IllegalArgumentException - 使用 for-in 或者 next() 方法遍历迭代器时,如果读取到非法字符,抛出异常。

func split(String, Bool)

public func split(str: String, removeEmpty!: Bool = false): Array<String>

功能:对原字符串按照字符串 str 分隔符分割,指定是否删除空串。

当 str 未出现在原字符串中,返回长度为 1 的字符串数组,唯一的元素为原字符串。

参数:

  • str: String - 字符串分隔符。
  • removeEmpty!: Bool - 移除分割结果中的空字符串,默认值为 false。

返回值:

func split(String, Int64, Bool)

public func split(str: String, maxSplits: Int64, removeEmpty!: Bool = false): Array<String>

功能:对原字符串按照字符串 str 分隔符分割,指定最多分隔子串数,以及是否删除空串。

  • 当 maxSplit 为 0 时,返回空的字符串数组;
  • 当 maxSplit 为 1 时,返回长度为 1 的字符串数组,唯一的元素为原字符串;
  • 当 maxSplit 为负数时,返回完整分割后的字符串数组;
  • 当 maxSplit 大于完整分割出来的子字符串数量时,返回完整分割的字符串数组;
  • 当 str 未出现在原字符串中,返回长度为 1 的字符串数组,唯一的元素为原字符串;
  • 当 str 为空时,对每个字符进行分割;当原字符串和分隔符都为空时,返回空字符串数组。

参数:

  • str: String - 字符串分隔符。
  • maxSplits: Int64 - 最多分割为 maxSplit 个子字符串。
  • removeEmpty!: Bool - 移除分割结果中的空字符串,默认值为 false。

返回值:

func startsWith(String)

public func startsWith(prefix: String): Bool

功能:判断原字符串是否以 prefix 字符串为前缀。

参数:

  • prefix: String - 被判断的前缀字符串。

返回值:

  • Bool - 如果字符串 str 是原字符串的前缀,返回 true,否则返回 false,特别地,如果 str 字符串长度为 0,返回 true。

func toArray()

public func toArray(): Array<Byte>

功能:获取字符串的 UTF-8 编码的字节数组。

返回值:

  • Array<Byte> - 字符串的 UTF-8 编码的字节数组。

func toAsciiLower()

public func toAsciiLower(): String

功能:将该字符串中所有 Ascii 大写字母转化为 Ascii 小写字母。

返回值:

  • String - 转换后的新字符串。

func toAsciiTitle()

public func toAsciiTitle(): String

功能:将该字符串标题化。

该函数只转换 Ascii 英文字符,当该英文字符是字符串中第一个字符或者该字符的前一个字符不是英文字符,则该字符大写,其他英文字符小写。

返回值:

  • String - 转换后的新字符串。

func toAsciiUpper()

public func toAsciiUpper(): String

功能:将该字符串中所有 Ascii 小写字母转化为 Ascii 大写字母。

返回值:

  • String - 转换后的新字符串。

func toRuneArray()

public func toRuneArray(): Array<Rune>

功能:获取字符串的 Rune 数组。如果原字符串为空字符串,则返回空数组。

返回值:

  • Array<Rune> - 字符串的 Rune 数组。

func toString()

public func toString(): String

功能:获得字符串本身。

返回值:

  • String - 返回字符串本身。

func trimAscii()

public func trimAscii(): String

功能:去除原字符串开头结尾以 whitespace 字符组成的子字符串。

whitespace 的 unicode 码点范围为 [0009, 000D] 和 [0020]。

返回值:

  • String - 转换后的新字符串。

func trimAsciiEnd()

public func trimAsciiEnd(): String

功能:去除原字符串结尾以 whitespace 字符组成的子字符串。

返回值:

  • String - 转换后的新字符串。

func trimAsciiStart()

public func trimAsciiStart(): String

功能:去除原字符串开头以 whitespace 字符组成的子字符串。

返回值:

  • String - 转换后的新字符串。

func trimEnd((Rune)->Bool)

public func trimEnd(predicate: (Rune)->Bool): String

功能:修剪当前字符串,从尾开始删除符合过滤条件的 Rune 字符,直到第一个不符合过滤条件的 Rune 字符为止。

参数:

  • predicate: (Rune)->Bool - 过滤条件。

返回值:

  • String - 修剪后得到的新字符串。

func trimEnd(Array<Rune>)

public func trimEnd(set: Array<Rune>): String

功能:修剪当前字符串,从尾开始删除在 set 中的 Rune 字符,直到第一个不在 set 中的 Rune 字符为止。

例如 "14122".trimEnd([r'1', r'2']) = "14"。

参数:

  • set: Array<Rune> - 待删除的字符的集合。

返回值:

  • String - 修剪后得到的新字符串。

func trimEnd(String)

public func trimEnd(set: String): String

功能:修剪当前字符串,从尾开始删除在 set 中的 Rune 字符,直到第一个不在 set 中的 Rune 字符为止。

例如 "14122".trimEnd("12") = "14"。

参数:

  • set: String - 待删除的字符的集合。

返回值:

  • String - 修剪后得到的新字符串。

func trimStart((Rune)->Bool)

public func trimStart(predicate: (Rune)->Bool): String

功能:修剪当前字符串,从头开始删除符合过滤条件的 Rune 字符,直到第一个不符合过滤条件的 Rune 字符为止。

参数:

  • predicate: (Rune)->Bool - 过滤条件。

返回值:

  • String - 修剪后得到的新字符串。

func trimStart(Array<Rune>)

public func trimStart(set: Array<Rune>): String

功能:修剪当前字符串,从头开始删除在 set 中的 Rune 字符,直到第一个不在 set 中的 Rune 字符为止。

例如 "12241".trimStart([r'1', r'2']) = "41"。

参数:

  • set: Array<Rune> - 待删除的字符的集合。

返回值:

  • String - 修剪后得到的新字符串。

func trimStart(String)

public func trimStart(set: String): String

功能:修剪当前字符串,从头开始删除在 set 中的 Rune 字符,直到第一个不在 set 中的 Rune 字符为止。

例如 "12241".trimStart("12") = "41"。

参数:

  • set: String - 待删除的字符的集合。

返回值:

  • String - 修剪后得到的新字符串。

operator func !=(String)

public const operator func !=(right: String): Bool

功能:判断两个字符串是否不相等。

参数:

返回值:

  • Bool - 不相等返回 true,相等返回 false。

operator func *(Int64)

public const operator func *(count: Int64): String

功能:原字符串重复 count 次。

参数:

  • count: Int64 - 原字符串重复的次数。

返回值:

operator func +(String)

public const operator func +(right: String): String

功能:两个字符串相加,将 right 字符串拼接在原字符串的末尾。

参数:

  • right: String - 待追加的字符串。

返回值:

  • String - 返回拼接后的字符串。

operator func <(String)

public const operator func <(right: String): Bool

功能:判断两个字符串大小。

参数:

  • right: String - 待比较的字符串。

返回值:

  • Bool - 原字符串字典序小于 right 时,返回 true,否则返回 false。

operator func <=(String)

public const operator func <=(right: String): Bool

功能:判断两个字符串大小。

参数:

  • right: String - 待比较的字符串。

返回值:

  • Bool - 原字符串字典序小于或等于 right 时,返回 true,否则返回 false。

operator func ==(String)

public const operator func ==(right: String): Bool

功能:判断两个字符串是否相等。

参数:

  • right: String - 待比较的字符串。

返回值:

  • Bool - 相等返回 true,不相等返回 false。

operator func >(String)

public const operator func >(right: String): Bool

功能:判断两个字符串大小。

参数:

  • right: String - 待比较的字符串。

返回值:

  • Bool - 原字符串字典序大于 right 时,返回 true,否则返回 false。

operator func >=(String)

public const operator func >=(right: String): Bool

功能:判断两个字符串大小。

参数:

  • right: String - 待比较的字符串。

返回值:

  • Bool - 原字符串字典序大于或等于 right 时,返回 true,否则返回 false。

operator func [](Int64)

public const operator func [](index: Int64): Byte

功能:返回指定索引 index 处的 UTF-8 编码字节。

参数:

  • index: Int64 - 要获取 UTF-8 编码字节的下标。

返回值:

  • Byte - 获取得到下标对应的 UTF-8 编码字节。

异常:

operator func [](Range<Int64>)

public const operator func [](range: Range<Int64>): String

功能:根据给定区间获取当前字符串的切片。

注意:

  1. 如果参数 range 是使用 Range 构造函数构造的 Range 实例,有如下行为:
    • start 的值就是构造函数传入的值本身,不受构造时传入的 hasStart 的值的影响。
    • hasEnd 为 false 时,end 值不生效,且不受构造时传入的 isClosed 的值的影响,该字符串切片取到原字符串最后一个元素。
  2. range 的步长只能为 1。

参数:

返回值:

异常:

异常类

class ArithmeticException

public open class ArithmeticException <: Exception {
    public init()
    public init(message: String)
}

功能:算术异常类,发生算术异常时使用。

父类型:

init()

public init()

功能:构造一个默认的 ArithmeticException 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据异常信息构造一个 ArithmeticException 实例。

参数:

  • message: String - 异常提示信息。

func getClassName()

protected open override func getClassName(): String

功能:获得类名。

返回值:

class Error

public open class Error <: ToString

功能:Error 是所有错误类的基类。该类不可被继承,不可初始化,但是可以被捕获到。

父类型:

prop message

public open prop message: String

功能:获取错误信息。

类型:String

func getStackTrace()

public func getStackTrace(): Array<StackTraceElement>

功能:获取堆栈信息,每一条堆栈信息用一个 StackTraceElement 实例表示,最终返回一个 StackTraceElement 的数组。

返回值:

func printStackTrace()

public open func printStackTrace(): Unit

功能:向控制台打印堆栈信息。

func toString()

public open func toString(): String

功能:获取当前 Error 实例的字符串值,包括类名和错误信息。

返回值:

  • String - 错误信息字符串。

class Exception

public open class Exception <: ToString {
    public init()
    public init(message: String)
}

功能:Exception 是所有异常类的父类。

支持构造一个异常类,设置、获取异常信息,转换为字符串,获取、打印堆栈,设置异常名(用于字符串表示)。

父类型:

prop message

public open prop message: String

功能:获取异常信息。

类型:String

init()

public init()

功能:构造一个默认的 Exception 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据异常信息构造一个 Exception 实例。

参数:

  • message: String - 异常提示信息。

func getClassName()

protected open func getClassName(): String

功能:获得类名,用字符串表示。

类名将在异常字符串中体现(toString 函数返回值),覆写该函数将改变异常信息字符串中类名信息。

返回值:

func getStackTrace()

public func getStackTrace(): Array<StackTraceElement>

功能:获取堆栈信息,每一条堆栈信息用一个 StackTraceElement 实例表示,最终返回一个 StackTraceElement 的数组。

返回值:

func printStackTrace()

public func printStackTrace(): Unit

功能:向控制台打印堆栈信息。

func toString()

public open func toString(): String

功能:获取当前 Exception 实例的字符串值,包括类名和异常信息。

返回值:

class IllegalArgumentException

public open class IllegalArgumentException <: Exception {
    public init()
    public init(message: String)
}

功能:表示参数非法的异常类。

父类型:

init()

public init()

功能:构造一个默认的 IllegalArgumentException 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据异常信息构造一个 IllegalArgumentException 实例。

参数:

  • message: String - 异常提示信息。

func getClassName()

protected override open func getClassName(): String

功能:获得类名,用字符串表示。

类名将在异常字符串中体现(toString 函数返回值),覆写该函数将改变异常信息字符串中类名信息。默认实现中类名为 "IllegalArgumentException"。

返回值:

class IllegalFormatException

public open class IllegalFormatException <: IllegalArgumentException {
    public init()
    public init(message: String)
}

功能:表示变量的格式无效或不标准时的异常类。

父类型:

init()

public init()

功能:构造一个默认的 IllegalFormatException 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据异常信息构造一个 IllegalFormatException 实例。

参数:

  • message: String - 异常提示信息。

class IllegalMemoryException

public class IllegalMemoryException <: Exception {
    public init()
    public init(message: String)
}

功能:表示内存操作错误的异常类。

父类型:

init()

public init()

功能:构造一个默认的 IllegalMemoryException 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据指定异常信息构造 IllegalMemoryException 实例。

参数:

  • message: String - 异常提示信息。

class IllegalStateException

public class IllegalStateException <: Exception {
    public init()
    public init(message: String)
}

功能:表示状态非法的异常类。

父类型:

init()

public init()

功能:构造一个默认的 IllegalStateException 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据异常信息构造一个 IllegalStateException 实例。

参数:

  • message: String - 异常提示信息。

class IndexOutOfBoundsException

public class IndexOutOfBoundsException <: Exception {
    public init()
    public init(message: String)
}

功能:表示索引越界的异常类。

父类型:

init()

public init()

功能:构造一个默认的 IndexOutOfBoundsException 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据异常信息构造一个 IndexOutOfBoundsException 实例。

参数:

  • message: String - 异常提示信息。

class InternalError

public class InternalError <: Error

功能:表示内部错误的错误类,该类不可初始化,但是可以被捕获到。

父类型:

class NegativeArraySizeException

public class NegativeArraySizeException <: Exception {
    public init()
    public init(message: String)
}

功能:表示数组大小为负数的异常类。

父类型:

init()

public init()

功能:构造一个默认的 NegativeArraySizeException 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据异常信息构造一个 NegativeArraySizeException 实例。

参数:

  • message: String - 异常提示信息。

class NoneValueException

public class NoneValueException <: Exception {
    public init()
    public init(message: String)
}

功能:表示 Option<T> 实例的值为 None 的异常类,通常在 getOrThrow 函数中被抛出。

父类型:

init()

public init()

功能:构造一个默认的 NoneValueException 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据异常信息构造一个 NoneValueException 实例。

参数:

  • message: String - 异常提示信息。

class OutOfMemoryError

public class OutOfMemoryError <: Error

功能:表示内存不足错误的错误类,该类不可被继承,不可初始化,但是可以被捕获到。

父类型:

class OverflowException

public class OverflowException <: ArithmeticException {
    public init()
    public init(message: String)
}

功能:表示算术运算溢出的异常类。

父类型:

init()

public init()

功能:构造一个默认的 OverflowException 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据指定异常信息构造 OverflowException 实例。

参数:

  • message: String - 异常提示信息。

class SpawnException

public class SpawnException <: Exception {
    public init()
    public init(message: String)
}

功能:线程异常类,表示线程处理过程中发生异常。

父类型:

init()

public init()

功能:构造一个默认的 SpawnException 实例,默认错误信息为空。

init(String)

public init(message: String)

功能:根据异常信息构造一个 SpawnException 实例。

参数:

  • message: String - 异常提示信息。

class StackOverflowError

public class StackOverflowError <: Error

功能:表示堆栈溢出错误的错误类,该类不可被继承,不可初始化,但是可以被捕获到。

父类型:

func printStackTrace()

public override func printStackTrace(): Unit

功能:向控制台打印堆栈信息。

class TimeoutException

public class TimeoutException <: Exception {
    public init()
    public init(message: String)
}

功能:当阻塞操作超时时引发异常。

父类型:

init()

public init()

功能:构造一个默认的 TimeoutException 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据指定异常信息构造 TimeoutException 实例。

参数:

  • message: String - 异常提示信息。

class UnsupportedException

public class UnsupportedException <: Exception {
    public init()
    public init(message: String)
}

功能:表示功能未支持的异常类。

父类型:

init()

public init()

功能:构造一个默认的 UnsupportedException 实例,默认异常信息为空。

init(String)

public init(message: String)

功能:根据指定异常信息构造 UnsupportedException 实例。

参数:

  • message: String - 异常提示信息。

仓颉并发编程示例

spawn 的使用

主线程和新线程同时尝试打印一些文本。

代码如下:


main(): Int64 {
    spawn { =>
        for (i in 0..10) {
            println("New thread, number = ${i}")
            sleep(100 * Duration.millisecond) /* 睡眠 100 毫秒 */
        }
    }

    for (i in 0..5) {
        println("Main thread, number = ${i}")
        sleep(100 * Duration.millisecond) /* 睡眠 100 毫秒 */
    }
    return 0
}

运行结果如下:

Main thread, number = 0
New thread, number = 0
Main thread, number = 1
New thread, number = 1
Main thread, number = 2
New thread, number = 2
Main thread, number = 3
New thread, number = 3
Main thread, number = 4
New thread, number = 4
New thread, number = 5

注意:

上述打印信息仅做参考,实际结果受运行时序影响,呈现随机性。

由于主线程不会等待新线程执行结束,因此程序退出时新线程并未执行结束。

Future 的 get 的使用

主线程等待创建线程执行完再执行。

代码如下:


main(): Int64 {
    let fut: Future<Unit> = spawn { =>
        for (i in 0..10) {
            println("New thread, number = ${i}")
            sleep(100 * Duration.millisecond) /* 睡眠 100 毫秒 */
        }
    }

    fut.get() /* 等待线程完成 */

    for (i in 0..5) {
        println("Main thread, number = ${i}")
        sleep(100 * Duration.millisecond) /* 睡眠 100 毫秒 */
    }
    return 0
}

运行结果如下:

New thread, number = 0
New thread, number = 1
New thread, number = 2
New thread, number = 3
New thread, number = 4
New thread, number = 5
New thread, number = 6
New thread, number = 7
New thread, number = 8
New thread, number = 9
Main thread, number = 0
Main thread, number = 1
Main thread, number = 2
Main thread, number = 3
Main thread, number = 4

取消仓颉线程

子线程接收主线程发送的取消请求。

main(): Unit {
    let future = spawn { // Create a new thread
        while (true) {
            if (Thread.currentThread.hasPendingCancellation) {
                return 0
            }
        }
        return 1
    }
    //...
    future.cancel()    // Send a termination request
    let res = future.get() // Wait for thread termination
    println(res) // 0
}

运行结果:

0

使用 CString 与 C 代码交互示例

C 代码中分别提供两个函数: getCString 函数,用于返回一个 C 侧的字符串指针; printCString 函数,用于打印来自仓颉侧 CString 。

#include <stdio.h>

char *str = "CString in C code.";

char *getCString() { return str; }

void printCString(char *s) { printf("%s\n", s); }

在仓颉代码中,创建一个 CString 对象,传递给 C 侧打印。并且获取 C 侧字符串,在仓颉侧打印:

foreign func getCString(): CString
foreign func printCString(s: CString): Unit

main() {
    // 仓颉侧构造 CString 实例,传递到 C 侧
    unsafe {
        let s: CString = LibC.mallocCString("CString in Cangjie code.")
        printCString(s)
        LibC.free(s)
    }

    unsafe {
        // C 侧申请字符串指针,传递到仓颉侧成为 CString 实例,再转换为仓颉字符串 String 类型
        let cs = getCString()
        println(cs.toString())
    }

    // 在 try-with-resource 语法上下文中使用 CStringResource 自动管理 CString 内存
    let cs = unsafe { LibC.mallocCString("CString in Cangjie code.") }
    try (csr = cs.asResource()) {
        unsafe { printCString(csr.value) }
    }

    0
}

示例输出:

CString in Cangjie code.
CString in C code.
CString in Cangjie code.

说明:

编译方式:先将 C 代码编译成静态库或动态库,然后编译仓颉代码并链接 C 库。 假设 C 文件为 test.c,仓颉文件为 test.cj,编译过程如下:

  1. 使用 gcc 命令 gcc -fPIC -shared test.c -o libtest.so,编出 C 库 libtest.so
  2. 使用 cjc 命令 cjc -L . -l test test.cj,编出可执行文件 main

std.argopt 包

功能介绍

argopt 包提供从命令行参数字符串解析出参数名和参数值的相关能力。

命令行参数是在命令行中传递给程序的参数,它们用于指定程序的配置或行为。例如,一个命令行程序可能有一个参数来指定它要处理的文件的名称,或者一个参数来指定使用的数据库。这些参数通常会被解析并传递给程序的代码,以便程序可以根据这些参数正确地执行其功能。

命令行参数分为短命令行参数和长命令行参数,区别在于它们的长度和可读性。短命令行参数通常由单个字母组成,易于记忆;长命令行参数通常由一个或多个单词组成,易于理解。

API 列表

类名功能
ArgOptArgopt 用于解析命令行参数,并提供了获取解析结果的功能。

class Argopt

public class ArgOpt {
    public init(shortArgFormat: String)
    public init(longArgList: Array<String>)
    public init(shortArgFormat: String, longArgList: Array<String>)
    public init(args: Array<String>, shortArgFormat: String, longArgList: Array<String>)
}

功能:Argopt 用于解析命令行参数,并提供了获取解析结果的功能。

一个命令行参数是由前缀符号、参数名、参数值组成。

其中 "-" 表示短参(短命令行参数)的前缀,"--" 表示长参(长命令行参数)的前缀。可解析的短参参数名只能是字母,可解析长参参数名字符串需满足:以字母开头,参数名中不能包含 "="。

例如:"-a123" 和 "--target=abc.txt" 为两个命令行参数,"a" 为短参名,"target" 为长参名。而 "-123" 和 "--tar=get=abc.txt" 则是错误的命令行参数。

该类允许用户指定参数名和参数字符串,并提供根据参数名解析字符串的方法。

用户指定短参名和长参名时格式如下:

  • 短参名字符串的参数,格式为:"a:",规范为:一位字母和 ":" 的组合,例如:"ab:",该例仅解析 "b" 作为短参名。
  • 长参名字符串数组参数,字符串格式为:"--testA=" 或 "testA=",规范为:"--" + 长参参数名 + "="(前缀"--"可省略)。

根据参数名解析命令行参数时,若命令行参数格式正确且有对应的参数名,可正确解析并被用户获取;否则不会解析。

例如:参数名为 "a:b:",命令行参数为 "-a123 -cofo",将解析出参数名为 "a",参数值为 "123" 的命令行参数。"-cofo" 则不会解析。

init(Array<String>)

public init(longArgList: Array<String>)

功能:构造 ArgOpt 实例,并从列表的字符串中解析长参名。

参数:

  • longArgList: Array<String> - 包含长参名的字符串数组。

异常:

  • IllegalArgumentException - 当字符串数组中的长参名字符串不符合规范,或字符串不符合 UTF-8 编码,或不存在该 Unicode 字符时,抛出异常。

init(Array<String>, String, Array<String>)

public init(args: Array<String>, shortArgFormat: String, longArgList: Array<String>)

功能:构造 ArgOpt 实例,并从短参名字符串中解析短参名、从列表的字符串中解析长参名,若解析成功,则依据解析出的参数名从参数 args 指定的命令行参数中解析参数名的对应取值。

参数:

  • args: Array<String> - 待解析的命令行参数字符串数组。
  • shortArgFormat: String - 包含短参名的字符串。
  • longArgList: Array<String> - 包含长参名的字符串数组。

异常:

  • IllegalArgumentException - 当短参名字符串不符合规范,或字符串数组中的长参名字符串不符合规范,或字符串不符合 UTF-8 编码,或不存在该 Unicode 字符时,抛出异常。

init(String)

public init(shortArgFormat: String)

功能:构造 ArgOpt 实例,并从短参名字符串中解析短参名。

参数:

  • shortArgFormat: String - 包含短参名的字符串。

异常:

  • IllegalArgumentException - 当短参名字符串不符合规范时,或字符串不符合 UTF-8 编码,或不存在该 Unicode 字符时,抛出异常。

init(String, Array<String>)

public init(shortArgFormat: String, longArgList: Array<String>)

功能:构造 ArgOpt 实例,并从短参名字符串中解析短参名、从列表的字符串中解析长参名。

参数:

  • shortArgFormat: String - 包含短参名的字符串。
  • longArgList: Array<String> - 包含长参名的字符串数组。

异常:

  • IllegalArgumentException - 当短参名字符串不符合规范,或字符串数组中的长参名字符串不符合规范时,或字符串不符合 UTF-8 编码,或不存在该 Unicode 字符时,抛出异常。

func getArg(String)

public func getArg(arg: String): Option<String>

功能:返回参数 arg 指定参数的解析值。

参数:

  • arg: String - 前缀和参数名组成的字符串(可省略前缀)。

返回值:

func getArgumentsMap()

public func getArgumentsMap(): HashMap<String, String>

功能:获取所有已解析的参数名和参数值,以哈希表的形式返回。

返回值:

func getUnparseArgs()

public func getUnparseArgs(): Array<String>

功能:返回未被解析的命令行参数。

返回值:

  • Array<String> - 存放没有被解析的字符串的数组。

长命令行参数解析

import std.argopt.*

main() {
    let shortArgs: Array<String> = ["--test1=abc", "--test2=123", "--test3 xyz"]
    let shortArgName: String = ""
    let longArgName: Array<String> = ["--test1=", "test2=", "--test3="]
    let ao: ArgOpt = ArgOpt(shortArgs, shortArgName, longArgName)
    println(ao.getArg("--test1") ?? "None")
    println(ao.getArg("--test2") ?? "None")
    println(ao.getArg("--test3") ?? "None")
}

运行结果

abc
123
None

短命令行参数解析

import std.argopt.*

main() {
    let shortArgs: Array<String> = ["-a123", "-bofo", "-cccc"]
    let shortArgName: String = "a:b:c"
    let longArgName: Array<String> = Array<String>()
    let ao: ArgOpt = ArgOpt(shortArgs, shortArgName, longArgName)
    println(ao.getArg("-a") ?? "None")
    println(ao.getArg("-b") ?? "None")
    println(ao.getArg("-c") ?? "None")
}

运行结果

123
ofo
None

std.ast 包

功能介绍

ast 包主要包含了仓颉源码的语法解析器和仓颉语法树节点,提供语法解析函数。可将仓颉源码的词法单元 (Tokens) 解析为抽象语法树 (Abstract Syntax Tree) 节点对象。

仓颉 ast 包提供了 Macro With Context 的相关函数,用于在宏展开时获取展开过程中的上下文相关信息。在嵌套宏场景下,内层宏可以调用库函数 assertParentContext(String) 来保证内层宏调用一定嵌套在特定的外层宏调用中。如果内层宏调用这个函数时没有嵌套在给定的外层宏调用中,该函数将抛出一个错误。同时,函数 insideParentContext(String) 也用于检查内层宏调用是否嵌套在特定的外层宏调用中,但是返回一个布尔值。Macro With Context 的相关函数只能作为函数被直接调用,不能赋值给变量,不能作为实参或返回值使用。

Macro With Context 相关函数如下:

API 列表

函数

函数名功能
assertParentContext(String)  检查当前宏调用是否在特定的宏调用内;若检查不符合预期,编译器出现一个错误提示。
cangjieLex(String)  将字符串转换为 Tokens 类型。
cangjieLex(String, Bool)  将字符串转换为 Tokens 类型。
compareTokens(Tokens, Tokens)  用于比较两个 Tokens 是否一致。
diagReport(DiagReportLevel, Tokens, String, String)  报错接口,在编译过程的宏展开阶段输出错误提示信息,支持 WARNINGERROR 两个等级的报错。
getChildMessages(String)  获取特定内层宏发送的信息。
getTokenKind(UInt16)  将词法单元种类序号转化为 TokenKind
insideParentContext(String)  检查当前宏调用是否在特定的宏调用内,返回一个布尔值。
parseDecl(Tokens, String)  用于解析一组词法单元,获取一个 Decl 类型的节点。
parseDeclFragment(Tokens, Int64)  用于解析一组词法单元,获取一个 Decl 类型的节点和继续解析节点的索引。
parseExpr(Tokens)  用于解析一组词法单元,获取一个 Expr 类型的节点。
parseExprFragment(Tokens, Int64)  用于解析一组词法单元,获取一个 Expr 类型的节点和继续解析节点的索引。
parsePattern(Tokens)  用于解析一组词法单元,获取一个 Pattern 类型的节点。
parsePatternFragment(Tokens, Int64)  用于解析一组词法单元,获取一个 Pattern 类型的节点和继续解析节点的索引。
parseProgram(Tokens)  用于解析单个仓颉文件的源码,获取一个 Program 类型的节点。
parseType(Tokens)  用于解析一组词法单元,获取一个 TypeNode 类型的节点。
parseTypeFragment(Tokens, Int64)  用于解析一组词法单元,获取一个 TypeNode 类型的节点和继续解析节点的索引。
setItem(String, Bool)  内层宏通过该接口发送 Bool 类型的信息到外层宏。
setItem(String, Int64)  内层宏通过该接口发送 Int64 类型的信息到外层宏。
setItem(String, String)  内层宏通过该接口发送 String 类型的信息到外层宏。
setItem(String, Tokens)  内层宏通过该接口发送 Tokens 类型的信息到外层宏。

接口

接口名功能
ToBytes提供对应类型的序列化功能。
ToTokens实现对应类型的实例到 Tokens 类型转换的接口,作为支持quote插值操作必须实现的接口。

类名功能
Annotation表示编译器内置的注解节点。
Argument表示函数调用的实参节点。
ArrayLiteral表示 Array 字面量节点。
AsExpr表示一个类型检查表达式。
AssignExpr表示赋值表达式节点。
BinaryExpr表示一个二元操作表达式节点。
Block表示块节点。
Body表示 Class 类型、 Struct 类型、 Interface 类型以及扩展中由 {} 和内部的一组声明节点组成的结构。
CallExpr表示函数调用节点节点。
ClassDecl类定义节点。
ConstPattern表示常量模式节点。
Constructor表示 enum 类型中的 Constructor 节点。
Decl所有声明节点的父类,继承自 Node 节点,提供了所有声明节点的通用接口。
DoWhileExpr表示 do-while 表达式。
EnumDecl表示一个 Enum 定义节点。
EnumPattern表示 enum 模式节点。
ExceptTypePattern表示一个用于异常模式状态下的节点。
Expr所有表达式节点的父类,继承自 Node 节点。
ExtendDecl表示一个扩展定义节点。
ForInExpr表示 for-in 表达式。
FuncDecl表示一个函数定义节点。
FuncParam表示函数参数节点,包括非命名参数和命名参数。
FuncType表示函数类型节点。
GenericConstraint表示一个泛型约束节点。
GenericParam表示一个类型形参节点。
IfExpr表示条件表达式。
ImportContent表示包导入节点中的导入项。
ImportList表示包导入节点。
IncOrDecExpr表示包含自增操作符(++)或自减操作符(--)的表达式。
InterfaceDecl表示接口定义节点。
IsExpr表示一个类型检查表达式。
JumpExpr表示循环表达式的循环体中的 breakcontinue
LambdaExpr表示 Lambda 表达式,是一个匿名的函数。
LetPatternExpr表示 let 声明的解构匹配节点。
LitConstExpr表示一个常量表达式节点。
MacroDecl表示一个宏定义节点。
MacroExpandDecl表示宏调用节点。
MacroExpandExpr表示宏调用节点。
MacroExpandParam表示宏调用节点。
MacroMessage记录内层宏发送的信息。
MainDecl表示一个 main 函数定义节点。
MatchCase表示一个 MatchCase 类型。
MatchExpr表示模式匹配表达式实现模式匹配。
MemberAccess表示成员访问表达式。
Modifier表示该定义具备某些特性,通常放在定义处的最前端。
Node所有仓颉语法树节点的父类。
OptionalExpr表示一个带有问号操作符的表达式节点。
PackageHeader表示包声明节点。
ParenExpr表示一个括号表达式节点,是指使用圆括号括起来的表达式。
ParenType表示括号类型节点。
Pattern所有模式匹配节点的父类,继承自 Node 节点。
PrefixType表示带问号的前缀类型节点。
PrimaryCtorDecl表示一个主构造函数节点。
PrimitiveType表示一个基本类型节点。
PrimitiveTypeExpr表示基本类型表达式节点。
Program表示一个仓颉源码文件节点。
PropDecl表示一个属性定义节点。
QualifiedType表示一个用户自定义成员类型。
QuoteExpr表示 quote 表达式节点。
QuoteToken表示 quote 表达式节点内任意合法的 token
RangeExpr表示包含区间操作符的表达式。
RefExpr表示一个使用自定义类型节点相关的表达式节点。
RefType表示一个用户自定义类型节点。
ReturnExpr表示 return 表达式节点。
SpawnExpr表示 Spawn 表达式。
StructDecl表示一个 Struct 节点。
SubscriptExpr表示索引访问表达式。
SynchronizedExpr表示 synchronized 表达式。
ThisType表示 This 类型节点。
ThrowExpr表示 throw 表达式节点。
TokensToken 序列进行封装的类型。
TokensIterator实现 Tokens 的迭代器功能。
TrailingClosureExpr表示尾随 Lambda 节点。
TryExpr表示 try 表达式节点。
TupleLiteral表示元组字面量节点。
TuplePattern表示 Tuple 模式节点。
TupleType表示元组类型节点。
TypeAliasDecl表示类型别名节点。
TypeConvExpr表示类型转换表达式。
TypeNode所有类型节点的父类,继承自 Node
TypePattern表示类型模式节点。
UnaryExpr表示一个一元操作表达式节点。
VArrayExpr表示 VArray 的实例节点。
VArrayType表示 VArray 类型节点。
VarDecl表示变量定义节点。
VarOrEnumPattern表示当模式的标识符为 Enum 构造器时的节点。
VarPattern表示绑定模式节点。
Visitor一个抽象类,其内部默认定义了访问不同类型 AST 节点访问(visit)函数。
WhileExpr表示 while 表达式。
WildcardExpr表示通配符表达式节点。
WildcardPattern表示通配符模式节点。

枚举

枚举名功能
DiagReportLevel表示报错接口的信息等级,支持 ERRORWARNING 两种格式。
ImportKind表示导入语句的类型,包括单导入、别名导入、全导入和多导入四种类型。
TokenKind表示仓颉编译内部所有的词法结构,包括符号、关键字、标识符、换行等。

结构体

结构体名功能
Position表示位置信息的数据结构,包含文件ID,行号和列号。
Token词法单元类型。

异常类

异常类名功能
ASTExceptionast 库的异常类,在 ast 库调用过程中发生异常时使用。
MacroContextExceptionast 库的上下文宏异常类,在上下文宏的相关接口中发生异常时使用。
ParseASTExceptionast 库的解析异常类,在节点解析过程中发生异常时使用。

函数

func assertParentContext(String)

public func assertParentContext(parentMacroName: String): Unit

功能:检查当前宏调用是否在特定的宏调用内。若检查不符合预期,编译器出现一个错误提示。

注意:

该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。

参数:

  • parentMacroName: String - 待检查的外层宏调用的名字。

func cangjieLex(String)

public func cangjieLex(code: String): Tokens

功能:将字符串转换为 Tokens 对象。

参数:

  • code: String - 待词法解析的字符串。

返回值:

异常:

func cangjieLex(String, Bool)

public func cangjieLex(code: String, truncated: Bool): Tokens

功能:将字符串转换为 Tokens 对象。

参数:

  • code: String - 待词法解析的字符串。
  • truncated: Bool - 是否删减解析后 Tokens 中的 Token(END)。

返回值:

异常:

func compareTokens(Tokens, Tokens)

public func compareTokens(tokens1: Tokens, tokens2: Tokens): Bool

功能:用于比较两个Tokens是否一致。

参数:

返回值:

  • Bool - 如果两个 Tokens 内容相同(除了换行符、结束符和位置信息)则返回 true

func diagReport(DiagReportLevel, Tokens, String, String)

public func diagReport(level: DiagReportLevel, tokens: Tokens, message: String, hint: String): Unit

功能:报错接口,在编译过程的宏展开阶段输出错误提示信息,支持 WARNINGERROR 两个等级的报错。

注意:

  • 该接口在 错误等级为 ERROR 时会终止编译过程,但不会终止宏展开过程,建议用户调用接口后直接 return 或者抛出异常来终止宏展开过程。
  • 该接口会按照 cjc 标准报错的接口,将传入的 tokens 所在行的代码列出,并对 tokens 的内容用波浪线进行标注, message 信息将展示在首行, hint 信息将紧跟波浪线进行展示。
  • 报错引用的源码内容目前仅依据第一个 Token 的开始位置和最后一个 Token 的结束位置确定,不校验中间 Token 位置信息的一致性。
  • 该接口在非宏展开过程中调用无效,参见示例代码

参数:

  • level: DiagReportLevel - 报错信息等级。
  • tokens: Tokens - 报错信息中所引用源码内容对应的 Tokens
  • message: String - 报错的主信息。
  • hint: String - 辅助提示信息。

异常:

  • ASTException - 当输入的 Tokens 存在以下错误时,抛出异常。

    • 输入的 Tokens 为空;
    • 输入的 Tokens 中的 Token 来自于不同的源文件;
    • 输入的 Tokens 中首位 Token 位置早于末位 Token 位置;
    • 输入的 Tokens 中的 Token 位置范围超出了宏调用的位置范围。

func getChildMessages(String)

public func getChildMessages(children:String): ArrayList<MacroMessage>

功能:获取特定内层宏发送的信息。

注意:

该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。

参数:

  • children: String - 待接收信息的内层宏名称。

返回值:

func getTokenKind(UInt16)

public func getTokenKind(no: UInt16): TokenKind

功能:将词法单元种类序号转化为 TokenKind

参数:

  • no: UInt16 - 需要转换的序号。

返回值:

func insideParentContext(String)

public func insideParentContext(parentMacroName: String): Bool

功能:检查当前宏调用是否在特定的宏调用内,返回一个布尔值。

注意:

  • 在嵌套宏场景下,内层宏也可以通过发送键/值对的方式与外层宏通信。当内层宏执行时,通过调用标准库函数 setItem 向外层宏发送信息;随后,当外层宏执行时,调用标准库函数 getChildMessages 接收每一个内层宏发送的信息(一组键/值对映射)。
  • 该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。

参数:

  • parentMacroName: String - 待检查的外层宏调用的名字。

返回值:

  • Bool - 若当前宏嵌套在特定的宏调用内,返回 true。

func parseDecl(Tokens, String)

public func parseDecl(input: Tokens, astKind!: String = ""): Decl

功能:用于解析一组词法单元,获取一个 Decl 类型的节点。

参数:

  • input: Tokens - 待解析源码的词法单元。
  • astKind!: String - 用于指定解析特定的节点类型,有效支持的值为:PrimaryCtorDeclPropMemberDecl
    • PrimaryCtorDecl: 解析主构造函数。
    • PropMemberDecl: 解析prop声明的getter和setter函数。

返回值:

异常:

示例:

  1. 以下代码展示 astKind 设为 PropMemberDecl 的案例。在这个参数下,可以使用 parseDecl 解析 prop 的getter和setter函数,解析结果为 FuncDecl 类型(如果不设置astKind,则会因为没有 func 关键字而无法解析)。

    import std.ast.*
    
    main() {
        let getter = quote( get() { _val } )
        let setter = quote( set(v) { _val = v })
        let getterDecl = parseDecl(getter, astKind: "PropMemberDecl")
        let setterDecl = parseDecl(setter, astKind: "PropMemberDecl")
        println((getterDecl as FuncDecl).getOrThrow().block.toTokens())
        println((setterDecl as FuncDecl).getOrThrow().block.toTokens())
    }
    

    运行结果:

    {
        _val
    }
    
    {
        _val = v
    }
    
  2. 以下代码展示 astKind 设为 PrimaryCtorDecl 的案例。在这个参数下,可以使用 parseDecl 解析主构造函数节点,解析结果为 PrimaryCtorDecl 类型(如果不设置 astKind,则会因为没有 func 关键字而无法解析)。

    import std.ast.*
    
    main() {
        let ctor = quote(
            Point(var x: Int32, var y: Int32) {}
        )
        let ctorDecl = parseDecl(ctor, astKind: "PrimaryCtorDecl")
        println(ctorDecl is PrimaryCtorDecl)
        println(ctorDecl.toTokens())
    }
    

    运行结果:

    true
    Point(var x: Int32, var y: Int32) {
    }
    

func parseDeclFragment(Tokens, Int64)

public func parseDeclFragment(input: Tokens, startFrom !: Int64 = 0): (Decl, Int64)

功能:用于解析一组词法单元,获取一个 Decl 类型的节点和继续解析节点的索引。

参数:

  • input: Tokens - 待解析源码的词法单元。
  • startFrom!: Int64 - 起始位置。

返回值:

  • (Decl, Int64) - 语法树节点,继续解析的位置。

异常:

func parseExpr(Tokens)

public func parseExpr(input: Tokens): Expr

功能:用于解析一组词法单元,获取一个 Expr 类型的节点。

参数:

  • input: Tokens - 待解析源码的词法单元。

返回值:

异常:

func parseExprFragment(Tokens, Int64)

public func parseExprFragment(input: Tokens, startFrom !: Int64 = 0): (Expr, Int64)

功能:用于解析一组词法单元,获取一个 Expr 类型的节点和继续解析节点的索引。

参数:

  • input: Tokens - 待解析源码的词法单元。
  • startFrom!: Int64 - 起始位置。

返回值:

  • (Expr, Int64) - 语法树节点,继续解析的位置。

异常:

func parsePattern(Tokens)

public func parsePattern(input: Tokens): Pattern

功能:用于解析一组词法单元,获取一个 Pattern 类型的节点。

参数:

  • input: Tokens - 待解析源码的词法单元。

返回值:

异常:

func parsePatternFragment(Tokens, Int64)

public func parsePatternFragment(input: Tokens, startFrom !: Int64 = 0): (Pattern, Int64)

功能:用于解析一组词法单元,获取一个 Pattern 类型的节点和继续解析节点的索引。

参数:

  • input: Tokens - 待解析源码的词法单元。
  • startFrom!: Int64 - 起始位置。

返回值:

  • (Pattern, Int64) - 语法树节点,继续解析的位置。

异常:

func parseProgram(Tokens)

public func parseProgram(input: Tokens): Program

功能:用于解析单个仓颉文件的源码,获取一个 Program 类型的节点。

参数:

  • input: Tokens - 待解析源码的词法单元。

返回值:

异常:

func parseType(Tokens)

public func parseType(input: Tokens): TypeNode

功能:用于解析一组词法单元,获取一个 TypeNode 类型的节点。

参数:

  • input: Tokens - 待解析源码的词法单元。

返回值:

异常:

func parseTypeFragment(Tokens, Int64)

public func parseTypeFragment(input: Tokens, startFrom !: Int64 = 0): (TypeNode, Int64)

功能:用于解析一组词法单元,获取一个 TypeNode 类型的节点和继续解析节点的索引。

参数:

  • input: Tokens - 待解析源码的词法单元。
  • startFrom!: Int64 - 起始位置。

返回值:

异常:

func setItem(String, Bool)

public func setItem(key: String, value: Bool): Unit

功能:内层宏通过该接口发送 Bool 类型的信息到外层宏。

注意:

该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。

参数:

  • key: String - 发送的关键字,用于检索信息。
  • value: Bool - 要发送的 Bool 类型的信息。

func setItem(String, Int64)

public func setItem(key: String, value: Int64): Unit

功能:内层宏通过该接口发送 Int64 类型的信息到外层宏。

注意:

该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。

参数:

  • key: String - 发送的关键字,用于检索信息。
  • value: Int64 - 要发送的 Int64 类型的信息。

func setItem(String, String)

public func setItem(key: String, value: String): Unit

功能:内层宏通过该接口发送 String 类型的信息到外层宏。

注意:

该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。

参数:

  • key: String - 发送的关键字,用于检索信息。
  • value: String - 要发送的 String 类型的信息。

func setItem(String, Tokens)

public func setItem(key: String, value: Tokens): Unit

功能:内层宏通过该接口发送 Tokens 类型的信息到外层宏。

注意:

该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。

参数:

  • key: String - 发送的关键字,用于检索信息。
  • value: Tokens - 要发送的 Tokens 类型的信息。

接口

interface ToBytes

public interface ToBytes {
    func toBytes(): Array<UInt8>
}

功能:提供对应类型的序列化功能。

func toBytes()

func toBytes(): Array<UInt8>

功能:提供对应类型的序列化功能。

返回值:

interface ToTokens

public interface ToTokens {
    func toTokens(): Tokens
}

功能:实现对应类型的实例到 Tokens 类型转换的接口,作为支持 quote 插值操作必须实现的接口。

func toTokens()

func toTokens(): Tokens

功能:实现对应类型的实例到 Tokens 类型的转换。

返回值:

extend Array <: ToTokens

extend<T> Array<T> <: ToTokens

功能:实现 Array 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Array 类型到 Tokens 类型的转换,仅支持数值类型、Rune 类型、Bool 类型、String 类型。

返回值:

extend ArrayList <: ToTokens

extend<T> ArrayList<T> <: ToTokens

功能:实现 ArrayList 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 ArrayList 类型到 Tokens 类型的转换,目前支持的类型有 DeclNodeConstructorArgumentFuncParamMatchCaseModifierAnnotationImportListPatternTypeNode等。

返回值:

extend Bool <: ToTokens

extend Bool <: ToTokens

功能:实现 Bool 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Bool 类型到 Tokens 类型的转换。

返回值:

extend Float16 <: ToTokens

extend Float16 <: ToTokens

功能:实现 Float16 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Float16 类型到 Tokens 类型的转换。

返回值:

extend Float32 <: ToTokens

extend Float32 <: ToTokens

功能:实现 Float32 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Float32 类型到 Tokens 类型的转换。

返回值:

extend Float64 <: ToTokens

extend Float64 <: ToTokens

功能:实现 Float64 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Float64 类型到 Tokens 类型的转换。

返回值:

extend Int16 <: ToTokens

extend Int16 <: ToTokens

功能:实现 Int16 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Int16 类型到 Tokens 类型的转换。

返回值:

extend Int32 <: ToTokens

extend Int32 <: ToTokens

功能:实现 Int32 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Int32 类型到 Tokens 类型的转换。

返回值:

extend Int64 <: ToTokens

extend Int64 <: ToTokens

功能:实现 Int64 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Int64 类型到 Tokens 类型的转换。

返回值:

extend Int8 <: ToTokens

extend Int8 <: ToTokens

功能:实现 Int8 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Int8 类型到 Tokens 类型的转换。

返回值:

extend Rune <: ToTokens

extend Rune <: ToTokens

功能:实现 Rune 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Rune 类型到 Tokens 类型的转换。

返回值:

extend String <: ToTokens

extend String <: ToTokens

功能:实现 String 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 String 类型到 Tokens 类型的转换。

返回值:

extend Token <: ToTokens

extend Token <: ToTokens

功能:实现 Token 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Token 类型到 Tokens 类型的转换。

返回值:

extend Tokens <: ToTokens

extend Tokens <: ToTokens

功能:实现 Tokens 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 Tokens 类型到 Tokens 类型的转换。

返回值:

extend UInt16 <: ToTokens

extend UInt16 <: ToTokens

功能:实现 UInt16 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 UInt16 类型到 Tokens 类型的转换。

返回值:

extend UInt32 <: ToTokens

extend UInt32 <: ToTokens

功能:实现 UInt32 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 UInt32 类型到 Tokens 类型的转换。

返回值:

extend UInt64 <: ToTokens

extend UInt64 <: ToTokens

功能:实现 UInt64 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 UInt64 类型到 Tokens 类型的转换。

返回值:

extend UInt8 <: ToTokens

extend UInt8 <: ToTokens

功能:实现 UInt8 类型到 Tokens 类型的转换。

父类型:

func toTokens()

public func toTokens(): Tokens

功能:实现 UInt8 类型到 Tokens 类型的转换。

返回值:

class Annotation

public class Annotation <: Node {
    public init()
    public init(inputs: Tokens)
}

功能:表示编译器内置的注解节点。

一个 Annotation 节点:@CallingConv[xxx], @Attribute[xxx], @When[condition]等。

父类型:

prop arguments

public mut prop arguments: ArrayList<Argument>

功能:获取或设置 Annotation 中的参数序列,如 @CallingConv[xxx] 中的 xxx

类型:ArrayList<Argument>

prop at

public mut prop at: Token

功能:获取或设置 Annotation 节点中的 @ 操作符。

类型:Token

异常:

prop attributes

public mut prop attributes: Tokens

功能:获取或设置 Attribute 中设置的属性值,仅用于 @Attribute,如 @Attribute[xxx] 中的 xxx

类型:Tokens

prop condition

public mut prop condition: Expr

功能:获取或设置条件编译中的条件表达式,用于 @When,如 @When[xxx] 中的 xxx

类型:Expr

异常:

prop identifier

public mut prop identifier: Token

功能:获取或设置 Annotation 节点的标识符,如 @CallingConv[xxx] 中的 CallingConv

类型:Token

init()

public init()

功能:构造一个默认的 Annotation 对象。

init(Tokens)

public init(inputs: Tokens)

功能:根据输入的词法单元,构造一个 Annotation 对象。

参数:

异常:

class Argument

public class Argument <: Node {
    public init()
}

功能:表示函数调用的实参节点。

例如 foo(arg:value) 中的 arg:value

父类型:

prop colon

public mut prop colon: Token

功能:获取或设置 Argument 节点中的操作符 ":",可能为 ILLEGAL 的词法单元。

类型:Token

异常:

prop expr

public mut prop expr: Expr

功能:获取或设置 Argument 节点中的表达式,如 arg:value 中的 value

类型:Expr

prop identifier

public mut prop identifier: Token

功能:获取或设置 Argument 节点中的标识符,如 arg:value 中的 arg,可能为 ILLEGAL 的词法单元。

类型:Token

prop keyword

public mut prop keyword: Token

功能:获取或设置 Argument 节点中的关键字 inout,可能为 ILLEGAL 的词法单元。

类型:Token

init()

public init()

功能:构造一个默认的 Argument 对象。

class ArrayLiteral

public class ArrayLiteral <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 Array 字面量节点。

ArrayLiteral 节点:使用格式 [element1, element2, ... , elementN] 表示, 每个 element 是一个表达式。

父类型:

prop elements

public mut prop elements: ArrayList<Expr>

功能:获取或设置 ArrayLiteral 中的表达式列表。

类型:ArrayList<Expr>

prop lSquare

public mut prop lSquare: Token

功能:获取或设置 ArrayLiteral 中的 "["。

类型:Token

异常:

prop rSquare

public mut prop rSquare: Token

功能:获取或设置 ArrayLiteral 中的 "]"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 ArrayLiteral 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ArrayLiteral 对象。

参数:

异常:

class AsExpr

public class AsExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个类型检查表达式。

一个 AsExpr 表达式:e as T,类型为 Option<T>。其中 e 可以是任何类型的表达式,T 可以是任何类型。

父类型:

prop expr

public mut prop expr: Expr

功能:获取或设置 AsExpr 节点中的表达式节点。

类型:Expr

prop keyword

public mut prop keyword: Token

功能:获取或设置 AsExpr 节点中的 as 操作符。

类型:Token

异常:

prop shiftType

public mut prop shiftType: TypeNode

功能:获取或设置 AsExpr 节点中的目标类型。

类型:TypeNode

init()

public init()

功能:构造一个默认的 AsExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 AsExpr 对象。

参数:

异常:

class AssignExpr

public class AssignExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示赋值表达式节点。

用于将左操作数的值修改为右操作数的值。一个 AssignExpr 节点:a = b

父类型:

prop assign

public mut prop assign: Token

功能:获取或设置 AssignExpr 节点中的赋值操作符(如 = 等)。

类型:Token

异常:

prop leftExpr

public mut prop leftExpr: Expr

功能:获取或设置 AssignExpr 节点中的左操作数。

类型:Expr

prop rightExpr

public mut prop rightExpr: Expr

功能:获取或设置 AssignExpr 节点中的右操作数。

类型:Expr

init()

public init()

功能:构造一个默认的 AssignExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 AssignExpr 对象。

参数:

异常:

class BinaryExpr

public class BinaryExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个二元操作表达式节点。

一个 BinaryExpr 节点:a + b, a - b 等。

父类型:

prop leftExpr

public mut prop leftExpr: Expr

功能:获取或设置 BinaryExpr 节点中操作符左侧的表达式节点。

类型:Expr

prop op

public mut prop op: Token

功能:获取或设置 BinaryExpr 节点中的二元操作符。

类型:Token

prop rightExpr

public mut prop rightExpr: Expr

功能:获取或设置 BinaryExpr 节点中操作符右侧的表达式节点。

类型:Expr

init()

public init()

功能:构造一个默认的 BinaryExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 BinaryExpr 对象。

参数:

异常:

class Block

public class Block <: Expr {
    public init()
}

功能:表示块节点。

Block 由一对匹配的大括号及其中可选的表达式声明序列组成的结构,简称 “块”。

父类型:

prop lBrace

public mut prop lBrace: Token

功能:获取或设置 Block 的 "{"。

类型:Token

异常:

prop nodes

public mut prop nodes: ArrayList<Node>

功能:获取或设置 Block 中的表达式或声明序列。

类型:ArrayList<Node>

prop rBrace

public mut prop rBrace: Token

功能:获取或设置 Block 的 "}"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 Block 对象。

说明:

Block 节点无法脱离表达式或声明节点单独存在,因此不提供其他的构造函数。

class Body

public class Body <: Node {
    public init()
    public init(decls: ArrayList<Decl>)
}

功能:表示 Class 类型、 Struct 类型、 Interface 类型以及扩展中由 {} 和内部的一组声明节点组成的结构。

父类型:

prop decls

public mut prop decls: ArrayList<Decl>

功能:获取或设置 Body 内的声明节点集合。

类型:ArrayList<Decl>

prop lBrace

public mut prop lBrace: Token

功能:获取或设置 { 词法单元。

类型:Token

异常:

prop rBrace

public mut prop rBrace: Token

功能:获取或设置 } 词法单元。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 Body 对象。

init(ArrayList<Decl>)

public init(decls: ArrayList<Decl>)

功能:构造一个 Body 对象。

参数:

class CallExpr

public class CallExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示函数调用节点节点。

一个 CallExpr 节点包括一个表达式后面紧跟参数列表,例如 foo(100)

父类型:

prop arguments

public mut prop arguments: ArrayList<Argument>

功能:获取或设置 CallExpr 节点中函数参数。

类型:ArrayList<Argument>

prop callFunc

public mut prop callFunc: Expr

功能:获取或设置 CallExpr 节点中的函数调用节点。

类型:Expr

prop lParen

public mut prop lParen: Token

功能:获取或设置 CallExpr 节点中的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 CallExpr 节点中的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 CallExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 CallExpr 对象。

参数:

异常:

class ClassDecl

public class ClassDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:类定义节点。

类的定义使用 class 关键字,定义依次为:可缺省的修饰符、class 关键字、class 名、可选的类型参数、是否指定父类或父接口、可选的泛型约束、类体的定义。

父类型:

prop body

public mut prop body: Body

功能:获取或设置 ClassDecl 节点的类体。

类型:Body

prop superTypeBitAnds

public mut prop superTypeBitAnds: Tokens

功能:获取或设置 ClassDecl 节点的父类或父接口声明中的 & 操作符的词法单元序列,可能为空。

类型:Tokens

异常:

prop superTypes

public mut prop superTypes: ArrayList<TypeNode>

功能:获取或设置 ClassDecl 节点的父类或者父接口。

类型:ArrayList<TypeNode>

prop upperBound

public mut prop upperBound: Token

功能:获取或设置 <: 操作符。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 ClassDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ClassDecl 对象。

参数:

异常:

class ConstPattern

public class ConstPattern <: Pattern {
    public init()
    public init(inputs: Tokens)
}

功能:表示常量模式节点。

常量模式可以是整数字面量、字符字节字面量、浮点数字面量、字符字面量、布尔字面量、字符串字面量等字面量,如 case 1 => 0 中的 1

父类型:

prop litConstExpr

public mut prop litConstExpr: LitConstExpr

功能:获取或设置 ConstPattern 节点中的字面量表达式。

类型:LitConstExpr

init()

public init()

功能:构造一个默认的 ConstPattern 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ConstPattern 对象。

参数:

异常:

class Constructor

public class Constructor <: Node {
    public init()
}

功能:表示 enum 类型中的 Constructor 节点。

一个 Constructor 节点:enum TimeUnit { Year | Month(Float32, Float32)} 中的 Year 和 Month(Float32, Float32)。

说明:

Constructor 可以没有参数,也可以有一组不同类型的参数。

父类型:

prop identifier

public mut prop identifier: Token

功能:获取或设置 Constructor 的标识符词法单元。

类型:Token

prop lParen

public mut prop lParen: Token

功能:获取或设置 Constructor 节点中的 "(" 词法单元。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 Constructor 节点中的 ")" 词法单元。

类型:Token

异常:

prop typeArguments

public mut prop typeArguments: ArrayList<TypeNode>

功能:获取或设置 Constructor 节点可选的参数类型节点的集合。

类型:ArrayList<TypeNode>

init()

public init()

功能:构造一个默认的 Constructor 对象。

class Decl

public open class Decl <: Node

功能:所有声明节点的父类,继承自 Node 节点,提供了所有声明节点的通用接口。

说明:

类定义、接口定义、函数定义、变量定义、枚举定义、结构体定义、扩展定义、类型别名定义、宏定义等都属于 Decl 节点。

父类型:

prop annotations

public mut prop annotations: ArrayList<Annotation>

功能:获取或设置作用于 Decl 节点的注解列表。

类型:ArrayList<Annotation>

prop constraintCommas

public mut prop constraintCommas: Tokens

功能:获取或设置 Decl 节点中的 "," 词法单元序列,可能为空。

类型:Tokens

异常:

prop genericConstraint

public mut prop genericConstraint: ArrayList<GenericConstraint>

功能:获取或设置定义节点的泛型约束,可能为空,如 func foo<T>() where T <: Comparable<T> {} 中的 where T <: Comparable<T>

类型:ArrayList<GenericConstraint>

prop genericParam

public mut prop genericParam: GenericParam

功能:获取或设置形参列表,类型形参列表由 <> 括起,多个类型形参之间用逗号分隔。

类型:GenericParam

异常:

  • ASTException - 当节点未定义类型形参列表时,抛出异常。

prop identifier

public mut open prop identifier: Token

功能:获取或设置定义节点的标识符,如 class foo {} 中的 foo

类型:Token

prop isGenericDecl()

public mut prop isGenericDecl: Bool

功能:判断是否是一个泛型节点。

类型:Bool - 是一个泛型节点为 true;反之为 false。

prop keyword

public mut prop keyword: Token

功能:获取或设置定义节点的关键字。

类型:Token

prop modifiers

public mut prop modifiers: ArrayList<Modifier>

功能:获取或设置修饰节点的修饰符列表。

类型:ArrayList<Modifier>

func getAttrs()

public func getAttrs(): Tokens

功能:获取当前节点的属性(一般通过内置的 Attribute 来设置某个声明设置属性值)。

返回值:

  • Tokens - 当前节点的属性。

func hasAttr(String)

public func hasAttr(attr: String): Bool

功能:判断当前节点是否具有某个属性(一般通过内置的 Attribute 来设置某个声明的属性值)。

参数:

  • attr: String - 将要判断是否存在于该节点的属性。

返回值:

  • Bool - 当前节点具有该属性时,返回 true;反之,返回 false。

class DoWhileExpr

public class DoWhileExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 do-while 表达式。

父类型:

prop block

public mut prop block: Block

功能:获取或设置 DoWhileExpr 中的块表达式。

类型:Block

prop condition

public mut prop condition: Expr

功能:获取或设置关键字 DoWhileExpr 中的条件表达式。

类型:Expr

prop keywordD

public mut prop keywordD: Token

功能:获取或设置 DoWhileExpr 节点中 do 关键字,其中 keywordD 中的 D 为关键字 do 的首字母大写,代表关键字 do

类型:Token

异常:

prop keywordW

public mut prop keywordW: Token

功能:获取或设置 DoWhileExpr 节点中 while 关键字,其中 keywordW 中的 W 为关键字 while 的首字母大写,代表关键字 while

类型:Token

异常:

prop lParen

public mut prop lParen: Token

功能:获取或设置 DoWhileExprwhile 关键字之后的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 DoWhileExprwhile 关键字之后的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 DoWhileExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 DoWhileExpr 对象。

参数:

异常:

class EnumDecl

public class EnumDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个 Enum 定义节点。

Enum 的定义使用 enum 关键字,定义依次为:可缺省的修饰符、enum 关键字、enum 名、可选的类型参数、是否指定父接口、可选的泛型约束、enum 体的定义。

父类型:

prop constructors

public mut prop constructors: ArrayList<Constructor>

功能:获取或设置 EnumDecl 节点内 constructor 的成员。

类型:ArrayList<Constructor>

prop decls

public mut prop decls: ArrayList<Decl>

功能:获取或设置 EnumDecl 节点内除 constructor 的其它成员。

类型:ArrayList<Decl>

prop lBrace

public mut prop lBrace: Token

功能:获取或设置 EnumDecl 节点的 { 词法单元类型。

类型:Token

异常:

prop rBrace

public mut prop rBrace: Token

功能:获取或设置 EnumDecl 节点的 } 词法单元类型。

类型:Token

异常:

prop superTypeBitAnds

public mut prop superTypeBitAnds: Tokens

功能:获取或设置 EnumDecl 节点的父接口声明中的 & 操作符的词法单元序列,可能为空。

类型:Tokens

异常:

prop superTypes

public mut prop superTypes: ArrayList<TypeNode>

功能:获取或设置 EnumDecl 节点的父接口。

类型:ArrayList<TypeNode>

prop upperBound

public mut prop upperBound: Token

功能:获取或设置 <: 操作符。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 EnumDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 EnumDecl 对象。

参数:

异常:

class EnumPattern

public class EnumPattern <: Pattern {
    public init()
    public init(inputs: Tokens)
}

功能:表示 enum 模式节点。

用于匹配 enum 的 constructor, 如 case Year(n) => 1 中的 Year(n)

父类型:

prop commas

public mut prop commas: Tokens

功能:获取或设置 EnumPattern 节点中的 "," 词法单元序列,可能为空。

类型:Tokens

异常:

prop constructor

public mut prop constructor: Expr

功能:获取或设置 EnumPattern 节点中的构造器表达式节点。

类型:Expr

prop lParen

public mut prop lParen: Token

功能:获取或设置 EnumPattern 节点中的 "(" 的词法单元。

类型:Token

异常:

prop patterns

public mut prop patterns: ArrayList<Pattern>

功能:获取或设置 EnumPattern 节点中有参构造器内的模式节点列表。

类型:ArrayList<Pattern>

prop rParen

public mut prop rParen: Token

功能:获取或设置 EnumPattern 节点中的 ")" 的词法单元。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 EnumPattern 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 EnumPattern 对象。

参数:

异常:

class ExceptTypePattern

public class ExceptTypePattern <: Pattern {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个用于异常模式状态下的节点。

例如 e: Exception1 | Exception2

父类型:

prop colon

public mut prop colon: Token

功能:获取或设置 ExceptTypePattern 节点中的 ":" 操作符的词法单元。

类型:Token

异常:

prop pattern

public mut prop pattern: Pattern

功能:获取或设置 ExceptTypePattern 节点中的模式节点。

类型:Pattern

prop types

public mut prop types: ArrayList<TypeNode>

功能:获取或设置 ExceptTypePattern 节点中有类型列表。

类型:ArrayList<TypeNode>

init()

public init()

功能:构造一个默认的 ExceptTypePattern 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ExceptTypePattern 对象。

参数:

异常:

class Expr

public open class Expr <: Node

功能:所有表达式节点的父类,继承自 Node 节点。

表达式节点的 toTokens 方法会根据操作符优先级添加括号,例如已有一个 BinaryExpr 节点 a * b, 用户将左表达式内容 a 修改为 a + 1,修改后 toTokens 方法会为左表达式添加括号,toTokens 输出为 (a + 1) * b。

父类型:

class ExtendDecl

public class ExtendDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个扩展定义节点。

扩展的定义使用 extend 关键字,扩展定义依次为:extend 关键字、扩展类型、是否指定父接口、可选的泛型约束、扩展体的定义。

父类型:

prop body

public mut prop body: Body

功能:获取或设置 ExtendDecl 节点的类体。

类型:Body

prop extendType

public mut prop extendType: TypeNode

功能:获取或设置被扩展的类型。

类型:TypeNode

prop identifier

public mut override prop identifier: Token

功能:ExtendDecl 节点继承 Decl 节点,但是不支持 identifier 属性,使用时会抛出异常。

类型:Token

异常:

  • ASTException - 当使用 identifier 属性时,抛出异常。

prop superTypeBitAnds

public mut prop superTypeBitAnds: Tokens

功能:获取或设置 ExtendDecl 节点的父接口声明中的 & 操作符的词法单元序列,可能为空。

类型:Tokens

异常:

prop superTypes

public mut prop superTypes: ArrayList<TypeNode>

功能:获取或设置 ExtendDecl 节点的父接口。

类型:ArrayList<TypeNode>

prop upperBound

public mut prop upperBound: Token

功能:获取或设置 <: 操作符。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 ExtendDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ExtendDecl 对象。

参数:

异常:

class ForInExpr

public class ForInExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 for-in 表达式。

ForInExpr 类型中,关键字 for 之后是 Pattern, 此后是一个 in 关键字和表达式节点,最后是一个执行循环体 Block

父类型:

prop block

public mut prop block: Block

功能:获取或设置 ForInExpr 中的循环体。

类型:Block

prop expr

public mut prop expr: Expr

功能:获取或设置 ForInExpr 中的表达式。

类型:Expr

prop keywordF

public mut prop keywordF: Token

功能:获取或设置 ForInExpr 中的关键字 for

类型:Token

异常:

prop keywordI

public mut prop keywordI: Token

功能:获取或设置 ForInExpr 中的关键字 in

类型:Token

异常:

prop keywordW

public mut prop keywordW: Token

功能:获取或设置 ForInExpr 中的关键字 where

类型:Token

异常:

prop lParen

public mut prop lParen: Token

功能:获取或设置 ForInExpr 中关键字 for 后的 "("。

类型:Token

异常:

prop pattern

public mut prop pattern: Pattern

功能:获取或设置 ForInExpr 中的 Pattern 节点。

类型:Pattern

prop patternGuard

public mut prop patternGuard: Expr

功能:获取或设置 ForInExpr 中的 patternGuard 条件表达式。

类型:Expr

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 ForInExpr 中的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 ForInExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ForInExpr 对象。

参数:

异常:

class FuncDecl

public class FuncDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个函数定义节点。

由可选的函数修饰符,关键字 func ,函数名,可选的类型形参列表,函数参数,可缺省的函数返回类型来定义一个函数,函数定义时必须有函数体,函数体是一个块。

父类型:

prop block

public mut prop block: Block

功能:获取或设置 FuncDecl 节点的函数体。

类型:Block

prop colon

public mut prop colon: Token

功能:获取或设置 FuncDecl 节点的冒号。

类型:Token

异常:

prop declType

public mut prop declType: TypeNode

功能:获取或设置 FuncDecl 节点的函数返回类型。

类型:TypeNode

异常:

prop funcParams

public mut prop funcParams: ArrayList<FuncParam>

功能:获取或设置 FuncDecl 节点的函数参数。

类型:ArrayList<FuncParam>

prop lParen

public mut prop lParen: Token

功能:获取或设置 FuncDecl 节点的 "("。

类型:Token

异常:

prop overloadOp

public mut prop overloadOp: Tokens

功能:获取或设置 FuncDecl 节点的重载操作符。

类型:Tokens

prop rParen

public mut prop rParen: Token

功能:获取或设置 FuncDecl 节点的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 FuncDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 FuncDecl 对象。

参数:

异常:

func isConst()

public func isConst(): Bool

功能:判断是否是一个 Const 类型的节点。

返回值:

  • Bool - 是一个 Const 类型的节点返回 true;反之,返回 false。

class FuncParam

public open class FuncParam <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示函数参数节点,包括非命名参数和命名参数。

一个 FuncParam 节点: func foo(a: Int64, b: Float64) {...} 中的 a: Int64b: Float64

父类型:

prop assign

public mut prop assign: Token

功能:获取或设置具有默认值的函数参数中的 =

类型:Token

异常:

prop colon

public mut prop colon: Token

功能:获取或设置置形参中的 ":"。

类型:Token

异常:

prop expr

public mut prop expr: Expr

功能:获取或设置具有默认值的函数参数的变量初始化节点。

类型:Expr

异常:

  • ASTException - 当函数参数没有进行初始化时,抛出异常。

prop not

public mut prop not: Token

功能:获取或设置命名形参中的 !

类型:Token

异常:

prop paramType

public mut prop paramType: TypeNode

功能:获取或设置函数参数的类型。

类型:TypeNode

init()

public init()

功能:构造一个默认的 FuncParam 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 FuncParam 对象。

参数:

异常:

func isMemberParam()

public func isMemberParam(): Bool

功能:当前的函数参数是否是主构造函数中的参数。

返回值:

  • Bool - 布尔类型,如果是主构造函数中的参数,返回 true

class FuncType

public class FuncType <: TypeNode {
    public init()
    public init(inputs: Tokens)
}

功能:表示函数类型节点。

由函数的参数类型和返回类型组成,参数类型与返回类型之间用 -> 分隔,如:(Int32) -> Unit

父类型:

prop arrow

public mut prop arrow: Token

功能:获取或设置 FuncType 节点参数类型与返回类型之间的 ->的词法单元。

类型:Token

异常:

prop commas

public mut prop commas: Tokens

功能:获取或设置 FuncType 节点中的 "," 词法单元序列,可能为空。

类型:Tokens

异常:

prop keyword

public mut prop keyword: Token

功能:获取或设置 FuncType 节点的中的关键字 CFunc 的词法单元,若不是一个 CFunc 类型,则获取一个 ILLEGAL 的词法单元。

类型:Token

prop lParen

public mut prop lParen: Token

功能:获取或设置 FuncType 节点的 "(" 的词法单元。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 FuncType 节点的 ")" 的词法单元。

类型:Token

异常:

prop returnType

public mut prop returnType: TypeNode

功能:获取或设置 FuncType 返回类型节点。

类型:TypeNode

prop types

public mut prop types: ArrayList<TypeNode>

功能:获取或设置 FuncType 节点中函数的参数类型列表。

类型:ArrayList<TypeNode>

init()

public init()

功能:构造一个默认的 FuncType 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 FuncType 对象。

参数:

异常:

class GenericConstraint

public class GenericConstraint <: Node {
    public init()
}

功能:表示一个泛型约束节点。

一个 GenericConstraint 节点:interface Enumerable<U> where U <: Bounded {} 中的 where U <: Bounded

说明:

通过 where 之后的 <: 运算符来声明,由一个下界与一个上界来组成。其中 <: 左边称为约束的下界,下界只能为类型变元。<: 右边称为约束上界,约束上界可以为类型。

父类型:

prop bitAnds

public mut prop bitAnds: Tokens

功能:获取或设置 GenericConstraint 节点中的 & 操作符的词法单元序列,可能为空。

类型:Tokens

异常:

prop keyword

public mut prop keyword: Token

功能:获取或设置 GenericConstraint 节点中关键字 where 词法单元,可能为 ILLEGAL 的词法单元。

类型:Token

异常:

prop typeArgument

public mut prop typeArgument: TypeNode

功能:获取或设置 GenericConstraint 节点中的约束下界。

类型:TypeNode

prop upperBound

public mut prop upperBound: Token

功能:获取或设置 GenericConstraint 节点中的 <: 运算符。

类型:Token

异常:

prop upperBounds

public mut prop upperBounds: ArrayList<TypeNode>

功能:获取或设置 GenericConstraint 节点约束上界的 TypeNode 类型节点的集合。

类型:ArrayList<TypeNode>

init()

public init()

功能:构造一个默认的 GenericConstraint 对象。

class GenericParam

public class GenericParam <: Node {
    public init()
    public init(parameters: Tokens)
}

功能:表示一个类型形参节点。

一个 GenericParam 节点:<T1, T2, T3>

说明:

类型形参用 <> 括起并用 "," 分隔多个类型形参名称。

父类型:

prop lAngle

public mut prop lAngle: Token

功能:获取或设置 GenericParam 节点中的左尖括号词法单元。

类型:Token

异常:

prop parameters

public mut prop parameters: Tokens

功能:获取或设置 GenericParam 节点中的类型形参的 Tokens 类型,可能为空,如 <T1, T2, T3> 中的 T1 T2T3

类型:Tokens

prop rAngle

public mut prop rAngle: Token

功能:获取或设置 GenericParam 节点中的右尖括号词法单元。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 GenericParam 对象。

init(Tokens)

public init(parameters: Tokens)

功能:构造一个 GenericParam 对象。

参数:

class IfExpr

public class IfExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示条件表达式。

可以根据判定条件是否成立来决定执行哪条代码分支。一个 IfExpr 节点中 if 是关键字,if 之后是一个小括号,小括号内可以是一个表达式或者一个 let 声明的解构匹配,接着是一个 BlockBlock 之后是可选的 else 分支。 else 分支以 else 关键字开始,后接新的 if 表达式或一个 Block

父类型:

prop condition

public mut prop condition: Expr

功能:获取或设置 IfExpr 节点中的 if 后的条件表达式。

类型:Expr

prop elseExpr

public mut prop elseExpr: Expr

功能:获取或设置 IfExpr 节点中 else 分支节点。

类型:Expr

异常:

prop ifBlock

public mut prop ifBlock: Block

功能:获取或设置 IfExpr 节点中的 if 后的 block 节点。

类型:Block

prop keywordE

public mut prop keywordE: Token

功能:获取或设置 IfExpr 节点中 else 关键字。

类型:Token

异常:

prop keywordI

public mut prop keywordI: Token

功能:获取或设置 IfExpr 节点中的 if 关键字。

类型:Token

异常:

prop lParen

public mut prop lParen: Token

功能:获取或设置 IfExpr 节点中的 if 后的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 IfExpr 节点中的 if 后的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 IfExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 IfExpr 对象。

参数:

异常:

class ImportContent

public class ImportContent <: Node {
    public init()
}

父类型:

prop importKind

public mut prop importKind: ImportKind

功能:获取或设置 ImportContent 节点中导入类型。

类型:ImportKind

prop prefixPaths

public mut prop prefixPaths: Tokens

功能:获取或设置 ImportContent 节点中完整包名的前缀部分的词法单元序列,可能为空。如 import a.b.c 中的 ab

类型:Tokens

prop prefixDots

public mut prop prefixDots: Tokens

功能:获取或设置 ImportContent 节点中完整包名中用于分隔每层子包的词法单元序列,可能为空。如 import a.b.c 中的两个 "."。

类型:Tokens

异常:

prop identifier

public mut prop identifier: Token

功能:获取或设置 ImportContent 节点中被导入的项,它可能是包中的顶层定义或声明,也可能是子包的名字。

类型:Token

prop importAlias

public mut prop importAlias: Tokens

功能:获取或设置 ImportContent 节点中导入的定义或声明的别名词法单元序列,只有 importKindImportKind.Alias 时非空。如:import packageName.xxx as yyy 中的 as yyy

类型:Tokens

prop lBrace

public mut prop lBrace: Token

功能:获取或设置 ImportContent 节点中的 { 操作符词法单元,只有 importKindImportKind.Multi 时非空。

类型:Token

异常:

prop items

public mut prop items: ArrayList<ImportContent>

功能:获取或设置 ImportContent 节点中被导入的所有项,只有 importKindImportKind.Multi 时非空。

类型:ArrayList<ImportContent>

prop commas

public mut prop commas: Tokens

功能:获取或设置 ImportContent 节点中的 "," 词法单元序列,只有 importKindImportKind.Multi 时非空。

类型:Tokens

异常:

prop rBrace

public mut prop rBrace: Token

功能:获取或设置 ImportContent 节点中的 } 操作符词法单元,只有 importKindImportKind.Multi 时非空。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 ImportContent 对象。

func isImportAlias()

public func isImportAlias(): Bool

功能:判断 ImportContent 节点是否对导入项取了别名。

返回值:

func isImportAll()

public func isImportAll(): Bool

功能:判断 ImportContent 节点是否为全导入。

返回值:

func isImportMulti()

public func isImportMulti(): Bool

功能:判断 ImportContent 节点是否导入了多个顶级定义或声明。

返回值:

func isImportSingle()

public func isImportSingle(): Bool

功能:判断 ImportContent 节点是否为单导入。

返回值:

class ImportList

public class ImportList <: Node {
    public init()
    public init(inputs: Tokens)
}

功能:表示包导入节点。

一个 ImportList 节点: import moduleName.packageName.foo as bar

说明:

导入节点以可选的访问性修饰符(public/protected/internal/private)加关键字 import 开头。以 import pkga.pkgb.item 为例,pkga.pkgb 为导入的顶级定义或声明所在的包的名字,item 为导入的顶级定义或声明。

父类型:

prop modifier

public mut prop modifier: Token

功能:获取或设置 ImportList 节点中的修饰符,可能为 ILLEGAL 的词法单元。

类型:Token

prop keywordI

public mut prop keywordI: Token

功能:获取或设置 ImportList 节点中的 import 关键字的词法单元,I 为关键字首字母。

类型:Token

prop content

public mut prop content: ImportContent

功能:获取或设置 ImportList 节点中的被导入的具体项。如 import a.b.c 中的 a.b.c 部分。

类型:ImportContent

init()

public init()

功能:构造一个默认的 ImportList 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ImportList 对象。

参数:

异常:

func isImportMulti()

public func isImportMulti(): Bool

功能:判断 ImportList 节点是否导入了多个顶级定义或声明。

返回值:

  • Bool - 如果 ImportList 节点导入了多个顶级定义或声明,返回 true;反之,返回 false。

class IncOrDecExpr

public class IncOrDecExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示包含自增操作符(++)或自减操作符(--)的表达式。

父类型:

prop expr

public mut prop expr: Expr

功能:获取或设置 IncOrDecExpr 中的表达式。

类型:Expr

prop op

public mut prop op: Token

功能:获取或设置 IncOrDecExpr 中的操作符。

类型:Token

init()

public init()

功能:构造一个默认的 IncOrDecExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 IncOrDecExpr 对象。

参数:

异常:

class InterfaceDecl

public class InterfaceDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示接口定义节点。

接口的定义使用 interface 关键字,接口定义依次为:可缺省的修饰符、interface 关键字、接口名、可选的类型参数、是否指定父接口、可选的泛型约束、接口体的定义。

父类型:

prop body

public mut prop body: Body

功能:获取或设置 InterfaceDecl 节点的类体。

类型:Body

prop superTypeBitAnds

public mut prop superTypeBitAnds: Tokens

功能:获取或设置 InterfaceDecl 节点的父接口声明中的 & 操作符的词法单元序列,可能为空。

类型:Tokens

异常:

prop superTypes

public mut prop superTypes: ArrayList<TypeNode>

功能:获取或设置 InterfaceDecl 节点的父接口。

类型:ArrayList<TypeNode>

prop upperBound

public mut prop upperBound: Token

功能:获取或设置 <: 操作符。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 InterfaceDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 InterfaceDecl 对象。

参数:

异常:

class IsExpr

public class IsExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个类型检查表达式。

一个 IsExpr 表达式:e is T,类型为 Bool。其中 e 可以是任何类型的表达式,T 可以是任何类型。

父类型:

prop expr

public mut prop expr: Expr

功能:获取或设置 IsExpr 节点中的表达式节点。

类型:Expr

prop keyword

public mut prop keyword: Token

功能:获取或设置 IsExpr 节点中的 is 操作符。

类型:Token

异常:

prop shiftType

public mut prop shiftType: TypeNode

功能:获取或设置 IsExpr 节点中的目标类型。

类型:TypeNode

init()

public init()

功能:构造一个默认的 IsExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 IsExpr 对象。

参数:

异常:

class JumpExpr

public class JumpExpr <: Expr {
    public init()
    public init(kind: Tokens)
}

功能:表示循环表达式的循环体中的 breakcontinue

父类型:

prop keyword

public mut prop keyword: Token

功能:获取或设置关键字。

类型:Token

init()

public init()

功能:构造一个默认的 JumpExpr 对象。

init(Tokens)

public init(kind: Tokens)

功能:构造一个 JumpExpr 对象。

参数:

异常:

class LambdaExpr

public class LambdaExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 Lambda 表达式,是一个匿名的函数。

一个 LambdaExpr 节点有两种形式,一种是有形参的,例如 {a: Int64 => e1; e2 },另一种是无形参的,例如 { => e1; e2 }

父类型:

prop doubleArrow

public mut prop doubleArrow: Token

功能:获取或设置 LambdaExpr 中的 =>

类型:Token

异常:

prop funcParams

public mut prop funcParams:  ArrayList<FuncParam>

功能:获取或设置 LambdaExpr 中的参数列表。

类型:ArrayList<FuncParam>

prop lBrace

public mut prop lBrace: Token

功能:获取或设置 LambdaExpr 中的 "{"。

类型:Token

异常:

prop nodes

public mut prop nodes: ArrayList<Node>

功能:获取或设置 LambdaExpr 中的表达式或声明节点。

类型:ArrayList<Node>

prop rBrace

public mut prop rBrace: Token

功能:获取或设置 LambdaExpr 中的 "}"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 LambdaExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 LambdaExpr 对象。

参数:

异常:

class LetPatternExpr

public class LetPatternExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 let 声明的解构匹配节点。

一个 LetPatternExpr 节点:if (let Some(v) <- x) 中的 let Some(v) <- x

父类型:

prop backArrow

public mut prop backArrow: Token

功能:获取或设置 LetPatternExpr 节点中 <- 操作符。

类型:Token

异常:

prop expr

public mut prop expr: Expr

功能:获取或设置 LetPatternExpr 节点中 <- 操作符之后的表达式。

类型:Expr

prop keyword

public mut prop keyword: Token

功能:获取或设置 LetPatternExpr 节点中 let 关键字。

类型:Token

异常:

prop pattern

public mut prop pattern: Pattern

功能:获取或设置 LetPatternExpr 节点中 let 之后的 pattern。

类型:Pattern

init()

public init()

功能:构造一个默认的 LetPatternExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 LetPatternExpr 对象。

参数:

异常:

class LitConstExpr

public class LitConstExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个常量表达式节点。

一个 LitConstExpr 表达式:"abc"123 等。

父类型:

prop literal

public mut prop literal: Token

功能:获取或设置 LitConstExpr 节点中的字面量。

类型:Token

init()

public init()

功能:构造一个默认的 LitConstExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 LitConstExpr 对象。

参数:

异常:

class MacroDecl

public class MacroDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个宏定义节点。

一个 MacroDecl 节点:public macro M(input: Tokens): Tokens {...}

父类型:

prop block

public mut prop block: Block

功能:获取或设置 MacroDecl 节点的函数体。

类型:Block

prop colon

public mut prop colon: Token

功能:获取或设置 MacroDecl 节点的冒号。

类型:Token

异常:

prop declType

public mut prop declType: TypeNode

功能:获取或设置 MacroDecl 节点的函数返回类型。

类型:TypeNode

异常:

prop funcParams

public mut prop funcParams: ArrayList<FuncParam>

功能:获取或设置 MacroDecl 节点的参数。

类型:ArrayList<FuncParam>

prop lParen

public mut prop lParen: Token

功能:获取或设置 MacroDecl 节点的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 MacroDecl 节点的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 MacroDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 MacroDecl 对象。

参数:

异常:

class MacroExpandDecl

public class MacroExpandDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示宏调用节点。

一个 MacroExpandDecl 节点: @M class A {}

父类型:

prop fullIdentifier

public mut prop fullIdentifier: Token

功能:获取或设置宏调用节点的完整标识符。

类型:Token

prop lParen

public mut prop lParen: Token

功能:获取或设置 MacroExpandDecl 宏调用的 "("。

类型:Token

异常:

prop lSquare

public mut prop lSquare: Token

功能:获取或设置 MacroExpandDecl 属性宏调用的 "["。

类型:Token

异常:

prop macroAttrs

public mut prop macroAttrs: Tokens

功能:获取或设置 MacroExpandDecl 属性宏调用的输入。

类型:Tokens

prop macroInputDecl

public mut prop macroInputDecl: Decl

功能:获取或设置 MacroExpandDecl 中的声明节点。

类型:Decl

异常:

prop macroInputs

public mut prop macroInputs: Tokens

功能:获取或设置 MacroExpandDecl 宏调用的输入。

类型:Tokens

prop rParen

public mut prop rParen: Token

功能:获取或设置 MacroExpandDecl 宏调用的 ")"。

类型:Token

异常:

prop rSquare

public mut prop rSquare: Token

功能:获取或设置 MacroExpandDecl 属性宏调用的 "]"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 MacroExpandDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 MacroExpandDecl 对象。

参数:

异常:

class MacroExpandExpr

public class MacroExpandExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示宏调用节点。

一个 MacroExpandExpr 节点: @M (a is Int64)

父类型:

prop at

public mut prop at: Token

功能:获取或设置 MacroExpandExpr 节点中的 @ 操作符。

类型:Token

异常:

prop identifier

public mut prop identifier: Token

功能:获取或设置宏调用节点的标识符。

类型:Token

prop lParen

public mut prop lParen: Token

功能:获取或设置 MacroExpandExpr 宏调用的 "("。

类型:Token

异常:

prop lSquare

public mut prop lSquare: Token

功能:获取或设置 MacroExpandExpr 属性宏调用的 "["。

类型:Token

异常:

prop macroAttrs

public mut prop macroAttrs: Tokens

功能:获取或设置 MacroExpandExpr 属性宏调用的输入。

类型:Tokens

prop macroInputs

public mut prop macroInputs: Tokens

功能:获取或设置 MacroExpandExpr 宏调用的输入。

类型:Tokens

prop rParen

public mut prop rParen: Token

功能:获取或设置 MacroExpandExpr 宏调用的 ")"。

类型:Token

异常:

prop rSquare

public mut prop rSquare: Token

功能:获取或设置 MacroExpandExpr 属性宏调用的 "]"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 MacroExpandExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 MacroExpandExpr 对象。

参数:

异常:

class MacroExpandParam

public class MacroExpandParam <: FuncParam {
    public init()
}

功能:表示宏调用节点。

一个 MacroExpandDecl 节点: func foo (@M a: Int64) 中的 @M a: Int64

父类型:

prop fullIdentifier

public mut prop fullIdentifier: Token

功能:获取或设置宏调用节点的完整标识符。

类型:Token

prop lParen

public mut prop lParen: Token

功能:获取或设置 MacroExpandParam 宏调用的 "("。

类型:Token

异常:

prop lSquare

public mut prop lSquare: Token

功能:获取或设置 MacroExpandParam 属性宏调用的 "["。

类型:Token

异常:

prop macroAttrs

public mut prop macroAttrs: Tokens

功能:获取或设置 MacroExpandParam 属性宏调用的输入。

类型:Tokens

prop macroInputDecl

public mut prop macroInputDecl: Decl

功能:获取或设置 MacroExpandParam 中的声明节点。

类型:Decl

异常:

prop macroInputs

public mut prop macroInputs: Tokens

功能:获取或设置 MacroExpandParam 宏调用的输入。

类型:Tokens

prop rParen

public mut prop rParen: Token

功能:获取或设置 MacroExpandParam 宏调用的 ")"。

类型:Token

异常:

prop rSquare

public mut prop rSquare: Token

功能:获取或设置 MacroExpandParam 属性宏调用的 "]"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 MacroExpandParam 对象。

class MacroMessage

public class MacroMessage

功能:记录内层宏发送的信息。

func getBool(String)

public func getBool(key: String): Bool

功能:获取对应 key 值的 Bool 类型信息。

参数:

  • key: String - 用于检索的关键字的名字。

返回值:

  • Bool - 返回存在 key 值对应的 Bool 类型的信息。

异常:

  • Exception - 当不存在 key 值对应的 Bool 类型的信息时,抛出异常。

func getInt64(String)

public func getInt64(key: String): Int64

功能:获取对应 key 值的 Int64 类型信息。

参数:

  • key: String - 用于检索的关键字的名字。

返回值:

  • Int64 - 返回存在 key 值对应的 Int64 类型的信息。

异常:

  • Exception - 当不存在 key 值对应的 Int64 类型的信息时,抛出异常。

func getString(String)

public func getString(key: String): String

功能:获取对应 key 值的 String 类型信息。

参数:

  • key: String - 用于检索的关键字的名字。

返回值:

  • String - 返回存在 key 值对应的 String 类型的信息。

异常:

  • Exception - 当不存在 key 值对应的 String 类型的信息时,抛出异常。

func getTokens(String)

public func getTokens(key: String): Tokens

功能:获取对应 key 值的 Tokens 类型信息。

参数:

  • key: String - 用于检索的关键字的名字。

返回值:

  • Tokens - 返回存在 key 值对应的 Tokens 类型的信息。

异常:

  • Exception - 当不存在 key 值对应的 Tokens 类型的信息时,抛出异常。

func hasItem(String)

public func hasItem(key: String): Bool

功能:检查是否有 key 值对应的相关信息。

参数:

  • key: String - 用于检索的关键字名字。

返回值:

  • Bool - 若存在 key 值对应的相关信息,返回 true;反之,返回 false。

class MainDecl

public class MainDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个 main 函数定义节点。

一个 MainDecl 节点:main() {}

父类型:

prop block

public mut prop block: Block

功能:获取或设置 MainDecl 节点的函数体。

类型:Block

prop colon

public mut prop colon: Token

功能:获取或设置 MainDecl 节点的冒号。

类型:Token

异常:

prop declType

public mut prop declType: TypeNode

功能:获取或设置 MainDecl 节点的函数返回类型。

类型:TypeNode

异常:

prop funcParams

public mut prop funcParams: ArrayList<FuncParam>

功能:获取或设置 MainDecl 节点的函数参数。

类型:ArrayList<FuncParam>

prop lParen

public mut prop lParen: Token

功能:获取或设置 MainDecl 节点的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 MainDecl 节点的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 MainDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 MainDecl 对象。

参数:

异常:

class MatchCase

public class MatchCase <: Node {
    public init()
}

功能:表示一个 MatchCase 类型。

一个 MatchCase 节点:case failScore where score > 0 => 0

说明:

  • MatchCase 以关键字 case 开头,后跟 Expr 或者一个或多个由 | 分隔的相同种类的 pattern,一个可选的 patternguard,一个 => 和一系列声明或表达式。
  • 该节点与 MatchExpr 存在强绑定关系。

父类型:

prop arrow

public mut prop arrow: Token

功能:获取或设置 MatchCase 中的 => 操作符的词法单元。

类型:Token

异常:

prop bitOrs

public mut prop bitOrs: Tokens

功能:获取或设置 MatchCase 中的 | 操作符的词法单元序列,可能为空。

类型:Tokens

异常:

prop block

public mut prop block: Block

功能:获取或设置 MatchCase 中的一系列声明或表达式节点。

类型:Block

prop expr

public mut prop expr: Expr

功能:获取或设置 MatchCase 中位于 case 后的表达式节点。

类型:Expr

异常:

prop keywordC

public mut prop keywordC: Token

功能:获取或设置 MatchCase 内的 case 关键字的词法单元。

类型:Token

异常:

prop keywordW

public mut prop keywordW: Token

功能:获取或设置 MatchCase 中可选的关键字 where 的词法单元,可能为 ILLEGAL 的词法单元。

类型:Token

异常:

prop patternGuard

public mut prop patternGuard: Expr

功能:获取或设置 MatchCase 中可选的 pattern guard 表达式节点。

类型:Expr

异常:

prop patterns

public mut prop patterns: ArrayList<Pattern>

功能:获取或设置 MatchCase 中位于 case 后的 pattern 列表。

类型:ArrayList<Pattern>

init()

public init()

功能:构造一个默认的 MatchCase 对象。

class MatchExpr

public class MatchExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示模式匹配表达式实现模式匹配。

模式匹配表达式分为带 selector 的 match 表达式和不带 selector 的 match 表达式。

父类型:

prop keyword

public mut prop keyword: Token

功能:获取或设置 MatchExpr 节点中 match 关键字。

类型:Token

异常:

prop lBrace

public mut prop lBrace: Token

功能:获取或设置 MatchExpr 之后的 "{"。

类型:Token

异常:

prop lParen

public mut prop lParen: Token

功能:获取或设置 MatchExpr 之后的 "("。

类型:Token

异常:

prop matchCases

public mut prop matchCases: ArrayList<MatchCase>

功能:获取或设置 MatchExpr 内的 matchCase, matchCase 以关键字 case 开头,后跟一个或者多个由 PatternExpr节点,具体见 MatchCase

类型:ArrayList<MatchCase>

prop rBrace

public mut prop rBrace: Token

功能:获取或设置 MatchExpr 之后的 "}"。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 MatchExpr 之后的 ")"。

类型:Token

异常:

prop selector

public mut prop selector: Expr

功能:获取或设置关键字 match 之后的 Expr

类型:Expr

异常:

  • ASTException - 当该表达式是一个不带 selector 的 match 表达式时,抛出异常。

init()

public init()

功能:构造一个默认的 MatchExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 MatchExpr 对象。

参数:

异常:

class MemberAccess

public class MemberAccess <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示成员访问表达式。

可以用于访问 class、interface、struct 等类型的成员。一个 MemberAccess 节点的形式为 T.aT 为成员访问表达式的主体,a 表示成员的名字。

父类型:

prop baseExpr

public mut prop baseExpr: Expr

功能:获取或设置 MemberAccess 节点的成员访问表达式主体。

类型:Expr

prop commas

public mut prop commas: Tokens

功能:获取或设置 MemberAccess 节点中的 "," 词法单元序列,可能为空。

类型:Tokens

异常:

prop dot

public mut prop dot: Token

功能:获取或设置 MemberAccess 节点中的 "."。

类型:Token

异常:

  • ASTException - 当设置的 Token 不是 "." 词法单元类型时,抛出异常。

prop field

public mut prop field: Token

功能:获取或设置 MemberAccess 节点成员的名字。

类型:Token

prop lAngle

public mut prop lAngle: Token

功能:获取或设置 MemberAccess 节点中的左尖括号。

类型:Token

异常:

prop rAngle

public mut prop rAngle: Token

功能:获取或设置 MemberAccess 节点中的右尖括号。

类型:Token

异常:

prop typeArguments

public mut prop typeArguments: ArrayList<TypeNode>

功能:获取或设置 MemberAccess 节点中的实例化类型。

类型:ArrayList<TypeNode>

init()

public init()

功能:构造一个默认的 MemberAccess 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 MemberAccess 对象。

参数:

异常:

class Modifier

public class Modifier <: Node {
    public init()
    public init(keyword: Token)
}

功能:表示该定义具备某些特性,通常放在定义处的最前端。

一个 Modifier 节点:public func foo() 中的 public

父类型:

prop keyword(Token)

public mut prop keyword: Token

功能:获取或设置 Modifier 节点中的修饰符词法单元。

类型:Token

init()

public init()

功能:构造一个默认的 Modifier 对象。

init(Token)

public init(keyword: Token)

功能:构造一个 Modifier 对象。

参数:

  • keyword: Token - 将要构造 Modifier 类型的词法单元。

class Node

abstract sealed class Node <: ToTokens

功能:所有仓颉语法树节点的父类。

该类提供了所有数据类型通用的操作接口。

父类型:

prop beginPos

public mut prop beginPos: Position

功能:获取或设置当前节点的起始的位置信息。

类型:Position

prop endPos

public mut prop endPos: Position

功能:获取或设置当前节点的终止的位置信息。

类型:Position

func dump()

public func dump(): Unit

功能:将当前语法树节点转化为树形结构的形态并进行打印。

语法树节点的树形结构将按照以下形式进行输出:

  • - 字符串:表示当前节点的公共属性, 如 -keyword , -identifier
  • 节点属性后紧跟该节点的具体类型, 如 -declType: PrimitiveType 表示节点类型是一个 PrimitiveType 节点。
  • 每个类型使用大括号表示类型的作用区间。

语法树输出的详细格式请参考示例代码中语法树节点打印的内容。

func toTokens()

public func toTokens(): Tokens

功能:将语法树节点转化为 Tokens 类型。

返回值:

func traverse(Visitor)

public func traverse(v: Visitor): Unit

功能:遍历当前语法树节点及其子节点。若提前终止遍历子节点的行为,可重写 visit 函数并调用 breakTraverse 函数提前终止遍历行为,详细见 示例代码中 自定义访问函数遍历 AST 对象示例 的内容。

参数:

class OptionalExpr

public class OptionalExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个带有问号操作符的表达式节点。

一个 OptionalExpr 节点:a?.b, a?(b), a?[b] 中的 a?

父类型:

prop baseExpr

public mut prop baseExpr: Expr

功能:获取或设置 OptionalExpr 的表达式节点。

类型:Expr

prop quest

public mut prop quest: Token

功能:获取或设置 OptionalExpr 中的问号操作符。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 OptionalExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 OptionalExpr 对象。

参数:

异常:

class PackageHeader

public class PackageHeader <: Node {
    public init()
    public init(inputs: Tokens)
}

功能:表示包声明节点。

一个 PackageHeader 节点: package define 或者 macro package define

说明:

包声明以关键字 packagemacro package 开头,后面紧跟包名,且包声明必须在源文件的首行。

父类型:

prop accessible

public mut prop accessible: Token

功能:获取或设置 PackageHeader 节点中的访问性修饰符的词法单元,可能为 ILLEGAL 的词法单元。

类型:Token

prop keywordM

public mut prop keywordM: Token

功能:获取或设置 PackageHeader 节点中的 macro 关键字的词法单元(M 为关键字首字母,下同),可能为 ILLEGAL 的词法单元。

类型:Token

异常:

prop keywordP

public mut prop keywordP: Token

功能:获取或设置 PackageHeader 节点中的 package 关键字的词法单元。

类型:Token

异常:

prop prefixPaths

public mut prop prefixPaths: Tokens

功能:获取或设置 PackageHeader 节点中完整包名的前缀部分的词法单元序列,可能为空。如 package a.b.c 中的 ab

类型:Tokens

prop prefixDots

public mut prop prefixDots: Tokens

功能:获取或设置 PackageHeader 节点中完整包名中用于分隔每层子包的词法单元序列,可能为空。如 package a.b.c 中的两个 "."。

类型:Tokens

异常:

prop packageIdentifier

public mut prop packageIdentifier: Token

功能:获取或设置 PackageHeader 节点中当前包的名字,如果当前包为 root 包,即为完整包名,若当前包为子包,则为最后一个 "." 后的名字。

类型:Token

init()

public init()

功能:构造一个默认的 PackageHeader 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 PackageHeader 对象。

参数:

异常:

class ParenExpr

public class ParenExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个括号表达式节点,是指使用圆括号括起来的表达式。

一个 ParenExpr 节点:(1 + 2)

父类型:

prop lParen

public mut prop lParen: Token

功能:获取或设置 ParenExpr 节点中的 "("。

类型:Token

异常:

prop parenthesizedExpr

public mut prop parenthesizedExpr: Expr

功能:获取或设置 ParenExpr 节点中由圆括号括起来的子表达式。

类型:Expr

prop rParen

public mut prop rParen: Token

功能:获取或设置 ParenExpr 节点中的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 ParenExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ParenExpr 对象。

参数:

异常:

class ParenType

public class ParenType <: TypeNode {
    public init()
    public init(inputs: Tokens)
}

功能:表示括号类型节点。

例如 var a: (Int64) 中的 (Int64)

父类型:

prop lParen

public mut prop lParen: Token

功能:获取或设置 ParenType 节点中的 "(" 词法单元。

类型:Token

异常:

prop parenthesizedType

public mut prop parenthesizedType: TypeNode

功能:获取或设置 ParenType 节点中括起来的类型,如 (Int64) 中的 Int64

类型:TypeNode

prop rParen

public mut prop rParen: Token

功能:获取或设置 ParenType 节点中的 ")" 词法单元。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 ParenType 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ParenType 对象。

参数:

异常:

class Pattern

public open class Pattern <: Node

功能:所有模式匹配节点的父类,继承自 Node 节点。

父类型:

class PrefixType

public class PrefixType <: TypeNode {
    public init()
    public init(inputs: Tokens)
}

功能:表示带问号的前缀类型节点。

例如 var a : ?A 中的 ?A

父类型:

prop baseType

public mut prop baseType: TypeNode

功能:获取或设置 PrefixType 节点中的类型节点,如 var a: ?A 中的 A

类型:TypeNode

prop prefixOps

public mut prop prefixOps: Tokens

功能:获取或设置 PrefixType 节点中前缀操作符集合。

类型:Tokens

init()

public init()

功能:构造一个默认的 PrefixType 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 PrefixType 对象。

参数:

异常:

class PrimaryCtorDecl

public class PrimaryCtorDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个主构造函数节点。

主构造函数节点由修饰符,主构造函数名,形参列表和主构造函数体构成。

父类型:

prop block

public mut prop block: Block

功能:获取或设置 PrimaryCtorDecl 节点的主构造函数体。

类型:Block

prop funcParams

public mut prop funcParams: ArrayList<FuncParam>

功能:获取或设置 PrimaryCtorDecl 节点的参数。

类型:ArrayList<FuncParam>

prop lParen

public mut prop lParen: Token

功能:获取或设置 PrimaryCtorDecl 节点的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 PrimaryCtorDecl 节点的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 PrimaryCtorDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 PrimaryCtorDecl 对象。

参数:

异常:

func isConst()

public func isConst(): Bool

功能:判断是否是一个 Const 类型的节点。

返回值:

  • Bool - 当前节点为 Const 类型的节点时,返回 true;反之,返回 false。

class PrimitiveType

public class PrimitiveType <: TypeNode {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个基本类型节点。

例如数值类型,Rune 类型,布尔类型等。

父类型:

prop keyword

public mut prop keyword: Token

功能:获取或设置构造 PrimitiveType 类型的关键字,如 Int8

类型:Token

init()

public init()

功能:构造一个默认的 PrimitiveType 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 PrimitiveType 对象。

参数:

异常:

class PrimitiveTypeExpr

public class PrimitiveTypeExpr <: Expr {
    public init()
    public init(kind: Tokens)
}

功能:表示基本类型表达式节点。

PrimitiveTypeExpr 节点:编译器内置的基本类型作为表达式出现在节点中。如 Int64.toSting() 中的 Int64

父类型:

prop keyword

public mut prop keyword: Token

功能:获取或设置 PrimitiveTypeExpr 中的基本类型关键字。

类型:Token

init()

public init()

功能:构造一个默认的 PrimitiveTypeExpr 对象。

init(Tokens)

public init(kind: Tokens)

功能:构造一个 PrimitiveTypeExpr 对象。

参数:

异常:

class Program

public class Program <: Node {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个仓颉源码文件节点。

一个仓颉源码文件节点主要包括包定义节点,包导入节点和 TopLevel 作用域内的所有声明节点。

说明:

任何一个仓颉源码文件都可以被解析为一个 Program 类型。

父类型:

prop decls

public mut prop decls: ArrayList<Decl>

功能:获取或设置仓颉源码文件中 TopLevel 作用域内定义的声明节点列表。

类型:ArrayList<Decl>

prop importLists

public mut prop importLists: ArrayList<ImportList>

功能:获取或设置仓颉源码文件中包导入节点 ImportList 的列表。

类型:ArrayList<ImportList>

prop packageHeader

public mut prop packageHeader: PackageHeader

功能:获取或设置仓颉源码文件中包的声明节点 PackageHeader

类型:PackageHeader

init()

public init()

功能:构造一个默认的 Program 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 Program 对象。

参数:

异常:

  • ASTException - 当输入的 Tokens 类型无法构造为一个文件节点时,抛出异常。

class PropDecl

public class PropDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个属性定义节点。

一个 PropDecl 节点:prop var X: Int64 { get() { 0 } }

父类型:

prop colon

public mut prop colon: Token

功能:获取或设置 PropDecl 节点的冒号。

类型:Token

异常:

prop declType

public mut prop declType : TypeNode

功能:获取或设置 PropDecl 节点的返回类型。

类型:TypeNode

prop getter

public mut prop getter: FuncDecl

功能:获取或设置 PropDecl 节点的 getter 函数。

类型:FuncDecl

异常:

-ASTException:当 PropDecl 节点不存在 getter 函数时,抛出异常。

prop lBrace

public mut prop lBrace: Token

功能:获取或设置 PropDecl 节点的 "{"。

类型:Token

异常:

prop rBrace

public mut prop rBrace: Token

功能:获取或设置 PropDecl 节点的 "}"。

类型:Token

异常:

prop setter

public mut prop setter: FuncDecl

功能:获取或设置 PropDecl 节点的 setter 函数。

类型:FuncDecl

异常:

-ASTException:当 PropDecl 节点不存在 setter 函数时,抛出异常。

init()

public init()

功能:构造一个默认的 PropDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 PropDecl 对象。

参数:

异常:

class QualifiedType

public class QualifiedType <: TypeNode {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个用户自定义成员类型。

例如 var a : T.a 中的 T.a, 其中 T 是包名,a 是从 T 包中导入的类型。

父类型:

prop baseType

public mut prop baseType: TypeNode

功能:获取或设置 QualifiedType 节点的成员访问类型主体,如 var a : T.a 中的 T

类型:TypeNode

prop commas

public mut prop commas: Tokens

功能:获取或设置 QualifiedType 节点中的 "," 词法单元序列,可能为空。

类型:Tokens

异常:

prop dot

public mut prop dot: Token

功能:获取或设置 QualifiedType 节点中的 "." 。

类型:Token

异常:

prop identifier

public mut prop identifier: Token

功能:获取或设置 QualifiedType 节点成员的标识符,如 var a : T.a 中的 a

类型:Token

prop lAngle

public mut prop lAngle: Token

功能:获取或设置 QualifiedType 节点中的左尖括号词法单元,可能为 ILLEGAL 的词法单元。

类型:Token

异常:

prop rAngle

public mut prop rAngle: Token

功能:获取或设置 QualifiedType 节点中的右尖括号词法单元,可能为 ILLEGAL 的词法单元。

类型:Token

异常:

prop typeArguments

public mut prop typeArguments: ArrayList<TypeNode>

功能:获取或设置 QualifiedType 节点中的实例化类型的列表,如 T.a<Int32> 中的 Int32,列表可能为空。

类型:ArrayList<TypeNode>

init()

public init()

功能:构造一个默认的 QualifiedType 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 QualifiedType 对象。

参数:

异常:

class QuoteExpr

public class QuoteExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 quote 表达式节点。

一个 QuoteExpr 节点: quote(var ident = 0)

父类型:

prop exprs

public mut prop exprs: ArrayList<Expr>

功能:获取或设置 QuoteExpr 中由 () 括起的内部引用表达式节点。

类型:ArrayList<Expr>

prop keyword

public mut prop keyword: Token

功能:获取或设置 QuoteExprquote 关键字。

类型:Token

异常:

prop lParen

public mut prop lParen: Token

功能:获取或设置 QuoteExpr 中的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 QuoteExpr 中的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 QuoteExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 QuoteExpr 对象。

参数:

异常:

class QuoteToken

public class QuoteToken <: Expr

功能:表示 quote 表达式节点内任意合法的 token

父类型:

prop tokens

public mut prop tokens: Tokens

功能:获取 QuoteToken 内的 Tokens

类型:Tokens

class RangeExpr

public class RangeExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示包含区间操作符的表达式。

RangeExpr 节点:存在两种 Range 操作符:....=,分别用于创建左闭右开和左闭右闭的 Range 实例。它们的使用方式分别为 start..end:stepstart..=end:step

父类型:

prop colon

public mut prop colon: Token

功能:获取或设置 RangeExpr 中的 ":" 操作符。

类型:Token

异常:

prop end

public mut prop end: Expr

功能:获取或设置 RangeExpr 中的终止值。

类型:Expr

异常:

  • ASTException - 终止表达式省略。只有在 Range<Int64> 类型的实例用在下标操作符 [] 为空的场景。

prop op

public mut prop op: Token

功能:获取或设置 RangeExpr 中的 Range 的操作符。

类型:Token

prop start

public mut prop start: Expr

功能:获取或设置 RangeExpr 中的起始值。

类型:Expr

异常:

  • ASTException - 起始表达式省略。只有在 Range<Int64> 类型的实例用在下标操作符 [] 为空的场景。

prop step

public mut prop step: Expr

功能:获取或设置 RangeExpr 中序列中前后两个元素之间的差值。

类型:Expr

异常:

init()

public init()

功能:构造一个默认的 RangeExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 RangeExpr 对象。

参数:

异常:

class RefExpr

public class RefExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示引用一个声明的表达式节点。

一个 RefExpr 节点:var b = a + 1 中的 a 是一个 RefExpr

父类型:

prop commas

public mut prop commas: Tokens

功能:获取或设置 RefExpr 节点中的 "," 词法单元序列,可能为空。

类型:Tokens

异常:

prop identifier

public mut prop identifier: Token

功能:获取或设置 RefExpr 节点中的自定义类型的标识符。

类型:Token

prop lAngle

public mut prop lAngle: Token

功能:获取或设置 RefExpr 节点中的左尖括号。

类型:Token

异常:

prop rAngle

public mut prop rAngle: Token

功能:获取或设置 RefExpr 节点中的右尖括号。

类型:Token

异常:

prop typeArguments

public mut prop typeArguments: ArrayList<TypeNode>

功能:获取或设置 RefExpr 节点中的实例化类型。

类型:ArrayList<TypeNode>

init()

public init()

功能:构造一个默认的 RefExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 RefExpr 对象。

参数:

异常:

class RefType

public class RefType <: TypeNode {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个非基础类型节点。

例如用户通过 classstructenum 等定义的自定义类型,以及 ArrayString 等内置类型都可以使用 RefType 表示。例如 var a : A 中的 A

父类型:

prop commas

public mut prop commas: Tokens

功能:获取或设置 RefType 节点中的 "," 词法单元序列,可能为空。

类型:Tokens

异常:

prop identifier

public mut prop identifier: Token

功能:获取或设置构造 RefType 类型的关键字,如 var a : A = A() 中的 A

类型:Token

prop lAngle

public mut prop lAngle: Token

功能:获取或设置 RefType 节点中的左尖括号词法单元,可能为 ILLEGAL 的词法单元。

类型:Token

异常:

prop rAngle

public mut prop rAngle: Token

功能:获取或设置 RefType 节点中的右尖括号词法单元,可能为 ILLEGAL 的词法单元。

类型:Token

异常:

prop typeArguments

public mut prop typeArguments: ArrayList<TypeNode>

功能:获取或设置 RefType 节点中的实例化类型的列表,可能为空,如 var a : Array<Int32> 中的 Int32

类型:ArrayList<TypeNode>

init()

public init()

功能:构造一个默认的 RefType 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 RefType 对象。

参数:

异常:

class ReturnExpr

public class ReturnExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 return 表达式节点。

一个 ReturnExpr 节点:return 1

父类型:

prop expr

public mut prop expr: Expr

功能:获取或设置 ReturnExpr 节点中的表达式节点。

类型:Expr

异常:

prop keyword

public mut prop keyword: Token

功能:获取或设置 ReturnExpr 节点中的关键字。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 ReturnExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ReturnExpr 对象。

参数:

异常:

class SpawnExpr

public class SpawnExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 Spawn 表达式。

一个 SpawnExpr 节点由 spawn 关键字和一个不包含形参的闭包组成,例如:spawn { add(1, 2) }

父类型:

prop keyword

public mut prop keyword: Token

功能:获取或设置 SpawnExpr 中的 spawn 关键字。

类型:Token

异常:

prop lParen

public mut prop lParen: Token

功能:获取或设置 SpawnExpr 中的 "("。

类型:Token

异常:

prop lambdaExpr

public mut prop lambdaExpr: LambdaExpr

功能:获取或设置 SpawnExpr 中的不含形参的闭包。

类型:LambdaExpr

prop rParen

public mut prop rParen: Token

功能:获取或设置 SpawnExpr 中的 ")"。

类型:Token

异常:

prop threadContext

public mut prop threadContext: Expr

功能:获取或设置 SpawnExpr 中的线程上下文环境表达式。

类型:Expr

异常:

init()

public init()

功能:构造一个默认的 SpawnExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 SpawnExpr 对象。

参数:

异常:

class StructDecl

public class StructDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个 Struct 节点。

Struct 的定义使用 struct 关键字,定义依次为:可缺省的修饰符、struct 关键字、struct 名、可选的类型参数、是否指定父接口、可选的泛型约束、struct 体的定义。

父类型:

prop body

public mut prop body: Body

功能:获取或设置 StructDecl 节点的类体。

类型:Body

prop superTypeBitAnds

public mut prop superTypeBitAnds: Tokens

功能:获取或设置 StructDecl 节点的父接口声明中的 & 操作符的词法单元序列,可能为空。

类型:Tokens

异常:

prop superTypes

public mut prop superTypes: ArrayList<TypeNode>

功能:获取或设置 StructDecl 节点的父接口。

类型:ArrayList<TypeNode>

prop upperBound

public mut prop upperBound: Token

功能:获取或设置 <: 操作符。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 StructDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 StructDecl 对象。

参数:

异常:

class SubscriptExpr

public class SubscriptExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示索引访问表达式。

SubscriptExpr 节点:用于那些支持索引访问的类型(包括 Array 类型和 Tuple 类型)通过下标来访问其具体位置的元素,如 arr[0]

父类型:

prop baseExpr

public mut prop baseExpr: Expr

功能:获取或设置 SubscriptExpr 中的表达式。

类型:Expr

prop indexList

public mut prop indexList: ArrayList<Expr>

功能:获取或设置 SubscriptExpr 中的索引表达式序列。

类型:ArrayList<Expr>

prop lSquare

public mut prop lSquare: Token

功能:获取或设置 SubscriptExpr 中的 "["。

类型:Token

异常:

prop rSquare

public mut prop rSquare: Token

功能:获取或设置 SubscriptExpr 中的 "]"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 SubscriptExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 SubscriptExpr 对象。

参数:

异常:

class SynchronizedExpr

public class SynchronizedExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 synchronized 表达式。

一个 SynchronizedExpr 节点由 synchronized 关键字和 StructuredMutex 对以及后面的代码块组成, 例如 synchronized(m) { foo() }

父类型:

prop block

public mut prop block: Block

功能:获取或设置 SynchronizedExpr 修饰的代码块。

类型:Block

prop keyword

public mut prop keyword: Token

功能:获取或设置 SynchronizedExpr 中的 synchronized 关键字。

类型:Token

异常:

  • ASTException - 当设置的 Token 不是 synchronized 关键字时,抛出异常。

prop lParen

public mut prop lParen: Token

功能:获取或设置 SynchronizedExpr 中的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 SynchronizedExpr 中的 ")"。

类型:Token

异常:

prop structuredMutex

public mut prop structuredMutex: Expr

功能:获取或设置 SynchronizedExpr 中的 StructuredMutex 的对象。

类型:Expr

init()

public init()

功能:构造一个默认的 SynchronizedExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 SynchronizedExpr 对象。

参数:

异常:

class ThisType

public class ThisType <: TypeNode {
    public init()
    public init(inputs: Tokens)
}

功能:表示 This 类型节点。

父类型:

prop keyword

public mut prop keyword: Token

功能:获取或设置 ThisType 节点关键字 This 的词法单元。

类型:Token

init()

public init()

功能:构造一个默认的 ThisType 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ThisType 对象。

参数:

异常:

class ThrowExpr

public class ThrowExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 throw 表达式节点。

一个 ThrowExpr 节点:throw Exception()

父类型:

prop expr

public mut prop expr: Expr

功能:获取或设置 ThrowExpr 节点中的表达式节点。

类型:Expr

prop keyword

public mut prop keyword: Token

功能:获取或设置 ThrowExpr 节点中的关键字。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 ThrowExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 ThrowExpr 对象。

参数:

异常:

class Tokens

public open class Tokens <: ToString & Iterable<Token> & ToBytes {
    public init()
    public init(tokArray: Array<Token>)
    public init(tokArrayList: ArrayList<Token>)
}

功能:对 Token 序列进行封装的类型。

父类型:

prop size

public open prop size: Int64

功能:获取 Tokens 对象中 Token 类型的数量。

类型:Int64

init()

public init()

功能:构造一个默认的 Tokens 对象。

init(Array<Token>)

public init(tokArray: Array<Token>)

功能:构造一个 Tokens 对象。

参数:

init(ArrayList<Token>)

public init(tokArrayList: ArrayList<Token>)

功能:构造一个 Tokens 对象。

参数:

func append(Node)

public func append(node: Node): Tokens

功能:将当前的 Tokens 与传入节点所转换得到的 Tokens 进行拼接。

参数:

  • node: Node - 待拼接的 Node 对象。

返回值:

func append(Token)

public open func append(token: Token): Tokens

功能:将当前的 Tokens 与传入的 Token 进行拼接。

参数:

返回值:

func append(Tokens)

public open func append(tokens: Tokens): Tokens

功能:在当前的 Tokens 后追加传入的 Tokens 进行拼接(该接口性能较其他拼接函数表现更好)。

参数:

返回值:

func concat(Tokens)

public func concat(tokens: Tokens): Tokens

功能:将当前的 Tokens 与传入的 Tokens 进行拼接。

参数:

返回值:

func dump()

public func dump(): Unit

功能:将 Tokens 内所有 Token 的信息打印出来。

func get(Int64)

public open func get(index: Int64): Token

功能:通过索引值获取 Token 元素。

参数:

  • index: Int64 - 待索引的数值。

返回值:

func iterator()

public func iterator(): TokensIterator

功能:获取 Tokens 对象中的一个迭代器对象。

返回值:

func remove(Int64)

public func remove(index: Int64): Tokens

功能:删除指定位置的 Token 对象。

参数:

返回值:

func toBytes()

public func toBytes(): Array<UInt8>

功能:Tokens 类型的序列化。

返回值:

func toString()

public func toString(): String

功能:将 Tokens 转化为 String 类型。

operator func +(Token)

public operator func +(r: Token): Tokens

功能:使用当前 Tokens 与另一个 Token 相加以获取新的 Tokens

参数:

  • r: Token - 待操作的另一个 Token 对象。

返回值:

operator func +(Tokens)

public operator func +(r: Tokens): Tokens

功能:使用当前 TokensTokens 相加以获取新的 Tokens 类型。

参数:

返回值:

operator func [](Int64)

public operator func [](index: Int64): Token

功能:操作符重载,通过索引值获取对应 Token

参数:

  • index: Int64 - 待索引的数值。

返回值:

operator func [](Range<Int64>)

public open operator func [](range: Range<Int64>): Tokens

功能:操作符重载,通过 range 获取对应 Tokens 切片。

参数:

  • range: Range<Int64> - 待索引的切片范围。

返回值:

异常:

class TokensIterator

public class TokensIterator <: Iterator<Token> {
    public init(tokens: Tokens)
}

功能:实现 Tokens 的迭代器功能。

父类型:

init(Tokens)

public init(tokens: Tokens)

功能:构造一个 TokensIterator 对象。

参数:

func iterator()

public func iterator(): Iterator<Token>

功能:获取当前迭代器实例。

返回值:

func next()

public func next(): Option<Token>

功能:获取迭代器中的下一个值。

返回值:

func peek()

public func peek(): Option<Token>

功能:获取迭代器中的当前值。

返回值:

func seeing(TokenKind)

public func seeing(kind: TokenKind): Bool

功能:判断当前节点的 Token 类型是否是传入的类型。

参数:

返回值:

  • Bool - 如果当前节点的 TokenKind 与传入类型相同,返回 true,否则返回 false。

class TrailingClosureExpr

public class TrailingClosureExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示尾随 Lambda 节点。

一个 TrailingClosureExpr 节点将 lambda 表达式放在函数调用的尾部,括号外面,如 f(a){ i => i * i }

父类型:

prop expr

public mut prop expr: Expr

功能:获取或设置 TrailingClosureExpr 中的表达式。

类型:Expr

prop lambdaExpr

public mut prop lambdaExpr: LambdaExpr

功能:获取或设置 TrailingClosureExpr 中的尾随 lambda。

类型:LambdaExpr

init()

public init()

功能:构造一个默认的 TrailingClosureExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 TrailingClosureExpr 对象。

参数:

异常:

class TryExpr

public class TryExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 try 表达式节点。

try 表达式包括三个部分:try 块,catch 块和 finally 块。

父类型:

prop catchBlocks

public mut prop catchBlocks: ArrayList<Block>

功能:获取或设置 TryExpr 中的 Catch 块。

类型:ArrayList<Block>

prop catchPatterns

public mut prop catchPatterns: ArrayList<Pattern>

功能:获取或设置 TryExpr 中通过模式匹配的方式匹配待捕获的异常序列。

类型:ArrayList<Pattern>

prop finallyBlock

public mut prop finallyBlock: Block

功能:获取或设置 TryExpr 中的关键字 Finally 块。

类型:Block

异常:

prop keywordF

public mut prop keywordF: Token

功能:获取或设置 TryExpr 中的 finally 关键字。

类型:Token

异常:

prop keywordT

public mut prop keywordT: Token

功能:获取或设置 TryExpr 中的 try 关键字。

类型:Token

异常:

prop keywordsC

public mut prop keywordsC: Tokens

功能:获取或设置 TryExpr 中的关键字 catch

类型:Tokens

异常:

prop resourceSpec

public mut prop resourceSpec: ArrayList<VarDecl>

功能:获取或设置 TryExpr 中 Try-with-resources 类型表达式的实例化对象序列。

类型:ArrayList<VarDecl>

prop tryBlock

public mut prop tryBlock: Block

功能:获取或设置 TryExpr 中由表达式与声明组成的块。

类型:Block

init()

public init()

功能:构造一个默认的 TryExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 TryExpr 对象。

参数:

异常:

class TupleLiteral

public class TupleLiteral <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示元组字面量节点。

TupleLiteral 节点:使用格式 (expr1, expr2, ... , exprN) 表示,每个 expr 是一个表达式。

父类型:

prop elements

public mut prop elements: ArrayList<Expr>

功能:获取或设置 TupleLiteral 中的表达式列表。

类型:ArrayList<Expr>

prop lParen

public mut prop lParen: Token

功能:获取或设置 TupleLiteral 中的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 TupleLiteral 中的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 TupleLiteral 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 TupleLiteral 对象。

参数:

异常:

class TuplePattern

public class TuplePattern <: Pattern {
    public init()
    public init(inputs: Tokens)
}

功能:表示 Tuple 模式节点。

用于 tuple 值的匹配,如 case ("Bob", age) => 1 中的 ("Bob", age)

父类型:

prop commas

public mut prop commas: Tokens

功能:获取或设置 TuplePattern 节点中的 "," 词法单元序列,可能为空。

类型:Tokens

异常:

prop lParen

public mut prop lParen: Token

功能:获取或设置 TuplePattern 节点中的 "(" 的词法单元。

类型:Token

异常:

prop patterns

public mut prop patterns: ArrayList<Pattern>

功能:获取或设置 TuplePattern 节点中的一组 Pattern 节点。

类型:ArrayList<Pattern>

prop rParen

public mut prop rParen: Token

功能:获取或设置 TuplePattern 节点中的 ")" 的词法单元。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 TuplePattern 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 TuplePattern 对象。

参数:

异常:

class TupleType

public class TupleType <: TypeNode {
    public init()
    public init(inputs: Tokens)
}

功能:表示元组类型节点。

例如 var a : (Int64, Int32) 中的 (Int64, Int32)

父类型:

prop lParen

public mut prop lParen: Token

功能:获取或设置 TupleType 节点中的 "(" 词法单元。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 TupleType 节点中的 ")" 词法单元。

类型:Token

异常:

prop types

public mut prop types: ArrayList<TypeNode>

功能:获取或设置 TupleType 节点中的类型节点列表。

类型:ArrayList<TypeNode>

init()

public init()

功能:构造一个默认的 TupleType 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 TupleType 对象。

参数:

异常:

class TypeAliasDecl

public class TypeAliasDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示类型别名节点。

一个 TypeAliasDecl 节点: type Point2D = Float64

说明:

该节点中 type 作为关键字,紧跟任意的合法标识符,其后的 type 是任意的 top-level 可见的类型,标识符和 type 之间使用 = 进行连接。

父类型:

prop aliasType

public mut prop aliasType: TypeNode

功能:获取或设置将要别名的类型。

类型:TypeNode

prop assign

public mut prop assign: Token

功能:获取或设置标识符和 type 之间的 =

类型:Token

异常:

init()

public init()

功能:构造一个默认的 TypeAliasDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 TypeAliasDecl 对象。

参数:

异常:

class TypeConvExpr

public class TypeConvExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示类型转换表达式。

用于实现若干数值类型间的转换。一个 TypeConvExpr 节点:Int8(32)

父类型:

prop expr

public mut prop expr: Expr

功能:获取或设置 TypeConvExpr 中进行类型转化的原始表达式。

类型:Expr

prop lParen

public mut prop lParen: Token

功能:获取或设置 TypeConvExpr 中的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 TypeConvExpr 中的 ")"。

类型:Token

异常:

prop targetType

public mut prop targetType: PrimitiveType

功能:获取或设置 TypeConvExpr 中将要转换到的目标类型。

类型:PrimitiveType

init()

public init()

功能:构造一个默认的 TypeConvExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 TypeConvExpr 对象。

参数:

异常:

class TypeNode

public open class TypeNode <: Node

功能:所有类型节点的父类,继承自 Node

父类型:

prop typeParameterName

public mut prop typeParameterName: Token

功能:获取或设置类型节点的参数,如:(p1:Int64, p2:Int64) 中的 p1p2,可能为 ILLEGAL 的词法单元。

类型:Token

prop colon

public mut prop colon: Token

功能:获取或设置 TypeNode 节点中的操作符 ":",可能为 ILLEGAL 的词法单元。

类型:Token

异常:

class TypePattern

public class TypePattern <: Pattern {
    public init()
    public init(inputs: Tokens)
}

功能:表示类型模式节点。

用于判断一个值的运行时类型是否是某个类型的子类型,如 case b: Base => 0 中的 b: Base

父类型:

prop colon

public mut prop colon: Token

功能:获取或设置 TypePattern 节点中的 ":" 操作符的词法单元节点。

类型:Token

异常:

prop pattern

public mut prop pattern: Pattern

功能:获取或设置 TypePattern 节点中的模式节点。

类型:Pattern

prop patternType

public mut prop patternType: TypeNode

功能:获取或设置 TypePattern 节点中的待匹配的模式类型节点。

类型:TypeNode

init()

public init()

功能:构造一个默认的 TypePattern 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 TypePattern 对象。

参数:

异常:

class UnaryExpr

public class UnaryExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示一个一元操作表达式节点。

父类型:

prop expr

public mut prop expr: Expr

功能:获取或设置 UnaryExpr 节点中的操作数。

类型:Expr

prop op

public mut prop op: Token

功能:获取或设置 UnaryExpr 节点中的一元操作符。

类型:Token

init()

public init()

功能:构造一个默认的 UnaryExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 UnaryExpr 对象。

参数:

异常:

class VArrayExpr

public class VArrayExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 VArray 的实例节点。

一个 VArrayExpr 节点:let arr: VArray<Int64, $5> = VArray<Int64, $5> { i => i} 中的 VArray<Int64, $5> { i => i}

父类型:

prop arguments

public mut prop arguments: ArrayList<Argument>

功能:获取或设置 VArrayExpr 中的中的初始化参数序列。

类型:ArrayList<Argument>

prop lParen

public mut prop lParen: Token

功能:获取或设置 VArrayExpr 中的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 VArrayExpr 中的 ")"。

类型:Token

异常:

prop vArrayType

public mut prop vArrayType: VArrayType

功能:获取或设置 VArrayExpr 的 VArray 类型节点。

类型:VArrayType

init()

public init()

功能:构造一个默认的 VArrayExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 VArrayExpr 对象。

参数:

异常:

class VArrayType

public class VArrayType <: TypeNode {
    public init()
    public init(inputs: Tokens)
}

功能:表示 VArray 类型节点。

使用泛型 VArray<T, size: Int64> 表示 VArray 类型。

父类型:

prop dollar

public mut prop dollar: Token

功能:获取或设置 VArrayType 节点中的操作符 $ 的词法单元。

类型:Token

异常:

prop elementTy

public mut prop elementTy: TypeNode

功能:获取或设置 VArrayType 节点中的类型变元节点,如 VArray<Int16, $0> 中的 Int16

类型:TypeNode

prop keyword

public mut prop keyword: Token

功能:获取或设置 VArrayType 节点的关键字 VArray 的词法单元。

类型:Token

prop lAngle

public mut prop lAngle: Token

功能:获取或设置 VArrayType 节点左尖括号的词法单元。

类型:Token

异常:

prop rAngle

public mut prop rAngle: Token

功能:获取或设置 VArrayType 节点右尖括号的词法单元。

类型:Token

异常:

prop size

public mut prop size: Token

功能:获取或设置 VArrayType 节点中类型长度的词法单元。

类型:Token

init()

public init()

功能:构造一个默认的 VArrayType 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 VArrayType 对象。

参数:

异常:

class VarDecl

public class VarDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能:表示变量定义节点。

一个 VarDecl 节点: var a: Stringvar b: Int64 = 1

说明:

变量的定义主要包括如下几个部分:修饰符、关键字、patternsMaybeIrrefutable、变量类型和变量初始值。

父类型:

prop assign

public mut prop assign: Token

功能:获取或设置 VarDecl 节点中的赋值操作符的位置信息。

类型:Token

异常:

prop colon

public mut prop colon: Token

功能:获取或设置 VarDecl 节点中的冒号位置信息。

类型:Token

异常:

prop declType

public mut prop declType: TypeNode

功能:获取或设置 VarDecl 节点的变量类型。

类型:TypeNode

异常:

prop expr

public mut prop expr: Expr

功能:获取或设置 VarDecl 节点的变量初始化节点。

类型:Expr

异常:

prop pattern

public mut prop pattern: Pattern

功能:获取或设置 VarDecl 节点的 pattern 节点。

类型:Pattern

异常:

init()

public init()

功能:构造一个默认的 VarDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 VarDecl 对象。

参数:

异常:

func isConst()

public func isConst(): Bool

功能:判断是否是一个 Const 类型的节点。

返回值:

  • Bool - 是一个 Const 类型的节点返回 true;反之,返回 false。

class VarOrEnumPattern

public class VarOrEnumPattern <: Pattern {
    public init()
    public init(identifier: Token)
}

功能:表示当模式的标识符为 Enum 构造器时的节点。

例如 case RED 中的 REDEnum 构造器。

父类型:

prop identifier

public mut prop identifier: Token

功能:获取或设置 VarOrEnumPattern 节点中的标识符的词法单元。

类型:Token

init()

public init()

功能:构造一个默认的 VarOrEnumPattern 对象。

init(Tokens)

public init(identifier: Token)

功能:构造一个 VarOrEnumPattern 对象。

参数:

异常:

class VarPattern

public class VarPattern <: Pattern {
    public init()
    public init(identifier: Token)
}

功能:表示绑定模式节点。

使用一个合法的标识符表示,如 for (i in 1..10) 中的 i

父类型:

prop identifier

public mut prop identifier: Token

功能:获取或设置 VarPattern 节点中的标识符符的词法单元。

类型:Token

init()

public init()

功能:构造一个默认的 VarPattern 对象。

init(Tokens)

public init(identifier: Token)

功能:构造一个 VarPattern 对象。

参数:

异常:

class Visitor

public abstract class Visitor

功能:一个抽象类,其内部默认定义了访问不同类型 AST 节点访问(visit)函数。

说明:

  • visit 函数搭配 traverse 一起使用,可实现对节点的访问和修改, 所有 visit 函数都有默认为空的实现,可以按需实现需要的 visit 方法。
  • 该类需要被继承使用,并允许子类重新定义访问函数。

func breakTraverse()

public func breakTraverse(): Unit

功能:用于重写 visit 函数中,通过调用该函数来终止继续遍历子节点的行为。

class WhileExpr

public class WhileExpr <: Expr {
    public init()
    public init(inputs: Tokens)
}

功能:表示 while 表达式。

while 是关键字,while 之后是一个小括号,小括号内可以是一个表达式或者一个 let 声明的解构匹配,接着是一个 Block 节点。

父类型:

prop block

public mut prop block: Block

功能:获取或设置 WhileExpr 中的块节点。

类型:Block

prop condition

public mut prop condition: Expr

功能:获取或设置关键字 WhileExpr 中的条件表达式。

类型:Expr

prop keyword

public mut prop keyword: Token

功能:获取或设置 WhileExpr 节点中 while 关键字。

类型:Token

异常:

prop lParen

public mut prop lParen: Token

功能:获取或设置 WhileExprwhile 关键字之后的 "("。

类型:Token

异常:

prop rParen

public mut prop rParen: Token

功能:获取或设置 WhileExprwhile 关键字之后的 ")"。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 WhileExpr 对象。

init(Tokens)

public init(inputs: Tokens)

功能:构造一个 WhileExpr 对象。

参数:

异常:

class WildcardExpr

public class WildcardExpr <: Expr {
    public init()
    public init(keyword: Tokens)
}

功能:表示通配符表达式节点。

父类型:

prop keyword

public mut prop keyword: Token

功能:获取 WildcardExpr 的 "_" 关键字。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 WildcardExpr 对象。

init(Tokens)

public init(keyword: Tokens)

功能:构造一个 WildcardExpr 对象。

参数:

异常:

class WildcardPattern

public class WildcardPattern <: Pattern {
    public init()
    public init(keyword: Tokens)
}

功能:表示通配符模式节点。

使用下划线 "_" 表示,可以匹配任意值。

父类型:

prop wildcard

public mut prop wildcard: Token

功能:获取或设置 WildcardPattern 节点中的 "_" 操作符的词法单元。

类型:Token

异常:

init()

public init()

功能:构造一个默认的 WildcardPattern 对象。

init(Tokens)

public init(keyword: Tokens)

功能:构造一个 WildcardPattern 对象。

参数:

异常:

枚举

enum DiagReportLevel

public enum DiagReportLevel {
    ERROR|
    WARNING
}

功能:表示报错接口的信息等级,支持 ERRORWARNING 两种等级。

ERROR

ERROR

功能:构造一个表示 ERROR 的枚举实例。

WARNING

WARNING

功能:构造一个表示 WARNING 的枚举实例。

func level()

public func level(): Int32

功能:返回枚举值对应的整型。

返回值:

  • Int32 - 枚举值对应的整型。ERROR 返回 0,WARNING 返回 1。

enum ImportKind

public enum ImportKind <: ToString {
    Single | Alias | All | Multi
}

功能:表示导入语句的类型。

父类型:

Single

Single

功能:表示单导入,如 import a.b

Alias

Alias

功能:表示别名导入,如 import a.b as c

All

All

功能:表示全导入,如 import a.b.*

Multi

Multi

功能:表示多导入,如 import a.{b, c, d}

func toString()

public func toString(): String

功能:将 ImportKind 类型转化为字符串类型表示。

返回值:

enum TokenKind

public enum TokenKind <: ToString {
    DOT|                      /*  "."           */
    COMMA|                    /*  ","           */
    LPAREN|                   /*  "("           */
    RPAREN|                   /*  ")"           */
    LSQUARE|                  /*  "["           */
    RSQUARE|                  /*  "]"           */
    LCURL|                    /*  "{"           */
    RCURL|                    /*  "}"           */
    EXP|                      /*  "**"          */
    MUL|                      /*  "*"           */
    MOD|                      /*  "%"           */
    DIV|                      /*  "/"           */
    ADD|                      /*  "+"           */
    SUB|                      /*  "-"           */
    INCR|                     /*  "++"          */
    DECR|                     /*  "--"          */
    AND|                      /*  "&&"          */
    OR|                       /*  "||"          */
    COALESCING|               /*  "??"          */
    PIPELINE|                 /*  "|>"          */
    COMPOSITION|              /*  "~>"          */
    NOT|                      /*  "!"           */
    BITAND|                   /*  "&"           */
    BITOR|                    /*  "|"           */
    BITXOR|                   /*  "^"           */
    BITNOT|                   /*  "~"           */
    LSHIFT|                   /*  "<<"          */
    RSHIFT|                   /*  ">>"          */
    COLON|                    /*  ":"           */
    SEMI|                     /*  ";"           */
    ASSIGN|                   /*  "="           */
    ADD_ASSIGN|               /*  "+="          */
    SUB_ASSIGN|               /*  "-="          */
    MUL_ASSIGN|               /*  "*="          */
    EXP_ASSIGN|               /*  "**="         */
    DIV_ASSIGN|               /*  "/="          */
    MOD_ASSIGN|               /*  "%="          */
    AND_ASSIGN|               /*  "&&="         */
    OR_ASSIGN|                /*  "||="         */
    BITAND_ASSIGN|            /*  "&="          */
    BITOR_ASSIGN|             /*  "|="          */
    BITXOR_ASSIGN|            /*  "^="          */
    LSHIFT_ASSIGN|            /*  "<<="         */
    RSHIFT_ASSIGN|            /*  ">>="         */
    ARROW|                    /*  "->"          */
    BACKARROW|                /*  "<-"          */
    DOUBLE_ARROW|             /*  "=>"          */
    RANGEOP|                  /*  ".."          */
    CLOSEDRANGEOP|            /*  "..="         */
    ELLIPSIS|                 /*  "..."         */
    HASH|                     /*  "#"           */
    AT|                       /*  "@"           */
    QUEST|                    /*  "?"           */
    LT|                       /*  "<"           */
    GT|                       /*  ">"           */
    LE|                       /*  "<="          */
    GE|                       /*  ">="          */
    IS|                       /*  "is"          */
    AS|                       /*  "as"          */
    NOTEQ|                    /*  "!="          */
    EQUAL|                    /*  "=="          */
    WILDCARD|                 /*  "_"           */
    INT8|                     /*  "Int8"        */
    INT16|                    /*  "Int16"       */
    INT32|                    /*  "Int32"       */
    INT64|                    /*  "Int64"       */
    INTNATIVE|                /*  "IntNative"   */
    UINT8|                    /*  "UInt8"       */
    UINT16|                   /*  "UInt16"      */
    UINT32|                   /*  "UInt32"      */
    UINT64|                   /*  "UInt64"      */
    UINTNATIVE|               /*  "UIntNative"  */
    FLOAT16|                  /*  "Float16"     */
    FLOAT32|                  /*  "Float32"     */
    FLOAT64|                  /*  "Float64"     */
    RUNE|                     /*  "Rune"        */
    BOOLEAN|                  /*  "Bool"        */
    NOTHING|                  /*  "Nothing"     */
    UNIT|                     /*  "Unit"        */
    STRUCT|                   /*  "struct"      */
    ENUM|                     /*  "enum"        */
    CFUNC|                    /*  "CFunc"       */
    VARRAY|                   /*  "VArray"      */
    THISTYPE|                 /*  "This"        */
    PACKAGE|                  /*  "package"     */
    IMPORT|                   /*  "import"      */
    CLASS|                    /*  "class"       */
    INTERFACE|                /*  "interface"   */
    FUNC|                     /*  "func"        */
    MACRO|                    /*  "macro"       */
    QUOTE|                    /*  "quote"       */
    DOLLAR|                   /*  "$"           */
    LET|                      /*  "let"         */
    VAR|                      /*  "var"         */
    CONST|                    /*  "const"       */
    TYPE|                     /*  "type"        */
    INIT|                     /*  "init"        */
    THIS|                     /*  "this"        */
    SUPER|                    /*  "super"       */
    IF|                       /*  "if"          */
    ELSE|                     /*  "else"        */
    CASE|                     /*  "case"        */
    TRY|                      /*  "try"         */
    CATCH|                    /*  "catch"       */
    FINALLY|                  /*  "finally"     */
    FOR|                      /*  "for"         */
    DO|                       /*  "do"          */
    WHILE|                    /*  "while"       */
    THROW|                    /*  "throw"       */
    RETURN|                   /*  "return"      */
    CONTINUE|                 /*  "continue"    */
    BREAK|                    /*  "break"       */
    IN|                       /*  "in"          */
    NOT_IN|                   /*  "!in"         */
    MATCH|                    /*  "match"       */
    WHERE|                    /*  "where"       */
    EXTEND|                   /*  "extend"      */
    WITH|                     /*  "with"        */
    PROP|                     /*  "prop"        */
    STATIC|                   /*  "static"      */
    PUBLIC|                   /*  "public"      */
    PRIVATE|                  /*  "private"     */
    INTERNAL|                 /*  "internal"    */
    PROTECTED|                /*  "protected"   */
    OVERRIDE|                 /*  "override"    */
    REDEF|                    /*  "redef"       */
    ABSTRACT|                 /*  "abstract"    */
    SEALED|                   /*  "sealed"      */
    OPEN|                     /*  "open"        */
    FOREIGN|                  /*  "foreign"     */
    INOUT|                    /*  "inout"       */
    MUT|                      /*  "mut"         */
    UNSAFE|                   /*  "unsafe"      */
    OPERATOR|                 /*  "operator"    */
    SPAWN|                    /*  "spawn"       */
    SYNCHRONIZED|             /*  "synchronized" */
    UPPERBOUND|               /*  "<:"          */
    MAIN|                     /*  "main"        */
    IDENTIFIER|               /*  "x"           */
    PACKAGE_IDENTIFIER|       /*  e.g. "x-y"  */
    INTEGER_LITERAL|          /*  e.g. "1"      */
    RUNE_BYTE_LITERAL|        /*  e.g. "b'x'"   */
    FLOAT_LITERAL|            /*  e.g. "'1.0'"  */
    COMMENT|                  /*  e.g. "/*xx*/" */
    NL|                       /*  newline         */
    END|                      /*  end of file     */
    SENTINEL|                 /*  ";"             */
    RUNE_LITERAL|             /*  e.g. "r'x'"      */
    STRING_LITERAL|           /*  e.g. ""xx""     */
    JSTRING_LITERAL|          /*  e.g. "J"xx""     */
    MULTILINE_STRING|         /*  e.g. """"aaa""""   */
    MULTILINE_RAW_STRING|     /*  e.g. "#"aaa"#"     */
    BOOL_LITERAL|             /*  "true" or "false"  */
    UNIT_LITERAL|             /*  "()"               */
    DOLLAR_IDENTIFIER|        /*  e.g. "$x"          */
    ANNOTATION|               /*  e.g. "@When"       */
    ILLEGAL
}

功能:表示仓颉编译内部所有的词法结构,包括符号、关键字、标识符、换行等。

父类型:

ABSTRACT

ABSTRACT

功能:构造一个表示 abstract 的枚举实例。

ADD

ADD

功能:构造一个表示 + 的枚举实例。

ADD_ASSIGN

ADD_ASSIGN

功能:构造一个表示 += 的枚举实例。

AND

AND

功能:构造一个表示 && 的枚举实例。

AND_ASSIGN

AND_ASSIGN

功能:构造一个表示 &&= 的枚举实例。

ANNOTATION

ANNOTATION

功能:构造一个表示注解的枚举实例。

ARROW

ARROW

功能:构造一个表示 -> 的枚举实例。

AS

AS

功能:构造一个表示 as 的枚举实例。

ASSIGN

ASSIGN

功能:构造一个表示 = 的枚举实例。

AT

AT

功能:构造一个表示 @ 的枚举实例。

BACKARROW

BACKARROW

功能:构造一个表示 <- 的枚举实例。

BITAND

BITAND

功能:构造一个表示 & 的枚举实例。

BITAND_ASSIGN

BITAND_ASSIGN

功能:构造一个表示 &= 的枚举实例。

BITNOT

BITNOT

功能:构造一个表示 ~ 的枚举实例。

BITOR

BITOR

功能:构造一个表示 | 的枚举实例。

BITOR_ASSIGN

BITOR_ASSIGN

功能:构造一个表示 |= 的枚举实例。

BITXOR

BITXOR

功能:构造一个表示 ^ 的枚举实例。

BITXOR_ASSIGN

BITXOR_ASSIGN

功能:构造一个表示 ^= 的枚举实例。

BOOLEAN

BOOLEAN

功能:构造一个表示 bool 的枚举实例。

BOOL_LITERAL

BOOL_LITERAL

功能:构造一个表示布尔类型字面量的枚举实例。

BREAK

BREAK

功能:构造一个表示 break 的枚举实例。

CASE

CASE

功能:构造一个表示 case 的枚举实例。

CATCH

CATCH

功能:构造一个表示 catch 的枚举实例。

CFUNC

CFUNC

功能:构造一个表示 cfunc 的枚举实例。

CLASS

CLASS

功能:构造一个表示 class 的枚举实例。

CLOSEDRANGEOP

CLOSEDRANGEOP

功能:构造一个表示 ..= 的枚举实例。

COALESCING

COALESCING

功能:构造一个表示 ?? 的枚举实例。

COLON

COLON

功能:构造一个表示 : 的枚举实例。

COMMA

COMMA

功能:构造一个表示 , 的枚举实例。

COMMENT

COMMENT

功能:构造一个表示注释的枚举实例。

COMPOSITION

COMPOSITION

功能:构造一个表示 ~> 的枚举实例。

CONST

CONST

功能:构造一个表示 const 的枚举实例。

CONTINUE

CONTINUE

功能:构造一个表示 continue 的枚举实例。

DECR

DECR

功能:构造一个表示 -- 的枚举实例。

DIV

DIV

功能:构造一个表示 / 的枚举实例。

DIV_ASSIGN

DIV_ASSIGN

功能:构造一个表示 /= 的枚举实例。

DO

DO

功能:构造一个表示 do 的枚举实例。

DOLLAR

DOLLAR

功能:构造一个表示 $ 的枚举实例。

DOLLAR_IDENTIFIER

DOLLAR_IDENTIFIER

功能:构造一个表示插值字符串的枚举实例。

DOT

DOT

功能:构造一个表示 . 的枚举实例。

DOUBLE_ARROW

DOUBLE_ARROW

功能:构造一个表示 => 的枚举实例。

ELLIPSIS

ELLIPSIS

功能:构造一个表示 ... 的枚举实例。

ELSE

ELSE

功能:构造一个表示 else 的枚举实例。

END

END

功能:构造一个表示 EOF 的枚举实例。

ENUM

ENUM

功能:构造一个表示 enum 的枚举实例。

EQUAL

EQUAL

功能:构造一个表示 == 的枚举实例。

EXP

EXP

功能:构造一个表示 ** 的枚举实例。

EXP_ASSIGN

EXP_ASSIGN

功能:构造一个表示 **= 的枚举实例。

EXTEND

EXTEND

功能:构造一个表示 extend 的枚举实例。

FINALLY

FINALLY

功能:构造一个表示 finally 的枚举实例。

FLOAT16

FLOAT16

功能:构造一个表示 float16 的枚举实例。

FLOAT32

FLOAT32

功能:构造一个表示 float32 的枚举实例。

FLOAT64

FLOAT64

功能:构造一个表示 float64 的枚举实例。

FLOAT_LITERAL

FLOAT_LITERAL

功能:构造一个表示浮点字面量的枚举实例。

FOR

FOR

功能:构造一个表示 for 的枚举实例。

FOREIGN

FOREIGN

功能:构造一个表示 foreign 的枚举实例。

FUNC

FUNC

功能:构造一个表示 func 的枚举实例。

GE

GE

功能:构造一个表示 >= 的枚举实例。

GT

GT

功能:构造一个表示 > 的枚举实例。

HASH

HASH

功能:构造一个表示 # 的枚举实例。

IDENTIFIER

IDENTIFIER

功能:构造一个表示标识符的枚举实例。

PACKAGE_IDENTIFIER

PACKAGE_IDENTIFIER

功能:构造一个表示包标识符的枚举实例。

IF

IF

功能:构造一个表示 if 的枚举实例。

ILLEGAL

ILLEGAL

功能:构造一个表示非法的枚举实例。

IMPORT

IMPORT

功能:构造一个表示 import 的枚举实例。

IN

IN

功能:构造一个表示 in 的枚举实例。

INCR

INCR

功能:构造一个表示 ++ 的枚举实例。

INIT

INIT

功能:构造一个表示 init 的枚举实例。

INOUT

INOUT

功能:构造一个表示 inout 的枚举实例。

INT16

INT16

功能:构造一个表示 int16 的枚举实例。

INT32

INT32

功能:构造一个表示 int32 的枚举实例。

INT64

INT64

功能:构造一个表示 int64 的枚举实例。

INT8

INT8

功能:构造一个表示 int8 的枚举实例。

INTEGER_LITERAL

INTEGER_LITERAL

功能:构造一个表示整型字面量的枚举实例。

INTERFACE

INTERFACE

功能:构造一个表示 interface 的枚举实例。

INTERNAL

INTERNAL

功能:构造一个表示 internal 的枚举实例。

INTNATIVE

INTNATIVE

功能:构造一个表示 intnative 的枚举实例。

IS

IS

功能:构造一个表示 is 的枚举实例。

JSTRING_LITERAL

JSTRING_LITERAL

功能:构造一个表示 JavaSTRING字面量 的枚举实例。

LCURL

LCURL

功能:构造一个表示 { 的枚举实例。

LE

LE

功能:构造一个表示 <= 的枚举实例。

LET

LET

功能:构造一个表示 let 的枚举实例。

LPAREN

LPAREN

功能:构造一个表示 ( 的枚举实例。

LSHIFT

LSHIFT

功能:构造一个表示 << 的枚举实例。

LSHIFT_ASSIGN

LSHIFT_ASSIGN

功能:构造一个表示 <<= 的枚举实例。

LSQUARE

LSQUARE

功能:构造一个表示 [ 的枚举实例。

LT

LT

功能:构造一个表示 < 的枚举实例。

MACRO

MACRO

功能:构造一个表示 macro 的枚举实例。

MAIN

MAIN

功能:构造一个表示 main 的枚举实例。

MATCH

MATCH

功能:构造一个表示 match 的枚举实例。

MOD

MOD

功能:构造一个表示 % 的枚举实例。

MOD_ASSIGN

MOD_ASSIGN

功能:构造一个表示 %= 的枚举实例。

MUL

MUL

功能:构造一个表示 * 的枚举实例。

MULTILINE_RAW_STRING

MULTILINE_RAW_STRING

功能:构造一个表示多行原始字符串字面量的枚举实例。

MULTILINE_STRING

MULTILINE_STRING

功能:构造一个表示多行字符串字面量的枚举实例。

MUL_ASSIGN

MUL_ASSIGN

功能:构造一个表示 *= 的枚举实例。

MUT

MUT

功能:构造一个表示 mut 的枚举实例。

NL

NL

功能:构造一个表示换行符的枚举实例。

NOT

NOT

功能:构造一个表示 ! 的枚举实例。

NOTEQ

NOTEQ

功能:构造一个表示 != 的枚举实例。

NOTHING

NOTHING

功能:构造一个表示 nothing 的枚举实例。

NOT_IN

NOT_IN

功能:构造一个表示 !in 的枚举实例。

OPEN

OPEN

功能:构造一个表示 open 的枚举实例。

OPERATOR

OPERATOR

功能:构造一个表示 operator 的枚举实例。

OR

OR

功能:构造一个表示 || 的枚举实例。

OR_ASSIGN

OR_ASSIGN

功能:构造一个表示 ||= 的枚举实例。

OVERRIDE

OVERRIDE

功能:构造一个表示 override 的枚举实例。

PACKAGE

PACKAGE

功能:构造一个表示 package 的枚举实例。

PIPELINE

PIPELINE

功能:构造一个表示 |> 的枚举实例。

PRIVATE

PRIVATE

功能:构造一个表示 private 的枚举实例。

PROP

PROP

功能:构造一个表示 prop 的枚举实例。

PROTECTED

PROTECTED

功能:构造一个表示 protected 的枚举实例。

PUBLIC

PUBLIC

功能:构造一个表示 public 的枚举实例。

QUEST

QUEST

功能:构造一个表示 ? 的枚举实例。

QUOTE

QUOTE

功能:构造一个表示 quote 的枚举实例。

RANGEOP

RANGEOP

功能:构造一个表示 .. 的枚举实例。

RCURL

RCURL

功能:构造一个表示 } 的枚举实例。

REDEF

REDEF

功能:构造一个表示 redef 的枚举实例。

RETURN

RETURN

功能:构造一个表示 return 的枚举实例。

RPAREN

RPAREN

功能:构造一个表示 ) 的枚举实例。

RSHIFT

RSHIFT

功能:构造一个表示 >> 的枚举实例。

RSHIFT_ASSIGN

RSHIFT_ASSIGN

功能:构造一个表示 >>= 的枚举实例。

RSQUARE

RSQUARE

功能:构造一个表示 ] 的枚举实例。

RUNE

RUNE

功能:构造一个表示 Rune 的枚举实例。

RUNE_BYTE_LITERAL

RUNE_BYTE_LITERAL

功能:构造一个表示字符字节字面量的枚举实例。

RUNE_LITERAL

RUNE_LITERAL

功能:构造一个表示字符字面量的枚举实例。

SEALED

SEALED

功能:构造一个表示 sealed 的枚举实例。

SEMI

SEMI

功能:构造一个表示 ; 的枚举实例。

SENTINEL

SENTINEL

功能:构造一个表示 ; 的枚举实例。

SPAWN

SPAWN

功能:构造一个表示 spawn 的枚举实例。

STATIC

STATIC

功能:构造一个表示 static 的枚举实例。

STRING_LITERAL

STRING_LITERAL

功能:构造一个表示字符串字面量的枚举实例。

STRUCT

STRUCT

功能:构造一个表示 struct 的枚举实例。

SUB

SUB

功能:构造一个表示 - 的枚举实例。

SUB_ASSIGN

SUB_ASSIGN

功能:构造一个表示 -= 的枚举实例。

SUPER

SUPER

功能:构造一个表示 super 的枚举实例。

SYNCHRONIZED

SYNCHRONIZED

功能:构造一个表示 synchronized 的枚举实例。

THIS

THIS

功能:构造一个表示 this 的枚举实例。

THISTYPE

THISTYPE

功能:构造一个表示 this 的枚举实例。

THROW

THROW

功能:构造一个表示 throw 的枚举实例。

TRY

TRY

功能:构造一个表示 try 的枚举实例。

TYPE

TYPE

功能:构造一个表示 type 的枚举实例。

UINT16

UINT16

功能:构造一个表示 uint16 的枚举实例。

UINT32

UINT32

功能:构造一个表示 uint32 的枚举实例。

UINT64

UINT64

功能:构造一个表示 uint64 的枚举实例。

UINT8

UINT8

功能:构造一个表示 uint8 的枚举实例。

UINTNATIVE

UINTNATIVE

功能:构造一个表示 uintnative 的枚举实例。

UNIT

UNIT

功能:构造一个表示 unit 的枚举实例。

UNIT_LITERAL

UNIT_LITERAL

功能:构造一个表示 unit 的枚举实例。

UNSAFE

UNSAFE

功能:构造一个表示 unsafe 的枚举实例。

UPPERBOUND

UPPERBOUND

功能:构造一个表示 <: 的枚举实例。

VAR

VAR

功能:构造一个表示 var 的枚举实例。

VARRAY

VARRAY

功能:构造一个表示 varray 的枚举实例。

WHERE

WHERE

功能:构造一个表示 where 的枚举实例。

WHILE

WHILE

功能:构造一个表示 while 的枚举实例。

WILDCARD

WILDCARD

功能:构造一个表示 _ 的枚举实例。

WITH

WITH

功能:构造一个表示 with 的枚举实例。

func !=(TokenKind)

public operator func !=(right: TokenKind): Bool

功能:重载不等号操作符,用于比较两个 TokenKind 是否相等。

返回值:

  • Bool - 布尔类型。

func ==(TokenKind)

public operator func ==(right: TokenKind): Bool

功能:重载等号操作符,用于比较两个 TokenKind 是否相等。

返回值:

  • Bool - 布尔类型。

func toString()

public func toString(): String

功能:将 TokenKind 类型转化为字符串类型表示。

返回值:

结构体

struct Position

public struct Position <: ToBytes {
    public let column: Int32
    public let fileID: UInt32
    public let line: Int32
    public init()
    public init(fileID: UInt32, line: Int32, column: Int32)
}

功能:表示位置信息的数据结构,包含文件ID,行号和列号。

父类型:

let column

public let column: Int32

功能:获取列号信息。

类型:Int32

let fileID

public let fileID: UInt32

功能:获取文件 ID 信息。

类型:UInt32

let line

public let line: Int32

功能:获取行号信息。

类型:Int32

init()

public init()

功能:构造一个默认的 Position 实例,其中 fileIDlinecolumn 成员变量均为 0

init(UInt32, Int32, Int32)

public init(fileID: UInt32, line: Int32, column: Int32)

功能:构造一个 Position 实例。

参数:

  • fileID: UInt32 - 文件ID。
  • line: Int32 - 行号。
  • column: Int32 - 列号。

func dump()

public func dump(): Unit

功能:将 Position 的信息打印出来。

func isEmpty()

public func isEmpty(): Bool

功能:判断行号和列号是否同时为 0

返回值:

  • Bool - 当行号和列号为 0 时返回 true。

func toBytes()

public func toBytes(): Array<UInt8>

功能:Position 类型的序列化。

返回值:

operator func !=(Position)

public operator func !=(r: Position): Bool

功能:比较两个 Position 实例是否不等。

参数:

  • r: Position - 与当前位置比较的另一个位置实例。

返回值:

  • Bool - 当两个 Position 实例不完全相等时返回 true。

operator func ==(Position)

public operator func ==(r: Position): Bool

功能:比较两个 Position 实例是否相等。

参数:

  • r: Position - 与当前位置比较的另一个位置实例。

返回值:

  • Bool - 当两个 Position 实例完全相等时返回 true。

struct Token

public struct Token <: ToBytes {
    public let kind: TokenKind
    public let pos: Position
    public let value: String
    public var delimiterNum: UInt16 = 1
    public init()
    public init(kind: TokenKind)
    public init(kind: TokenKind, value: String)
}

功能:词法单元类型。

词法单元是构成仓颉源码的最小单元,一组合法的词法单元列表经过语法解析后可生成一个语法树节点。

父类型:

let kind

public let kind: TokenKind

功能:词法单元的类型。词法单元类型有关键字、标识符、运算符、常量值等,具体见 TokenKind 章节。

类型:TokenKind

let pos

public let pos: Position

功能:词法单元在源码中的位置信息。

类型:Position

let value

public let value: String

功能:词法单元的字面量值。

类型:String

var delimiterNum

public var delimiterNum: UInt16 = 1

功能:多行字符串的 '#' 符号个数。

类型:UInt16

init()

public init()

功能:构造一个默认的 Token 对象,其中 TokenKind 类型为 ILLEGALvalue 为空字符串,Position 成员变量均为 0。

init(TokenKind)

public init(kind: TokenKind)

功能:根据词法单元类型,构造一个默认的 Token 对象。

参数:

  • kind: TokenKind - 构建词法单元的类型。

init(TokenKind, String)

public init(kind: TokenKind, value: String)

功能:根据词法单元类型 kind 和词法单元值 value,构造一个 Token 对象。

参数:

  • kind: TokenKind - 要构建词法单元的类型。
  • value: String - 要构建词法单元的 value 值。

异常:

func addPosition(UInt32, Int32, Int32)

public func addPosition(fileID: UInt32, line: Int32, colum: Int32): Token

功能:补充词法单元的位置信息。

参数:

返回值:

  • Token - 补充完位置信息后的 Token 对象。

func dump()

public func dump(): Unit

功能:将 Token 的信息打印出来。

func toBytes()

public func toBytes(): Array<UInt8>

功能:Token 类型的序列化。

返回值:

operator func !=(Token)

public operator func !=(r: Token): Bool

功能:判断两个 Token 对象是否不相等。

参数:

  • r: Token - 待比较的另一个 Token 对象。

返回值:

  • Bool - 两个词法单元的种类 ID、值、位置不相同时,返回 true。

operator func +(Token)

public operator func +(r: Token): Tokens

功能:使用当前 Token 添加一个 Token 以获取新的 Tokens

参数:

  • r: Token - 待添加的另一个 Token 对象。

返回值:

operator func +(Tokens)

public operator func +(r: Tokens): Tokens

功能:使用当前 Token 添加一个 Tokens 以获取新的 Tokens

参数:

  • r: Tokens - 待添加的另一组 Token 对象集合。

返回值:

operator func ==(Token)

public operator func ==(r: Token): Bool

功能:判断两个 Token 对象是否相等。

参数:

  • r: Token - 待比较的另一个 Token 对象。

返回值:

  • Bool - 两个词法单元的种类 ID、值、位置相同时,返回 true。

异常类

class ASTException

public class ASTException <: Exception {
    public init()
    public init(message: String)
}

功能:ast 库的异常类,在 ast 库调用过程中发生异常时使用。

父类型:

init()

public init()

功能:构造一个默认的 ASTException 对象。

init(String)

public init(message: String)

功能:根据异常信息构造一个 ASTException 对象。

参数:

  • message: String - 异常信息。

class MacroContextException

public class MacroContextException <: Exception {
    public init()
    public init(message: String)
}

功能:ast库的上下文宏异常类,在上下文宏的相关接口中发生异常时使用。

父类型:

init()

public init()

功能:构造一个默认的 MacroContextException 对象。

init(String)

public init(message: String)

功能:根据异常信息构造一个 MacroContextException 对象。

参数:

  • message: String - 异常信息

class ParseASTException

public class ParseASTException <: Exception {
    public init()
    public init(message: String)
}

功能:ast库的解析异常类,在节点解析过程中发生异常时使用。

父类型:

init()

public init()

功能:构造一个默认的 ParseASTException 对象。

init(String)

public init(message: String)

功能:根据异常信息构造一个 ParseASTException 对象。

参数:

  • message: String - 异常信息。

Macro With Context

宏定义如下:

// macro_definition.cj
macro package macro_definition

import std.ast.*

public macro Outter(input: Tokens): Tokens {
    return input
}

public macro Inner(input: Tokens): Tokens {
    assertParentContext("Outter")
    return input
}

宏调用如下:

// macro_call.cj
package macro_calling

import macro_definition.*

main() {
    @Outter var a = 0
    @Inner var b = 0 // error: The macro call 'Inner' should with the surround code contains a call 'Outter'.
}

编译命令如下:

# 先编译宏定义文件
cjc macro_definition.cj --compile-macro

# 编译使用宏的文件
cjc macro_call.cj -o demo

如上代码所示,Inner 宏在定义时使用了 assertParentContext 函数用于检查其在调用阶段是否位于 Outter 宏中,在代码示例的宏调用场景下,由于 OutterInner 在调用时不存在这样的嵌套关系,因此编译器将报告一个错误。

宏定义如下:

// macro_definition.cj
macro package macro_definition

import std.ast.*

public macro Outter(input: Tokens): Tokens {
    let messages = getChildMessages("Inner")
    for (m in messages) {
        let value1 = m.getString("key1") // get value: "value1"
        let value2 = m.getString("key2") // get value: "value2"
        println("value1: ${value1}  value2: ${value2}")
    }
    return input
}

public macro Inner(input: Tokens): Tokens {
    assertParentContext("Outter")
    setItem("key1", "value1")
    setItem("key2", "value2")
    return input
}

宏调用如下:

// macro_call.cj
import std.ast.*

import macro_definition.*

main() {
    @Outter(
        @Inner var cnt = 0
    )
    println(cnt)
}

编译命令如下:

# 先编译宏定义文件
cjc macro_definition.cj --compile-macro

# 编译使用宏的文件
cjc macro_call.cj -o demo

编译阶段输出:

value1: value1  value2: value2

在上面的代码中,内层宏 Inner 通过 setItem 向外层宏发送信息;Outter 宏通过 getChildMessages 函数接收到 Inner 发送的一组信息对象(Outter 中可以调用多次 Inner);最后通过该信息对象的 getString 函数接收对应的值。

语法树节点打印

仓颉 ast 包提供了丰富的语法树节点用于表示仓颉源码。由于节点种类丰富、不同节点间属性不同,使用过程可能会发生混淆不清的情况,为此我们为每个 AST 节点实现了 dump 函数方便实时查看语法树节点的整体结构,避免重复查看该手册带来的困扰。

示例:

import std.ast.*
main() {
    let input = quote(var demo: Int64 = 1) // 假设当前代码所在行数为:3
    let varDecl = parseDecl(input)
    varDecl.dump()
}

运行结果:

VarDecl {
  -keyword: Token {
    value: "var"
    kind: VAR
    pos: 3: 23
  }
  -identifier: Token {
    value: "demo"
    kind: IDENTIFIER
    pos: 3: 27
  }
  -declType: PrimitiveType {
    -keyword: Token {
      value: "Int64"
      kind: INT64
      pos: 3: 33
    }
  }
  -assign: Token {
    value: "="
    kind: ASSIGN
    pos: 3: 39
  }
  -expr: LitConstExpr {
    -literal: Token {
      value: "1"
      kind: INTEGER_LITERAL
      pos: 3: 41
    }
  }
}

操作 AST 对象示例

获取 ClassDecl 类型的节点后,可以对该节点进行增、删、改、查等操作。代码如下所示:

import std.ast.*
main() {
    let input: Tokens = quote(
        class Data {
            var a: Int32
            init(a_: Int32) {
                a = a_
            }
        }
    )
    let decl = parseDecl(input) // 获取一个 Decl 声明节点
    var classDecl = match (decl as ClassDecl) { // decl 的具体类型为 ClassDecl, 将其进行类型转化。
        case Some(v) => v
        case None => throw Exception()
    }
    var identifier = classDecl.identifier
    // 为该节点增加一个成员函数用于获取a的值
    var funcdecl = FuncDecl(quote(func getValue() {a}))
    classDecl.body.decls.append(funcdecl)
    println("Identifier value is ${identifier.value}")
    println("ClassDecl body size is ${classDecl.body.decls.size}")
    0
}

运行结果:

Identifier value is Data
ClassDecl body size is 3

将仓颉源码解析为 AST 对象示例

如下有一个类 Data:

class Data {
    var a: Int32
    init(a_: Int32) {
        a = a_
    }
}

利用解析函数将上述代码解析为一个 Decl 对象,代码如下所示:

import std.ast.*

main() {
    let input: Tokens = quote(
        class Data {
            var a: Int32
            init(a_: Int32) {
                a = a_
            }
        }
    )
    let decl = parseDecl(input) // 获取一个 Decl 声明节点
    var classDecl = match (decl as ClassDecl) { // decl 的具体类型为 ClassDecl, 将其进行类型转化。
        case Some(v) => v
        case None => throw Exception()
    }
    classDecl.dump()
}

运行结果:

ClassDecl {
  -keyword: Token {
    value: "class"
    kind: CLASS
    pos: 5: 9
  }
  -identifier: Token {
    value: "Data"
    kind: IDENTIFIER
    pos: 5: 15
  }
  -body: Body {
    -decls: 0, VarDecl {
      -keyword: Token {
        value: "var"
        kind: VAR
        pos: 6: 13
      }
      -identifier: Token {
        value: "a"
        kind: IDENTIFIER
        pos: 6: 17
      }
      -declType: PrimitiveType {
        -keyword: Token {
          value: "Int32"
          kind: INT32
          pos: 6: 20
        }
      }
    }
    -decls: 1, FuncDecl {
      -keyword: Token {
        value: "init"
        kind: INIT
        pos: 7: 13
      }
      -identifier: Token {
        value: "init"
        kind: IDENTIFIER
        pos: 7: 13
      }
      -funcParams: 0, FuncParam {
        -identifier: Token {
          value: "a_"
          kind: IDENTIFIER
          pos: 7: 18
        }
        -colon: Token {
          value: ":"
          kind: COLON
          pos: 7: 20
        }
        -paramType: PrimitiveType {
          -keyword: Token {
            value: "Int32"
            kind: INT32
            pos: 7: 22
          }
        }
      }
      -block: Block {
        -nodes: 0, AssignExpr {
          -leftExpr: RefExpr {
            -identifier: Token {
              value: "a"
              kind: IDENTIFIER
              pos: 8: 17
            }
          }
          -assign: Token {
            value: "="
            kind: ASSIGN
            pos: 8: 19
          }
          -rightExpr: RefExpr {
            -identifier: Token {
              value: "a_"
              kind: IDENTIFIER
              pos: 8: 21
            }
          }
        }
      }
    }
  }
}

自定义报错接口

仓颉 ast 包提供了自定义报错接口 diagReport。方便定义宏的用户,在解析传入 Tokens 时,对错误 Tokens 内容进行自定义报错。

自定义报错接口提供同原生编译器报错一样的输出格式,允许用户报 WARNINGERROR 两类错误提示信息。

正确使用示例

宏定义如下:

// macro_definition.cj
macro package macro_definition

import std.ast.*

public macro testDef(input: Tokens): Tokens {
    for (i in 0..input.size) {
        if (input[i].kind == IDENTIFIER) {
            diagReport(DiagReportLevel.ERROR, input[i..(i + 1)], "This expression is not allowed to contain identifier",   "Here is the illegal identifier")
        }
    }
    return input
}

宏调用如下:

// macro_call.cj
package macro_calling

import std.ast.*
import macro_definition.*

main(): Int64 {
    let a = @testDef(1)
    let b = @testDef(a)
    let c = @testDef(1 + a)
    return 0
}

编译命令如下:

# 先编译宏定义文件
cjc macro_definition.cj --compile-macro

# 编译使用宏的文件
cjc macro_call.cj -o demo

报错提示信息如下:

error: This expression is not allowed to contain identifier
 ==> call.cj:9:22:
  |
9 |     let b = @testDef(a)
  |                      ^ Here is the illegal identifier
  |

error: This expression is not allowed to contain identifier
  ==> call.cj:10:26:
   |
10 |     let c = @testDef(1 + a)
   |                          ^ Here is the illegal identifier
   |

2 errors generated, 2 errors printed.

非宏展开过程中调用示例

import std.ast.*

func A(input: Tokens) {
    diagReport(DiagReportLevel.ERROR, input, "Message", "Hint")  // 该调用处在普通函数 A 中,diagReport 实际不会执行任何操作
}

main() {
    let tokens = quote(var a = 0)
    A(tokens)
}

自定义访问函数遍历 AST 对象示例

定义访问变量声明节点的行为:继承 Visitor 并重写访问函数,找到未定义变量,将其变量词法单元存起来。

import std.ast.*

class MyVisitor <: Visitor {
    public var unitializedVars = Tokens() // 存储变量词法单元
    override public func visit(varDecl: VarDecl) {
        try {
            varDecl.expr
        } catch (e: ASTException) {
            unitializedVars.append(varDecl.identifier)
        }
        breakTraverse() // 不会继续遍历 varDecl 的子节点
        return
    }
}

main(): Int64 {
    let input = quote(
        var a : Int64
    )
    let varDecl = parseDecl(input)
    let visitor = MyVisitor() // MyVisitor中定义了对 varDecl 节点的处理
    varDecl.traverse(visitor) // 实现对 varDecl 节点的处理
    println("Unitialized VarDecl size is ${visitor.unitializedVars.size}")
    0
}

运行结果:

Unitialized VarDecl size is 1

std.binary 包

功能介绍

当前 binary 包提供了如下功能:

  • 仓颉数据类型和二进制字节序列间的互相转换接口,分为大端序和小端序两种转换类型。
  • 仓颉数据类型自身大小端序转换的接口。

说明:

  • 一般来说,多字节对象被存储为连续的字节序列。存储器或数字通信链路中,字节的排列顺序称为端序(Endianness)。端序又称字节顺序或者尾序。
  • 字节有两种排列方式:将将一个多位数的低位存储在内存的低地址端,高位存储在内存的高地址端,称为小端序(Little-endian);反之称为大端序(Big-endian)。

API 列表

接口

接口名功能
BigEndianOrder<T>大端序字节序列转换接口。
LittleEndianOrder<T>小端序字节序列转换接口。
SwapEndianOrder<T>反转字节顺序接口。

接口

interface BigEndianOrder<T>

public interface BigEndianOrder<T> {
    func writeBigEndian(buffer: Array<Byte>): Int64
    static func readBigEndian(buffer: Array<Byte>): T
}

功能:大端序字节序列转换接口。

static func readBigEndian(Array<Byte>)

static func readBigEndian(buffer: Array<Byte>): T

功能:从字节数组中以大端序的方式读取一个 T 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

  • T - T 值。

异常:

func writeBigEndian(Array<Byte>)

func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 T 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

extend Bool <: BigEndianOrder<Bool>

extend Bool <: BigEndianOrder<Bool>

功能:为 Bool 扩展 BigEndianOrder 接口,以实现将 Bool 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): Bool

功能:从字节数组中以大端序的方式读取一个 Bool 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x1]
    let n = Bool.readBigEndian(buffer)
    @Assert(n, true)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 Bool 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = true.writeBigEndian(buffer)
    @Assert(n, 1)
    @Assert(buffer[..n], [0x01u8])
}

extend Float16 <: BigEndianOrder<Float16>

extend Float16 <: BigEndianOrder<Float16>

功能:为 Float16 扩展 BigEndianOrder 接口,以实现将 Float16 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): Float16

功能:从字节数组中以大端序的方式读取一个 Float16 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x4A, 0x40]
    let n = Float16.readBigEndian(buffer)
    @Assert(n, 12.5)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 Float16 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 12.5f16.writeBigEndian(buffer)
    @Assert(n, 2)
    @Assert(buffer[..n], [0x4A, 0x40])
}

extend Float32 <: BigEndianOrder<Float32>

extend Float32 <: BigEndianOrder<Float32>

功能:为 Float32 扩展 BigEndianOrder 接口,以实现将 Float32 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): Float32

功能:从字节数组中以大端序的方式读取一个 Float32 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x41, 0x48, 0x00, 0x00]
    let n = Float32.readBigEndian(buffer)
    @Assert(n, 12.5)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 Float32 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 12.5f32.writeBigEndian(buffer)
    @Assert(n, 4)
    @Assert(buffer[..n], [0x41, 0x48, 0x00, 0x00])
}

extend Float64 <: BigEndianOrder<Float64>

extend Float64 <: BigEndianOrder<Float64>

功能:为 Float64 扩展 BigEndianOrder 接口,以实现将 Float64 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): Float64

功能:从字节数组中以大端序的方式读取一个 Float64 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]
    let n = Float64.readBigEndian(buffer)
    @Assert(n, 12.5)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 Float64 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 12.5f64.writeBigEndian(buffer)
    @Assert(n, 8)
    @Assert(buffer[..n], [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
}

extend Int16 <: BigEndianOrder<Int16>

extend Int16 <: BigEndianOrder<Int16>

功能:为 Int16 扩展 BigEndianOrder 接口,以实现将 Int16 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): Int16

功能:从字节数组中以大端序的方式读取一个 Int16 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x12, 0x34]
    let n = Int16.readBigEndian(buffer)
    @Assert(n, 0x1234)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 Int16 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x1234i16.writeBigEndian(buffer)
    @Assert(n, 2)
    @Assert(buffer[..n], [0x12, 0x34])
}

extend Int32 <: BigEndianOrder<Int32>

extend Int32 <: BigEndianOrder<Int32>

功能:为 Int32 扩展 BigEndianOrder 接口,以实现将 Int32 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): Int32

功能:从字节数组中以大端序的方式读取一个 Int32 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x12, 0x34, 0x56, 0x78]
    let n = Int32.readBigEndian(buffer)
    @Assert(n, 0x12345678)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 Int32 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x12345678i32.writeBigEndian(buffer)
    @Assert(n, 4)
    @Assert(buffer[..n], [0x12, 0x34, 0x56, 0x78])
}

extend Int64 <: BigEndianOrder<Int64>

extend Int64 <: BigEndianOrder<Int64>

功能:为 Int64 扩展 BigEndianOrder 接口,以实现将 Int64 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): Int64

功能:从字节数组中以大端序的方式读取一个 Int64 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]
    let n = Int64.readBigEndian(buffer)
    @Assert(n, 0x1234567890123456)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 Int64 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x1234567890123456i64.writeBigEndian(buffer)
    @Assert(n, 8)
    @Assert(buffer[..n], [0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56])
}

extend Int8 <: BigEndianOrder<Int8>

extend Int8 <: BigEndianOrder<Int8>

功能:为 Int8 扩展 BigEndianOrder 接口,以实现将 Int8 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): Int8

功能:从字节数组中以大端序的方式读取一个 Int8 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x12]
    let n = Int8.readBigEndian(buffer)
    @Assert(n, 0x12)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 Int8 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x12i8.writeBigEndian(buffer)
    @Assert(n, 1)
    @Assert(buffer[..n], [0x12])
}

extend UInt16 <: BigEndianOrder<UInt16>

extend UInt16 <: BigEndianOrder<UInt16>

功能:为 UInt16 扩展 BigEndianOrder 接口,以实现将 UInt16 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): UInt16

功能:从字节数组中以大端序的方式读取一个 UInt16 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x12, 0x34]
    let n = UInt16.readBigEndian(buffer)
    @Assert(n, 0x1234)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 UInt16 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x1234u16.writeBigEndian(buffer)
    @Assert(n, 2)
    @Assert(buffer[..n], [0x12, 0x34])
}

extend UInt32 <: BigEndianOrder<UInt32>

extend UInt32 <: BigEndianOrder<UInt32>

功能:为 UInt32 扩展 BigEndianOrder 接口,以实现将 UInt32 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): UInt32

功能:从字节数组中以大端序的方式读取一个 UInt32 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x12, 0x34, 0x56, 0x78]
    let n = UInt32.readBigEndian(buffer)
    @Assert(n, 0x12345678)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 UInt32 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x12345678u32.writeBigEndian(buffer)
    @Assert(n, 4)
    @Assert(buffer[..n], [0x12, 0x34, 0x56, 0x78])
}

extend UInt64 <: BigEndianOrder<UInt64>

extend UInt64 <: BigEndianOrder<UInt64>

功能:为 UInt64 扩展 BigEndianOrder 接口,以实现将 UInt64 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): UInt64

功能:从字节数组中以大端序的方式读取一个 UInt64 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]
    let n = UInt64.readBigEndian(buffer)
    @Assert(n, 0x1234567890123456)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 UInt64 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x1234567890123456u64.writeBigEndian(buffer)
    @Assert(n, 8)
    @Assert(buffer[..n], [0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56])
}

extend UInt8 <: BigEndianOrder<UInt8>

extend UInt8 <: BigEndianOrder<UInt8>

功能:为 UInt8 扩展 BigEndianOrder 接口,以实现将 UInt8 值和大端序字节序列的转换。

父类型:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): UInt8

功能:从字节数组中以大端序的方式读取一个 UInt8 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x12]
    let n = UInt8.readBigEndian(buffer)
    @Assert(n, 0x12)
}

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:将 UInt8 值以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x12u8.writeBigEndian(buffer)
    @Assert(n, 1)
    @Assert(buffer[..n], [0x12])
}

interface LittleEndianOrder<T>

public interface LittleEndianOrder<T> {
    func writeLittleEndian(buffer: Array<Byte>): Int64
    static func readLittleEndian(buffer: Array<Byte>): T
}

功能:小端序字节序列转换接口。

static func readLittleEndian(Array<Byte>)

static func readLittleEndian(buffer: Array<Byte>): T

功能:从字节数组中以小端序的方式读取一个 T 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

  • T - T 值。

异常:

func writeLittleEndian(Array<Byte>)

func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 T 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

extend Bool <: LittleEndianOrder<Bool>

extend Bool <: LittleEndianOrder<Bool>

功能:为 Bool 扩展 LittleEndianOrder 接口,以实现将 Bool 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): Bool

功能:从字节数组中以小端序的方式读取一个 Bool 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x1]
    let n = Bool.readLittleEndian(buffer)
    @Assert(n, true)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 Bool 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = true.writeLittleEndian(buffer)
    @Assert(n, 1)
    @Assert(buffer[..n], [0x01])
}

extend Float16 <: LittleEndianOrder<Float16>

extend Float16 <: LittleEndianOrder<Float16>

功能:为 Float16 扩展 LittleEndianOrder 接口,以实现将 Float16 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): Float16

功能:从字节数组中以小端序的方式读取一个 Float16 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x40, 0x4A]
    let n = Float16.readLittleEndian(buffer)
    @Assert(n, 12.5)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 Float16 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 12.5f16.writeLittleEndian(buffer)
    @Assert(n, 2)
    @Assert(buffer[..n], [0x40, 0x4A])
}

extend Float32 <: LittleEndianOrder<Float32>

extend Float32  <: LittleEndianOrder<Float32>

功能:为 Float32 扩展 LittleEndianOrder 接口,以实现将 Float32 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): Float32

功能:从字节数组中以小端序的方式读取一个 Float32 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x00, 0x00, 0x48, 0x41]
    let n = Float32.readLittleEndian(buffer)
    @Assert(n, 12.5)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 Float32 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 12.5f32.writeLittleEndian(buffer)
    @Assert(n, 4)
    @Assert(buffer[..n], [0x00, 0x00, 0x48, 0x41])
}

extend Float64 <: LittleEndianOrder<Float64>

extend Float64 <: LittleEndianOrder<Float64>

功能:为 Float64 扩展 LittleEndianOrder 接口,以实现将 Float64 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): Float64

功能:从字节数组中以小端序的方式读取一个 Float64 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40]
    let n = Float64.readLittleEndian(buffer)
    @Assert(n, 12.5)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 Float64 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 12.5f64.writeLittleEndian(buffer)
    @Assert(n, 8)
    @Assert(buffer[..n], [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40])
}

extend Int16 <: LittleEndianOrder<Int16>

extend Int16 <: LittleEndianOrder<Int16>

功能:为 Int16 扩展 LittleEndianOrder 接口,以实现将 Int16 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): Int16

功能:从字节数组中以小端序的方式读取一个 Int16 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x34, 0x12]
    let n = Int16.readLittleEndian(buffer)
    @Assert(n, 0x1234i16)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 Int16 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x1234i16.writeLittleEndian(buffer)
    @Assert(n, 2)
    @Assert(buffer[..n], [0x34, 0x12])
}

extend Int32 <: LittleEndianOrder<Int32>

extend Int32 <: LittleEndianOrder<Int32>

功能:为 Int32 扩展 LittleEndianOrder 接口,以实现将 Int32 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): Int32

功能:从字节数组中以小端序的方式读取一个 Int32 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x78, 0x56, 0x34, 0x12]
    let n = Int32.readLittleEndian(buffer)
    @Assert(n, 0x12345678i32)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 Int32 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x12345678i32.writeLittleEndian(buffer)
    @Assert(n, 4)
    @Assert(buffer[..n], [0x78, 0x56, 0x34, 0x12])
}

extend Int64 <: LittleEndianOrder<Int64>

extend Int64 <: LittleEndianOrder<Int64>

功能:为 Int64 扩展 LittleEndianOrder 接口,以实现将 Int64 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): Int64

功能:从字节数组中以小端序的方式读取一个 Int64 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]
    let n = Int64.readLittleEndian(buffer)
    @Assert(n, 0x1234567890123456i64)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 Int64 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x1234567890123456i64.writeLittleEndian(buffer)
    @Assert(n, 8)
    @Assert(buffer[..n], [0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12])
}

extend Int8 <: LittleEndianOrder<Int8>

extend Int8 <: LittleEndianOrder<Int8>

功能:为 Int8 扩展 LittleEndianOrder 接口,以实现将 Int8 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): Int8

功能:从字节数组中以小端序的方式读取一个 Int8 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x12]
    let n = Int8.readLittleEndian(buffer)
    @Assert(n, 0x12)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 Int8 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x12i8.writeLittleEndian(buffer)
    @Assert(n, 1)
    @Assert(buffer[..n], [0x12])
}

extend UInt16 <: LittleEndianOrder<UInt16>

extend UInt16 <: LittleEndianOrder<UInt16>

功能:为 UInt16 扩展 LittleEndianOrder 接口,以实现将 UInt16 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): UInt16

功能:从字节数组中以小端序的方式读取一个 UInt16 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x34, 0x12]
    let n = UInt16.readLittleEndian(buffer)
    @Assert(n, 0x1234u16)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 UInt16 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x1234u16.writeLittleEndian(buffer)
    @Assert(n, 2)
    @Assert(buffer[..n], [0x34, 0x12])
}

extend UInt32 <: LittleEndianOrder<UInt32>

extend UInt32 <: LittleEndianOrder<UInt32>

功能:为 UInt32 扩展 LittleEndianOrder 接口,以实现将 UInt32 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): UInt32

功能:从字节数组中以小端序的方式读取一个 UInt32 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x78, 0x56, 0x34, 0x12]
    let n = UInt32.readLittleEndian(buffer)
    @Assert(n, 0x12345678i32)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 UInt32 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x12345678u32.writeLittleEndian(buffer)
    @Assert(n, 4)
    @Assert(buffer[..n], [0x78, 0x56, 0x34, 0x12])
}

extend UInt64 <: LittleEndianOrder<UInt64>

extend UInt64 <: LittleEndianOrder<UInt64>

功能:为 UInt64 扩展 LittleEndianOrder 接口,以实现将 UInt64 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): UInt64

功能:从字节数组中以小端序的方式读取一个 UInt64 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]
    let n = UInt64.readLittleEndian(buffer)
    @Assert(n, 0x1234567890123456i64)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 UInt64 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x1234567890123456u64.writeLittleEndian(buffer)
    @Assert(n, 8)
    @Assert(buffer[..n], [0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12])
}

extend UInt8 <: LittleEndianOrder<UInt8>

extend UInt8 <: LittleEndianOrder<UInt8>

功能:为 UInt8 扩展 LittleEndianOrder 接口,以实现将 UInt8 值和小端序字节序列的转换。

父类型:

static func readLittleEndian(Array<Byte>)

public static func readLittleEndian(buffer: Array<Byte>): UInt8

功能:从字节数组中以小端序的方式读取一个 UInt8 值。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

返回值:

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x12]
    let n = UInt8.readLittleEndian(buffer)
    @Assert(n, 0x12)
}

func writeLittleEndian(Array<Byte>)

public func writeLittleEndian(buffer: Array<Byte>): Int64

功能:将 UInt8 值以小端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

返回值:

  • Int64 - 写入的数据的字节数。

异常:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x12u8.writeLittleEndian(buffer)
    @Assert(n, 1)
    @Assert(buffer[..n], [0x12])
}

interface SwapEndianOrder<T>

public interface SwapEndianOrder<T> {
    func swapBytes(): T
}

功能:反转字节顺序接口。

func swapBytes()

func swapBytes(): T

功能:反转 T 值的字节顺序。

返回值:

  • T - T 值。

extend Int16 <: SwapEndianOrder<Int16>

extend Int16 <: SwapEndianOrder<Int16>

功能:为 Int16 扩展 SwapEndianOrder 接口,以实现将 Int16 值的字节顺序反转。

父类型:

func swapBytes()

public func swapBytes(): Int16

功能:反转 Int16 值的字节顺序。

返回值:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let n = 0x1234i16
    let m = n.swapBytes()
    @Assert(m, 0x3412)
}

extend Int32 <: SwapEndianOrder<Int32>

extend Int32 <: SwapEndianOrder<Int32>

功能:为 Int32 扩展 SwapEndianOrder 接口,以实现将 Int32 值的字节顺序反转。

父类型:

func swapBytes()

public func swapBytes(): Int32

功能:反转 Int32 值的字节顺序。

返回值:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let n = 0x12345678i32
    let m = n.swapBytes()
    @Assert(m, 0x78563412)
}

extend Int64 <: SwapEndianOrder<Int64>

extend Int64 <: SwapEndianOrder<Int64>

功能:为 Int64 扩展 SwapEndianOrder 接口,以实现将 Int64 值的字节顺序反转。

父类型:

func swapBytes()

public func swapBytes(): Int64

功能:反转 Int64 值的字节顺序。

返回值:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let n = 0x1234567890123456i64
    let m = n.swapBytes()
    @Assert(m, 0x5634129078563412)
}

extend Int8 <: SwapEndianOrder<Int8>

extend Int8 <: SwapEndianOrder<Int8>

功能:为 Int8 扩展 SwapEndianOrder 接口,以实现将 Int8 值的字节顺序反转。

父类型:

func swapBytes()

public func swapBytes(): Int8

功能:反转 Int8 值的字节顺序。

返回值:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let n = 0x12i8
    let m = n.swapBytes()
    @Assert(m, 0x12)
}

extend UInt16 <: SwapEndianOrder<UInt16>

extend UInt16 <: SwapEndianOrder<UInt16>

功能:为 UInt16 扩展 SwapEndianOrder 接口,以实现将 UInt16 值的字节顺序反转。

父类型:

func swapBytes()

public func swapBytes(): UInt16

功能:反转 UInt16 值的字节顺序。

返回值:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let n = 0x1234u16
    let m = n.swapBytes()
    @Assert(m, 0x3412)
}

extend UInt32 <: SwapEndianOrder<UInt32>

extend UInt32 <: SwapEndianOrder<UInt32>

功能:为 UInt32 扩展 SwapEndianOrder 接口,以实现将 UInt32 值的字节顺序反转。

父类型:

func swapBytes()

public func swapBytes(): UInt32

功能:反转 UInt32 值的字节顺序。

返回值:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let n = 0x12345678u32
    let m = n.swapBytes()
    @Assert(m, 0x78563412)
}

extend UInt64 <: SwapEndianOrder<UInt64>

extend UInt64 <: SwapEndianOrder<UInt64>

功能:为 UInt64 扩展 SwapEndianOrder 接口,以实现将 UInt64 值的字节顺序反转。

父类型:

func swapBytes()

public func swapBytes(): UInt64

功能:反转 UInt64 值的字节顺序。

返回值:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let n = 0x1234567890123456u64
    let m = n.swapBytes()
    @Assert(m, 0x5634129078563412)
}

extend UInt8 <: SwapEndianOrder<UInt8>

extend UInt8 <: SwapEndianOrder<UInt8>

功能:为 UInt8 扩展 SwapEndianOrder 接口,以实现将 UInt8 值的字节顺序反转。

父类型:

func swapBytes()

public func swapBytes(): UInt8

功能:反转 UInt8 值的字节顺序。

返回值:

示例:

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let n = 0x12u8
    let m = n.swapBytes()
    @Assert(m, 0x12)
}

std.collection 包

功能介绍

collection 包提供了常见数据结构的高效实现、相关抽象的接口的定义以及在集合类型中常用的函数功能。

本包实现了以下常用的数据结构:

  • ArrayList:变长的连续数组,在需要存储不确定数量的数据,或者需要根据运行时的条件动态调整数组大小时使用 ArrayList,使用 ArrayList 可能会导致内存分配和释放的开销增加,因此需要谨慎使用。

  • LinkedList:链表结构, LinkedList 的优点是它可以动态地添加或删除元素,而不需要移动其他元素。这使得它在需要频繁添加或删除元素的情况下非常有用。它还可以轻松地进行修改或删除操作,并且可以在列表中存储多个元素。 LinkedList 的缺点是它需要额外的内存来存储每个元素的引用,这可能会导致内存浪费。

  • HashMap:哈希表,它存储键值对,并且可以根据键快速访问值。在需要使用映射关系并且需要快速查找时使用。

  • HashSet:基于哈希表实现的集合数据结构,它可以用于快速检索和删除元素,具有高效的插入、删除和查找操作。

  • TreeMap:基于红黑树实现的有序映射表。通常情况下,当需要将元素按照自然顺序或者自定义顺序进行排序时,可以使用TreeMap。

collection 包提供的集合类型都不支持并发安全,并发安全的集合请见 collection.concurrent 包

API 列表

函数

函数名功能
all<T>((T) -> Bool)判断迭代器所有元素是否都满足条件。
any<T>((T) -> Bool)判断迭代器是否存在任意一个满足条件的元素。
at<T>(Int64)获取迭代器指定位置的元素。
collectArrayList<T>(Iterable<T>)将一个迭代器转换成 ArrayList 类型。
collectArray<T>(Iterable<T>)将一个迭代器转换成 Array 类型。
collectHashMap<K, V>(Iterable<(K, V)>) where K <: Hashable & Equatable<K>将一个迭代器转换成 HashMap 类型。
collectHashSet<T>(Iterable<T>) where T <: Hashable & Equatable<T>将一个迭代器转换成 HashSet 类型。
collectString<T>(String) where T <: ToString将一个对应元素实现了 ToString 接口的迭代器转换成 String 类型。
concat<T>(Iterable<T>)串联两个迭代器。
contains<T>(T) where T <: Equatable<T>遍历所有元素,判断是否包含指定元素并返回该元素。
count<T>(Iterable<T>)统计迭代器包含元素数量。
enumerate<T>(Iterable<T>)用于获取带索引的迭代器。
filter<T>((T) -> Bool)筛选出满足条件的元素。
filterMap<T, R>((T) -> ?R)同时进行筛选操作和映射操作,返回一个新的迭代器。
first<T>(Iterable<T>)获取头部元素。
flatMap<T, R>( (T) -> Iterable<R>)创建一个带 flatten 功能的映射。
flatten<T, R>(Iterable<T>) where T <: Iterable<R>将嵌套的迭代器展开一层。
fold<T, R>(R, (R, T) -> R)使用指定初始值,从左向右计算。
forEach<T>((T) -> Unit)遍历所有元素,指定给定的操作。
inspect<T>((T) -> Unit)迭代器每次调用 next() 对当前元素执行额外操作(不会消耗迭代器中元素)。
isEmpty<T>(Iterable<T>)判断迭代器是否为空。
last<T>(Iterable<T>)获取尾部元素。
map<T, R>((T) -> R)创建一个映射。
max<T>(Iterable<T>) where T <: Comparable<T>筛选最大的元素。
min<T>(Iterable<T>) where T <: Comparable<T>筛选最小的元素。
none<T>((T) -> Bool)判断迭代器是否都不满足条件。
reduce<T>((T, T) -> T)使用第一个元素作为初始值,从左向右计算。
skip<T>(Int64)从迭代器跳过特定个数。
step<T>(Int64)迭代器每次调用 next() 跳过特定个数。
take<T>(Int64)从迭代器取出特定个数。
zip<T, R>(Iterable<R>)将两个迭代器合并成一个(长度取决于短的那个迭代器)。

接口

接口名功能
Map<K, V> where K <: Equatable<K>提供了一种将键映射到值的方式。
Set<T> where T <: Equatable<T>不包含重复元素的集合。
EquatableCollection<T> where T <: Equatable<T>定义了可以进行比较的集合类型。

类名功能
ArrayList<T>提供可变长度的数组的功能。
ArrayListIterator<T>此类主要实现 ArrayList<T> 的迭代器功能。
HashMapIterator<K, V> where K <: Hashable & Equatable<K>此类主要实现 HashMap 的迭代器功能。
HashMap<K, V> where K <: Hashable & Equatable<K>Map<K, V> where K <: Equatable<K> 接口的哈希表实现。
HashSet<T> where T <: Hashable & Equatable<T>基于 HashMap<K, V> where K <: Hashable & Equatable<K> 实现的 Set<T> where T <: Equatable<T> 接口的实例。
LinkedListNode<T>LinkedList<T> 上的节点。
LinkedList<T>实现双向链表的数据结构。
TreeMap<K, V> where K <: Comparable<K>基于平衡二叉搜索树实现的 Map<K, V> where K <: Equatable<K> 接口实例。

结构体

异常类

异常类名功能
ConcurrentModificationException并发修改异常类。

函数

func all<T>((T) -> Bool)

public func all<T>(predicate: (T) -> Bool): (Iterable<T>) -> Bool

功能:判断迭代器所有元素是否都满足条件。

参数:

  • predicate: (T) -> Bool - 给定的条件。

返回值:

  • (Iterable<T>) -> Bool - 返回一个判断全部满足条件的函数。

func any<T>((T) -> Bool)

public func any<T>(predicate: (T) -> Bool): (Iterable<T>) -> Bool

功能:判断迭代器是否存在任意一个满足条件的元素。

参数:

  • predicate: (T) -> Bool - 给定的条件。

返回值:

  • (Iterable<T>) -> Bool - 返回一个判断存在任意一个满足条件的函数。

func at<T>(Int64)

public func at<T>(n: Int64): (Iterable<T>) -> Option<T>

功能:获取迭代器指定位置的元素。

参数:

  • n: Int64 - 给定的个数。

返回值:

  • (Iterable<T>) -> Option<T> - 返回获取对应位置元素的函数,若迭代器为空则该函数返回 None。

func collectArrayList<T>(Iterable<T>)

public func collectArrayList<T>(it: Iterable<T>): ArrayList<T>

功能:将一个迭代器转换成 ArrayList 类型。

参数:

  • it: Iterable<T> - 给定的迭代器。

返回值:

func collectArray<T>(Iterable<T>)

public func collectArray<T>(it: Iterable<T>): Array<T>

功能:将一个迭代器转换成 Array 类型。

参数:

  • it: Iterable<T> - 给定的迭代器。

返回值:

  • Array<T> - 返回一个数组。

func collectHashMap<K, V>(Iterable<(K, V)>) where K <: Hashable & Equatable<K>

public func collectHashMap<K, V>(it: Iterable<(K, V)>): HashMap<K, V> where K <: Hashable & Equatable<K>

功能:将一个迭代器转换成 HashMap 类型。

参数:

  • it: Iterable<(K, V)> - 给定的迭代器。

返回值:

func collectHashSet<T>(Iterable<T>) where T <: Hashable & Equatable<T>

public func collectHashSet<T>(it: Iterable<T>): HashSet<T> where T <: Hashable & Equatable<T>

功能:将一个迭代器转换成 HashSet 类型。

参数:

  • it: Iterable<T> - 给定的迭代器。

返回值:

func collectString<T>(String) where T <: ToString

public func collectString<T>(delimiter!: String = ""): (Iterable<T>) -> String where T <: ToString

功能:将一个对应元素实现了 ToString 接口的迭代器转换成 String 类型。

参数:

  • delimiter!: String - 字符串拼接分隔符。

返回值:

func concat<T>(Iterable<T>)

public func concat<T>(other: Iterable<T>): (Iterable<T>) -> Iterator<T>

功能:串联两个迭代器。

参数:

  • other: Iterable<T> - 要串联在后面的迭代器。

返回值:

func contains<T>(T) where T <: Equatable<T>

public func contains<T>(element: T): (Iterable<T>) -> Bool where T <: Equatable<T>

功能:遍历所有元素,判断是否包含指定元素并返回该元素。

参数:

  • element: T - 要查找的元素。

返回值:

func count<T>(Iterable<T>)

public func count<T>(it: Iterable<T>): Int64

功能:统计迭代器包含元素数量。

参数:

  • it: Iterable<T> - 给定的迭代器。

返回值:

  • Int64 - 返回迭代器包含元素数量。

func enumerate<T>(Iterable<T>)

public func enumerate<T>(it: Iterable<T>): Iterator<(Int64, T)>

功能:用于获取带索引的迭代器。

参数:

  • it: Iterable<T> - 给定的迭代器。

返回值:

func filter<T>((T) -> Bool)

public func filter<T>(predicate: (T) -> Bool): (Iterable<T>) -> Iterator<T>

功能:筛选出满足条件的元素。

参数:

  • predicate: (T) -> Bool - 给定的条件。

返回值:

func filterMap<T, R>((T) -> ?R)

public func filterMap<T, R>(transform: (T)-> ?R): (Iterable<T>) ->Iterator<R>

功能:同时进行筛选操作和映射操作,返回一个新的迭代器。

参数:

  • transform: (T) -> ?R - 给定的映射函数。函数返回值为 Some 对应 filter 的 predicate 为 true,反之表示 false。

返回值:

func first<T>(Iterable<T>)

public func first<T>(it: Iterable<T>): Option<T>

功能:获取头部元素。

参数:

  • it: Iterable<T> - 给定的迭代器。

返回值:

  • Option<T> - 返回头部元素,若为空则返回 None。

func flatMap<T, R>( (T) -> Iterable<R>)

public func flatMap<T, R>(transform: (T) -> Iterable<R>): (Iterable<T>) -> Iterator<R>

功能:创建一个带 flatten 功能的映射。

参数:

  • transform: (T) -> Iterable<R> - 给定的映射函数。

返回值:

func flatten<T, R>(Iterable<T>) where T <: Iterable<R>

public func flatten<T, R>(it: Iterable<T>): Iterator<R> where T <: Iterable<R>

功能:将嵌套的迭代器展开一层。

参数:

  • it: Iterable<T> - 给定的迭代器。

返回值:

  • Iterator<R> - 返回展开一层后的迭代器。

func fold<T, R>(R, (R, T) -> R)

public func fold<T, R>(initial: R, operation: (R, T) -> R): (Iterable<T>) -> R

功能:使用指定初始值,从左向右计算。

参数:

  • initial: R - 给定的 R 类型的初始值。
  • operation: (R, T) -> R - 给定的计算函数。

返回值:

  • (Iterable<T>) -> R - 返回一个折叠函数。

func forEach<T>((T) -> Unit)

public func forEach<T>(action: (T) -> Unit): (Iterable<T>) -> Unit

功能:遍历所有元素,指定给定的操作。

参数:

  • action: (T) -> Unit - 给定的操作函数。

返回值:

  • (Iterable<T>) -> Unit - 返回一个执行遍历操作的函数。

func inspect<T>((T) -> Unit)

public func inspect<T>(action: (T)->Unit): (Iterable<T>) ->Iterator<T>

功能:迭代器每次调用 next() 对当前元素执行额外操作(不会消耗迭代器中元素)。

参数:

  • action: (T) -> Unit - 给定的操作函数。

返回值:

  • (Iterable<T>) -> Iterator<T> - 返回一个能对迭代器每个元素执行额外操作的函数。

func isEmpty<T>(Iterable<T>)

public func isEmpty<T>(it: Iterable<T>): Bool

功能:判断迭代器是否为空。

参数:

  • it: Iterable<T> - 给定的迭代器。

返回值:

  • Bool - 返回迭代器是否为空。

func last<T>(Iterable<T>)

public func last<T>(it: Iterable<T>): Option<T>

功能:获取尾部元素。

参数:

  • it: Iterable<T> - 给定的迭代器。

返回值:

  • Option<T> - 返回尾部元素,若为空则返回 None。

func map<T, R>((T) -> R)

public func map<T, R>(transform: (T) -> R): (Iterable<T>) -> Iterator<R>

功能:创建一个映射。

参数:

  • transform: (T) ->R - 给定的映射函数。

返回值:

func max<T>(Iterable<T>) where T <: Comparable<T>

public func max<T>(it: Iterable<T>): Option<T> where T <: Comparable<T>

功能:筛选最大的元素。

参数:

  • it: Iterable<T> - 给定的迭代器。

返回值:

  • Option<T> - 返回最大的元素,若为空则返回 None。

func min<T>(Iterable<T>) where T <: Comparable<T>

public func min<T>(it: Iterable<T>): Option<T> where T <: Comparable<T>

功能:筛选最小的元素。

参数:

  • it: Iterable<T> - 给定的迭代器。

返回值:

  • Option<T> - 返回最小的元素,若为空则返回 None。

func none<T>((T) -> Bool)

public func none<T>(predicate: (T) -> Bool): (Iterable<T>) -> Bool

功能:判断迭代器中所有元素是否都不满足条件。

参数:

  • predicate: (T) -> Bool - 给定的条件。

返回值:

  • (Iterable<T>) -> Bool - 返回一个判断都不满足条件的函数。

func reduce<T>((T, T) -> T)

public func reduce<T>(operation: (T, T) -> T): (Iterable<T>) -> Option<T>

功能:使用第一个元素作为初始值,从左向右计算。

参数:

  • operation: (T, T) -> T - 给定的操作函数。

返回值:

func skip<T>(Int64)

public func skip<T>(count: Int64): (Iterable<T>) -> Iterator<T>

功能:从迭代器跳过特定个数。

当 count 小于 0 时,抛异常。当 count 等于 0 时,相当没有跳过任何元素,返回原迭代器。当 count 大于0并且count小于迭代器的大小时,跳过 count 个元素后,返回含有剩下的元素的新迭代器。当 count 大于等于迭代器的大小时,跳过所有元素,返回空迭代器。

参数:

  • count: Int64 - 要跳过的个数。

返回值:

  • (Iterable<T>) -> Iterator<T> - 返回一个跳过指定数量元素的函数。

异常:

func step<T>(Int64)

public func step<T>(count: Int64): (Iterable<T>) -> Iterator<T>

功能:迭代器每次调用 next() 跳过特定个数。

当 count 小于等于 0 时,抛异常。当 count 大于 0 时,每次调用 next() 跳过 count 次,直到迭代器为空。

参数:

  • count: Int64 - 每次调用 next() 要跳过的个数。

返回值:

  • (Iterable<T>) -> Iterator<T> - 返回改变迭代器每次调用 next() 跳过特定个数的函数。

异常:

func take<T>(Int64)

public func take<T>(count: Int64): (Iterable<T>) -> Iterator<T>

功能:从迭代器取出特定个数。

当 count 小于 0 时,抛异常。当 count 等于 0 时,不取元素,返回空迭代器。当 count 大于 0 小于迭代器的大小时,取前 count 个元素,返回新迭代器。当 count 大于等于迭代器的大小时,取所有元素,返回原迭代器。

参数:

  • count: Int64 - 要取出的个数。

返回值:

  • (Iterable<T>) -> Iterator<T> - 返回一个取出指定数量元素的函数。

异常:

func zip<T, R>(Iterable<R>)

public func zip<T, R>(other: Iterable<R>): (Iterable<T>) -> Iterator<(T, R)>

功能:将两个迭代器合并成一个(长度取决于短的那个迭代器)。

参数:

  • other: Iterable<R> - 要合并的其中一个迭代器。

返回值:

接口

interface EquatableCollection<T> where T <: Equatable<T>

public interface EquatableCollection<T> <: Collection<T> where T <: Equatable<T> {
    func contains(element: T): Bool
    func containsAll(elements: Collection<T>): Bool
}

功能:定义了可以进行比较的集合类型。

父类型:

func contains(T)

func contains(element: T): Bool

功能:判断 Keys 是否包含指定元素。

参数:

  • element: T - 指定元素,待判断 Keys 是否包含该元素。

返回值:

  • Bool - 包含返回 true,否则返回 false。

func containsAll(Collection<T>)

func containsAll(elements: Collection<T>): Bool

功能:判断 Keys 是否包含指定集合的所有元素。

参数:

  • elements: Collection<T> - 待判断的集合 elements。

返回值:

  • Bool - 包含则返回 true,否则返回 false。

interface Map<K, V> where K <: Equatable<K>

功能:Map 接口提供了一种将键映射到值的方式。它允许我们使用键来查找值,因此可以用于存储和操作键值对。

map不能包含重复的key,每个key最多只能映射到一个value。

public interface Map<K, V> <: Collection<(K, V)> where K <: Equatable<K> {
    func get(key: K): Option<V>
    func contains(key: K): Bool
    func containsAll(keys: Collection<K>): Bool
    mut func put(key: K, value: V): Option<V>
    mut func putAll(elements: Collection<(K, V)>): Unit
    mut func remove(key: K): Option<V>
    mut func removeAll(keys: Collection<K>): Unit
    mut func removeIf(predicate: (K, V) -> Bool): Unit
    mut func clear(): Unit
    func clone(): Map<K, V>
    operator func [](key: K): V
    operator func [](key: K, value!: V): Unit
    func keys(): EquatableCollection<K>
    func values(): Collection<V>
    prop size: Int64
    func isEmpty(): Bool
    func iterator(): Iterator<(K, V)>
}

父类型:

prop size

prop size: Int64

功能:返回 Map 中所有的键值对的个数。

类型:Int64

func clear()

mut func clear(): Unit

功能:清除所有键值对。

func clone()

func clone(): Map<K, V>

功能:克隆 Map

返回值:

  • Map < K, V > - 返回一个 Map<K, V>。

func contains(K)

func contains(key: K): Bool

功能:判断是否包含指定键的映射。

参数:

  • key: K - 传递要判断的 key。

返回值:

  • Bool - 如果存在,则返回 true;否则,返回 false。

func containsAll(Collection<K>)

func containsAll(keys: Collection<K>): Bool

功能:判断是否包含指定集合键的映射。

参数:

  • keys: Collection<K> - 传递待判断的 key 的集合。

返回值:

  • Bool - 如果存在,则返回 true;否则,返回 false。

func get(K)

func get(key: K): Option<V>

功能:根据 key 得到 Map 中映射的值。

参数:

  • key: K - 传递 key,获取 value。

返回值:

func isEmpty()

func isEmpty(): Bool

功能:检查 Map 是否为空。

返回值:

  • Bool - 如果 Map 为空,返回 true; 否则,返回 false

func iterator()

func iterator(): Iterator<(K, V)>

功能:返回 Map 的迭代器。

返回值:

func keys()

func keys(): EquatableCollection<K>

功能:返回 Map 中所有的 key,并将所有 key 存储在一个 EquatableCollection<K> 容器中。

返回值:

func put(K, V)

mut func put(key: K, value: V): Option<V>

功能:将传入的键值对放入该 Map 中。对于 Map 中已有的键,该键映射的值将被新值替换。

参数:

  • key: K - 要放置的键。
  • value: V - 要分配的值。

返回值:

  • Option<V> - 如果赋值之前 key 存在,旧的 value 用 Option 封装;否则,返回 Option<V>.None。

func putAll(Collection<(K, V)>)

mut func putAll(elements: Collection<(K, V)>): Unit

功能:将新的键值对放入 Map 中。对于 Map 中已有的键,该键映射的值将被新值替换。

参数:

  • elements: Collection<(K, V)> - 需要放入到 Map 中的键值对集合。

func remove(K)

mut func remove(key: K): Option<V>

功能:从此 Map 中删除指定键的映射(如果存在)。

参数:

  • key: K - 传入要删除的 key。

返回值:

func removeAll(Collection<K>)

mut func removeAll(keys: Collection<K>): Unit

功能:从此映射中删除指定集合的映射(如果存在)。

参数:

  • keys: Collection<K> - 传入要删除的集合。

func removeIf((K, V) -> Bool)

mut func removeIf(predicate: (K, V) -> Bool): Unit

功能:传入 lambda 表达式,如果满足条件,则删除对应的键值对。

参数:

  • predicate: (K, V) ->Bool - 传递一个 lambda 表达式进行判断。

func values()

func values(): Collection<V>

功能:返回 Map 中所有的 value,并将所有 value 存储在一个 Collection<V> 容器中。

返回值:

operator func [](K)

operator func [](key: K): V

功能:运算符重载集合,如果键存在,返回键对应的值,如果不存在,抛出异常。

参数:

  • key: K - 需要进行查找的键。

返回值:

  • V - 与键对应的值。

operator func [](K, V)

operator func [](key: K, value!: V): Unit

功能:运算符重载集合,如果键存在,新 value 覆盖旧 value,如果键不存在,添加此键值对。

参数:

  • key: K - 需要进行设置的键。
  • value!: V - 传递要设置的值。

interface Set<T> where T <: Equatable<T>

public interface Set<T> <: Collection<T> where T <: Equatable<T> {
    func contains(element: T): Bool
    func subsetOf(other: Set<T>): Bool
    func containsAll(elements: Collection<T>): Bool
    mut func put(element: T): Bool
    mut func putAll(elements: Collection<T>): Unit
    mut func remove(element: T): Bool
    mut func removeAll(elements: Collection<T>): Unit
    mut func removeIf(predicate: (T) -> Bool): Unit
    mut func clear(): Unit
    mut func retainAll(elements: Set<T>): Unit
    func clone(): Set<T>
}

功能:不包含重复元素的集合。

Set 接口不规定内部的实现方式,在 Set 接口的实例中,其内部的元素通常是无序的,不能通过索引访问,也不能保证元素的插入顺序。

父类型:

func clear()

mut func clear(): Unit

功能:清除所有键值对。

func clone()

func clone(): Set<T>

功能:克隆此 Set,并返回克隆出的新的 Set

返回值:

func contains(T)

func contains(element: T): Bool

功能:如果该集合包含指定元素,则返回 true。

参数:

  • element: T - 需要判断的元素。

返回值:

  • Bool - 如果包含,则返回 true;否则,返回 false。

func containsAll(Collection<T>)

func containsAll(elements: Collection<T>): Bool

功能:检查该集合是否包含其他集合。

参数:

返回值:

  • Bool - 如果该集合包含指定集合,则返回 true;否则,返回 false。

func put(T)

mut func put(element: T): Bool

功能:添加元素操作。如果元素已经存在,则不会添加它。

参数:

  • element: T - 要添加的元素。

返回值:

  • Bool - 如果添加成功,则返回 true;否则,返回 false。

func putAll(Collection<T>)

mut func putAll(elements: Collection<T>): Unit

功能:添加 Collection 中的所有元素至此 Set 中,如果元素存在,则不添加。

参数:

  • elements: Collection<T> - 需要被添加的元素的集合。

func remove(T)

mut func remove(element: T): Bool

功能:从该集合中移除指定元素(如果存在)。

参数:

  • element: T - 要删除的元素。

返回值:

  • Bool - 集合中存在指定的元素并且删除成功返回 true,否则返回 false

func removeAll(Collection<T>)

mut func removeAll(elements: Collection<T>): Unit

功能:移除此 Set 中那些也包含在指定 Collection 中的所有元素。

参数:

func removeIf((T) -> Bool)

mut func removeIf(predicate: (T) -> Bool): Unit

功能:传入 lambda 表达式,如果满足 true 条件,则删除对应的元素。

参数:

  • predicate: (T) ->Bool - 传入一个 lambda 表达式进行判断。

func retainAll(Set<T>)

mut func retainAll(elements: Set<T>): Unit

功能:仅保留该 Set 与入参 Set 中重复的元素。

参数:

  • elements: Set<T> - 要保存的元素集合。

func subsetOf(Set<T>)

func subsetOf(other: Set<T>): Bool

功能:检查该集合是否为其他集合的子集。

参数:

  • other: Set<T> - 其他集合。

返回值:

  • Bool - 果该集合是指定集合的子集,则返回 true;否则,返回 false。

class ArrayList<T>

public class ArrayList<T> <: Collection<T> {
    public init()
    public init(capacity: Int64)
    public init(size: Int64, initElement: (Int64) -> T)
    public init(elements: Array<T>)
    public init(elements: Collection<T>)
}

功能:提供可变长度的数组的功能。

ArrayList 是一种线性的动态数组,与 Array 不同,它可以根据需要自动调整大小,并且在创建时不需要指定大小。

说明:

  • 当向动态数组中添加元素时,如果数组已满,则会重新分配更大的内存空间,并将原有的元素复制到新的内存空间中。

  • 动态数组的优点是可以节省内存空间,并且可以根据需要自动调整大小,因此非常适合需要频繁添加或删除元素的情况。但是,动态数组的缺点是在重新分配内存空间时可能会导致性能下降,因此在使用动态数组时需要考虑这一点。

父类型:

prop size

public prop size: Int64

功能:返回此 ArrayList 中的元素个数。

类型:Int64

init()

public init()

功能:构造一个初始容量大小为默认值16ArrayList

init(Array<T>)

public init(elements: Array<T>)

功能:构造一个包含指定数组中所有元素的 ArrayList

注意:

当 T 的类型是 Int64 时,此构造函数的变长参数语法糖版本可能会和 public init(Int64) 产生歧义,比如 ArrayList<Int64>(8, 9) 是构造一个包含两个元素的 ArrayList, 而 ArrayList<Int64>(8) 是构造一个容量为 8 的 ArrayList

参数:

  • elements: Array<T> - 传入数组。

init(Collection<T>)

public init(elements: Collection<T>)

功能:构造一个包含指定集合中所有元素的 ArrayList。这些元素按照集合的迭代器返回的顺序排列。

参数:

init(Int64)

public init(capacity: Int64)

功能:构造一个初始容量为指定大小的 ArrayList

参数:

  • capacity: Int64 - 指定的初始容量大小。

异常:

init(Int64, (Int64) -> T)

public init(size: Int64, initElement: (Int64) -> T)

功能:构造具有指定初始元素个数和指定规则函数的 ArrayList。该构造函数根据参数 size 设置 ArrayList 的容量。

参数:

  • size: Int64 - 初始化函数元素个数。
  • initElement: (Int64) ->T - 传入初始化函数。

异常:

func append(T)

public func append(element: T): Unit

功能:将指定的元素附加到此 ArrayList 的末尾。

参数:

  • element: T - 插入的元素,类型为 T。

示例:

使用示例见 ArrayList 的 append/insert 函数

func appendAll(Collection<T>)

public func appendAll(elements: Collection<T>): Unit

功能:将指定集合中的所有元素附加到此 ArrayList 的末尾。

函数会按照迭代器顺序遍历入参中的集合,并且将所有元素插入到此 ArrayList 的尾部。

参数:

  • elements: Collection<T> - 需要插入的元素的集合。

func capacity()

public func capacity(): Int64

功能:返回此 ArrayList 的容量大小。

返回值:

func clear()

public func clear(): Unit

功能:从此 ArrayList 中删除所有元素。

示例:

使用示例见 ArrayList 的 remove/clear/slice 函数

func clone()

public func clone(): ArrayList<T>

功能:返回此ArrayList实例的拷贝(浅拷贝)。

返回值:

func get(Int64)

public func get(index: Int64): ?T

功能:返回此 ArrayList 中指定位置的元素。

参数:

  • index: Int64 - 要返回的元素的索引。

返回值:

  • ?T - 返回指定位置的元素,如果 index 大小小于 0 或者大于等于 ArrayList 中的元素数量,返回 None。

示例:

使用示例见 ArrayList 的 get/set 函数

func getRawArray()

public unsafe func getRawArray(): Array<T>

功能:返回 ArrayList 的原始数据。

注意:

这是一个 unsafe 的接口,使用处需要在 unsafe 上下文中。

原始数据是指 ArrayList 底层实现的数组,其大小大于等于 ArrayList 中的元素数量,且索引大于等于 ArrayList 大小的位置中可能包含有未初始化的元素,对其进行访问可能会产生未定义的行为。

返回值:

func insert(Int64, T)

public func insert(index: Int64, element: T): Unit

功能:在此 ArrayList 中的指定位置插入指定元素。

参数:

  • index: Int64 - 插入元素的目标索引。
  • element: T - 要插入的 T 类型元素。

异常:

示例:

使用示例见 ArrayList 的 append/insert 函数

func insertAll(Int64, Collection<T>)

public func insertAll(index: Int64, elements: Collection<T>): Unit

功能:从指定位置开始,将指定集合中的所有元素插入此 ArrayList

函数会按照迭代器顺序遍历入参中的集合,并且将所有元素插入到指定位置。

参数:

  • index: Int64 - 插入集合的目标索引。
  • elements: Collection<T> - 要插入的 T 类型元素集合。

异常:

示例:

使用示例见 ArrayList 的 remove/clear/slice 函数

func isEmpty()

public func isEmpty(): Bool

功能:判断 ArrayList 是否为空。

返回值:

  • Bool - 如果为空,则返回 true,否则,返回 false

func iterator()

public func iterator(): Iterator<T>

功能:返回此 ArrayList 中元素的迭代器。

返回值:

func prepend(T)

public func prepend(element: T): Unit

功能:在起始位置,将指定元素插入此 ArrayList

参数:

  • element: T - 插入 T 类型元素。

func prependAll(Collection<T>)

public func prependAll(elements: Collection<T>): Unit

功能:从起始位置开始,将指定集合中的所有元素插入此 ArrayList

函数会按照迭代器顺序遍历入参中的集合,并且将所有元素插入到指定位置。

参数:

  • elements: Collection<T> - 要插入的 T 类型元素集合。

func remove(Int64)

public func remove(index: Int64): T

功能:删除此 ArrayList 中指定位置的元素。

参数:

  • index: Int64 - 被删除元素的索引。

返回值:

  • T - 被移除的元素。

异常:

示例:

使用示例见 ArrayList 的 remove/clear/slice 函数

func remove(Range<Int64>)

public func remove(range: Range<Int64>): Unit

功能:删除此 ArrayListRange 范围所包含的所有元素。

注意:

如果参数 range 是使用 Range 构造函数构造的 Range 实例,hasEnd 为 false 时,end 值不生效,且不受构造时传入的 isClosed 的值的影响,数组切片取到原数组最后一个元素。

参数:

  • range: Range<Int64> - 需要被删除的元素的范围。

异常:

func removeIf((T) -> Bool)

public func removeIf(predicate: (T) -> Bool): Unit

功能:删除此 ArrayList 中满足给定 lambda 表达式或函数的所有元素。

参数:

  • predicate: (T) ->Bool - 传递判断删除的条件。

func reserve(Int64)

public func reserve(additional: Int64): Unit

功能:增加此 ArrayList 实例的容量。

ArrayList 扩容 additional 大小,当 additional 小于等于零时,不发生扩容;当 ArrayList 剩余容量大于等于 additional 时,不发生扩容;当 ArrayList 剩余容量小于 additional 时,取(原始容量的1.5倍向下取整)与(additional + 已使用容量)两个值中的最大值进行扩容。

参数:

  • additional: Int64 - 将要扩容的大小。

异常:

  • OverflowException - 当additional + 已使用容量超过Int64.Max时,抛出异常。

func reverse()

public func reverse(): Unit

功能:反转此 ArrayList 中元素的顺序。

func set(Int64, T)

public func set(index: Int64, element: T): Unit

功能:将此 ArrayList 中指定位置的元素替换为指定的元素。

参数:

  • index: Int64 - 要设置的索引值。
  • element: T - T 类型元素。

异常:

示例:

使用示例见 ArrayList 的 get/set 函数

func slice(Range<Int64>)

public func slice(range: Range<Int64>): ArrayList<T>

功能:以传入参数 range 作为索引,返回索引对应的 ArrayList<T>。

注意:

如果参数 range 是使用 Range 构造函数构造的 Range 实例,有如下行为:

  1. start 的值就是构造函数传入的值本身,不受构造时传入的 hasStart 的值的影响。
  2. hasEnd 为 false 时,end 值不生效,且不受构造时传入的 isClosed 的值的影响,该数组切片取到原数组最后一个元素。

参数:

返回值:

异常:

示例:

使用示例见 ArrayList 的 remove/clear/slice 函数

func sortBy(Bool, (T, T) -> Ordering)

public func sortBy(stable!: Bool = false, comparator!: (T, T) -> Ordering): Unit

功能:对数组中的元素进行排序。

通过传入的比较函数,根据其返回值 Ordering 类型的结果,可对数组进行自定义排序comparator: (t1: T, t2: T) -> Ordering,如果 comparator 的返回值为 Ordering.GT,排序后 t1 在 t2后;如果 comparator 的返回值为 Ordering.LT,排序后 t1 在t2 前;如果 comparator 的返回值为 Ordering.EQ,且为稳定排序,那么 t1 在 t2 之前; 如果 comparator 的返回值为 Ordering.EQ,且为不稳定排序,那么 t1,t2 顺序不确定。

参数:

  • stable!: Bool - 是否使用稳定排序。
  • comparator!: (T, T) ->Ordering - (T, T) -> Ordering 类型。

func toArray()

public func toArray(): Array<T>

功能:返回一个数组,其中包含此列表中按正确顺序排列的所有元素。

返回值:

  • Array<T> - T 类型数组。

operator func [](Int64)

public operator func [](index: Int64): T

功能:操作符重载 - get。

参数:

  • index: Int64 - 表示 get 接口的索引。

返回值:

  • T - 索引位置的元素的值。

异常:

operator func [](Int64, T)

public operator func [](index: Int64, value!: T): Unit

功能:操作符重载 - set,通过下标运算符用指定的元素替换此列表中指定位置的元素。

参数:

  • index: Int64 - 要设置的索引值。
  • value!: T - 要设置的 T 类型的值。

异常:

operator func [](Range<Int64>)

public operator func [](range: Range<Int64>): ArrayList<T>

功能:运算符重载 - 切片。

注意:

  • 如果参数 range 是使用 Range 构造函数构造的 Range 实例,有如下行为:

    • start 的值就是构造函数传入的值本身,不受构造时传入的 hasStart 的值的影响。
    • hasEnd 为 false 时,end 值不生效,且不受构造时传入的 isClosed 的值的影响,数组切片取到原数组最后一个元素。
  • 切片操作返回的 ArrayList 为全新的对象,与原 ArrayList 无引用关系。

参数:

返回值:

异常:

extend<T> ArrayList<T> <: Equatable<ArrayList<T>> where T <: Equatable<T>

extend<T> ArrayList<T> <: Equatable<ArrayList<T>> where T <: Equatable<T>

功能:为 ArrayList<T> 类型扩展 Equatable<ArrayList<T>> 接口,支持判等操作。

父类型:

operator func ==(ArrayList<T>)

public operator func ==(that: ArrayList<T>): Bool

功能:判断当前实例与参数指向的 ArrayList 实例是否相等。

两个数组相等指的是两者对应位置的元素分别相等。

参数:

返回值:

  • Bool - 如果相等,则返回 true,否则返回 false。

operator func !=(ArrayList<T>)

public operator func !=(that: ArrayList<T>): Bool

功能:判断当前实例与参数指向的 ArrayList 实例是否不等。

参数:

返回值:

  • Bool - 如果不等,则返回 true,否则返回 false。

func contains(T)

public func contains(element: T): Bool

功能:判断当前数组中是否含有指定元素 element

参数:

  • element: T - 待寻找的元素。

返回值:

  • Bool - 如果数组中包含指定元素,返回 true,否则返回 false。

extend<T> ArrayList<T> <: SortExtension where T <: Comparable<T>

extend<T> ArrayList<T> <: SortExtension where T <: Comparable<T>

功能:为 ArrayList<T> 扩展 SortExtension 接口,支持数组排序。

父类型:

func sort(Bool)

public func sort(stable!: Bool = false): Unit

功能:将当前数组内元素以升序的方式排序。

参数:

  • stable!: Bool - 是否使用稳定排序。

func sortDescending(Bool)

public func sortDescending(stable!: Bool = false): Unit

功能:将当前数组内元素以降序的方式排序。

参数:

  • stable!: Bool - 是否使用稳定排序。

extend<T> ArrayList<T> <: ToString where T <: ToString

extend<T> ArrayList<T> <: ToString where T <: ToString

功能:为 ArrayList<T> 扩展 ToString 接口,支持转字符串操作。

父类型:

func toString()

public func toString(): String

功能:将当前数组转换为字符串。

该字符串包含数组内每个元素的字符串表示,形如:"[elem1, elem2, elem3]"。

返回值:

  • String - 转换得到的字符串。

class ArrayListIterator<T>

public class ArrayListIterator<T> <: Iterator<T> {
    public init(data: ArrayList<T>)
}

功能:此类主要实现 ArrayList 的迭代器功能。

父类型:

init(ArrayList<T>)

public init(data: ArrayList<T>)

功能:创建 ArrayListIterator<T> 实例。

参数:

  • date:传入 ArrayList<T>。

func next()

public func next(): Option<T>

功能:返回迭代中的下一个元素。

返回值:

  • ?T - 迭代器中的下一个元素,用 Option 封装。

异常:

func iterator()

public func iterator(): Iterator<T>

功能:返回迭代器自身。

返回值:

class HashMapIterator<K, V> where K <: Hashable & Equatable<K>

public class HashMapIterator<K, V> <: Iterator<(K, V)> where K <: Hashable & Equatable<K> {
    public init(map: HashMap<K, V>)
}

功能:此类主要实现 HashMap 的迭代器功能。

父类型:

init(HashMap<K, V>)

public init(map: HashMap<K, V>)

功能:创建 HashMapIterator<K, V> 实例。

参数:

func iterator()

public func iterator(): Iterator<(K, V)>

功能:返回迭代器实例本身。

返回值:

  • Iterator <(K, V) > - 迭代器实例本身。

func next()

public func next(): ?(K, V)

功能:返回迭代器中的下一个元素。

返回值:

  • ?(K, V) - 迭代器中的下一个元素,用 Option 封装。

异常:

func remove()

public func remove(): Option<(K, V)>

功能:删除此 HashMap 迭代器的 next 函数返回的元素,此函数只能在 next 函数调用时调用一次。

返回值:

  • Option <(K, V) > - 返回被删除的元素。

异常:

class HashMap<K, V> where K <: Hashable & Equatable<K>

public class HashMap<K, V> <: Map<K, V> where K <: Hashable & Equatable<K> {
    public init()
    public init(elements: Collection<(K, V)>)
    public init(elements: Array<(K, V)>)
    public init(capacity: Int64)
    public init(size: Int64, initElement: (Int64) -> (K, V))
}

功能: Map 接口的哈希表实现。

哈希表是一种常用的数据结构,它可以用来快速地查找、插入和删除数据。哈希表的基本原理是将数据映射到一个数组中,这个数组称为哈希表。每个数据元素都有一个对应的哈希值,这个哈希值可以用来确定该元素在哈希表中的位置。

哈希表的特点是快速的查找、插入和删除操作,时间复杂度通常是O(1)。由于哈希表底层的数组大小是动态的,所以哈希表不能保证元素的顺序不可变。

父类型:

prop size

public prop size: Int64

功能:返回键值对的个数。

类型:Int64

init()

public init()

功能:构造一个具有默认初始容量为16和默认负载因子为空的 HashMap

init(Array<(K, V)>)

public init(elements: Array<(K, V)>)

功能:通过传入的键值对数组构造一个 HashMap

该构造函数根据传入数组的 size 设置 HashMap 的容量。由于HashMap 内部不允许键重复,当 Array 中存在重复的键时,按照迭代器顺序,出现在后面的键值对将会覆盖前面的键值对。

参数:

  • elements: Array<(K, V)> - 初始化该 HashMap 的键值对数组。

init(Collection<(K, V)>)

public init(elements: Collection<(K, V)>)

功能:通过传入的键值对集合构造一个 HashMap

该构造函数根据传入集合 elements 的 size 设置 HashMap 的容量。由于HashMap 内部不允许键重复,当 Array 中存在重复的键时,按照迭代器顺序,出现在后面的键值对将会覆盖前面的键值对。

参数:

init(Int64)

public init(capacity: Int64)

功能:构造一个带有传入容量大小的 HashMap

参数:

  • capacity: Int64 - 初始化容量大小。

异常:

init(Int64, (Int64) -> (K, V))

public init(size: Int64, initElement: (Int64) -> (K, V))

功能:通过传入的元素个数 size 和函数规则来构造 HashMap

构造出的 HashMap 的容量受 size 大小影响。由于HashMap 内部不允许键重复,当函数 initElement 生成相同的键时,后构造的键值对将会覆盖之前出现的键值对。

参数:

  • size: Int64 - 初始化该 HashMap 的函数规则。
  • initElement: (Int64) ->(K, V) - 初始化该 HashMap 的函数规则。

异常:

func capacity()

public func capacity(): Int64

功能:返回 HashMap 的容量。

返回值:

func clear()

public func clear(): Unit

功能:清除所有键值对。

示例:

使用示例见 HashMap 的 putAll/remove/clear 函数

func clone()

public func clone(): HashMap<K, V>

功能:克隆 HashMap

返回值:

func contains(K)

public func contains(key: K): Bool

功能:判断是否包含指定键的映射。

参数:

  • key: K - 传递要判断的 key。

返回值:

  • Bool - 如果存在,则返回 true;否则,返回 false。

示例:

使用示例见 Hashmap 的 get/put/contains 函数

func containsAll(Collection<K>)

public func containsAll(keys: Collection<K>): Bool

功能:判断是否包含指定集合中所有键的映射。

参数:

  • keys: Collection<K> - 键传递待判断的 keys。

返回值:

  • Bool - 如果都包含,则返回 true;否则,返回 false。

func entryView(K)

public func entryView(key: K): EntryView<K, V>

功能:如果不包含特定键,返回一个空的引用视图。如果包含特定键,则返回该键对应的元素的引用视图。

EntryView 的使用方式见 EntryView

参数:

  • key: K - 要添加的键值对的键。

返回值:

func get(K)

public func get(key: K): Option<V>

功能:返回指定键映射到的值,如果 HashMap 不包含指定键的映射,则返回 Option<V>.None。

参数:

  • key: K - 传入的键。

返回值:

示例:

使用示例见 Hashmap 的 get/put/contains 函数

func isEmpty()

public func isEmpty(): Bool

功能:判断 HashMap 是否为空,如果是,则返回 true;否则,返回 false。

返回值:

func iterator()

public func iterator(): HashMapIterator<K, V>

功能:返回 Hashmap 的迭代器。

返回值:

func keys()

public func keys(): EquatableCollection<K>

功能:返回 HashMap 中所有的 key,并将所有 key 存储在一个 Keys 容器中。

返回值:

func put(K, V)

public func put(key: K, value: V): Option<V>

功能:将键值对放入 HashMap 中。

对于 HashMap 中已有的键,该键的值将被新值替换,并且返回旧的值。

参数:

  • key: K - 要放置的键。
  • value: V - 要分配的值。

返回值:

  • Option<V> - 如果赋值之前 key 存在,旧的 value 用 Option 封装;否则,返回 Option<V>.None。

示例:

使用示例见 Hashmap 的 get/put/contains 函数

func putAll(Collection<(K, V)>)

public func putAll(elements: Collection<(K, V)>): Unit

功能:按照 elements 的迭代器顺序将新的键值对集合放入 HashMap 中。

对于 HashMap 中已有的键,该键的值将被新值替换。

参数:

示例:

使用示例见 HashMap 的 putAll/remove/clear 函数

func putIfAbsent(K, V)

public func putIfAbsent(key: K, value: V): Bool

功能:当此 HashMap 中不存在键 key 时,向 HashMap 中插入键值对(key, value)。

参数:

  • key: K - 要放置的键。
  • value: V - 要分配的值。

返回值:

  • Bool - 如果赋值之前 key 存在,则返回 false ,否则返回 true

func remove(K)

public func remove(key: K): Option<V>

功能:从此 HashMap 中删除指定键的映射(如果存在)。

参数:

  • key: K - 传入要删除的 key。

返回值:

示例:

使用示例见 HashMap 的 putAll/remove/clear 函数

func removeAll(Collection<K>)

public func removeAll(keys: Collection<K>): Unit

功能:从此 HashMap 中删除指定集合中键的映射(如果存在)。

参数:

  • keys: Collection<K> - 传入要删除的键的集合。

func removeIf((K, V) -> Bool)

public func removeIf(predicate: (K, V) -> Bool): Unit

功能:传入 lambda 表达式,如果满足条件,则删除对应的键值对。

该函数会遍历整个HashMap,所以满足 predicate(K, V) == true 的键值对都会被删除。

参数:

  • predicate: (K, V) ->Bool - 传递一个 lambda 表达式进行判断。

异常:

func reserve(Int64)

public func reserve(additional: Int64): Unit

功能:扩容当前的HashMap

HashMap 扩容 additional 大小当 additional 小于等于零时,不发生扩容;当 HashMap 剩余容量大于等于 additional 时,不发生扩容;当 HashMap 剩余容量小于 additional 时,取(原始容量的1.5倍向下取整)与(additional + 已使用容量)中的最大值进行扩容。

参数:

  • additional: Int64 - 将要扩容的大小。

异常:

  • OverflowException - 当additional + 已使用容量超过Int64.Max时,抛出异常。

func toArray()

public func toArray(): Array<(K, V)>

功能:构造一个包含 HashMap 内键值对的数组,并返回。

返回值:

  • Array <(K, V) > - 包含容器内所有键值对的数组。

func values()

public func values(): Collection<V>

功能:返回 HashMap 中包含的值,并将所有的 value 存储在一个 Values 容器中。

返回值:

operator func [](K, V)

public operator func [](key: K, value!: V): Unit

功能:运算符重载 put 方法,如果键存在,新 value 覆盖旧 value,如果键不存在,添加此键值对。

参数:

  • key: K - 传递值进行判断。
  • value!: V - 传递要设置的值。

operator func [](K)

public operator func [](key: K): V

功能:运算符重载 get 方法,如果键存在,返回键对应的值。

参数:

  • key: K - 传递值进行判断。

返回值:

  • V - 与键对应的值。

异常:

extend<K, V> HashMap<K, V> <: Equatable<HashMap<K, V>> where V <: Equatable<V>

extend<K, V> HashMap<K, V> <: Equatable<HashMap<K, V>> where V <: Equatable<V>

功能:为 HashMap<K, V> 类型扩展 Equatable<HashMap<K, V>> 接口,支持判等操作。

父类型:

operator func ==(HashMap<K, V>)

public operator func ==(right: HashMap<K, V>): Bool

功能:判断当前实例与参数指向的 HashMap<K, V> 实例是否相等。

两个 HashMap<K, V> 相等指的是其中包含的键值对完全相等。

参数:

  • right: HashMap<K, V> - 被比较的对象。

返回值:

  • Bool - 如果相等,则返回 true,否则返回 false。

operator func !=(HashMap<K, V>)

public operator func !=(right: HashMap<K, V>): Bool

功能:判断当前实例与参数指向的 HashMap<K, V> 实例是否不等。

参数:

  • right: HashMap<K, V> - 被比较的对象。

返回值:

  • Bool - 如果不等,则返回 true,否则返回 false。

extend<K, V> HashMap<K, V> <: ToString where V <: ToString, K <: ToString

extend<K, V> HashMap<K, V> <: ToString where V <: ToString, K <: ToString

功能:为 HashMap<K, V> 扩展 ToString 接口,支持转字符串操作。

父类型:

func toString()

public func toString(): String

功能:将当前 HashMap<K, V> 实例转换为字符串。

该字符串包含 HashMap<K, V> 内每个键值对的字符串表示,形如:"[(k1, v1), (k2, v2), (k3, v3)]"。

返回值:

  • String - 转换得到的字符串。

class HashSet<T> where T <: Hashable & Equatable<T>

public class HashSet<T> <: Set<T> where T <: Hashable & Equatable<T> {
    public init()
    public init(elements: Collection<T>)
    public init(elements: Array<T>)
    public init(capacity: Int64)
    public init(size: Int64, initElement: (Int64) -> T)
}

功能:基于 HashMap 实现的 Set 接口的实例。

HashSet中的元素是无序的,不允许有重复元素。当我们向HashSet中添加元素时,HashSet会根据元素的哈希值来确定该元素在哈希表中的位置。

提示:

HashSet 是基于 HashMap 实现的,因此 HashSet 的容量、内存布局、时间性能等都和 HashMap 相同。

父类型:

prop size

public prop size: Int64

功能:返回此 HashSet 的元素个数。

类型:Int64

init(Int64, Int64 -> T)

public init(size: Int64, initElement: (Int64) -> T)

功能:通过传入的函数元素个数 size 和函数规则来构造 HashSet。构造出的 HashSet 的容量受 size 大小影响。

参数:

  • size: Int64 - 初始化函数中元素的个数。
  • initElement: (Int64) ->T - 初始化函数规则。

异常:

init()

public init()

功能:构造一个空的 HashSet ,初始容量为 16 。

init(Array<T>)

public init(elements: Array<T>)

功能:使用传入的数组构造 HashSet。该构造函数根据传入数组 elements 的 size 设置 HashSet 的容量。

参数:

init(Collection<T>)

public init(elements: Collection<T>)

功能:使用传入的集合构造 HashSet。该构造函数根据传入集合 elements 的 size 设置 HashSet 的容量。

参数:

init(Int64)

public init(capacity: Int64)

功能:使用传入的容量构造一个 HashSet

参数:

  • capacity: Int64 - 初始化容量大小。

异常:

func capacity()

public func capacity(): Int64

功能:返回此 HashSet 的内部数组容量大小。

注意:

容量大小不一定等于 HashSet 的 size。

返回值:

func clear()

public func clear(): Unit

功能:从此 HashSet 中移除所有元素。

func clone()

public func clone(): HashSet<T>

功能:克隆 HashSet

返回值:

func contains(T)

public func contains(element: T): Bool

功能:判断 HashSet 是否包含指定元素。

参数:

  • element: T - 指定的元素。

返回值:

  • Bool - 如果包含指定元素,则返回 true;否则,返回 false。

func containsAll(Collection<T>)

public func containsAll(elements: Collection<T>): Bool

功能:判断 HashSet 是否包含指定 Collection 中的所有元素。

参数:

  • elements: Collection<T> - 指定的元素集合。

返回值:

  • Bool - 如果此 HashSet 包含 Collection 中的所有元素,则返回 true;否则,返回 false。

func isEmpty()

public func isEmpty(): Bool

功能:判断 HashSet 是否为空。

返回值:

  • Bool - 如果为空,则返回 true;否则,返回 false。

func iterator()

public func iterator(): Iterator<T>

功能:返回此 HashSet 的迭代器。

返回值:

示例:

使用示例见 HashSet 的 put/iterator/remove 函数

func put(T)

public func put(element: T): Bool

功能:将指定的元素添加到 HashSet 中, 若添加的元素在 HashSet 中存在, 则添加失败。

参数:

  • element: T - 指定的元素。

返回值:

  • Bool - 如果添加成功,则返回 true;否则,返回 false。

示例:

使用示例见 HashSet 的 put/iterator/remove 函数

func putAll(Collection<T>)

public func putAll(elements: Collection<T>): Unit

功能:添加 Collection 中的所有元素至此 HashSet 中,如果元素存在,则不添加。

参数:

  • elements: Collection<T> - 需要被添加的元素的集合。

func remove(T)

public func remove(element: T): Bool

功能:如果指定元素存在于此 HashSet 中,则将其移除。

参数:

  • element: T - 需要被移除的元素。

返回值:

  • Bool - true,表示移除成功;false,表示移除失败。

示例:

使用示例见 HashSet 的 put/iterator/remove 函数

func removeAll(Collection<T>)

public func removeAll(elements: Collection<T>): Unit

功能:移除此 HashSet 中那些也包含在指定 Collection 中的所有元素。

参数:

func removeIf((T) -> Bool)

public func removeIf(predicate: (T) -> Bool): Unit

功能:传入 lambda 表达式,如果满足 true 条件,则删除对应的元素。

参数:

  • predicate: (T) ->Bool - 是否删除元素的判断条件。

异常:

func reserve(Int64)

public func reserve(additional: Int64): Unit

功能:将 HashSet 扩容 additional 大小,当 additional 小于等于零时,不发生扩容;当 HashSet 剩余容量大于等于 additional 时,不发生扩容;当 HashSet 剩余容量小于 additional 时,取(原始容量的1.5倍向下取整)与(additional + 已使用容量)中的最大值进行扩容。

参数:

  • additional: Int64 - 将要扩容的大小。

异常:

  • OverflowException - 当additional + 已使用容量超过Int64.Max时,抛出异常。

func retainAll(Set<T>)

public func retainAll(elements: Set<T>): Unit

功能:从此 HashSet 中保留 Set 中的元素。

参数:

  • elements: Set<T> - 需要保留的 Set

func subsetOf(Set<T>)

public func subsetOf(other: Set<T>): Bool

功能:检查该集合是否为其他 Set 的子集。

参数:

  • other: Set<T> - 传入集合,此函数将判断当前集合是否为 other 的子集。

返回值:

  • Bool - 如果该 Set 是指定 Set 的子集,则返回 true;否则返回 false。

func toArray()

public func toArray(): Array<T>

功能:返回一个包含容器内所有元素的数组。

返回值:

  • Array<T> - T 类型数组。

extend<T> HashSet<T> <: Equatable<HashSet<T>>

extend<T> HashSet<T> <: Equatable<HashSet<T>>

功能:为 HashSet<T> 类型扩展 Equatable<HashSet<T>> 接口,支持判等操作。

父类型:

operator func ==(HashSet<T>)

public operator func ==(that: HashSet<T>): Bool

功能:判断当前实例与参数指向的 HashSet<T> 实例是否相等。

两个 HashSet<T> 相等指的是其中包含的元素完全相等。

参数:

  • that: HashSet<T> - 被比较的对象。

返回值:

  • Bool - 如果相等,则返回 true,否则返回 false。

operator func !=(HashSet<T>)

public operator func !=(that: HashSet<T>): Bool

功能:判断当前实例与参数指向的 HashSet<T> 实例是否不等。

参数:

  • that: HashSet<T> - 被比较的对象。

返回值:

  • Bool - 如果不等,则返回 true,否则返回 false。

extend<T> HashSet<T> <: ToString where T <: ToString

extend<T> HashSet<T> <: ToString where T <: ToString

功能:为 HashSet<T> 扩展 ToString 接口,支持转字符串操作。

父类型:

func toString()

public func toString(): String

功能:将当前 HashSet<T> 实例转换为字符串。

该字符串包含 HashSet<T> 内每个元素的字符串表示,形如:"[elem1, elem2, elem3]"。

返回值:

  • String - 转换得到的字符串。

class LinkedListNode<T>

public class LinkedListNode<T>

功能:LinkedListNodeLinkedList 上的节点。

可以通过 LinkedListNodeLinkedList 进行前向后向遍历操作,也可以访问和修改元素的值。

LinkedListNode 只能通过对应 LinkedList 的 'nodeAt'、'firstNode'、'lastNode' 获得,当 LinkedList 删除掉对应的节点时,会造成一个悬空的节点,对悬空的节点进行任何操作都会抛 'IllegalStateException' 异常。

prop next

public prop next: Option<LinkedListNode<T>>

功能:获取当前节点的下一个节点,如果没有则返回 None。

类型:Option<LinkedListNode<T>>

异常:

prop prev

public prop prev: Option<LinkedListNode<T>>

功能:获取当前节点的前一个节点,如果没有则返回 None。

类型:Option<LinkedListNode<T>>

异常:

prop value

public mut prop value: T

功能:获取或者修改元素的值。

类型:T

异常:

func backward()

public func backward(): Iterator<T>

功能:获取一个从当前节点开始,到所对应链表的尾部节点的所有元素的迭代器。

返回值:

  • Iterator<T> - 对应元素的迭代器。

异常:

func forward()

public func forward(): Iterator<T>

功能:获取一个从当前节点开始,到所对应链表的头部节点的所有元素的迭代器。

返回值:

  • Iterator<T> - 对应元素的迭代器。

异常:

class LinkedList<T>

public class LinkedList<T> <: Collection<T> {
    public init()
    public init(elements: Collection<T>)
    public init(elements: Array<T>)
    public init(size: Int64, initElement: (Int64)-> T)
}

功能:实现双向链表的数据结构。

双向链表是一种常见的数据结构,它由一系列节点组成,每个节点都包含两个指针,一个指向前一个节点,另一个指向后一个节点。这种结构允许在任何一个节点上进行双向遍历,即可以从头节点开始向后遍历,也可以从尾节点开始向前遍历。

LinkedList 不支持并发操作,并且对集合中元素的修改不会使迭代器失效,只有在添加和删除元素的时候会使迭代器失效。

父类型:

prop first

public prop first: ?T

功能:链表中第一个元素的值,如果是空链表则返回 None。

类型:?T

prop last

public prop last: ?T

功能:链表中最后一个元素的值,如果是空链表则返回 None。

类型:?T

prop size

public prop size: Int64

功能:链表中的元素数量。

类型:Int64

init

public init()

功能:构造一个空的链表。

init(Array<T>)

public init(elements: Array<T>)

功能:按照数组的遍历顺序构造一个包含指定集合元素的 LinkedList 实例。

参数:

  • elements: Array<T> - 将要放入此链表中的元素数组。

init(Collection<T>)

public init(elements: Collection<T>)

功能:按照集合迭代器返回元素的顺序构造一个包含指定集合元素的链表。

参数:

  • elements: Collection<T> - 将要放入此链表中的元素集合。

init(Int64, (Int64)-> T)

public init(size: Int64, initElement: (Int64)-> T)

功能:创建一个包含 size 个元素,且第 n 个元素满足 (Int64)-> T 条件的链表。

参数:

  • size: Int64 - 要创建的链表元素数量。
  • initElement: (Int64) ->T - 元素的初始化参数。

func append(T)

public func append(element: T): LinkedListNode<T>

功能:在链表的尾部位置添加一个元素,并且返回该元素的节点。

参数:

  • element: T - 要添加到链表中的元素。

返回值:

func clear()

public func clear(): Unit

功能:删除链表中的所有元素。

func firstNode()

public func firstNode(): Option<LinkedListNode<T>>

功能:获取链表中的第一个元素的节点。

返回值:

  • Option < LinkedListNode<T>> - 第一个元素的节点,如果链表为空链表则返回 None。

func insertAfter(LinkedListNode<T>,T)

public func insertAfter(node: LinkedListNode<T>, element: T): LinkedListNode<T>

功能:在链表中指定节点的后面插入一个元素,并且返回该元素的节点。

参数:

  • node: LinkedListNode<T> - 指定的节点。
  • element: T - 要添加到链表中的元素。

返回值:

异常:

func insertBefore(LinkedListNode<T>,T)

public func insertBefore(node: LinkedListNode<T>, element: T): LinkedListNode<T>

功能:在链表中指定节点的前面插入一个元素,并且返回该元素的节点。

参数:

  • node: LinkedListNode<T> - 指定的节点。
  • element: T - 要添加到链表中的元素。

返回值:

异常:

func isEmpty()

public func isEmpty(): Bool

功能:返回此链表是否为空链表的判断。

返回值:

  • Bool - 如果此链表中不包含任何元素,返回 true。

func iterator()

public func iterator(): Iterator<T>

功能:返回当前集合中元素的迭代器,其顺序是从链表的第一个节点到链表的最后一个节点。

返回值:

  • Iterator<T> - 当前集合中元素的迭代器。

func lastNode()

public func lastNode(): Option<LinkedListNode<T>>

功能:获取链表中的最后一个元素的节点。

返回值:

  • Option < LinkedListNode<T>> - 最后一个元素的节点,如果链表为空链表则返回 None。

func nodeAt(Int64)

public func nodeAt(index: Int64): Option<LinkedListNode<T>>

功能:获取链表中的第 index 个元素的节点,编号从 0 开始。

该函数的时间复杂度为 O(n)。

参数:

  • index: Int64 - 指定获取第 index 个元素的节点。

返回值:

func popFirst()

public func popFirst() : ?T

功能:移除链表的第一个元素,并返回该元素的值。

返回值:

  • ?T - 被删除的元素的值,若链表为空则返回 None。

func popLast()

public func popLast() : ?T

功能:移除链表的最后一个元素,并返回该元素的值。

返回值:

  • ?T - 被删除的元素的值,若链表为空则返回 None。

func prepend(T)

public func prepend(element: T): LinkedListNode<T>

功能:在链表的头部位置插入一个元素,并且返回该元素的节点。

参数:

  • element: T - 要添加到链表中的元素。

返回值:

func remove(LinkedListNode<T>)

public func remove(node: LinkedListNode<T>): T

功能:删除链表中指定节点。

参数:

返回值:

  • T - 被删除的节点的值。

异常:

func removeIf((T)-> Bool)

public func removeIf(predicate: (T)-> Bool): Unit

功能:删除此链表中满足给定 lambda 表达式或函数的所有元素。

参数:

  • predicate: (T) ->Bool - 对于要删除的元素,返回值为 true。

func reverse()

public func reverse(): Unit

功能:反转此链表中的元素顺序。

func splitOff(LinkedListNode<T>)

public func splitOff(node: LinkedListNode<T>): LinkedList<T>

功能:从指定的节点 node 开始,将链表分割为两个链表,如果分割成功,node 不在当前的链表内,而是作为首个节点存在于新的链表内部。

参数:

返回值:

  • LinkedList<T> - 原链表分割后新产生的链表。

异常:

func toArray()

public func toArray(): Array<T>

功能:返回一个数组,数组包含该链表中的所有元素,并且顺序与链表的顺序相同。

返回值:

  • Array<T> - T 类型数组。

extend<T> LinkedList<T> <: Equatable<LinkedList<T>> where T <: Equatable<T>

extend<T> LinkedList<T> <: Equatable<LinkedList<T>> where T <: Equatable<T>

功能:为 LinkedList<T> 类型扩展 Equatable<LinkedList<T>> 接口,支持判等操作。

父类型:

operator func ==(LinkedList<T>)

public operator func ==(right: LinkedList<T>): Bool

功能:判断当前实例与参数指向的 LinkedList<T> 实例是否相等。

两个 LinkedList<T> 相等指的是其中包含的元素完全相等。

参数:

  • right: HashSet<T> - 被比较的对象。

返回值:

  • Bool - 如果相等,则返回 true,否则返回 false。

operator func !=(LinkedList<T>)

public operator func !=(right: LinkedList<T>): Bool

功能:判断当前实例与参数指向的 LinkedList<T> 实例是否不等。

参数:

返回值:

  • Bool - 如果不等,则返回 true,否则返回 false。

extend<T> LinkedList<T> <: ToString where T <: ToString

extend<T> LinkedList<T> <: ToString where T <: ToString

功能:为 LinkedList<T> 扩展 ToString 接口,支持转字符串操作。

父类型:

func toString()

public func toString(): String

功能:将当前 LinkedList<T> 实例转换为字符串。

该字符串包含 LinkedList<T> 内每个元素的字符串表示,形如:"[elem1, elem2, elem3]"。

返回值:

  • String - 转换得到的字符串。

class TreeMap<K, V> where K <: Comparable<K>

public class TreeMap<K, V> <: Map<K, V> where K <: Comparable<K> {
    public init()
    public init(elements: Collection<(K, V)>)
    public init(elements: Array<(K,V)>)
    public init(size: Int64, initElement: (Int64) -> (K, V))
}

功能:基于平衡二叉搜索树实现的 Map 接口实例。

这个类的主要目的是提供一个有序的 key-value 存储结构,它可以快速地插入、删除、查找元素。

TreeMap 可以用于任何需要有序键值对存储的场景,例如数据库、缓存、查找表等。

父类型:

prop size

public prop size: Int64

功能:返回键值的个数。

类型:Int64

init()

public init()

功能:构造一个空的 TreeMap

init(Array<(K,V)>)

public init(elements: Array<(K,V)>)

功能:通过传入的键值对数组构造一个 TreeMap

按照 elements 的先后顺序将元素插入到 TreeMap 内,由于 TreeMap 中不允许出现相同的键,如果 elements 中有相同的键时,后出现的键值对将会覆盖先出现的键值对。

参数:

  • elements: Array<(K, V)> - 初始化该 TreeMap 的键值对数组。

init(Collection<(K, V)>)

public init(elements: Collection<(K, V)>)

功能:通过传入的键值对集合构造一个 TreeMap

按照 elements 的迭代器顺序将元素插入到 TreeMap 内,由于 TreeMap 中不允许出现相同的键,如果 elements 中有相同的键时,后出现(迭代器顺序)的键值对将会覆盖先出现的键值对。

参数:

init(Int64, (Int64) -> (K, V))

public init(size: Int64, initElement: (Int64) -> (K, V))

功能:通过传入的元素个数 size 和函数规则来构造 TreeMap

参数:

  • size: Int64 - 传入的元素个数。
  • initElement: (Int64) ->(K, V) - 初始化该 TreeMap 的函数规则。

异常:

func clear()

public func clear(): Unit

功能:清除所有键值对。

func clone()

public func clone(): TreeMap<K, V>

功能:克隆 TreeMap

返回值:

func contains(K)

public func contains(key: K): Bool

功能:判断是否包含指定键的映射。

参数:

  • key: K - 传递要判断的 key。

返回值:

  • Bool - 如果存在,则返回 true;否则,返回 false。

func containsAll(Collection<K>)

public func containsAll(keys: Collection<K>): Bool

功能:判断是否包含指定集合键的映射。

参数:

返回值:

  • Bool - 如果存在,则返回 true;否则,返回 false。

func findLower(K, Bool)

public func findLower(bound: K, inclusive!: Bool = false): Option<TreeMapNode<K, V>>

功能:返回比传入的键小的最大元素。

参数:

  • bound: K - 传入的键。
  • inclusive!: Bool - 是否包含传入的键本身,默认为 false ,即不包含。

返回值:

func findUpper(K, Bool)

public func findUpper(bound: K, inclusive!: Bool = false): Option<TreeMapNode<K, V>>

功能:返回比传入的键大的最小元素。

参数:

  • bound: K - 传入的键。
  • inclusive!: Bool - 是否包含传入的键本身,默认为 false ,即不包含。

返回值:

func firstEntry()

public func firstEntry(): Option<(K, V)>

功能:获取 TreeMap 的第一个元素。

返回值:

  • Option <(K, V) > - 如果存在第一个元素,用 Option 封装该元素并返回;否则返回 Option<(K, V)>.None。

func get(K)

public func get(key: K): Option<V>

功能:返回指定键映射的值。

参数:

  • key: K - 指定的键。

返回值:

  • Option<V> - 如果存在这样一个值,用 Option 封装该值并返回;否则,返回 Option<V>.None。

func isEmpty()

public func isEmpty(): Bool

功能:判断 TreeMap 是否为空。

返回值:

  • Bool - 如果为空,返回 true,否则返回 false。

func iterator()

public func iterator(): Iterator<(K, V)>

功能:返回 TreeMap 的迭代器,迭代器按 Key 值从小到大的顺序迭代。

返回值:

func keys()

public func keys(): EquatableCollection<K>

功能:返回 TreeMap 中所有的 key,并将所有 key 存储在一个容器中。

返回值:

func lastEntry()

public func lastEntry(): Option<(K, V)>

功能:获取 TreeMap 的最后一个元素。

返回值:

  • Option <(K, V) > - 如果存在最后一个元素,用 Option 封装该元素并返回;否则返回 Option<(K, V)>.None。

func popFirstEntry()

public func popFirstEntry(): Option<(K, V)>

功能:删除 TreeMap 的第一个元素。

返回值:

  • Option <(K, V) > - 如果存在第一个元素,那么删除该元素,用 Option 封装该元素并返回;否则返回 Option<(K, V)>.None。

func popLastEntry()

public func popLastEntry(): Option<(K, V)>

功能:删除 TreeMap 的最后一个元素。

返回值:

  • Option <(K, V) > - 如果存在最后一个元素,那么删除该元素,用 Option 封装该元素并返回;否则返回 Option<(K, V)>.None。

func put(K, V)

public func put(key: K, value: V): Option<V>

功能:将新的键值对放入 TreeMap 中。对于 TreeMap 中已有的键,该键的值将被新值替换。

参数:

  • key: K - 要放置的键。
  • value: V - 要分配的值。

返回值:

  • Option<V> - 如果赋值之前 key 存在,旧的 value 用 Option 封装并返回;否则,返回 Option<V>.None。

func putAll(Collection<K, V>)

public func putAll(elements: Collection<(K, V)>): Unit

功能:将新的键值对集合放入 TreeMap 中。对于 TreeMap 中已有的键,该键的值将被新值替换。

参数:

func remove(K)

public func remove(key: K): Option<V>

功能:从此映射中删除指定键的映射(如果存在)。

参数:

  • key: K - 传入要删除的 key。

返回值:

  • Option<V> - 被移除映射的值用 Option 封装,如果 TreeMap 中不存在指定的键,返回 None。

func removeAll(Collection<K>)

public func removeAll(keys: Collection<K>): Unit

功能:从此映射中删除指定集合的映射(如果存在)。

参数:

  • keys: Collection<K> - 传入要删除的键的集合。

func removeIf((K, V) -> Bool)

public func removeIf(predicate: (K, V) -> Bool): Unit

功能:传入 lambda 表达式,如果满足条件,则删除对应的键值。

参数:

  • predicate: (K, V) ->Bool - 传递一个 lambda 表达式进行判断。

func values()

public func values(): Collection<V>

功能:返回 TreeMap 中包含的值,并将所有的 value 存储在一个容器中。

返回值:

operator func [](K, V)

public operator func [](key: K, value!: V): Unit

功能:运算符重载集合,如果键存在,新 value 覆盖旧 value,如果键不存在,添加此键值对。

参数:

  • key: K - 传递值进行判断。
  • value!: V - 传递要设置的值。

operator func [](K)

public operator func [](key: K): V

功能:运算符重载集合,如果键存在,返回键对应的值。

参数:

  • key: K - 传递值进行判断。

返回值:

  • V - 与键对应的值。

异常:

extend<K, V> TreeMap<K, V> <: Equatable<TreeMap<K, V>> where V <: Equatable<V>

extend<K, V> TreeMap<K, V> <: Equatable<TreeMap<K, V>> where V <: Equatable<V>

功能:为 TreeMap<K, V> 类型扩展 Equatable<TreeMap<K, V>> 接口,支持判等操作。

父类型:

operator func ==(TreeMap<K, V>)

public operator func ==(right: TreeMap<K, V>): Bool

功能:判断当前实例与参数指向的 TreeMap<K, V> 实例是否相等。

两个 TreeMap<K, V> 相等指的是其中包含的键值对完全相等。

参数:

  • right: TreeMap<K, V> - 被比较的对象。

返回值:

  • Bool - 如果相等,则返回 true,否则返回 false。

operator func !=(TreeMap<K, V>)

public operator func !=(right: TreeMap<K, V>): Bool

功能:判断当前实例与参数指向的 TreeMap<K, V> 实例是否不等。

参数:

  • right: TreeMap<K, V> - 被比较的对象。

返回值:

  • Bool - 如果不等,则返回 true,否则返回 false。

extend<K, V> TreeMap<K, V> <: ToString where V <: ToString, K <: ToString & Comparable<K>

extend<K, V> TreeMap<K, V> <: ToString where V <: ToString, K <: ToString & Comparable<K>

功能:为 TreeMap<K, V> 扩展 ToString 接口,支持转字符串操作。

父类型:

func toString()

public func toString(): String

功能:将当前 TreeMap<K, V> 实例转换为字符串。

该字符串包含 TreeMap<K, V> 内每个键值对的字符串表示,形如:"[(k1, v1), (k2, v2), (k3, v3)]"。

返回值:

  • String - 转换得到的字符串。

结构体

struct EntryView<K, V> where K <: Hashable & Equatable<K>

public struct EntryView<K, V>  where K <: Hashable & Equatable<K>

功能:HashMap 中某一个 Key 的视图。

通过对视图的修改,可以实现快速的获取或者修改 HashMap 中与 Key 对应的 Value 的值,在使用视图的过程中,如果集合修改、增加、删除了某些元素,视图会无效并抛出 ConcurrentModificationException

该结构体的实例只能通过对应 HashMapfunc entryView(K) 方法获得。

func getKey()

public func getKey(): K

功能:获取视图中的键,时间复杂度为 O(1)。

返回值:

  • K - 视图的键。

异常:

func getValue()

public func getValue(): ?V

功能:获取视图中的值,时间复杂度为 O(1)。

如果视图为空,返回 None;否则,返回键对应的值。

返回值:

  • ?V - 视图的值。

异常:

func isAbsent()

public func isAbsent(): Bool

功能:判断视图是否为空。

如果视图为空,说明对应的 HashMap 中不存在 Key 值和此视图的 Key值相同的 (Key, Value) 组合。

返回值:

  • Bool - 如果视图为空,则返回 true;否则,返回 false。

func setValue(V)

public mut func setValue(v: V): V

功能:设置视图中的值,时间复杂度为 O(1)。

如果视图为空,则插入指定的键值对,并返回插入的值;否则,返回设置前的值。

参数:

  • v: V - 指定的值。

返回值:

  • V - 视图的值或者新插入的值。

异常:

struct TreeMapNode<K, V> where K <: Comparable<K>

public struct TreeMapNode<K, V> where K <: Comparable<K>

功能:TreeMap 的节点结构。

注意:

在使用 TreeMapNode 实例进行节点操作时,如果此时对对应的 TreeMap 进行插入或删除操作,将会导致 TreeMapNode 失效,对失效的 TreeMapNode 进行操作将会抛出异常 ConcurrentModificationException

prop key

public prop key: K

功能:获取当前节点的键。

类型:K

异常:

prop value

public mut prop value: V

功能:获取或设置当前节点的值。

类型:V

异常:

func backward(K, Bool)

public func backward(bound: K, inclusive!:Bool = true): Iterator<(K, V)>

功能:从当前节点开始,到 bound 结束,生成一个正序的迭代器。

参数:

  • bound: K - 传入的键。
  • inclusive!: Bool - 是否包含传入的键本身,默认为 true ,即包含传入的键本身。

返回值:

  • Iterator <(K, V) > - 返回从当前节点开始,到 bound 结束的一个正序的迭代器。

异常:

func forward(K, Bool)

public func forward(bound: K, inclusive!:Bool = true): Iterator<(K, V)>

功能:从当前节点开始,到 bound 结束,生成一个逆序的迭代器。

参数:

  • bound: K - 传入的键。
  • inclusive!: Bool - 是否包含传入的键本身,默认为 true ,即包含传入的键本身。

返回值:

  • Iterator <(K, V) > - 返回从当前节点开始,到 bound 结束的一个逆序的迭代器。

异常:

func next()

public func next(): Option<TreeMapNode<K, V>>

功能:访问后继节点。

返回值:

异常:

func prev()

public func prev(): Option<TreeMapNode<K, V>>

功能:访问前继节点。

返回值:

异常:

异常

class ConcurrentModificationException

public class ConcurrentModificationException <: Exception {
    public init()
    public init(message: String)
}

功能:并发修改异常类。当函数检测到不同步的并发修改,抛出异常。

由于 collection 包提供的容器类都不支持并发修改,因此在执行某些操作时,会抛出 ConcurrentModificationException

典型的抛异常场景有:

  • 使用 for-in 遍历一个容器过程中对容器进行修改时(HashMapIteratorremove() 方法除外)。
  • 在使用声明周期较短的类型,如 EntryViewTreeMapNode 时,如果其所在的容器内容被修改,也会抛出异常。

父类型:

init()

public init()

功能:构造一个不带异常信息的实例。

init(String)

public init(message: String)

功能:根据异常信息构造异常实例。

参数:

  • message: String - 异常信息。

ArrayList 的 append/insert 函数

ArrayList 中添加元素的方法如下:

import std.collection.*

main() {
    var list: ArrayList<Int64> = ArrayList<Int64>(10) //创建一个容量为 10 的 ArrayList
    var arr: Array<Int64> = [1, 2, 3]
    list.appendAll(arr) // list: [1, 2, 3]
    list.set(1, 120) // list: [1, 120, 3]
    var b = list.get(2)
    print("b=${b.getOrThrow()},")
    list.insert(1, 12) // list: [1, 12, 120, 3]
    var c = list.get(2)
    print("c=${c.getOrThrow()},")
    var arr1: Array<Int64> = [1,2,3]
    list.insertAll(1, arr1) // list: [1, 1, 2, 3, 12, 120, 3]
    var d = list.get(2)
    print("d=${d.getOrThrow()}")
    return 0
}

运行结果如下:

b=3,c=120,d=2

ArrayList 的 get/set 函数

此用例展示了如何使用 get 方法获取 ArrayList 中对应索引的值,以及使用 set 方法修改值。

代码如下:

import std.collection.*
main() {
    var list = ArrayList<Int64>([97, 100]) // list: [97, 100]
    list.set(1, 120) // list: [97, 120]
    var b = list.get(1)
    print("b=${b.getOrThrow()}")
    return 0
}

运行结果如下:

b=120

ArrayList 的 remove/clear/slice 函数

此用例展示了 ArrayList 的 remove/clear/slice 函数的使用方法。

代码如下:

import std.collection.*
main() {
    var list: ArrayList<Int64> = ArrayList<Int64>(97, 100, 99) // Function call syntactic sugar of variable-length
    list.remove(1) // list: [97, 99]
    var b = list.get(1)
    print("b=${b.getOrThrow()},")
    list.clear()
    list.append(11) // list: [97, 99, 11]
    var arr: Array<Int64> = [1, 2, 3]
    list.insertAll(0, arr) // list: [1, 2, 3, 97, 99]
    var g = list.get(0)
    print("g=${g.getOrThrow()},")
    let r: Range<Int64> = 1..=2 : 1
    var sublist: ArrayList<Int64> = list.slice(r) // sublist: [2, 3]
    var m = sublist.get(0)
    print("m=${m.getOrThrow()}")
    return 0
}

运行结果如下:

b=99,g=1,m=2

HashMap 的 get/put/contains 函数

此用例展示了 HashMap 的基本使用方法。

代码如下:

import std.collection.*
main() {
    var map: HashMap<String, Int64> = HashMap<String, Int64>()
    map.put("a", 99) // map : [("a", 99)]
    map.put("b", 100) // map : [("a", 99), ("b", 100)]
    var a = map.get("a")
    var bool = map.contains("a")
    print("a=${a.getOrThrow()} ")
    print("bool=${bool.toString()}")
    return 0
}

运行结果如下:

a=99 bool=true

HashMap 的 putAll/remove/clear 函数

此用例展示了 HashMap 的基本使用方法。

代码如下:

import std.collection.*
main() {
    var map: HashMap<String, Int64> = HashMap<String, Int64>()
    var arr: Array<(String, Int64)> = [("d", 11), ("e", 12)]
    map.putAll(arr) // map : [("d", 11), ("e", 12)]
    var d = map.get("d")
    print("d=${d.getOrThrow()} ")
    map.remove("d") // map : [("e", 12)]
    var bool = map.contains("d")
    print("bool=${bool.toString()} ")
    map.clear() // map: []
    var bool1 = map.contains("e")
    print("bool1=${bool1.toString()}")
    return 0
}

运行结果如下:

d=11 bool=false bool1=false

HashSet 的 put/iterator/remove 函数

此用例展示了 HashSet 的基本使用方法。

代码如下:

import std.collection.*
/* 测试 */
main() {
    var set: HashSet<String> = HashSet<String>() // set: []
    set.put("apple") // set: ["apple"]
    set.put("banana") // set: ["apple", "banana"], not in order
    set.put("orange") // set: ["apple", "banana", "orange"], not in order
    set.put("peach") // set: ["apple", "banana", "orange", "peach"], not in order
    var itset = set.iterator()
    while(true) {
        var value = itset.next()
        match(value) {
            case Some(v) =>
                if (!set.contains(v)) {
                    print("Operation failed")
                    return 1
                } else { println(v) }
            case None => break
        }
    }
    set.remove("apple") // set: ["banana", "orange", "peach"], not in order
    println(set)
    return 0
}

由于 Set 中的顺序不是固定的,因此运行结果可能如下:

apple
banana
orange
peach
[banana, orange, peach]

迭代器操作函数

此用例展示了迭代器操作函数结合 pipeline 表达式的使用方法。

代码如下:

import std.collection.*

main() {
    let arr = [-1, 2, 3, 4, 5, 6, 7, 8, 9]
    arr |> filter{a: Int64 => a > 0} |> // filter -1
        step<Int64>(2) |> // [2, 4, 6, 8]
        skip<Int64>(2) |> // [6, 8]
        forEach<Int64>(println)

    let str = arr |> filter{a: Int64 => a % 2 == 1} |> collectString<Int64>(delimiter: ">")
    println(str)
    println(arr |> contains(6_i64))
    return 0
}

运行结果如下:

6
8
3>5>7>9
true

std.collection.concurrent 包

功能介绍

collection.concurrent 包提供了并发安全的集合类型实现。

本包实现了以下几种并发安全的集合类型:

  • ArrayBlockingQueue:以数组的形式实现的具有固定大小的有界队列。

  • BlockingQueue:一个线程安全的队列,它支持在队列为空时阻塞获取元素的操作,以及在队列已满时阻塞添加元素的操作。

  • ConcurrentHashMap:线程安全的哈希表实现,支持高并发的读写操作。

  • NonBlockingQueue:一种线程安全的队列数据结构,特点是在添加元素时,如果当前的尾部Block已满,那么会创建一个新的Block,而不是阻塞等待。这样可以保证在多线程环境下,队列的操作不会因为阻塞而导致线程的阻塞,从而提高了程序的性能。

API 列表

接口

接口名功能
ConcurrentMap<K, V> where K <: Equatable<K>保证线程安全和操作原子性的 Map 接口定义。

类名功能
ArrayBlockingQueue<E>基于数组实现的 Blocking Queue 数据结构及相关操作函数。
BlockingQueue<E>实现是带阻塞机制并支持用户指定容量上界的并发队列。
ConcurrentHashMapIterator<K, V> where K <: Hashable & Equatable<K>此类主要实现 Concurrent HashMap 的迭代器功能。
ConcurrentHashMap<K, V> where K <: Hashable & Equatable<K>此类用于实现并发场景下线程安全的哈希表 ConcurrentHashMap 数据结构及相关操作函数。
NonBlockingQueue<E>提供一个线程安全的队列,可以在多线程环境下安全地进行元素的添加和删除操作。

接口

interface ConcurrentMap<K, V> where K <: Equatable<K>

public interface ConcurrentMap<K, V> where K <: Equatable<K> {
    func get(key: K): Option<V>
    func contains(key: K): Bool
    mut func put(key: K, value: V): Option<V>
    mut func putIfAbsent(key: K, value: V): Option<V>
    mut func remove(key: K): Option<V>
    mut func remove(key: K, predicate: (V) -> Bool): Option<V>
    mut func replace(key: K, value: V): Option<V>
    mut func replace(key: K, eval: (V) -> V): Option<V>
    mut func replace(key: K, predicate: (V) -> Bool, eval: (V) -> V): Option<V>
}

功能:保证线程安全和操作原子性的 Map 接口定义。

ConcurrentMap 接口中声明了并发场景下线程安全的 Map 必须保证原子性的方法,我们希望定义的线程安全 Map 类都能实现 ConcurrentMap 接口。例如我们在该包中定义的 ConcurrentHashMap 就实现了 ConcurrentMap 接口,并提供了 ConcurrentMap 中所声明方法的保证原子性的实现。

ConcurrentMap 接口中声明了并发 Map 在并发场景下需要保证原子性的方法。

并发 Map 为“键”到“值”的映射,其中 K 为键的类型,V 为值的类型。

func contains(K)

func contains(key: K): Bool

功能:判断 Map 中是否包含指定键 key 的关联。

参数:

  • key: K - 传递要判断的 key。

返回值:

  • Bool - 当 key 存在时返回 true;当 key 不存在时返回 false。

func get(K)

func get(key: K): Option<V>

功能:返回 Map 中键 key 所关联的值。

参数:

  • key: K - 传递 key,获取 value。

返回值:

  • Option<V> - 当 key 存在时,返回其关联的值 Some(V);当 key 不存在时,返回 None。

func put(K, V)

mut func put(key: K, value: V): Option<V>

功能:将指定的值 value 与此 Map 中指定的键 key 关联。如果 Map 中已经包含键 key 的关联,则旧值将被替换;如果 Map 中不包含键 key 的关联,则添加键 key 与值 value 的关联。

参数:

  • key: K - 要放置的键。
  • value: V - 要关联的值。

返回值:

  • Option<V> - 如果赋值之前 key 存在,则返回旧的值 Some(V);当赋值前 key 不存在时,返回 None。

func putIfAbsent(K, V)

mut func putIfAbsent(key: K, value: V): Option<V>

功能:当此 Map 中不存在键 key 时,在 Map 中添加指定的值 value 与指定的键 key 的关联。如果 Map 已经包含键 key,则不执行赋值操作。

参数:

  • key: K - 要放置的键。
  • value: V - 要分配的值。

返回值:

  • Option<V> - 如果赋值之前 key 存在,则返回当前 key 对应的值 Some(V),且不执行赋值操作;当赋值前 key 不存在时,返回 None。

func remove(K)

mut func remove(key: K): Option<V>

功能:从此映射中删除指定键 key 的映射(如果存在)。

参数:

  • key: K - 传入要删除的 key。

返回值:

  • Option<V> - 如果移除之前 key 存在,则返回 key 对应的值 Some(V);当移除时 key 不存在时,返回 None。

func remove(K, (V) -> Bool)

mut func remove(key: K, predicate: (V) -> Bool): Option<V>

功能:如果 Map 中存在键 key 且 key 所关联的值 v 满足条件 predicate,则从 Map 中删除 key 的关联。

参数:

  • key: K - 传入要删除的 key。
  • predicate: (V) ->Bool - 传递一个 lambda 表达式进行判断。

返回值:

  • Option<V> - 如果 Map 中存在 key,则返回 key 对应的旧值 Some(V);当 Map 中不存在 key 时,或者 key 关联的值不满足 predicate 时,返回 None。

func replace(K, (V) -> Bool, (V) -> V)

mut func replace(key: K, predicate: (V) -> Bool, eval: (V) -> V): Option<V>

功能:如果 Map 中存在键 key(假设其关联的值为 v),且 v 满足条件 predicate,则将 Map 中键 key 关联的值替换为 eval(v) 的计算结果;如果 Map 中不存在键 key,或者存在键 key 但关联的值不满足 predicate,则不对 Map 做任何修改。

参数:

  • key: K - 传入要替换所关联值的键。
  • predicate: (V) ->Bool - 传递一个 lambda 表达式进行判断。
  • eval: (V) ->V - 传入计算用于替换的新值的函数。

返回值:

  • Option<V> - 如果 key 存在,则返回 key 对应的旧值 Some(V);当 key 不存在时,或者 key 关联的值不满足 predicate 时,返回 None。

func replace(K, (V) -> V)

mut func replace(key: K, eval: (V) -> V): Option<V>

功能:如果 Map 中存在键 key(假设其关联的值为 v),则将 Map 中键 key 关联的值替换为 eval(v) 的计算结果;如果 Map 中不存在键 key,则不对 Map 做任何修改。

参数:

  • key: K - 传入要替换所关联值的键。
  • eval: (V) ->V - 传入计算用于替换的新值的函数。

返回值:

  • Option<V> - 如果 key 存在,则返回 key 对应的旧值 Some(V);当 key 不存在时,返回 None。

func replace(K, V)

mut func replace(key: K, value: V): Option<V>

功能:如果 Map 中存在 key,则将 Map 中键 key 关联的值替换为 value;如果 Map 中不存在 key,则不对 Map 做任何修改。

参数:

  • key: K - 传入要替换所关联值的键。
  • value: V - 传入要替换成的新值。

返回值:

  • Option<V> - 如果 key 存在,则返回 key 对应的旧值 Some(V);当 key 不存在时,返回 None。

class ArrayBlockingQueue<E>

public class ArrayBlockingQueue<E> {
    public init(capacity: Int64)
    public init(capacity: Int64, elements: Collection<E>)
}

功能:基于数组实现的 Blocking Queue 数据结构及相关操作函数。

ArrayBlockingQueue 是带阻塞机制且需要用户指定容量上界的并发队列。

prop size

public prop size: Int64

功能:返回此 ArrayBlockingQueue 的元素个数。

注意:

此方法不保证并发场景下的原子性,建议在环境中没有其它线程并发地修改 ArrayBlockingQueue 时调用。

类型:Int64

capacity

public let capacity: Int64

功能:此 ArrayBlockingQueue 的容量。

类型:Int64

init(Int64)

public init(capacity: Int64)

功能:构造一个带有传入容量大小的 ArrayBlockingQueue

参数:

  • capacity: Int64 - 初始化容量大小。

异常:

init(Int64, Collection<E>)

public init(capacity: Int64, elements: Collection<E>)

功能:构造一个带有传入容量大小,并带有传入迭代器的 ArrayBlockingQueue

参数:

  • capacity: Int64 - 初始化容量大小。
  • elements: Collection<E> - 初始化迭代器元素。

异常:

  • IllegalArgumentException - 如果 capacity 小于等于 0 或小于迭代器元素 elements 的 size 则抛出异常。

func dequeue()

public func dequeue(): E

功能:阻塞的出队操作,获得队首元素并删除。

返回值:

  • E - 返回队首元素。

func dequeue(Duration)

public func dequeue(timeout: Duration): Option<E>

功能:阻塞的出队操作,获得队首元素并删除,如果队列为空,将等待指定的时间。如果 timeout 为负,则会立即执行出队操作并且返回操作结果。

参数:

返回值:

  • Option<E> - 返回队首元素。如果超出等待时间还未成功获取队首元素,则返回 None。

func enqueue(E)

public func enqueue(element: E): Unit

功能:阻塞的入队操作,将元素添加到队列尾部。

参数:

  • element: E - 要添加的元素。

func enqueue(E, Duration)

public func enqueue(element: E, timeout: Duration): Bool

功能:阻塞的入队操作,将元素添加到队列尾部,如果队列满了,将等待指定的时间。如果 timeout 为负,则会立即执行入队操作并且返回操作结果。

参数:

  • element: E - 要添加的元素。
  • timeout: Duration - 等待时间。

返回值:

  • Bool - 成功添加元素返回 true,超出等待时间还未成功添加元素返回 false。

func head()

public func head(): Option<E>

功能:获取队首元素。

注意:

该函数是非阻塞的。

返回值:

  • Option<E> - 返回队首元素,队列为空时返回 None。

func tryDequeue()

public func tryDequeue(): Option<E>

功能:非阻塞的出队操作,获得队首元素并删除。

返回值:

  • Option<E> - 返回队首元素,队列为空时返回 None。

func tryEnqueue(E)

public func tryEnqueue(element: E): Bool

功能:非阻塞的入队操作,将元素添加到队列尾部。

参数:

  • element: E - 要添加的元素。

返回值:

  • Bool - 成功添加返回 true;如果队列满了,添加失败返回 false。

class BlockingQueue<E>

public class BlockingQueue<E> {
    public init()
    public init(capacity: Int64)
    public init(capacity: Int64, elements: Array<E>)
    public init(capacity: Int64, elements: Collection<E>)
}

功能:实现是带阻塞机制并支持用户指定容量上界的并发队列。

阻塞队列的特点是,当队列满时,尝试向队列中添加元素的线程会被阻塞,直到队列有空余位置;当队列空时,尝试从队列中获取元素的线程会被阻塞,直到队列有可取元素。

let capacity

public let capacity: Int64

功能:返回此 BlockingQueue 的容量。

类型:Int64

prop size

public prop size: Int64

功能:返回此 BlockingQueue 的元素个数。

注意:

此方法不保证并发场景下的原子性,建议在环境中没有其它线程并发地修改 BlockingQueue 时调用。

类型:Int64

init()

public init()

功能:构造一个具有默认初始容量(Int64.Max)的 BlockingQueue

init(Int64)

public init(capacity: Int64)

功能:构造一个带有传入容量大小的 BlockingQueue

参数:

  • capacity: Int64 - 初始化容量大小。

异常:

init(Int64, Array<E>)

public init(capacity: Int64, elements: Array<E>)

功能:构造一个带有传入容量大小,并带有传入数组元素的 BlockingQueue

参数:

  • capacity: Int64 - 初始化容量大小。
  • elements: Array<E> - 初始化数组元素。

异常:

init(Int64, Collection<E>)

public init(capacity: Int64, elements: Collection<E>)

功能:构造一个带有传入容量大小,并带有传入迭代器的 BlockingQueue

参数:

  • capacity: Int64 - 初始化容量大小。
  • elements: Collection<E> - 初始化迭代器元素。

异常:

  • IllegalArgumentException - 如果 capacity 小于等于 0 或小于迭代器元素elements 的 size 则抛出异常。

func dequeue()

public func dequeue(): E

功能:阻塞的出队操作,获得队首元素并删除。

返回值:

  • E - 返回队首元素。

func dequeue(Duration)

public func dequeue(timeout: Duration): Option<E>

功能:阻塞的出队操作,获得队首元素并删除。如果队列为空,将等待指定的时间。如果 timeout 为负,则会立即执行出队操作并且返回操作结果。

参数:

返回值:

  • Option<E> - 返回队首元素。如果超出等待时间还未成功获取队首元素,则返回 None。

func enqueue(E)

public func enqueue(element: E): Unit

功能:阻塞的入队操作,将元素添加到队列尾部。

参数:

  • element: E - 要添加的元素。

func enqueue(E, Dureation)

public func enqueue(element: E, timeout: Duration): Bool

功能:阻塞的入队操作,将元素添加到队列尾部,如果队列满了,将等待指定的时间。如果 timeout 为负,则会立即执行入队操作并且返回操作结果。

参数:

  • element: E - 要添加的元素。
  • timeout: Duration - 等待时间。

返回值:

  • Bool - 成功添加元素返回 true。超出等待时间还未成功添加元素返回 false。

func head()

public func head(): Option<E>

功能:获取队首元素。

注意:

该函数是非阻塞的。

返回值:

  • Option<E> - 返回队首元素,队列为空时返回 None。

func tryDequeue()

public func tryDequeue(): Option<E>

功能:非阻塞的出队操作,获得队首元素并删除。

返回值:

  • Option<E> - 返回队首元素,队列为空时返回 None。

func tryEnqueue(E)

public func tryEnqueue(element: E): Bool

功能:非阻塞的入队操作,将元素添加到队列尾部。

参数:

  • element: E - 要添加的元素。

返回值:

  • Bool - 成功添加返回 true;如果队列满了,添加失败返回 false。

class ConcurrentHashMapIterator<K, V> where K <: Hashable & Equatable<K>

public class ConcurrentHashMapIterator<K, V> <: Iterator<(K, V)> where K <: Hashable & Equatable<K> {
    public init(cmap: ConcurrentHashMap<K, V>)
}

功能:此类主要实现 ConcurrentHashMap 的迭代器功能。

注意:

这里定义的 ConcurrentHashMap 迭代器:

  1. 不保证迭代结果为并发 HashMap 某一时刻的 “快照”,建议在环境中没有其它线程并发地修改 ConcurrentHashMap 时调用;
  2. 迭代器在迭代过程中,不保证可以感知环境线程对目标 ConcurrentHashMap 的修改。

父类型:

init(ConcurrentHashMap<K, V>)

public init(cmap: ConcurrentHashMap<K, V>)

功能:创建 ConcurrentHashMapIterator<K, V> 实例。

参数:

func iterator()

public func iterator(): Iterator<(K, V)>

功能:获取 ConcurrentHashMap<K, V> 迭代器自身。

返回值:

  • Iterator <(K, V) > - 迭代器自身。

func next()

public func next(): Option<(K, V)>

功能:返回迭代中的下一个元素。

返回值:

class ConcurrentHashMap<K, V> where K <: Hashable & Equatable<K>

public class ConcurrentHashMap<K, V> <: ConcurrentMap<K, V> & Collection<(K, V)> where K <: Hashable & Equatable<K> {
    public init(concurrencyLevel!: Int64 = 16)
    public init(capacity: Int64, concurrencyLevel!: Int64 = 16)
    public init(elements: Collection<(K, V)>, concurrencyLevel!: Int64 = 16)
    public init(size: Int64, initElement: (Int64) -> (K, V), concurrencyLevel!: Int64 = 16)
}

功能:此类用于实现并发场景下线程安全的哈希表 ConcurrentHashMap 数据结构及相关操作函数。

ConcurrentHashMap 中出现键值对数量大于“桶”数量的情况时,会进行“扩容”。

构造函数中的参数 concurrencyLevel 表示“并发度”,即:最多允许多少个线程并发修改 ConcurrentHashMap。查询键值对的操作是非阻塞的,不受所指定的并发度 concurrencyLevel 的限制。参数 concurrencyLevel 默认等于 16。它只影响 ConcurrentHashMap 在并发场景下的性能,不影响功能。

注意:

如果用户传入的 concurrencyLevel 小于 16,则并发度会被设置为 16。

concurrencyLevel 并非越大越好,更大的 concurrencyLevel 会导致更大的内存开销(甚至可能导致 out of memory 异常),用户需要在内存开销和运行效率之间进行平衡。

使用父类型:

示例:

使用示例见 ConcurrentHashMap 使用示例

prop size

public prop size: Int64

功能:返回键值的个数。

注意:

此方法不保证并发场景下的原子性,建议在环境中没有其它线程并发地修改 ConcurrentHashMap 时调用。

类型:Int64

init(Collection<(K, V)>, Int64)

public init(elements: Collection<(K, V)>, concurrencyLevel!: Int64 = 16)

功能:构造一个带有传入迭代器和指定并发度的 ConcurrentHashMap。该构造函数根据传入迭代器元素 elements 的 size 设置 ConcurrentHashMap 的容量。

参数:

  • elements: Collection<(K, V)> - 初始化迭代器元素。
  • concurrencyLevel!: Int64 - 用户指定的并发度。

init(Int64)

public init(concurrencyLevel!: Int64 = 16)

功能:构造一个具有默认初始容量(16)和指定并发度(默认等于 16)的 ConcurrentHashMap

参数:

  • concurrencyLevel!: Int64 - 用户指定的并发度。

init(Int64, (Int64) -> (K, V), Int64)

public init(size: Int64, initElement: (Int64) -> (K, V), concurrencyLevel!: Int64 = 16)

功能:构造具有传入大小和初始化函数元素以及指定并发度的 ConcurrentHashMap。该构造函数根据参数 size 设置 ConcurrentHashMap 的容量。

参数:

  • size: Int64 - 初始化函数元素的大小。
  • initElement: (Int64) ->(K, V) - 初始化函数元素。
  • concurrencyLevel!: Int64 - 用户指定并发度。

异常:

init(Int64, Int64)

public init(capacity: Int64, concurrencyLevel!: Int64 = 16)

功能:构造一个带有传入容量大小和指定并发度(默认等于 16)的 ConcurrentHashMap

参数:

  • capacity: Int64 - 初始化容量大小。
  • concurrencyLevel!: Int64 - 用户指定的并发度。

异常:

func contains(K)

public func contains(key: K): Bool

功能:判断此映射中是否包含指定键 key 的映射。

参数:

  • key: K - 传递要判断的 key。

返回值:

  • Bool - 是否包含指定键 key 的映射,包含为true,不包含为false。

func get(K)

public func get(key: K): ?V

功能:返回此映射中键 key 所关联的值。

参数:

  • key: K - 传递 key,获取 value。

返回值:

  • Option<V> - 此映射中键 key 所关联的值。

func isEmpty()

public func isEmpty(): Bool

功能:判断 ConcurrentHashMap 是否为空。

注意:

此方法不保证并发场景下的原子性,建议在环境中没有其它线程并发地修改 ConcurrentHashMap 时调用。

返回值:

  • Bool - 如果是,则返回 true,否则,返回 false。

func iterator()

public func iterator(): ConcurrentHashMapIterator<K, V>

功能:获取 ConcurrentHashMap 的迭代器。

返回值:

func put(K, V)

public func put(key: K, value: V): ?V

功能:将指定的值 value 与此 ConcurrentHashMap中指定的键 key 关联。如果 ConcurrentHashMap 中已经包含键 key 的关联,则旧值将被替换;如果 ConcurrentHashMap 中不包含键 key 的关联,则添加键 key 与值 value 的关联。

参数:

  • key: K - 要放置的键。
  • value: V - 要关联的值。

返回值:

  • Option<V> - 如果赋值之前 key 存在,则返回旧的值 Some(V);当赋值前 key 不存在时,返回 None。

func putIfAbsent(K, V)

public func putIfAbsent(key: K, value: V): ?V

功能:当此 ConcurrentHashMap中不存在键 key 时,在 ConcurrentHashMap 中添加指定的值 value 与指定的键 key 的关联。如果 ConcurrentHashMap 已经包含键 key,则不执行赋值操作。

参数:

  • key: K - 要放置的键。
  • value: V - 要分配的值。

返回值:

  • Option<V> - 如果赋值之前 key 存在,则返回当前 key 对应的值 Some(V),且不执行赋值操作;当赋值前 key 不存在时,返回 None。

func remove((K, (V) -> Bool))

public func remove(key: K, predicate: (V) -> Bool): ?V

功能:如果此映射中存在键 key 且 key 所映射的值 v 满足条件 predicate,则从此映射中删除 key 的映射。

参数:

  • key: K - 传入要删除的 key。
  • predicate: (V) ->Bool - 传递一个 lambda 表达式进行判断。

返回值:

  • Option<V> - 如果映射中存在 key,则返回 key 对应的旧值;当映射中不存在 key 时,或者 key 关联的值不满足 predicate 时,返回 None。

func remove(K)

public func remove(key: K): ?V

功能:从此映射中删除指定键 key 的映射(如果存在)。

参数:

  • key: K - 传入要删除的 key。

返回值:

  • Option<V> - 如果移除之前 key 存在,则返回 key 对应的值 Some(V);当移除时 key 不存在时,返回 None。

func replace(K, (V) -> Bool, (V) -> V)

public func replace(key: K, predicate: (V) -> Bool, eval: (V) -> V): ?V

功能:如果 ConcurrentHashMap 中存在键 key(假设其关联的值为 v),且 v 满足条件 predicate,则将 ConcurrentHashMap 中键 key 关联的值替换为 eval(v) 的计算结果;如果 ConcurrentHashMap 中不存在键 key,或者存在键 key 但关联的值不满足 predicate,则不对 ConcurrentHashMap 做任何修改。 参数:

  • key: K - 传入要替换所关联值的键。
  • predicate: (V) ->Bool - 传递一个 lambda 表达式进行判断。
  • eval: (V) ->V - 传入计算用于替换的新值的函数。

返回值:

  • Option<V> - 如果 key 存在,则返回 key 对应的旧值 Some(V);当 key 不存在时,或者 key 关联的值不满足 predicate 时,返回 None。

func replace(K, (V) -> V)

public func replace(key: K, eval: (V) -> V): ?V

功能:如果 ConcurrentHashMap 中存在键 key(假设其关联的值为 v),则将 ConcurrentHashMap 中键 key 关联的值替换为 eval(v) 的计算结果;如果 ConcurrentHashMap中不存在键 key,则不对 ConcurrentHashMap 做任何修改。

参数:

  • key: K - 传入要替换所关联值的键。
  • eval: (V) ->V - 传入计算用于替换的新值的函数。

返回值:

  • Option<V> - 如果 key 存在,则返回 key 对应的旧值 Some(V);当 key 不存在时,返回 None。

func replace(K, V)

public func replace(key: K, value: V): ?V

功能:如果 ConcurrentHashMap 中存在 key,则将 ConcurrentHashMap 中键 key 关联的值替换为 value;如果 ConcurrentHashMap 中不存在 key,则不对 ConcurrentHashMap 做任何修改。

参数:

  • key: K - 传入要替换所关联值的键。
  • value: V - 传入要替换成的新值。

返回值:

  • Option<V> - 如果 key 存在,则返回 key 对应的旧值 Some(V);当 key 不存在时,返回 None。

operator func [](K)

public operator func [](key: K): V

功能:运算符重载集合,如果键存在,返回键对应的值;如果不存在,抛出异常。

参数:

  • key: K - 传递值进行判断。

返回值:

  • V - 与键对应的值。

异常:

operator func [](K, V)

public operator func [](key: K, value!: V): Unit

功能:运算符重载集合,如果键 key 存在,新 value 覆盖旧 value;如果键不存在,添加此键值对。

参数:

  • key: K - 传递值进行判断。
  • value!: V - 传递要设置的值。

class NonBlockingQueue<E>

public class NonBlockingQueue<E> {
    public init()
    public init(elements: Collection<E>)
}

功能:提供一个线程安全的队列,可以在多线程环境下安全地进行元素的添加和删除操作。

非阻塞队列的目的是为了解决多线程环境下的同步问题,使得多个线程可以并发地进行队列的操作,而不会出现数据冲突或者死锁的问题。

非阻塞队列在多线程编程中非常常见,它可以用于任何需要线程安全队列的场景,例如生产者消费者模型、任务调度、线程池等。

使用示例:

使用示例见 NonBlockingQueue 使用示例

prop size

public prop size: Int64

功能:获取此 NonBlockingQueue 的元素个数。

注意:

此方法不保证并发场景下的原子性,建议在环境中没有其它线程并发地修改 NonBlockingQueue 时调用。

类型:Int64

init()

public init()

功能:构造一个默认的 NonBlockingQueue 实例。

init(Collection<E>)

public init(elements: Collection<E>)

功能:根据 Collection<E> 实例构造一个 NonBlockingQueue 实例。

参数:

func dequeue()

public func dequeue(): Option<E>

功能:获取并删除队首元素。

返回值:

  • Option<E> - 成功删除则返回队首元素,队列为空则返回 None。

func enqueue(E)

public func enqueue(element: E): Bool

功能:非阻塞的入队操作,将元素添加到队列尾部。

注意:

该函数不会返回 false。

参数:

  • element: E - 要添加的元素。

返回值:

  • Bool - 成功添加元素则返回 true。

func head()

public func head(): Option<E>

功能:获取队首元素,不会删除该元素。

返回值:

  • Option<E> - 成功获取则返回队首元素,队列为空则返回 None。

ConcurrentHashMap 使用示例

import std.collection.*
import std.collection.concurrent.*
import std.sync.*

main() {
    let threads = 8
    let M = 1024

    let cmap = ConcurrentHashMap<Int64, Int64>(concurrencyLevel: 64)
    let jobs = Array<Future<Unit>>(threads, repeat: unsafe { zeroValue<Future<Unit>>() })
    for (t in 0..threads) {
        jobs[t] = spawn {
            for (i in t..M : threads) {
                cmap.put(i, i + 3)
            }
        }
    }

    for (t in 0..threads) {
        jobs[t].get()
    }

    println("Size after put: ${cmap.size}")

    for (t in 0..threads) {
        jobs[t] = spawn {
            for (i in t..M : threads) {
                cmap.remove(i, {v => v % 2 == 0})
            }
        }
    }

    for (t in 0..threads) {
        jobs[t].get()
    }

    println("Size after remove first: ${cmap.size}")

    for (t in 0..threads) {
        jobs[t] = spawn {
            for (i in t..M : threads) {
                cmap.remove(i)
            }
        }
    }

    for (t in 0..threads) {
        jobs[t].get()
    }

    println("Size after remove second: ${cmap.size}")
}

结果如下:

Size after put: 1024
Size after remove first: 512
Size after remove second: 0

NonBlockingQueue 使用示例

import std.collection.*
import std.collection.concurrent.*
import std.sync.*

main() {
    let threads = 8
    let total: Int64 = 128
    let bq = NonBlockingQueue<Int64>(Array<Int64>(total, {i => i}))
    println("Total ${bq.size} after init")
    let jobs = Array<Future<Unit>>(threads, repeat: unsafe { zeroValue<Future<Unit>>() })
    for (t in 0..threads) {
        jobs[t] = spawn {
            for (i in t..total : threads) {
                bq.dequeue()
            }
        }
    }

    for (t in 0..threads) {
        jobs[t].get()
    }
    println("Total ${bq.size} after dequeue")
}

结果如下:

Total 128 after init
Total 0 after dequeue

std.console 包

功能介绍

console 包提供和标准输入、标准输出、标准错误进行交互的方法。

本包提供 Console 类,用于获取这三个标准流。

  • ConsoleReader 封装了标准输入流的相关功能,可以通过相关的 read 方法从标准输入中读取数据。
  • ConsoleWriter 封装了标准输出、标准错误流的相关功能,ConsoleWriter 封装了一系列的 write 方法,提供了向标准输出、标准错误写入数据的能力。

标准输入(stdin)、标准输出(stdout)和标准错误(stderr)是计算机操作系统中常见的三个流。

标准输入是程序从用户获取输入数据的流,通常是键盘输入。标准输出是程序向用户输出结果的流,通常是屏幕输出。标准错误是程序在发生错误时输出错误信息的流,通常也是屏幕输出。

在 Unix/Linux 系统中,标准输入、标准输出和标准错误分别对应文件描述符 0、1 和 2。程序可以使用这些文件描述符来读取和写入数据。例如,可以使用重定向符号将标准输出重定向到文件中,或将标准错误输出重定向到另一个程序的标准输入中。

注意:

console 只支持 UTF-8 编码,Windows 环境需要在 CMD 终端手动执行 chcp 65001(将 Windows 终端的编码更改为 UTF-8)。当系统编码和 console 相关 API 所要求的编码类型不一致时,可能导致乱码等问题。

API 列表

类名功能
Console提供标准输入、标准输出和标准错误 Stream 的获取接口。
ConsoleReader提供从标准输入读取字符或者字符串的功能。
ConsoleWriter提供向标准输出或者标准错误流写入字符或者字符串的功能。

class Console

public class Console

功能:此类提供标准输入、标准输出和标准错误流的获取接口。

static prop stdErr

public static prop stdErr: ConsoleWriter

功能:该成员属性为 ConsoleWriter 类型,它提供标准错误的获取功能。

类型:ConsoleWriter

static prop stdIn

public static prop stdIn: ConsoleReader

功能:该成员属性为 ConsoleReader 类型,它提供标准输入的获取功能。

类型:ConsoleReader

static prop stdOut

public static prop stdOut: ConsoleWriter

功能:该成员属性为 ConsoleWriter 类型,它提供标准输出的获取功能。

类型:ConsoleWriter

class ConsoleReader

public class ConsoleReader <: InputStream

功能:提供从控制台读出数据并转换成字符或字符串的功能。

该类型无法构造实例,只能通过 Console.stdIn 获取实例。 读操作是同步的,内部设有缓存区来保存控制台输入的内容,当到达控制台输入流的结尾时,控制台读取函数将返回None

说明:

ConsoleReader 只有一个实例,所有方法共享同一个缓存区,相关read方法返回None的情形有:

  • 将标准输入重定向到文件时,读取到文件结尾EOF。
  • Linux 环境,按下 Ctrl+D
  • Windows 环境,按下 Ctrl+Z 后加回车。

ConsoleReader 只支持 UTF-8 编码,Windows 环境需手动执行 chcp 65001(将 Windows 终端的编码更改为 UTF-8 ),当系统编码和 API 所需编码不一致时,可能产生乱码,从而导致读取 Rune 时发生异常,抛出 IllegalArgumentException

父类型:

func read()

public func read(): ?Rune

功能:从标准输入中读取下一个字符。

返回值:

  • ?Rune - 读取到字符,返回 ?Rune,否则返回None

异常:

func read(Array<Byte>)

public func read(arr: Array<Byte>): Int64

功能:从标准输入中读取并放入 arr 中。

注意:

该函数存在风险,可能读取出来的结果恰好把 UTF-8 code point 从中截断,如果发生截断,将导致该 Array<Byte> 转换成字符串的结果不正确或抛出异常。

参数:

返回值:

  • Int64 - 返回读取到的字节长度。

func readToEnd()

public func readToEnd(): ?String

功能:从标准输入中读取所有字符。

直到读取到文件结束符EOF,或者在 Linux 上键入 Ctrl+D 或在 Windows 上键入 Ctrl+Z + 回车结束。读取到字符,返回 ?String,否则返回 None。读取失败时会返回 None,该接口不会抛出异常,即使输入不符合 UTF-8 编码的字符串,也会构造出一个 String 并返回,其行为等同于 String.fromUtf8Uncheck(Array<Byte>)。

返回值:

  • ?String - 将读取到的所有数据以 ?String 的形式返回。

func readUntil((Rune) -> Bool)

public func readUntil(predicate: (Rune) -> Bool): ?String

功能:从标准输入中读取数据直到读取到的字符满足predicate条件结束。

满足 predicate: (Rune) -> Bool 条件的字符包含在结果中,读取失败时会返回None

参数:

  • predicate: (Rune) ->Bool - 终止读取的条件。

返回值:

  • ?String - 将读取到的数据以 ?String 的形式返回。

func readUntil(Rune)

public func readUntil(ch: Rune): ?String

功能:从标准输入中读取数据直到读取到字符 ch 结束。

ch包含在结果中,如果读取到文件结束符 EOF,将返回读取到的所有信息,读取失败时会返回 None

参数:

  • ch: Rune - 终止字符。

返回值:

  • ?String - 将读取到的数据以 ?String 的形式返回。

func readln()

public func readln(): ?String

功能:从标准输入中读取一行字符串。

读取到字符,返回 ?String,结果不包含末尾换行符。该接口不会抛出异常,即使输入不符合UTF-8编码的字符串,也会构造出一个 String 并返回,其行为等同于 String.fromUtf8Uncheck(Array<Byte>)。

返回值:

  • ?String - 读取到的行数据,读取失败返回 None

class ConsoleWriter

public class ConsoleWriter <: OutputStream

功能:此类提供保证线程安全的标准输出功能。

每次 write 调用写到控制台的结果是完整的,不同的 write 函数调用的结果不会混合到一起。 该类型无法构造实例,只能通过 Console.stdOut 获取标准输出实例或者 Console.stdErr 获取标准错误的实例。

父类型:

func flush()

public func flush(): Unit

功能:刷新输出流。

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能:指定的将字节数组 buffer 写入标准输出或标准错误流中。

参数:

  • buffer: Array<Byte> - 要被写入的字节数组。

func write(Bool)

public func write(v: Bool): Unit

功能:将指定的布尔值的文本表示形式写入标准输出或标准错误流中。

参数:

  • v: Bool - 要写入的值。

func write(Float16)

public func write(v: Float16): Unit

功能:将指定的 16 位浮点数值的文本表示写入标准输出或标准错误流中。

参数:

func write(Float32)

public func write(v: Float32): Unit

功能:将指定的 32 位浮点数值的文本表示写入标准输出或标准错误流中。

参数:

func write(Float64)

public func write(v: Float64): Unit

功能:将指定的 64 位浮点数值的文本表示写入标准输出或标准错误流中。

参数:

func write(Int16)

public func write(v: Int16): Unit

功能:将指定的 16 位有符号整数值的文本表示写入标准输出或标准错误流中。

参数:

  • v: Int16 - 要写入的值。

func write(Int32)

public func write(v: Int32): Unit

功能:将指定的 32 位有符号整数值的文本表示写入标准输出或标准错误流中。

参数:

  • v: Int32 - 要写入的值。

func write(Int64)

public func write(v: Int64): Unit

功能:将指定的 64 位有符号整数值的文本表示写入标准输出或标准错误流中。

参数:

  • v: Int64 - 要写入的值。

func write(Int8)

public func write(v: Int8): Unit

功能:将指定的 8 位有符号整数值的文本表示写入标准输出或标准错误流中。

参数:

  • v: Int8 - 要写入的值。

func write(Rune)

public func write(v: Rune): Unit

功能:将指定的 Rune 的 Unicode 字符值写入标准输出或标准错误流中。

参数:

  • v: Rune - 要写入的值。

func write(String)

public func write(v: String): Unit

功能:将指定的字符串值写入标准输出或标准错误流中。

参数:

  • v: String - 要写入的值。

func write(UInt16)

public func write(v: UInt16): Unit

功能:将指定的 16 位无符号整数值的文本表示写入标准输出或标准错误流中。

参数:

  • v: UInt16 - 要写入的值。

func write(UInt32)

public func write(v: UInt32): Unit

功能:将指定的 32 位无符号整数值的文本表示写入标准输出或标准错误流中。

参数:

  • v: UInt32 - 要写入的值。

func write(UInt64)

public func write(v: UInt64): Unit

功能:将指定的 64 位无符号整数值的文本表示写入标准输出或标准错误流中。

参数:

  • v: UInt64 - 要写入的值。

func write(UInt8)

public func write(v: UInt8): Unit

功能:将指定的 8 位无符号整数值的文本表示写入标准输出或标准错误流中。

参数:

  • v: UInt8 - 要写入的值。

func write<T>(T) where T <: ToString

public func write<T>(v: T): Unit where T <: ToString

功能:将实现了 ToString 接口的数据类型写入标准输出或标准错误流中。

参数:

  • v: T - 要被写入的 ToString 类型的实例。

func writeln(Array<Byte>)

public func writeln(buffer: Array<Byte>): Unit

功能:指定的将字节数组 buffer (后跟换行符)写入标准输出或标准错误流中。

参数:

func writeln(Bool)

public func writeln(v: Bool): Unit

功能:将指定的布尔值的文本表示形式(后跟换行符)写入标准输出或标准错误流中。

参数:

  • v: Bool - 要写入的值。

func writeln(Float16)

public func writeln(v: Float16): Unit

功能:将指定的 16 位浮点数值的文本表示(后跟换行符)写入标准输出或标准错误流中。

参数:

func writeln(Float32)

public func writeln(v: Float32): Unit

功能:将指定的 32 位浮点数值的文本表示(后跟换行符)写入标准输出或标准错误流中。

参数:

func writeln(Float64)

public func writeln(v: Float64): Unit

功能:将指定的 64 位浮点数值的文本表示(后跟换行符)写入标准输出或标准错误流中。

参数:

func writeln(Int16)

public func writeln(v: Int16): Unit

功能:将指定的 16 位有符号整数值的文本表示(后跟换行符)写入标准输出或标准错误流中。

参数:

  • v: Int16 - 要写入的值。

func writeln(Int32)

public func writeln(v: Int32): Unit

功能:将指定的 32 位有符号整数值的文本表示(后跟换行符)写入标准输出或标准错误流中。

参数:

  • v: Int32 - 要写入的值。

func writeln(Int64)

public func writeln(v: Int64): Unit

功能:将指定的 64 位有符号整数值的文本表示(后跟换行符)写入标准输出或标准错误流中。

参数:

  • v: Int64 - 要写入的值。

func writeln(Int8)

public func writeln(v: Int8): Unit

功能:将指定的 8 位有符号整数值的文本表示(后跟换行符)写入标准输出或标准错误流中。

参数:

  • v: Int8 - 要写入的值。

func writeln(Rune)

public func writeln(v: Rune): Unit

功能:将指定的 Unicode 字符值(后跟换行符)写入标准输出或标准错误流中。

参数:

  • v: Rune - 要写入的值。

func writeln(String)

public func writeln(v: String): Unit

功能:将指定的字符串值(后跟换行符)写入标准输出或标准错误流中。

参数:

  • v: String - 要写入的值。

func writeln(UInt16)

public func writeln(v: UInt16): Unit

功能:将指定的 16 位无符号整数值的文本表示(后跟换行符)写入标准输出或标准错误流中。

参数:

  • v: UInt16 - 要写入的值。

func writeln(UInt32)

public func writeln(v: UInt32): Unit

功能:将指定的 32 位无符号整数值的文本表示(后跟换行符)写入标准输出或标准错误流中。 参数:

  • v: UInt32 - 要写入的值。

func writeln(UInt64)

public func writeln(v: UInt64): Unit

功能:将指定的 64 位无符号整数值的文本表示(后跟换行符)写入标准输出或标准错误流中。

参数:

  • v: UInt64 - 要写入的值。

func writeln(UInt8)

public func writeln(v: UInt8): Unit

功能:将指定的 8 位无符号整数值的文本表示(后跟换行符)写入标准输出或标准错误流中。

参数:

  • v: UInt8 - 要写入的值。

func writeln<T>(T) where T <: ToString

public func writeln<T>(v: T): Unit where T <: ToString

功能:将实现了 ToString 接口的数据类型转换成的字符串(后跟换行符)写入标准输出或标准错误流中。

参数:

  • v: T - 要写入的值。

Console 示例

下面是 Console 示例,示例中接收用户输入的两条信息,并将这些信息通过标准输出原样返回给用户。

import std.console.*

main() {
    Console.stdOut.write("请输入信息1:")
    var c = Console.stdIn.readln() // 输入:你好,请问今天星期几?
    var r = c.getOrThrow()
    Console.stdOut.writeln("输入的信息1为:" + r)

    Console.stdOut.write("请输入信息2:")
    c = Console.stdIn.readln() // 输入:你好,请问今天几号?
    r = c.getOrThrow()
    Console.stdOut.writeln("输入的信息2为:" + r)

    return
}

运行结果如下:

请输入信息1:你好,请问今天星期几?
输入的信息1为:你好,请问今天星期几?
请输入信息2:你好,请问今天几号?
输入的信息2为:你好,请问今天几号?

std.convert 包

功能介绍

convert 包提供从字符串转到特定类型的 Convert 系列函数。

例如字符串 "true" 到布尔类型 true 的转换。

API 列表

接口

接口名功能
Parsable<T>将字符串解析为特定类型的接口。

接口

interface Parsable<T>

public interface Parsable<T> {
    static func parse(value: String): T
    static func tryParse(value: String): Option<T>
}

功能:本接口提供了统一的方法,以支持将字符串解析为特定类型。

本接口提供了 parse 和 tryParse 两套方法,parse 方法将在解析失败时抛出异常,tryParse 方法将返回值用 Option 包裹,解析失败时将返回 None。 本包内已经为 BoolRuneFloat16Int64 等基础类型实现该接口,可用于将字符串转换为这些类型。

static func parse(String)

static func parse(value: String): T

功能:从字符串中解析特定类型。

参数:

  • value: String - 待解析的字符串。

返回值:

  • T - 转换后的值。

static func tryParse(String)

static func tryParse(value: String): Option<T>

功能:从字符串中解析特定类型。

参数:

  • value: String - 待解析的字符串。

返回值:

  • Option<T> - 转换后值,转换失败返回 Option<T>.None。

extend Bool <: Parsable<Bool>

extend Bool <: Parsable<Bool>

功能:此扩展主要用于实现将 Bool 类型字面量的字符串转换为 Bool 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): Bool

功能:将 Bool 类型字面量的字符串转换为 Bool 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

static func tryParse(String)

public static func tryParse(data: String): Option<Bool>

功能:将 Bool 类型字面量的字符串转换为 Option<Bool> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend Float16 <: Parsable<Float16>

extend Float16 <: Parsable<Float16>

功能:此扩展主要用于实现将 Float16 类型字面量的字符串转换为 Float16 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): Float16

功能:将 Float16 类型字面量的字符串转换为 Float16 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

static func tryParse(String)

public static func tryParse(data: String): Option<Float16>

功能:将 Float16 类型字面量的字符串转换为 Option<Float16> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend Float32 <: Parsable<Float32>

extend Float32 <: Parsable<Float32>

功能:此扩展主要用于实现将 Float32 类型字面量的字符串转换为 Float32 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): Float32

功能:将 Float32 类型字面量的字符串转换为 Float32 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

static func tryParse(String)

public static func tryParse(data: String): Option<Float32>

功能:将 Float32 类型字面量的字符串转换为 Option<Float32> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend Float64 <: Parsable<Float64>

extend Float64 <: Parsable<Float64>

功能:此扩展主要用于实现将 Float64 类型字面量的字符串转换为 Float64 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): Float64

功能:将 Float64 类型字面量的字符串转换为 Float64 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

static func tryParse(String)

public static func tryParse(data: String): Option<Float64>

功能:将 Float64 类型字面量的字符串转换为 Option<Float64> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend Int16 <: Parsable<Int16>

extend Int16 <: Parsable<Int16>

功能:此扩展主要用于实现将 Int16 类型字面量的字符串转换为 Int16 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): Int16

功能:将 Int16 类型字面量的字符串转换为 Int16 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

  • IllegalArgumentException - 当字符串为空,首位为 + ,转换失败,或转换后超出 Int16 范围,或字符串中含有无效的 UTF-8 字符时,抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Int16>

功能:将 Int16 类型字面量的字符串转换为 Option<Int16> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend Int32 <: Parsable<Int32>

extend Int32 <: Parsable<Int32>

功能:此扩展主要用于实现将 Int32 类型字面量的字符串转换为 Int32 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): Int32

功能:将 Int32 类型字面量的字符串转换为 Int32 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

  • IllegalArgumentException - 当字符串为空,首位为 + ,转换失败,或转换后超出 Int32 范围,或字符串中含有无效的 UTF-8 字符时,抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Int32>

功能:将 Int32 类型字面量的字符串转换为 Option<Int32> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend Int64 <: Parsable<Int64>

extend Int64 <: Parsable<Int64>

功能:此扩展主要用于实现将 Int64 类型字面量的字符串转换为 Int64 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): Int64

功能:将 Int64 类型字面量的字符串转换为 Int64 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

  • IllegalArgumentException - 当字符串为空,首位为 + ,转换失败,或转换后超出 Int64 范围,或字符串中含有无效的 UTF-8 字符时,抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Int64>

功能:将 Int64 类型字面量的字符串转换为 Option<Int64> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend Int8 <: Parsable<Int8>

extend Int8 <: Parsable<Int8>

功能:此扩展主要用于实现将 Int8 类型字面量的字符串转换为 Int8 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): Int8

功能:将 Int8 类型字面量的字符串转换为 Int8 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

  • IllegalArgumentException - 当字符串为空,首位为 + ,转换失败,或转换后超出 Int8 范围,或字符串中含有无效的 UTF-8 字符时,抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Int8>

功能:将 Int8 类型字面量的字符串转换为 Option<Int8> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend Rune <: Parsable<Rune>

extend Rune <: Parsable<Rune>

功能:此扩展主要用于实现将 Rune 类型字面量的字符串转换为 Rune 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): Rune

功能:将 Rune 类型字面量的字符串转换为 Rune 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

  • IllegalArgumentException - 当字符串为空,或转换失败时,或字符串中含有无效的 UTF-8 字符时,抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Rune>

功能:将 Rune 类型字面量的字符串转换为 Option<Rune> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend UInt16 <: Parsable<UInt16>

extend UInt16 <: Parsable<UInt16>

功能:此扩展主要用于实现将 UInt16 类型字面量的字符串转换为 UInt16 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): UInt16

功能:将 UInt16 类型字面量的字符串转换为 UInt16 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

  • IllegalArgumentException - 当字符串为空,首位为 +-,转换失败,或转换后超出 UInt16 范围,或字符串中含有无效的 UTF-8 字符时,抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<UInt16>

功能:将 UInt16 类型字面量的字符串转换为 Option<UInt16> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend UInt32 <: Parsable<UInt32>

extend UInt32 <: Parsable<UInt32>

功能:此扩展主要用于实现将 UInt32 类型字面量的字符串转换为 UInt32 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): UInt32

功能:将 UInt32 类型字面量的字符串转换为 UInt32 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

  • IllegalArgumentException - 当字符串为空,首位为 +-,转换失败,或转换后超出 UInt32 范围,或字符串中含有无效的 UTF-8 字符时,抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<UInt32>

功能:将 UInt32 类型字面量的字符串转换为 Option<UInt32> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend UInt64 <: Parsable<UInt64>

extend UInt64 <: Parsable<UInt64>

功能:此扩展主要用于实现将 UInt64 类型字面量的字符串转换为 UInt64 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): UInt64

功能:将 UInt64 类型字面量的字符串转换为 UInt64 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

  • IllegalArgumentException - 当字符串为空,首位为 +-,转换失败,或转换后超出 UInt64 范围,或字符串中含有无效的 UTF-8 字符时,抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<UInt64>

功能:将 UInt64 类型字面量的字符串转换为 Option<UInt64> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

extend UInt8 <: Parsable<UInt8>

extend UInt8 <: Parsable<UInt8>

功能:此扩展主要用于实现将 UInt8 类型字面量的字符串转换为 UInt8 值的相关操作函数。

父类型:

static func parse(String)

public static func parse(data: String): UInt8

功能:将 UInt8 类型字面量的字符串转换为 UInt8 值。

参数:

  • data: String - 要转换的字符串。

返回值:

异常:

  • IllegalArgumentException - 当字符串为空,首位为 +-,转换失败,或转换后超出 UInt8 范围,或字符串中含有无效的 UTF-8 字符时,抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<UInt8>

功能:将 UInt8 类型字面量的字符串转换为 Option<UInt8> 值。

参数:

  • data: String - 要转换的字符串。

返回值:

covert 使用示例

代码如下:

import std.convert.*

main():Int64 {
    var strBool_parse : String = "true"
    var strBool_tryParse : String = "false"
    var strChar_parse : String = "'a'"
    var strChar_tryParse : String = "'\\u{00e2}'"
    var strInt8_parse : String = "-128"
    var strInt8_tryParse : String = "127"
    var strInt16_parse : String = "-32768"
    var strInt16_tryParse : String = "32767"
    var strInt32_parse : String = "-2147483648"
    var strInt32_tryParse : String = "2147483647"
    var strInt64_parse : String = "-9223372036854775808"
    var strInt64_tryParse : String = "9223372036854775807"
    var strFloat16_parse : String = "-65504.0"
    var strFloat16_tryParse : String = "65504.0"
    var strFloat32_parse : String = "-3.14159"
    var strFloat32_tryParse : String = "3.14159"
    var strFloat64_parse : String = "-3.1415926"
    var strFloat64_tryParse : String = "3.1415926"
    var strUInt8_parse : String = "255"
    var strUInt8_tryParse : String = "255"
    var strUInt16_parse : String = "65535"
    var strUInt16_tryParse : String = "65535"
    var strUInt32_parse : String = "4294967295"
    var strUInt32_tryParse : String = "4294967295"
    var strUInt64_parse : String = "18446744073709551615"
    var strUInt64_tryParse : String = "18446744073709551615"

    println("After the conversion of parse, \"true\" became ${Bool.parse(strBool_parse)}")
    println("After the conversion of tryParse, \"false\" became ${Bool.tryParse(strBool_tryParse)}")

    println("After the conversion of parse, \"'a'\" became ${Rune.parse(strChar_parse)}")
    println("After the conversion of tryParse, \"'\\u{00e2}'\" became ${Rune.tryParse(strChar_tryParse)}")

    println("After the conversion of parse, \"-128\" became ${Int8.parse(strInt8_parse)}")
    println("After the conversion of tryParse, \"127\" became ${Int8.tryParse(strInt8_tryParse)}")

    println("After the conversion of parse, \"-32768\" became ${Int16.parse(strInt16_parse)}")
    println("After the conversion of tryParse, \"32767\" became ${Int16.tryParse(strInt16_tryParse)}")

    println("After the conversion of parse, \"-2147483648\" became ${Int32.parse(strInt32_parse)}")
    println("After the conversion of tryParse, \"2147483647\" became ${Int32.tryParse(strInt32_tryParse)}")

    println("After the conversion of parse, \"-9223372036854775808\" became ${Int64.parse(strInt64_parse)}")
    println("After the conversion of tryParse, \"9223372036854775807\" became ${Int64.tryParse(strInt64_tryParse)}")

    println("After the conversion of parse, \"-65504.0\" became ${Float16.parse(strFloat16_parse)}")
    println("After the conversion of tryParse, \"65504.0\" became ${Float16.tryParse(strFloat16_tryParse)}")

    println("After the conversion of parse, \"-3.14159\" became ${Float32.parse(strFloat32_parse)}")
    println("After the conversion of tryParse, \"3.14159\" became ${Float32.tryParse(strFloat32_tryParse)}")

    println("After the conversion of parse, \"-3.1415926\" became ${Float64.parse(strFloat64_parse)}")
    println("After the conversion of tryParse, \"3.1415926\" became ${Float64.tryParse(strFloat64_tryParse)}")

    println("After the conversion of parse, \"255\" became ${UInt8.parse(strUInt8_parse)}")
    println("After the conversion of tryParse, \"255\" became ${UInt8.tryParse(strUInt8_tryParse)}")

    println("After the conversion of parse, \"65535\" became ${UInt16.parse(strUInt16_parse)}")
    println("After the conversion of tryParse, \"65535\" became ${UInt16.tryParse(strUInt16_tryParse)}")

    println("After the conversion of parse, \"4294967295\" became ${UInt32.parse(strUInt32_parse)}")
    println("After the conversion of tryParse, \"4294967295\" became ${UInt32.tryParse(strUInt32_tryParse)}")

    println("After the conversion of parse, \"18446744073709551615\" became ${UInt64.parse(strUInt64_parse)}")
    println("After the conversion of tryParse, \"18446744073709551615\" became ${UInt64.tryParse(strUInt64_tryParse)}")
    return 0
}

运行结果如下:

After the conversion of parse, "true" became true
After the conversion of tryParse, "false" became Some(false)
After the conversion of parse, "'a'" became a
After the conversion of tryParse, "'\u{00e2}'" became Some(â)
After the conversion of parse, "-128" became -128
After the conversion of tryParse, "127" became Some(127)
After the conversion of parse, "-32768" became -32768
After the conversion of tryParse, "32767" became Some(32767)
After the conversion of parse, "-2147483648" became -2147483648
After the conversion of tryParse, "2147483647" became Some(2147483647)
After the conversion of parse, "-9223372036854775808" became -9223372036854775808
After the conversion of tryParse, "9223372036854775807" became Some(9223372036854775807)
After the conversion of parse, "-65504.0" became -65504.000000
After the conversion of tryParse, "65504.0" became Some(65504.000000)
After the conversion of parse, "-3.14159" became -3.141590
After the conversion of tryParse, "3.14159" became Some(3.141590)
After the conversion of parse, "-3.1415926" became -3.141593
After the conversion of tryParse, "3.1415926" became Some(3.141593)
After the conversion of parse, "255" became 255
After the conversion of tryParse, "255" became Some(255)
After the conversion of parse, "65535" became 65535
After the conversion of tryParse, "65535" became Some(65535)
After the conversion of parse, "4294967295" became 4294967295
After the conversion of tryParse, "4294967295" became Some(4294967295)
After the conversion of parse, "18446744073709551615" became 18446744073709551615
After the conversion of tryParse, "18446744073709551615" became Some(18446744073709551615)

std.crypto.cipher 包

功能介绍

std.crypto.cipher 包提供对称加解密通用接口。

API 列表

接口

接口名功能
BlockCipher此接口是摘要算法的通用接口。

接口

interface BlockCipher

public interface BlockCipher {
    prop blockSize: Int64
    func encrypt(input: Array<Byte>): Array<Byte>
    func decrypt(input: Array<Byte>): Array<Byte>
}

功能:分组加解密算法接口,继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

prop blockSize

prop blockSize: Int64

功能:分组块长度,单位字节。

类型:Int64

func encrypt(Array<Byte>)

func encrypt(input: Array<Byte>): Array<Byte>

功能:提供加密函数。

参数:

  • input: Array<Byte> - 待进行加密的数据。

返回值:

func decrypt(Array<Byte>)

func decrypt(input: Array<Byte>): Array<Byte>

功能:提供解密函数。

参数:

  • input: Array<Byte> - 待进行解密的数据。

返回值:

std.crypto.digest 包

功能介绍

std.crypto.digest 包提供常用摘要算法的通用接口,包括 MD5、SHA1、SHA224、SHA256、SHA384、SHA512、HMAC、SM3等。

API 列表

函数

函数名功能
digest<T>(T, Array<Byte>) where T <: Digest提供 digest 泛型函数,实现用指定的摘要算法进行摘要运算。
digest<T>(T, String) where T <: Digest提供 digest 泛型函数,实现用指定的摘要算法进行摘要运算。

接口

接口名功能
Digest此接口是摘要算法的通用接口。

函数

func digest<T>(T, Array<Byte>) where T <: Digest

public func digest<T>(algorithm: T, data: Array<Byte>): Array<Byte> where T <: Digest

功能:提供 digest 泛型函数,实现用指定的摘要算法进行摘要运算。

参数:

  • algorithm: T - 具体的摘要算法。
  • data: Array<Byte> - 待进行摘要运算的数据。

返回值:

func digest<T>(T, String) where T <: Digest

public func digest<T>(algorithm: T, data: String): Array<Byte> where T <: Digest

功能:提供 digest 泛型函数,实现用指定的摘要算法进行摘要运算。

参数:

  • algorithm: T - 具体的摘要算法。
  • data: String - 待进行摘要运算的数据。

返回值:

接口

interface Digest

public interface Digest {
    prop size: Int64
    prop blockSize: Int64
}

功能:摘要算法接口,继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

prop blockSize

prop blockSize: Int64

功能:返回Block块长度,单位字节。

类型:Int64

prop size

prop size: Int64

功能:返回生成的摘要信息长度,单位字节。

类型:Int64

func finish()

func finish(): Array<Byte>

功能:返回生成的 digest 值。

返回值:

func reset()

mut func reset(): Unit

功能:重置 digest 对象到初始状态。

func write(Array<Byte>)

mut func write(buffer: Array<Byte>): Unit

功能:使用给定的 buffer 更新 digest 对象。

std.database.sql 包

功能介绍

database.sql 包提供仓颉访问数据库的接口。

本包提供 SQL/CLI 的通用接口,配合数据库驱动 Driver 完成对数据库的各项操作。

注意:

当前仅支持 SQL/CLI 接口。

SQL 数据类型和仓颉数据类型对应表如下:

SQLCDBC/CangjieSqlDataType说明
RUNEStringSqlChar-
VARCHARStringSqlVarchar-
CLOBio.InputStreamSqlClob-
BINARYArray<Byte>SqlBinary-
VARBINARYArray<Byte>SqlVarBinary-
BLOBio.InputStreamSqlBlob-
NUMERICDecimalsqlDecimal-
DECIMALDecimalsqlDecimal-
BOOLEANBoolSqlBool-
TINYINTInt8SqlByte-
SMALLINTInt16SqlSmallInt-
INTEGERInt32SqlInteger-
BIGINTInt64SqlBigInt-
REALFloat32SqlReal-
DOUBLEFloat64SqlDouble-
DATEtime.DateTimeSqlDate值支持 YEARMONTHDAY
TIMEtime.DateTimeSqlTime值支持 HOURMINUTESECOND(不包括 TIME ZONE)。
TIMETZtime.DateTimeSqlTimeTz值支持 HOURMINUTESECOND(包括 TIME ZONE)。
TIMESTAMPtime.DateTimeSqlTimestamp值支持 YEARMONTHDAYHOURMINUTESECONDTIME ZONE
INTERVALtime.DurationSqlInterval年-月间隔或者日-时间隔。

API列表

接口

接口名功能
ColumnInfo执行 Select/Query 语句返回结果的列信息。
Connection数据库连接接口。
Datasource数据源接口。
Driver数据库驱动接口。
QueryResult执行 Select 语句产生的结果接口。
SqlDbType所有 sql 数据类型的父类。
SqlNullableDbType允许 null 值的 sql 数据类型父类。
Statementsql 语句预执行接口。
Transaction定义数据库事务的核心行为。
UpdateResult执行 Insert、Update、Delete 语句产生的结果接口。

类名功能
DriverManager支持运行时根据驱动名获取数据库驱动实例。
PooledDatasource数据库连接池类,提供数据库连接池能力。
SqlOption预定义的 sql 选项名称和值。
SqlBigInt大整数,对应仓颉 Int64 类型。
SqlBinary定长二进制字符串,对应仓颉 Array<Byte> 类型。
SqlBlob变长超大二进制字符串(BINARY LARGE OBJECT),对应仓颉 InputStream 类型。
SqlBool布尔类型,对应仓颉 Bool 类型。
SqlByte字节,对应仓颉 Int8 类型。
SqlChar定长字符串,对应仓颉 String 类型。
SqlClob变长超大字符串(RUNE LARGE OBJECT),对应仓颉 InputStream 类型。
SqlDate日期,仅年月日有效,对应仓颉 DateTime 类型。
SqlDecimal高精度数,对应仓颉 Decimal 类型。
SqlDouble双精度数,对应仓颉 Float64 类型。
SqlInteger中整数,对应仓颉 Int32 类型。
SqlInterval时间间隔,对应仓颉 Duration 类型。
SqlReal浮点数,对应仓颉 Float32 类型。
SqlSmallInt小整数,对应仓颉 Int16 类型。
SqlTime时间,仅时分秒毫秒有效,对应仓颉 DateTime 类型。
SqlTimestamp时间戳,对应仓颉 DateTime 类型。
SqlTimeTz带时区的时间,仅时分秒毫秒时区有效,对应仓颉 DateTime 类型。
SqlVarBinary变长二进制字符串,对应仓颉 Array<Byte> 类型。
SqlVarchar变长字符串,对应仓颉 String 类型。
SqlNullableBigInt大整数,对应仓颉 Int64 类型,可为数据库 Null 值。
SqlNullableBinary定长二进制字符串,对应仓颉 Array<Byte> 类型,可为数据库 Null 值。
SqlNullableBlob变长超大二进制字符串(BINARY LARGE OBJECT),对应仓颉 InputStream 类型,可为数据库 Null 值。
SqlNullableBool布尔类型,对应仓颉 Bool 类型,可为数据库 Null 值。
SqlNullableByte字节,对应仓颉 Int8 类型,可为数据库 Null 值。
SqlNullableChar定长二进制字符串,对应仓颉 String 类型,可为数据库 Null 值。
SqlNullableClob变长超大字符串(RUNE LARGE OBJECT),对应仓颉 InputStream 类型,可为数据库 Null 值。
SqlNullableDate日期,仅年月日有效,对应仓颉 DateTime 类型,可为数据库 Null 值。
SqlNullableDecimal高精度数,对应仓颉 Decimal 类型,可为数据库 Null 值。
SqlNullableDouble双精度数,对应仓颉 Float64 类型,可为数据库 Null 值。
SqlNullableInteger中整数,对应仓颉 Int32 类型,可为数据库 Null 值。
SqlNullableInterval时间间隔,对应仓颉 Duration 类型,可为数据库 Null 值。
SqlNullableReal浮点数,对应仓颉 Float32 类型,可为数据库 Null 值。
SqlNullableSmallInt小整数,对应仓颉 Int16 类型,可为数据库 Null 值。
SqlNullableTime时间,仅时分秒毫秒有效,对应仓颉 DateTime 类型,可为数据库 Null 值。
SqlNullableTimestamp时间戳,对应仓颉 DateTime 类型,可为数据库 Null 值。
SqlNullableTimeTz带时区的时间,仅时分秒毫秒时区有效,对应仓颉 DateTime 类型,可为数据库 Null 值。
SqlNullableVarBinary变长二进制字符串,对应仓颉 Array<Byte> 类型,可为数据库 Null 值。
SqlNullableVarchar变长字符串,对应仓颉 String 类型,可为数据库 Null 值。

枚举

枚举名功能
ConnectionState描述与数据源连接的当前状态。
TransactionAccessMode事务读写模式。
TransactionDeferrableMode事务的延迟模式。
TransactionIsoLevel定义了数据库系统中,一个事务中操作的结果在何时以何种方式对其他并发事务操作可见。

异常类

异常类名功能
SqlException用于处理 sql 相关的异常。

接口

interface ColumnInfo

public interface ColumnInfo {
    prop displaySize: Int64
    prop length: Int64
    prop name: String
    prop nullable: Bool
    prop scale: Int64
    prop typeName: String
}

功能:执行 Select/Query 语句返回结果的列信息。

prop displaySize

prop displaySize: Int64

功能:获取列值的最大显示长度,如果无限制,则应该返回 Int64.Max (仍然受数据库的限制)。

类型:Int64

prop length

prop length: Int64

功能:获取列值大小。

说明:

  • 对于数值数据,表示最大精度。
  • 对于字符数据,表示以字符为单位的长度。
  • 对于日期时间数据类型,表示字符串表示形式的最大字符长度。
  • 对于二进制数据,表示以字节为单位的长度。
  • 对于 RowID 数据类型,表示以字节为单位的长度。
  • 对于列大小不适用的数据类型,返回 0。

类型:Int64

prop name

prop name: String

功能:列名或者别名。

类型:String

prop nullable

prop nullable: Bool

功能:表示列值是否允许数据库 Null 值。

类型:Bool

prop scale

prop scale: Int64

功能:获取列值的小数长度,如果无小数部分,返回 0。

类型:Int64

prop typeName

prop typeName: String

功能:获取列类型名称,如果在仓颉中有对应数据类型的定义,返回对应类型的 toString 函数的返回值;如果在仓颉中无对应数据类型的定义,由数据库驱动定义。

类型:String

interface Connection

public interface Connection <: Resource {
    prop state: ConnectionState
    func createTransaction(): Transaction
    func getMetaData(): Map<String, String>
    func prepareStatement(sql: String): Statement
}

功能:数据库连接接口。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

父类型:

prop state

prop state: ConnectionState

功能:描述与数据源连接的当前状态。

类型:ConnectionState

func createTransaction()

func createTransaction(): Transaction

功能:创建事务对象。

返回值:

异常:

  • SqlException - 当已经处于事务状态,不支持并行事务时,抛出异常。

func getMetaData()

func getMetaData(): Map<String, String>

功能:返回连接到的数据源元数据。

返回值:

func prepareStatement(String)

func prepareStatement(sql: String): Statement

功能:通过传入的 sql 语句,返回一个预执行的 Statement 对象实例。

参数:

  • sql: String - 预执行的 sql 语句,sql 语句的参数只支持 ? 符号占位符。

返回值:

  • Statement - 一个可以执行 sql 语句的实例对象。

异常:

  • SqlException - 当 sql 语句包含不认识的字符时,抛出异常。

interface Datasource

public interface Datasource <: Resource {
    func connect(): Connection
    func setOption(key: String, value: String): Unit
}

功能:数据源接口。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

父类型:

func connect()

func connect(): Connection

功能:返回一个可用的连接。

返回值:

func setOption(String, String)

func setOption(key: String, value: String): Unit

功能:设置连接选项。

参数:

  • key: String - 连接选项名称。
  • value: String - 连接选项的值。

interface Driver

public interface Driver {
    prop name: String
    prop preferredPooling: Bool
    prop version: String
    func open(connectionString: String, opts: Array<(String, String)>): Datasource
}

功能:数据库驱动接口。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

prop name

prop name: String

功能:驱动名称。

类型:String

prop preferredPooling

prop preferredPooling: Bool

功能:指示驱动程序是否与连接池亲和。

如果否,则不建议使用连接池。比如 sqlite 驱动连接池化的收益不明显,不建议使用连接池。

类型:Bool

prop version

prop version: String

功能:驱动版本。

类型:String

func open(String, Array<(String, String)>)

func open(connectionString: String, opts: Array<(String, String)>): Datasource

功能:通过 connectionString 和选项打开数据源。

参数:

  • connectionString: String - 数据库连接字符串。
  • opts: Array<(String, String)> - key,value 的 tuple 数组,打开数据源的选项。

返回值:

interface QueryResult

public interface QueryResult <: Resource {
    prop columnInfos: Array<ColumnInfo>
    func next(values: Array<SqlDbType>): Bool
}

功能:执行 Select 语句产生的结果接口。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

父类型:

prop columnInfos

prop columnInfos: Array<ColumnInfo>

功能:返回结果集的列信息,比如列名,列类型,列长度,是否允许数据库 Null 值等。

类型:Array<ColumnInfo>

func next(Array<SqlDbType>)

func next(values: Array<SqlDbType>): Bool

功能:向后移动一行,必须先调用一次 next 才能移动到第一行,第二次调用移动到第二行,依此类推。当返回 true 时,驱动会在 values 中填入行数据;当返回 false 时结束,且不会修改 values 的内容。

参数:

返回值:

  • Bool - 下一行存在数据则返回 true,否则返回 false

interface SqlDbType

public interface SqlDbType {
    prop name: String
}

功能:所有 sql 数据类型的父类。

要扩展用户定义的类型,请继承 SqlDbTypeSqlNullableDbType

说明:

SqlDbType 接口所有实现类型都必须具有公共 value 属性。每种 sql 数据类型实现类,同时满足以下条件:

  • 只有一个参数的构造函数,参数类型为 TT 为仓颉语言支持的类型)。
  • public 修饰的 value 属性,其类型必须上一条中使用的参数类型一致,其值为对应仓颉类型的值。
  • 如果数据类型允许 null 值,继承 SqlNullableDbTypenull 值时,value 字段的值为 Option<T>.None。

prop name

prop name: String

功能:获取类型名称。

类型:String

interface SqlNullableDbType

public interface SqlNullableDbType <: SqlDbType

功能:允许 null 值的 sql 数据类型父类。

如果为 null 值,value 属性值为 Option.None。

父类型:

interface Statement

public interface Statement <: Resource {
    prop parameterColumnInfos: Array<ColumnInfo>
    func query(params: Array<SqlDbType>): QueryResult
    func setOption(key: String, value: String): Unit
    func update(params: Array<SqlDbType>): UpdateResult
}

功能:sql 语句预执行接口。

Statement 绑定了一个 Connection ,继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

父类型:

prop parameterColumnInfos

prop parameterColumnInfos: Array<ColumnInfo>

功能:预执行 sql 语句中,占位参数的列信息,比如列名,列类型,列长度,是否允许数据库 Null 值等。

类型:Array<ColumnInfo>

func query(Array<SqlDbType>)

func query(params: Array<SqlDbType>): QueryResult

功能:执行 sql 语句,得到查询结果。

参数:

  • params: Array<SqlDbType> - sql 数据类型的数据列表,用于替换 sql 语句中的 ? 占位符。

返回值:

异常:

  • SqlException - 当执行过程中发生了异常情况,比如网络中断,服务器超时,参数个数不正确时,抛出异常。

func setOption(String, String)

func setOption(key: String, value: String): Unit

功能:设置预执行 sql 语句选项。

参数:

  • key: String - 连接选项名称。
  • value: String - 连接选项的值。

func update(Array<SqlDbType>)

func update(params: Array<SqlDbType>): UpdateResult

功能:执行 sql 语句,得到更新结果。

参数:

  • params: Array<SqlDbType> - sql 数据类型的数据列表,用于替换 sql 语句中的 ? 占位符。

返回值:

异常:

  • SqlException - 当执行过程中发生了异常情况,比如网络中断,服务器超时,参数个数不正确时,抛出异常。

interface Transaction

public interface Transaction {
    mut prop accessMode: TransactionAccessMode
    mut prop deferrableMode: TransactionDeferrableMode
    mut prop isoLevel: TransactionIsoLevel
    func begin(): Unit
    func commit(): Unit
    func release(savePointName: String): Unit
    func rollback(): Unit
    func rollback(savePointName: String): Unit
    func save(savePointName: String): Unit
}

功能:定义数据库事务的核心行为。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

prop accessMode

mut prop accessMode: TransactionAccessMode

功能:获取数据库事务访问模式。

类型:TransactionAccessMode

prop deferrableMode

mut prop deferrableMode: TransactionDeferrableMode

功能:获取数据库事务延迟模式。

类型:TransactionDeferrableMode

prop isoLevel

mut prop isoLevel: TransactionIsoLevel

功能:获取数据库事务隔离级别。

类型:TransactionIsoLevel

func begin()

func begin(): Unit

功能:开始数据库事务。

异常:

  • SqlException - 当提交事务时服务器端发生错误,以及当事务已提交或回滚或连接已断开时,抛出异常。

func commit()

func commit(): Unit

功能:提交数据库事务。

异常:

  • SqlException - 当提交事务时服务器端发生错误,以及当事务已提交或回滚或连接已断开时,抛出异常。

func release(String)

func release(savePointName: String): Unit

功能:销毁先前在当前事务中定义的保存点。这允许系统在事务结束之前回收一些资源。

参数:

  • savePointName: String - 保存点名称。

异常:

  • SqlException - 当提交事务时服务器端发生错误,以及当事务已提交或回滚或连接已断开时,抛出异常。

func rollback()

func rollback(): Unit

功能:从挂起状态回滚事务。

异常:

  • SqlException - 当提交事务时服务器端发生错误,以及当事务已提交或回滚或连接已断开时,抛出异常。

func rollback(String)

func rollback(savePointName: String): Unit

功能:回滚事务至指定保存点名称。

参数:

  • savePointName: String - 保存点名称。

异常:

  • SqlException - 当提交事务时服务器端发生错误,以及当事务已提交或回滚或连接已断开时,抛出异常。

func save(String)

func save(savePointName: String): Unit

功能:在事务中创建一个指定名称的保存点,可用于回滚此保存点之后的事务。

参数:

  • savePointName: String - 保存点名称。

异常:

  • SqlException - 当提交事务时服务器端发生错误,以及当事务已提交或回滚或连接已断开时,抛出异常。

interface UpdateResult

public interface UpdateResult {
    prop lastInsertId: Int64
    prop rowCount: Int64
}

功能:执行 Insert、Update、Delete 语句产生的结果接口。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

prop lastInsertId

prop lastInsertId: Int64

功能:执行 Insert 语句自动生成的最后 row ID ,如果不支持则 row ID 为 0。

类型:Int64

prop rowCount

prop rowCount: Int64

功能:执行 Insert、Update、Delete 语句影响的行数。

类型:Int64

class DriverManager

public class DriverManager

功能:支持运行时根据驱动名获取数据库驱动实例。

static func deregister(String)

public static func deregister(driverName: String): Unit

功能:按名称取消注册数据库驱动(如果存在)。本函数并发安全。

参数:

  • driverName: String - 驱动名称。

static func drivers()

public static func drivers(): Array<String>

功能:返回已注册数据库驱动名称的列表(名称已按照字典序排序)。本方法并发安全。

返回值:

static func getDriver(String)

public static func getDriver(driverName: String): Option<Driver>

功能:按名称获取已注册的数据库驱动,如果不存在返回 None。本函数并发安全。

参数:

  • driverName: String - 驱动名称。

返回值:

  • Option<Driver> - 若驱动存在返回 Option 包装的驱动实例,否则返回 None

static func register(String, Driver)

public static func register(driverName: String, driver: Driver): Unit

功能:按名称和驱动实例注册数据库驱动,名称和实例一一对应。本方法并发安全。

参数:

  • driverName: String - 驱动名称。
  • driver: Driver - 驱动实例。

异常:

  • SqlException - 当名称重复已经被注册时,抛出异常。

class PooledDatasource

public class PooledDatasource <: Datasource {
    public init(datasource: Datasource)
}

功能:数据库连接池类,提供数据库连接池能力。

父类型:

prop connectionTimeout

public mut prop connectionTimeout: Duration

功能:从池中获取连接的超时时间。

类型:Duration

异常:

prop idleTimeout

public mut prop idleTimeout: Duration

功能:允许连接在池中闲置的最长时间,超过这个时间的空闲连接可能会被回收。

类型:Duration

prop keepaliveTime

public mut prop keepaliveTime: Duration

功能:检查空闲连接健康状况的间隔时间,防止它被数据库或网络基础设施超时。

类型:Duration

prop maxIdleSize

public mut prop maxIdleSize: Int32

功能:最大空闲连接数量,超过这个数量的空闲连接会被关闭,负数或0表示无限制。

类型:Int32

prop maxLifeTime

public mut prop maxLifeTime: Duration

功能:自连接创建以来的持续时间,在该持续时间之后,连接将自动关闭。

类型:Duration

prop maxSize

public mut prop maxSize: Int32

功能:连接池最大连接数量,负数或0表示无限制。

类型:Int32

init(DataSource)

public init(datasource: Datasource)

功能:通过数据源 datasource 构造一个 PooledDatasource 实例,入参必须为 Datasource 对象。

参数:

func close()

public func close(): Unit

功能:关闭连接池中的所有连接并阻止其它连接请求。调用该方法会阻塞至所有连接关闭并归还到连接池。

func connect()

public func connect(): Connection

功能:获取一个连接。

返回值:

func isClosed()

public func isClosed(): Bool

功能:判断连接是否关闭。

返回值:

  • Bool - 连接是否关闭。

func setOption(String, String)

public func setOption(key: String, value: String): Unit

功能:设置数据库驱动连接选项(公钥在 SqlOption 中预定义)。

参数:

  • key: String - 连接选项名称。
  • value: String - 连接选项的值。

class SqlBigInt

public class SqlBigInt <: SqlDbType {
    public init(v: Int64)
}

功能:大整数,对应仓颉 Int64 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlBigInt

类型:String

prop value

public mut prop value: Int64

功能:该数据的值。

类型:Int64

init(Int64)

public init(v: Int64)

功能:根据传入参数 v 构造一个 SqlBigInt 实例。

参数:

  • v: Int64 - 传入的数据。

class SqlBinary

public class SqlBinary <: SqlDbType {
    public init(v: Array<Byte>)
}

功能:定长二进制字符串,对应仓颉 Array<Byte> 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlBinary

类型:String

prop value

public mut prop value: Array<Byte>

功能:该数据的值。

类型:Array<Byte>

init(Array<Byte>)

public init(v: Array<Byte>)

功能:根据传入参数 v 构造一个 SqlBinary 实例。

参数:

class SqlBlob

public class SqlBlob <: SqlDbType {
    public init(v: InputStream)
}

功能:变长超大二进制字符串(BINARY LARGE OBJECT),对应仓颉 InputStream 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlBlob

类型:String

prop value

public mut prop value: InputStream

功能:该数据的值。

类型:InputStream

init(InputStream)

public init(v: InputStream)

功能:根据传入参数 v 构造一个 SqlBlob 实例。

参数:

class SqlBool

public class SqlBool <: SqlDbType {
    public init(v: Bool)
}

功能:布尔类型,对应仓颉 Bool 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlBool

类型:String

prop value

public mut prop value: Bool

功能:该数据的值。

类型:Bool

init(Bool)

public init(v: Bool)

功能:根据传入参数 v 构造一个 SqlBool 实例。

参数:

  • v: Bool - 传入的数据。

class SqlByte

public class SqlByte <: SqlDbType {
    public init(v: Int8)
}

功能:字节,对应仓颉 Int8 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlByte

类型:String

prop value

public mut prop value: Int8

功能:该数据的值。

类型:Int8

init(Int8)

public init(v: Int8)

功能:根据传入参数 v 构造一个 SqlByte 实例。

参数:

  • v: Int8 - 传入的数据。

class SqlChar

public class SqlChar <: SqlDbType {
    public init(v: String)
}

功能:定长字符串,对应仓颉 String 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlChar

类型:String

prop value

public mut prop value: String

功能:该数据的值。

类型:String

init(String)

public init(v: String)

功能:根据传入参数 v 构造一个 SqlChar 实例。

参数:

  • v: String - 传入的数据。

class SqlClob

public class SqlClob <: SqlDbType {
    public init(v: InputStream)
}

功能:变长超大字符串(RUNE LARGE OBJECT),对应仓颉 InputStream 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlClob

类型:String

prop value

public mut prop value: InputStream

功能:该数据的值。

类型:InputStream

init(InputStream)

public init(v: InputStream)

功能:根据传入参数 v 构造一个 SqlClob 实例。

参数:

class SqlDate

public class SqlDate <: SqlDbType {
    public init(v: DateTime)
}

功能:日期,仅年月日有效,对应仓颉 DateTime 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlDate

类型:String

prop value

public mut prop value: DateTime

功能:该数据的值。

类型:DateTime

init(DateTime)

public init(v: DateTime)

功能:根据传入参数 v 构造一个 SqlDate 实例。

参数:

class SqlDecimal

public class SqlDecimal <: SqlDbType {
    public init(v: Decimal)
}

功能:高精度数,对应仓颉 Decimal 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlDecimal

类型:String

prop value

public mut prop value: Decimal

功能:该数据的值。

类型:Decimal

init(Decimal)

public init(v: Decimal)

功能:根据传入参数 v 构造一个 SqlDecimal 实例。

参数:

class SqlDouble

public class SqlDouble <: SqlDbType {
    public init(v: Float64)
}

功能:双精度数,对应仓颉 Float64 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlDouble

类型:String

prop value

public mut prop value: Float64

功能:该数据的值。

类型:Float64

init(Float64)

public init(v: Float64)

功能:根据传入参数 v 构造一个 SqlDouble 实例。

参数:

class SqlInteger

public class SqlInteger <: SqlDbType {
    public init(v: Int32)
}

功能:中整数,对应仓颉 Int32 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlInteger

类型:String

prop value

public mut prop value: Int32

功能:该数据的值。

类型:Int32

init(Int32)

public init(v: Int32)

功能:根据传入参数 v 构造一个 SqlInteger 实例。

参数:

  • v: Int32 - 传入的数据。

class SqlInterval

public class SqlInterval <: SqlDbType {
    public init(v: Duration)
}

功能:时间间隔,对应仓颉 Duration 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlInterval

类型:String

prop value

public mut prop value: Duration

功能:该数据的值。

类型:Duration

init(Duration)

public init(v: Duration)

功能:根据传入参数 v 构造一个 SqlInterval 实例。

参数:

class SqlNullableBigInt

public class SqlNullableBigInt <: SqlNullableDbType {
    public init(v: ?Int64)
}

功能:大整数,对应仓颉 Int64 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableBigInt

类型:String

prop value

public mut prop value: ?Int64

功能:该数据的值。

类型:?Int64

init(?Int64)

public init(v: ?Int64)

功能:根据传入参数 v 构造一个 SqlNullableBigInt 实例。

参数:

  • v: ?Int64 - 传入的数据。

class SqlNullableBinary

public class SqlNullableBinary <: SqlNullableDbType {
    public init(v: ?Array<Byte>)
}

功能:定长二进制字符串,对应仓颉 Array<Byte> 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableBinary

类型:String

prop value

public mut prop value: ?Array<Byte>

功能:该数据的值。

类型:?Array<Byte>

init(?Array<Byte>)

public init(v: ?Array<Byte>)

功能:根据传入参数 v 构造一个 SqlNullableBinary 实例。

参数:

class SqlNullableBlob

public class SqlNullableBlob <: SqlNullableDbType {
    public init(v: ?InputStream)
}

功能:变长超大二进制字符串(BINARY LARGE OBJECT),对应仓颉 InputStream 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableBlob

类型:String

prop value

public mut prop value: ?InputStream

功能:该数据的值。

类型:?InputStream

init(?InputStream)

public init(v: ?InputStream)

功能:根据传入参数 v 构造一个 SqlNullableBlob 实例。

参数:

class SqlNullableBool

public class SqlNullableBool <: SqlNullableDbType {
    public init(v: ?Bool)
}

功能:布尔类型,对应仓颉 Bool 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableBool

类型:String

prop value

public mut prop value: ?Bool

功能:该数据的值。

类型:?Bool

init(?Bool)

public init(v: ?Bool)

功能:根据传入参数 v 构造一个 SqlNullableBool 实例。

参数:

  • v: ?Bool - 传入的数据。

class SqlNullableByte

public class SqlNullableByte <: SqlNullableDbType {
    public init(v: ?Int8)
}

功能:字节,对应仓颉 Int8 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableByte

类型:String

prop value

public mut prop value: ?Int8

功能:该数据的值。

类型:?Int8

init(?Int8)

public init(v: ?Int8)

功能:根据传入参数 v 构造一个 SqlNullableByte 实例。

参数:

  • v: ?Int8 - 传入的数据。

class SqlNullableChar

public class SqlNullableChar <: SqlNullableDbType {
    public init(v: ?String)
}

功能:定长字符串,对应仓颉 String 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableChar

类型:String

prop value

public mut prop value: ?String

功能:该数据的值。

类型:?String

init(?String)

public init(v: ?String)

功能:根据传入参数 v 构造一个 SqlNullableChar 实例。

参数:

  • v: ?String - 传入的数据。

class SqlNullableClob

public class SqlNullableClob <: SqlNullableDbType {
    public init(v: ?InputStream)
}

功能:变长超大字符串(RUNE LARGE OBJECT),对应仓颉 InputStream 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableClob

类型:String

prop value

public mut prop value: ?InputStream

功能:该数据的值。

类型:?InputStream

init(?InputStream)

public init(v: ?InputStream)

功能:根据传入参数 v 构造一个 SqlNullableClob 实例。

参数:

class SqlNullableDate

public class SqlNullableDate <: SqlNullableDbType {
    public init(v: ?DateTime)
}

功能:日期,仅年月日有效,对应仓颉 DateTime 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableDate

类型:String

prop value

public mut prop value: ?DateTime

功能:该数据的值。

类型:?DateTime

init(?DateTime)

public init(v: ?DateTime)

功能:根据传入参数 v 构造一个 SqlNullableDate 实例。

参数:

class SqlNullableDecimal

public class SqlNullableDecimal <: SqlNullableDbType {
    public init(v: ?Decimal)
}

功能:高精度数,对应仓颉 Decimal 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableDecimal

类型:String

prop value

public mut prop value: ?Decimal

功能:该数据的值。

类型:?Decimal

init(?Decimal)

public init(v: ?Decimal)

功能:根据传入参数 v 构造一个 SqlNullableDecimal 实例。

参数:

class SqlNullableDouble

public class SqlNullableDouble <: SqlNullableDbType {
    public init(v: ?Float64)
}

功能:双精度数,对应仓颉 Float64 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableDouble

类型:String

prop value

public mut prop value: ?Float64

功能:该数据的值。

类型:?Float64

init(?Float64)

public init(v: ?Float64)

功能:根据传入参数 v 构造一个 SqlNullableDouble 实例。

参数:

class SqlNullableInteger

public class SqlNullableInteger <: SqlNullableDbType {
    public init(v: ?Int32)
}

功能:中整数,对应仓颉 Int32 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableInteger

类型:String

prop value

public mut prop value: ?Int32

功能:该数据的值。

类型:?Int32

init(?Int32)

public init(v: ?Int32)

功能:根据传入参数 v 构造一个 SqlNullableInteger 实例。

参数:

  • v: ?Int32 - 传入的数据。

class SqlNullableInterval

public class SqlNullableInterval <: SqlNullableDbType {
    public init(v: ?Duration)
}

功能:时间间隔,对应仓颉 Duration 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableInterval

类型:String

prop value

public mut prop value: ?Duration

功能:该数据的值。

类型:?Duration

init(?Duration)

public init(v: ?Duration)

功能:根据传入参数 v 构造一个 SqlNullableInterval 实例。

参数:

class SqlNullableReal

public class SqlNullableReal <: SqlNullableDbType {
    public init(v: ?Float32)
}

功能:浮点数,对应仓颉 Float32 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableReal

类型:String

prop value

public mut prop value: ?Float32

功能:该数据的值。

类型:?Float32

init(?Float32)

public init(v: ?Float32)

功能:根据传入参数 v 构造一个 SqlNullableReal 实例。

参数:

class SqlNullableSmallInt

public class SqlNullableSmallInt <: SqlNullableDbType {
    public init(v: ?Int16)
}

功能:小整数,对应仓颉 Int16 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableSmallInt

类型:String

prop value

public mut prop value: ?Int16

功能:该数据的值。

类型:?Int16

init(?Int16)

public init(v: ?Int16)

功能:根据传入参数 v 构造一个 SqlNullableSmallInt 实例。

参数:

  • v: ?Int16 - 传入的数据。

class SqlNullableTime

public class SqlNullableTime <: SqlNullableDbType {
    public init(v: ?DateTime)
}

功能:时间,仅时分秒毫秒有效,对应仓颉 DateTime 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableTime

类型:String

prop value

public mut prop value: ?DateTime

功能:该数据的值。

类型:?DateTime

init(?DateTime)

public init(v: ?DateTime)

功能:根据传入参数 v 构造一个 SqlNullableTime 实例。

参数:

class SqlNullableTimeTz

public class SqlNullableTimeTz <: SqlNullableDbType {
    public init(v: ?DateTime)
}

功能:带时区的时间,仅时分秒毫秒时区有效,对应仓颉 DateTime 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableTimeTz

类型:String

prop value

public mut prop value: ?DateTime

功能:该数据的值。

类型:?DateTime

init(?DateTime)

public init(v: ?DateTime)

功能:根据传入参数 v 构造一个 SqlNullableTimeTz 实例。

参数:

class SqlNullableTimestamp

public class SqlNullableTimestamp <: SqlNullableDbType {
    public init(v: ?DateTime)
}

功能:时间戳,对应仓颉 DateTime 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableTimestamp

类型:String

prop value

public mut prop value: ?DateTime

功能:该数据的值。

类型:?DateTime

init(?DateTime)

public init(v: ?DateTime)

功能:根据传入参数 v 构造一个 SqlNullableTimestamp 实例。

参数:

class SqlNullableVarBinary

public class SqlNullableVarBinary <: SqlNullableDbType {
    public init(v: ?Array<Byte>)
}

功能:变长二进制字符串,对应仓颉 Array<Byte> 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableVarBinary

类型:String

prop value

public mut prop value: ?Array<Byte>

功能:该数据的值。

类型:?Array<Byte>

init(?Array<Byte>)

public init(v: ?Array<Byte>)

功能:根据传入参数 v 构造一个 SqlNullableVarBinary 实例。

参数:

class SqlNullableVarchar

public class SqlNullableVarchar <: SqlNullableDbType {
    public init(v: ?String)
}

功能:变长字符串,对应仓颉 String 类型,可为数据库 Null 值。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlNullableVarchar

类型:String

prop value

public mut prop value: ?String

功能:该数据的值。 类型:?String

init(?String)

public init(v: ?String)

功能:根据传入参数 v 构造一个 SqlNullableVarchar 实例。

参数:

  • v: ?String - 传入的数据。

class SqlOption

public class SqlOption

功能:预定义的 sql 选项名称和值。如果需要扩展,请不要与这些名称和值冲突。

static const ConnectionTimeout

public static const ConnectionTimeout = "connection_timeout"

功能:获取 connect 操作的超时时间,单位 ms。

类型:String

static const Database

public static const Database = "database"

功能:获取数据库名称。

类型:String

static const Driver

public static const Driver = "driver"

功能:获取数据库驱动名称,比如 postgres,opengauss。

类型:String

static const Encoding

public static const Encoding = "encoding"

功能:获取数据库字符集编码类型。

类型:String

static const FetchRows

public static const FetchRows = "fetch_rows"

功能:获取指定需要获取额外行时从数据库中提取的行数。

类型:String

static const Host

public static const Host = "host"

功能:获取数据库服务器主机名或者 IP 地址。

类型:String

static const Password

public static const Password = "password"

功能:获取连接数据库的密码。

类型:String

static const QueryTimeout

public static const QueryTimeout = "query_timeout"

功能:获取 query 操作的超时时间,单位 ms。

类型:String

static const SSLCA

public static const SSLCA = "ssl.ca"

功能:证书颁发机构( CA )证书文件的路径名。

类型:String

static const SSLCert

public static const SSLCert = "ssl.cert"

功能:客户端 SSL 公钥证书文件的路径名。

类型:String

static const SSLKey

public static const SSLKey = "ssl.key"

功能:客户端 SSL 私钥文件的路径名。

类型:String

static const SSLKeyPassword

public static const SSLKeyPassword = "ssl.key.password"

功能:客户端 SSL 私钥文件的密码。

类型:String

static const SSLMode

public static const SSLMode = "ssl.mode"

功能:获取 SSLMode 传输层加密模式。

类型:String

static const SSLModeDisabled

public static const SSLModeDisabled = "ssl.mode.disabled"

功能:建立未加密的连接。

类型:String

static const SSLModePreferred

public static const SSLModePreferred = "ssl.mode.preferred"

功能:如果服务器支持加密连接,则建立加密连接; 如果无法建立加密连接,则回退到未加密连接,这是 SSLMode 的默认值。

类型:String

static const SSLModeRequired

public static const SSLModeRequired = "ssl.mode.required"

功能:如果服务器支持加密连接,则建立加密连接。如果无法建立加密连接,则连接失败。

类型:String

static const SSLModeVerifyCA

public static const SSLModeVerifyCA = "ssl.mode.verify_ca"

功能:SSLModeVerifyCA 和 SSLModeRequired 类似,但是增加了校验服务器证书,如果校验失败,则连接失败。

类型:String

static const SSLModeVerifyFull

public static const SSLModeVerifyFull = "ssl.mode.verify_full"

功能:SSLModeVerifyFull 和 SSLModeVerifyCA 类似,但通过对照服务器发送给客户端的证书中的标识检查客户端用于连接到服务器的主机名来执行主机名身份验证。

类型:String

static const SSLSni

public static const SSLSni = "ssl.sni"

功能:客户端通过该标识在握手过程开始时试图连接到哪个主机名。

类型:String

static const Tls12Ciphersuites

public static const Tls12Ciphersuites = "tls1.2.ciphersuites"

功能:此选项指定客户端允许使用 TLSv1.2 及以下的加密连接使用哪些密码套件。 值为冒号分隔的字符串,比如 "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256:TLS_DHE_RSA_WITH_AES_128_CBC_SHA"。

类型:String

static const Tls13Ciphersuites

public static const Tls13Ciphersuites = "tls1.3.ciphersuites"

功能:此选项指定客户端允许使用 TLSv1.3 的加密连接使用哪些密码套件。 值为冒号分隔的字符串,比如 "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"。

类型:String

static const TlsVersion

public static const TlsVersion = "tls.version"

功能:支持的 TLS 版本号,值为逗号分隔的字符串,比如 "TLSv1.2,TLSv1.3"。

类型:String

static const URL

public static const URL = "url"

功能:获取数据库连接 URL 字符串。

类型:String

static const UpdateTimeout

public static const UpdateTimeout = "update_timeout"

功能:获取 update 操作的超时时间,单位 ms。

类型:String

static const Username

public static const Username = "username"

功能:获取连接数据库的用户名。

类型:String

class SqlReal

public class SqlReal <: SqlDbType {
    public init(v: Float32)
}

功能:浮点数,对应仓颉 Float32 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlReal

类型:String

prop value

public mut prop value: Float32

功能:该数据的值。

类型:Float32

init(Float32)

public init(v: Float32)

功能:根据传入参数 v 构造一个 SqlReal 实例。

参数:

class SqlSmallInt

public class SqlSmallInt <: SqlDbType {
    public init(v: Int16)
}

功能:小整数,对应仓颉 Int16 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlSmallInt

类型:String

prop value

public mut prop value: Int16

功能:该数据的值。

类型:Int16

init(Int16)

public init(v: Int16)

功能:根据传入参数 v 构造一个 SqlSmallInt 实例。

参数:

  • v: Int16 - 传入的数据。

class SqlTime

public class SqlTime <: SqlDbType {
    public init(v: DateTime)
}

功能:时间,仅时分秒毫秒有效,对应仓颉 DateTime 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlTime

类型:String

prop value

public mut prop value: DateTime

功能:该数据的值。

类型:DateTime

init(DateTime)

public init(v: DateTime)

功能:根据传入参数 v 构造一个 SqlTime 实例。

参数:

class SqlTimeTz

public class SqlTimeTz <: SqlDbType {
    public init(v: DateTime)
}

功能:带时区的时间,仅时分秒毫秒时区有效,对应仓颉 DateTime 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlTimeTz

类型:String

prop value

public mut prop value: DateTime

功能:该数据的值。

类型:DateTime

init(DateTime)

public init(v: DateTime)

功能:根据传入参数 v 构造一个 SqlTimeTz 实例。

参数:

class SqlTimestamp

public class SqlTimestamp <: SqlDbType {
    public init(v: DateTime)
}

功能:时间戳,对应仓颉 DateTime 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlTimestamp

类型:String

prop value

public mut prop value: DateTime

功能:该数据的值。

类型:DateTime

init(DateTime)

public init(v: DateTime)

功能:根据传入参数 v 构造一个 SqlTimestamp 实例。

参数:

class SqlVarBinary

public class SqlVarBinary <: SqlDbType {
    public init(v: Array<Byte>)
}

功能:变长二进制字符串,对应仓颉 Array<Byte> 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlVarBinary

类型:String

prop value

public mut prop value: Array<Byte>

功能:该数据的值。

类型:Array<Byte>

init(Array<Byte>)

public init(v: Array<Byte>)

功能:根据传入参数 v 构造一个 SqlVarBinary 实例。

参数:

class SqlVarchar

public class SqlVarchar <: SqlDbType {
    public init(v: String)
}

功能:变长字符串,对应仓颉 String 类型。

父类型:

prop name

public prop name: String

功能:类型名称,即 SqlVarchar

类型:String

prop value

public mut prop value: String

功能:该数据的值。

类型:String

init(String)

public init(v: String)

功能:根据传入参数 v 构造一个 SqlVarchar 实例。

参数:

  • v: String - 传入的数据。

枚举

enum ConnectionState

public enum ConnectionState <: Equatable<ConnectionState> {
    | Broken
    | Closed
    | Connecting
    | Connected
}

功能:描述与数据源连接的当前状态。

父类型:

Broken

Broken

功能:表示与数据源的连接已中断。只有在 Connected 之后才可能发生这种情况。

Closed

Closed

功能:表示连接对象已关闭。

Connected

Connected

功能:表示连接对象已与数据源连接上。

Connecting

Connecting

功能:表示连接对象正在与数据源连接。

operator func !=(ConnectionState)

public operator func !=(rhs: ConnectionState): Bool

功能:判断数据源连接状态是否不同。

参数:

返回值:

  • Bool - 传入数据源连接状态与当前状态相同则返回 false ,否则返回 true

operator func ==(ConnectionState)

public operator func ==(rhs: ConnectionState): Bool

功能:判断数据源连接状态是否相同。

参数:

返回值:

  • Bool - 传入数据源连接状态与当前状态相同则返回 true ,否则返回 false

enum TransactionAccessMode

public enum TransactionAccessMode <: ToString & Hashable & Equatable<TransactionAccessMode> {
    | ReadOnly
    | ReadWrite    
    | Unspecified
}

功能:事务读写模式。

父类型:

ReadOnly

ReadOnly

功能:表示只读模式。

ReadWrite

ReadWrite

功能:表示读 + 写模式。

Unspecified

Unspecified

功能:表示未指定的事务读写模式。其行为取决于具体的数据库服务器。

func hashCode()

public func hashCode(): Int64

功能:获取事务读写模式的哈希值。

返回值:

  • Int64 - 事务读写模式的哈希值。

func toString()

public func toString(): String

功能:返回事务读写模式的字符串表示。枚举值和字符串的对应关系如下表所示:

枚举值字符串
ReadOnly"Read Only"
ReadWrite"Read Write"
Unspecified"Unspecified"

返回值:

  • String - 事务读写模式的字符串。

operator func !=(TransactionAccessMode)

public operator func != (rhs: TransactionAccessMode): Bool

功能:判断两个 TransactionAccessMode 是否不相等。

参数:

返回值:

  • Bool - 如果不相等,则返回 true,否则返回 false

operator func ==(TransactionAccessMode)

public operator func == (rhs: TransactionAccessMode): Bool

功能:判断两个 TransactionAccessMode 是否相等。

参数:

返回值:

  • Bool - 如果相等,则返回 true,否则返回 false

enum TransactionDeferrableMode

public enum TransactionDeferrableMode <: ToString & Hashable & Equatable<TransactionDeferrableMode> {
    | Deferrable
    | NotDeferrable
    | Unspecified
}

功能:事务的延迟模式。

父类型:

Deferrable

Deferrable

功能:表示可延迟。

说明:

延迟事务是指在前滚阶段结束时未提交的事务,并且遇到了阻止其回滚的错误。因为事务无法回滚,所以它被推迟。

NotDeferrable

NotDeferrable

功能:表示不可延迟。

Unspecified

Unspecified

功能:未指定的事务延迟模式,其行为取决于具体的数据库服务器。

func hashCode()

public func hashCode(): Int64

功能:获取事务延迟模式的哈希值。

返回值:

  • Int64 - 事务延迟模式的哈希值。

func toString()

public func toString(): String

功能:返回事务延迟模式的字符串表示。枚举值和字符串的对应关系如下表所示:

枚举值字符串
Deferrable"Deferrable"
NotDeferrable"Not Deferrable"
Unspecified"Unspecified"

返回值:

  • String - 事务延迟模式的字符串。

operator func !=(TransactionDeferrableMode)

public operator func != (rhs: TransactionDeferrableMode): Bool

功能:判断两个 TransactionDeferrableMode 是否不相等。

参数:

返回值:

  • Bool - 如果不相等,则返回 true,否则返回 false

operator func ==(TransactionDeferrableMode)

public operator func == (rhs: TransactionDeferrableMode): Bool

功能:判断两个 TransactionDeferrableMode 是否相等。

参数:

返回值:

  • Bool - 如果相等,则返回 true,否则返回 false

enum TransactionIsoLevel

public enum TransactionIsoLevel <: ToString & Hashable & Equatable<TransactionIsoLevel> {
    | Chaos
    | Linearizable
    | ReadCommitted
    | ReadUncommitted
    | RepeatableRead
    | Serializable
    | Snapshot
    | Unspecified
}

功能:事务隔离级别。

说明:

事务隔离定义了数据库系统中,一个事务中操作的结果在何时以何种方式对其他并发事务操作可见。

父类型:

Chaos

Chaos

功能:表示无法覆盖来自隔离级别更高的事务的挂起更改。

Linearizable

Linearizable

功能:表示事务线性化。

说明:

区别于串行化(Serializable),线性化主要强调单个对象上(即 db 行或 nosql 记录)的一组单个操作(比如一系列读写操作),线性化保证这些操作严格按真实时间顺序执行。比如当您查看单个对象上的操作子集时,线性化是相关的。

ReadCommitted

ReadCommitted

功能:表示事务等待,直到其他事务写锁定的行被解锁;这将防止它读取任何“脏”数据。

ReadUncommitted

ReadUncommitted

功能:表示事务之间不隔离。

RepeatableRead

RepeatableRead

功能:表示事务可重复读。对同一字段的多次读取结果都是一致的,除非数据是被本身事务自己所修改。

Serializable

Serializable

功能:表示事务可串行化。此隔离级别下,所有事务顺序执行,因此,脏读、不可重复读、幻读都不会出现。

Snapshot

Snapshot

功能:表示快照隔离通过使用行版本控制避免了大多数锁定和阻止。

Unspecified

Unspecified

功能:未指定的事务隔离级别,其行为取决于具体的数据库服务器。

func hashCode()

public func hashCode(): Int64

功能:获取事务隔离级别的哈希值。

返回值:

  • Int64 - 事务隔离级别的哈希值。

func toString()

public func toString(): String

功能:返回事务隔离级别的字符串表示。枚举值和字符串的对应关系如下表所示:

枚举值字符串
Chaos"Chaos"
Linearizable"Linearizable"
ReadCommitted"Read Committed"
ReadUncommitted"Read Uncommitted"
RepeatableRead"Repeatable Read"
Serializable"Serializable"
Snapshot"Snapshot"
Unspecified"Unspecified"

返回值:

  • String - 事务隔离级别的字符串。

operator func !=(TransactionIsoLevel)

public operator func != (rhs: TransactionIsoLevel): Bool

功能:判断两个 TransactionIsoLevel 是否不相等。

参数:

返回值:

  • Bool - 如果不相等,则返回 true,否则返回 false

operator func ==(TransactionIsoLevel)

public operator func == (rhs: TransactionIsoLevel): Bool

功能:判断两个 TransactionIsoLevel 是否相等。

参数:

返回值:

  • Bool - 如果相等,则返回 true,否则返回 false

异常类

class SqlException

public open class SqlException <: Exception

功能:用于处理 sql 相关的异常。

父类型:

prop errorCode

public prop errorCode: Int64

功能:数据库供应商返回的整数错误代码。

类型:Int64

prop message

public override prop message: String

功能:获取异常信息字符串。

类型:String

prop sqlState

public prop sqlState: String

功能:长度为五个字符的字符串,是数据库系统返回的最后执行的 sql 语句状态。

类型:String

init()

public init()

功能:无参构造函数。

init(String)

public init(message: String)

功能:根据异常信息创建 SqlException 实例。

参数:

  • message: String - 异常信息。

init(String, String, Int64)

public init(message: String, sqlState: String, errorCode: Int64)

功能:根据异常信息、SQL语句状态、错误码信息,创建 SqlException 实例。

参数:

  • message: String - 异常信息。
  • sqlState: String - 长度为五个字符的字符串,是数据库系统返回的最后执行的 sql 语句状态。
  • errorCode: Int64 - 数据库供应商返回的整数错误代码。

实现数据库驱动查询功能示例

对于数据库驱动提供者,此处给出实现查询功能的样例代码:

import std.database.sql.*
import std.sync.*

// 实现 QueryResult 接口
public class Rows <: QueryResult {
    let closed = AtomicBool(false)
    public func close(): Unit {
        if (isClosed()) {
            return
        }
        closed.store(true)
    }
    public func isClosed(): Bool {
        closed.load()
    }
    public prop columnInfos: Array<ColumnInfo> {
        get() {
            []
        }
    }
    public func next(values: Array<SqlDbType>): Bool {
        for (idx in 0..values.size) {
            match (values[idx]) {
                case v: SqlBigInt => v.value = 100
                case v: SqlVarchar => v.value = "foo"
                case v: SqlNullableTimestamp => v.value = None
                case _ => ()
            }
        }
        return false
    }
}

获取数据库连接示例

import std.database.sql.*

main() {
    // 获取已经注册的驱动
    let drv = DriverManager.getDriver("opengauss") ?? return

    // 设置打开数据源的选项
    let opts = [
        ("cachePrepStmts", "true"),
        ("prepStmtCacheSize", "250"),
        ("prepStmtCacheSqlLimit", "2048")
    ]

    // 通过连接路径和选项打开数据源
    let ds = drv.open("opengauss://testuser:testpwd@localhost:5432/testdb", opts)

    // 设置连接选项
    ds.setOption(SqlOption.SSLMode, SqlOption.SSLModeVerifyCA)
    ds.setOption(SqlOption.SSLCA, "ca.crt")
    ds.setOption(SqlOption.SSLCert, "server.crt")
    ds.setOption(SqlOption.SSLKey, "server.key")
    ds.setOption(SqlOption.SSLKeyPassword, "key_password")
    ds.setOption(SqlOption.TlsVersion, "TLSv1.2,TLSv1.3")

    // 返回一个可用连接
    let conn = ds.connect()
}

删除表、创建表示例

import std.database.sql.*

main() {
    // 获取数据库链接示例
    let drv = DriverManager.getDriver("opengauss") ?? return
    let opts = [
        ("cachePrepStmts", "true"),
        ("prepStmtCacheSize", "250"),
        ("prepStmtCacheSqlLimit", "2048")
    ]

    let ds = drv.open("opengauss://testuser:testpwd@localhost:5432/testdb", opts)

    let conn = ds.connect()

    // 删除和创建表
    var stmt = conn.prepareStatement("DROP TABLE IF EXISTS test")
    var ur = stmt.update()
    println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")
    stmt.close()
    stmt = conn.prepareStatement("CREATE TABLE test(id SERIAL PRIMARY KEY, name VARCHAR(20) NOT NULL, age INT)")
    ur = stmt.update()
    println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")
    stmt.close()
}

执行数据库操作语句示例

插入数据

import std.database.sql.*

main() {
    // 获取数据库连接示例
    let drv = DriverManager.getDriver("opengauss") ?? return
    let ds = drv.open("opengauss://testuser:testpwd@localhost:5432/testdb", [])
    let conn = ds.connect()

    // 插入数据示例
    var stmt = conn.prepareStatement("INSERT INTO test VALUES(?, ?)")
    var name = SqlVarchar("li lei")
    var age = SqlNullableInteger(12)
    var ur = stmt.update(name, age)
    println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")
    name.value = "han meimei"
    age.value = 13
    ur = stmt.update(name, age)
    println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")

    // 如果需要在插入数据后返回插入的 id 值,可以参考如下方式:
    let sql = "INSERT INTO test (name, age) VALUES (?,?) RETURNING id, name"
    try (stmt = conn.prepareStatement(sql)) {
        var name = SqlVarchar("li hua")
        var age = SqlNullableInteger(12)
        let qr = stmt.query(name, age)
        let id = SqlInteger(0)
        while (qr.next(id, name)) {
            println("id = ${id.value}, name=${name.value}")
        }
    } catch (e: Exception) {
        e.printStackTrace()
    }
    stmt.close()
}

查询数据

import std.database.sql.*

main() {
    // 获取数据库连接示例
    let drv = DriverManager.getDriver("opengauss") ?? return
    let ds = drv.open("opengauss://testuser:testpwd@localhost:5432/testdb", [])
    let conn = ds.connect()

    // 查询操作示例
    var stmt = conn.prepareStatement("select * from test where name = ?")
    var name = SqlNullableVarchar("li lei")
    let id = SqlInteger(0)
    let qr = stmt.query(name)
    var age = SqlNullableInteger(0)
    while (qr.next(id, name, age)) {
        println("id = ${id.value}, name = ${name.value}, age=${age.value}")
    }
    stmt.close()
}

更新数据

import std.database.sql.*

main() {
    // 获取数据库连接示例
    let drv = DriverManager.getDriver("opengauss") ?? return
    let ds = drv.open("opengauss://testuser:testpwd@localhost:5432/testdb", [])
    let conn = ds.connect()

    // 更新操作示例
    var stmt = conn.prepareStatement("update test set age = ? where name = ?")
    var age = SqlNullableInteger(15)
    var name = SqlNullableVarchar("li lei")
    var ur = stmt.update(age, name)
    println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")
    stmt.close()
}

删除数据

import std.database.sql.*

main() {
    // 获取数据库连接示例
    let drv = DriverManager.getDriver("opengauss") ?? return
    let ds = drv.open("opengauss://testuser:testpwd@localhost:5432/testdb", [])
    let conn = ds.connect()

    // 删除操作示例
    var stmt = conn.prepareStatement("delete from test where name = ?")
    var name = SqlNullableVarchar("li lei")
    var ur = stmt.update(name)
    println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")
    stmt.close()
}

执行事务控制语句示例

普通数据库事务

import std.database.sql.*
import std.time.*

func test_transaction() {
    let SQL_INSERT = "INSERT INTO EMPLOYEE (NAME, SALARY, CREATED_DATE) VALUES (?, ?, ?)"
    let SQL_UPDATE = "UPDATE EMPLOYEE SET SALARY=? WHERE NAME=?"
    let drv = DriverManager.getDriver("opengauss").getOrThrow()
    let db = drv.open("opengauss://localhost:5432/testdb")
    try(cn = db.connect()) {
        let psInsert = cn.prepareStatement(SQL_INSERT)
        let psUpdate = cn.prepareStatement(SQL_UPDATE)

        // 创建事务对象
        let tx = cn.createTransaction()
        try {
            psInsert.update([SqlChar("mkyong"), SqlBinary(Array<Byte>(1, repeat: 10)), SqlTime(DateTime.now())])

            psInsert.update([SqlChar("kungfu"), SqlBinary(Array<Byte>(1, repeat: 20)), SqlTime(DateTime.now())])

            // if connnected to a DB, test rollback SQLException: No value specified for parameter 3.
            psInsert.update([SqlVarchar("mkyong"), SqlBinary(Array<Byte>(5, {i  => UInt8(i + 1)}))])

            // 提交事务
            tx.commit()

        } catch (e1: SqlException) {
            e1.printStackTrace()
            try {
                // 发生异常,回滚所有事务
                tx.rollback()
            } catch (e2: SqlException) {
                e2.printStackTrace()
            }
        }
    } catch (e: SqlException) {
        e.printStackTrace()
    }
}

事务保存点

如果数据库事务支持保存点,可以参考如下样例:

import std.database.sql.*
import std.time.*

func test_savepoint() {
    let SQL_INSERT = "INSERT INTO EMPLOYEE (NAME, SALARY, CREATED_DATE) VALUES (?, ?, ?)"
    let SQL_UPDATE = "UPDATE EMPLOYEE SET SALARY=? WHERE NAME=?"
    let drv = DriverManager.getDriver("opengauss").getOrThrow()
    let db = drv.open("opengauss://localhost:5432/testdb")
    try(cn = db.connect()) {
        let psInsert = cn.prepareStatement(SQL_INSERT)
        let psUpdate = cn.prepareStatement(SQL_UPDATE)

        let tx = cn.createTransaction()
        try {
            // 创建保存点 1
            tx.save("save1")
            psInsert.update([SqlChar("mkyong"), SqlBinary(Array<Byte>(1, repeat: 10)), SqlTime(DateTime.now())])

            // 创建保存点 2
            tx.save("save2")
            psInsert.update([SqlChar("kungfu"), SqlBinary(Array<Byte>(1, repeat: 20)), SqlTime(DateTime.now())])

            // 创建保存点 3
            tx.save("save3")
            psInsert.update([SqlVarchar("mkyong"), SqlBinary(Array<Byte>(5, {i  => UInt8(i + 1)}))])

            // 回滚到保存点 2
            tx.rollback("save2")

            // 提交事务
            tx.commit()

        } catch (e1: SqlException) {
            e1.printStackTrace()
            try {
                // 发生异常,回滚所有事务
                tx.rollback()
            } catch (e2: SqlException) {
                e2.printStackTrace()
            }
        }
    } catch (e: SqlException) {
        e.printStackTrace()
    }
}

std.deriving 包

std.deriving 提供了一种根据类、结构体和枚举类型的字段、属性等自动生成接口实现的方法。

当前支持自动生成以下接口的实现:

更多示例详见 Deriving 用户手册

API 列表

宏名功能
DeriveDerive 是一个核心宏,其仅可修饰结构体、类或枚举等声明,对被修饰的声明自动扩展接口
DeriveExcludeDeriveExclude 可为已被 @Derive 宏修饰的声明排除不需要处理的字段,字段默认被 Deriving 处理。
DeriveIncludeDeriveInclude 可为已被 @Derive 宏修饰的声明增加需要处理的属性,属性默认情况不会被 Deriving 处理。
DeriveOrderDeriveOrder 可为已被 @Derive 宏修饰的声明指定处理字段和属性的顺序,通常对 Comparable 接口有意义。

@Derive

功能:Derive 是一个核心宏,其仅可修饰结构体、类或枚举等声明,对被修饰的声明自动扩展接口

@DeriveExclude

功能:DeriveExclude 可为已被 @Derive 宏修饰的声明排除不需要处理的字段,字段默认被 Deriving 处理。

@DeriveInclude

功能:DeriveInclude 可为已被 @Derive 宏修饰的声明增加需要处理的属性,属性默认情况不会被 Deriving 处理。

@DeriveOrder

功能:DeriveOrder 可为已被 @Derive 宏修饰的声明指定处理字段和属性的顺序,通常对 Comparable 接口有意义。

Deriving

一个简单示例:

import std.deriving.*

@Derive[ToString]
class User {
    User(
        let name: String,
        let id: Int
    ) {}
}

main() {
    println(User("root", 0)) // -> "User(name = root, id = 0)"
}

@Derive[ToString] 应用于类或结构体时, Deriving 会收集和使用类或结构体的可变和不可变字段,包括在主构造函数中指定的字段,并自动实现 ToString 的方法。当 @Derive[ToString] 应用于枚举时, Deriving 将收集枚举的构造函数参数。静态字段和属性将不会被收集和使用,另外, Deriving 收集的字段不允许存在私有字段,否则将抛出编译错误。

收集到的字段用于 Deriving 时,其类型需要实现目标接口,以便将字段结果组合在一起。例如,当处理 ToString 时,生成的代码将在所有收集到的字段上调用 toString ,然后将结果与对应的字段名称连接成一个字符串。如果其中一个字段的类型不支持 ToString ,则会抛出编译错误并且 Deriving 无法完成。

注意

标记为派生的类应该是最终的:它不应该是开放的、抽象的或 sealed 的。

有些字段可能具有特殊含义,它们的值没有多大意义,则可通过在这些字段上应用 @DeriveExclude 来排除这些字段:

@Derive[ToString]
class User {
    User(let name: String) {}

    @DeriveExclude
    let lazyHashCode = 0 // it will not be printed because it's excluded
}

默认情况 Deriving 仅使能字段,对于属性则需要通过 @DeriveInclude 来显式使能:

@Derive[ToString]
class User {
    User(
        let id: Int
    ) {}

    @DeriveInclude
    prop name: String {
        get() { passwdFile.getUserName(id) }
    }
}

main() {
    println(User(0)) // -> "User(id = 0, name = root)"
}

请注意,因为属性 name 是在 id 之后声明的,因此打印的顺序为先 idname

如果需要更改打印的顺序,可以使用 @DeriveOrder

@Derive[ToString]
@DeriveOrder(name, id)
class User {
    User(
        let id: Int
    ) {}

    @DeriveInclude
    prop name: String {
        get() { passwdFile.getUserName(id) }
    }
}

main() {
    println(User(0)) // -> "User(name = root, id = 0)"
}

常见的 Deriving 语法

@Derive 宏支持以逗号分隔的接口名称列表。此外,该宏可以重复多次被调用,但所有 @Derive 宏调用都应位于声明的顶部,而其他宏(如 @DeriveOrder )应始终位于其后。

支持的接口列表的顺序没有影响。

@Derive[ToString, Hashable]
@Derive[Equatable]
@DeriveOrder[currency,price,quantity]
struct Order {}

当 Deriving 多个相交的接口时,例如,Comparable 还包括 Equatable ,则允许两者同时存在,等同于仅有范围最广的一个:

@Derive[Comparable] // does also generate Equatable

等同于:

@Derive[Comparable, Equatable]

包含和排除

默认情况下会处理所有字段,包括定义为主构造函数参数的字段。 当需要排除某个字段时,可以对其应用 @DeriveExclude

@Derive[ToString]
struct S {
    S(let id) { key = "s_${id}" }

    @DeriveExclude
    let key: String
}

默认情况下不处理属性,需要通过 @DeriveInclude 包含属性。

@Derive[ToString]
struct S {
    S(let id) {}

    @DeriveInclude
    prop key: String {
        get() { "s_${id}" }
    }
}

被 Deriving 的字段和属性都不能是 private 的。因此,private 的字段或者属性应被除外或者使其为包内可见属性。

注意

静态的字段和属性始终会被忽略,因此他们都不能被 @DeriveInclude@DeriveInclude 修饰。

支持的接口

当前仅支持如下接口:

  • ToString
  • Hashable
  • Equatable
  • Comparable

暂不支持用户自定义的接口。

变更顺序

在对由多个字段组成的复杂类型的实例进行排序和比较时,测试字段的顺序通常很重要。默认情况下,所有字段都按声明顺序考虑。可以使用 @DeriveOrder 宏修改顺序。

@Derive[Comparable, ToString]
struct Floor {
    Floor(
        let level: Int,
        let building: Int
    ) {}
}

main() {
    let floors = [
        Floor(1, 2),
        Floor(3, 2),
        Floor(2, 1)
    ]
    floors.sort()
    for (f in floors) { println(f) }
}

上述示例将打印以下内容,看起来顺序没有很大影响。

Floor(level = 1, building = 2)
Floor(level = 2, building = 1)
Floor(level = 3, building = 2)

但是当我实现 Comparable 时,不同的顺序将影响结果。

@Derive[Comparable, ToString]
@DeriveOrder[building, level]
struct Floor {
    Floor(
        let level: Int,
        let building: Int
    ) {}
}

此时,结果将首先按 building 排序,然后按 level 排序:

Floor(building = 1, level = 2)
Floor(building = 2, level = 1)
Floor(building = 2, level = 3)

泛型

实现泛型类型的接口通常需要应用约束,以便类型仅在某些条件下实现接口。例如:

class Cell<T> {
    Cell(let value: T) {}
}

此时可能希望仅当单元格的值可打印时才能够打印该单元格。为了实现它,我们将编写一个带有约束的扩展:

extend <T> Cell<T> <: ToString where T <: ToString {
    public func toString(): String {
        "Cell(value = ${value})"
    }
}

当使用 Deriving 时,它会默认尝试对所有泛型参数应用约束,因此以下内容与上面的扩展相同:

@Derive[ToString]
class Cell<T> {
    Cell(let value: T) {}
}

然而在某些情况下,默认行为并不符合期望。此时,可使用 @Derive 内部的 where 来覆盖默认约束:

interface PrintableCellValue <: ToString { ... }

@Derive[ToString where T <: PrintableCellValue]
class Cell<T> {}

请注意,在上面的示例中,自定义约束仅适用于 ToString ,因此如果需要对所有接口进行约束,则应单独为每个接口重复此动作。

@Derive[ToString where T <: PrintableCellValue]
@Derive[Hashable where T <: PrintableCellValue & Hashable]
class Cell<T> {}

性能说明

由于 Deriving 是基于仓颉宏的,不涉及任何反射,因此 Deriving 实现的运行时性能与手写相当。但是,Deriving 涉及编译时的代码转换,因此它会影响编译时间。

std.ffi.python 包

功能介绍

ffi.python 包提供仓颉与 Python 语言互操作调用的能力,以兼容强大的计算和 AI 生态。

本包为用户提供了以下能力:

  1. Python 包为用户提供了全局解释器对象 Python ,其类型为 PythonBuiltins ,通过该解释器对象可以:

    • 加载、卸载解释器资源;
    • 获取当前使用的 Python 解释器版本;
    • 导入及使用 Python 的三方模块。

    详细介绍及使用请参见《仓颉语言用户指南》(跨语言互操作/与 Python 语言互操作/PythonBuiltins 内建函数类)。

  2. Python 包提供了 Python 数据类型与仓颉类型之间的互相转换。如 PyBool/PyLong/PyFloat/PyString/PyTuple/PyList/PyDict/PySet, 它们均继承自 PyObject 类型,PyObject 类型提供了所有类型的通用接口,如成员变量访问、函数访问、到仓颉类型转换等。PyObject 类型的子类提供了每个类型独有的函数接口。

    详细映射关系介绍及使用请参见《仓颉语言用户指南》(跨语言互操作/与 Python 语言互操作/类型映射)。

  3. Python 包支持简单的函数注册及 Python 对仓颉函数调用。Python 回调仓颉代码需要通过 C 作为中间层进行调用,并且使用到了 Python 的三方库: ctypes 以及 _ctypes

    详细映射关系介绍及使用请参见《仓颉语言用户指南》(跨语言互操作/与 Python 语言互操作/仓颉与 Python 的注册回调),该章节详细介绍了在回调过程中,两边参数和返回值的类型映射情况以及调用方式。

注意:

  • 本包暂不支持 Windows 平台。

API 列表

常量&变量

变量/常量名功能
PYLOGffi.python 日志对象,用于打印控制及输出。
PythonPython 解释器全局资源。

接口

接口名功能
CjObj该接口提供将仓颉类型转换为 Python Object 的函数。
PyFFIType该接口表示支持与 Python 互操作的类型。

类型名功能
PyBool表示 Python 的布尔类型。
PyCFunc表示 Python 的 C 风格函数类型。
PyDict<K, V> where K <: Hashable & Equatable<K> & PyFFIType表示 Python 的字典类型。
PyFloat表示 Python 的浮点数类型。
PyList<T> where T <: PyFFIType表示 Python 的列表类型。
PyLong表示 Python 的整数类型。
PyObj表示 Python 所有类型的父类。
PyObjIterator表示 PyObj 的迭代器类型。
PyString表示 Python 的字符串类型。
PySet<T> where T <: Hashable & Equatable<T> & PyFFIType表示 Python 的集合类型。
PySlice<T> where T <: Countable<T> & Comparable<T> & Equatable<T> & CjObj表示 Python 的区间类型。
PyTuple表示 Python 的元组类型。
PythonLogger表示 ffi.python 包的日志类型。
PythonBuiltins表示 Python 的内建函数集合。

异常类

类型名功能
PythonException表示来自 ffi.python 包的异常类型。

常量&变量

let PYLOG

public let PYLOG: PythonLogger = PythonLogger()

功能:ffi.python 包的全局日志实例,用于该包相关日志的打印控制及输出。

通过该全局变量,可以静态访问 PythonLogger 的打印函数,用于输出不同等级的日志。详细功能可见 PythonLogger 章节。

类型:PythonLogger

let Python

public let Python: PythonBuiltins = PythonBuiltins()

功能:Python 解释器全局资源。

通过该全局变量,可以进行 Python 解释器的创建和销毁,以及 Python 的内建函数调用。详细功能可见 PythonBuiltins 章节。

类型:PythonBuiltins

接口

interface CjObj

public interface CjObj <: PyFFIType

功能:该接口提供将仓颉类型转换为 Python 类型的函数。

父类型:

interface PyFFIType

public interface PyFFIType

功能:该接口表示支持与 Python 互操作的类型。

class PyBool

public class PyBool <: PyObj

功能:该类型为 Python 语言的布尔类型,可以与仓颉的 Bool 类型互转。

该类型的详细介绍请参见《仓颉语言用户指南》(跨语言互操作/与 Python 语言互操作/类型映射/PyBoolBool 的映射)

父类型:

class PyCFunc

public class PyCFunc <: PyObj

功能:PyCFunc 为用户提供了注册仓颉的 CFunc 函数给 Python 侧,并且支持由 Python 回调 CFunc 函数的能力。

该类型的详细介绍请参见《仓颉语言用户指南》(跨语言互操作/与 Python 语言互操作/仓颉与 Python 的注册回调/PyCFunc 类原型)。

父类型:

class PyDict<K, V> where K <: Hashable & Equatable<K> & PyFFIType

public class PyDict<K, V> <: PyObj where K <: Hashable & Equatable<K> & PyFFIType

功能:该类型为 Python 语言的字典类型,可以与仓颉的 HashMap 类型互转。

该类型的详细介绍请参见《仓颉语言用户指南》(跨语言互操作/与 Python 语言互操作/类型映射/PyDictHashMap 的映射)。

父类型:

class PyFloat

public class PyFloat <: PyObj

功能:该类型为 Python 语言的浮点数类型,可以与仓颉的 Float32/Float64 类型互转。

该类型的详细介绍请参见《仓颉语言用户指南》(跨语言互操作/与 Python 语言互操作/类型映射/PyFloat 与浮点的映射)。

父类型:

class PyList<T> where T <: PyFFIType

public class PyList<T> <: PyObj where T <: PyFFIType

功能:该类型为 Python 语言的列表类型,可以与仓颉的 Array 类型互转。

该类型的详细介绍请参见《仓颉语言用户指南》跨语言互操作/与 Python 语言互操作/类型映射PyListArray 的映射)。

父类型:

class PyLong

public class PyLong <: PyObj

功能:该类型为 Python 语言的整数类型,与仓颉的 UInt8/Int8/Int16/UInt16/Int32/UInt32/Int64/UInt64 类型映射。

该类型的详细介绍请参见《仓颉语言用户指南》跨语言互操作/与 Python 语言互操作/类型映射PyLong 与整型的映射)。

父类型:

class PyObj

public open class PyObj <: ToString & PyFFIType & Hashable & Equatable<PyObj>

功能:该类型是所有支持与 Python 互操作类型的基类。

该类型的详细介绍请参见《仓颉语言用户指南》跨语言互操作/与 Python 语言互操作/类型映射PyObj 类)。

父类型:

class PyObjIterator

public class PyObjIterator <: Iterator<PyObj>

功能:该类型是 PyObj 类型的迭代器。

该类型的详细介绍请参见《仓颉语言用户指南》跨语言互操作/与 Python 语言互操作/类型映射PyObj 的迭代器类型 PyObjIterator)。

父类型:

class PySet<T> where T <: Hashable & Equatable<T> & PyFFIType

public class PySet<T> <: PyObj where T <: Hashable & Equatable<T> & PyFFIType

功能:该类型为 Python 语言的集合类型,可以与仓颉的 HashSet 类型互转。

该类型的详细介绍请参见《仓颉语言用户指南》跨语言互操作/与 Python 语言互操作/类型映射PySetHashSet 的映射)。

父类型:

class PySlice<T> where T <: Countable<T> & Comparable<T> & Equatable<T> & CjObj

public class PySlice<T> <: PyObj where T <: Countable<T> & Comparable<T> & Equatable<T> & CjObj

功能:该类型为 Python 语言的区间类型,可以与仓颉的 Range 类型互转。

该类型的详细介绍请参见《仓颉语言用户指南》跨语言互操作/与 Python 语言互操作/类型映射PySlice 类型)。

父类型:

class PyString

public class PyString <: PyObj

功能:该类型为 Python 语言的字符串类型,可以与仓颉的 PyString 类型互转。

该类型的详细介绍请参见《仓颉语言用户指南》跨语言互操作/与 Python 语言互操作/类型映射PyString 与字符、字符串的映射)。

父类型:

class PyTuple

public class PyTuple <: PyObj

功能:改类型为 Python 的元组类型。

该类型的详细介绍请参见《仓颉语言用户指南》跨语言互操作/与 Python 语言互操作/类型映射PyTuple 类型)。

父类型:

class PythonBuiltins

public class PythonBuiltins

功能:该类型为用户提供解释器创建与销毁接口以及 Python 的常用内建函数。

该类型的详细介绍请参见《仓颉语言用户指南》(跨语言互操作/与 Python 语言互操作/PythonBuiltins 内建函数类)。

class PythonLogger

public class PythonLogger <: Logger

功能:该类型为 ffi.python 包中的日志类型。

该类型的详细介绍请参见《仓颉语言用户指南》(跨语言互操作/与 Python 语言互操作/Python 的全局资源及使用/提供 Python 库日志类 PythonLogger)。 父类型:

异常类

class PythonException

public class PythonException <: Exception

功能:该类型为 ffi.python 包中的异常类型。

该类型的详细介绍请参见《仓颉语言用户指南》(跨语言互操作/与 Python 语言互操作/Python 的全局资源及使用/提供 Python 库异常类 PythonException)。 父类型:

std.format 包

功能介绍

format 包提供格式化能力,主要为将仓颉类型实例转换为格式化字符串。

本包定义了接口 Formatter,用于规定统一的格式化方法,并为 Rune、Int8 等一系列仓颉类型实现了该接口,用户也可以自行为其他类型实现该接口以获取格式化功能。

将仓颉类型转换为字符串时,可根据格式化参数规定字符串格式,如宽度、对齐方式等。(在 Formatter 接口定义的方法中,格式化参数将作为函数入参)。

格式化参数的详细语法说明如下:

format_spec := [flags][width][.precision][specifier]

flags := '-' | '+' | '#' | '0'

width := integer

precision := integer

specifier := 'b' | 'B' | 'o' | 'O' | 'x' | 'X' | 'e' | 'E' | 'g' | 'G'

参数 flags:

  • '-' 适用于 Int,UInt,Rune 和 Float,表示左对齐。

    代码如下:

    import std.format.*
    
    main() {
        var c : Int32 = -20
        print("\"${c.format("-10")}\"")
    }
    

    运行结果如下:

    "-20       "
    
  • '+' 适用于 Int,UInt 和 Float,如果数值为正数则打出 '+' 符号,如果数值为负数则忽略。

    代码如下:

    import std.format.*
    
    main() {
        var c: Int32 = 20
        print("\"${c.format("+10")}\"")
    }
    

    运行结果如下:

    "       +20"
    
  • '#' 是针对进制打印的,对于二进制打印会补充一个 '0b' 或者 '0B',对于八进制打印会补充一个 '0o' 或者 '0O',对于十六进制会补充 '0x' 或者 '0X'。

    代码如下:

    import std.format.*
    
    main() {
        var c: Int32 = 1
        print("\"${c.format("#10x")}\"")
    }
    

    运行结果如下:

    "       0x1"
    
  • '0' 适用于 Int,UInt 和 Float,在空位补充 0。

    代码如下:

    import std.format.*
    
    main() {
        var c: Int32 = -20
        print("\"${c.format("010")}\"")
    }
    

    运行结果如下:

    "-000000020"
    

参数 width 宽度:

  • 宽度为正整数,适用于 Int,UInt,Rune 和 Float,宽度前有负号则表示左对齐,没有负号则是右对齐,如果数值小于数值本身的长度,不会发生截断。 如果前缀有 +- 符号会占用一个字符位,如果前缀有 0x0o 等会占用两个字符位。

    代码如下:

    import std.format.*
    
    main() {
        var c: Int32 = 20
        println("\"${c.format("1")}\"")
        println("\"${c.format("+4")}\"")
    }
    

    运行结果如下:

    "20"
    " +20"
    

参数 precision 精度:

  • 精度为正整数,适用于 Int,UInt 和 Float。 对于浮点数表示小数点后的有效数字位数,如果不指定,那么则打印六位小数,如果小于数值本身有效数字的长度,那就四舍五入,如果大于就补全,补全的不一定是 0。

  • 对于整数类型,不指定或者指定的数字小于数值本身的长度,则无效果,如果大于数值本身的长度,则在前面补全'0'。

    代码如下:

    import std.format.*
    
    main() {
        var e: Float32 = 1234.1
        println("\"${e.format("20.20")}\"")
        var c: Int32 = -20
        println("\"${c.format("10.8")}\"")
    }
    

    运行结果如下:

    "1234.09997558593750000000"
    " -00000020"
    

参数 specifier:

  • 'b' | 'B' | 'o' | 'O' | 'x' | 'X' 适用于 Int 和 UInt 类型。

    'b' | 'B' : 表示二进制格式打印

    'o' | 'O' : 表示八进制格式打印

    'x' | 'X' : 表示十六进制格式打印

    代码如下:

    import std.format.*
    
    main() {
        var a = 20
        println("\"${a.format("b")}\"")
        println("\"${a.format("o")}\"")
        println("\"${a.format("x")}\"")
        println("\"${a.format("X")}\"")
        println("\"${a.format("#X")}\"")
    }
    

    运行结果如下:

    "10100"
    "24"
    "14"
    "14"
    "0X14"
    
  • 'e' | 'E' | 'g' | 'G' 适用于 Float 类型。

    'e' | 'E' : 科学计数法,小写和大写

    'g' | 'G' : general,用十进制或者科学计数法表示,会选择精简的表示方式进行打印

    代码如下:

    import std.format.*
    
    main() {
        var f: Float32 = 1234.1
        var c: Float32 = 123412341234.1
        println("\"${f.format("20.2e")}\"")
        println("\"${f.format("20G")}\"")
        println("\"${c.format("20G")}\"")
        println("\"${f.format("20")}\"")
        println("\"${c.format("20")}\"")
    }
    

    运行结果如下:

    "            1.23e+03"
    "              1234.1"
    "         1.23412E+11"
    "         1234.099976"
    " 123412340736.000000"
    

API 列表

接口

接口名功能
Formatter该接口定义了格式化函数,即根据格式化参数将指定类型实例转换为对应格式的字符串。

接口

interface Formatter

public interface Formatter {
    func format(fmt: String): String
}

功能:该接口定义了格式化函数,即根据格式化参数将指定类型实例转换为对应格式的字符串。

格式化参数相关的说明详见 format 包中功能介绍一节。

其他类型可通过实现该接口提供格式化功能。

func format(String)

func format(fmt: String): String

功能:根据格式化参数将当前实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前实例格式化后得到的字符串。

extend Float16 <: Formatter

extend Float16 <: Formatter

功能:为 Float16 扩展 Formatter 接口,以实现将 Float16 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 Float16 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 Float16 类型实例格式化后得到的字符串。

异常:

extend Float32 <: Formatter

extend Float32 <: Formatter

功能:为 Float32 扩展 Formatter 接口,以实现将 Float32 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 Float32 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 Float32 类型实例格式化后得到的字符串。

异常:

extend Float64 <: Formatter

extend Float64 <: Formatter

功能:为 Float64 扩展 Formatter 接口,以实现将 Float64 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 Float64 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 Float64 类型实例格式化后得到的字符串。

异常:

extend Int16 <: Formatter

extend Int16 <: Formatter

功能:为 Int16 扩展 Formatter 接口,以实现将 Int16 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 Int16 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 Int16 类型实例格式化后得到的字符串。

异常:

extend Int32 <: Formatter

extend Int32 <: Formatter

功能:为 Int32 扩展 Formatter 接口,以实现将 Int32 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 Int32 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 Int32 类型实例格式化后得到的字符串。

异常:

extend Int64 <: Formatter

extend Int64 <: Formatter

功能:为 Int64 扩展 Formatter 接口,以实现将 Int64 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 Int64 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 Int64 类型实例格式化后得到的字符串。

异常:

extend Int8 <: Formatter

extend Int8 <: Formatter

功能:为 Int8 扩展 Formatter 接口,以实现将 Int8 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 Int8 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 Int8 类型实例格式化后得到的字符串。

异常:

extend Rune <: Formatter

extend Rune <: Formatter

功能:为 Rune 扩展 Formatter 接口,以实现将 Rune 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 Rune 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 Rune 类型实例格式化后得到的字符串。

异常:

extend UInt16 <: Formatter

extend UInt16 <: Formatter

功能:为 UInt16 扩展 Formatter 接口,以实现将 UInt16 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 UInt16 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 UInt16 类型实例格式化后得到的字符串。

异常:

extend UInt32 <: Formatter

extend UInt32 <: Formatter

功能:为 UInt32 扩展 Formatter 接口,以实现将 UInt32 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 UInt32 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 UInt32 类型实例格式化后得到的字符串。

异常:

extend UInt64 <: Formatter

extend UInt64 <: Formatter

功能:为 UInt64 扩展 Formatter 接口,以实现将 UInt64 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 UInt64 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 UInt64 类型实例格式化后得到的字符串。

异常:

extend UInt8 <: Formatter

extend UInt8 <: Formatter

功能:为 UInt8 扩展 Formatter 接口,以实现将 UInt8 实例转换为格式化字符串。

父类型:

func format(String)

public func format(fmt: String): String

功能:根据格式化参数将当前 UInt8 类型实例格式化为对应格式的字符串。

参数:

  • fmt: String - 格式化参数。

返回值:

  • String - 将当前 UInt8 类型实例格式化后得到的字符串。

异常:

format 使用示例

格式化整型

下面是格式化整型示例。

代码如下:

import std.format.*

main(): Int64 {
    var a: Int32 = -20
    var res1 = a.format("-10")
    var res2 = a.format("+10")
    var res3 = (-20).format("10")
    var res4 = a.format("-")
    println("\"${res1}\"")
    println("\"${res2}\"")
    println("\"${res3}\"")
    println("\"${res4}\"")
    return 0
}

运行结果如下:

"-20       "
"       -20"
"       -20"
"-20"

格式化浮点型

下面是格式化浮点型示例。

代码如下:

 import std.format.*

/* flags '-' */
main(): Int64 {
    var a: Float16 = -0.34
    var b: Float32 = .34
    var c: Float64 = 3_0.3__4_
    var d: Float64 = 20.00
    /* left  align */
    var res1 = a.format("-20")
    /* right align */
    var res2 = b.format("+20")
    /* left  align */
    var res3 = c.format("10")
    /* left  align */
    var res4 = d.format("-10")
    /* left  align */
    var res5 = d.format("-")
    println("\"${res1}\"")
    println("\"${res2}\"")
    println("\"${res3}\"")
    println("\"${res4}\"")
    println("\"${res5}\"")
    return 0
}

运行结果如下:

"-0.340088           "
"           +0.340000"
" 30.340000"
"20.000000 "
"20.000000"

格式化字符型

下面是格式化字符型示例。

代码如下:

import std.format.*

main(): Int64 {
    var a: Rune = 'a'
    var b: Rune = '-'
    /* left  align */
    var res1 = a.format("-10")
    /* right  align */
    var res2 = b.format("-10")
    /* left  align */
    var res3 = a.format("10")
    /* left  align */
    var res4 = b.format("10")
    println("\"${res1}\"")
    println("\"${res2}\"")
    println("\"${res3}\"")
    println("\"${res4}\"")
    return 0
}

运行结果如下:

"a         "
"-         "
"         a"
"         -"

std.fs 包

功能介绍

fs(file system)包提供对文件、文件夹、路径、文件元数据信息的一些操作函数。

目前支持 Linux,macOS 和 Windows 平台下使用。

API 列表

函数

函数名功能
canonicalize(Path)Path 实例规范化,获取绝对路径形式的规范化路径。
canonicalize(String)用 path 字符串构造 Path 实例,并进行规范化,获取绝对路径形式的规范化路径。
copy(Path, Path, Bool)实现文件系统的拷贝功能,用于于复制文件或目录。
copy(String, String, Bool)实现文件系统的拷贝功能,用于于复制文件或目录。
exists(Path)判断目标地址是否存在。
exists(String)判断目标地址是否存在。
rename(Path, Path, Bool)重命名文件。
rename(String, String, Bool)重命名文件。
remove(Path, Bool)删除文件或目录。
remove(String, Bool)删除文件或目录。
removeIfExists(Path, Bool)判断目标是否存在,如果存在则删除。
removeIfExists(String, Bool)判断目标是否存在,如果存在则删除。

类名功能
Directory对应文件系统中的目录,它提供创建、查询属性以及遍历目录等能力。
File提供一些对文件进行操作的函数,包括文件的打开、创建、关闭、文件的流式读写操作、查询属性以及一些其他函数。
HardLink提供处理文件系统硬链接相关接口。
SymbolicLink提供处理文件系统符号链接相关接口。

枚举

枚举名功能
OpenOption表示不同的文件打开选项。

结构体

结构体名功能
FileDescriptor用于获取文件句柄信息。
FileInfo对应文件系统中的文件元数据,提供一些文件属性的查询和设置等函数。
Path提供路径相关的函数。

异常类

异常类名功能
FSException文件流异常类,继承了 IO 流异常类。

函数

func canonicalize(Path)

public func canonicalize(path: Path): Path

功能:将 Path 实例规范化,获取绝对路径形式的规范化路径。

所有的中间引用和软链接都会处理(UNC 路径下的软链接无法被规范化),例如,对于路径 "/foo/test/../test/bar.txt",该函数会返回 "/foo/test/bar.txt"。

参数:

  • path: Path - 待规范化的 Path 实例。

返回值:

异常:

func canonicalize(String)

public func canonicalize(path: String): Path

功能:用 path 字符串构造 Path 实例,并进行规范化,获取绝对路径形式的规范化路径。

所有的中间引用和软链接都会处理 (UNC 路径下的软链接无法被规范化),例如,对于路径 "/foo/test/../test/bar.txt",该函数会返回 "/foo/test/bar.txt"。

参数:

  • path: String - 待规范化的路径字符串。

返回值:

异常:

func copy(Path, Path, Bool)

public func copy(sourcePath: Path, to!: Path, overwrite!: Bool = false): Unit

功能:实现文件系统的拷贝功能,用于复制文件或目录。

当目标位置存在且 overwritetrue 时,该函数要求 sourcePath 的类型与 to 的类型一致,比如,sourcePath 的类型是 Directoryto 的类型也应该是 Directory,否则函数会抛出异常 FSException。当前支持的文件类型有文件夹(Directory),常规文件(Regular file),符号链接(SymbolicLink)。

参数:

  • sourcePath: Path - 待拷贝的文件地址。
  • to!: Path - 目标地址。
  • overwrite!: Bool - 是否覆盖目标地址,默认值为 false

异常:

  • FSException - 如果源文件类型和目标文件类型不一致会抛出异常,或者 overwritefalse 并且目标地址存在时抛出异常。
  • IllegalArgumentException - 路径为空,或包含字符串结束符时抛出异常。

func copy(String, String, Bool)

public func copy(sourcePath: String, to!: String, overwrite!: Bool = false): Unit

功能:实现文件系统的拷贝功能,用于复制文件或目录。

当目标位置存在且 overwritetrue 时,该函数要求 sourcePath 的类型与 to 的类型一致,比如,sourcePath 的类型是 Directoryto 的类型也应该是 Directory,否则函数会抛出异常 FSException。当前支持的文件类型有文件夹(Directory),常规文件(Regular file),符号链接(SymbolicLink)。

参数:

  • sourcePath: String - 待拷贝的文件地址。
  • to!: String - 目标地址。
  • overwrite!: Bool - 是否覆盖目标地址,默认值为 false

异常:

  • FSException - 如果源文件类型和目标文件类型不一致会抛出异常,或者 overwritefalse 并且目标地址存在时抛出异常。
  • IllegalArgumentException - 路径为空,或包含字符串结束符时抛出异常。

func exists(Path)

public func exists(path: Path): Bool

功能:判断目标地址是否存在。

参数:

  • path: Path - 待判断的目标地址。

返回值:

  • Bool - 目标地址是否存在。

异常:

func exists(String)

public func exists(path: String): Bool

功能:判断目标地址是否存在。

参数:

  • path: String - 待判断的目标地址。

返回值:

  • Bool - 目标地址是否存在。

异常:

func rename(Path, Path, Bool)

public func rename(sourcePath: Path, to!: Path, overwrite!: Bool = false): Unit

功能:将 sourcePath 指定的文件或者目录重命名为由 to 给定的名称,sourcePath 必须是现有文件或者目录的路径,如果 to 是现有文件或者目录的路径时,其具体行为由 overwrite 指定, 如果 overwritetrue,将会删除现有的文件或者目录,再执行重命名操作,否则会抛出异常。

注意

overwritetrue时,rename的一个隐含行为是删除目标位置的原有文件或者目录,如果目标位置是目录,将会递归删除目录内的所有内容,需要谨慎使用。

参数:

  • sourcePath: Path - 待重命名的地址。
  • to!: Path - 目标地址。
  • overwrite!: Bool - 是否覆盖目标地址,默认值为 false

异常:

func rename(String, String, Bool)

public func rename(sourcePath: String, to!: String, overwrite!: Bool = false): Unit

功能:将 sourcePath 指定的文件或者目录重命名为由 to 给定的名称,sourcePath 必须是现有文件或者目录的路径,如果 to 是现有文件或者目录的路径时,其具体行为由 overwrite 指定, 如果 overwritetrue,将会删除现有的文件或者目录,再执行重命名操作,overwritefalse 会抛出异常。

注意

overwritetrue时,rename的一个隐含行为是删除目标位置的原有文件或者目录,如果目标位置是目录,将会递归删除目录内的所有内容,需要谨慎使用。

参数:

  • sourcePath: String - 待重命名的地址。
  • to!: String - 目标地址。
  • overwrite!: Bool - 是否覆盖目标地址,默认值为 false

异常:

func remove(Path, Bool)

public func remove(path: Path, recursive!: Bool = false): Unit

功能:删除文件或目录。

当目标是文件夹时,可选择是否递归删除文件夹。

参数:

  • path: Path - 目标路径。
  • recursive!: Bool - 是否递归删除文件夹,默认值为 false

异常:

func remove(String, Bool)

public func remove(path: String, recursive!: Bool = false): Unit

功能:删除文件或目录。

当目标是文件夹时,可选择是否递归删除文件夹。

参数:

  • path: String - 目标路径。
  • recursive!: Bool - 是否递归删除文件夹,默认值为 false

异常:

func removeIfExists(Path, Bool)

public func removeIfExists(path: Path, recursive!: Bool = false): Bool

功能:判断目标是否存在,如果存在则执行remove方法,并返回 true

参数:

  • path: Path - 目标路径。
  • recursive!: Bool - 是否递归删除文件夹,默认值为 false

返回值:

  • Bool - 目标地址是否存在。

异常:

func removeIfExists(String, Bool)

public func removeIfExists(path: String, recursive!: Bool = false): Bool

功能:判断目标是否存在,如果存在则执行remove方法,并返回 true

参数:

  • path: String - 目标路径。
  • recursive!: Bool - 是否递归删除文件夹,默认值为 false

返回值:

  • Bool - 目标地址是否存在。

异常:

class Directory

public class Directory <: Iterable<FileInfo> {
    public init(path: Path)
    public init(path: String)
}

功能:对应文件系统中的目录,它提供创建、移动、复制、删除、查询属性以及遍历目录等能力。

说明:

非法路径指的是以下情况之一:

  • 路径中包含非法字符,例如空格、制表符、换行符等;
  • 路径中包含不合法的字符,例如特殊字符、控制字符等;
  • 路径中包含不存在的目录或文件;
  • 路径中包含无法访问的目录或文件,例如权限不足或被锁定等。

在输入路径时,应该避免使用非法字符,确保路径的合法性,以便正确地访问目标文件或目录。

父类型:

prop info

public prop info: FileInfo

功能:当前目录元数据信息。

类型:FileInfo

init(Path)

public init(path: Path)

功能:创建 Directory 实例。

参数:

  • path: Path - Path 形式的目录路径。

异常:

init(String)

public init(path: String)

功能:创建 Directory 实例,支持绝对路径和相对路径,路径非法抛异常。

参数:

  • path: String - 字符串形式的目录路径。

异常:

static func create(Path, Bool)

public static func create(path: Path, recursive!: Bool = false): Directory

功能:创建目录。

可指定是否递归创建,如果需要递归创建,将逐级创建路径中不存在的目录。

参数:

  • path: Path - 待创建的目录路径。
  • recursive!: Bool - 是否递归创建目录,true 代表递归创建,false 代表不递归创建,默认 false。

返回值:

异常:

  • FSException - 目录已存在时,抛出异常;非递归时中间有不存在的目录时抛出异常。
  • IllegalArgumentException - 目录为空、目录为当前目录、目录为根目录,或目录中存在空字符时抛出异常。

static func create(String, Bool)

public static func create(path: String, recursive!: Bool = false): Directory

功能:创建目录。

可指定是否递归创建,如果需要递归创建,将逐级创建路径中不存在的目录。

参数:

  • path: String - 待创建的目录路径。
  • recursive!: Bool - 是否递归创建目录,true 代表递归创建,false 代表不递归创建,默认 false。

返回值:

异常:

  • FSException - 目录已存在时,抛出异常;非递归时中间有不存在的目录时抛出异常。
  • IllegalArgumentException - 目录为空、目录为当前目录、目录为根目录,或目录中存在空字符时抛出异常。

static func createTemp(Path)

public static func createTemp(directoryPath: Path): Directory

功能:在指定目录下创建临时目录。

参数:

  • directoryPath: Path - Path 形式的目录路径。

返回值:

异常:

static func createTemp(String)

public static func createTemp(directoryPath: String): Directory

功能:在指定目录下创建临时目录。

参数:

  • directoryPath: String - 字符串形式的目录路径。

返回值:

异常:

func createFile(String)

public func createFile(name: String): File

功能:在当前 Directory 下创建指定名字的子文件。

参数:

  • name: String - 子文件名,参数只接受不带路径前缀的字符串。

返回值:

  • File - 子文件的 File 实例,该实例需要手动及时调用 close 函数关闭文件。

异常:

func createSubDirectory(String)

public func createSubDirectory(name: String): Directory

功能:在当前 Directory 下创建指定名字的子目录。

参数:

  • name: String - 子目录名,参数只接受不带路径前缀的字符串。

返回值:

异常:

  • FSException - 当子目录名中含有路径信息、路径已存在或创建目录失败时,抛出异常。
  • IllegalArgumentException - 当目录名中含有空字符时,抛出异常。

func directories()

public func directories(): Iterator<FileInfo>

功能:返回当前目录的子目录迭代器。

返回值:

返回值:目录是否为空,true 为空,false 不为空。

异常:

  • FSException - 获取目录的成员信息失败时,抛出异常。

func directoryList()

public func directoryList(): ArrayList<FileInfo>

功能:返回当前目录的子目录列表。

返回值:

异常:

  • FSException - 获取目录的成员信息失败时,抛出异常。

func entryList()

public func entryList(): ArrayList<FileInfo>

功能:返回当前目录的文件或子目录列表。

返回值:

异常:

  • FSException - 获取目录的成员信息失败时,抛出异常。

func fileList()

public func fileList(): ArrayList<FileInfo>

功能:返回当前目录的子文件列表。

返回值:

异常:

  • FSException - 获取目录的成员信息失败时,抛出异常。

func files()

public func files(): Iterator<FileInfo>

功能:返回当前目录的子文件迭代器。

返回值:

异常:

  • FSException - 获取目录的成员信息失败时,抛出异常。

func isEmpty()

public func isEmpty(): Bool

功能:判断当前目录是否为空。

返回值:

  • Bool - 为 true 时目录为空,为 false 时不为空。

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。

func iterator()

public func iterator(): Iterator<FileInfo>

功能:返回当前目录的文件或子目录迭代器。

返回值:

异常:

  • FSException - 获取目录的成员信息失败时,抛出异常。

class File

public class File <: Resource & IOStream & Seekable {
    public init(path: Path, openOption: OpenOption)
    public init(path: String, openOption: OpenOption)
}

功能:提供一些对文件进行操作的函数,包括文件的打开、创建、关闭、移动、复制、删除,文件的流式读写操作,查询属性以及一些其他函数。

说明:

非法路径指的是以下情况之一:

  • 路径中包含非法字符,例如空格、制表符、换行符等;
  • 路径中包含不合法的字符,例如特殊字符、控制字符等;
  • 路径中包含不存在的目录或文件;
  • 路径中包含无法访问的目录或文件,例如权限不足或被锁定等。

在输入路径时,应该避免使用非法字符,确保路径的合法性,以便正确地访问目标文件或目录。

注意:

  • 创建的 File 对象会默认打开对应的文件,当使用结束后需要及时调用 close 函数关闭文件,否则会造成资源泄露。

父类型:

prop fileDescriptor

public prop fileDescriptor: FileDescriptor

功能:获取文件描述符信息。

类型:FileDescriptor

prop info

public prop info: FileInfo

功能:获取文件元数据信息。

类型:FileInfo

prop length

public prop length: Int64

功能:获取文件头至文件尾的数据字节数。

类型:Int64

prop position

public prop position: Int64

功能:获取文件当前光标位置。

类型:Int64

prop remainLength

public prop remainLength: Int64

功能:获取文件当前光标位置至文件尾的数据字节数。

类型:Int64

init(Path, OpenOption)

public init(path: Path, openOption: OpenOption)

功能:创建一个 File 对象。

需指定文件路径和文件打开方式(读写权限),路径支持相对路径和绝对路径。

参数:

  • path: Path - 文件路径。
  • openOption: OpenOption - 文件打开选项。

异常:

  • FSException - 如果创建操作时文件已存在、进行操作时文件不存在、文件的父目录不存在,或其他原因导致无法打开文件,则抛异常。
  • IllegalArgumentException - 如果 path 为空路径或者 path 路径中包含空字符,则抛出异常。

init(String, OpenOption)

public init(path: String, openOption: OpenOption)

功能:创建 File 对象。

需指定文件路径和文件打开方式(读写权限),路径支持相对路径和绝对路径。

参数:

  • path: String - 文件路径字符串。
  • openOption: OpenOption - 文件打开选项。

异常:

  • FSException - 如果创建操作时文件已存在、进行操作时文件不存在、文件的父目录不存在,或其他原因导致无法打开文件,则抛异常。
  • IllegalArgumentException - 如果 path 是空字符串或者 path 包含空字符,则抛出异常。

static func create(Path)

public static func create(path: Path): File

功能:以只写模式创建指定路径的文件。

参数:

  • path: Path - 文件路径。

返回值:

异常:

  • FSException - 如果路径指向的文件的上级目录不存在或文件已存在,则抛出异常。
  • IllegalArgumentException - 如果文件路径为空或包含空字符,则抛出异常。

static func create(String)

public static func create(path: String): File

功能:以只写模式创建指定路径的文件。

参数:

  • path: String - 文件路径字符串。

返回值:

异常:

  • FSException - 如果路径指向的文件的上级目录不存在或文件已存在,则抛出异常。
  • IllegalArgumentException - 如果文件路径为空字符串或包含空字符,则抛出异常。

static func createTemp(Path)

public static func createTemp(directoryPath: Path): File

功能:在指定目录下创建临时文件。

创建的文件名称是 tmpFileXXXXXX 形式,不使用的临时文件应手动删除。

参数:

  • directoryPath: Path - 目录路径。

返回值:

异常:

static func createTemp(String)

public static func createTemp(directoryPath: String): File

功能:在指定目录下创建临时文件。

创建的文件名称是 tmpFileXXXXXX 形式,不使用的临时文件应手动删除。

参数:

  • directoryPath: String - 目录路径字符串。

返回值:

异常:

static func openRead(Path)

public static func openRead(path: Path): File

功能:以只读模式打开指定路径的文件。

参数:

  • path: Path - 文件路径。

返回值:

  • File - File 实例,该实例需要手动及时调用 close 函数关闭文件。

异常:

static func openRead(String)

public static func openRead(path: String): File

功能:以只读模式打开指定路径的文件。

参数:

  • path: String - 文件路径字符串。

返回值:

  • File - File 实例,该实例需要手动及时调用 close 函数关闭文件。

异常:

static func readFrom(Path)

public static func readFrom(path: Path): Array<Byte>

功能:根据指定路径读取文件全部内容,以字节数组的形式返回其内容。

参数:

  • path: Path - 文件路径。

返回值:

  • Array<Byte> - 字节数组形式的文件全部内容。

异常:

static func readFrom(String)

public static func readFrom(path: String): Array<Byte>

功能:根据指定路径读取文件全部内容,以字节数组的形式返回其内容。

参数:

  • path: String - 文件路径字符串。

返回值:

  • Array<Byte> - 字节数组形式的文件全部内容。

异常:

  • FSException - 文件读取失败、文件关闭失败、文件路径为空、文件不可读,则抛出异常。
  • IllegalArgumentException - 文件路径包含空字符则抛出异常。

static func writeTo(Path, Array<Byte>, OpenOption)

public static func writeTo(path: Path, buffer: Array<Byte>, openOption!: OpenOption = CreateOrAppend): Unit

功能:按照 openOption 打开指定路径的文件并将 buffer 写入。

参数:

  • path: Path - 文件路径。
  • buffer: Array<Byte> - 待写入的 bytes。
  • openOption!: OpenOption - 文件打开选项,默认为 CreateOrAppend。

异常:

static func writeTo(String, Array<Byte>, OpenOption)

public static func writeTo(path: String, buffer: Array<Byte>, openOption!: OpenOption = CreateOrAppend): Unit

功能:按照 openOption 打开指定路径的文件并将 buffer 写入。

参数:

  • path: String - 文件路径字符串。
  • buffer: Array<Byte> - 待写入的 bytes。
  • openOption!: OpenOption - 文件打开选项,默认为 CreateOrAppend。

异常:

func canRead()

public func canRead(): Bool

功能:判断当前 File 对象是否可读。

该函数返回值由创建文件对象的 openOption 所决定,文件对象关闭后返回 false。

返回值:

  • Bool - 返回 true 表示可读,返回 false 表示不可读或文件对象已关闭。

func canWrite()

public func canWrite(): Bool

功能:判断当前 File 对象是否可写。

该函数返回值由创建文件对象的 openOption 所决定,文件对象关闭后返回 false。

返回值:

  • Bool - 返回 true 表示可写,false 表示不可写或文件对象已关闭。

func close()

public func close(): Unit

功能:关闭当前 File 对象。

异常:

func flush()

public func flush(): Unit

功能:将缓冲区数据写入流。由于 File 不存在缓冲区,所以该函数没有具体作用。

func isClosed()

public func isClosed(): Bool

功能:判断当前 File 对象是否已关闭。

返回值:

  • Bool - true 表示已关闭,false 表示未关闭。

func read(Array<Byte>)

public func read(buffer: Array<Byte>): Int64

功能:从文件中读出数据到 buffer 中。

参数:

  • buffer: Array<Byte> - 读取数据存放的缓冲区。

返回值:

  • Int64 - 读取成功,返回读取字节数,如果文件被读完,返回 0。

异常:

func seek(SeekPosition)

public func seek(sp: SeekPosition): Int64

功能:将光标跳转到指定位置。

指定的位置不能位于文件头部之前,指定位置可以超过文件末尾,但指定位置到文件头部的最大偏移量不能超过当前文件系统允许的最大值,这个最大值接近当前文件系统的所允许的最大文件大小,一般为最大文件大小减去 4096 个字节。

参数:

返回值:

  • Int64 - 返回文件头部到跳转后位置的偏移量(以字节为单位)。

异常:

  • FSException - 指定位置不满足以上情况时,或文件不能 seek 时均会抛异常。

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能:将 buffer 中的数据写入到文件中。

参数:

  • buffer: Array<Byte> - 待写入数据的缓冲区,若 buffer 为空则直接返回。

异常:

  • FSException - 如果写入失败、只写入了部分数据、文件已关闭或文件不可写则抛出异常。
public class HardLink

功能: 提供处理文件系统硬链接相关接口。

static func create(Path, Path)

public static func create(link: Path, to!: Path): Unit

功能:创建一个新的硬链接到现有路径。如果新的路径存在,则不会覆盖。

参数:

  • link: Path - 新路径的名称。
  • to!: Path - 现有路径的名称。

异常:

static func create(String, String)

public static func create(link: String, to!: String): Unit

功能:创建一个新的硬链接到现有路径。如果新的路径存在,则不会覆盖。

参数:

  • link: String - 新路径的名称。
  • to!: String - 现有路径的名称。

异常:

public class SymbolicLink

功能: 提供处理文件系统符号链接相关接口。

static func create(Path, Path)

public static func create(link: Path, to!: Path): Unit

功能:创建一个新的符号链接到现有路径。

参数:

  • link: Path - 待创建的符号链接。
  • to!: Path - 待创建的符号链接的目标的路径。

异常:

static func create(String, String)

public static func create(link: String, to!: String): Unit

功能:创建一个新的符号链接到现有路径。

参数:

  • link: String - 待创建的符号链接。
  • to!: String - 待创建的符号链接的目标的路径。

异常:

static func readFrom(Path, Bool)

public static func readFrom(path: Path, recursive!: Bool = false): Path

功能:获取指定符号链接的目标。当指定 'recursive' 为 'true' 时,表示跟踪指向最终目标的链接,并且返回目标的全路径,当指定 'recursive' 为 'false' 时,读取当前目标链接并且返回。

参数:

  • path: Path - 符号链接的地址。
  • recursive!: Bool - 是否递归读取目标地址,默认为 'false'。

返回值:

  • Path - 符号链接的目标地址。

异常:

static func readFrom(String, Bool)

public static func readFrom(path: String, recursive!: Bool = false): Path

功能:获取指定符号链接的目标。当指定 'recursive' 为 'true' 时,表示跟踪指向最终目标的链接,并且返回目标的全路径,当指定 'recursive' 为 'false' 时,读取当前目标链接并且返回。

参数:

  • path: String - 符号链接的地址。
  • recursive!: Bool - 是否递归读取目标地址,默认为 'false'。

返回值:

  • Path - 符号链接的目标地址。

异常:

枚举

enum OpenOption

public enum OpenOption {
    | Append
    | Create(Bool)
    | CreateOrAppend
    | CreateOrTruncate(Bool)
    | Open(Bool, Bool)
    | Truncate(Bool)
}

功能:表示不同的文件打开选项。

Append

Append

功能:构造一个 OpenOption 实例,指定文件系统应打开现有文件并查找到文件尾,用这个选项创建的 File 默认只具有 Write 权限,试图查找文件尾之前的位置时会引发 FSException 异常,并且任何试图读取的操作都会失败并引发 FSException 异常。如果文件不存在,则将引发 FSException 异常。

Create(Bool)

Create(Bool)

功能:构造一个 OpenOption 实例,指定文件系统应创建新文件,用这个选项创建的 File 默认具有 Write 权限,可以通过参数指定是否具有 Read 权限。如果文件已存在,则将引发 FSException 异常。

CreateOrAppend

CreateOrAppend

功能:构造一个 OpenOption 实例,指定文件系统应打开文件(如果文件存在),否则,应创建新文件。用这个选项创建的 File 默认只具有 Write 权限,并且试图查找文件尾之前的位置时会引发 FSException 异常。分为两种情况:如果文件不存在,则使用 Create;否则使用 Append。

CreateOrTruncate(Bool)

CreateOrTruncate(Bool)

功能:构造一个 OpenOption 实例,指定文件系统应创建新文件,如果此文件已存在,则会将其覆盖。用这个选项创建的 File 默认具有 Write 权限,可以通过参数指定是否具有 Read 权限。分为两种情况:如果文件不存在,则使用 Create;否则使用 Truncate。

Open(Bool, Bool)

Open(Bool, Bool)

功能:构造一个 OpenOption 实例,指定文件系统应打开现有文件,第一个参数指定文件是否具有 Read 权限,第二个参数指定文件是否具有 Write 权限。如果文件不存在,则将引发 FSException 异常。

Truncate(Bool)

Truncate(Bool)

功能:构造一个 OpenOption 实例,指定文件系统应打开现有文件,该文件被打开时,将被截断为零字节大小。用这个选项创建的 File 默认具有 Write 权限,可以通过参数指定是否具有 Read 权限。如果文件不存在,则将引发 FSException 异常。

结构体

struct FileDescriptor

public struct FileDescriptor

功能:用于获取文件句柄信息。

说明:

文件句柄(File Handle)是操作系统为了跟踪文件而分配的一种数据结构,用于标识一个打开文件的实例。文件句柄包含了文件的元数据信息(如文件名、路径、大小、修改时间等)以及文件数据在磁盘上的物理位置等信息。 在不同的操作系统中,文件句柄的形式可能会有所不同。在 Unix 和 Linux 系统中,文件句柄通常是一个非负整数,由操作系统内核分配,并在打开文件时返回给应用程序。在 Windows 系统中,文件句柄通常是一个指向文件对象的指针,由操作系统内核分配,并在打开文件时返回给应用程序。无论文件句柄的形式是什么,应用程序都可以使用它来执行文件的读取、写入、修改等操作。

prop fileHandle

public prop fileHandle: CPointer<Unit>

功能:Windows 下获取文件句柄信息。

类型:CPointer<Unit>

prop fileHandle

public prop fileHandle: Int32

功能:Linux 下获取文件句柄信息。

类型:Int32

struct FileInfo

public struct FileInfo <: Equatable<FileInfo> {
    public init(path: Path)
    public init(path: String)
}

功能:对应文件系统中的文件元数据。

说明:

文件元数据是指文件系统中与文件相关的信息,包括文件名、文件大小、创建时间、修改时间、访问时间、文件权限、文件所有者等。

FileInfo 的底层实现是没有直接缓存文件属性的,每次通过 FileInfo 的 API 都是现场获取的最新的文件属性。

因此这里有需要注意的情况,对于创建的同一 FileInfo 实例,如果在两次获取其文件属性操作期间,对应的文件实体可能会被其他用户或进程做了修改或者替换等不期望的操作,就会导致后一次获取的可能不是期望的文件属性。 如果有特殊文件操作需求需要避免上述情况的产生,可以采用设置文件权限或者给关键文件操作加锁的方式来保证。

父类型:

prop creationTime

public prop creationTime: DateTime

功能:获取创建时间。

类型:DateTime

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。

prop lastAccessTime

public prop lastAccessTime: DateTime

功能:获取最后访问时间。

类型:DateTime

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。

prop lastModificationTime

public prop lastModificationTime: DateTime

功能:获取最后修改时间。

类型:DateTime

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。

prop name

public prop name: String

功能:获取当前实例对应的文件名或目录名。

该属性与 this.path.fileName 等价,路径解析规则详见 Path 结构体的 fileName 属性。

类型:String

prop parentDirectory

public prop parentDirectory: Option<FileInfo>

功能:获得父级目录元数据,以 Option<FileInfo> 形式返回,有父级返回 Option<FileInfo>.Some(v);否则返回 Option<FileInfo>.None。

类型:Option<FileInfo>

prop path

public prop path: Path

功能:获得当前文件路径,以 Path 形式返回。

类型:Path

prop size

public prop size: Int64

功能:返回当前文件大小。

  • 当前是文件时,表示单个文件占用磁盘空间的大小。
  • 当前是目录时,表示当前目录的所有文件占用磁盘空间的大小。

类型:Int64

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。

init(Path)

public init(path: Path)

功能:创建 FileInfo 实例。

参数:

  • path: Path - Path 形式的目录路径。

异常:

init(String)

public init(path: String)

功能:创建 FileInfo 实例。

参数:

异常:

func canExecute()

public func canExecute(): Bool

功能:判断当前用户是否有权限执行该实例对应的文件。

  • 对文件而言,判断用户是否有执行文件的权限。
  • 对目录而言,判断用户是否有进入目录的权限。
  • 在 Windows 环境下,用户对于文件的执行权限由文件扩展名决定;用户始终拥有对于目录的执行权限,该函数不生效,返回 true。
  • 在 Linux 和 macOS 环境下,该函数正常使用。

返回值:

  • Bool - true 表示有权限;false 表示无权限。

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。

func canRead()

public func canRead(): Bool

功能:判断当前用户是否有权限读取该实例对应的文件。

  • 对文件而言,判断用户是否有读取文件的权限。
  • 对目录而言,判断用户是否有浏览目录的权限。
  • 在 Windows 环境下,用户始终拥有对于文件和目录的可读权限,该函数不生效,返回 true。
  • 在 Linux 和 macOS 环境下,该函数正常使用。

返回值:

  • Bool - true 表示有权限;false 表示无权限。

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。

func canWrite()

public func canWrite(): Bool

功能:判断当前用户是否有权限写入该实例对应的文件。

  • 对文件而言,判断用户是否有写入文件的权限。
  • 对目录而言,判断用户是否有删除、移动、创建目录内文件的权限。
  • 在 Windows 环境下,用户对于文件的可写权限正常使用,用户始终拥有对于目录的可写权限,该函数不生效,返回 true。
  • 在 Linux 和 macOS 环境下,该函数正常使用。

返回值:

  • Bool - true 表示有权限;false 表示无权限。

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。

func isDirectory()

public func isDirectory(): Bool

功能:判断当前文件是否是目录。

返回值:

  • Bool - true 表示是目录;false 表示不是目录。

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。

func isRegular()

public func isRegular(): Bool

功能:判断当前文件是否是普通文件。

返回值:

  • Bool - true 表示是文件;false 表示不是文件。

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。

func isHidden()

public func isHidden(): Bool

功能:判断当前文件是否隐藏。

返回值:

  • Bool - true 表示隐藏;false 表示未隐藏。

func isReadOnly()

public func isReadOnly(): Bool

功能:判断当前文件是否只读。

  • 在 Windows 环境下,用户对于文件的只读权限正常使用;用户始终拥有对于目录的删除修改权限,该函数不生效,返回 false。
  • 在 Linux 和 macOS 环境下,该函数正常使用。

返回值:

  • Bool - true 表示是只读;false 表示不是只读。

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。
public func isSymbolicLink(): Bool

功能:判断当前文件是否是软链接。

返回值:

  • Bool - true 表示是软链接;false 表示不是软链接。

异常:

  • FSException - 如果判断过程中底层调用的系统接口发生错误,则抛异常。

func setExecutable(Bool)

public func setExecutable(executable: Bool): Bool

功能:对当前实例对应的文件设置当前用户是否可执行的权限,当前用户没有权限修改抛异常。

  • 对文件而言,设置用户是否有执行文件的权限,对目录而言,设置用户是否有进入目录的权限。
  • 在 Windows 环境下,用户对于文件的执行权限由文件扩展名决定,用户始终拥有对于目录的执行权限该函数不生效,返回 false。
  • 在 Linux 和 macOS 环境下,该函数正常使用如果在此函数调用期间,该 FileInfo 对应的文件实体被其它用户或者进程修改,有可能因为竞争条件(Race Condition)导致其它修改不能生效。

参数:

  • executable: Bool - 是否设置可执行。

返回值:

  • Bool - true,操作成功;false,操作失败。

func setReadable(Bool)

public func setReadable(readable: Bool): Bool

功能:对当前实例对应的文件设置当前用户是否可读取的权限,当前用户没有权限修改抛异常。

  • 对文件而言,设置用户是否有读取文件的权限。
  • 对目录而言,设置用户是否有浏览目录的权限。
  • 在 Windows 环境下,用户始终拥有对于文件以及目录的可读权限,不可更改,该函数不生效当 readable 为 true 时,函数返回 true,当 readable 为 false 时,函数返回 false。
  • 在 Linux 和 macOS 环境下,该函数正常使用如果在此函数调用期间,该 FileInfo 对应的文件实体被其它用户或者进程修改,有可能因为竞争条件(Race Condition)导致其它修改不能生效。

参数:

  • readable: Bool - 是否设置可读。

返回值:

  • Bool - true,操作成功;false,操作失败。

func setWritable(Bool)

public func setWritable(writable: Bool): Bool

功能:对当前实例对应的文件设置当前用户是否可写入的权限,当前用户没有权限修改抛异常。

  • 对文件而言,设置用户是否有写入文件的权限。
  • 对目录而言,设置用户是否有删除、移动、创建目录内文件的权限。
  • 在 Windows 环境下,用户对于文件的可写权限正常使用;用户始终拥有对于目录的可写权限,不可更改,该函数不生效,返回 false。
  • 在 Linux 和 macOS 环境下,该函数正常使用如果在此函数调用期间,该 FileInfo 对应的文件实体被其它用户或者进程修改,有可能因为竞争条件(Race Condition)导致其它修改不能生效。

参数:

  • writable: Bool - 是否设置可写。

返回值:

  • Bool - true,操作成功;false,操作失败。

operator func !=(FileInfo)

public operator func !=(that: FileInfo): Bool

功能:判断当前 FileInfo 和另一个 FileInfo 是否对应非同一文件。

参数:

返回值:

  • Bool - true,不是同一文件;false,是同一文件。

operator func ==(FileInfo)

public operator func ==(that: FileInfo): Bool

功能:判断当前 FileInfo 和另一个 FileInfo 是否对应同一文件。

参数:

返回值:

  • Bool - true,是同一文件;false,不是同一文件。

struct Path

public struct Path <: Equatable<Path> & Hashable & ToString {
    public static const Separator: String
    public static const ListSeparator: String
    public init(rawPath: String)
}

功能:提供路径相关的函数。

Path 用来表示本地路径(Windows 平台已支持 DOS 设备路径和 UNC 路径,长度限制跟随系统)。 路径的字符串最大支持 4096 个字节(包括结束符 \0)。

说明:

非法路径指的是以下情况之一:

  • 路径中包含非法字符,例如空格、制表符、换行符等;
  • 路径中包含不合法的字符,例如特殊字符、控制字符等;
  • 路径中包含不存在的目录或文件;
  • 路径中包含无法访问的目录或文件,例如权限不足或被锁定等。

在输入路径时,应该避免使用非法字符,确保路径的合法性,以便正确地访问目标文件或目录。

父类型:

static const ListSeparator

public static const ListSeparator: String

功能:获取路径列表分隔符,用于分隔路径列表中的不同路径。

Windows 系统中路径列表分隔符为 ";",非 Windows 系统中为 ":"。

类型:String

static const Separator

public static const Separator: String

功能:获取路径分隔符,用于分隔多级目录。

Windows 系统中分隔符为 "\",非 Windows 系统中为 "/"。

类型:String

prop extensionName

public prop extensionName: String

功能:获得 Path 的文件扩展名部分。

文件名 fileName 根据最后一个 r'.' 被划分为不带扩展名的文件名 fileNameWithoutExtension 和扩展名 extensionName 两部分。无扩展名时返回空字符串。

  • 对于路径 "./NewFile.txt",此属性返回 "txt"
  • 对于路径 "./.gitignore",此属性返回 "gitignore"
  • 对于路径 "./noextension",此属性返回 ""
  • 对于路径 "./a.b.c",此属性返回 "c"
  • 对于路径 "./NewFile.txt/",此属性返回 "txt"

类型:String

异常:

prop fileName

public prop fileName: String

功能:获得 Path 的文件名(含扩展名)部分。

整个路径字符串被划分为 parent 和 fileName 两部分,详见 parent。无文件名时返回空字符串。

以下示例适用于所有系统:

  • 对于路径 "./NewFile.txt",此属性返回 "NewFile.txt";
  • 对于路径 "./.gitignore",此属性返回 ".gitignore";
  • 对于路径 "./noextension",此属性返回 "noextension";
  • 对于路径 "./a.b.c",此属性返回 "a.b.c";
  • 对于路径 "./NewDir/",此属性返回 "NewDir";

特别地,在 Windows 文件系统中,fileName 不包括卷名部分。

以下示例仅适用于 Windows 系统:

  • 对于路径 "c:\a.txt",此属性返回 "a.txt";
  • 对于路径 "c:",此属性返回 "";
  • 对于路径 "\\Server\Share\a.txt",此属性返回 "a.txt";
  • 对于路径 "\\Server\Share\",此属性返回 "";
  • 对于路径 "\\?\C:a\b.txt",此属性返回 "b.txt";
  • 对于路径 "\\?\C:",此属性返回 ""。

类型:String

异常:

prop fileNameWithoutExtension

public prop fileNameWithoutExtension: String

功能:获得 Path 的文件名(不含扩展名)部分。

文件名 fileName 根据最后一个 r'.' 被划分为不带扩展名的文件名 fileNameWithoutExtension 和扩展名 extensionName 两部分。无文件名(不含扩展名)时返回空字符串。

  • 对于路径 "./NewFile.txt",此属性返回 "NewFile"
  • 对于路径 "./.gitignore",此属性返回 ""
  • 对于路径 "./noextension",此属性返回 "noextension"
  • 对于路径 "./a.b.c",此属性返回 "a.b"
  • 对于路径 "./NewFile/",此属性返回 "NewFile"

类型:String

异常:

prop parent

public prop parent: Path

功能:获得该 Path 实例的父路径。

整个路径字符串被划分为 parent 和 fileName,以最后一个有效文件分隔符(末尾的分隔符会被忽略)作为分界。如果 parent 不存在,就返回空字符串构造的 Path 实例。parent 和 fileName 部分都不包含末尾分隔符,parent 保留表示根目录的分隔符。无父目录时返回空的 Path 实例。

该属性不会访问文件系统,也不会消除特殊名称。如果有需要可以跟规范化搭配使用。

该属性在不同操作系统行为有差异,在 Windows 系统中,文件分隔符为 "\" 或 "/"(规范化时会统一转换为 "\"),在 Linux、macOS、ohos 系统中,文件分隔符为 "/"。

以下示例适用于所有系统:

  • 对于路径 "/a/b/c",此属性返回 Path("/a/b");
  • 对于路径 "/a/b/",此属性返回 Path("/a");
  • 对于路径 "/a",此属性返回 Path("/");
  • 对于路径 "/",此属性返回 Path("/");
  • 对于路径 "./a/b",此属性返回 Path("./a");
  • 对于路径 "./",此属性返回 Path("");
  • 对于路径 ".gitignore",此属性返回 Path("");
  • 对于路径 "/a/./../b",此属性返回 Path("/a/./..")。

此外,在 Windows 系统中,path 被分为卷名、目录名和文件名,详见微软官方文档:https://learn.microsoft.com/zh-cn/dotnet/standard/io/file-path-formats。属性 parent 包含卷名和目录名。

以下示例仅适用于 Windows 系统:

  • 对于路径 "C:",此属性返回 Path("C:");
  • 对于路径 "C:\a\b",此属性返回 Path("C:\a");
  • 对于路径 "\\Server\Share\xx\yy",此属性返回 Path("\\Server\Share\xx");
  • 对于路径 "\\?\UNC\Server\Share\xx\yy",此属性返回 Path("\\?\UNC\Server\Share\xx");
  • 对于路径 "\\?\c:\xx\yy",此属性返回 Path("\\?\c:\xx")。

类型:Path

异常:

init(String)

public init(rawPath: String)

功能:创建 Path 实例时不检查路径字符串是否合法,支持绝对路径和相对路径。

参数:

  • rawPath: String - 路径的字符串。

func hashCode()

public func hashCode(): Int64

功能:获得 Path 的哈希值。

返回值:

func isAbsolute()

public func isAbsolute(): Bool

功能:判断 Path 是否是绝对路径。在 Unix 中,以 / 开头的路径为绝对路径。

返回值:

  • Bool - true,是绝对路径;false,不是绝对路径。

异常:

func isEmpty()

public func isEmpty(): Bool

功能:判断当前实例是否为空路径。

返回值:

  • Bool - 如果当前实例为空路径,返回 true,否则返回 false。

func isRelative()

public func isRelative(): Bool

功能:判断 Path 是否是相对路径,其结果与函数 isAbsolute 结果相反。

返回值:

  • Bool - true,是相对路径;false,不是相对路径。

异常:

func join(Path)

public func join(path: Path): Path

功能:在当前路径后拼接另一个路径字符串形成新路径。

  • 对于路径 "a/b","c",返回 "a/b/c"。
  • 对于路径 "a","b/c",返回 "a/b/c"。

返回值:

异常:

func join(String)

public func join(path: String): Path

功能:在当前路径后拼接另一个路径字符串形成新路径。

  • 对于路径 "a/b","c",返回 "a/b/c"。
  • 对于路径 "a","b/c",返回 "a/b/c"。

返回值:

异常:

func normalize()

public func normalize(): Path

功能:将路径字符串进行规范化处理,并用规范化后的字符串构造新的 Path 实例。该函数仅做字符串解析,不会进行 io 操作。

规范化规则:

  • 将连续的多个路径分隔符替换为单个路径分隔符;
  • 删除末尾的路径分隔符(不删除作为根目录的路径分隔符,或卷名中的字符);
  • 删除每一个 "." 路径名元素(代表当前目录);
  • 删除每一个路径内的 ".." 路径名元素(代表父目录)和它前面的非 ".." 路径名元素;
  • 删除开始于根路径的 ".." 路径名元素,即将路径开始处的 "/.." 替换为 "/"(Windows 系统中还会将 "\.." 替换为 "\");
  • 相对路径保留开头的 "../"(Windows 系统中还将保留 "..\");
  • 最后如果得到空路径,返回 Path(".")。

特别地,Windows 文件系统中,卷名部分仅做分隔符转换,即 "/" 转换为 "\"。

返回值:

func toString()

public func toString(): String

功能:获得 Path 的路径字符串。

返回值:

operator func !=(Path)

public operator func !=(that: Path): Bool

功能:判断 Path 是否不等。

判等规则详见 == 操作符相关说明。

参数:

返回值:

  • Bool - true,不是同一路径;false,是同一路径。

operator func ==(Path)

public operator func ==(that: Path): Bool

功能:判断 Path 是否相等。

判等时将对 Path 进行规范化,如果规范化后的字符串相等,则认为两个 Path 实例相等。规范化规则详见函数 normalize

参数:

返回值:

  • Bool - true,是同一路径;false,不是同一路径。

异常类

class FSException

文件流异常类,继承了 IO 流异常类。

public class FSException <: IOException {
    public init()
    public init(message: String)
}

父类型:

init()

public init()

功能:构造一个文件异常实例,无异常提示信息。

init(String)

public init(message: String)

功能:构造一个文件异常实例,有异常提示信息。

参数:

  • message: String - 错误信息。

Directory 示例

Directory 一些基础操作演示

代码如下:

import std.fs.*

main() {
    let testDirPath: Path = Path("./testDir")
    let subDirPath: Path = Path("./testDir/subDir")
    if (exists(testDirPath)) {
        remove(testDirPath, recursive: true)
    }

    /* 递归创建目录 和 "./testDir/subDir" */
    let subDir: Directory = Directory.create(subDirPath, recursive: true)
    if (exists(subDirPath)) {
        println("The directory './testDir/subDir' is successfully created recursively in current directory.")
    }

    /* 在 "./testDir/subDir" 下创建子目录 "dir1" */
    subDir.createSubDirectory("dir1")
    if (exists("./testDir/subDir/dir1")) {
        println("The directory 'dir1' is created successfully in directory './testDir/subDir'.")
    }

    /* 在 "./testDir/subDir" 下创建子文件 "file1" */
    subDir.createFile("file1")
    if (exists("./testDir/subDir/file1")) {
        println("The file 'file1' is created successfully in directory './testDir/subDir'.")
    }

    /* 在 "./testDir" 下创建临时目录 */
    let tempDir: Directory = Directory.createTemp(testDirPath)
    let tempDirPath: Path = tempDir.info.path
    if (exists(tempDirPath)) {
        println("The temporary directory is created successfully in directory './testDir'.")
    }

    /* 将 "subDir" 移动到临时目录下并重命名为 "subDir_new" */
    let newSubDirPath: Path = tempDirPath.join("subDir_new")
    rename(subDirPath, to: newSubDirPath)
    if (exists(newSubDirPath) && !exists(subDirPath)) {
        println("The directory './testDir/subDir' is moved successfully to the temporary directory and renamed 'subDir_new'.")
    }

    /* 将 "subDir_new" 拷贝到 "./testDir" 下并重命名为 "subDir" */
    copy(newSubDirPath, to: subDirPath, overwrite: false)
    if (exists(subDirPath) && exists(newSubDirPath)) {
        println("The directory 'subDir_new' is copied successfully to directory './testDir' and renamed 'subDir'.")
    }

    remove(testDirPath, recursive: true)
    return 0
}

运行结果如下:

The directory './testDir/subDir' is successfully created recursively in current directory.
The directory 'dir1' is created successfully in directory './testDir/subDir'.
The file 'file1' is created successfully in directory './testDir/subDir'.
The temporary directory is created successfully in directory './testDir'.
The directory './testDir/subDir' is moved successfully to the temporary directory and renamed 'subDir_new'.
The directory 'subDir_new' is copied successfully to directory './testDir' and renamed 'subDir'.

File 示例

File 常规操作:创建、删除、读写、关闭

代码如下:

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

main() {
    let filePath: Path = Path("./tempFile.txt")
    if (exists(filePath)) {
        remove(filePath)
    }

    /* 在当前目录以 只写模式 创建新文件 'tempFile.txt',写入三遍 "123456789\n" 并关闭文件 */
    var file: File = File(filePath, OpenOption.Create(false))
    if (exists(filePath)) {
        println("The file 'tempFile.txt' is created successfully in current directory.\n")
    }
    let bytes: Array<Byte> = "123456789\n".toArray()
    for (_ in 0..3) {
        file.write(bytes)
    }
    file.close()

    /* 以 追加模式 打开文件 './tempFile.txt',写入 "abcdefghi\n" 并关闭文件 */
    file = File(filePath, OpenOption.Append)
    file.write("abcdefghi\n".toArray())
    file.close()

    /* 以 只读模式 打开文件 './tempFile.txt',按要求读出数据并关闭文件 */
    file = File(filePath, OpenOption.Open(true, false))
    let bytesBuf: Array<Byte> = Array<Byte>(10, repeat: 0)
    // 从文件头开始的第 10 个字节后开始读出 10 个字节的数据
    file.seek(SeekPosition.Begin(10))
    file.read(bytesBuf)
    println("Data of the 10th byte after the 10th byte: ${String.fromUtf8(bytesBuf)}")
    // 读出文件尾的 10 个字节的数据
    file.seek(SeekPosition.End(-10))
    file.read(bytesBuf)
    println("Data of the last 10 bytes: ${String.fromUtf8(bytesBuf)}")
    file.close()

    /* 以 截断模式 打开文件 './tempFile.txt',写入 "The file was truncated to an empty file!" 并关闭文件 */
    file = File(filePath, OpenOption.Truncate(true))
    file.write("The file was truncated to an empty file!".toArray())
    file.seek(SeekPosition.Begin(0))
    let allBytes: Array<Byte> = readToEnd(file)
    file.close()
    println("Data written newly: ${String.fromUtf8(allBytes)}")

    remove(filePath)
    return 0
}

运行结果如下:

The file 'tempFile.txt' is created successfully in current directory.

Data of the 10th byte after the 10th byte: 123456789

Data of the last 10 bytes: abcdefghi

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

File 的一些 static 函数演示

代码如下:

import std.fs.*

main() {
    let filePath: Path = Path("./tempFile.txt")
    if (exists(filePath)) {
        remove(filePath)
    }

    /* 以 只写模式 创建文件,并写入 "123456789\n" 并关闭文件 */
    var file: File = File.create(filePath)
    file.write("123456789\n".toArray())
    file.close()

    /* 以 追加模式 写入 "abcdefghi\n" 到文件 */
    File.writeTo(filePath, "abcdefghi".toArray(), openOption: OpenOption.Append)

    /* 直接读取文件中所有数据 */
    let allBytes: Array<Byte> = File.readFrom(filePath)
    println(String.fromUtf8(allBytes))

    remove(filePath)
    return 0
}

运行结果如下:

123456789
abcdefghi

FileInfo 示例

FileInfo 一些基础操作演示

代码如下:

import std.fs.*
import std.time.DateTime

main() {
    // 在当前目录下创建个临时文件以便下面 FileInfo 的演示
    let curDirPath: Path = canonicalize(Path("./"))
    let file: File =  File.createTemp(curDirPath)
    file.write("123456789\n".toArray())
    let fileInfo: FileInfo = file.info

    file.close()

    /* 获得这个文件父级目录的 FileInfo,这个文件的父目录是当前目录 */
    let parentDirectory: Option<FileInfo> = fileInfo.parentDirectory
    checkResult(parentDirectory == Some(FileInfo(curDirPath)), "The 'parentFileInfo' is obtained successfully.")

    /* 获得这个文件的路径 */
    /*
    let filePath: Path = fileInfo.path
    */

    /* 获取这个文件的创建时间、最后访问时间、最后修改时间 */
    /*
    let creationTime: DateTime = fileInfo.creationTime
    let lastAccessTime: DateTime = fileInfo.lastAccessTime
    let lastModificationTime: DateTime = fileInfo.lastModificationTime
    */

    /*
     * 获取这个文件的 length
     * 如果是文件代表这个文件占用磁盘空间的大小
     * 如果是目录代表这个目录的所有文件占用磁盘空间的大小(不包含子目录)
     */
    /*
    let length: Int64 = fileInfo.size
    */

    /* 判断这个文件是否是软链接、普通文件、目录 */
    checkResult(fileInfo.isSymbolicLink(), "The file is a symbolic link.")
    checkResult(fileInfo.isRegular(), "The file is a regular file.")
    checkResult(fileInfo.isDirectory(), "The file is a directory.")

    /* 判断这个文件对于当前用户是否是只读、隐藏、可执行、可读、可写 */
    checkResult(fileInfo.isReadOnly(), "This file is read-only.")
    checkResult(fileInfo.isHidden(), "The file is hidden.")
    checkResult(fileInfo.canExecute(), "The file is executable.")
    checkResult(fileInfo.canRead(), "The file is readable.")
    checkResult(fileInfo.canWrite(), "The file is writable.")

    /* 修改当前用户对这个文件的权限,这里设置为对当前用户只读 */
    checkResult(fileInfo.setExecutable(false), "The file was successfully set to executable.")
    checkResult(fileInfo.setReadable(true), "The file was successfully set to readable.")
    checkResult(fileInfo.setWritable(false), "The file was successfully set to writable.")
    checkResult(fileInfo.isReadOnly(), "This file is now read-only.")

    return 0
}

func checkResult(result: Bool, message: String): Unit {
    if (result) {
        println(message)
    }
}

运行结果如下:

The 'parentFileInfo' is obtained successfully.
The file is a regular file.
The file is readable.
The file is writable.
The file was successfully set to executable.
The file was successfully set to readable.
The file was successfully set to writable.
This file is now read-only.

Path 示例

不同 Path 实例的属性信息展示

打印 Path 实例的目录部分、文件全名(有扩展名)、扩展名、文件名(无扩展名),并判断 Path 实例是绝对路径还是相对路径

代码如下:

import std.fs.Path

main() {
    let pathStrArr: Array<String> = [
        // 绝对路径
        "/a/b/c",
        "/a/b/",
        "/a/b/c.cj",
        "/a",
        "/",
        // 相对路径
        "./a/b/c",
        "./a/b/",
        "./a/b/c.cj",
        "./",
        ".",
        "123."
    ]

    for (i in 0..pathStrArr.size) {
        let path: Path = Path(pathStrArr[i])
        // 打印 path 的整个路径字符串
        println("Path${i}: ${path.toString()}")
        // 打印 path 的目录路径
        println("Path.parent: ${path.parent}")
        // 打印 path 的文件全名(有扩展名)
        println("Path.fileName: ${path.fileName}")
        // 打印 path 的扩展名
        println("Path.extensionName: ${path.extensionName}")
        // 打印 path 的文件名(无扩展名)
        println("Path.fileNameWithoutExtension: ${path.fileNameWithoutExtension}")
        // 打印 path 是否是绝对路径、相对路径
        println("Path.isAbsolute: ${path.isAbsolute()}; Path.isRelative: ${path.isRelative()}")
        println()
    }

    return 0
}

运行结果如下:

Path0: /a/b/c
Path.parent: /a/b
Path.fileName: c
Path.extensionName: 
Path.fileNameWithoutExtension: c
Path.isAbsolute: true; Path.isRelative: false

Path1: /a/b/
Path.parent: /a
Path.fileName: b
Path.extensionName: 
Path.fileNameWithoutExtension: b
Path.isAbsolute: true; Path.isRelative: false

Path2: /a/b/c.cj
Path.parent: /a/b
Path.fileName: c.cj
Path.extensionName: cj
Path.fileNameWithoutExtension: c
Path.isAbsolute: true; Path.isRelative: false

Path3: /a
Path.parent: /
Path.fileName: a
Path.extensionName: 
Path.fileNameWithoutExtension: a
Path.isAbsolute: true; Path.isRelative: false

Path4: /
Path.parent: /
Path.fileName: 
Path.extensionName: 
Path.fileNameWithoutExtension: 
Path.isAbsolute: true; Path.isRelative: false

Path5: ./a/b/c
Path.parent: ./a/b
Path.fileName: c
Path.extensionName: 
Path.fileNameWithoutExtension: c
Path.isAbsolute: false; Path.isRelative: true

Path6: ./a/b/
Path.parent: ./a
Path.fileName: b
Path.extensionName: 
Path.fileNameWithoutExtension: b
Path.isAbsolute: false; Path.isRelative: true

Path7: ./a/b/c.cj
Path.parent: ./a/b
Path.fileName: c.cj
Path.extensionName: cj
Path.fileNameWithoutExtension: c
Path.isAbsolute: false; Path.isRelative: true

Path8: ./
Path.parent: 
Path.fileName: .
Path.extensionName: 
Path.fileNameWithoutExtension: 
Path.isAbsolute: false; Path.isRelative: true

Path9: .
Path.parent: 
Path.fileName: .
Path.extensionName: 
Path.fileNameWithoutExtension: 
Path.isAbsolute: false; Path.isRelative: true

Path10: 123.
Path.parent: 
Path.fileName: 123.
Path.extensionName: 
Path.fileNameWithoutExtension: 123
Path.isAbsolute: false; Path.isRelative: true

Path 的拼接、判等、转规范化路径等操作

代码如下:

import std.fs.*

main() {
    let dirPath: Path = Path("./a/b/c")
    if (!exists(dirPath)) {
        Directory.create(dirPath, recursive: true)
    }

    let filePath: Path = dirPath.join("d.cj") // ./a/b/c/d.cj
    if (filePath == Path("./a/b/c/d.cj")) {
        println("filePath.join: success")
    }
    if (!exists(filePath)) {
        File.create(filePath).close()
    }

    let curNormalizedPath: Path = canonicalize(Path("."))
    let fileNormalizedPath: Path = canonicalize(Path("././././a/./../a/b/../../a/b/c/.././../../a/b/c/d.cj"))
    if (fileNormalizedPath == canonicalize(filePath) &&
        fileNormalizedPath.toString() == curNormalizedPath.toString() + "/a/b/c/d.cj") {
        println("canonicalize filePath: success")
    }

    remove(dirPath, recursive: true)
    return 0
}

运行结果如下:

filePath.join: success
canonicalize filePath: success

通过 Path 创建文件和目录

代码如下:

import std.fs.*

main() {
    let curPath: Path = Path("./")
    let dirPath: Path = curPath.join("tempDir")
    let filePath: Path = dirPath.join("tempFile.txt")
    if (exists(dirPath)) {
        remove(dirPath, recursive: true)
    }

    Directory.create(dirPath)
    if (exists(dirPath)) {
        println("Directory 'tempDir' is created successfully.")
    }

    File.create(filePath).close()
    if (exists(filePath)) {
        println("File 'tempFile.txt' is created successfully in directory 'tempDir'.")
    }

    remove(dirPath, recursive: true)
    return 0
}

运行结果如下:

Directory 'tempDir' is created successfully.
File 'tempFile.txt' is created successfully in directory 'tempDir'.

std.io 包

功能介绍

io 包提供程序与外部设备进行数据交换的能力。

I/O 操作是指程序与外部设备进行数据交换的操作。仓颉提供了流式 I/O 操作的通用接口和一些特殊实现。输入输出流类似一个数据通道,承载一段有序数据,程序从输入流读取数据(来自文件、网络等),往输出流(通往文件、网络等)写入数据。

API 列表

函数

函数名功能
copy(InputStream, OutputStream)将一个输入流中未被读取的数据拷贝到另一个输出流中。
readString<T>(T) where T <: InputStream & Seekable读取入参中的所有剩余内容,并返回一个字符串。
readStringUnchecked<T>(T) where T <: InputStream & Seekable读取入参中的所有剩余内容,并返回一个字符串。该函数不会检查字符串的合法性。
func readToEnd<T>(T) where T <: InputStream & Seekable获取入参中未被读取的数据。

接口

接口名功能
InputStream输入流接口。
IOStream输入输出流接口。
OutputStream输出流接口。
Seekable移动光标接口。

类名功能
BufferedInputStream<T> where T <: InputStream提供带缓冲区的输入流。
BufferedOutputStream<T> where T <: OutputStream提供带缓冲区的输出流。
ByteBuffer输入流接口。
ChainedInputStream<T> where T <: InputStream提供顺序从 InputStream 数组中读取数据的能力。
MultiOutputStream<T> where T <: OutputStream提供将数据同时写入到 OutputStream 数组中每个输出流中的能力。
StringReader<T> where T <: InputStream提供从 InputStream 输入流中读出数据并转换成字符或字符串的能力。
StringWriter<T> where T <: OutputStream提供将 String 以及一些 ToString 类型转换成指定编码格式和字节序配置的字符串并写入到输出流的能力。

枚举

枚举名功能
SeekPosition输入流接口。

异常类

异常类名功能
ContentFormatException提供字符格式相关的异常处理。
IOException提供 IO 流相关的异常处理。

函数

func copy(InputStream, OutputStream)

public func copy(from: InputStream, to!: OutputStream): Int64

功能:将一个输入流中未被读取的数据拷贝到另一个输出流中。

参数:

返回值:

  • Int64 - 拷贝数据的字节数。

func readString<T>(T) where T <: InputStream & Seekable

public func readString<T>(from: T): String where T <: InputStream & Seekable

功能:读取入参中的所有剩余内容,并返回一个字符串。

参数:

  • from: T - 要读取数据的对象。

返回值:

  • String - 读取到的结果字符串。

异常:

func readStringUnchecked<T>(T) where T <: InputStream & Seekable

public unsafe func readStringUnchecked<T>(from: T): String where T <: InputStream & Seekable

功能:读取入参中的所有剩余内容,并返回一个字符串。该函数不会检查字符串的合法性。

参数:

  • from: T - 要读取数据的对象。

返回值:

  • String - 读取到的结果字符串。

func readToEnd<T>(T) where T <: InputStream & Seekable

public func readToEnd<T>(from: T): Array<Byte> where T <: InputStream & Seekable

功能:获取入参中未被读取的数据。

参数:

  • from: T - 要读取数据的对象。

返回值:

  • Array<Byte> - 未被读取的数据的拷贝。

接口

interface IOStream

public interface IOStream <: InputStream & OutputStream {}

功能:输入输出流接口。

父类型:

interface InputStream

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

功能:输入流接口。

func read(Array<Byte>)

func read(buffer: Array<Byte>): Int64

功能:从输入流中读取数据放到 buffer 中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放从输入流中读取的数据。

返回值:

  • Int64 - 读取的数据的字节数。

interface OutputStream

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

功能:输出流接口。

func flush()

func flush(): Unit

功能:清空缓存区。该函数提供默认实现,默认实现为空。

func write(Array<Byte>)

func write(buffer: Array<Byte>): Unit

功能:将 buffer 中的数据写入到输出流中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入输出流的数据。

interface Seekable

public interface Seekable {
    prop length: Int64
    prop position: Int64
    prop remainLength: Int64
    func seek(sp: SeekPosition): Int64
}

功能:移动光标接口。

prop length

prop length: Int64

功能:返回当前流中的总数据量。

类型:Int64

prop position

prop position: Int64

功能:返回当前光标位置。

类型:Int64

prop remainLength

prop remainLength: Int64

功能:返回当前流中未读的数据量。

类型:Int64

func seek(SeekPosition)

func seek(sp: SeekPosition): Int64

功能:移动光标到指定的位置。

参数:

返回值:

  • Int64 - 返回流中数据的起点到移动后位置的偏移量(以字节为单位)。

class BufferedInputStream<T> where T <: InputStream

public class BufferedInputStream<T> <: InputStream where T <: InputStream {
    public init(input: T)
    public init(input: T, buffer: Array<Byte>)
    public init(input: T, capacity: Int64)
}

功能:提供带缓冲区的输入流。

可将其他 InputStream 类型的输入流(如 ByteBuffer)绑定到 BufferedInputStream 实例,从该实例读取数据时,先把数据从被绑定的流读入缓冲区暂存,再从缓冲区读取用户需要的数据。

父类型:

init(T)

public init(input: T)

功能:创建 BufferedInputStream 实例,缓冲区容量取默认值 4096。

参数:

  • input: T - 绑定指定输入流。

init(T, Array<Byte>)

public init(input: T, buffer: Array<Byte>)

功能:创建 BufferedInputStream 实例。

其内部使用的缓存区由入参决定,在注重性能的场景下,通过复用传入的 buffer,可以减少内存分配次数,提高性能。

参数:

异常:

init(T, Int64)

public init(input: T, capacity: Int64)

功能:创建 BufferedInputStream 实例。

参数:

  • input: T - 绑定指定输入流。
  • capacity: Int64 - 内部缓冲区容量。

异常:

func read(Array<Byte>)

public func read(buffer: Array<Byte>): Int64

功能:从绑定的输入流读出数据到 buffer 中。

参数:

  • buffer: Array<Byte> - 存放读取的数据的缓冲区。

返回值:

  • Int64 - 读取数据的字节数。

异常:

func readByte()

public func readByte(): ?Byte

功能:从输入流中读取一个字节。

返回值:

  • ?Byte - 读取到的数据。读取失败时会返回 None

func reset(T)

public func reset(input: T): Unit

功能:绑定新的输入流,重置状态,但不重置 capacity

参数:

  • input: T - 待绑定的输入流。

extend<T> BufferedInputStream<T> <: Resource where T <: Resource

extend<T> BufferedInputStream<T> <: Resource where T <: Resource

功能:为 BufferedInputStream 实现 Resource 接口,该类型对象可在 try-with-resource 语法上下文中实现自动资源释放。

父类型:

func close()

public func close(): Unit

功能:关闭当前流。

注意:

  • 调用此方法后不可再调用 BufferedInputStream 的其他接口,否则会造成不可期现象。

func isClosed()

public func isClosed(): Bool

功能:判断当前流是否关闭。

返回值:

  • Bool - 如果当前流已经被关闭,返回 true,否则返回 false。

extend<T> BufferedInputStream<T> <: Seekable where T <: Seekable

extend<T> BufferedInputStream<T> <: Seekable where T <: Seekable

功能:为 BufferedInputStream 实现 Seekable 接口,支持查询数据长度,移动光标等操作。

父类型:

prop length

public prop length: Int64

功能:返回当前流中的总数据量。

类型:Int64

prop position

public prop position: Int64

功能:返回当前光标位置。

类型:Int64

prop remainLength

public prop remainLength: Int64

功能:返回当前流中未读的数据量。

类型:Int64

func seek(SeekPosition)

public func seek(sp: SeekPosition): Int64

功能:移动光标到指定的位置。

说明:

  • 指定的位置不能位于流中数据头部之前。
  • 指定位置可以超过流中数据末尾。
  • 调用该函数会先清空缓存区,再移动光标的位置。

参数:

返回值:

  • Int64 - 返回流中数据的起点到移动后位置的偏移量(以字节为单位)。

class BufferedOutputStream<T> where T <: OutputStream

public class BufferedOutputStream<T> <: OutputStream where T <: OutputStream {
    public init(output: T)
    public init(output: T, buffer: Array<Byte>)
    public init(output: T, capacity: Int64)
}

功能:提供带缓冲区的输出流。

可将其他 OutputStream 类型的输入流(如 ByteBuffer)绑定到 BufferedOutputStream 实例,从该实例写入数据时,先把数据写入缓冲区暂存,再从缓冲区写入数据到流中。

父类型:

init(T)

public init(output: T)

功能:创建 BufferedOutputStream 实例,缓冲区容量取默认值 4096。

参数:

  • output: T - 绑定指定输出流。

init(T, Array<Byte>)

public init(output: T, buffer: Array<Byte>)

功能:创建 BufferedOutputStream 实例。

其内部使用的缓存区由入参决定,在注重性能的场景下,通过复用传入的 buffer,可以减少内存分配次数,提高性能。

参数:

异常:

init(T, Int64)

public init(output: T, capacity: Int64)

功能:创建 BufferedOutputStream 实例。

参数:

  • output: T - 绑定指定输出流。
  • capacity: Int64 - 内部缓冲区容量。

异常:

func flush()

public func flush(): Unit

功能:刷新 BufferedOutputStream:将内部缓冲区的剩余数据写入绑定的输出流,并刷新 BufferedOutputStream

func reset(T)

public func reset(output: T): Unit

功能:绑定新的输出流,重置状态,但不重置 capacity

参数:

  • output: T - 待绑定的输出流。

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能:将 buffer 中的数据写入到绑定的输出流中。

参数:

  • buffer: Array<Byte> - 待写入数据的缓冲区。

func writeByte(Byte)

public func writeByte(v: Byte): Unit

功能: 写入一个字节到绑定的输出流中。

参数:

  • v: Byte - 待写入的字节。

extend<T> BufferedOutputStream<T> <: Resource where T <: Resource

extend<T> BufferedOutputStream<T> <: Resource where T <: Resource

功能:为 BufferedOutputStream 实现 Resource 接口,该类型对象可在 try-with-resource 语法上下文中实现自动资源释放。

父类型:

func close()

public func close(): Unit

功能:关闭当前流。

注意:

  • 调用此方法后不可再调用 BufferedOutputStream 的其他接口,否则会造成不可期现象。

func isClosed()

public func isClosed(): Bool

功能:判断当前流是否关闭。

返回值:

  • Bool - 如果当前流已经被关闭,返回 true,否则返回 false。

extend<T> BufferedOutputStream<T> <: Seekable where T <: Seekable

extend<T> BufferedOutputStream<T> <: Seekable where T <: Seekable

功能:为 BufferedOutputStream 实现 Seekable 接口,支持查询数据长度,移动光标等操作。

父类型:

prop length

public prop length: Int64

功能:返回当前流中的总数据量。

类型:Int64

prop position

public prop position: Int64

功能:返回当前光标位置。

类型:Int64

prop remainLength

public prop remainLength: Int64

功能:返回当前流中未读的数据量。

类型:Int64

func seek(SeekPosition)

public func seek(sp: SeekPosition): Int64

功能:移动光标到指定的位置。

说明:

  • 指定的位置不能位于流中数据头部之前。
  • 指定位置可以超过流中数据末尾。
  • 调用该函数会先将缓存区内的数据写到绑定的输出流里,再移动光标的位置。

参数:

返回值:

  • Int64 - 返回流中数据的起点到移动后位置的偏移量(以字节为单位)。

class ByteBuffer

public class ByteBuffer <: IOStream & Seekable {
    public init()
    public init(capacity: Int64)
}

功能:基于 Array<Byte> 数据类型,提供对字节流的写入、读取等操作。

父类型:

prop capacity

public prop capacity: Int64

功能:获取当前缓冲区容量。

返回值:

  • Int64 - 当前缓冲区容量。

prop length

public prop length: Int64

功能:返回当前流中的总数据量。

类型:Int64

prop position

public prop position: Int64

功能:获取当前光标位置。

类型:Int64

prop remainLength

public prop remainLength: Int64

功能:获取当前流中未读的数据量。

类型:Int64

init()

public init()

功能:创建 ByteBuffer 实例,默认的初始容量是 32。

init(Array<Byte>)

public init(source: Array<Byte>)

功能:根据传入的数组构造 ByteBuffer 实例。

参数:

init(Int64)

public init(capacity: Int64)

功能:创建 ByteBuffer 实例。

参数:

  • capacity: Int64 - 指定的初始容量。

异常:

func bytes()

public func bytes(): Array<Byte>

功能:获取当前 ByteBuffer 中未被读取的数据的切片。

注意:

  • 缓冲区进行读取,写入或重置等修改操作会导致这个切片失效。
  • 对切片的修改会影响缓冲区的内容。

返回值:

  • Array<Byte> - 当前流中未被读取的数据的切片。

func clear()

public func clear(): Unit

功能:清除当前 ByteBuffer 中所有数据。

func clone()

public func clone(): ByteBuffer

功能:用当前 ByteBuffer 中的数据来构造一个新的 ByteBuffer

返回值:

func read(Array<Byte>)

public func read(buffer: Array<Byte>): Int64

功能:从输入流中读取数据放到 buffer 中。

参数:

  • buffer: Array<Byte> - 存放读取的数据的缓冲区。

返回值:

  • Int64 - 读取数据的字节数。

异常:

func readByte()

public func readByte(): ?Byte

功能:从输入流中读取一个字节。

返回值:

  • ?Byte - 读取到的数据。读取失败时会返回 None

func reserve(Int64)

public func reserve(additional: Int64): Unit

功能:将缓冲区扩容指定大小。

说明:

  • 当缓冲区剩余字节数大于等于 additional 时不发生扩容。
  • 当缓冲区剩余字节数量小于 additional 时,取(additional + capacity)与(capacity的1.5倍向下取整)两个值中的最大值进行扩容。

参数:

  • additional: Int64 - 将要扩容的大小。

异常:

func seek(SeekPosition)

public func seek(sp: SeekPosition): Int64

功能:将光标跳转到指定位置。

说明:

  • 指定的位置不能位于流中数据头部之前。
  • 指定位置可以超过流中数据末尾。

参数:

返回值:

  • Int64 - 流中数据的头部到跳转后位置的偏移量(以字节为单位)。

异常:

  • IOException - 当指定的位置位于流中数据头部之前时,抛出异常。

func setLength(Int64)

public func setLength(length: Int64): Unit

功能:将当前数据修改为指定长度。该操作不会改变seek的偏移。

参数:

  • length: Int64 - 要修改的长度。

异常:

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能:将 buffer 中的数据写入到输出流中。

参数:

  • buffer: Array<Byte> - 待写入数据的缓冲区。

异常:

func writeByte(Byte)

public func writeByte(v: Byte): Unit

功能:将一个字节写入到输出流中。

参数:

  • v: Byte - 待写入的字节。

class ChainedInputStream<T> where T <: InputStream

public class ChainedInputStream<T> <: InputStream where T <: InputStream {
    public init(input: Array<T>)
}

功能:提供顺序从 InputStream 数组中读取数据的能力。

父类型:

init(Array<T>)

public init(input: Array<T>)

功能:创建 ChainedInputStream 实例。

参数:

  • input: Array<T> - 绑定指定输入流数组。

异常:

func read(Array<Byte>)

public func read(buffer: Array<Byte>): Int64

功能:依次从绑定 InputStream 数组中读出数据到 buffer 中。

参数:

  • buffer: Array<Byte> - 存储读出数据的缓冲区。

返回值:

  • Int64 - 读取字节数。

异常:

class MultiOutputStream<T> where T <: OutputStream

public class MultiOutputStream<T> <: OutputStream where T <: OutputStream {
    public init(output: Array<T>)
}

功能:提供将数据同时写入到 OutputStream 数组中每个输出流中的能力。

父类型:

init(Array<T>)

public init(output: Array<T>)

功能:创建 MultiOutputStream 实例。

参数:

  • output: Array<T> - 绑定指定输出流数组。

异常:

func flush()

public func flush(): Unit

功能:刷新绑定的输出流数组里的每个输出流。

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能:将 buffer 同时写入到绑定的 OutputStream 数组里的每个输出流中。

参数:

  • buffer: Array<Byte> - 存储待写入数据的缓冲区。

class StringReader<T> where T <: InputStream

public class StringReader<T> where T <: InputStream {
    public init(input: T)
}

功能:提供从 InputStream 输入流中读出数据并转换成字符或字符串的能力。

说明:

  • StringReader 内部默认有缓冲区,缓冲区容量 4096 个字节。
  • StringReader 目前仅支持 UTF-8 编码,暂不支持 UTF-16、UTF-32。

init(T)

public init(input: T)

功能:创建 StringReader 实例。

参数:

  • input: T - 待读取数据的输入流。

func lines()

public func lines(): Iterator<String>

功能:获得 StringReader 的行迭代器。

相当于循环调用 func readln(),内部遇到非法字符时也会抛出异常。

说明:

  • 每行都由换行符进行分隔。
  • 换行符是 \n \r \r\n 之一。
  • 每行不包括换行符。

返回值:

异常:

func read()

public func read(): ?Rune

功能:按字符读取流中的数据。

返回值:

异常:

func readToEnd()

public func readToEnd(): String

功能:读取流中所有剩余数据。

返回值:

  • String - 流中所有剩余数据。

异常:

func readUntil((Rune)->Bool)

public func readUntil(predicate: (Rune)->Bool): Option<String>

功能:从流内读取到使 predicate 返回 true 的字符位置(包含这个字符)或者流结束位置的数据。

参数:

  • predicate: (Rune)->Bool - 满足一定条件返回 true 的表达式。

返回值:

异常:

func readUntil(Rune)

public func readUntil(v: Rune): Option<String>

功能:从流内读取到指定字符(包含指定字符)或者流结束位置的数据。

参数:

  • v: Rune - 指定字符。

返回值:

异常:

func readln()

public func readln(): Option<String>

功能:按行读取流中的数据。

说明:

  • 读取的数据会去掉原换行符。

返回值:

异常:

func runes()

public func runes(): Iterator<Rune>

功能:获得 StringReaderRune 迭代器。

返回值:

异常:

extend<T> StringReader<T> <: Resource where T <: Resource

extend<T> StringReader<T> <: Resource where T <: Resource

功能:为 StringReader 实现 Resource 接口,该类型对象可在 try-with-resource 语法上下文中实现自动资源释放。

父类型:

func close()

public func close(): Unit

功能:关闭当前流。

注意:

  • 调用此方法后不可再调用 StringReader 的其他接口,否则会造成不可期现象。

func isClosed()

public func isClosed(): Bool

功能:判断当前流是否关闭。

返回值:

  • Bool - 如果当前流已经被关闭,返回 true,否则返回 false。

extend<T> StringReader<T> <: Seekable where T <: Seekable

extend<T> StringReader<T> <: Seekable where T <: Seekable

功能:为 StringReader 实现 Seekable 接口,支持查询数据长度,移动光标等操作。

父类型:

prop length

public prop length: Int64

功能:返回当前流中的总数据量。

类型:Int64

prop position

public prop position: Int64

功能:返回当前光标位置。

类型:Int64

prop remainLength

public prop remainLength: Int64

功能:返回当前流中未读的数据量。

类型:Int64

func seek(SeekPosition)

public func seek(sp: SeekPosition): Int64

功能:移动光标到指定的位置。

说明:

  • 指定的位置不能位于流中数据头部之前。
  • 指定位置可以超过流中数据末尾。

参数:

返回值:

  • Int64 - 返回流中数据的起点到移动后位置的偏移量(以字节为单位)。

class StringWriter<T> where T <: OutputStream

public class StringWriter<T> where T <: OutputStream {
    public init(output: T)
}

功能:提供将 String 以及一些 ToString 类型转换成指定编码格式和字节序配置的字符串并写入到输出流的能力。

说明:

  • StringWriter 内部默认有缓冲区,缓冲区容量 4096 个字节。
  • StringWriter 目前仅支持 UTF-8 编码,暂不支持 UTF-16、UTF-32。

init(T)

public init(output: T)

功能:创建 StringWriter 实例。

参数:

  • output: T - 待写入数据的输出流。

func flush()

public func flush(): Unit

功能:刷新内部缓冲区,将缓冲区数据写入 output 中,并刷新 output。

func write(Bool)

public func write(v: Bool): Unit

功能:写入 Bool 类型。

参数:

func write(Float16)

public func write(v: Float16): Unit

功能:写入 Float16 类型。

参数:

func write(Float32)

public func write(v: Float32): Unit

功能:写入 Float32 类型。

参数:

func write(Float64)

public func write(v: Float64): Unit

功能:写入 Float64 类型。

参数:

func write(Int16)

public func write(v: Int16): Unit

功能:写入 Int16 类型。

参数:

func write(Int32)

public func write(v: Int32): Unit

功能:写入 Int32 类型。

参数:

func write(Int64)

public func write(v: Int64): Unit

功能:写入 Int64 类型。

参数:

func write(Int8)

public func write(v: Int8): Unit

功能:写入 Int8 类型。

参数:

func write(Rune)

public func write(v: Rune): Unit

功能:写入 Rune 类型。

参数:

func write(String)

public func write(v: String): Unit

功能:写入字符串。

参数:

  • v: String - 待写入的字符串。

func write(UInt16)

public func write(v: UInt16): Unit

功能:写入 UInt16 类型。

参数:

func write(UInt32)

public func write(v: UInt32): Unit

功能:写入 UInt32 类型。

参数:

func write(UInt64)

public func write(v: UInt64): Unit

功能:写入 UInt64 类型。

参数:

func write(UInt8)

public func write(v: UInt8): Unit

功能:写入 UInt8 类型。

参数:

func write<T>(T) where T <: ToString

public func write<T>(v: T): Unit where T <: ToString

功能:写入 ToString 类型。

参数:

func writeln()

public func writeln(): Unit

功能:写入换行符。

func writeln(Bool)

public func writeln(v: Bool): Unit

功能:写入 Bool 类型 + 换行符。

参数:

func writeln(Float16)

public func writeln(v: Float16): Unit

功能:写入 Float16 类型 + 换行符。

参数:

func writeln(Float32)

public func writeln(v: Float32): Unit

功能:写入 Float32 类型 + 换行符。

参数:

func writeln(Float64)

public func writeln(v: Float64): Unit

功能:写入 Float64 类型 + 换行符。

参数:

func writeln(Int16)

public func writeln(v: Int16): Unit

功能:写入 Int16 类型 + 换行符。

参数:

func writeln(Int32)

public func writeln(v: Int32): Unit

功能:写入 Int32 类型 + 换行符。

参数:

func writeln(Int64)

public func writeln(v: Int64): Unit

功能:写入 Int64 类型 + 换行符。

参数:

func writeln(Int8)

public func writeln(v: Int8): Unit

功能:写入 Int8 类型 + 换行符。

参数:

func writeln(Rune)

public func writeln(v: Rune): Unit

功能:写入 Rune 类型 + 换行符。

参数:

func writeln(String)

public func writeln(v: String): Unit

功能:写入字符串 + 换行符。

参数:

  • v: String - 待写入的字符串。

func writeln(UInt16)

public func writeln(v: UInt16): Unit

功能:写入 UInt16 类型 + 换行符。

参数:

func writeln(UInt32)

public func writeln(v: UInt32): Unit

功能:写入 UInt32 类型 + 换行符。

参数:

func writeln(UInt64)

public func writeln(v: UInt64): Unit

功能:写入 UInt64 类型 + 换行符。

参数:

func writeln(UInt8)

public func writeln(v: UInt8): Unit

功能:写入 UInt8 类型 + 换行符。

参数:

func writeln<T>(T) where T <: ToString

public func writeln<T>(v: T): Unit where T <: ToString

功能:写入 ToString 类型 + 换行符。

参数:

extend<T> StringWriter<T> <: Resource where T <: Resource

extend<T> StringWriter<T> <: Resource where T <: Resource

功能:为 StringWriter 实现 Resource 接口,该类型对象可在 try-with-resource 语法上下文中实现自动资源释放。

父类型:

func close()

public func close(): Unit

功能:关闭当前流。

注意:

  • 调用此方法后不可再调用 StringWriter 的其他接口,否则会造成不可期现象。

func isClosed()

public func isClosed(): Bool

功能:判断当前流是否关闭。

返回值:

  • Bool - 如果当前流已经被关闭,返回 true,否则返回 false。

extend<T> StringWriter<T> <: Seekable where T <: Seekable

extend<T> StringWriter<T> <: Seekable where T <: Seekable

功能:为 StringWriter 实现 Seekable 接口,支持查询数据长度,移动光标等操作。

父类型:

prop length

public prop length: Int64

功能:返回当前流中的总数据量。

类型:Int64

prop position

public prop position: Int64

功能:返回当前光标位置。

类型:Int64

prop remainLength

public prop remainLength: Int64

功能:返回当前流中未读的数据量。

类型:Int64

func seek(SeekPosition)

public func seek(sp: SeekPosition): Int64

功能:移动光标到指定的位置。

说明:

  • 指定的位置不能位于流中数据头部之前。
  • 指定位置可以超过流中数据末尾。

参数:

返回值:

  • Int64 - 返回流中数据的起点到移动后位置的偏移量(以字节为单位)。

枚举

enum SeekPosition

public enum SeekPosition {
    | Begin(Int64)
    | Current(Int64)
    | End(Int64)
}

功能:该枚举类型表示光标在文件中的位置。

Begin(Int64)

Begin(Int64)

功能:表示从起点开始移动。

Current(Int64)

Current(Int64)

功能:表示从当前位置开始移动。

End(Int64)

End(Int64)

功能:表示从末尾开始移动。

异常

class ContentFormatException

public class ContentFormatException <: Exception {
    public init()
    public init(message: String)
}

功能:提供字符格式相关的异常处理。

父类型:

init()

public init()

功能:创建 ContentFormatException 实例。

init(String)

public init(message: String)

功能:根据异常信息创建 ContentFormatException 实例。

参数:

  • message: String - 异常提示信息。

class IOException

public open class IOException <: Exception {
    public init()
    public init(message: String)
}

功能:提供 IO 流相关的异常处理。

父类型:

init()

public init()

功能:创建 IOException 实例。

init(String)

public init(message: String)

功能:根据异常信息创建 IOException 实例。

参数:

  • message: String - 异常提示信息。

BufferedInputStream 示例

下面是 BufferedInputStream 从流中读取数据示例。

import std.io.*

main(): Unit {
    let arr1 = "0123456789".toArray()
    let byteBuffer = ByteBuffer()
    byteBuffer.write(arr1)
    let bufferedInputStream = BufferedInputStream(byteBuffer)
    let arr2 = Array<Byte>(20, repeat: 0)

    /* 读取流中数据,返回读取到的数据的长度 */
    let readLen = bufferedInputStream.read(arr2)
    println(String.fromUtf8(arr2[..readLen]))
}

运行结果

0123456789

BufferedOutputStream 示例

下面是 BufferedOutputStream 向流中写入数据示例。

import std.io.*

main(): Unit {
    let arr1 = "01234".toArray()
    let byteBuffer = ByteBuffer()
    byteBuffer.write(arr1)
    let bufferedInputStream = BufferedOutputStream(byteBuffer)
    let arr2 = "56789".toArray()

    /* 向流中写入数据,此时数据在外部流的缓冲区中 */
    bufferedInputStream.write(arr2)

    /* 调用 flush 函数,真正将数据写入内部流中 */
    bufferedInputStream.flush()
    println(String.fromUtf8(readToEnd(byteBuffer)))
}

运行结果

0123456789

ByteBuffer 示例

下面是 ByteBuffer 对流进行写入数据,读取数据等操作的示例。

import std.io.*

main(): Unit {
    let arr1 = "test case".toArray()
    let byteBuffer = ByteBuffer()

    /* 将 arr1 中的数据写入到流中 */
    byteBuffer.write(arr1)

    /* 读取 4 个字节的数据到 arr2 中 */
    let arr2 = Array<Byte>(4, repeat: 0)
    byteBuffer.read(arr2)
    println(String.fromUtf8(arr2))

    /* 将流的索引指向起点 */
    byteBuffer.seek(Begin(0))

    /* 读取流中全部数据 */
    let arr3 = readToEnd(byteBuffer)
    println(String.fromUtf8(arr3))

    /* 将流的索引指向字母 c */
    byteBuffer.seek(End(-4))

    /* 读取流中剩余数据 */
    let str = readString(byteBuffer)
    println(str)
}

运行结果

test
test case
case

ChainedInputStream 示例

下面是 ChainedInputStream 从绑定的流中循环读取数据示例。

import std.io.*
import std.collection.ArrayList

main(): Unit {
    const size = 2

    /* 创建两个 ByteBuffer 并写入数据 */
    let streamArr = Array<InputStream>(size, {_ => ByteBuffer()})
    for (i in 0..size) {
        match (streamArr[i]) {
            case v: OutputStream =>
                let str = "now ${i}"
                v.write(str.toArray())
            case _ => throw Exception()
        }
    }

    /* 将两个 ByteBuffer 绑定到 ChainedInputStream */
    let chainedInputStream = ChainedInputStream(streamArr)
    let res = ArrayList<Byte>()
    let buffer = Array<Byte>(20, repeat: 0)
    var readLen = chainedInputStream.read(buffer)

    /* 循环读取 chainedInputStream 中数据 */
    while (readLen != 0) {
        res.appendAll(buffer[..readLen])
        readLen = chainedInputStream.read(buffer)
    }
    println(String.fromUtf8(res.toArray()))
}

运行结果

now 0now 1

MultiOutputStream 示例

下面是 MultiOutputStream 向绑定的所有流中写入数据示例。

import std.io.*

main(): Unit {
    const size = 2

    /* 将两个 ByteBuffer 绑定到 MultiOutputStream */
    let streamArr = Array<OutputStream>(size, {_ => ByteBuffer()})
    let multiOutputStream = MultiOutputStream(streamArr)

    /* 往 MultiOutputStream 写入数据,会同时写入绑定的两个 ByteBuffer */
    multiOutputStream.write("test".toArray())

    /* 读取 ByteBuffer 中数据,验证结果 */
    for (i in 0..size) {
        match (streamArr[i]) {
            case v: ByteBuffer =>
                println(String.fromUtf8(readToEnd(v)))
            case _ => throw Exception()
        }
    }
}

运行结果

test
test

StringReader 示例

下面是 StringReader 从流中读取数据示例。

import std.io.*

main(): Unit {
    let arr1 = "012\n346789".toArray()
    let byteBuffer = ByteBuffer()
    byteBuffer.write(arr1)
    let stringReader = StringReader(byteBuffer)

    /* 读取一个字节 */
    let ch = stringReader.read()
    println(ch ?? 'a')

    /* 读取一行数据 */
    let line = stringReader.readln()
    println(line ?? "error")

    /* 读取数据直到遇到字符6 */
    let until = stringReader.readUntil(r'6')
    println(until ?? "error")

    /* 读取全部数据 */
    let all = stringReader.readToEnd()
    println(all)
}

运行结果

0
12
346
789

StringWriter 示例

下面是 StringWriter 向流中写入数据示例。

import std.io.*

main(): Unit {
    let byteBuffer = ByteBuffer()
    let stringWriter = StringWriter(byteBuffer)

    /* 写入字符串 */
    stringWriter.write("number")

    /* 写入字符串并自动转行 */
    stringWriter.writeln(" is:")

    /* 写入数字 */
    stringWriter.write(100.0f32)

    stringWriter.flush()

    println(String.fromUtf8(readToEnd(byteBuffer)))
}

运行结果

number is:
100.000000

std.log 包

功能介绍

log 包提供日志管理和打印功能。(已废弃,请使用 log 包)

API 列表

接口

接口名功能
Logger此接口用于管理和打印日志。

类名功能
SimpleLogger此类实现 Logger 接口,提供基础的日志打印和管理功能。

枚举

枚举名功能
LogLevel提供基础的日志打印和管理功能。

接口

interface Logger

public interface Logger {
    mut prop level: LogLevel
    func setOutput(output: OutputStream): Unit
    func trace(msg: String): Unit
    func debug(msg: String): Unit
    func info(msg: String): Unit
    func warn(msg: String): Unit
    func error(msg: String): Unit
    func log(level: LogLevel, msg: String): Unit
}

此接口用于管理和打印日志。

prop level

mut prop level: LogLevel

功能:获取和修改日志打印级别,只有级别小于等于该值的日志会被打印。

类型:LogLevel

func debug(String)

func debug(msg: String): Unit

功能:打印 DEBUG 级别的日志的便捷函数。

参数:

  • msg: String - 日志内容。

func error(String)

func error(msg: String): Unit

功能:打印 ERROR 级别的日志的便捷函数。

参数:

  • msg: String - 日志内容。

func info(String)

func info(msg: String): Unit

功能:打印 INFO 级别的日志的便捷函数。

参数:

  • msg: String - 日志内容。

func log(LogLevel, String)

func log(level: LogLevel, msg: String): Unit

功能:打印日志的通用函数,需指定日志级别。

参数:

func setOutput(OutputStream)

func setOutput(output: OutputStream): Unit

功能:设置日志输出流,日志将被打印到该输出流。

参数:

func trace(String)

func trace(msg: String): Unit

功能:打印 TRACE 级别的日志的便捷函数。如果设置的打印级别小于 TRACE,将忽略这条日志信息,否则打印到输出流。以下日志打印函数均使用该规则。

参数:

  • msg: String - 日志内容。

func warn(String)

func warn(msg: String): Unit

功能:打印 WARN 级别的日志的便捷函数。

参数:

  • msg: String - 日志内容。

class SimpleLogger

public class SimpleLogger <: Logger {
    public init()
    public init(name: String, level: LogLevel, output: OutputStream)
}

功能:此类实现 Logger 接口,提供基础的日志打印和管理功能。

包括自定义日志名称,控制日志打印级别,自定义输出流,默认情况下,日志名称为 “Logger”,打印级别为 INFO,输出流为 stdOut

父类型:

prop level

public mut prop level: LogLevel

功能:获取和修改日志打印级别。

类型:LogLevel

init()

public init()

功能:创建一个默认的 SimpleLogger 实例。

init(String, LogLevel, OutputStream)

public init(name: String, level: LogLevel, output: OutputStream)

功能:创建一个 SimpleLogger 实例,指定日志名称,日志打印级别和输出流。

参数:

func debug(String)

public func debug(msg: String): Unit

功能:打印 DEBUG 级别的日志的便捷函数。

参数:

  • msg: String - 日志内容。

func error(String)

public func error(msg: String): Unit

功能:打印 ERROR 级别的日志的便捷函数。

参数:

  • msg: String - 日志内容。

func flush()

public func flush(): Unit

功能:刷新输出流。

func info(String)

public func info(msg: String): Unit

功能:打印 INFO 级别的日志的便捷函数。

参数:

  • msg: String - 日志内容。

func log(LogLevel, String)

public func log(level: LogLevel, msg: String): Unit

功能:打印日志的通用函数,需指定日志级别。

参数:

func setOutput(OutputStream)

public func setOutput(output: OutputStream): Unit

功能:设置输出流,日志信息将打印到该输出流中。

参数:

func trace(String)

public func trace(msg: String): Unit

功能:打印 TRACE 级别的日志的便捷函数。

参数:

  • msg: String - 日志内容。

func warn(String)

public func warn(msg: String): Unit

功能:打印 WARN 级别的日志的便捷函数。

参数:

  • msg: String - 日志内容。

枚举

enum LogLevel

public enum LogLevel <: ToString {
    | OFF
    | ERROR
    | WARN
    | INFO
    | DEBUG
    | TRACE
    | ALL
}

功能:该枚举类表示打印级别。

定义了日志打印的七个级别,级别从低到高分别为 OFFERRORWARNINFODEBUGTRACEALL

SimpleLogger 类的实现中,指定了日志打印级别,以及每一条日志的级别,只有级别小于等于指定打印级别的日志条目会被打印到输出流中。

父类型:

ALL

ALL

功能:构造一个日志打印级别的枚举实例,等级为所有。

DEBUG

DEBUG

功能:构造一个日志打印级别的枚举实例,等级为调试。

ERROR

ERROR

功能:构造一个日志打印级别的枚举实例,等级为错误。

INFO

INFO

功能:构造一个日志打印级别的枚举实例,等级为通知。

OFF

OFF

功能:构造一个日志打印级别的枚举实例,等级为禁用。

TRACE

TRACE

功能:构造一个日志打印级别的枚举实例,等级为跟踪。

WARN

WARN

功能:构造一个日志打印级别的枚举实例,等级为警告。

func level()

public func level(): Int64

功能:获取日志级别对应的数字,OFF 为 1,ERROR 为 2,此后依次加一。

返回值:

  • Int64 - 当前的日志级别对应的数字。

func toString()

public func toString(): String

功能:获取日志级别对应的名称。

返回值:

  • String - 当前的日志级别的名称。

operator func >=(LogLevel)

public operator func >=(target: LogLevel): Bool

功能:比较日志级别高低。

参数:

  • target: LogLevel - 将当前日志级别和 target 进行比较。

返回值:

  • Bool - 如果当前日志级别大于等于 target,返回 true,否则返回 false

日志打印示例

ALL 级别日志打印

下面是 ALL 级别日志打印示例。

代码如下:

import std.log.*
main(): Int64 {
    let logger: SimpleLogger = SimpleLogger()
    logger.level = LogLevel.ALL
    logger.log(LogLevel.ALL, "============== 日志级别为 ALL================")
    logger.log(LogLevel.TRACE,
    "=============="+logger.level.toString()+"================")
    logger.log(LogLevel.OFF, "OFF 打印出来!")
    logger.log(LogLevel.ERROR, "error 打印出来!")
    logger.log(LogLevel.WARN, "warn 打印出来!")
    logger.log(LogLevel.INFO, "INFO 打印出来!")
    logger.log(LogLevel.DEBUG, "DEBUG 打印出来!")
    logger.log(LogLevel.TRACE, "trace 打印出来!")
    logger.log(LogLevel.ALL, "ALL 打印出来!")
    logger.flush()
    0
}

运行结果如下:

2021/08/05 08:20:42.692770 ALL Logger ============== 日志级别为 ALL================
2021/08/05 08:20:42.696645 TRACE Logger ==============ALL================
2021/08/05 08:20:42.700188 ERROR Logger error 打印出来!
2021/08/05 08:20:42.703576 WARN Logger warn 打印出来!
2021/08/05 08:20:42.706920 INFO Logger INFO 打印出来!
2021/08/05 08:20:42.710268 DEBUG Logger DEBUG 打印出来!
2021/08/05 08:20:42.713602 TRACE Logger trace 打印出来!
2021/08/05 08:20:42.716940 ALL Logger ALL 打印出来!

指定日志级别和输出流

以下示例前半部分指定打印级别为 ERROR,输出流为 error_log.txt 文件,后半部分指定打印级别为 WARN,输出流为 warn_log.txt 文件。

代码如下:

import std.fs.*
import std.log.*
main(): Int64 {
    let logger: SimpleLogger = SimpleLogger()

    logger.level = LogLevel.ERROR
    var s = File("./error_log.txt", OpenOption.CreateOrTruncate(false))
    logger.setOutput(s)
    logger.log(LogLevel.ERROR, "============== 日志级别为 ERROR================")
    logger.log(LogLevel.ERROR,
    "=============="+logger.level.toString()+"================")
    logger.log(LogLevel.OFF, "OFF 打印出来!")
    logger.log(LogLevel.ERROR, "error 打印出来!")
    logger.log(LogLevel.WARN, "warn 打印出来!")
    logger.log(LogLevel.INFO, "INFO 打印出来!")
    logger.log(LogLevel.DEBUG, "DEBUG 打印出来!")
    logger.log(LogLevel.TRACE, "trace 打印出来!")
    logger.log(LogLevel.ALL, "ALL 打印出来!")
    logger.flush()
    s.close()

    logger.level = LogLevel.WARN
    s = File("./warn_log.txt", OpenOption.CreateOrTruncate(false))
    logger.setOutput(s)
    logger.log(LogLevel.WARN, "============== 日志级别为 WARN================")
    logger.log(LogLevel.WARN,
    "=============="+logger.level.toString()+"================")
    logger.log(LogLevel.OFF, "OFF 打印出来!")
    logger.log(LogLevel.ERROR, "error 打印出来!")
    logger.log(LogLevel.WARN, "warn 打印出来!")
    logger.log(LogLevel.INFO, "INFO 打印出来!")
    logger.log(LogLevel.DEBUG, "DEBUG 打印出来!")
    logger.log(LogLevel.TRACE, "trace 打印出来!")
    logger.log(LogLevel.ALL, "ALL 打印出来!")
    logger.flush()
    s.close()
    0
}

运行结果如下:

$ cat error_log.txt
2021/08/05 08:28:29.667441 ERROR Logger ============== 日志级别为 ERROR================
2021/08/05 08:28:29.671402 ERROR Logger ==============ERROR================
2021/08/05 08:28:29.674891 ERROR Logger error 打印出来!
$ cat warn_log.txt
2021/08/05 08:28:29.678978 WARN Logger ============== 日志级别为 WARN================
2021/08/05 08:28:29.682635 WARN Logger ==============WARN================
2021/08/05 08:28:29.686126 ERROR Logger error 打印出来!
2021/08/05 08:28:29.689561 WARN Logger warn 打印出来!

std.math 包

功能介绍

math 包提供常见的数学运算,常数定义,浮点数处理等功能。

包括了以下能力:

  1. 科学常数与类型常数定义;
  2. 浮点数的判断,规整;
  3. 常用的位运算;
  4. 通用的数学函数,如绝对值,三角函数,指数,对数计算;
  5. 最大公约数与最小公倍数。

API 列表

函数

函数名功能
abs(Float16)求一个半精度浮点数的绝对值。
abs(Float32)求一个单精度浮点数的绝对值。
abs(Float64)求一个双精度浮点数的绝对值。
abs(Int8)求一个 8 位有符号整数的绝对值。
abs(Int16)求一个 16 位有符号整数的绝对值。
abs(Int32)求一个 32 位有符号整数的绝对值。
abs(Int64)求一个 64 位有符号整数的绝对值。
acos(Float16)计算半精度浮点数的反余弦函数值,单位为弧度。
acos(Float32)计算单精度浮点数的反余弦函数值,单位为弧度。
acos(Float64)计算双精度浮点数的反余弦函数值,单位为弧度。
acosh(Float16)计算半精度浮点数的反双曲余弦函数值。
acosh(Float32)计算单精度浮点数的反双曲余弦函数值。
acosh(Float64)计算双精度浮点数的反双曲余弦函数值。
asin(Float16)计算半精度浮点数的反正弦函数值,单位为弧度。
asin(Float32)计算单精度浮点数的反正弦函数值,单位为弧度。
asin(Float64)计算双精度浮点数的反正弦函数值,单位为弧度。
asinh(Float16)计算半精度浮点数的反双曲正弦函数值。
asinh(Float32)计算单精度浮点数的反双曲正弦函数值。
asinh(Float64)计算双精度浮点数的反双曲正弦函数值。
atan(Float16)计算半精度浮点数的反正切函数值,单位为弧度。
atan(Float32)计算单精度浮点数的反正切函数值,单位为弧度。
atan(Float64)计算双精度浮点数的反正切函数值,单位为弧度。
atanh(Float16)计算半精度浮点数的反双曲正切函数值。
atanh(Float32)计算单精度浮点数的反双曲正切函数值。
atanh(Float64)计算双精度浮点数的反双曲正切函数值。
cbrt(Float16)求半精度浮点数的立方根。
cbrt(Float32)求单精度浮点数的立方根。
cbrt(Float64)求双精度浮点数的立方根。
ceil(Float16)求半精度浮点数的向上取整值。
ceil(Float32)求单精度浮点数的向上取整值。
ceil(Float64)求双精度浮点数的向上取整值。
checkedAbs(Int8)检查并求一个 8 位有符号整数的绝对值。如果入参是 8 位有符号整数的最小值,函数返回 None;否则,返回 Some(abs(x))
checkedAbs(Int16)检查并求一个 16 位有符号整数的绝对值。如果入参是 16 位有符号整数的最小值,函数返回 None;否则,返回 Some(abs(x))
checkedAbs(Int32)检查并求一个 32 位有符号整数的绝对值。如果入参是 32 位有符号整数的最小值,函数返回 None;否则,返回 Some(abs(x))
checkedAbs(Int64)检查并求一个 64 位有符号整数的绝对值。如果入参是 64 位有符号整数的最小值,函数返回 None;否则,返回 Some(abs(x))
clamp(Float16, Float16, Float16)求浮点数的范围区间数。如果此浮点数在该范围区间则返回此浮点数;如果此浮点数小于这个范围区间,则返回该范围区间的最小值;如果此浮点数大于这个范围区间,则返回该范围区间的最大值;如果是 NaN 则返回 NaN
clamp(Float32, Float32, Float32)求浮点数的范围区间数。如果此浮点数在该范围区间则返回此浮点数;如果此浮点数小于这个范围区间,则返回该范围区间的最小值;如果此浮点数大于这个范围区间,则返回该范围区间的最大值;如果是 NaN 则返回 NaN
clamp(Float64, Float64, Float64)求浮点数的范围区间数。如果此浮点数在该范围区间则返回此浮点数;如果此浮点数小于这个范围区间,则返回该范围区间的最小值;如果此浮点数大于这个范围区间,则返回该范围区间的最大值;如果是 NaN 则返回 NaN
cos(Float16)计算半精度浮点数的余弦函数值,入参单位为弧度。
cos(Float32)计算单精度浮点数的余弦函数值,入参单位为弧度。
cos(Float64)计算双精度浮点数的余弦函数值,入参单位为弧度。
cosh(Float16)计算半精度浮点数的双曲余弦函数值。
cosh(Float32)计算单精度浮点数的双曲余弦函数值。
cosh(Float64)计算双精度浮点数的双曲余弦函数值。
countOne(Int8)求 8 位整型的二进制表达中的 1 的位的个数。
countOne(Int16)求 16 位整型的二进制表达中的 1 的位的个数。
countOne(Int32)求 32 位整型的二进制表达中的 1 的位的个数。
countOne(Int64)求 64 位整型的二进制表达中的 1 的位的个数。
countOne(UInt8)求 8 位无符号整型的二进制表达中的 1 的位的个数。
countOne(UInt16)求 16 位无符号整型的二进制表达中的 1 的位的个数。
countOne(UInt32)求 32 位无符号整型的二进制表达中的 1 的位的个数。
countOne(UInt64)求 64 位无符号整型的二进制表达中的 1 的位的个数。
erf(Float16)求半精度浮点数的误差值。
erf(Float32)求单精度浮点数的误差值。
erf(Float64)求双精度浮点数的误差值。
exp(Float16)求自然常数 e 的 x 次幂。
exp(Float32)求自然常数 e 的 x 次幂。
exp(Float64)求自然常数 e 的 x 次幂。
exp2(Float16)求 2 的 x 次幂。
exp2(Float32)求 2 的 x 次幂。
exp2(Float64)求 2 的 x 次幂。
floor(Float16)求浮点数的向下取整值。
floor(Float32)求浮点数的向下取整值。
floor(Float64)求浮点数的向下取整值。
gamma(Float16)求浮点数的 Gamma 值。
gamma(Float32)求浮点数的 Gamma 值。
gamma(Float64)求浮点数的 Gamma 值。
gcd(Int8, Int8)求两个 8 位有符号整数的最大公约数。
gcd(Int16, Int16)求两个 16 位有符号整数的最大公约数。
gcd(Int32, Int32)求两个 32 位有符号整数的最大公约数。
gcd(Int64, Int64)求两个 64 位有符号整数的最大公约数。
gcd(UInt16, UInt16)求两个 16 位无符号整数的最大公约数。
gcd(UInt32, UInt32)求两个 32 位无符号整数的最大公约数。
gcd(UInt64, UInt64)求两个 64 位无符号整数的最大公约数。
gcd(UInt8, UInt8)求两个 8 位无符号整数的最大公约数。
lcm(Int8, Int8)求两个 8 位有符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。
lcm(Int16, Int16)求两个 16 位有符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。
lcm(Int32, Int32)求两个 32 位有符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。
lcm(Int64, Int64)求两个 64 位有符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。
lcm(UInt8, UInt8)求两个 8 位无符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。
lcm(UInt16, UInt16)求两个 16 位无符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。
lcm(UInt32, UInt32)求两个 32 位无符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。
lcm(UInt64, UInt64)求两个 64 位无符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。
leadingZeros(Int8)求 8 位有符号整数的二进制表达中的从最高位算起,包含符号位,连续位为 0 的个数。如果最高位不是 0,则返回 0。
leadingZeros(Int16)求 16 位有符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。如果最高位不是 0,则返回 0。
leadingZeros(Int32)求 32 位有符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。如果最高位不是 0,则返回 0。
leadingZeros(Int64)求 64 位有符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。如果最高位不是 0,则返回 0。
leadingZeros(UInt8)求 8 位无符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。
leadingZeros(UInt16)求 16 位无符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。
leadingZeros(UInt32)求 32 位无符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。
leadingZeros(UInt64)求 64 位无符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。
log(Float16)求以 e 为底 x 的对数。
log(Float32)求以 e 为底 x 的对数。
log(Float64)求以 e 为底 x 的对数。
log10(Float16)求以 10 为底 x 的对数。
log10(Float32)求以 10 为底 x 的对数。
log10(Float64)求以 10 为底 x 的对数。
log2(Float16)求以 2 为底 x 的对数。
log2(Float32)求以 2 为底 x 的对数。
log2(Float64)求以 2 为底 x 的对数。
logBase(Float16, Float16)求以 base 为底 x 的对数。
logBase(Float32, Float32)求以 base 为底 x 的对数。
logBase(Float64, Float64)求以 base 为底 x 的对数。
pow(Float32, Float32)求浮点数 baseexponent 次幂。
pow(Float32, Int32)求浮点数 baseexponent 次幂。
pow(Float64, Float64)求浮点数 baseexponent 次幂。
pow(Float64, Int64)求浮点数 baseexponent 次幂。
reverse(UInt8)求无符号整数按位反转后的数。
reverse(UInt16)求无符号整数按位反转后的数。
reverse(UInt32)求无符号整数按位反转后的数。
reverse(UInt64)求无符号整数按位反转后的数。
rotate(Int16, Int8)求整数的按位旋转后的结果。
rotate(Int32, Int8)求整数的按位旋转后的结果。
rotate(Int64, Int8)求整数的按位旋转后的结果。
rotate(Int8, Int8)求整数的按位旋转后的结果。
rotate(UInt16, Int8)求整数的按位旋转后的结果。
rotate(UInt32, Int8)求整数的按位旋转后的结果。
rotate(UInt64, Int8)求整数的按位旋转后的结果。
rotate(UInt8, Int8)求整数的按位旋转后的结果。
round(Float16)此函数采用 IEEE-754 的向最近舍入规则,计算浮点数的舍入值。
round(Float32)此函数采用 IEEE-754 的向最近舍入规则,计算浮点数的舍入值。
round(Float64)此函数采用 IEEE-754 的向最近舍入规则,计算浮点数的舍入值。
sin(Float16)计算半精度浮点数的正弦函数值,入参单位为弧度。
sin(Float32)计算单精度浮点数的正弦函数值,入参单位为弧度。
sin(Float64)计算双精度浮点数的正弦函数值,入参单位为弧度。
sinh(Float16)计算半精度浮点数的双曲正弦函数值。
sinh(Float32)计算单精度浮点数的双曲正弦函数值。
sinh(Float64)计算双精度浮点数的双曲正弦函数值。
sqrt(Float16)求浮点数的算术平方根。
sqrt(Float32)求浮点数的算术平方根。
sqrt(Float64)求浮点数的算术平方根。
tan(Float16)计算半精度浮点数的正切函数值,入参单位为弧度。
tan(Float32)计算单精度浮点数的正切函数值,入参单位为弧度。
tan(Float64)计算双精度浮点数的正切函数值,入参单位为弧度。
tanh(Float16)计算半精度浮点数的双曲正切函数值。
tanh(Float32)计算单精度浮点数的双曲正切函数值。
tanh(Float64)计算双精度浮点数的双曲正切函数值。
trailingZeros(Int8)求 16 位有符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。
trailingZeros(Int16)求 16 位有符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。
trailingZeros(Int32)求 32 位有符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。
trailingZeros(Int64)求 64 位有符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。
trailingZeros(UInt8)求 8 位无符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。
trailingZeros(UInt16)求 16 位无符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。
trailingZeros(UInt32)求 32 位无符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。
trailingZeros(UInt64)求 64 位无符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。
trunc(Float16)求浮点数的截断取整值。
trunc(Float32)求浮点数的截断取整值。
trunc(Float64)求浮点数的截断取整值。

接口

接口名功能
MathExtension为了导出 prop 而作辅助接口,浮点数导出 PI,E 属性。

枚举

枚举功能
RoundingMode舍入规则枚举类,共包含 6 中舍入规则。除包含 IEEE 754 浮点数规定约定的 5 种舍入规则外,提供使用较多的 “四舍五入” 舍入规则。

接口

interface MathExtension

public interface MathExtension {
}

功能:为了导出 prop 而作辅助接口,浮点数导出 PI,E 属性。该辅助接口内部为空。

extend Float16 <: MathExtension

extend Float16 <: MathExtension

功能:拓展半精度浮点数以支持一些数学常数。

父类型:

static prop E

public static prop E: Float16

功能:获取半精度浮点数的自然常数。

类型:Float16

static prop PI

public static prop PI: Float16

功能:获取半精度浮点数的圆周率常数。

类型:Float16

extend Float32 <: MathExtension

extend Float32 <: MathExtension

功能:拓展单精度浮点数以支持一些数学常数。

父类型:

static prop E

public static prop E: Float32

功能:获取单精度浮点数的自然常数。

类型:Float32

static prop PI

public static prop PI: Float32

功能:获取单精度浮点数的圆周率常数。

类型:Float32

extend Float64 <: MathExtension

extend Float64 <: MathExtension

功能:拓展双精度浮点数以支持一些数学常数。

父类型:

static prop E

public static prop E: Float64

功能:获取双精度浮点数的自然常数。

类型:Float64

static prop PI

public static prop PI: Float64

功能:获取双精度浮点数的圆周率常数。

类型:Float64

函数

func abs(Float16)

public func abs(x: Float16): Float16

功能:求一个半精度浮点数的绝对值。

参数:

  • x: Float16 - 传入的半精度浮点数。

返回值:

  • Float16 - 返回传入参数的绝对值。

示例:

import std.math.abs

main() {
    let n: Float16 = -23.0
    let abs = abs(n)
    println(abs)
}

运行结果:

23.000000

func abs(Float32)

public func abs(x: Float32): Float32

功能:求一个单精度浮点数的绝对值。

参数:

  • x: Float32 - 传入的单精度浮点数。

返回值:

  • Float32 - 返回传入参数的绝对值。

示例:

import std.math.abs

main() {
    let n: Float32 = -23.0
    let abs = abs(n)
    println(abs)
}

运行结果:

23.000000

func abs(Float64)

public func abs(x: Float64): Float64

功能:求一个双精度浮点数的绝对值。

参数:

  • x: Float64 - 传入的双精度浮点数。

返回值:

  • Float64 - 返回传入参数的绝对值。

示例:

import std.math.abs

main() {
    let n: Float64 = -23.0
    let abs = abs(n)
    println(abs)
}

运行结果:

23.000000

func abs(Int16)

public func abs(x: Int16): Int16

功能:求一个 16 位有符号整数的绝对值。

参数:

  • x: Int16 - 传入的 16 位有符号整数。

返回值:

  • Int16 - 返回传入参数的绝对值。

异常:

  • OverflowException - 当输入参数是有符号整数的最小值,抛出异常。

示例:

import std.math.abs

main() {
    let n: Int16 = -23
    let abs = abs(n)
    println(abs)
}

运行结果:

23

func abs(Int32)

public func abs(x: Int32): Int32

功能:求一个 32 位有符号整数的绝对值。

参数:

  • x: Int32 - 传入的 32 位有符号整数。

返回值:

  • Int32 - 返回传入参数的绝对值。

异常:

  • OverflowException - 当输入参数是有符号整数的最小值,抛出异常。

示例:

import std.math.abs

main() {
    let n: Int32 = -23
    let abs = abs(n)
    println(abs)
}

运行结果:

23

func abs(Int64)

public func abs(x: Int64): Int64

功能:求一个 64 位有符号整数的绝对值。

参数:

  • x: Int64 - 传入的 64 位有符号整数。

返回值:

  • Int64 - 返回传入参数的绝对值。

异常:

  • OverflowException - 当输入参数是有符号整数的最小值,抛出异常。

示例:

import std.math.abs

main() {
    let n: Int64 = -23
    let abs = abs(n)
    println(abs)
}

运行结果:

23

func abs(Int8)

public func abs(x: Int8): Int8

功能:求一个 8 位有符号整数的绝对值。

参数:

  • x: Int8 - 传入的 8 位有符号整数。

返回值:

  • Int8 - 返回传入参数的绝对值。

异常:

  • OverflowException - 当输入参数是有符号整数的最小值,抛出异常。

示例:

import std.math.abs

main() {
    let n: Int8 = -23
    let abs = abs(n)
    println(abs)
}

运行结果:

23

func acos(Float16)

public func acos(x: Float16): Float16

功能:计算半精度浮点数的反余弦函数值。

参数:

  • x: Float16 - 传入的半精度浮点数。-1.0 <= x <= 1.0。

返回值:

  • Float16 - 返回传入参数的反余弦函数值,单位为弧度。

异常:

示例:

import std.math.acos

main() {
    let n: Float16 = 1.0
    let acos = acos(n)
    println(acos)
}

运行结果:

0.000000

func acos(Float32)

public func acos(x: Float32): Float32

功能:计算单精度浮点数的反余弦函数值。

参数:

  • x: Float32 - 传入的单精度浮点数。-1.0 <= x <= 1.0。

返回值:

  • Float32 - 返回传入参数的反余弦函数值,单位为弧度。

异常:

示例:

import std.math.acos

main() {
    let n: Float32 = 1.0
    let acos = acos(n)
    println(acos)
}

运行结果:

0.000000

func acos(Float64)

public func acos(x: Float64): Float64

功能:计算双精度浮点数的反余弦函数值。

参数:

  • x: Float64 - 传入的双精度浮点数。-1.0 <= x <= 1.0。

返回值:

  • Float64 - 返回传入参数的反余弦函数值,单位为弧度。

异常:

示例:

import std.math.acos

main() {
    let n: Float64 = 1.0
    let acos = acos(n)
    println(acos)
}

运行结果:

0.000000

func acosh(Float16)

public func acosh(x: Float16): Float16

功能:计算半精度浮点数的反双曲余弦函数值。

参数:

  • x: Float16 - 传入的半精度浮点数。

返回值:

  • Float16 - 返回传入参数的反双曲余弦函数值。x >= 1.0。

异常:

示例:

import std.math.acosh

main() {
    let n: Float16 = 1.0
    let acosh = acosh(n)
    println(acosh)
}

运行结果:

0.000000

func acosh(Float32)

public func acosh(x: Float32): Float32

功能:计算单精度浮点数的反双曲余弦函数值。

参数:

  • x: Float32 - 传入的单精度浮点数。x >= 1.0。

返回值:

  • Float32 - 返回传入参数的反双曲余弦函数值。

异常:

示例:

import std.math.acosh

main() {
    let n: Float32 = 1.0
    let acosh = acosh(n)
    println(acosh)
}

运行结果:

0.000000

func acosh(Float64)

public func acosh(x: Float64): Float64

功能:计算双精度浮点数的反双曲余弦函数值。

参数:

  • x: Float64 - 传入的双精度浮点数。x >= 1.0。

返回值:

  • Float64 - 返回传入参数的反双曲余弦函数值。

异常:

示例:

import std.math.acosh

main() {
    let n: Float64 = 1.0
    let acosh = acosh(n)
    println(acosh)
}

运行结果:

0.000000

func asin(Float16)

public func asin(x: Float16): Float16

功能:计算半精度浮点数的反正弦函数值。

参数:

  • x: Float16 - 传入的半精度浮点数。-1.0 <= x <= 1.0。

返回值:

  • Float16 - 返回传入参数的反正弦函数值,单位为弧度。

异常:

示例:

import std.math.asin

main() {
    let n: Float16 = 0.0
    let asin = asin(n)
    println(asin)
}

运行结果:

0.000000

func asin(Float32)

public func asin(x: Float32): Float32

功能:计算单精度浮点数的反正弦函数值。

参数:

  • x: Float32 - 传入的单精度浮点数。-1.0 <= x <= 1.0。

返回值:

  • Float32 - 返回传入参数的反正弦函数值,单位为弧度。

异常:

示例:

import std.math.asin

main() {
    let n: Float32 = 0.0
    let asin = asin(n)
    println(asin)
}

运行结果:

0.000000

func asin(Float64)

public func asin(x: Float64): Float64

功能:计算双精度浮点数的反正弦函数值。

参数:

  • x: Float64 - 传入的双精度浮点数。-1.0 <= x <= 1.0。

返回值:

  • Float64 - 返回传入参数的反正弦函数值,单位为弧度。

异常:

示例:

import std.math.asin

main() {
    let n: Float64 = 0.0
    let asin = asin(n)
    println(asin)
}

运行结果:

0.000000

func asinh(Float16)

public func asinh(x: Float16): Float16

功能:计算半精度浮点数的反双曲正弦函数值。

参数:

  • x: Float16 - 传入的半精度浮点数。

返回值:

  • Float16 - 返回传入参数的反双曲正弦函数值。

示例:

import std.math.asinh

main() {
    let n: Float16 = 0.0
    let asinh = asinh(n)
    println(asinh)
}

运行结果:

0.000000

func asinh(Float32)

public func asinh(x: Float32): Float32

功能:计算单精度浮点数的反双曲正弦函数值。

参数:

  • x: Float32 - 传入的单精度浮点数。

返回值:

  • Float32 - 返回传入参数的反双曲正弦函数值。

示例:

import std.math.asinh

main() {
    let n: Float32 = 0.0
    let asinh = asinh(n)
    println(asinh)
}

运行结果:

0.000000

func asinh(Float64)

public func asinh(x: Float64): Float64

功能:计算双精度浮点数的反双曲正弦函数值。

参数:

  • x: Float64 - 传入的双精度浮点数。

返回值:

  • Float64 - 返回传入参数的反双曲正弦函数值。

示例:

import std.math.asinh

main() {
    let n: Float64 = 0.0
    let asinh = asinh(n)
    println(asinh)
}

运行结果:

0.000000

func atan(Float16)

public func atan(x: Float16): Float16

功能:计算半精度浮点数的反正切函数值。

参数:

  • x: Float16 - 传入的半精度浮点数。

返回值:

  • Float16 - 返回传入参数的反正切函数值,单位为弧度。

示例:

import std.math.atan

main() {
    let n: Float16 = 0.0
    let atan = atan(n)
    println(atan)
}

运行结果:

0.000000

func atan(Float32)

public func atan(x: Float32): Float32

功能:计算单精度浮点数的反正切函数值。

参数:

  • x: Float32 - 传入的单精度浮点数。

返回值:

  • Float32 - 返回传入参数的反正切函数值,单位为弧度。

示例:

import std.math.atan

main() {
    let n: Float32 = 0.0
    let atan = atan(n)
    println(atan)
}

运行结果:

0.000000

func atan(Float64)

public func atan(x: Float64): Float64

功能:计算双精度浮点数的反正切函数值。

参数:

  • x: Float64 - 传入的双精度浮点数。

返回值:

  • Float64 - 返回传入参数的反正切函数值,单位为弧度。

示例:

import std.math.atan

main() {
    let n: Float64 = 0.0
    let atan = atan(n)
    println(atan)
}

运行结果:

0.000000

func atanh(Float16)

public func atanh(x: Float16): Float16

功能:计算半精度浮点数的反双曲正切函数值。

参数:

  • x: Float16 - 传入的半精度浮点数。-1.0 < x < 1.0。

返回值:

  • Float16 - 返回传入参数的反双曲正切函数值。

异常:

示例:

import std.math.atanh

main() {
    let n: Float16 = 0.0
    let atanh = atanh(n)
    println(atanh)
}

运行结果:

0.000000

func atanh(Float32)

public func atanh(x: Float32): Float32

功能:计算单精度浮点数的反双曲正切函数值。

参数:

  • x: Float32 - 传入的单精度浮点数。-1.0 < x < 1.0。

返回值:

  • Float32 - 返回传入参数的反双曲正切函数值。

异常:

示例:

import std.math.atanh

main() {
    let n: Float32 = 0.0
    let atanh = atanh(n)
    println(atanh)
}

运行结果:

0.000000

func atanh(Float64)

public func atanh(x: Float64): Float64

功能:计算双精度浮点数的反双曲正切函数值。

参数:

  • x: Float64 - 传入的双精度浮点数。-1.0 < x < 1.0。

返回值:

  • Float64 - 返回传入参数的反双曲正切函数值。

异常:

示例:

import std.math.atanh

main() {
    let n: Float64 = 0.0
    let atanh = atanh(n)
    println(atanh)
}

运行结果:

0.000000

func cbrt(Float16)

public func cbrt(x: Float16): Float16

功能:求半精度浮点数的立方根。

参数:

  • x: Float16 - 传入的半精度浮点数。

返回值:

  • Float16 - 返回传入参数的立方根。

示例:

import std.math.cbrt

main() {
    let n: Float16 = -1000.0
    let cbrt = cbrt(n)
    println(cbrt)
}

运行结果:

-10.000000

func cbrt(Float32)

public func cbrt(x: Float32): Float32

功能:求单精度浮点数的立方根。

参数:

  • x: Float32 - 传入的单精度浮点数。

返回值:

  • Float32 - 返回传入参数的立方根。

示例:

import std.math.cbrt

main() {
    let n: Float32 = -1000.0
    let cbrt = cbrt(n)
    println(cbrt)
}

运行结果:

-10.000000

func cbrt(Float64)

public func cbrt(x: Float64): Float64

功能:求双精度浮点数的立方根。

参数:

  • x: Float64 - 传入的双精度浮点数。

返回值:

  • Float64 - 返回传入参数的立方根。

示例:

import std.math.cbrt

main() {
    let n: Float64 = -1000.0
    let cbrt = cbrt(n)
    println(cbrt)
}

运行结果:

-10.000000

func ceil(Float16)

public func ceil(x: Float16): Float16

功能:求半精度浮点数的向上取整值。

参数:

  • x: Float16 - 传入的半精度浮点数。

返回值:

  • Float16 - 返回传入参数的向上取整值。

示例:

import std.math.ceil

main() {
    let n: Float16 = 0.7
    let ceil = ceil(n)
    println(ceil)
}

运行结果:

1.000000

func ceil(Float32)

public func ceil(x: Float32): Float32

功能:求单精度浮点数的向上取整值。

参数:

  • x: Float32 - 传入的单精度浮点数。

返回值:

  • Float32 - 返回传入参数的向上取整值。

示例:

import std.math.ceil

main() {
    let n: Float32 = 0.7
    let ceil = ceil(n)
    println(ceil)
}

运行结果:

1.000000

func ceil(Float64)

public func ceil(x: Float64): Float64

功能:求双精度浮点数的向上取整值。

参数:

  • x: Float64 - 传入的双精度浮点数。

返回值:

  • Float64 - 返回传入参数的向上取整值。

示例:

import std.math.ceil

main() {
    let n: Float64 = 0.7
    let ceil = ceil(n)
    println(ceil)
}

运行结果:

1.000000

func checkedAbs(Int16)

public func checkedAbs(x: Int16): Option<Int16>

功能:求一个 16 位有符号整数的绝对值。如果入参是 16 位有符号整数的最小值,函数返回 None;否则,返回 Some(abs(x))。

参数:

  • x: Int16 - 传入的 16 位有符号整数。

返回值:

示例:

import std.math.checkedAbs

main() {
    let n: Int16 = -23
    let checkedAbs = checkedAbs(n)
    println(checkedAbs)
}

运行结果:

Some(23)

func checkedAbs(Int32)

public func checkedAbs(x: Int32): Option<Int32>

功能:求一个 32 位有符号整数的绝对值。如果入参是 32 位有符号整数的最小值,函数返回 None;否则,返回 Some(abs(x))。

参数:

  • x: Int32 - 传入的 32 位有符号整数。

返回值:

示例:

import std.math.checkedAbs

main() {
    let n: Int32 = -23
    let checkedAbs = checkedAbs(n)
    println(checkedAbs)
}

运行结果:

Some(23)

func checkedAbs(Int64)

public func checkedAbs(x: Int64): Option<Int64>

功能:求一个 64 位有符号整数的绝对值。如果入参是 64 位有符号整数的最小值,函数返回 None;否则,返回 Some(abs(x))。

参数:

  • x: Int64 - 传入的 64 位有符号整数。

返回值:

示例:

import std.math.checkedAbs

main() {
    let n: Int64 = -23
    let checkedAbs = checkedAbs(n)
    println(checkedAbs)
}

运行结果:

Some(23)

func checkedAbs(Int8)

public func checkedAbs(x: Int8): Option<Int8>

功能:求一个 8 位有符号整数的绝对值。如果入参是 8 位有符号整数的最小值,函数返回 None;否则,返回 Some(abs(x))。

参数:

  • x: Int8 - 传入的 8 位有符号整数。

返回值:

示例:

import std.math.checkedAbs

main() {
    let n: Int8 = -23
    let checkedAbs = checkedAbs(n)
    println(checkedAbs)
}

运行结果:

Some(23)

func clamp(Float16, Float16, Float16)

public func clamp(v: Float16, min: Float16, max: Float16): Float16

功能:求浮点数的范围区间数。如果此浮点数在该范围区间则返回此浮点数;如果此浮点数小于这个范围区间,则返回该范围区间的最小值;如果此浮点数大于这个范围区间,则返回该范围区间的最大值;如果是 NaN 则返回 NaN

参数:

  • v: Float16 - 传入一个浮点数。
  • min: Float16 - 指定的最小值。
  • max: Float16 - 指定的最大值。

返回值:

  • Float16 - 如果 vminmax 之间则返回 v;如果 v 小于等于 min 则返回 min;如果 v 大于等于 max,则返回 max;如果是 NaN 则返回 NaN

异常:

示例:

import std.math.clamp

main() {
    let n: Float16 = -23.0
    let clamp = clamp(n, -100.0, 100.0)
    println(clamp)
}

运行结果:

-23.000000

func clamp(Float32, Float32, Float32)

public func clamp(v: Float32, min: Float32, max: Float32): Float32

功能:求浮点数的范围区间数。如果此浮点数在该范围区间则返回此浮点数;如果此浮点数小于这个范围区间,则返回该范围区间的最小值;如果此浮点数大于这个范围区间,则返回该范围区间的最大值;如果是 NaN 则返回 NaN

参数:

  • v: Float32 - 传入一个浮点数。
  • min: Float32 - 指定的最小值。
  • max: Float32 - 指定的最大值。

返回值:

  • Float32 - 如果 vminmax 之间则返回 v;如果 v 小于等于 min 则返回 min;如果 v 大于等于 max,则返回 max;如果是 NaN 则返回 NaN

异常:

示例:

import std.math.clamp

main() {
    let n: Float32 = -23.0
    let clamp = clamp(n, -100.0, 100.0)
    println(clamp)
}

运行结果:

-23.000000

func clamp(Float64, Float64, Float64)

public func clamp(v: Float64, min: Float64, max: Float64): Float64

功能:求浮点数的范围区间数。如果此浮点数在该范围区间则返回此浮点数;如果此浮点数小于这个范围区间,则返回该范围区间的最小值;如果此浮点数大于这个范围区间,则返回该范围区间的最大值;如果是 NaN 则返回 NaN

参数:

  • v: Float64 - 传入一个浮点数。
  • min: Float64 - 指定的最小值。
  • max: Float64 - 指定的最大值。

返回值:

  • Float64 - 如果 vminmax 之间则返回 v;如果 v 小于等于 min 则返回 min;如果 v 大于等于 max,则返回 max;如果是 NaN 则返回 NaN

异常:

示例:

import std.math.clamp

main() {
    let n: Float64 = -23.0
    let clamp = clamp(n, -100.0, 100.0)
    println(clamp)
}

运行结果:

-23.000000

func cos(Float16)

public func cos(x: Float16): Float16

功能:计算半精度浮点数的余弦函数值。

参数:

  • x: Float16 - 传入的半精度浮点数,入参单位为弧度。

返回值:

  • Float16 - 返回传入参数的余弦函数值。

示例:

import std.math.cos

main() {
    let n: Float16 = 3.14159265
    let cos = cos(n)
    println(cos)
}

运行结果:

-1.000000

func cos(Float32)

public func cos(x: Float32): Float32

功能:计算单精度浮点数的余弦函数值。

参数:

  • x: Float32 - 传入的单精度浮点数,入参单位为弧度。

返回值:

  • Float32 - 返回传入参数的余弦函数值。

示例:

import std.math.cos

main() {
    let n: Float32 = 3.14159265
    let cos = cos(n)
    println(cos)
}

运行结果:

-1.000000

func cos(Float64)

public func cos(x: Float64): Float64

功能:计算双精度浮点数的余弦函数值。

参数:

  • x: Float64 - 传入的双精度浮点数,入参单位为弧度。

返回值:

  • Float64 - 返回传入参数的余弦函数值。

示例:

import std.math.cos

main() {
    let n: Float64 = 3.14159265
    let cos = cos(n)
    println(cos)
}

运行结果:

-1.000000

func cosh(Float16)

public func cosh(x: Float16): Float16

功能:计算半精度浮点数的双曲余弦函数值。

参数:

  • x: Float16 - 传入的半精度浮点数。

返回值:

  • Float16 - 返回传入参数的双曲余弦函数值。

示例:

import std.math.cosh

main() {
    let n: Float16 = 0.0
    let cosh = cosh(n)
    println(cosh)
}

运行结果:

1.000000

func cosh(Float32)

public func cosh(x: Float32): Float32

功能:计算单精度浮点数的双曲余弦函数值。

参数:

  • x: Float32 - 传入的单精度浮点数。

返回值:

  • Float32 - 返回传入参数的双曲余弦函数值。

示例:

import std.math.cosh

main() {
    let n: Float32 = 0.0
    let cosh = cosh(n)
    println(cosh)
}

运行结果:

1.000000

func cosh(Float64)

public func cosh(x: Float64): Float64

功能:计算双精度浮点数的双曲余弦函数值。

参数:

  • x: Float64 - 传入的双精度浮点数。

返回值:

  • Float64 - 返回传入参数的双曲余弦函数值。

示例:

import std.math.cosh

main() {
    let n: Float64 = 0.0
    let cosh = cosh(n)
    println(cosh)
}

运行结果:

1.000000

func countOne(Int16)

public func countOne(x: Int16): Int8

功能:求 16 位整型的二进制表达中 1 的个数。

参数:

  • x: Int16 - 传入的 16 位有符号整数。

返回值:

  • Int8 - 返回传入参数的二进制表达中的 1 的位的个数。

示例:

import std.math.countOne

main() {
    let n: Int16 = 15
    let countOne = countOne(n)
    println(countOne)
}

运行结果:

4

func countOne(Int32)

public func countOne(x: Int32): Int8

功能:求 32 位整型的二进制表达中 1 的个数。

参数:

  • x: Int32 - 传入的 32 位有符号整数。

返回值:

  • Int8 - 返回传入参数的二进制表达中的 1 的位的个数。

示例:

import std.math.countOne

main() {
    let n: Int32 = 15
    let countOne = countOne(n)
    println(countOne)
}

运行结果:

4

func countOne(Int64)

public func countOne(x: Int64): Int8

功能:求 64 位整型的二进制表达中 1 的个数。

参数:

  • x: Int64 - 传入的 64 位有符号整数。

返回值:

  • Int8 - 返回传入参数的二进制表达中的 1 的位的个数。

示例:

import std.math.countOne

main() {
    let n: Int64 = 15
    let countOne = countOne(n)
    println(countOne)
}

运行结果:

4

func countOne(Int8)

public func countOne(x: Int8): Int8

功能:求 8 位整型的二进制表达中 1 的个数。

参数:

  • x: Int8 - 传入的 8 位有符号整数。

返回值:

  • Int8 - 返回传入参数的二进制表达中的 1 的位的个数。

示例:

import std.math.countOne

main() {
    let n: Int8 = 15
    let countOne = countOne(n)
    println(countOne)
}

运行结果:

4

func countOne(UInt16)

public func countOne(x: UInt16): Int8

功能:求 16 位无符号整型的二进制表达中的 1 的位的个数。

参数:

  • x: UInt16 - 传入的 16 位无符号整数。

返回值:

  • Int8 - 返回传入参数的二进制表达中的 1 的位的个数。

示例:

import std.math.countOne

main() {
    let n: UInt16 = 15
    let countOne = countOne(n)
    println(countOne)
}

运行结果:

4

func countOne(UInt32)

public func countOne(x: UInt32): Int8

功能:求 32 位无符号整型的二进制表达中的 1 的位的个数。

参数:

  • x: UInt32 - 传入的 32 位无符号整数。

返回值:

  • Int8 - 返回传入参数的二进制表达中的 1 的位的个数。

示例:

import std.math.countOne

main() {
    let n: UInt32 = 15
    let countOne = countOne(n)
    println(countOne)
}

运行结果:

4

func countOne(UInt64)

public func countOne(x: UInt64): Int8

功能:求 64 位无符号整型的二进制表达中的 1 的位的个数。

参数:

  • x: UInt64 - 传入的 64 位无符号整数。

返回值:

  • Int8 - 返回传入参数的二进制表达中的 1 的位的个数。

示例:

import std.math.countOne

main() {
    let n: UInt64 = 15
    let countOne = countOne(n)
    println(countOne)
}

运行结果:

4

func countOne(UInt8)

public func countOne(x: UInt8): Int8

功能:求 8 位无符号整型的二进制表达中的 1 的位的个数。

参数:

  • x: UInt8 - 传入的 8 位无符号整数。

返回值:

  • Int8 - 返回传入参数的二进制表达中的 1 的位的个数。

示例:

import std.math.countOne

main() {
    let n: UInt8 = 15
    let countOne = countOne(n)
    println(countOne)
}

运行结果:

4

func erf(Float16)

public func erf(x: Float16): Float16

功能:求半精度浮点数的误差值。相关定义是:$$erf(x) = \frac{2}{\sqrt{\pi}}\int_0^xe^{-t^2}dt$$

参数:

  • x: Float16 - 传入的半精度浮点数。

返回值:

  • Float16 - 返回传入参数的半精度浮点数的误差值。

示例:

import std.math.erf

main() {
    let n: Float16 = 5.0
    let erf = erf(n)
    println(erf)
}

运行结果:

1.000000

func erf(Float32)

public func erf(x: Float32): Float32

功能:求单精度浮点数的误差值。相关定义是:$$erf(x) = \frac{2}{\sqrt{\pi}}\int_0^xe^{-t^2}dt$$

参数:

  • x: Float32 - 传入的单精度浮点数。

返回值:

  • Float32 - 返回传入参数的单精度浮点数的误差值。

示例:

import std.math.erf

main() {
    let n: Float32 = 5.0
    let erf = erf(n)
    println(erf)
}

运行结果:

1.000000

func erf(Float64)

public func erf(x: Float64): Float64

功能:求双精度浮点数的误差值。相关定义是:$$erf(x) = \frac{2}{\sqrt{\pi}}\int_0^xe^{-t^2}dt$$

参数:

  • x: Float64 - 传入的双精度浮点数。

返回值:

  • Float64 - 返回传入参数的双精度浮点数的误差值。

示例:

import std.math.erf

main() {
    let n: Float64 = 5.0
    let erf = erf(n)
    println(erf)
}

运行结果:

1.000000

func exp(Float16)

public func exp(x: Float16): Float16

功能:求自然常数 e 的 x 次幂。

参数:

  • x: Float16 - 传入的半精度浮点数指数。

返回值:

  • Float16 - 返回自然常数 e 的 x 次幂。

示例:

import std.math.exp

main() {
    let n: Float16 = 1.0
    let exp = exp(n)
    println(exp)
}

运行结果:

2.718750

func exp(Float32)

public func exp(x: Float32): Float32

功能:求自然常数 e 的 x 次幂。

参数:

  • x: Float32 - 传入的单精度浮点数指数。

返回值:

  • Float32 - 返回自然常数 e 的 x 次幂。

示例:

import std.math.exp

main() {
    let n: Float32 = 1.0
    let exp = exp(n)
    println(exp)
}

运行结果:

2.718282

func exp(Float64)

public func exp(x: Float64): Float64

功能:求自然常数 e 的 x 次幂。

参数:

  • x: Float64 - 传入的双精度浮点数指数。

返回值:

  • Float64 - 返回自然常数 e 的 x 次幂。

示例:

import std.math.exp

main() {
    let n: Float64 = 1.0
    let exp = exp(n)
    println(exp)
}

运行结果:

2.718282

func exp2(Float16)

public func exp2(x: Float16): Float16

功能:求 2 的 x 次幂。

参数:

  • x: Float16 - 传入的半精度浮点数指数。

返回值:

  • Float16 - 返回 2 的 x 次幂。

示例:

import std.math.exp2

main() {
    let n: Float16 = 10.0
    let exp2 = exp2(n)
    println(exp2)
}

运行结果:

1024.000000

func exp2(Float32)

public func exp2(x: Float32): Float32

功能:求 2 的 x 次幂。

参数:

  • x: Float32 - 传入的单精度浮点数指数。

返回值:

  • Float32 - 返回 2 的 x 次幂。

示例:

import std.math.exp2

main() {
    let n: Float32 = 10.0
    let exp2 = exp2(n)
    println(exp2)
}

运行结果:

1024.000000

func exp2(Float64)

public func exp2(x: Float64): Float64

功能:求 2 的 x 次幂。

参数:

  • x: Float64 - 传入的双精度浮点数指数。

返回值:

  • Float64 - 返回 2 的 x 次幂。

示例:

import std.math.exp2

main() {
    let n: Float64 = 10.0
    let exp = exp2(n)
    println(exp)
}

运行结果:

1024.000000

func floor(Float16)

public func floor(x: Float16): Float16

功能:求浮点数的向下取整值。

参数:

  • x: Float16 - 传入的需要向下取整的半精度浮点数。

返回值:

  • Float16 - 返回传入浮点数的向下取整值。

示例:

import std.math.floor

main() {
    let n: Float16 = 10.5
    let floor = floor(n)
    println(floor)
}

运行结果:

10.000000

func floor(Float32)

public func floor(x: Float32): Float32

功能:求浮点数的向下取整值。

参数:

  • x: Float32 - 传入的需要向下取整的单精度浮点数。

返回值:

  • Float32 - 返回传入浮点数的向下取整值。

示例:

import std.math.floor

main() {
    let n: Float32 = 10.5
    let floor = floor(n)
    println(floor)
}

运行结果:

10.000000

func floor(Float64)

public func floor(x: Float64): Float64

功能:求浮点数的向下取整值。

参数:

  • x: Float64 - 传入的需要向下取整的双精度浮点数。

返回值:

  • Float64 - 返回传入浮点数的向下取整值。

示例:

import std.math.floor

main() {
    let n: Float64 = 10.5
    let floor = floor(n)
    println(floor)
}

运行结果:

10.000000

func gamma(Float16)

public func gamma(x: Float16): Float16

功能:求浮点数的伽马函数值,该函数是阶乘概念在实数上的推广。

参数:

  • x: Float16 - 传入的需要求伽马函数值的半精度浮点数。

返回值:

  • Float16 - 返回传入浮点数的伽马函数值。

示例:

import std.math.gamma

main() {
    let n: Float16 = -1.1
    let gamma = gamma(n)
    println(gamma)
}

运行结果:

9.750000

func gamma(Float32)

public func gamma(x: Float32): Float32

功能:求浮点数的伽马函数值,该函数是阶乘概念在实数上的推广。

参数:

  • x: Float32 - 传入的需要求伽马函数值的单精度浮点数。

返回值:

  • Float32 - 返回传入浮点数的伽马函数值。

示例:

import std.math.gamma

main() {
    let n: Float32 = -1.1
    let gamma = gamma(n)
    println(gamma)
}

运行结果:

9.714804

func gamma(Float64)

public func gamma(x: Float64): Float64

功能:求浮点数的伽马函数值,该函数是阶乘概念在实数上的推广。

参数:

  • x: Float64 - 传入的需要求伽马函数值的双精度浮点数。

返回值:

  • Float64 - 返回传入浮点数的伽马函数值。

示例:

import std.math.gamma

main() {
    let n: Float64 = -1.1
    let gamma = gamma(n)
    println(gamma)
}

运行结果:

9.714806

func gcd(Int16, Int16)

public func gcd(x: Int16, y: Int16): Int16

功能:求两个 16 位有符号整数的最大公约数。

参数:

  • x: Int16 - 传入的需要计算最大公约数的第一个整数。
  • y: Int16 - 传入的需要计算最大公约数的第二个整数。

返回值:

  • Int16 - 返回两个整数的最大公约数。

异常:

  • IllegalArgumentException - 当两参数都为有符号整数最小值,或一个参数为有符号整数的最小值且另一个参数为 0 时,抛出异常。

示例:

import std.math.gcd

main() {
    let x: Int16 = 15
    let y: Int16 = 9
    let gcd = gcd(x, y)
    println(gcd)
}

运行结果:

3

func gcd(Int32, Int32)

public func gcd(x: Int32, y: Int32): Int32

功能:求两个 32 位有符号整数的最大公约数。

参数:

  • x: Int32 - 传入的需要计算最大公约数的第一个整数。
  • y: Int32 - 传入的需要计算最大公约数的第二个整数。

返回值:

  • Int32 - 返回两个整数的最大公约数。

异常:

  • IllegalArgumentException - 当两参数都为有符号整数最小值,或一个参数为有符号整数的最小值且另一个参数为 0 时,抛出异常。

示例:

import std.math.gcd

main() {
    let x: Int32 = 15
    let y: Int32 = 9
    let gcd = gcd(x, y)
    println(gcd)
}

运行结果:

3

func gcd(Int64, Int64)

public func gcd(x: Int64, y: Int64): Int64

功能:求两个 64 位有符号整数的最大公约数。

参数:

  • x: Int64 - 传入的需要计算最大公约数的第一个整数。
  • y: Int64 - 传入的需要计算最大公约数的第二个整数。

返回值:

  • Int64 - 返回两个整数的最大公约数。

异常:

  • IllegalArgumentException - 当两参数都为有符号整数最小值,或一个参数为有符号整数的最小值且另一个参数为 0 时,抛出异常。

示例:

import std.math.gcd

main() {
    let x: Int64 = 15
    let y: Int64 = 9
    let gcd = gcd(x, y)
    println(gcd)
}

运行结果:

3

func gcd(Int8, Int8)

public func gcd(x: Int8, y: Int8): Int8

功能:求两个 8 位有符号整数的最大公约数。

参数:

  • x: Int8 - 传入的需要计算最大公约数的第一个整数。
  • y: Int8 - 传入的需要计算最大公约数的第二个整数。

返回值:

  • Int8 - 返回两个整数的最大公约数。

异常:

  • IllegalArgumentException - 当两参数都为有符号整数最小值,或一个参数为有符号整数的最小值且另一个参数为 0 时,抛出异常。

示例:

import std.math.gcd

main() {
    let x: Int8 = 15
    let y: Int8= 9
    let gcd = gcd(x, y)
    println(gcd)
}

运行结果:

3

func gcd(UInt16, UInt16)

public func gcd(x: UInt16, y: UInt16): UInt16

功能:求两个 16 位无符号整数的最大公约数。

参数:

  • x: UInt16 - 传入的需要计算最大公约数的第一个整数。
  • y: UInt16 - 传入的需要计算最大公约数的第二个整数。

返回值:

  • UInt16 - 返回两个整数的最大公约数。

示例:

import std.math.gcd

main() {
    let x: UInt16 = 15
    let y: UInt16 = 9
    let gcd = gcd(x, y)
    println(gcd)
}

运行结果:

3

func gcd(UInt32, UInt32)

public func gcd(x: UInt32, y: UInt32): UInt32

功能:求两个 32 位无符号整数的最大公约数。

参数:

  • x: UInt32 - 传入的需要计算最大公约数的第一个整数。
  • y: UInt32 - 传入的需要计算最大公约数的第二个整数。

返回值:

  • UInt32 - 返回两个整数的最大公约数。

示例:

import std.math.gcd

main() {
    let x: UInt32 = 15
    let y: UInt32 = 9
    let gcd = gcd(x, y)
    println(gcd)
}

运行结果:

3

func gcd(UInt64, UInt64)

public func gcd(x: UInt64, y: UInt64): UInt64

功能:求两个 64 位无符号整数的最大公约数。

参数:

  • x: UInt64 - 传入的需要计算最大公约数的第一个整数。
  • y: UInt64 - 传入的需要计算最大公约数的第二个整数。

返回值:

  • UInt64 - 返回两个整数的最大公约数。

示例:

import std.math.gcd

main() {
    let x: UInt64 = 15
    let y: UInt64 = 9
    let gcd = gcd(x, y)
    println(gcd)
}

运行结果:

3

func gcd(UInt8, UInt8)

public func gcd(x: UInt8, y: UInt8): UInt8

功能:求两个 8 位无符号整数的最大公约数。

参数:

  • x: UInt8 - 传入的需要计算最大公约数的第一个整数。
  • y: UInt8 - 传入的需要计算最大公约数的第二个整数。

返回值:

  • UInt8 - 返回两个整数的最大公约数。

示例:

import std.math.gcd

main() {
    let x: UInt8 = 15
    let y: UInt8= 9
    let gcd = gcd(x, y)
    println(gcd)
}

运行结果:

3

func lcm(Int16, Int16)

public func lcm(x: Int16, y: Int16): Int16

功能:求两个 16 位有符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。

参数:

  • x: Int16 - 传入的需要计算最小公倍数的第一个整数。
  • y: Int16 - 传入的需要计算最小公倍数的第二个整数。

返回值:

  • Int16 - 返回两个整数的最小的非负的公倍数,当入参有 0 时才返回 0。

异常:

示例:

import std.math.lcm

main() {
    let x: Int16 = -15
    let y: Int16 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

45

func lcm(Int32, Int32)

public func lcm(x: Int32, y: Int32): Int32

功能:求两个 32 位有符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。

参数:

  • x: Int32 - 传入的需要计算最小公倍数的第一个整数。
  • y: Int32 - 传入的需要计算最小公倍数的第二个整数。

返回值:

  • Int32 - 返回两个整数的最小的非负的公倍数,当入参有 0 时才返回 0。

异常:

示例:

import std.math.lcm

main() {
    let x: Int32 = -15
    let y: Int32 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

45

func lcm(Int64, Int64)

public func lcm(x: Int64, y: Int64): Int64

功能:求两个 64 位有符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。

参数:

  • x: Int64 - 传入的需要计算最小公倍数的第一个整数。
  • y: Int64 - 传入的需要计算最小公倍数的第二个整数。

返回值:

  • Int64 - 返回两个整数的最小的非负的公倍数,当入参有 0 时才返回 0。

异常:

示例:

import std.math.lcm

main() {
    let x: Int64 = 15
    let y: Int64 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

45

func lcm(Int8, Int8)

public func lcm(x: Int8, y: Int8): Int8

功能:求两个 8 位有符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。

参数:

  • x: Int8 - 传入的需要计算最小公倍数的第一个整数。
  • y: Int8 - 传入的需要计算最小公倍数的第二个整数。

返回值:

  • Int8 - 返回两个整数的最小的非负的公倍数,当入参有 0 时才返回 0。

异常:

示例:

import std.math.lcm

main() {
    let x: Int8 = 15
    let y: Int8= 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

45

func lcm(UInt16, UInt16)

public func lcm(x: UInt16, y: UInt16): UInt16

功能:求两个 16 位无符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。

参数:

  • x: UInt16 - 传入的需要计算最小公倍数的第一个整数。
  • y: UInt16 - 传入的需要计算最小公倍数的第二个整数。

返回值:

  • UInt16 - 返回两个整数的最小的非负的公倍数,当入参有 0 时才返回 0。

异常:

示例:

import std.math.lcm

main() {
    let x: UInt16 = 15
    let y: UInt16 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

45

func lcm(UInt32, UInt32)

public func lcm(x: UInt32, y: UInt32): UInt32

功能:求两个 32 位无符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。

参数:

  • x: UInt32 - 传入的需要计算最小公倍数的第一个整数。
  • y: UInt32 - 传入的需要计算最小公倍数的第二个整数。

返回值:

  • UInt32 - 返回两个整数的最小的非负的公倍数,当入参有 0 时才返回 0。

异常:

示例:

import std.math.lcm

main() {
    let x: UInt32 = 15
    let y: UInt32 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

45

func lcm(UInt64, UInt64)

public func lcm(x: UInt64, y: UInt64): UInt64

功能:求两个 64 位无符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。

参数:

  • x: UInt64 - 传入的需要计算最小公倍数的第一个整数。
  • y: UInt64 - 传入的需要计算最小公倍数的第二个整数。

返回值:

  • UInt64 - 返回两个整数的最小的非负的公倍数,当入参有 0 时才返回 0。

异常:

示例:

import std.math.lcm

main() {
    let x: UInt64 = 15
    let y: UInt64 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

45

func lcm(UInt8, UInt8)

public func lcm(x: UInt8, y: UInt8): UInt8

功能:求两个 8 位无符号整数的最小的非负的公倍数,当入参有 0 时才返回 0。

参数:

  • x: UInt8 - 传入的需要计算最小公倍数的第一个整数。
  • y: UInt8 - 传入的需要计算最小公倍数的第二个整数。

返回值:

  • UInt8 - 返回两个整数的最小的非负的公倍数,当入参有 0 时才返回 0。

异常:

示例:

import std.math.lcm

main() {
    let x: UInt8 = 15
    let y: UInt8= 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

45

func leadingZeros(Int16)

public func leadingZeros(x: Int16): Int8

功能:求 16 位有符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。如果最高位不是 0,则返回 0。

参数:

  • x: Int16 - 需要求前导 0 的整数。

返回值:

  • Int8 - 返回前导 0 的位数。

示例:

import std.math.leadingZeros

main() {
    let x: Int16 = 512
    let leadingZeros = leadingZeros(x)
    println(leadingZeros)
}

运行结果:

6

func leadingZeros(Int32)

public func leadingZeros(x: Int32): Int8

功能:求 32 位有符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。如果最高位不是 0,则返回 0。

参数:

  • x: Int32 - 需要求前导 0 的整数。

返回值:

  • Int8 - 返回前导 0 的位数。

示例:

import std.math.leadingZeros

main() {
    let x: Int32 = 512
    let leadingZeros = leadingZeros(x)
    println(leadingZeros)
}

运行结果:

22

func leadingZeros(Int64)

public func leadingZeros(x: Int64): Int8

功能:求 64 位有符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。如果最高位不是 0,则返回 0。

参数:

  • x: Int64 - 需要求前导 0 的整数。

返回值:

  • Int8 - 返回前导 0 的位数。

示例:

import std.math.leadingZeros

main() {
    let x: Int64 = 512
    let leadingZeros = leadingZeros(x)
    println(leadingZeros)
}

运行结果:

54

func leadingZeros(Int8)

public func leadingZeros(x: Int8): Int8

功能:求 8 位有符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。如果最高位不是 0,则返回 0。

参数:

  • x: Int8 - 需要求前导 0 的整数。

返回值:

  • Int8 - 返回前导 0 的位数。

示例:

import std.math.leadingZeros

main() {
    let x: Int8 = 4
    let leadingZeros = leadingZeros(x)
    println(leadingZeros)
}

运行结果:

5

func leadingZeros(UInt16)

public func leadingZeros(x: UInt16): Int8

功能:求 16 位无符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。如果最高位不是 0,则返回 0。

参数:

  • x: UInt16 - 需要求前导 0 的整数。

返回值:

  • Int8 - 返回前导 0 的位数。

示例:

import std.math.leadingZeros

main() {
    let x: UInt16 = 512
    let leadingZeros = leadingZeros(x)
    println(leadingZeros)
}

运行结果:

6

func leadingZeros(UInt32)

public func leadingZeros(x: UInt32): Int8

功能:求 32 位无符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。如果最高位不是 0,则返回 0。

参数:

  • x: UInt32 - 需要求前导 0 的整数。

返回值:

  • Int8 - 返回前导 0 的位数。

示例:

import std.math.leadingZeros

main() {
    let x: UInt32 = 512
    let leadingZeros = leadingZeros(x)
    println(leadingZeros)
}

运行结果:

22

func leadingZeros(UInt64)

public func leadingZeros(x: UInt64): Int8

功能:求 64 位无符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。如果最高位不是 0,则返回 0。

参数:

  • x: UInt64 - 需要求前导 0 的整数。

返回值:

  • Int8 - 返回前导 0 的位数。

示例:

import std.math.leadingZeros

main() {
    let x: UInt64 = 512
    let leadingZeros = leadingZeros(x)
    println(leadingZeros)
}

运行结果:

54

func leadingZeros(UInt8)

public func leadingZeros(x: UInt8): Int8

功能:求 8 位无符号整数的二进制表达中的从最高位算起,连续位为 0 的个数。如果最高位不是 0,则返回 0。

参数:

  • x: UInt8 - 需要求前导 0 的整数。

返回值:

  • Int8 - 返回前导 0 的位数。

示例:

import std.math.leadingZeros

main() {
    let x: UInt8 = 64
    let leadingZeros = leadingZeros(x)
    println(leadingZeros)
}

运行结果:

1

func log(Float16)

public func log(x: Float16): Float16

功能:求以 e 为底 x 的对数。

参数:

返回值:

  • Float16 - 返回以 e 为底 x 的对数。

说明:

返回值存在如下特殊场景:

  • 如果传入 x 小于 0 或为 NaN,返回 NaN
  • 如果传入 x 等于 0,返回 -Inf
  • 如果传入 xInf,返回 Inf

示例:

import std.math.log

main() {
    let x: Float16 = 2.718282
    let log = log(x)
    println(log)
}

运行结果:

1.000000

func log(Float32)

public func log(x: Float32): Float32

功能:求以 e 为底 x 的对数。

参数:

返回值:

  • Float32 - 返回以 e 为底 x 的对数。

说明:

返回值存在如下特殊场景:

  • 如果传入 x 小于 0 或为 NaN,返回 NaN
  • 如果传入 x 等于 0,返回 -Inf
  • 如果传入 xInf,返回 Inf

示例:

import std.math.log

main() {
    let x: Float32 = 2.718282
    let log = log(x)
    println(log)
}

运行结果:

1.000000

func log(Float64)

public func log(x: Float64): Float64

功能:求以 e 为底 x 的对数。

参数:

返回值:

  • Float64 - 返回以 e 为底 x 的对数。

说明:

返回值存在如下特殊场景:

  • 如果传入 x 小于 0 或为 NaN,返回 NaN
  • 如果传入 x 等于 0,返回 -Inf
  • 如果传入 xInf,返回 Inf

示例:

import std.math.log

main() {
    let x: Float64 = 2.718282
    let log = log(x)
    println(log)
}

运行结果:

1.000000

func log10(Float16)

public func log10(x: Float16): Float16

功能:求以 10 为底 x 的对数。

参数:

返回值:

  • Float16 - 返回以 10 为底 x 的对数。

说明:

返回值存在如下特殊场景:

  • 如果传入 x 小于 0 或为 NaN,返回 NaN
  • 如果传入 x 等于 0,返回 -Inf
  • 如果传入 xInf,返回 Inf

示例:

import std.math.log10

main() {
    let x: Float16 = 1000.0
    let log10 = log10(x)
    println(log10)
}

运行结果:

3.000000

func log10(Float32)

public func log10(x: Float32): Float32

功能:求以 10 为底 x 的对数。

参数:

返回值:

  • Float32 - 返回以 10 为底 x 的对数。

说明:

返回值存在如下特殊场景:

  • 如果传入 x 小于 0 或为 NaN,返回 NaN
  • 如果传入 x 等于 0,返回 -Inf
  • 如果传入 xInf,返回 Inf

示例:

import std.math.log10

main() {
    let x: Float32 = 1000.0
    let log10 = log10(x)
    println(log10)
}

运行结果:

3.000000

func log10(Float64)

public func log10(x: Float64): Float64

功能:求以 10 为底 x 的对数。

参数:

返回值:

  • Float64 - 返回以 10 为底 x 的对数。

说明:

返回值存在如下特殊场景:

  • 如果传入 x 小于 0 或为 NaN,返回 NaN
  • 如果传入 x 等于 0,返回 -Inf
  • 如果传入 xInf,返回 Inf

示例:

import std.math.log10

main() {
    let x: Float64 = 1000.0
    let log10 = log10(x)
    println(log10)
}

运行结果:

3.000000

func log2(Float16)

public func log2(x: Float16): Float16

功能:求以 2 为底 x 的对数。

参数:

返回值:

  • Float16 - 返回以 2 为底 x 的对数。

说明:

返回值存在如下特殊场景:

  • 如果传入 x 小于 0 或为 NaN,返回 NaN
  • 如果传入 x 等于 0,返回 -Inf
  • 如果传入 xInf,返回 Inf

示例:

import std.math.log2

main() {
    let x: Float16 = 1024.0
    let log2 = log2(x)
    println(log2)
}

运行结果:

10.000000

func log2(Float32)

public func log2(x: Float32): Float32

功能:求以 2 为底 x 的对数。

参数:

返回值:

  • Float32 - 返回以 2 为底 x 的对数。

说明:

返回值存在如下特殊场景:

  • 如果传入 x 小于 0 或为 NaN,返回 NaN
  • 如果传入 x 等于 0,返回 -Inf
  • 如果传入 xInf,返回 Inf

示例:

import std.math.log2

main() {
    let x: Float32 = 1024.0
    let log2 = log2(x)
    println(log2)
}

运行结果:

10.000000

func log2(Float64)

public func log2(x: Float64): Float64

功能:求以 2 为底 x 的对数。

参数:

返回值:

  • Float64 - 返回以 2 为底 x 的对数。

说明:

返回值存在如下特殊场景:

  • 如果传入 x 小于 0 或为 NaN,返回 NaN
  • 如果传入 x 等于 0,返回 -Inf
  • 如果传入 xInf,返回 Inf

示例:

import std.math.log2

main() {
    let x: Float64 = 1024.0
    let log2 = log2(x)
    println(log2)
}

运行结果:

10.000000

func logBase(Float16, Float16)

public func logBase(x: Float16, base: Float16): Float16

功能:求以 base 为底 x 的对数。

参数:

  • x: Float16 - 真数。真数需要大于 0。
  • base: Float16 - 底数。底数需要大于 0,且不能为 1。

返回值:

  • Float16 - 返回以以 base 为底 x 的对数。

异常:

示例:

import std.math.logBase

main() {
    let x: Float16 = 512.0
    let base: Float16 = 2.0
    let logBase = logBase(x, base)
    println(logBase)
}

运行结果:

9.000000

func logBase(Float32, Float32)

public func logBase(x: Float32, base: Float32): Float32

功能:求以 base 为底 x 的对数。

参数:

  • x: Float32 - 真数。真数需要大于 0。
  • base: Float32 - 底数。底数需要大于 0,且不能为 1。

返回值:

  • Float32 - 返回以以 base 为底 x 的对数。

异常:

示例:

import std.math.logBase

main() {
    let x: Float32 = 1024.0
    let base: Float32 = 2.0
    let logBase = logBase(x, base)
    println(logBase)
}

运行结果:

10.000000

func logBase(Float64, Float64)

public func logBase(x: Float64, base: Float64): Float64

功能:求以 base 为底 x 的对数。

参数:

  • x: Float64 - 真数。真数需要大于 0。
  • base: Float64 - 底数。底数需要大于 0,且不能为 1。

返回值:

  • Float64 - 返回以以 base 为底 x 的对数。

异常:

示例:

import std.math.logBase

main() {
    let x: Float64 = 1024.0
    let base: Float64 = 2.0
    let logBase = logBase(x, base)
    println(logBase)
}

运行结果:

10.000000

func pow(Float32, Float32)

public func pow(base: Float32, exponent: Float32): Float32

功能:求浮点数 baseexponent 次幂。

参数:

返回值:

  • Float32 - 返回传入浮点数 baseexponent 次幂。如果值不存在,则返回 nan

示例:

import std.math.pow

main() {
    let base: Float32 = -1.0
    let exponent: Float32 = 0.5
    let pow = pow(base, exponent)
    println(pow)
}

运行结果:

nan

func pow(Float32, Int32)

public func pow(base: Float32, exponent: Int32): Float32

功能:求浮点数 baseexponent 次幂。

参数:

返回值:

  • Float32 - 返回传入浮点数 baseexponent 次幂。

示例:

import std.math.pow

main() {
    let base: Float32 = -1.0
    let exponent: Int32 = 2
    let pow = pow(base, exponent)
    println(pow)
}

运行结果:

1.000000

func pow(Float64, Float64)

public func pow(base: Float64, exponent: Float64): Float64

功能:求浮点数 baseexponent 次幂。

参数:

返回值:

  • Float64 - 返回传入浮点数 baseexponent 次幂。如果值不存在,则返回 nan

示例:

import std.math.pow

main() {
    let base: Float64 = -1.0
    let exponent: Float64 = 0.5
    let pow = pow(base, exponent)
    println(pow)
}

运行结果:

nan

func pow(Float64, Int64)

public func pow(base: Float64, exponent: Int64): Float64

功能:求浮点数 baseexponent 次幂。

参数:

返回值:

  • Float64 - 返回传入浮点数 baseexponent 次幂。

示例:

import std.math.pow

main() {
    let base: Float64 = -1.0
    let exponent: Int64 = 2
    let pow = pow(base, exponent)
    println(pow)
}

运行结果:

1.000000

func reverse(UInt16)

public func reverse(x: UInt16): UInt16

功能:求无符号整数按位反转后的数。

参数:

  • x: UInt16 - 需要进行反转的无符号整数。

返回值:

  • UInt16 - 返回反转后的无符号数。

示例:

import std.math.reverse

main() {
    let n: UInt16 = 0x8000
    let reverse = reverse(n)
    println(reverse)
}

运行结果:

1

func reverse(UInt32)

public func reverse(x: UInt32): UInt32

功能:求无符号整数按位反转后的数。

参数:

  • x: UInt32 - 需要进行反转的无符号整数。

返回值:

  • UInt32 - 返回反转后的无符号数。

示例:

import std.math.reverse

main() {
    let n: UInt32 = 0x8000_0000
    let reverse = reverse(n)
    println(reverse)
}

运行结果:

1

func reverse(UInt64)

public func reverse(x: UInt64): UInt64

功能:求无符号整数按位反转后的数。

参数:

  • x: UInt64 - 需要进行反转的无符号整数。

返回值:

  • UInt64 - 返回反转后的无符号数。

示例:

import std.math.reverse

main() {
    let n: UInt64 = 0x8000_0000_0000_0000
    let reverse = reverse(n)
    println(reverse)
}

运行结果:

1

func reverse(UInt8)

public func reverse(x: UInt8): UInt8

功能:求无符号整数按位反转后的数。

参数:

  • x: UInt8 - 需要进行反转的无符号整数。

返回值:

  • UInt8 - 返回反转后的无符号数。

示例:

import std.math.reverse

main() {
    let n: UInt8 = 0x80
    let reverse = reverse(n)
    println(reverse)
}

运行结果:

1

func rotate(Int16, Int8)

public func rotate(num: Int16, d: Int8): Int16

功能:求整数的按位旋转后的结果。

参数:

  • num: Int16 - 传入一个整数。
  • d: Int8 - 旋转位数,负数右移,正数左移。

返回值:

  • Int16 - 返回旋转后的整数。

示例:

import std.math.rotate

main() {
    let n: Int16 = 1
    let rotate = rotate(n, 2)
    println(rotate)
}

运行结果:

4

func rotate(Int32, Int8)

public func rotate(num: Int32, d: Int8): Int32

功能:求整数的按位旋转后的结果。

参数:

  • num: Int32 - 传入一个整数。
  • d: Int8 - 旋转位数,负数右移,正数左移。

返回值:

  • Int32 - 返回旋转后的整数。

示例:

import std.math.rotate

main() {
    let n: Int32 = 1
    let rotate = rotate(n, 2)
    println(rotate)
}

运行结果:

4

func rotate(Int64, Int8)

public func rotate(num: Int64, d: Int8): Int64

功能:求整数的按位旋转后的结果。

参数:

  • num: Int64 - 传入一个整数。
  • d: Int8 - 旋转位数,负数右移,正数左移。

返回值:

  • Int64 - 返回旋转后的整数。

示例:

import std.math.rotate

main() {
    let n: Int64 = 1
    let rotate = rotate(n, 2)
    println(rotate)
}

运行结果:

4

func rotate(Int8, Int8)

public func rotate(num: Int8, d: Int8): Int8

功能:求整数的按位旋转后的结果。

参数:

  • num: Int8 - 传入一个整数。
  • d: Int8 - 旋转位数,负数右移,正数左移。

返回值:

  • Int8 - 返回旋转后的整数。

示例:

import std.math.rotate

main() {
    let n: Int8 = 1
    let rotate = rotate(n, 2)
    println(rotate)
}

运行结果:

4

func rotate(UInt16, Int8)

public func rotate(num: UInt16, d: Int8): UInt16

功能:求整数的按位旋转后的结果。

参数:

  • num: UInt16 - 传入一个整数。
  • d: Int8 - 旋转位数,负数右移,正数左移。

返回值:

  • UInt16 - 返回旋转后的整数。

示例:

import std.math.rotate

main() {
    let n: UInt16 = 1
    let rotate = rotate(n, 2)
    println(rotate)
}

运行结果:

4

func rotate(UInt32, Int8)

public func rotate(num: UInt32, d: Int8): UInt32

功能:求整数的按位旋转后的结果。

参数:

  • num: UInt32 - 传入一个整数。
  • d: Int8 - 旋转位数,负数右移,正数左移。

返回值:

  • UInt32 - 返回旋转后的整数。

示例:

import std.math.rotate

main() {
    let n: UInt32 = 1
    let rotate = rotate(n, 2)
    println(rotate)
}

运行结果:

4

func rotate(UInt64, Int8)

public func rotate(num: UInt64, d: Int8): UInt64

功能:求整数的按位旋转后的结果。

参数:

  • num: UInt64 - 传入一个整数。
  • d: Int8 - 旋转位数,负数右移,正数左移。

返回值:

  • UInt64 - 返回旋转后的整数。

示例:

import std.math.rotate

main() {
    let n: UInt64 = 1
    let rotate = rotate(n, 2)
    println(rotate)
}

运行结果:

4

func rotate(UInt8, Int8)

public func rotate(num: UInt8, d: Int8): UInt8

功能:求整数的按位旋转后的结果。

参数:

  • num: UInt8 - 传入一个整数。
  • d: Int8 - 旋转位数,负数右移,正数左移。

返回值:

  • UInt8 - 返回旋转后的整数。

示例:

import std.math.rotate

main() {
    let n: UInt8 = 1
    let rotate = rotate(n, 2)
    println(rotate)
}

运行结果:

4

func round(Float16)

public func round(x: Float16): Float16

功能:此函数采用 IEEE-754 的向最近舍入规则,计算浮点数的舍入值。如果该浮点数有两个最近整数,则向偶数舍入。

参数:

  • x: Float16 - 需要计算舍入值的浮点数。

返回值:

  • Float16 - 返回浮点数向最近整数方向的舍入值。如果该浮点数有两个最近整数,则返回向偶数舍入值。

示例:

import std.math.round

main() {
    let n: Float16 = 1.5
    let round = round(n)
    println(round)
}

运行结果:

2.000000

func round(Float32)

public func round(x: Float32): Float32

功能:此函数采用 IEEE-754 的向最近舍入规则,计算浮点数的舍入值。如果该浮点数有两个最近整数,则向偶数舍入。

参数:

  • x: Float32 - 需要计算舍入值的浮点数。

返回值:

  • Float32 - 返回浮点数向最近整数方向的舍入值。如果该浮点数有两个最近整数,则返回向偶数舍入值。

示例:

import std.math.round

main() {
    let n: Float32 = 1.5
    let round = round(n)
    println(round)
}

运行结果:

2.000000

func round(Float64)

public func round(x: Float64): Float64

功能:此函数采用 IEEE-754 的向最近舍入规则,计算浮点数的舍入值。如果该浮点数有两个最近整数,则向偶数舍入。

参数:

  • x: Float64 - 需要计算舍入值的浮点数。

返回值:

  • Float64 - 返回浮点数向最近整数方向的舍入值。如果该浮点数有两个最近整数,则返回向偶数舍入值。

示例:

import std.math.round

main() {
    let n: Float64 = 1.5
    let round = round(n)
    println(round)
}

运行结果:

2.000000

func sin(Float16)

public func sin(x: Float16): Float16

功能:计算半精度浮点数的正弦函数值。

参数:

  • x: Float16 - 传入的半精度浮点数,入参单位为弧度。

返回值:

  • Float16 - 返回传入参数的正弦函数值。

示例:

import std.math.sin

main() {
    let n: Float16 = 3.1415926/2.0
    let sin = sin(n)
    println(sin)
}

运行结果:

1.000000

func sin(Float32)

public func sin(x: Float32): Float32

功能:计算单精度浮点数的正弦函数值。

参数:

  • x: Float32 - 传入的单精度浮点数,入参单位为弧度。

返回值:

  • Float32 - 返回传入参数的正弦函数值。

示例:

import std.math.sin

main() {
    let n: Float32 = 3.1415926/2.0
    let sin = sin(n)
    println(sin)
}

运行结果:

1.000000

func sin(Float64)

public func sin(x: Float64): Float64

功能:计算双精度浮点数的正弦函数值。

参数:

  • x: Float64 - 传入的双精度浮点数,入参单位为弧度。

返回值:

  • Float64 - 返回传入参数的正弦函数值。

示例:

import std.math.sin

main() {
    let n: Float64 = 3.1415926/2.0
    let sin = sin(n)
    println(sin)
}

运行结果:

1.000000

func sinh(Float16)

public func sinh(x: Float16): Float16

功能:计算半精度浮点数的双曲正弦函数值。

参数:

  • x: Float16 - 传入的半精度浮点数。

返回值:

  • Float16 - 返回传入参数的双曲正弦函数值。

示例:

import std.math.sinh

main() {
    let n: Float16 = 0.0
    let sinh = sinh(n)
    println(sinh)
}

运行结果:

0.000000

func sinh(Float32)

public func sinh(x: Float32): Float32

功能:计算单精度浮点数的双曲正弦函数值。

参数:

  • x: Float32 - 传入的单精度浮点数。

返回值:

  • Float32 - 返回传入参数的双曲正弦函数值。

示例:

import std.math.sinh

main() {
    let n: Float32 = 0.0
    let sinh = sinh(n)
    println(sinh)
}

运行结果:

0.000000

func sinh(Float64)

public func sinh(x: Float64): Float64

功能:计算双精度浮点数的双曲正弦函数值。

参数:

  • x: Float64 - 传入的双精度浮点数。

返回值:

  • Float64 - 返回传入参数的双曲正弦函数值。

示例:

import std.math.sinh

main() {
    let n: Float64 = 0.0
    let sinh = sinh(n)
    println(sinh)
}

运行结果:

0.000000

func sqrt(Float16)

public func sqrt(x: Float16): Float16

功能:求浮点数的算术平方根。

参数:

  • x: Float16 - 需要计算算数平方根的浮点数。x 需要大于等于 0。

返回值:

  • Float16 - 返回传入的浮点数的算术平方根。

异常:

示例:

import std.math.sqrt

main() {
    let n: Float16 = 16.0
    let sqrt = sqrt(n)
    println(sqrt)
}

运行结果:

4.000000

func sqrt(Float32)

public func sqrt(x: Float32): Float32

功能:求浮点数的算术平方根。

参数:

  • x: Float32 - 需要计算算数平方根的浮点数。x 需要大于等于 0。

返回值:

  • Float32 - 返回传入的浮点数的算术平方根。

异常:

示例:

import std.math.sqrt

main() {
    let n: Float32 = 16.0
    let sqrt = sqrt(n)
    println(sqrt)
}

运行结果:

4.000000

func sqrt(Float64)

public func sqrt(x: Float64): Float64

功能:求浮点数的算术平方根。

参数:

  • x: Float64 - 需要计算算数平方根的浮点数。x 需要大于等于 0。

返回值:

  • Float64 - 返回传入的浮点数的算术平方根。

异常:

示例:

import std.math.sqrt

main() {
    let n: Float64 = 16.0
    let sqrt = sqrt(n)
    println(sqrt)
}

运行结果:

4.000000

func tan(Float16)

public func tan(x: Float16): Float16

功能:计算半精度浮点数的正切函数值。

参数:

  • x: Float16 - 传入的半精度浮点数,入参单位为弧度。

返回值:

  • Float16 - 返回传入参数的正切函数值。

示例:

import std.math.tan

main() {
    let n: Float16 = 0.0
    let tan = tan(n)
    println(tan)
}

运行结果:

0.000000

func tan(Float32)

public func tan(x: Float32): Float32

功能:计算单精度浮点数的正切函数值。

参数:

  • x: Float32 - 传入的单精度浮点数,入参单位为弧度。

返回值:

  • Float32 - 返回传入参数的正切函数值。

示例:

import std.math.tan

main() {
    let n: Float32 = 0.0
    let tan = tan(n)
    println(tan)
}

运行结果:

0.000000

func tan(Float64)

public func tan(x: Float64): Float64

功能:计算双精度浮点数的正切函数值。

参数:

  • x: Float64 - 传入的双精度浮点数,入参单位为弧度。

返回值:

  • Float64 - 返回传入参数的正切函数值。

示例:

import std.math.tan

main() {
    let n: Float64 = 0.0
    let tan = tan(n)
    println(tan)
}

运行结果:

0.000000

func tanh(Float16)

public func tanh(x: Float16): Float16

功能:计算半精度浮点数的双曲正切函数值。

参数:

  • x: Float16 - 传入的半精度浮点数。

返回值:

  • Float16 - 返回传入参数的双曲正切函数值。

示例:

import std.math.tanh

main() {
    let n: Float16 = 0.0
    let tanh = tanh(n)
    println(tanh)
}

运行结果:

0.000000

func tanh(Float32)

public func tanh(x: Float32): Float32

功能:计算单精度浮点数的双曲正切函数值。

参数:

  • x: Float32 - 传入的单精度浮点数。

返回值:

  • Float32 - 返回传入参数的双曲正切函数值。

示例:

import std.math.tanh

main() {
    let n: Float32 = 0.0
    let tanh = tanh(n)
    println(tanh)
}

运行结果:

0.000000

func tanh(Float64)

public func tanh(x: Float64): Float64

功能:计算双精度浮点数的双曲正切函数值。

参数:

  • x: Float64 - 传入的双精度浮点数。

返回值:

  • Float64 - 返回传入参数的双曲正切函数值。

示例:

import std.math.tanh

main() {
    let n: Float64 = 0.0
    let tanh = tanh(n)
    println(tanh)
}

运行结果:

0.000000

func trailingZeros(Int16)

public func trailingZeros(x: Int16): Int8

功能:求 16 位有符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。

参数:

  • x: Int16 - 需要求后置 0 的整数。

返回值:

  • Int8 - 后置 0 的位数。

示例:

import std.math.trailingZeros

main() {
    let x: Int16 = 512
    let trailingZeros = trailingZeros(x)
    println(trailingZeros)
}

运行结果:

9

func trailingZeros(Int32)

public func trailingZeros(x: Int32): Int8

功能:求 32 位有符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。

参数:

  • x: Int32 - 需要求后置 0 的整数。

返回值:

  • Int8 - 后置 0 的位数。

示例:

import std.math.trailingZeros

main() {
    let x: Int32 = 512
    let trailingZeros = trailingZeros(x)
    println(trailingZeros)
}

运行结果:

9

func trailingZeros(Int64)

public func trailingZeros(x: Int64): Int8

功能:求 64 位有符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。

参数:

  • x: Int64 - 需要求后置 0 的整数。

返回值:

  • Int8 - 后置 0 的位数。

示例:

import std.math.trailingZeros

main() {
    let x: Int64 = 512
    let trailingZeros = trailingZeros(x)
    println(trailingZeros)
}

运行结果:

9

func trailingZeros(Int8)

public func trailingZeros(x: Int8): Int8

功能:求 16 位有符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。

参数:

  • x: Int8 - 需要求后置 0 的整数。

返回值:

  • Int8 - 后置 0 的位数。

示例:

import std.math.trailingZeros

main() {
    let x: Int8 = 64
    let trailingZeros = trailingZeros(x)
    println(trailingZeros)
}

运行结果:

6

func trailingZeros(UInt16)

public func trailingZeros(x: UInt16): Int8

功能:求 16 位无符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。

参数:

  • x: UInt16 - 需要求后置 0 的整数。

返回值:

  • Int8 - 后置 0 的位数。

示例:

import std.math.trailingZeros

main() {
    let x: UInt16 = 512
    let trailingZeros = trailingZeros(x)
    println(trailingZeros)
}

运行结果:

9

func trailingZeros(UInt32)

public func trailingZeros(x: UInt32): Int8

功能:求 32 位无符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。

参数:

  • x: UInt32 - 需要求后置 0 的整数。

返回值:

  • Int8 - 后置 0 的位数。

示例:

import std.math.trailingZeros

main() {
    let x: UInt32 = 512
    let trailingZeros = trailingZeros(x)
    println(trailingZeros)
}

运行结果:

9

func trailingZeros(UInt64)

public func trailingZeros(x: UInt64): Int8

功能:求 64 位无符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。

参数:

  • x: UInt64 - 需要求后置 0 的整数。

返回值:

  • Int8 - 后置 0 的位数。

示例:

import std.math.trailingZeros

main() {
    let x: UInt64 = 512
    let trailingZeros = trailingZeros(x)
    println(trailingZeros)
}

运行结果:

9

func trailingZeros(UInt8)

public func trailingZeros(x: UInt8): Int8

功能:求 8 位无符号整数的二进制表达中的从最低位算起,连续位为 0 的个数。如果最低位不是 0,则返回 0。

参数:

  • x: UInt8 - 需要求后置 0 的整数。

返回值:

  • Int8 - 后置 0 的位数。

示例:

import std.math.trailingZeros

main() {
    let x: UInt8 = 64
    let trailingZeros = trailingZeros(x)
    println(trailingZeros)
}

运行结果:

6

func trunc(Float16)

public func trunc(x: Float16): Float16

功能:求浮点数的截断取整值。

参数:

  • x: Float16 - 需要截断取整的浮点数。

返回值:

  • Float16 - 返回传入浮点数截断取整后的值。

示例:

import std.math.trunc

main() {
    let x: Float16 = 64.555566
    let trunc = trunc(x)
    println(trunc)
}

运行结果:

64.000000

func trunc(Float32)

public func trunc(x: Float32): Float32

功能:求浮点数的截断取整值。

参数:

  • x: Float32 - 需要截断取整的浮点数。

返回值:

  • Float32 - 返回传入浮点数截断取整后的值。

示例:

import std.math.trunc

main() {
    let x: Float32 = 64.555566
    let trunc = trunc(x)
    println(trunc)
}

运行结果:

64.000000

func trunc(Float64)

public func trunc(x: Float64): Float64

功能:求浮点数的截断取整值。

参数:

  • x: Float64 - 需要截断取整的浮点数。

返回值:

  • Float64 - 返回传入浮点数截断取整后的值。

示例:

import std.math.trunc

main() {
    let x: Float64 = 64.555566
    let trunc = trunc(x)
    println(trunc)
}

运行结果:

64.000000

枚举

enum RoundingMode

public enum RoundingMode {
    | CEILING
    | DOWN
    | FLOOR
    | HALF_EVEN
    | HALF_UP
    | UP
}

舍入规则枚举类,共包含 6 中舍入规则。除包含 IEEE 754 浮点数规定约定的 5 种舍入规则外,提供使用较多的 “四舍五入” 舍入规则。

十进制数UPDOWNCEILINGFLOORHALF_UPHALF_EVEN
7.5878788
4.5545454
-1.1-2-1-1-2-1-1
-4.5-5-4-4-5-5-4
-7.5-8-7-7-8-8-8

CEILING

CEILING

功能:向正无穷方向舍入。

DOWN

DOWN

功能:向靠近零的方向舍入。

FLOOR

FLOOR

功能:向负无穷方向舍入。

HALF_EVEN

HALF_EVEN

功能:四舍六入五取偶,又称 “银行家舍入”。

HALF_UP

HALF_UP

功能:四舍五入。

UP

UP

功能:向远离零的方向舍入。

数学基础运算示例

import std.math.clamp
import std.math.gcd
import std.math.lcm
import std.math.rotate

// 范围截断示例
func clampTest() {
    let min: Float16 = -0.123
    let max: Float16 = 0.123
    let v: Float16 = 0.121
    let c = clamp(v, min, max)
    println("${c==v}")
    let min2: Float16 = -0.999
    let max2: Float16 = 10.123
    let v2: Float16 = 11.121
    let c2 = clamp(v2, min2, max2)
    println("${c2==max2}")
    let min3: Float16 = -0.999
    let max3: Float16 = 10.123
    let v3: Float16 = -1.121
    let c3 = clamp(v3, min3, max3)
    println("${c3==min3}")
}

// 求两个数的最大公约数
func gcdTest() {
    let c2 = gcd(0, -60)
    println("c2=${c2}")
    let c4 = gcd(-33, 27)
    println("c4=${c4}")
}

// 求两个数的最小公倍数
func lcmTest() {
    let a: Int8 = lcm(Int8(-3), Int8(5))
    println("a=${a}")
}

// 整数按二进制某一位前后翻转
func rotateTest() {
    let a: Int8 = rotate(Int8(92), Int8(4))
    println("a=${a}")

    let b: Int32 = rotate(Int32(1), Int8(4))
    println("b=${b}")
}

main(): Unit {
    println("/***********************    clampTest    **********************/")
    clampTest()
    println("/***********************    gcdTest    ************************/")
    gcdTest()
    println("/***********************    lcmTest    ************************/")
    lcmTest()
    println("/***********************    rotateTest    *********************/")
    rotateTest()
}

运行结果:

/***********************    clampTest    **********************/
true
true
true
/***********************    gcdTest    ************************/
c2=60
c4=3
/***********************    lcmTest    ************************/
a=15
/***********************    rotateTest    *********************/
a=-59
b=16

std.math.numeric 包

功能介绍

math.numeric 包对基础类型可表达范围之外提供扩展能力。

例如:

  1. 支持大整数(BigInt);
  2. 支持高精度十进制数(Decimal)类型;
  3. 提供常见的数学运算能力包括高精度运算规则。

API 列表

函数

函数名功能
abs(BigInt)求一个 BigInt 的绝对值。
abs(Decimal)求一个 Decimal 的绝对值。
sqrt(BigInt)BigInt 的算术平方根,向下取整。
sqrt(Decimal)Decimal 的算术平方根。结果为无限小数场景时,默认采用 IEEE 754-2019 decimal128 对结果进行舍入。
gcd(BigInt, BigInt)求两个 BigInt 的最大公约数。总是返回非负数(相当于绝对值的最大公约数)。
lcm(BigInt, BigInt)求两个 BigInt 的的最小公倍数。除了入参有 0 时返回 0 外,总是返回正数(相当于绝对值的最小公倍数)。
max(BigInt, BigInt)计算并返回两个 BigInt 中较大的那个。
min(BigInt, BigInt)计算并返回两个 BigInt 中较小的那个。
countOne(BigInt)计算并返回入参 BigInt 的二进制补码中 1 的个数。
round(Decimal, RoundingMode)计算 Decimal 的舍入值,根据舍入方式向邻近的整数舍入。

枚举

枚举功能
OverflowStrategy溢出策略枚举类,共包含 3 种溢出策略。BigInt 类型、Decimal 类型转换为整数类型时,允许指定不同的溢出处理策略。

结构体

结构体功能
BigIntBigInt 定义为任意精度(二进制)的有符号整数。仓颉的 struct BigInt 用于任意精度有符号整数的计算,类型转换等。
DecimalDecimal 用于表示任意精度的有符号的十进制数。允许操作过程指定上下文,指定结果精度及舍入规则。提供基础类型 (Int、UInt、String、Float等) 与 BigInt 类型互相转换能力,支持 Decimal 对象基本属性查询等能力,支持基础数学运算操作,提供对象比较、hash、字符串打印等基础能力。

函数

func abs(BigInt)

public func abs(i: BigInt): BigInt

功能:求一个 BigInt 的绝对值。

参数:

返回值:

示例:

import std.math.numeric.*

main() {
    let n: BigInt = BigInt(-23)
    let abs = abs(n)
    println(abs)
}

运行结果:

23

func abs(Decimal)

public func abs(d: Decimal): Decimal

功能:求一个 Decimal 的绝对值。

参数:

返回值:

示例:

import std.math.numeric.*

main() {
    let d: Decimal = Decimal("-1.23")
    let abs = abs(d)
    println(abs)
}

运行结果:

1.23

func countOne(BigInt)

public func countOne(i: BigInt): Int64

功能:计算并返回入参 BigInt 的二进制补码中 1 的个数。

参数:

  • i: BigInt - 需要计算二进制补码中 1 的个数的 BigInt

返回值:

  • Int64 - 返回入参 BigInt 的二进制补码中 1 的个数。

示例:

import std.math.numeric.*

main() {
    let i: BigInt = BigInt(255)
    let countOne = countOne(i)
    println(countOne)
}

运行结果:

8

func gcd(BigInt, BigInt)

public func gcd(i1: BigInt, i2: BigInt): BigInt

功能:求两个 BigInt 的最大公约数。总是返回非负数(相当于绝对值的最大公约数)。

参数:

  • i1: BigInt - 需要计算最大公约数的第一个入参。
  • i2: BigInt - 需要计算最大公约数的第二个入参。

返回值:

  • BigInt - 返回 i1i2 的最大公约数,总是返回非负数。

示例:

import std.math.numeric.*

main() {
    let i1: BigInt = BigInt(-36)
    let i2: BigInt = BigInt(48)
    let gcd = gcd(i1, i2)
    println(gcd)
}

运行结果:

12

func lcm(BigInt, BigInt)

public func lcm(i1: BigInt, i2: BigInt): BigInt

功能:求两个 BigInt 的的最小公倍数。除了入参有 0 时返回 0 外,总是返回正数(相当于绝对值的最小公倍数)。

参数:

  • i1: BigInt - 需要计算最小公倍数的第一个入参。
  • i2: BigInt - 需要计算最小公倍数的第二个入参。

返回值:

  • BigInt - 返回 i1i2 的最小公倍数,当入参有 0 时返回 0,其余情况返回正数。

示例:

import std.math.numeric.*

main() {
    let i1: BigInt = BigInt(-36)
    let i2: BigInt = BigInt(48)
    let lcm = lcm(i1, i2)
    println(lcm)
}

运行结果:

144

func round(Decimal, RoundingMode)

public func round(d: Decimal, roundingMode!: RoundingMode = RoundingMode.HALF_EVEN): Decimal

功能:计算 Decimal 的舍入值,根据舍入方式向邻近的整数舍入。

参数:

返回值:

异常:

func sqrt(BigInt)

public func sqrt(i: BigInt): BigInt

功能:求 BigInt 的算术平方根,向下取整。

参数:

  • i: BigInt - 需要计算算术平方根的 BigInt,入参需要非负。

返回值:

  • BigInt - 返回入参 BigInt 的算术平方根,向下取整。

异常:

示例:

import std.math.numeric.*

main() {
    let n: BigInt = BigInt(23)
    let sqrt = sqrt(n)
    println(sqrt)
}

运行结果:

4

func sqrt(Decimal)

public func sqrt(d: Decimal): Decimal

功能:求 Decimal 的算术平方根。结果为无限小数场景时,默认采用 IEEE 754-2019 decimal128 对结果进行舍入。

参数:

  • d: Decimal - 需要计算算术平方根的 Decimal,入参需要非负。

返回值:

异常:

示例:

import std.math.numeric.*

main() {
    let n: Decimal = Decimal("36")
    let sqrt = sqrt(n)
    println(sqrt)
}

运行结果:

6

枚举

enum OverflowStrategy

public enum OverflowStrategy {
    | saturating
    | throwing
    | wrapping
}

溢出策略枚举类,共包含 3 种溢出策略。BigInt 类型、Decimal 类型转换为整数类型时,允许指定不同的溢出处理策略。

saturating

saturating

功能:出现溢出,当前值大于目标类型的 MAX 值,返回目标类型 MAX 值,当前值小于目标类型的 MIN 值,返回目标类型 MIN 值。

throwing

throwing

功能:出现溢出,抛出异常。

wrapping

wrapping

功能:出现溢出,高位截断。

结构体

struct BigInt

public struct BigInt <: Comparable<BigInt> & Hashable & ToString

功能:BigInt 定义为任意精度(二进制)的有符号整数。仓颉的 struct BigInt 用于任意精度有符号整数的计算,类型转换等。

父类型:

prop bitLen

public prop bitLen: Int64

功能:获取此 BigInt 的最短 bit 长度。如 -3 (101) 返回 3,-1 (11) 返回 2,0 (0) 返回 1。

类型:Int64

prop sign

public prop sign: Int64

功能:获取此 BigInt 的符号。正数返回 1;0 返回 0;负数返回 -1。

类型:Int64

init(Array<Byte>)

public init(bytes: Array<Byte>)

功能:通过大端的 Byte 数组以补码形式构建一个 BigInt 结构体。

数据存储方法有以下两种:

  • 大端存储方式:高位字节存放在低位地址。

  • 小端存储方式:将数据的低位字节存放在内存的高位地址。

参数:

  • bytes: Array<Byte> - 大端二进制补码数组,数组长度不能为空。

异常:

init(Bool, Array<Byte>)

public init(sign: Bool, magnitude: Array<Byte>)

功能:通过符号位和真值的绝对值构建一个 BigInt 结构体。视空数组为 0。

参数:

  • sign: Bool - 符号。true 表示非负数,false 表示负数。
  • magnitude: Array<Byte> - 真值绝对值的二进制原码。

异常:

init(Bool, Int64, Random)

public init(sign: Bool, bitLen: Int64, rand!: Random = Random())

功能:通过指定正负、bit 长度和随机数种子构建一个随机的 BigInt 结构体。bit 长度需要大于 0。

参数:

  • sign: Bool - 指定随机 BigInt 的正负。
  • bitLen: Int64 - 指定随机 BigInt 的 bit 长度上限。
  • rand!: Random - 指定的随机数种子。

异常:

init(Int16)

public init(n: Int16)

功能:通过 16 位有符号整数构建一个 BigInt 结构体。

参数:

  • n: Int16 - 16 位有符号整数。

init(Int32)

public init(n: Int32)

功能:通过 32 位有符号整数构建一个 BigInt 结构体。

参数:

  • n: Int32 - 32 位有符号整数。

init(Int64)

public init(n: Int64)

功能:通过 64 位有符号整数构建一个 BigInt 结构体。

参数:

  • n: Int64 - 64 位有符号整数。

init(Int8)

public init(n: Int8)

功能:通过 8 位有符号整数构建一个 BigInt 结构体。

参数:

  • n: Int8 - 8 位有符号整数。

init(IntNative)

public init(n: IntNative)

功能:通过平台相关有符号整数构建一个 BigInt 结构体。

参数:

  • n: IntNative - 平台相关有符号整数。

init(String, Int64)

public init(s: String, base!: Int64 = 10)

功能:通过字符串和进制构建一个 BigInt 结构体,支持 2 进制到 36 进制。

字符串的规则如下,即开头是可选的符号(正号或负号),接一串字符串表示的数字:

IntegerString : (SignString)? ValueString

  • SignString : + | -

  • ValueString : Digits

    • Digits: Digit | Digit Digits

      • Digit : '0' ~ '9' | 'A' ~ 'Z' | 'a' ~ 'z'

        • 如果 Digit 在 '0' ~ '9' 内, 需要满足 (Digit - '0') < base;

        • 如果 Digit 在 'A' ~ 'Z' 内, 需要满足 (Digit - 'A') + 10 < base;

        • 如果 Digit 在 'a' ~ 'z' 内, 需要满足 (Digit - 'A') + 10 < base。

参数:

  • s: String - 用于构建 BigInt 结构体的字符串。字符串规则为,开头可选一个正号(+)或者负号(-)。接下来必选非空阿拉伯数字或大小写拉丁字母的字符序列,大小写字符含义一样,'a' 和 'A' 的大小等于十进制的 10,'b' 和 'B' 的大小等于十进制的 11,以此类推。序列中的字符大小不得大于等于进制大小。
  • base!: Int64 - 进制。字符串所表示的进制,范围为 [2, 36]。

异常:

  • IllegalArgumentException - 如果字符串 s 不符合上述规则,或 base 表示的进制不在 [2, 36] 区间内,抛此异常。

init(UInt16)

public init(n: UInt16)

功能:通过 16 位无符号整数构建一个 BigInt 结构体。

参数:

  • n: UInt16 - 16 位无符号整数。

init(UInt32)

public init(n: UInt32)

功能:通过 32 位无符号整数构建一个 BigInt 结构体。

参数:

  • n: UInt32 - 32 位无符号整数。

init(UInt64)

public init(n: UInt64)

功能:通过 64 位无符号整数构建一个 BigInt 结构体。

参数:

  • n: UInt64 - 64 位无符号整数。

init(UInt8)

public init(n: UInt8)

功能:通过 8 位无符号整数构建一个 BigInt 结构体。

参数:

  • n: UInt8 - 8 位无符号整数。

init(UIntNative)

public init(n: UIntNative)

功能:通过平台相关无符号整数构建一个 BigInt 结构体。

参数:

static func randomProbablePrime(Int64, UInt64, Random)

public static func randomProbablePrime(bitLen: Int64, certainty: UInt64, rand!: Random = Random()): BigInt

功能:通过可选的随机数种子构建一个随机的 BigInt 素数,素数的 bit 长度不超过入参 bitLen

显然,素数必定是大于等于 2 的整数,因此 bitLen 必须大于等于 2。素数检测使用 Miller-Rabin 素数测试算法。Miller-Rabin 测试会有概率将一个合数判定为素数,其出错概率随着入参 certainty 的增加而减少。

参数:

  • bitLen: Int64 - 所要生成的随机素数的 bit 长度的上限。
  • certainty: UInt64 - 生成的随机素数通过 Miller-Rabin 素数测试算法的次数,通过的次数越多,将合数误判为素数的概率越低。
  • rand!: Random - 指定的随机数种子。

返回值:

  • BigInt - 返回生成的随机素数。

异常:

示例:

import std.math.numeric.BigInt

main() {
    let randomProbablePrime = BigInt.randomProbablePrime(6, 3)
    println(randomProbablePrime)
}

运行结果:

11

func clearBit(Int64)

public func clearBit(index: Int64): BigInt

功能:通过将指定索引位置的 bit 修改为 0 来构造一个新 BigInt

参数:

  • index: Int64 - 需要设置的 bit 位置的索引。index 需要大于等于 0。

返回值:

  • BigInt - 一个新的 BigInt,它是将原 BigIntindex 处的 bit 改为 0 的产物。

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1024)
    let clearBit = bigInt.clearBit(10)
    println(clearBit)
}

运行结果:

0

func compare(BigInt)

public func compare(that: BigInt): Ordering

功能:判断 BigInt 与另一个 BigInt 的关系。

参数:

返回值:

func divAndMod(BigInt)

public func divAndMod(that: BigInt): (BigInt, BigInt)

功能:BigInt 的除法运算。

与另一个 BigInt 相除,返回商和模。此除法运算的行为与基础类型保持一致,即商向靠近 0 的方向取整,模的符号与被除数保持一致。

参数:

  • that: BigInt - 除数。除数不得为 0。

返回值:

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let (div, mod) = bigInt.divAndMod(that)
    println(div)
    println(mod)
}

运行结果:

2
1

func flipBit(Int64)

public func flipBit(index: Int64): BigInt

功能:通过翻转指定索引位置的 bit 来构造一个新 BigInt

参数:

  • index: Int64 - 需要翻转的 bit 位置的索引。index 需要大于等于 0。

返回值:

  • BigInt - 一个新的 BigInt,它是将原 BigInt index 处的 bit 翻转后的产物。

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1024)
    let flipBit = bigInt.flipBit(10)
    println(flipBit)
}

运行结果:

0

func hashCode()

public func hashCode(): Int64

功能:计算并返回此 BigInt 的哈希值。

返回值:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1024)
    let hashCode = bigInt.hashCode()
    println(hashCode)
}

运行结果:

1024

func isProbablePrime(UInt64)

public func isProbablePrime(certainty: UInt64): Bool

功能:判断一个数是不是素数。

说明:

该函数使用了 Miller-Rabin 测试算法,此算法的准确率会随着 certainty 参数的增加而增加。如果该数是素数,那么 Miller-Rabin 测试必定返回 true;如果该数是合数(期待返回 false),那么会有低于 1/4certainty 概率返回 true。素数只对大于等于 2 的正整数有意义,即负数,0,1 都不是素数。

参数:

  • certainty: UInt64 - 需要执行 Miller-Rabin 测试的次数。注意,如果测试次数为 0,表示不测试,那么总是返回 true(即不是素数的数也必定返回 true)。

返回值:

  • Bool - 如果使用此函数测定了一个数为素数,则返回 true;不为素数,则返回 false。

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1024)
    let isProbablePrime = bigInt.isProbablePrime(10)
    println(isProbablePrime)
}

运行结果:

false

func lowestOneBit()

public func lowestOneBit(): Int64

功能:判断为 1 的最低位的 bit 的位置。

返回值:

  • Int64 - 返回为 1 的最低位的 bit 的位置。如果 bit 全为 0,则返回 -1。

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(-1)
    let lowestOneBit = bigInt.lowestOneBit()
    println(lowestOneBit)
}

运行结果:

0

func modInverse(BigInt)

public func modInverse(that: BigInt): BigInt

功能:求模逆元。

模逆元 r 满足 $(this * r) % that == 1$。显然,thisthat 必须互质。当 that 为 正负 1 时,结果总是 0。

参数:

  • that: BigInt - 另外一个 BigInt。入参不得为 0,且需要与 this 互质。

返回值:

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let modInverse = bigInt.modInverse(that)
    println(modInverse)
}

运行结果:

1

func modPow(BigInt, BigInt)

public func modPow(n: BigInt, m!: ?BigInt = None): BigInt

功能:计算此 BigInt 的 n 次幂模 m 的结果,并返回。

模的规则与基础类型一致,即模的符号与被除数保持一致。

参数:

  • n: BigInt - 指数,必须为非负数。
  • m!: ?BigInt - 除数,此入参不得为 0。

返回值:

  • BigInt - 乘方后取模的运算结果。

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(2)
    let n = BigInt(10)
    let modPow = bigInt.modPow(n)
    println(modPow)
}

运行结果:

1024

func quo(BigInt)

public func quo(that: BigInt): BigInt

功能:BigInt 的除法运算。

与另一个 BigInt 相除,返回结果。此除法运算的行为与运算符重载函数区别于,如果被除数为负数,此函数的结果向着远离 0 的方向取整,保证余数大于等于 0。

参数:

  • that: BigInt - 除数。除数不得为 0。

返回值:

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let quo = bigInt.quo(that)
    println(quo)
}

运行结果:

2

func quoAndRem(BigInt)

public func quoAndRem(that: BigInt): (BigInt, BigInt)

功能:BigInt 的除法运算。

与另一个 BigInt 相除,返回商和余数。此除法运算的行为与 divAndMod 函数区别于,如果被除数为负数,此函数的结果向着远离 0 的方向取整,保证余数总是大于等于 0。

参数:

  • that: BigInt - 除数。除数不得为 0。

返回值:

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let (quo, rem) = bigInt.quoAndRem(that)
    println(quo)
    println(rem)
}

运行结果:

2
1

func rem(BigInt)

public func rem(that: BigInt): BigInt

功能:BigInt 的模运算。

与另一个 BigInt 相除,返回余数。余数的结果总是大于等于 0。

参数:

  • that: BigInt - 除数。除数不得为 0。

返回值:

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let rem = bigInt.rem(that)
    println(rem)
}

运行结果:

1

func setBit(Int64)

public func setBit(index: Int64): BigInt

功能:通过将指定索引位置的 bit 修改为 1 来构造一个新 BigInt

参数:

  • index: Int64 - 需要设置的 bit 位置的索引。index 需要大于等于 0。

返回值:

  • BigInt - 一个新的 BigInt,它是将原 BigInt index 处的 bit 改为 1 的产物。

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(0)
    let setBit = bigInt.setBit(10)
    println(setBit)
}

运行结果:

1024

func testBit(Int64)

public func testBit(index: Int64): Bool

功能:判断指定位置的 bit 信息,如果指定位置的 bit 为 0,则返回 false;为 1,则返回 true。

参数:

  • index: Int64 - 需要知道的 bit 的索引。index 需要大于等于 0。

返回值:

  • Bool - 指定位置的 bit 信息。

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(-1)
    let testBit = bigInt.testBit(100)
    println(testBit)
}

运行结果:

true

func toBytes()

public func toBytes(): Array<Byte>

功能:计算并返回此 BigInt 的大端补码字节数组。

字节数组最低索引的最低位为符号位,如 128 返回 [0, 128](符号位为 0),-128 返回 [128](符号位为 1)。

返回值:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(0x400)
    let toBytes = bigInt.toBytes()
    println(toBytes)
}

运行结果:

[4, 0]

func toInt16(OverflowStrategy)

public func toInt16(overflowHandling!: OverflowStrategy = throwing): Int16

功能:将当前 BigInt 对象转化为 Int16 类型,支持自定义溢出策略。

参数:

  • overflowHandling!: OverflowStrategy - 转换溢出策略。
    • "throwing":异常模式。出现溢出抛出异常。
    • "wrapping":溢出模式。出现溢出高位截断。
    • "saturating":边界值模式。出现溢出,当前值大于目标类型的 MAX 值,返回目标类型 MAX 值,当前值小于目标类型的 MIN 值,返回目标类型 MIN 值。

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt(0x8000_0000_0000)
    let toInt16 = bigInt.toInt16(overflowHandling: saturating)
    println(toInt16)
}

运行结果:

32767

func toInt32(OverflowStrategy)

public func toInt32(overflowHandling!: OverflowStrategy = throwing): Int32

功能:将当前 BigInt 对象转化为 Int32 类型,支持自定义溢出策略。

参数:

  • overflowHandling!: OverflowStrategy - 转换溢出策略。
    • "throwing":异常模式。出现溢出抛出异常。
    • "wrapping":溢出模式。出现溢出高位截断。
    • "saturating":边界值模式。出现溢出,当前值大于目标类型的 MAX 值,返回目标类型 MAX 值,当前值小于目标类型的 MIN 值,返回目标类型 MIN 值。

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt(0x8000_0000_00FF)
    let toInt32 = bigInt.toInt32(overflowHandling: wrapping)
    println(toInt32)
}

运行结果:

255

func toInt64(OverflowStrategy)

public func toInt64(overflowHandling!: OverflowStrategy = throwing): Int64

功能:将当前 BigInt 对象转化为 Int64 类型,支持自定义溢出策略。

参数:

  • overflowHandling!: OverflowStrategy - 转换溢出策略。
    • "throwing":异常模式。出现溢出抛出异常。
    • "wrapping":溢出模式。出现溢出高位截断。
    • "saturating":边界值模式。出现溢出,当前值大于目标类型的 MAX 值,返回目标类型 MAX 值,当前值小于目标类型的 MIN 值,返回目标类型 MIN 值。

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("800000000000000000", base: 16)
    let toInt64 = bigInt.toInt64(overflowHandling: wrapping)
    println(toInt64)
}

运行结果:

0

func toInt8(OverflowStrategy)

public func toInt8(overflowHandling!: OverflowStrategy = throwing): Int8

功能:将当前 BigInt 对象转化为 Int8 类型,支持自定义溢出策略。

参数:

  • overflowHandling!: OverflowStrategy - 转换溢出策略。
    • "throwing":异常模式。出现溢出抛出异常。
    • "wrapping":溢出模式。出现溢出高位截断。
    • "saturating":边界值模式。出现溢出,当前值大于目标类型的 MAX 值,返回目标类型 MAX 值,当前值小于目标类型的 MIN 值,返回目标类型 MIN 值。

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt(1024)
    let toInt8 = bigInt.toInt8(overflowHandling: saturating)
    println(toInt8)
}

运行结果:

127

func toIntNative(OverflowStrategy)

public func toIntNative(overflowHandling!: OverflowStrategy = throwing): IntNative

功能:将当前 BigInt 对象转化为 IntNative 类型,支持自定义溢出策略。

参数:

  • overflowHandling!: OverflowStrategy - 转换溢出策略。
    • "throwing":异常模式。出现溢出抛出异常。
    • "wrapping":溢出模式。出现溢出高位截断。
    • "saturating":边界值模式。出现溢出,当前值大于目标类型的 MAX 值,返回目标类型 MAX 值,当前值小于目标类型的 MIN 值,返回目标类型 MIN 值。

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("800000000000000000", base: 16)
    let toIntNative = bigInt.toIntNative(overflowHandling: wrapping)
    println(toIntNative)
}

运行结果:

0

func toString()

public func toString(): String

功能:计算并返回此 BigInt 的十进制字符串表示。

返回值:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(0x400)
    let toString = bigInt.toString()
    println(toString)
}

运行结果:

1024

func toString(Int64)

public func toString(base: Int64): String

功能:计算并返回此 BigInt 的任意进制字符串表示。

参数:

  • base: Int64 - 进制。字符串所表示的进制,范围为 [2, 36]。

返回值:

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(0x400)
    let toString = bigInt.toString(2)
    println(toString)
}

运行结果:

10000000000

func toUInt16(OverflowStrategy)

public func toUInt16(overflowHandling!: OverflowStrategy = throwing): UInt16

功能:将当前 BigInt 对象转化为 UInt16 类型,支持自定义溢出策略。

参数:

  • overflowHandling!: OverflowStrategy - 转换溢出策略。
    • "throwing":异常模式。出现溢出抛出异常。
    • "wrapping":溢出模式。出现溢出高位截断。
    • "saturating":边界值模式。出现溢出,当前值大于目标类型的 MAX 值,返回目标类型 MAX 值,当前值小于目标类型的 MIN 值,返回目标类型 MIN 值。

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("800000000000000000", base: 16)
    let toUInt16 = bigInt.toUInt16(overflowHandling: wrapping)
    println(toUInt16)
}

运行结果:

0

func toUInt32(OverflowStrategy)

public func toUInt32(overflowHandling!: OverflowStrategy = throwing): UInt32

功能:将当前 BigInt 对象转化为 UInt32 类型,支持自定义溢出策略。

参数:

  • overflowHandling!: OverflowStrategy - 转换溢出策略。
    • "throwing":异常模式。出现溢出抛出异常。
    • "wrapping":溢出模式。出现溢出高位截断。
    • "saturating":边界值模式。出现溢出,当前值大于目标类型的 MAX 值,返回目标类型 MAX 值,当前值小于目标类型的 MIN 值,返回目标类型 MIN 值。

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("800000000000000000", base: 16)
    let toUInt32 = bigInt.toUInt32(overflowHandling: wrapping)
    println(toUInt32)
}

运行结果:

0

func toUInt64(OverflowStrategy)

public func toUInt64(overflowHandling!: OverflowStrategy = throwing): UInt64

功能:将当前 BigInt 对象转化为 UInt64 类型,支持自定义溢出策略。

参数:

  • overflowHandling!: OverflowStrategy - 转换溢出策略。
    • "throwing":异常模式。出现溢出抛出异常。
    • "wrapping":溢出模式。出现溢出高位截断。
    • "saturating":边界值模式。出现溢出,当前值大于目标类型的 MAX 值,返回目标类型 MAX 值,当前值小于目标类型的 MIN 值,返回目标类型 MIN 值。

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("-800000000000000000", base: 16)
    let toUInt64 = bigInt.toUInt64(overflowHandling: saturating)
    println(toUInt64)
}

运行结果:

0

func toUInt8(OverflowStrategy)

public func toUInt8(overflowHandling!: OverflowStrategy = throwing): UInt8

功能:将当前 BigInt 对象转化为 UInt8 类型,支持自定义溢出策略。

参数:

  • overflowHandling!: OverflowStrategy - 转换溢出策略。
    • "throwing":异常模式。出现溢出抛出异常。
    • "wrapping":溢出模式。出现溢出高位截断。
    • "saturating":边界值模式。出现溢出,当前值大于目标类型的 MAX 值,返回目标类型 MAX 值,当前值小于目标类型的 MIN 值,返回目标类型 MIN 值。

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("800000000000000000", base: 16)
    try {
        bigInt.toUInt8(overflowHandling: throwing)
    } catch (e: OverflowException) {
        println(e.message)
    }
    return
}

运行结果:

Out of range of the UInt8

func toUIntNative(OverflowStrategy)

public func toUIntNative(overflowHandling!: OverflowStrategy = throwing): UIntNative

功能:将当前 BigInt 对象转化为 UIntNative 类型,支持自定义溢出策略。

参数:

  • overflowHandling!: OverflowStrategy - 转换溢出策略。
    • "throwing":异常模式。出现溢出抛出异常。
    • "wrapping":溢出模式。出现溢出高位截断。
    • "saturating":边界值模式。出现溢出,当前值大于目标类型的 MAX 值,返回目标类型 MAX 值,当前值小于目标类型的 MIN 值,返回目标类型 MIN 值。

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("-800000000000000000", base: 16)
    let toUIntNative = bigInt.toUIntNative(overflowHandling: saturating)
    println(toUIntNative)
}

运行结果:

0

operator func !()

public operator func !(): BigInt

功能:按位非。将操作数中的二进制位 0 变 1,1 变 0。

返回值:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let no = !bigInt
    println(no)
}

运行结果:

0

operator func !=(BigInt)

public operator func !=(that: BigInt): Bool

功能:判不等运算。

参数:

返回值:

  • Bool - 判不等的结果。不等返回 true,相等返回 false。

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt != that)
}

运行结果:

true

operator func %(BigInt)

public operator func %(that: BigInt): BigInt

功能:BigInt 的模运算。

取模运算的行为与基础类型保持一致,即符号与被除数保持一致。

参数:

  • that: BigInt - 除数。除数不得为 0。

返回值:

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-23456789123456789")
    let that = BigInt("-23456789123456789")
    let mod = bigInt % that
    println(mod)
}

运行结果:

0

operator func &(BigInt)

public operator func &(that: BigInt): BigInt

功能:按位与。其功能是参与运算的两数各对应的二进位相与。只有对应的两个二进位都为 1 时,结果位才为 1。

参数:

返回值:

  • BigInt - 返回与另一个 BigInt 的按位与的结果。

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("8")
    let that = BigInt("7")
    let and = bigInt & that
    println(and)
}

运行结果:

0

operator func *(BigInt)

public operator func *(that: BigInt): BigInt

功能:BigInt 乘法。

参数:

返回值:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-23456789123456789")
    let mul = bigInt * that
    println(mul)
}

运行结果:

23456789123456789

operator func **(UInt64)

public operator func **(n: UInt64): BigInt

功能:求 BigInt 的 n 次幂。

参数:

返回值:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-2")
    let power = bigInt ** 64
    println(power.toString(16))
}

运行结果:

10000000000000000

operator func +(BigInt)

public operator func +(that: BigInt): BigInt

功能:BigInt 加法。

参数:

返回值:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("123456789123456789")
    let that = BigInt("-23456789123456789")
    let plus = bigInt + that
    println(plus)
}

运行结果:

100000000000000000

operator func -()

public operator func -(): BigInt

功能:求 BigInt 的相反数。

返回值:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-23456789123456789")
    let opposite = -bigInt
    println(opposite)
}

运行结果:

23456789123456789

operator func -(BigInt)

public operator func -(that: BigInt): BigInt

功能:BigInt 减法。

参数:

返回值:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("100000000000000000")
    let that = BigInt("-23456789123456789")
    let sub = bigInt - that
    println(sub)
}

运行结果:

123456789123456789

operator func <(BigInt)

public operator func <(that: BigInt): Bool

功能:小于比较运算。

参数:

返回值:

  • Bool - 比较的结果。小于返回 true,否则返回 false。

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt < that)
}

运行结果:

false

operator func <<(Int64)

public operator func <<(n: Int64): BigInt

功能:左移运算。

参数:

  • n: Int64 - 左移 n 位,n 需要大于等于 0。

返回值:

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let leftShift = bigInt << 64
    println(leftShift.toString(16))
}

运行结果:

-10000000000000000

operator func <=(BigInt)

public operator func <=(that: BigInt): Bool

功能:小于等于比较运算。

参数:

  • that: BigInt - 小于等于比较运算的另一个 BigInt

返回值:

  • Bool - 比较的结果。小于等于返回 true,否则返回 false。

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt <= that)
}

运行结果:

false

operator func ==(BigInt)

public operator func ==(that: BigInt): Bool

功能:判等运算。

参数:

返回值:

  • Bool - 判等的结果。相等返回 true,不等返回 false。

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt == that)
}

运行结果:

false

operator func >(BigInt)

public operator func >(that: BigInt): Bool

功能:大于比较运算。

参数:

返回值:

  • Bool - 比较的结果。大于返回 true,否则返回 false。

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt > that)
}

运行结果:

true

operator func >=(BigInt)

public operator func >=(that: BigInt): Bool

功能:大于等于比较运算。

参数:

  • that: BigInt - 大于等于比较运算的另一个 BigInt

返回值:

  • Bool - 比较的结果。大于等于返回 true,否则返回 false。

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt >= that)
}

运行结果:

true

operator func >>(Int64)

public operator func >>(n: Int64): BigInt

功能:右移运算。

参数:

  • n: Int64 - 右移 n 位,n 需要大于等于 0。

返回值:

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let rightShift = bigInt >> 10000
    println(rightShift)
}

运行结果:

-1

operator func /(BigInt)

public operator func /(that: BigInt): BigInt

功能:BigInt 除法。

除法运算的行为与基础类型保持一致,即结果向靠近 0 的方向取整。

参数:

  • that: BigInt - 除数。除数不得为 0。

返回值:

异常:

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-23456789123456789")
    let that = BigInt("-23456789123456789")
    let div = bigInt / that
    println(div)
}

运行结果:

1

operator func ^(BigInt)

public operator func ^(that: BigInt): BigInt

功能:按位异或。其功能是参与运算的两数各对应的二进位相异或。二进制位结果不相同时,异或结果为 1;二进制位结果相同时,异或结果为 0。

参数:

  • that: BigInt - 按位异或运算的另外一个 BigInt

返回值:

  • BigInt - 返回与另一个 BigInt 的按位异或的结果。

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("7")
    let xor = bigInt ^ that
    println(xor)
}

运行结果:

-8

operator func |(BigInt)

public operator func |(that: BigInt): BigInt

功能:按位或。其功能是参与运算的两数各对应的二进位相或。只有对应的两个二进位都为 0 时,结果位才为 0。

参数:

返回值:

  • BigInt - 返回与另一个 BigInt 的按位或的结果。

示例:

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("8")
    let that = BigInt("7")
    let or = bigInt | that
    println(or)
}

运行结果:

15

struct Decimal

public struct Decimal <: Comparable<Decimal> & Hashable & ToString

功能:Decimal 用于表示任意精度的有符号的十进制数。允许操作过程指定结果精度及舍入规则。提供基础类型 (IntUIntStringFloat等) 与 BigInt 类型互相转换能力,支持 Decimal 对象基本属性查询等能力,支持基础数学运算操作,提供对象比较、hash、字符串打印等基础能力。

父类型:

prop precision

public prop precision: Int64

功能:获取 Decimal 精度值,即无标度整数部分十进制有效数字位数,非负数。如果精度值为0,表示无精度限制。

类型:Int64

prop scale

public prop scale: Int32

功能:获取 Decimal 标度值。

类型:Int32

prop sign

public prop sign: Int64

功能:获取 Decimal 实例符号值。

类型:Int64

prop value

public prop value: BigInt

功能:获取 Decimal 无标度整数值,BigInt 承载。

类型:BigInt

init(BigInt)

public init(val: BigInt)

功能:通过有符号大整数 BigInt 构建 Deciaml 结构体。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: BigInt - 有符号大整数值。

init(BigInt, Int32)

public init(val: BigInt, scale: Int32)

功能:通过有符号大整数 BigInt 和标度值构建 Deciaml 结构体。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: BigInt - 有符号大整数值。
  • scale: Int32 - 标度值。

init(Float16)

public init(val: Float16)

功能:通过 16 位有符号浮点数构建 Decimal 对象。默认采用精度值为0,即无限精度进行构建。

注意:

由于部分十进制小数无法通过二进制浮点数精确表示,此构造函数以精确值构建 Decimal 对象,传入浮点数值可能与最终构建 Decimal 对象字符串打印值不一致。

参数:

  • val: Float16 - 16 位有符号二进制浮点数。

异常:

init(Float32)

public init(val: Float32)

功能:通过 32 位有符号浮点数构建 Decimal 对象。默认采用精度值为0,即无限精度进行构建。

注意:

由于部分十进制小数无法通过二进制浮点数精确表示,此构造函数以精确值构建 Decimal 对象,传入浮点数值可能与最终构建 Decimal 对象字符串打印值不一致。

参数:

  • val: Float32 - 32 位有符号二进制浮点数。

异常:

init(Float64)

public init(val: Float64)

功能:通过 64 位有符号浮点数构建 Decimal 对象。默认采用精度值为0,即无限精度进行构建。

注意:

由于部分十进制小数无法通过二进制浮点数精确表示,此构造函数以精确值构建 Decimal 对象,传入浮点数值可能与最终构建 Decimal 对象字符串打印值不一致。

参数:

  • val: Float64 - 64 位有符号二进制浮点数。

异常:

init(Int16)

public init(val: Int16)

功能:通过 16 位有符号整数构建 Decimal 结构体。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: Int16 - 16 位有符号整数。

init(Int32)

public init(val: Int32)

功能:通过 32 位有符号整数构建 Decimal 对象。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: Int32 - 32 位有符号整数。

init(Int64)

public init(val: Int64)

功能:通过 64 位有符号整数构建 Decimal 对象。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: Int64 - 64 位有符号整数。

init(Int8)

public init(val: Int8)

功能:通过 8 位有符号整数构建 Decimal 结构体。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: Int8 - 8 位有符号整数。

init(IntNative)

public init(val: IntNative)

功能:通过 32 位或 64 位 (具体长度与平台相关) 有符号整数构建 Decimal 对象。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: IntNative - 32 位或 64位有符号整数。

init(String)

public init(val: String)

功能:通过规定格式字符串构建 Decimal 结构体。默认采用精度值为0,即无限精度进行构建。字符串需满足如下格式,即开头可选的符号(正号或负号),接 ValueString 字符串,再接可选的 ExponentString 字符串:

Decimal 字符串: (SignString)? ValueString (ExponentString)?

  • SignString:+ | -

  • ValueString:IntegerPart.(FractionPart)? | .FractionPart | IntegerPart

    • IntegerPart:Digits

    • FractionPart:Digits

    • Digits: Digit | Digit Digits

      • Digit:'0' ~ '9'
  • ExponentString:ExponentIndicator (SignString)? IntegerPart

    • ExponentIndicator:e | E

参数:

  • val: String - 规定格式字符串。

异常:

init(UInt16)

public init(val: UInt16)

功能:通过 16 位无符号整数构建 Decimal 对象。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: UInt16 - 16 位无符号整数。

init(UInt32)

public init(val: UInt32)

功能:通过 32 位无符号整数构建 Decimal 对象。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: UInt32 - 32 位无符号整数。

init(UInt64)

public init(val: UInt64)

功能:通过 64 位无符号整数构建 Decimal 对象。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: UInt64 - 64 位无符号整数。

init(UInt8)

public init(val: UInt8)

功能:通过 8 位无符号整数构建 Decimal 对象。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: UInt8 - 8 位无符号整数。

init(UIntNative)

public init(val: UIntNative)

功能:通过 32 位或 64 位 (具体长度与平台相关) 无符号整数构建 Decimal 对象。默认采用精度值为0,即无限精度进行构建。

参数:

  • val: UIntNative - 32 位或 64位无符号整数。

func compare(Decimal)

public func compare(d: Decimal): Ordering

功能:比较当前对象与入参 Decimal 对象,返回比较结果值。

参数:

返回值:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(-5)
    let B = Decimal(3)

    let C = A.compare(B)
    println(C)
}

运行结果:

Ordering.LT

func divWithPrecision(Decimal, Int64, RoundingMode)

public func divWithPrecision(d: Decimal, precision: Int64, roundingMode!: RoundingMode = HALF_EVEN): Decimal

功能:除法运算,支持自定义运算精度和舍入方式,除以入参 Decimal 对象,返回结果值,如果结果精度超过 precision 指定精度,则根据指定的精度对除法运算结果进行舍入。

参数:

返回值:

  • Decimal - 生成一个新的 Decimal 对象,用于存储除法运算结果值。

异常:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A.divWithPrecision(B, 0)
    println("C = ${C}")
}

运行结果:

C = 0.6666666666666666666666666666666667

func divAndRem(Decimal)

public func divAndRem(d: Decimal): (BigInt, Decimal)

功能:除法取商和余数运算,除以入参 Decimal 对象,返回整数商值和余数值。结果保留实际精度值。

参数:

返回值:

  • (BigInt, Decimal) - 生成一个元组对象,分别用于存储整数商值结果和余数结果值。

异常:

func hashCode()

public func hashCode(): Int64

功能:获取当前对象哈希值。

返回值:

  • Int64 - 返回当前对象哈希值。

func isInteger()

public func isInteger(): Bool

功能:判断当前 Decimal 对象是否为整数。

返回值:

  • Bool - 返回当前对象是否为整数判断结果。当前对象为整数时返回 true,否则返回 false。

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(100)
    println("${A}.isInteger() = ${A.isInteger()}")
}

运行结果:

100.isInteger() = true

func powWithPrecision(Int64, Int64, RoundingMode)

public func powWithPrecision(n: Int64, precision: Int64, roundingMode!: RoundingMode = RoundingMode.HALF_EVEN): Decimal

功能:乘方运算,支持自定义运算精度和舍入方式,获取当前对象为底数,入参 Int64 为指数的乘方运算结果,如果运算结果超过 precision 指定的精度,则根据指定的精度对乘方结果进行舍入。

参数:

  • n: Int64 - 乘方运算的指数值。
  • precision: Int64 - 精度值。
  • roundingMode!: RoundingMode - 舍入规则。

返回值:

  • Decimal - 生成一个新的 Decimal 对象,用于存储乘方运算结果值。

异常:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2.5)
    println("A.powWithPrecision(3, 0) = ${A.powWithPrecision(3, 0, roundingMode: HALF_EVEN)}")
}

运行结果:

A.powWithPrecision(3, 0) = 15.625

func reScale(Int32, RoundingMode)

public func reScale(newScale: Int32, roundingMode!: RoundingMode = HALF_EVEN): Decimal

功能:调整 Decimal 对象标度值,允许指定舍入规则,返回标度调整后新的 Decimal 对象。

参数:

返回值:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(1.234568)
    println("A.reScale(3) = ${A.reScale(3)}")
}

运行结果:

A.reScale(3) = 1.235

func removeTrailingZeros()

public func removeTrailingZeros(): Decimal

功能:对当前 Decimal 对象移除尾部零,不改变对象数值。

返回值:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(1.00)
    println("A.removeTrailingZeros() = ${A.removeTrailingZeros()}")
}

运行结果:

A.removeTrailingZeros() = 1

func roundWithPrecision(Int64, RoundingMode)

public func roundWithPrecision(precision: Int64, roundingMode!: RoundingMode = RoundingMode.HALF_EVEN): Decimal

功能:按照指定舍入精度和舍入规则对当前 Decimal 对象进行舍入操作。

参数:

返回值:

异常:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(1.0)
    println("A.roundWithPrecision(1.0) = ${A.roundWithPrecision(0, roundingMode: HALF_EVEN)}")
    let B = Decimal(0.1f16).roundWithPrecision(5, roundingMode: UP)
    println("B = ${B}")
}

运行结果:

A.roundWithPrecision(1.0) = 1
B = 0.099976

func scaleUnit()

public func scaleUnit(): Decimal

功能:对当前 Decimal 对象返回标度单位,即数值为 1 ,标度值与当前对象相等的 Decimal 对象。

返回值:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(100)
    println("A.scaleUnit() = ${A.scaleUnit()}")
}

运行结果:

A.scaleUnit() = 1

func shiftPoint(Int32)

public func shiftPoint(n: Int32): Decimal

功能:移动当前 Decimal 对象小数点 abs(n) 位返回结果对象,当 n 为正数时,左移小数点,n 为负数时,右移小数点,n 为零时,返回当前对象。

参数:

  • n: Int32 - 指定小数点移动位数及方向。

返回值:

  • Decimal - 对当前对象小数点移动指定位数后生成新的 Decimal 对象。

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(25)
    println("A.shiftPoint(1) = ${A.shiftPoint(1)}")
}

运行结果:

A.shiftPoint(-1) = 2.5

func sqrtWithPrecision(Int64, RoundingMode)

public func sqrtWithPrecision(precision: Int64, roundingMode!: RoundingMode = RoundingMode.HALF_EVEN): Decimal

功能:开方运算,支持自定义运算精度和结果舍入方式,获取当前对象开方结果,如果运算结果超过 presision 指定的精度,则根据指定的精度对开方结果进行舍入。

参数:

返回值:

  • Decimal - 返回入参 Decimal 的算术平方根,根据输入精度和舍入方式进行取整。

异常:

示例:

import std.math.numeric.*

main() {
    let n: Decimal = Decimal("2")
    let s = n.sqrtWithPrecision(2)
    println(s)
}

运行结果:

1.4

func toBigInt()

public func toBigInt(): BigInt

功能:将当前 Decimal 对象转化为 BigInt 类型。

返回值:

func toEngString()

public func toEngString(): String

功能:以工程计数法的形式打印输出 Decimal 对象,指数为 3 的倍数, 当值小于 0 时以 “-” 开头后跟十进制数字,大于等于 0 时,直接打印输出数字,不额外添加 “+”。指数小于 0 时同样遵循以上规则。

返回值:

func toSciString()

public func toSciString(): String

功能:以科学计数法的形式打印输出 Decimal 对象,当值小于 0 时以 “-” 开头后跟十进制数字,大于等于 0 时,直接打印输出数字,不额外添加 “+”。指数小于 0 时同样遵循以上规则。

返回值:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(6.25)
    println("A.toFloat16() = ${A.toFloat16()}")
    println("A.toFloat32() = ${A.toFloat32()}")
    println("A.toFloat64() = ${A.toFloat64()}")
    println("A.toBigInt() = ${A.toBigInt()}")
    println("A.toEngString() = ${A.toEngString()}")
    println("A.toSciString() = ${A.toSciString()}")
}

运行结果:

A.toFloat16() = 6.250000
A.toFloat32() = 6.250000
A.toFloat64() = 6.250000
A.toBigInt() = 6
A.toEngString() = 6.25E0
A.toSciString() = 6.25E0

func toFloat16()

public func toFloat16(): Float16

功能:将当前 Decimal 对象转化为 Float16 类型。

返回值:

  • Float16 - 转换后的 Float16 值,溢出时,当前值为正数,返回 inf,当前值为负数,返回 -inf

func toFloat32()

public func toFloat32(): Float32

功能:将当前 Decimal 对象转化为 Float32 类型。

返回值:

  • Float32 - 转换后的 Float32 值,溢出时,当前值为正数,返回 inf,当前值为负数,返回 -inf

func toFloat64()

public func toFloat64(): Float64

功能:将当前 Decimal 对象转化为 Float64 类型。

返回值:

  • Float64 - 转换后的 Float64 值,溢出时,当前值为正数,返回 inf,当前值为负数,返回 -inf

func toInt16(OverflowStrategy)

public func toInt16(overflowHandling!: OverflowStrategy = throwing): Int16

功能:将当前 Decimal 对象转化为 Int16 类型,支持自定义溢出策略。

入参:

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

func toInt32(OverflowStrategy)

public func toInt32(overflowHandling!: OverflowStrategy = throwing): Int32

功能:将当前 Decimal 对象转化为 Int32 类型,支持自定义溢出策略。

入参:

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

func toInt64(OverflowStrategy)

public func toInt64(overflowHandling!: OverflowStrategy = throwing): Int64

功能:将当前 Decimal 对象转化为 Int64 类型,支持自定义溢出策略。

入参:

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

func toInt8(OverflowStrategy)

public func toInt8(overflowHandling!: OverflowStrategy = throwing): Int8

功能:将当前 Decimal 对象转化为 Int8 类型,支持自定义溢出策略。

入参:

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

func toIntNative(OverflowStrategy)

public func toIntNative(overflowHandling!: OverflowStrategy = throwing): IntNative

功能:将当前 Decimal 对象转化为 IntNative 类型,支持自定义溢出策略。

入参:

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(6.25)
    println("A.toInt8() = ${A.toInt8()}")
    println("A.toInt16() = ${A.toInt16()}")
    println("A.toInt32() = ${A.toInt32()}")
    println("A.toInt64() = ${A.toInt64()}")
    println("A.toIntNative() = ${A.toIntNative()}")
}

运行结果:

A.toInt8() = 6
A.toInt16() = 6
A.toInt32() = 6
A.toInt64() = 6
A.toIntNative() = 6

func toString()

public func toString(): String

功能:以不带指数形式打印输出 Decimal 对象,小于 0 时以 “-” 开头后跟十进制数字,大于等于 0 时,直接打印输出数字,不额外添加 “+”。

返回值:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(-5)
    let B = Decimal(3 ** 5)

    println("A.hashCode() = ${A.hashCode()}")
    println("B.toString() = ${B.toString()}")
}

运行结果:

A.hashCode() = 155
B.toString() = 243

func toUInt16(OverflowStrategy)

public func toUInt16(overflowHandling!: OverflowStrategy = throwing): UInt16

功能:将当前 Decimal 对象转化为 UInt16 类型,支持自定义溢出策略。

入参:

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

func toUInt32(OverflowStrategy)

public func toUInt32(overflowHandling!: OverflowStrategy = throwing): UInt32

功能:将当前 Decimal 对象转化为 UInt32 类型,支持自定义溢出策略。

入参:

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

func toUInt64(OverflowStrategy)

public func toUInt64(overflowHandling!: OverflowStrategy = throwing): UInt64

功能:将当前 Decimal 对象转化为 UInt64 类型,支持自定义溢出策略。

入参:

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

func toUInt8(OverflowStrategy)

public func toUInt8(overflowHandling!: OverflowStrategy = throwing): UInt8

功能:将当前 Decimal 对象转化为 UInt8 类型,支持自定义溢出策略。

入参:

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

func toUIntNative(OverflowStrategy)

public func toUIntNative(overflowHandling!: OverflowStrategy = throwing): UIntNative

功能:将当前 Decimal 对象转化为 UIntNative 类型,支持自定义溢出策略。

入参:

返回值:

异常:

  • OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时,抛出此异常。

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(6.25)
    println("A.toUInt8() = ${A.toUInt8()}")
    println("A.toUInt16() = ${A.toUInt16()}")
    println("A.toUInt32() = ${A.toUInt32()}")
    println("A.toUInt64() = ${A.toUInt64()}")
    println("A.toUIntNative() = ${A.toUIntNative()}")
}

运行结果:

A.toUInt8() = 6
A.toUInt16() = 6
A.toUInt32() = 6
A.toUInt64() = 6
A.toUIntNative() = 6

operator func !=(Decimal)

public operator func !=(d: Decimal): Bool

功能:不等比较运算,不等运算符重载,判断入参 Decimal 对象与当前对象是否不相等,返回比较结果值。

参数:

返回值:

  • Bool - 返回不等比较运算结果。当前对象不等于入参时,返回 true,否则返回 false。

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(-5)
    let B = Decimal(3)

    println(" -A = ${-A}")
    println(" A <= B = ${ A <= B}")
    println(" A != B = ${ A != B}")
}

运行结果:

-A = 5
A <= B = true
A != B = true

operator func *(Decimal)

public operator func *(d: Decimal): Decimal

功能:乘法运算,乘法运算符重载,乘以入参 Decimal 对象,返回结果值。保留乘法运算结果实际精度值。

参数:

返回值:

  • Decimal - 生成一个新的 Decimal 对象,用于存储乘法运算结果值。

异常:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A * B
    println("C = ${C}")
}

运行结果:

C = 6

operator func **(Int64)

public operator func **(n: Int64): Decimal

功能:乘方运算,乘方运算符重载,获取当前对象为底数,入参 Int64 为指数的乘方运算结果,其中指数为入参 Decimal 对象的整数部分。

注意:

指数为负值且结果为无限小数场景时,默认采用 IEEE 754-2019 decimal128 对结果进行舍入。

参数:

  • n: Int64 - 乘方运算的指数值。

返回值:

  • Decimal - 生成一个新的 Decimal 对象,用于存储乘方运算结果值。

异常:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2.5)
    println("A ** 3 = ${A ** 3}")
}

运行结果:

A ** 3 = 15.625

operator func +(Decimal)

public operator func +(d: Decimal): Decimal

功能:加法运算,加法运算符重载,加上入参 Decimal 对象,返回结果值。结果保留实际精度值。

参数:

异常:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A + B
    println("C = ${C}")
}

运行结果:

C = 5

operator func -()

public operator func -(): Decimal

功能:取反运算,一元负数运算符重载,对当前 Decimal 对象取反,返回结果值。保留取反运算结果实际精度值。

返回值:

  • Decimal - 生成一个新的 Decimal 对象,用于存储取反结果值。

operator func -(Decimal)

public operator func -(d: Decimal): Decimal

功能:减法运算,减法运算符重载,减去入参 Decimal 对象,返回结果值。保留减法运算结果实际精度值。

参数:

返回值:

  • Decimal - 生成一个新的 Decimal 对象,用于存储减法运算结果值。

异常:

  • OverflowException - 当被减数与减数标度值相减溢出时,抛出此异常。

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A - B
    println("C = ${C}")
}

运行结果:

C = -1

operator func <(Decimal)

public operator func <(d: Decimal): Bool

功能:小于比较运算,小于运算符重载,判断入参 Decimal 对象是否小于当前对象,返回比较结果值。

参数:

返回值:

  • Bool - 返回小于比较运算结果。当前对象小于入参时,返回 true,否则返回 false。

operator func <=(Decimal)

public operator func <=(d: Decimal): Bool

功能:小于等于比较运算,小于等于运算符重载,判断入参 Decimal 对象是否小于等于当前对象,返回比较结果值。

参数:

返回值:

  • Bool - 返回小于等于比较运算结果。当前对象小于等于入参时,返回 true,否则返回 false

operator func ==(Decimal)

public operator func ==(d: Decimal): Bool

功能:等于比较运算,等于运算符重载,判断入参 Decimal 对象与当前对象是否相等,返回比较结果值。

参数:

返回值:

  • Bool - 返回等于比较运算结果。当前对象等于入参时,返回 true,否则返回 false。

operator func >(Decimal)

public operator func >(d: Decimal): Bool

功能:大于比较运算,大于运算符重载,判断入参 Decimal 对象是否大于当前对象,返回比较结果值。

参数:

返回值:

  • Bool - 返回大于比较运算结果。当前对象大于入参时,返回 true,否则返回 false

operator func >=(Decimal)

public operator func >=(d: Decimal): Bool

功能:大于等于比较运算,大于等于运算符重载,判断入参 Decimal 对象是否大于等于当前对象,返回比较结果值。

参数:

返回值:

  • Bool - 返回大于等于比较运算结果。当前对象大于等于入参时,返回 true,否则返回 false。

operator func /(Decimal)

public operator func /(d: Decimal): Decimal

功能:除法运算,除法运算符重载,除以入参 Decimal 对象,返回结果值。

注意:

结果为无限小数场景时,默认采用 IEEE 754-2019 decimal128 对结果进行舍入。

参数:

返回值:

  • Decimal - 生成一个新的 Decimal 对象,用于存储除法运算结果值。

异常:

示例:

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A / B
    println("C = ${C}")
}

运行结果:

C = 0.6666666666666666666666666666666667

BigInt 基础数学运算示例

以下为通过不同构造函数初始化 BigInt 对象的,并进行基础数学运算示例:

import std.math.numeric.*

main() {
    let int1: BigInt = BigInt("123456789")
    let int2: BigInt = BigInt("987654321")

    println("${int1} + ${int2} = ${int1 + int2}")
    println("${int1} - ${int2} = ${int1 - int2}")
    println("${int1} * ${int2} = ${int1 * int2}")
    println("${int1} / ${int2} = ${int1 / int2}")
    let (quo, mod) = int1.divAndMod(int2)
    println("${int1} / ${int2} = ${quo} .. ${mod}")

    return 0
}

运行结果:

123456789 + 987654321 = 1111111110
123456789 - 987654321 = -864197532
123456789 * 987654321 = 121932631112635269
123456789 / 987654321 = 0
123456789 / 987654321 = 0 .. 123456789

BigInt 基本属性示例

以下为初始化 BigInt 对象的,并查询对象的基本属性的示例:

import std.math.numeric.*

main() {
    let int = BigInt("-123456")
    println("BigInt: ${int}")
    println("BigInt sign: ${int.sign}")
    println("BigInt bitLen: ${int.bitLen}")
    return 0
}

运行结果:

BigInt: -123456
BigInt sign: -1
BigInt bitLen: 18

BigInt 大小比较示例

以下为初始化多个 BigInt 对象,相互之间大小比较的示例:

import std.math.numeric.*

main() {
    let int1 = BigInt("123456789")
    let int2 = BigInt("987654321")
    println("${int1} > ${int2} = ${int1 > int2}")
    println("${int1} < ${int2} = ${int1 < int2}")
    println("${int1} == ${int2} = ${int1 == int2}")
    println("${int1} != ${int2} = ${int1 != int2}")
    println("${int1} <= ${int2} = ${int1 <= int2}")
    println("${int1} >= ${int2} = ${int1 >= int2}")
    println("${int1}.compare(${int2}) = ${int1.compare(int2)}")
    return 0
}

运行结果:

123456789 > 987654321 = false
123456789 < 987654321 = true
123456789 == 987654321 = false
123456789 != 987654321 = true
123456789 <= 987654321 = true
123456789 >= 987654321 = false
123456789.compare(987654321) = Ordering.LT

Decimal 基础数学运算示例

以下为通过不同构造函数初始化 Decimal 对象的,并进行基础数学运算示例:

import std.math.*
import std.math.numeric.*

main() {
    let decimal1: Decimal = Decimal("12345.6789")
    let decimal2: Decimal = Decimal(BigInt("987654321"), 6)
    println("${decimal1} + ${decimal2} = ${decimal1 + decimal2}")
    println("${decimal1} - ${decimal2} = ${decimal1 - decimal2}")
    println("${decimal1} * ${decimal2} = ${decimal1 * decimal2}")
    println("${decimal1} / ${decimal2} = ${decimal1 / decimal2}")
    println("${decimal1} / ${decimal2} with precision 10 and rounding mode HALF_EVEN = ${decimal1.divWithPrecision(decimal2, 10, roundingMode: HALF_EVEN)}")
    let (quo, rem) = decimal1.divAndRem(decimal2)
    println("${decimal1} / ${decimal2} = ${quo} .. ${rem}")
    return 0
}

运行结果:

12345.6789 + 987.654321 = 13333.333221
12345.6789 - 987.654321 = 11358.024579
12345.6789 * 987.654321 = 12193263.1112635269
12345.6789 / 987.654321 = 12.49999988609375000142382812498220
12345.6789 / 987.654321 with precision 10 and rounding mode HALF_EVEN = 12.49999989
12345.6789 / 987.654321 = 12 .. 493.827048

Decimal 基本属性示例

以下为初始化 Decimal 对象,并查询对象的基本属性的示例:

import std.math.*
import std.math.numeric.*

main() {
    let decimalProperties = Decimal("-123456.7890123456789")
    println("decimal: ${decimalProperties}")
    println("decimal sign: ${decimalProperties.sign}")
    println("decimal scale: ${decimalProperties.scale}")
    println("decimal value: ${decimalProperties.value}")
    println("decimal precision: ${decimalProperties.precision}")

    // 如果希望初始化一个带有指定精度和舍入方式的 Decimal 对象,可以采用如下方式
    let decimalProperties2 = Decimal("-123456.7890123456789").roundWithPrecision(10, roundingMode: HALF_EVEN)
    println("decimal2: ${decimalProperties2}")
    println("decimal2 sign: ${decimalProperties2.sign}")
    println("decimal2 scale: ${decimalProperties2.scale}")
    println("decimal2 value: ${decimalProperties2.value}")
    println("decimal2 precision: ${decimalProperties2.precision}")

    return 0
}

运行结果:

decimal: -123456.7890123456789
decimal sign: -1
decimal scale: 13
decimal value: -1234567890123456789
decimal precision: 19
decimal2: -123456.7890
decimal2 sign: -1
decimal2 scale: 4
decimal2 value: -1234567890
decimal2 precision: 10

Decimal 大小比较示例

以下为初始化多个 Decimal 对象,相互之间大小比较的示例:

import std.math.*
import std.math.numeric.*

main() {
    let decimal1 = Decimal("12345.6789")
    let decimal2 = Decimal("987.654321")
    println("${decimal1} > ${decimal2} = ${decimal1 > decimal2}")
    println("${decimal1} < ${decimal2} = ${decimal1 < decimal2}")
    println("${decimal1} == ${decimal2} = ${decimal1 == decimal2}")
    println("${decimal1} != ${decimal2} = ${decimal1 != decimal2}")
    println("${decimal1} <= ${decimal2} = ${decimal1 <= decimal2}")
    println("${decimal1} >= ${decimal2} = ${decimal1 >= decimal2}")
    println("${decimal1}.compare(${decimal2}) = ${decimal1.compare(decimal2)}")
    return 0
}

运行结果:

12345.6789 > 987.654321 = true
12345.6789 < 987.654321 = false
12345.6789 == 987.654321 = false
12345.6789 != 987.654321 = true
12345.6789 <= 987.654321 = false
12345.6789 >= 987.654321 = true
12345.6789.compare(987.654321) = Ordering.GT

std.net 包

功能介绍

net 包用于进行网络通信,提供启动 Socket 服务器、连接 Socket 服务器、发送数据、接收数据等功能和 IP 地址、IP前缀(又称IP子网)、Socket 地址的相关数据结构。

我们支持 UDP/TCP/UDS 三种 Socket 类型,用户可按需选用。

UDP(User Datagram Protocol,用户数据报协议)是一种无连接的传输协议,它不提供可靠性和流量控制,但是具有较低的延迟和较小的网络开销。UDP协议主要用于一些实时性要求高的应用场景,例如视频直播、在线游戏等。

TCP(Transmission Control Protocol,传输控制协议)是一种面向连接的、可靠的传输协议。它提供了可靠的数据传输、流量控制、拥塞控制、错误检测和流量管理等功能,是互联网中最常用的传输协议之一。

UDS(Unix Domain Socket)是一种用于在同一台计算机上的进程之间进行通信的机制。与网络套接字不同,UDS不需要网络协议栈和网络设备,因此可以更快地进行通信,具有更低的延迟和更高的吞吐量。

如下为本库提供 Socket 的类继承关系:

Hierarchy
 Resource
 ├StreamingSocket
 │   ├TcpSocket
 │   └UnixSocket
 │
 ├DatagramSocket
 │   ├UdpSocket
 │   └UnixDatagramSocket
 │
 └ServerSocket
     ├TcpServerSocket
     └UnixServerSocket

API 列表

常量&变量

常量&变量名功能
IPV4_ALL_ROUTERIPv4 预留的组播地址。
IPV4_ALL_SYSTEMIPv4 多播地址。
IPV4_BROADCASTIPv4 广播地址。
IPV4_LOCAL_HOSTIPv4 本地地址。
IPV4_ZEROIPv4 通用地址。
IPV6_INTERFACE_LOCAL_ALL_NODESIPv6 在节点本地范围的所有节点多播地址。
IPV6_LINK_LOCAL_ALL_NODESIPv6 在链路本地范围的所有节点多播地址。
IPV6_LINK_LOCAL_ALL_ROUTERSIPv6 链路本地范围的所有路由器多播地址。
IPV6_LOOPBACKIPv6 环回地址(本地地址)。
IPV6_ZEROIPv6 通用地址。

接口

接口名功能
DatagramSocketDatagramSocket 是一种接收和读取数据包的套接字。
ServerSocket提供服务端的 Socket 需要的接口。
StreamingSocket双工流模式下的运行的 Socket,可被读写。

类名功能
IPAddress此类表示Internet协议(IP)地址。
IPPrefix这个类表示一个 IP 前缀(也称为“IP子网”),即一个连续的 IP 地址块,边界为2的幂。
IPSocketAddress此类实现了IP协议 Socket 地址(IP地址+端口号)。
IPv4Address此类表示 Internet 协议版本4(IPv4)地址。
IPv6Address此类表示 Internet 协议版本6(IPv6)地址。
RawSocketRawSocket 提供了套接字的基本功能。
SocketAddress此类表示协议无关的 Socket 地址。
TcpServerSocket监听 TCP 连接的服务端。
TcpSocket请求 TCP 连接的客户端。
UdpSocket提供 udp 报文通信。
UnixDatagramSocket提供基于数据包的主机通讯能力。
UnixServerSocket提供基于双工流的主机通讯服务端。
UnixSocket提供基于双工流的主机通讯客户端。
UnixSocketAddress此类实现了 Unix Domain Socket 地址。

枚举

枚举名功能
SocketNet传输层协议类型。

结构体

结构体名功能
AddressFamily地址族用于在个别地址的使用可能不明确的上下文中标识用于网络通信的个别网络地址方案或编号计划。
OptionLevel提供了常用的套接字选项级别。
OptionName提供了常用的套接字选项。
ProtocolType提供了常用的套接字协议,以及通过指定 Int32 值来构建套接字协议的功能。
RawAddress提供了 RawSocket 的通信地址创建和获取功能。
SocketDomain提供了常用的套接字通信域,以及通过指定 Int32 值来构建套接字通信域的功能。
SocketKeepAliveConfigTCP KeepAlive 属性配置。
SocketOptionsSocketOptions 存储了设置套接字选项的一些参数常量方便后续调用。
SocketType提供了常用的套接字类型,以及通过指定 Int32 值来构建套接字类型的功能。

异常类

异常类名功能
SocketException提供套接字相关的异常处理。
SocketTimeoutException提供字符格式相关的异常处理。

常量&变量

let IPV4_ALL_ROUTER

public let IPV4_ALL_ROUTER: Array<UInt8>

功能:IPV4 预留的组播地址。

用于向所有本地网络上的所有路由器发送路由信息。

类型:Array<UInt8>

let IPV4_ALL_SYSTEM

public let IPV4_ALL_SYSTEM: Array<UInt8>

功能:IPV4 多播地址。

用于向同一局域网中的所有主机发送多播数据包。

类型:Array<UInt8>

let IPV4_BROADCAST

public let IPV4_BROADCAST: Array<UInt8>

功能:IPV4 广播地址。

类型:Array<UInt8>

let IPV4_LOCAL_HOST

public let IPV4_LOCAL_HOST: Array<UInt8>

功能:IPV4 本地地址。

类型:Array<UInt8>

let IPV4_ZERO

public let IPV4_ZERO: Array<UInt8>

功能:IPV4 通用地址。

类型:Array<UInt8>

let IPV6_INTERFACE_LOCAL_ALL_NODES

public let IPV6_INTERFACE_LOCAL_ALL_NODES: Array<UInt8>

功能:IPv6 在节点本地范围的所有节点多播地址。

类型:Array<UInt8>

public let IPV6_LINK_LOCAL_ALL_NODES: Array<UInt8>

功能:IPv6 在链路本地范围的所有节点多播地址。

类型:Array<UInt8>

public let IPV6_LINK_LOCAL_ALL_ROUTERS: Array<UInt8>

功能:IPv6 链路本地范围的所有路由器多播地址。

类型:Array<UInt8>

let IPV6_LOOPBACK

public let IPV6_LOOPBACK: Array<UInt8>

功能:IPV6 环回地址(本地地址)。

类型:Array<UInt8>

let IPV6_ZERO

public let IPV6_ZERO: Array<UInt8>

功能:IPV6 通用地址。

类型:Array<UInt8>

接口

interface DatagramSocket

public interface DatagramSocket <: Resource & ToString {
    prop localAddress: SocketAddress
    prop remoteAddress: ?SocketAddress
    mut prop receiveTimeout: ?Duration
    mut prop sendTimeout: ?Duration
    func receiveFrom(buffer: Array<Byte>): (SocketAddress, Int64)
    func sendTo(address: SocketAddress, payload: Array<Byte>): Unit
}

功能:DatagramSocket 是一种接收和读取数据包的套接字。

一个数据包通常有有限的大小,可能为空。不同的数据包套接字类型有不同的数据包最大值。例如 UDP 套接字一次可以处理最大 64KB 的数据包。 数据包传输不是一种可靠的传输,不保证传输顺序。数据包大小在发送端决定,例如:一端发送了 10 字节和 15 字节的报文,对端将收到相同大小的对应报文,10 字节和 15 字节。

父类型:

prop localAddress

prop localAddress: SocketAddress

功能:读取 Socket 将要或已经被绑定的本地地址。

类型:SocketAddress

异常:

  • SocketException - 当 Socket 已经被关闭或无可用的本地地址(本地地址未配置并且套接字未连接)时,抛出异常。

prop receiveTimeout

mut prop receiveTimeout: ?Duration

功能:设置和读取 receiveFrom 超时时间,无超时时间设置为 None

如果设置的时间过小将会设置为最小时钟周期值;过大时将设置为最大超时时间(263-1 纳秒);默认值为 None

类型:?Duration

异常:

prop remoteAddress

prop remoteAddress: ?SocketAddress

功能:读取 Socket 已经连接的远端地址,当 Socket 未连接时返回 None。

类型:?SocketAddress

异常:

prop sendTimeout

mut prop sendTimeout: ?Duration

功能:设置和读取 sendTo 超时时间,默认设置为 None

如果设置的时间过小将会设置为最小时钟周期值;过大时将设置为最大超时时间(263-1 纳秒);默认值为 None

类型:?Duration

异常:

func receiveFrom(Array<Byte>)

func receiveFrom(buffer: Array<Byte>): (SocketAddress, Int64)

功能:阻塞式等待收取报文到 buffer 中。

参数:

  • buffer: Array<Byte> - 存储报文内容的缓存空间,buffer 应当有一个合适的大小,否则可能导致收取报文时报文被截断,并且返回的报文大小值大于 buffer 的大小。

返回值:

  • (SocketAddress, Int64) - 报文发送地址和收取到的报文大小(可能为 0,或大于参数 buffer 大小)。

异常:

func sendTo(SocketAddress, Array<Byte>)

func sendTo(address: SocketAddress, payload: Array<Byte>): Unit

功能:发送报文到指定的远端地址,当对端无足够缓存时,此操作可能被阻塞,报文可能被丢弃。

参数:

  • address: SocketAddress - 需要发送到的远端地址。
  • payload: Array<Byte> - 需要发送的报文内容。

interface ServerSocket

public interface ServerSocket <: Resource & ToString {
    prop localAddress: SocketAddress
    func accept(): StreamingSocket
    func accept(timeout!: ?Duration): StreamingSocket
    func bind(): Unit
}

功能:提供服务端的 Socket 需要的接口。

父类型:

prop localAddress

prop localAddress: SocketAddress

功能:读取 Socket 将要或已经被绑定的本地地址。

类型:SocketAddress

异常:

func accept()

func accept(): StreamingSocket

功能:接受一个客户端套接字的连接请求,阻塞式等待连接请求。

返回值:

func accept(?Duration)

func accept(timeout!: ?Duration): StreamingSocket

功能:接受一个客户端套接字的连接请求,阻塞式等待连接请求。

参数:

  • timeout!: ?Duration - 等待连接超时的时间。

返回值:

异常:

func bind()

func bind(): Unit

功能:绑定套接字。

当没有设置 reuse 属性,本地端口、地址、文件路径已被占用或者上次绑定套接字的连接失败后需要 close 套接字。不支持多次重试此操作后可执行 accept() 操作。

异常:

interface StreamingSocket

public interface StreamingSocket <: IOStream & Resource & ToString {
    prop localAddress: SocketAddress
    prop remoteAddress: SocketAddress
    mut prop readTimeout: ?Duration
    mut prop writeTimeout: ?Duration
}

功能:双工流模式下的运行的 Socket,可被读写。

StreamingSocket 可以被绑定 (bind) 和连接 (connect),用户可以通过属性设置绑定和连接的远端和本地地址。 StreamingSocket 可以有序分包传输字节流。我们会使用一段缓存空间存储读写的字节流。读取接口 (read()) 默认在无数据到来时阻塞式等待,直到下一次数据到达,或超时。写操作 (write()) 会写入缓存中的数据并在后续被发出,如果缓存不足,或者写入速度快于转发速度,写操作将会阻塞等待缓存空闲,或超时。 读写字符始终保持有序,但不保证传输过程中的分包策略及大小与发包时一致。例如:一端发送 10 字节报文后,又发送了 15 字节报文,对端可能分别收到 10 字节 和 15 字节报文,也可能一次性收到 25 字节的一个报文。 当收到一段异常报文时,将返回报文长度为 -1 。

父类型:

prop localAddress

prop localAddress: SocketAddress

功能:读取 Socket 将要或已经被绑定的本地地址。

类型:SocketAddress

异常:

  • SocketException - 当 Socket 已经被关闭或无可用的本地地址(本地地址未配置并且套接字未连接)时,抛出异常。

prop readTimeout

mut prop readTimeout: ?Duration

功能:设置和读取读超时时间。

如果设置的时间过小将会设置为最小时钟周期值;过大时将设置为最大超时时间(263-1 纳秒);默认值为 None

类型:?Duration

异常:

prop remoteAddress

prop remoteAddress: SocketAddress

功能:读取 Socket 将要或已经连接的远端地址。

类型:SocketAddress

异常:

prop writeTimeout

mut prop writeTimeout: ?Duration

功能:设置和读取写超时时间。

如果设置的时间过小将会设置为最小时钟周期值;过大时将设置为最大超时时间(263-1 纳秒);默认值为 None

类型:?Duration

异常:

class IPAddress

abstract sealed class IPAddress <: ToString & Equatable<IPAddress> & Hashable & BigEndianOrder<IPAddress>

功能:此类表示Internet协议(IP)地址。互联网协议地址(IP地址)是一个数字标签,例如 192.0.2.12001:0db8:0000:0000:0000:ff00:0042:8329,分配给连接到使用互联网协议进行通信的计算机网络设备。IP地址有两个主要功能:网络接口标识和位置寻址。

父类型:

prop hostName

public prop hostName: Option<String>

功能:返回当前 IPAddress 对象对应的主机名,如果无法成功解析,则为 None,当前暂未实现。

异常:

类型:Option<String>

prop size

public prop size: Int64

功能:获取 IP 地址对象字节长度。

类型:Int64

static func parse(String)

public static func parse(s: String): IPAddress

功能:将 IP 协议的 Socket 字符串转换为 IPAddress 对象。

参数:

  • s: String - IP 协议的 Socket 字符串。

异常:

返回值:

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let v4: IPAddress = IPAddress.parse("192.168.1.2")
    let v6: IPAddress = IPAddress.parse("2001:0250:1006:dff0:4913:2aa5:8075:7c10")
    @Assert(v4.toString(), "192.168.1.2")
    @Assert(v6.toString(), "2001:250:1006:dff0:4913:2aa5:8075:7c10")
}

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): IPAddress

功能:从字节数组中以大端序的方式读取一个 IPAddress 对象。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

异常:

返回值:

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let bufferV4: Array<Byte> = [0xC0, 0xA8, 0x1, 0x2]
    let bufferV6: Array<Byte> = [0x20, 0x01, 0x02, 0x50, 0x10, 0x06, 0xdf, 0xf0, 0x49, 0x13, 0x2a, 0xa5, 0x80, 0x75, 0x7c, 0x10]
    let v4: IPAddress = IPAddress.readBigEndian(bufferV4)
    let v6: IPAddress = IPAddress.readBigEndian(bufferV6)
    @Assert(v4.toString(), "192.168.1.2")
    @Assert(v6.toString(), "2001:250:1006:dff0:4913:2aa5:8075:7c10")
}

static func resolve(String)

public static func resolve(domain: String): Array<IPAddress>

功能:解析域名,得到 IPAddress 列表。

参数:

返回值:

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let iplist: Array<IPAddress> = IPAddress.resolve("localhost")
    println(iplist)
}
// may output: [127.0.0.1, ::1]

static func tryParse(String)

public static func tryParse(s: String): Option<IPAddress>

功能:将 IP 地址字符串转换为 IPAddress 对象,如果不是合法字符串,则返回None

参数:

  • s: String - IP 地址字符串。

返回值:

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let v4: ?IPAddress = IPAddress.tryParse("192.168.1.2")
    let v6: ?IPAddress = IPAddress.tryParse("2001:0250:1006:dff0:4913:2aa5:8075:7c10")
    @Assert(v4.toString(), "Some(192.168.1.2)")
    @Assert(v6.toString(), "Some(2001:250:1006:dff0:4913:2aa5:8075:7c10)")
}

func getAddressBytes()

public func getAddressBytes(): Array<Byte>

功能:返回此 IPAddress 对象的原始IP地址。

返回值:

返回值:

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let expectV4: Array<Byte> = [0xC0, 0xA8, 0x1, 0x2]
    let expectV6: Array<Byte> = [0x20, 0x01, 0x02, 0x50, 0x10, 0x06, 0xdf, 0xf0, 0x49, 0x13, 0x2a, 0xa5, 0x80, 0x75, 0x7c, 0x10]
    let v4: IPAddress = IPAddress.parse("192.168.1.2")
    let v6: IPAddress = IPAddress.parse("2001:0250:1006:dff0:4913:2aa5:8075:7c10")
    @Assert(v4.getAddressBytes(), expectV4)
    @Assert(v6.getAddressBytes(), expectV6)
}

func getPrefix(UInt8)

public func getPrefix(prefixLen: UInt8): IPPrefix

功能:此 IPAddress 地址对象根据指定的网络前缀长度创建一个网络前缀对象。

参数:

  • prefixLen: UInt8 - 网络前缀长度。

异常:

返回值:

func hashCode()

public func hashCode(): Int64

功能:获取 hashcode 值。

返回值:

  • Int64 - hashcode 值。

func isGlobalUnicast()

public func isGlobalUnicast(): Bool

功能:判断此 IPAddress 对象是不是全局单播地址。

返回值:

  • Bool - 返回 true 表示是全局单播地址,否则返回 false。

func isIPv4()

public func isIPv4(): Bool

功能:判断此 IPAddress 对象是不是 IPv4 地址。

返回值:

  • Bool - 返回 true 表示是 IPv4 地址,否则返回 false。

func isIPv6()

public func isIPv6(): Bool

功能:判断此 IPAddress 对象是不是 IPv6 地址。

返回值:

  • Bool - 返回 true 表示是 IPv6 地址,否则返回 false。

func isLinkLocal()

public func isLinkLocal(): Bool

功能:判断此 IPAddress 对象是不是链路本地地址。

返回值:

  • Bool - 返回 true 表示是链路本地地址,否则返回 false。

func isLoopback()

public func isLoopback(): Bool

功能:判断此 IPAddress 对象是不是环回地址。

返回值:

  • Bool - 返回 true 表示是环回地址,否则返回 false。

func isMulticast()

public func isMulticast(): Bool

功能:判断此 IPAddress 对象是不是多播地址。

返回值:

  • Bool - 返回 true 表示是多播地址,否则返回 false。

func isPrivate()

public func isPrivate(): Bool

功能:判断此 IPAddress 对象是不是私有地址。

返回值:

  • Bool - 返回 true 表示是私有地址,否则返回 false。

func isUnspecified()

public func isUnspecified(): Bool

功能:判断此 IPAddress 对象是不是“未指定” IP 地址。

返回值:

  • Bool - 返回 true 表示是“未指定” IP 地址,否则返回 false。

open func writeBigEndian(Array<Byte>)

public open func writeBigEndian(buffer: Array<Byte>): Int64

功能:返回此 IPAddress 对象以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

异常:

返回值:

  • Int64 - 写入的数据的字节数。

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let buffer = Array<Byte>(128, repeat: 0)
    let expectV4: Array<Byte> = [0xC0, 0xA8, 0x1, 0x2]
    let expectV6: Array<Byte> = [0x20, 0x01, 0x02, 0x50, 0x10, 0x06, 0xdf, 0xf0, 0x49, 0x13, 0x2a, 0xa5, 0x80, 0x75, 0x7c, 0x10]
    let v4: IPAddress = IPAddress.parse("192.168.1.2")
    let v6: IPAddress = IPAddress.parse("2001:0250:1006:dff0:4913:2aa5:8075:7c10")
    var len = v4.writeBigEndian(buffer)
    @Assert(buffer[..len], expectV4)
    len = v6.writeBigEndian(buffer)
    @Assert(buffer[..len], expectV6)
}

func toString()

public func toString(): String

功能:返回当前 IPAddress 的文本表示字符串。

返回值:

  • String - 当前 IPAddress 的文本表示字符串,比如 a.b.c.d2001:db8:aaaa:bbbb:cccc:dddd:eeee:1

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let bufferV4: Array<Byte> = [0xC0, 0xA8, 0x1, 0x2]
    let bufferV6: Array<Byte> = [0x20, 0x01, 0x02, 0x50, 0x10, 0x06, 0xdf, 0xf0, 0x49, 0x13, 0x2a, 0xa5, 0x80, 0x75, 0x7c, 0x10]
    let v4: IPAddress = IPAddress.readBigEndian(bufferV4)
    let v6: IPAddress = IPAddress.readBigEndian(bufferV6)
    @Assert(v4.toString(), "192.168.1.2")
    @Assert(v6.toString(), "2001:250:1006:dff0:4913:2aa5:8075:7c10")
}

operator func ==(IPAddress)

public operator func ==(rhs: IPAddress): Bool

功能:判断两个 IPAddress 对象是否相等。

参数:

返回值:

  • Bool - 如果两个 IPAddress 对象相等,则返回 true;否则,返回 false

operator func !=(IPAddress)

public operator func !=(rhs: IPAddress): Bool

功能:判断两个 IPAddress 对象是否不等。

参数:

返回值:

  • Bool - 如果两个 IPAddress 对象不等,则返回 true;否则,返回 false

class IPPrefix

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

功能:这个类表示一个 IP 前缀,即一个连续的 IP 地址块,边界为2的幂(也称为“IP子网”)。

一个 IP 前缀由两条信息指定:

  • 起始IP地址(IPv4或IPv6)。这是前缀的第一个IP地址。
  • 前缀长度。这通过指定IP地址中的位数来指定前缀的长度,从网络字节顺序中的最高有效位开始,对于前缀中的所有地址都是恒定的。

例如,前缀 192.0.2.0/24 涵盖从192.0.2.0192.0.2.255(含)的256IPv4地址,前缀2001:db8:1:2涵盖从2001:db8:1:2::2001:db8:1:2:ffff:ffff:ffff:ffff(含)的2^64IPv6地址。这个类的对象是不可变的。

父类型:

prop address

public prop address: IPAddress

功能:获取构造当前 IPPrefix 对象时的 IPAddress 地址。

类型:IPAddress

prop prefixLength

public prop prefixLength: UInt8

功能:获取前缀长度。

类型:UInt8

static func parse(String)

public static func parse(s: String): IPPrefix

功能:将 IP 协议的 Socket 字符串转换为 IPPrefix 对象。

参数:

  • s: String - IP 协议的 Socket 字符串。

异常:

返回值:

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let v4: IPPrefix = IPPrefix.parse("192.168.1.2/24")
    let v6: IPPrefix = IPPrefix.parse("2001:0250:1006:dff0:4913:2aa5:8075:7c10/32")
    @Assert(v4.toString(), "192.168.1.2/24")
    @Assert(v6.toString(), "2001:250:1006:dff0:4913:2aa5:8075:7c10/32")
}

static func tryParse(String)

public static func tryParse(s: String): Option<IPPrefix>

功能:将 IP 协议的 Socket 字符串转换为 IPPrefix 对象,如果不是合法字符串,则返回None

参数:

  • s: String - IP 协议的 Socket 字符串。

返回值:

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let v4: ?IPPrefix = IPPrefix.tryParse("192.168.1.2/24")
    let v6: ?IPPrefix = IPPrefix.tryParse("2001:0250:1006:dff0:4913:2aa5:8075:7c10/32")
    @Assert(v4.toString(), "Some(192.168.1.2/24)")
    @Assert(v6.toString(), "Some(2001:250:1006:dff0:4913:2aa5:8075:7c10/32)")
}

func broadcast()

public func broadcast(): IPAddress

功能:返回此 IPPrefix 地址的广播地址。

返回值:

func contains(IPAddress)

public func contains(rhs: IPAddress): Bool

功能:此 IPPrefix 地址是不是包含指定的 IPAddress 地址。

参数:

返回值:

  • Bool - 返回 true 表示包含指定的 IPAddress 地址,false 表示不包含。

func contains(IPPrefix)

public func contains(rhs: IPPrefix): Bool

功能:此 IPPrefix 地址是不是包含指定的 IPPrefix 地址。

参数:

返回值:

  • Bool - 返回 true 表示包含指定的 IPPrefix 地址,false 表示不包含。

func hostmask()

public func hostmask(): IPAddress

功能:返回此 IPPrefix 地址的主机网络掩码地址。

返回值:

func masked()

public func masked(): IPPrefix

功能:返回此 IPPrefix 地址根据前缀长度进行掩码后的 IPPrefix 地址,比如 192.168.12.34/16 返回 192.168.0.0/16; fc00::1:2:3:4/16 返回 fc00::/16

返回值:

func netmask()

public func netmask(): IPAddress

功能:返回此 IPPrefix 地址的网络掩码地址。

返回值:

func network()

public func network(): IPAddress

功能:返回此 IPPrefix 地址的网络地址。

返回值:

func overlaps(IPPrefix)

public func overlaps(rhs: IPPrefix): Bool

功能:此 IPPrefix 地址是不是和指定的 IPPrefix 地址有重叠。

参数:

返回值:

  • Bool - 返回 true 表示和指定的 IPPrefix 地址有重叠,false 表示没有重叠。

func toString()

public func toString(): String

功能:返回当前 IPPrefix 的文本表示字符串。

返回值:

  • String - 当前 IPPrefix 的文本表示字符串,比如 192.168.0.0/16fc00::/16

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let v4: IPPrefix = IPAddress.parse("192.168.1.2").getPrefix(24)
    let v6: IPPrefix = IPAddress.parse("2001:0250:1006:dff0:4913:2aa5:8075:7c10").getPrefix(32)
    @Assert(v4.toString(), "192.168.1.2/24")
    @Assert(v6.toString(), "2001:250:1006:dff0:4913:2aa5:8075:7c10/32")
}

operator func ==(IPPrefix)

public operator func ==(rhs: IPPrefix): Bool

功能:判断两个 IPPrefix 对象是否相等。

参数:

返回值:

  • Bool - 如果两个 IPPrefix 对象相等,则返回 true;否则,返回 false

operator func !=(IPPrefix)

public operator func !=(rhs: IPPrefix): Bool

功能:判断两个 IPPrefix 对象是否不等。

参数:

返回值:

  • Bool - 如果两个 IPPrefix 对象不等,则返回 true;否则,返回 false

class IPSocketAddress

public class IPSocketAddress <: SocketAddress & Equatable<IPSocketAddress>{
    public init(address: Array<Byte>, port: UInt16)
    public init(address: String, port: UInt16)
    public init(address: IPAddress, port: UInt16)
}

功能:此类实现了IP协议 Socket 地址(IP地址+端口号)。它提供了一个不可变的对象,用于 Socket 的绑定、连接或作为返回值。

父类型:

prop address

public prop address: IPAddress

功能:获取当前 IPSocketAddress 对象的 IP 地址。

类型:IPAddress

prop family

public prop family: AddressFamily

功能:获取当前 IPSocketAddress 对象的地址族。

类型:AddressFamily

prop port

public prop port: UInt16

功能:获取当前 IPSocketAddress 对象的端口。

类型:UInt16

prop size

public prop size: Int64

功能:获取当前 IPSocketAddress 对象的原始字节长度。

类型:Int64

init(Array<Byte>, UInt16)

public init(address: Array<Byte>, port: UInt16)

功能:根据大端序 Array<Byte> 表示的 IP 地址和本机序 UInt16 端口构造 IPSocketAddress 地址。

参数:

  • address: Array<Byte> - 大端序 IP 地址。
  • port: UInt16 - 本机序端口。

异常:

init(String, UInt16)

public init(address: String, port: UInt16)

功能:根据字符串表示的 IP 地址和 本机序 UInt16 端口构造 IPSocketAddress 地址。

参数:

  • address: String - IP 地址字符串。
  • port: UInt16 - 本机序端口。

异常:

init(IPAddress, UInt16)

public init(address: IPAddress, port: UInt16)

功能:根据 IPAddress 对象和 本机序 UInt16 端口构造 IPSocketAddress 地址。

参数:

static func parse(String)

public static func parse(s: String): IPSocketAddress

功能:将 IP 协议的 Socket 字符串转换为 IPSocketAddress 对象。

参数:

  • s: String - IP 协议的 Socket 字符串。

异常:

返回值:

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let v4: IPSocketAddress = IPSocketAddress.parse("192.168.1.2:8080")
    let v6: IPSocketAddress = IPSocketAddress.parse("[2001:0250:1006:dff0:4913:2aa5:8075:7c10]:8080")
    @Assert(v4.address.toString(), "192.168.1.2")
    @Assert(v4.port, 8080u16)
    @Assert(v6.address.toString(), "2001:250:1006:dff0:4913:2aa5:8075:7c10")
    @Assert(v6.port, 8080u16)
    @Assert(v4.toString(), "192.168.1.2:8080")
    @Assert(v6.toString(), "[2001:250:1006:dff0:4913:2aa5:8075:7c10]:8080")
}

static func tryParse(String)

public static func tryParse(s: String): Option<IPSocketAddress>

功能:将 IP 协议的 Socket 字符串转换为 IPSocketAddress 对象,如果不是合法字符串,则返回None

参数:

  • s: String - IP 协议的 Socket 字符串。

返回值:

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let v4: ?IPSocketAddress = IPSocketAddress.tryParse("192.168.1.2")
    let v6: ?IPSocketAddress = IPSocketAddress.tryParse("2001:0250:1006:dff0:4913:2aa5:8075:7c10")
    @Assert(v4.toString(), "Some(192.168.1.2)")
    @Assert(v6.toString(), "Some(2001:250:1006:dff0:4913:2aa5:8075:7c10)")
}

func getAddressBytes()

public func getAddressBytes(): Array<Byte>

功能:返回此 IPSocketAddress 对象的原始地址的 Array<Byte> 表示,内容布局与 sockaddr_insockaddr_in6 一致。

返回值:

func hashCode()

public func hashCode(): Int64

功能:获取 hashcode 值。

返回值:

  • Int64 - hashcode 值。

func isIPv4()

public func isIPv4(): Bool

功能:判断此 IPSocketAddress 对象是不是 IPv4 Socket 地址。

返回值:

  • Bool - 返回 true 表示是 IPv4 地址,否则返回 false。

func isIPv6()

public func isIPv6(): Bool

功能:判断此 IPSocketAddress 对象是不是 IPv6 Socket 地址。

返回值:

  • Bool - 返回 true 表示是 IPv6 地址,否则返回 false。

func toString()

public func toString(): String

功能:返回当前 IPSocketAddress 的文本表示字符串。

返回值:

  • String - 当前 IPSocketAddress 的文本表示字符串,比如 192.168.1.2:8080[fc00::/16]:8080

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let v4: IPSocketAddress = IPSocketAddress.parse("192.168.1.2:8080")
    let v6: IPSocketAddress = IPSocketAddress.parse("[2001:0250:1006:dff0:4913:2aa5:8075:7c10]:8080")
    @Assert(v4.toString(), "192.168.1.2:8080")
    @Assert(v6.toString(), "[2001:250:1006:dff0:4913:2aa5:8075:7c10]:8080")
}

operator func ==(IPSocketAddress)

public operator func ==(rhs: IPSocketAddress): Bool

功能:判断两个 IPSocketAddress 对象是否相等。

参数:

返回值:

operator func !=(IPSocketAddress)

public operator func !=(rhs: IPSocketAddress): Bool

功能:判断两个 IPSocketAddress 对象是否不等。

参数:

返回值:

class IPv4Address

public class IPv4Address <: IPAddress & ToString & Equatable<IPv4Address> & LessOrEqual<IPv4Address> {
    public static let broadcast: IPv4Address
    public static let localhost: IPv4Address
    public static let unspecified: IPv4Address
    public init(bits: UInt32)
    public init(a: Byte, b: Byte, c: Byte, d: Byte)
}

功能:此类表示 Internet 协议版本4 (IPv4)地址。由 RFC 790RFC 1918RFC 2365 定义。

父类型:

static let broadcast

public static let broadcast: IPv4Address

功能:返回 IPv4Address 的广播地址:255.255.255.255

类型:IPv4Address

static let localhost

public static let localhost: IPv4Address

功能:返回 IPv4Addresslocalhost 地址:127.0.0.1

类型:IPv4Address

static let unspecified

public static let unspecified: IPv4Address

功能:返回表示未指定的 IPv4Address 地址:0.0.0.0,这对应于其他语言中的常量 INADDR_ANY

类型:IPv4Address

init(UInt32)

public init(bits: UInt32)

功能:根据本机字节序 UInt32 值构造 IPv4Address 地址。

参数:

init(Byte, Byte, Byte, Byte)

public init(a: Byte, b: Byte, c: Byte, d: Byte)

功能:根据4 个 8-bit 字节构造 IPv4Address 地址对象,文本将表示为 a.b.c.d

参数:

  • a: Byte - 8-bit 字节。
  • b: Byte - 8-bit 字节。
  • c: Byte - 8-bit 字节。
  • d: Byte - 8-bit 字节。

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): IPv4Address

功能:从字节数组中以大端序的方式读取一个 IPv4Address 对象。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

异常:

返回值:

func getPrefix(UInt8)

public func getPrefix(prefixLen: UInt8): IPPrefix

功能:将 IPv4Address 地址根据指定的网络前缀长度创建一个网络前缀对象。

参数:

  • prefixLen: UInt8 - 网络前缀长度,必须 >= 0 且 <= 32。

异常:

返回值:

func hashCode()

public func hashCode(): Int64

功能:获取 hashcode 值。

返回值:

  • Int64 - hashcode 值。

func isBroadcast()

public func isBroadcast(): Bool

功能:判断此 IPv4Address 对象是不是广播地址。

返回值:

  • Bool - 返回 true 表示是广播地址,否则返回 false。

func isGlobalUnicast()

public func isGlobalUnicast(): Bool

功能:判断此 IPv4Address 对象是不是全局单播地址。

返回值:

  • Bool - 返回 true 表示是全局单播地址,否则返回 false。

func isLinkLocal()

public func isLinkLocal(): Bool

功能:判断此 IPv4Address 对象是不是链路本地地址。

返回值:

  • Bool - 返回 true 表示是链路本地地址,否则返回 false。

func isLoopback()

public func isLoopback(): Bool

功能:判断此 IPv4Address 对象是不是环回地址。

返回值:

  • Bool - 返回 true 表示是环回地址,否则返回 false。

func isMulticast()

public func isMulticast(): Bool

功能:判断此 IPv4Address 对象是不是多播地址。

返回值:

  • Bool - 返回 true 表示是多播地址,否则返回 false。

func isPrivate()

public func isPrivate(): Bool

功能:判断此 IPv4Address 对象是不是私有地址。

返回值:

  • Bool - 返回 true 表示是私有地址,否则返回 false。

func isUnspecified()

public func isUnspecified(): Bool

功能:判断此 IPv4Address 对象是不是“未指定” IP 地址。

返回值:

  • Bool - 返回 true 表示是“未指定” IP 地址,否则返回 false。

func toBits()

public func toBits(): UInt32

功能:此 IPv4Address 地址转换为本机字节序的 UInt32 值。

返回值:

func toIPv6Compatible()

public func toIPv6Compatible(): IPv6Address

功能:此 IPv4Address 地址转换为 IPv4 兼容的 IPv6Address 地址。a.b.c.d 变为 ::a.b.c.d

返回值:

func toIPv6Mapped()

public func toIPv6Mapped(): IPv6Address

功能:此 IPv4Address 地址转换为 IPv4 映射的 IPv6Address 地址。a.b.c.d 变为 ::ffff:a.b.c.d

返回值:

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:此 IPv4Address 对象以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

异常:

返回值:

  • Int64 - 写入的数据的字节数。

func toString()

public func toString(): String

功能:返回当前 IPv4Address 的文本表示字符串。

返回值:

operator func <=(IPv4Address)

public operator func <=(rhs: IPv4Address): Bool

功能:判断本 IPv4Address 对象是否小于等于被比较的 IPv4Address 对象。

参数:

返回值:

operator func ==(IPv4Address)

public operator func ==(rhs: IPv4Address): Bool

功能:判断两个 IPv4Address 对象是否相等。

参数:

返回值:

  • Bool - 如果两个 IPv4Address 对象相等,则返回 true;否则,返回 false

operator func !=(IPv4Address)

public operator func !=(rhs: IPv4Address): Bool

功能:判断两个 IPv4Address 对象是否不等。

参数:

返回值:

  • Bool - 如果两个 IPv4Address 对象不等,则返回 true;否则,返回 false

class IPv6Address

public class IPv6Address <: IPAddress & ToString & Equatable<IPv6Address> & LessOrEqual<IPv6Address> {
    public static let localhost: IPv6Address
    public static let unspecified: IPv6Address
    public init(octets: Array<Byte>, scopeId!: ?UInt32 = None)
    public init(a: UInt16, b: UInt16, c: UInt16, d: UInt16, e: UInt16, f: UInt16, g: UInt16, h: UInt16, scopeId!: ?UInt32 = None)
}

功能:此类表示 Internet 协议版本6 (IPv6)地址。由 RFC4291RFC5952RFC4007 定义。

父类型:

static let localhost

public static let localhost: IPv6Address

功能:返回 IPv6Addresslocalhost 地址:::1

类型:IPv6Address

static let unspecified

public static let unspecified: IPv4Address

功能:返回表示未指定的 IPv6Address 地址:::,这对应于其他语言中的常量 INADDR_ANY

类型:IPv6Address

prop scopeId

public prop scopeId: ?UInt32

功能:获取默认范围 ID。

类型:Option<UInt32>

init(Array<Byte>, Option<UInt32>)

public init(octets: Array<Byte>, scopeId!: ?UInt32 = None)

功能:根据大端序 Array<Byte> 构造 IPv6Address 地址。

异常:

参数:

init(UInt16, UInt16, UInt16, UInt16, UInt16, UInt16, UInt16, UInt16, Option<UInt32>)

public init(a: UInt16, b: UInt16, c: UInt16, d: UInt16, e: UInt16, f: UInt16, g: UInt16, h: UInt16, scopeId!: ?UInt32 = None)

功能:根据 8 个 16-bit 分段构造 IPv6Address 地址对象,文本将表示为 a:b:c:d:e:f:g:h%scopeId

参数:

static func readBigEndian(Array<Byte>)

public static func readBigEndian(buffer: Array<Byte>): IPv6Address

功能:从字节数组中以大端序的方式读取一个 IPv6Address 对象。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待读取的数据。

异常:

返回值:

func getPrefix(UInt8)

public func getPrefix(prefixLen: UInt8): IPPrefix

功能:此 IPv6Address 地址对象根据指定的网络前缀长度创建一个网络前缀对象。

参数:

  • prefixLen: UInt8 - 网络前缀长度,必须 >= 0 且 <= 128。

异常:

返回值:

func hashCode()

public func hashCode(): Int64

功能:获取 hashcode 值。

返回值:

  • Int64 - hashcode 值。

func isGlobalUnicast()

public func isGlobalUnicast(): Bool

功能:判断此 IPv6Address 对象是不是全局单播地址。

返回值:

  • Bool - 返回 true 表示是全局单播地址,否则返回 false。

func isIPv4Mapped()

public func isIPv4Mapped(): Bool

功能:判断此 IPv6Address 对象是不是 IPv4 映射地址。

返回值:

  • Bool - 返回 true 表示是 IPv4 映射地址,否则返回 false。

func isLinkLocal()

public func isLinkLocal(): Bool

功能:判断此 IPv6Address 对象是不是链路本地地址。

返回值:

  • Bool - 返回 true 表示是链路本地地址,否则返回 false。

func isLoopback()

public func isLoopback(): Bool

功能:判断此 IPv6Address 对象是不是环回地址。

返回值:

  • Bool - 返回 true 表示是环回地址,否则返回 false。

func isMulticast()

public func isMulticast(): Bool

功能:判断此 IPv6Address 对象是不是多播地址。

返回值:

  • Bool - 返回 true 表示是多播地址,否则返回 false。

func isPrivate()

public func isPrivate(): Bool

功能:判断此 IPv6Address 对象是不是私有地址。

返回值:

  • Bool - 返回 true 表示是私有地址,否则返回 false。

func isTeredo()

public func isTeredo(): Bool

功能:判断此 IPv6Address 对象是不是 Teredo 地址。Teredo 前缀为 2001::/32

返回值:

  • Bool - 返回 true 表示是 Teredo 地址,否则返回 false。

func isUnspecified()

public func isUnspecified(): Bool

功能:判断此 IPv6Address 对象是不是“未指定” IP 地址。

返回值:

  • Bool - 返回 true 表示是“未指定” IP 地址,否则返回 false。

func scope(Option<UInt32>)

public func scope(scopeId: ?UInt32): IPv6Address

功能:使用本 IPv6Address 对象的地址值和指定的范围 ID 转换为新的 IPv6Address 对象,如果指定的范围 ID 为 None,则去除已有的范围 ID。

参数:

返回值:

func toIPv4()

public func toIPv4(): ?IPv4Address

功能:此 IPv6Address 地址转换为 IPv4 兼容的 IPv4Address 地址。比如 ::a.b.c.d::ffff:a.b.c.d 转成 a.b.c.d; ::1 转成 0.0.0.1. 所有不以全零或 ::ffff 开头的地址将返回 None

返回值:

func toIPv4Mapped()

public func toIPv4Mapped(): ?IPv4Address

功能:此 IPv6Address 地址转换为 IPv4 映射的 IPv4Address 地址。比如 ::ffff:a.b.c.d 转换为 a.b.c.d, 所有不以 ::ffff 开头的地址将返回 None

返回值:

func writeBigEndian(Array<Byte>)

public func writeBigEndian(buffer: Array<Byte>): Int64

功能:返回此 IPv6Address 对象以大端序的方式写入字节数组中。

参数:

  • buffer: Array<Byte> - 缓冲区,用于存放待写入的数据。

异常:

返回值:

  • Int64 - 写入的数据的字节数。

func toString()

public func toString(): String

功能:返回当前 IPv6Address 的文本表示字符串。

返回值:

  • String - 当前 IPv6Address 的文本表示字符串,比如 2001:db8:1:2:ffff:ffff:ffff:ffff

operator func <=(IPv6Address)

public operator func <=(rhs: IPv6Address): Bool

功能:判断本 IPv6Address 对象是否小于等于被比较的 IPv6Address 对象。

参数:

返回值:

operator func ==(IPv6Address)

public operator func ==(rhs: IPv6Address): Bool

功能:判断两个 IPv6Address 对象是否相等。

参数:

返回值:

  • Bool - 如果两个 IPv6Address 对象相等,则返回 true;否则,返回 false

operator func !=(IPv6Address)

public operator func !=(rhs: IPv6Address): Bool

功能:判断两个 IPv6Address 对象是否不等。

参数:

返回值:

  • Bool - 如果两个 IPv6Address 对象不等,则返回 true;否则,返回 false

class RawSocket

public class RawSocket {
    public init(domain: SocketDomain, `type`: SocketType, protocol: ProtocolType)
}

功能:RawSocket 提供了套接字的基本功能。

可以访问特定通信域(domain)、类型(type)和协议(protocol)组合的套接字。Socket 包已经提供了 TCP、 UDP 等常用网络协议的支持,因此,该类型适用于其他类型的网络编程需求。

注意:

  • 当前 RawSocket 已经验证的功能包括 TCP、UDP、UDS 以及 ICMP 协议套接字,其它类型使用上可能存在预期之外的问题。
  • 此外,由于接口的开放性,可以使用 connectlisten 的组合,部分场景可能存在预期外的问题。建议开发者使用时遵循正常的调用逻辑,避免产生问题。

prop localAddr

public prop localAddr: RawAddress

功能:获取当前 RawSocket 实例的本地地址。

类型:RawAddress

异常:

prop readTimeout

public mut prop readTimeout: ?Duration

功能:获取或设置当前 RawSocket 实例的读超时时间。

类型:?Duration

异常:

prop remoteAddr

public prop remoteAddr: RawAddress

功能:获取当前 RawSocket 实例的对端地址。

类型:RawAddress

异常:

prop writeTimeout

public mut prop writeTimeout: ?Duration

功能:获取或设置当前 RawSocket 实例的写超时时间。

类型:?Duration

异常:

init(SocketDomain, SocketType, ProtocolType)

public init(domain: SocketDomain, `type`: SocketType, protocol: ProtocolType)

功能:创建特定通信域、类型、协议组合的套接字。

参数:

异常:

  • SocketException - 当通信域、类型、协议组合无法创建套接字时,抛出异常。

func accept(?Duration)

public func accept(timeout!: ?Duration = None): RawSocket

功能:接收当前 RawSocket 实例监听时挂起连接队列上的第一个连接请求,返回一个用于通信的 RawSocket

参数:

  • timeout!: ?Duration - 等待连接请求的最大时间,默认值 None 表示一直等待。

返回值:

异常:

func bind(RawAddress)

public func bind(addr: RawAddress): Unit

功能:将当前 RawSocket 实例与指定的套接字地址进行绑定。

参数:

异常:

func close()

public func close(): Unit

功能:关闭当前 RawSocket 实例。

func connect(RawAddress, ?Duration)

public func connect(addr: RawAddress, timeout!: ?Duration = None): Unit

功能:向目标地址发送连接请求。

参数:

  • addr: RawAddress - 发送连接请求的目标地址。
  • timeout!: ?Duration - 等待连接接收的最大时间,默认值 None 表示一直等待。

异常:

func getSocketOption(Int32, Int32, CPointer<Byte>, CPointer<Int32>)

public unsafe func getSocketOption(level: Int32, option: Int32, value: CPointer<Byte>, len: CPointer<Int32>): Unit

功能:获取套接字选项的值。

参数:

  • level: Int32 - 套接字选项级别。
  • option: Int32 - 套接字选项名。
  • value: CPointer<Byte> - 套接字选项值。
  • len: CPointer<Int32> - 套接字选项值的长度。

异常:

func listen(Int32)

public func listen(backlog: Int32): Unit

功能:监听当前 RawSocket 实例绑定的地址。

参数:

  • backlog: Int32 - 等待队列增长的最大长度。

异常:

func receive(Array<Byte>, Int32)

public func receive(buffer: Array<Byte>, flags: Int32): Int64

功能:接收来自连接对端发送的数据。

参数:

  • buffer: Array<Byte> - 存储接收数据的数组。
  • flags: Int32 - 指定函数行为的标志。

返回值:

  • Int64 - 数据长度。

异常:

func receiveFrom(Array<Byte>, Int32)

public func receiveFrom(buffer: Array<Byte>, flags: Int32): (RawAddress, Int64)

功能:接收来自其它 RawSocket 实例的数据。

参数:

  • buffer: Array<Byte> - 存储接收数据的数组。
  • flags: Int32 - 指定函数行为的标志。

返回值:

异常:

func send(Array<Byte>, Int32)

public func send(buffer: Array<Byte>, flags: Int32): Unit

功能:向连接的对端发送数据。

参数:

  • buffer: Array<Byte> - 数据。
  • flags: Int32 - 指定函数行为的标志。

异常:

func sendTo(RawAddress, Array<Byte>, Int32)

public func sendTo(addr: RawAddress, buffer: Array<Byte>, flags: Int32): Unit

功能:向目标地址发送数据。若 RawSocketDATAGRAM 类型,发送的数据包大小不允许超过 65507 字节。

参数:

  • addr: RawAddress - 发送数据的目标地址。
  • buffer: Array<Byte> - 数据。
  • flags: Int32 - 指定函数行为的标志。

异常:

  • SocketException - 当前 RawSocket 实例已经关闭、发送数据失败或者 macOS 平台下 connect 被调用后调用 sendTo 时,抛出异常。
  • SocketTimeoutException - 当超过指定的写超时时间时,抛出异常。

func setSocketOption(Int32, Int32, CPointer<Byte>, Int32)

public unsafe func setSocketOption(level: Int32, option: Int32, value: CPointer<Byte>, len: Int32): Unit

功能:设置套接字选项。

参数:

  • level: Int32 - 套接字选项级别。
  • option: Int32 - 套接字选项名。
  • value: CPointer<Byte> - 套接字选项值。
  • len: Int32 - 套接字选项值的长度。

异常:

class SocketAddress

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

功能:此类表示协议无关的 Socket 地址。它提供了一个不可变的对象,用于 Socket 的绑定、连接或作为返回值。

父类型:

prop size

public prop size: Int64

功能:当前 SocketAddress 对象的原始字节长度。

类型:Int64

prop family

public prop family: AddressFamily

功能:当前 SocketAddress 对象的地址族。

类型:AddressFamily

func getAddressBytes()

public func getAddressBytes(): Array<Byte>

功能:返回此 SocketAddress 对象的原始IP地址。

返回值:

func hashCode()

public func hashCode(): Int64

功能:获取 hashcode 值。

返回值:

  • Int64 - hashcode 值。

func toString()

public func toString(): String

功能:返回当前 SocketAddress 的文本表示字符串。

返回值:

  • String - 当前 SocketAddress 的文本表示字符串,比如 192.168.1.2:8080[fc00::/16]:8080/tmp/socket1

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let v4: SocketAddress = IPSocketAddress.parse("192.168.1.2:8080")
    let v6: SocketAddress = IPSocketAddress.parse("[2001:0250:1006:dff0:4913:2aa5:8075:7c10]:8080")
    @Assert(v4.toString(), "192.168.1.2:8080")
    @Assert(v6.toString(), "[2001:250:1006:dff0:4913:2aa5:8075:7c10]:8080")
}

operator func ==(SocketAddress)

public operator func ==(rhs: SocketAddress): Bool

功能:判断两个 SocketAddress 对象是否相等。

参数:

返回值:

  • Bool - 如果两个 SocketAddress 对象相等,则返回 true;否则,返回 false

operator func !=(SocketAddress)

public operator func !=(rhs: SocketAddress): Bool

功能:判断两个 SocketAddress 对象是否不等。

参数:

返回值:

  • Bool - 如果两个 SocketAddress 对象不等,则返回 true;否则,返回 false

class TcpServerSocket

public class TcpServerSocket <: ServerSocket {
    public init(bindAt!: SocketAddress)
    public init(bindAt!: UInt16)
}

功能:监听 TCP 连接的服务端。

套接字被创建后,可通过属性和 setSocketOptionXX 接口配置属性。 启动监听需要调用 bind() 将套接字绑定到本地端口。accept() 接口将接受 TCP 连接,阻塞等待连接,若队列中已有连接,则可立即返回。 套接字需要通过 close 显式关闭。

父类型:

prop backlogSize

public mut prop backlogSize: Int64

功能:设置和读取 backlog 大小。

仅可在调用 bind 前调用,否则将抛出异常。 变量是否生效取决于系统行为。

类型:Int64

异常:

prop bindToDevice

public mut prop bindToDevice: ?String

功能:设置和读取绑定网卡。

类型:?String

prop localAddress

public override prop localAddress: SocketAddress

功能:读取 Socket 将要或已经被绑定的本地地址。

类型:SocketAddress

异常:

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能:设置和读取 SO_RCVBUF 属性。

类型:Int64

异常:

prop reuseAddress

public mut prop reuseAddress: Bool

功能:设置和读取 SO_REUSEADDR 属性,默认设置为 true

属性生效后的行为取决于系统,使用前,请参阅不同系统针对此属性 SO_REUSEADDR/SOCK_REUSEADDR 的说明文档。

类型:Bool

prop reusePort

public mut prop reusePort: Bool

功能:设置和读取 SO_REUSEPORT 属性。

仅可在绑定前被修改。Windows 上可使用 SO_REUSEADDR,无该属性,抛出异常。 属性默认及配置生效后的行为取决于系统,使用前,请参阅不同系统针对此属性 SO_REUSEPORT 的说明文档。 同时开启 SO_REUSEADDR/SO_REUSEPORT 会导致不可预知的系统错误,用户需谨慎配置值。

类型:Bool

异常:

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能:设置和读取 SO_SNDBUF 属性。

类型:Int64

异常:

init(SocketAddress)

public init(bindAt!: SocketAddress)

功能:创建一个 TcpServerSocket 实例,尚未绑定,因此客户端无法连接。

参数:

  • bindAt!: SocketAddress - 指定本地绑定地址,端口号设置为 0 表示随机绑定空闲的本地地址。

init(UInt16)

public init(bindAt!: UInt16)

功能:创建一个 TcpServerSocket 实例,尚未绑定,因此客户端无法连接。

参数:

  • bindAt!: UInt16 - 指定本地绑定端口,0 表示随机绑定空闲的本地端口。

func accept()

public override func accept(): TcpSocket

功能:监听或接受客户端连接。阻塞等待。

返回值:

异常:

func accept(?Duration)

public override func accept(timeout!: ?Duration): TcpSocket

功能:监听或接受客户端连接。

参数:

返回值:

异常:

func bind()

public override func bind(): Unit

功能:绑定本地端口失败后需要 close 套接字,不支持多次重试。

异常:

func close()

public override func close(): Unit

功能:关闭套接字。接口允许多次调用。

func getSocketOption(Int32, Int32, CPointer<Unit>, CPointer<UIntNative>)

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能:获取指定的套接字参数。

参数:

异常:

func getSocketOptionBool(Int32, Int32)

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能:获取指定的套接字参数。从 IntNative 强转而来。0 => false,非 0 => true

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

  • Bool - 指定的套接字参数。从 IntNative 强转而来。0 => false,非 0 => true

异常:

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能:获取指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

异常:

func isClosed()

public override func isClosed(): Bool

功能:检查套接字是否关闭。

返回值:

  • Bool - 如果已经关闭,返回 true,否则返回 false

func setSocketOption(Int32, Int32, CPointer<Unit>, UIntNative)

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: CPointer<Unit> - 参数值。
  • valueLength: UIntNative - 参数值长度。

异常:

func setSocketOptionBool(Int32, Int32,Bool)

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: Bool - 参数值。

异常:

func setSocketOptionIntNative(Int32, Int32, IntNative)

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: IntNative - 参数值。

异常:

func toString()

public override func toString(): String

功能:返回当前 TcpServerSocket 的状态信息。

返回值:

class TcpSocket

public class TcpSocket <: StreamingSocket & Equatable<TcpSocket> & Hashable {
    public init(address: String, port: UInt16)
    public init(address: SocketAddress)
    public init(address: SocketAddress, localAddress!: ?SocketAddress)
}

功能:请求 TCP 连接的客户端。

当实例对象被创建后,可使用 connect 函数创建连接,并在结束时显式执行 close 操作。 该类型继承自 StreamingSocket, 可参阅 StreamingSocket 章节获取更多信息。

父类型:

prop bindToDevice

public mut prop bindToDevice: ?String

功能:设置和读取绑定网卡。

类型:?String

prop keepAlive

public mut prop keepAlive: ?SocketKeepAliveConfig

功能:设置和读取保活属性,None 表示关闭保活。

用户未设置时将使用系统默认配置。设置此配置可能会被延迟或被系统忽略,取决于系统的处理能力。

类型:?SocketKeepAliveConfig

prop linger

public mut prop linger: ?Duration

功能:设置和读取 SO_LINGER 属性,默认值取决于系统,None 表示禁用此选项。

说明:

  • 如果 SO_LINGER 被设置为 Some(v),当套接字关闭时,如果还有等待的字节流,我们将在关闭连接前等待 v 时间,如果超过时间,字节流还未被发送,连接将会被异常终止(通过 RST 报文关闭)。
  • 如果 SO_LINGER 被设置为 None,当套接字关闭时,连接将被立即关闭,如果当前等待发送的字符,使用 FIN-ACK 关闭连接,当还有剩余待发送的字符时,使用 RST 关闭连接。

类型:?Duration

异常:

prop localAddress

public override prop localAddress: SocketAddress

功能:读取 Socket 将要或已经被绑定的本地地址。

类型:SocketAddress

异常:

  • SocketException - 当 Socket 已经被关闭或无可用的本地地址(本地地址未配置并且套接字未连接)时,抛出异常。

prop noDelay

public mut prop noDelay: Bool

功能:设置和读取 TCP_NODELAY 属性,默认为 true

这个选项将禁用 Nagel 算法,所有写入字节被无延迟得转发。当属性设置为 false 时,Nagel 算法将在发包前引入延时时间。

类型:Bool

prop quickAcknowledge

public mut prop quickAcknowledge: Bool

功能:设置和读取 TCP_QUICKACK 属性,默认为 false

这个选项类似于 noDelay,但仅影响 TCP ACK 和第一次响应。不支持 Windows 和 macOS 系统。

类型:Bool

prop readTimeout

public override mut prop readTimeout: ?Duration

功能:设置和读取读操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值;过大时将设置为最大超时时间(263-1 纳秒);默认值为 None

类型:?Duration

异常:

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能:设置和读取 SO_RCVBUF 属性,提供一种方式指定收包缓存大小。选项的生效情况取决于系统。

类型:Int64

异常:

prop remoteAddress

public override prop remoteAddress: SocketAddress

功能:读取 Socket 已经或将要连接的远端地址。

类型:SocketAddress

异常:

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能:设置和读取 SO_SNDBUF 属性,提供一种方式指定发包缓存大小。选项的生效情况取决于系统。

类型:Int64

异常:

prop writeTimeout

public override mut prop writeTimeout: ?Duration

功能:设置和读取写操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值;过大时将设置为最大超时时间(263-1 纳秒);默认值为 None

类型:?Duration

异常:

init(SocketAddress)

public init(address: SocketAddress)

功能:创建一个未连接的套接字。

参数:

异常:

  • SocketException - 当 address 参数不合法或者 Windows 平台下地址为全零地址时,抛出异常。

init(SocketAddress, ?SocketAddress)

public init(address: SocketAddress, localAddress!: ?SocketAddress)

功能:创建一个未连接的套接字,并且绑定到指定本地地址,本地地址为 None 时,将随机选定地址去绑定。

此接口当 localAddress 不为 None 时,将默认设置 SO_REUSEADDRtrue,否则可能导致 "address already in use" 的错误。如果需要变更此配置,可以通过调用 setSocketOptionBool(SocketOptions.SOL_SOCKET, SocketOptions.SO_REUSEADDR, false)。另外,本地地址和远端地址需要均为 IPv4。

参数:

异常:

  • SocketException - 当 address 参数不合法或者 Windows 平台下地址为全零地址时,抛出异常。

init(String, UInt16)

public init(address: String, port: UInt16)

功能:创建一个未连接的套接字。

参数:

  • address: String - 即将要连接的地址。
  • port: UInt16 - 即将要连接的端口。

异常:

  • SocketException - 当 address 参数不合法或者 Windows 平台下地址为全零地址时,抛出异常。

func close()

public func close(): Unit

功能:关闭套接字,所有操作除了 close/isClosed 之外,均不允许再调用。接口允许多次调用。

func connect(?Duration)

public func connect(timeout!: ?Duration = None): Unit

功能:连接远端套接字,会自动绑定本地地址,因此不需要进行额外的绑定操作。

参数:

  • timeout!: ?Duration - 连接超时时间,None 表示无超时时间,并且连接操作无重试,当服务端拒绝连接时,将返回连接失败。并且此操作包含了绑定操作,因此无需重复调用 bind 接口。

异常:

  • IllegalArgumentException - 当远端地址不合法或者连接超时时间小于 0 或者超时时间小于 0 时,抛出异常。
  • SocketException - 当连接因系统原因(例如:套接字已关闭,没有访问权限,系统错误等)无法建立时,抛出异常。再次调用可能成功。
  • SocketTimeoutException - 当连接超时时,抛出异常。

func getSocketOption(Int32, Int32, CPointer<Unit>, CPointer<UIntNative>)

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能:读取指定的套接字参数。

参数:

异常:

func getSocketOptionBool(Int32, Int32)

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能:读取指定的套接字参数。从 IntNative 强转而来。0 => false,非 0 => true

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

  • Bool - 读取到的参数值。

异常:

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能:读取指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

异常:

func hashCode()

public override func hashCode(): Int64

功能:获取当前 TcpSocket 实例的哈希值。

返回值:

func isClosed()

public func isClosed(): Bool

功能:判断套接字是否通过调用 close 显式关闭。

返回值:

  • Bool - 套接字是否已经调用 close 显式关闭。是则返回 true;否则返回 false

func read(Array<Byte>)

public override func read(buffer: Array<Byte>): Int64

功能:读取报文。超时情况按 readTimeout 决定,详见 readTimeout

说明:

  • 由于系统底层接口差异,如果连接被对端关闭,readwrite 接口的行为也有相应的差异。
  • Windows 系统上,对端关闭连接后,如果本端调用一次 write,会导致清空缓冲区内容,在此基础上再调用 read 会抛出连接关闭异常。
  • Linux/macOS 系统上,对端关闭连接后,先调用 write 再调用 read 函数仍会读出缓冲区中的内容。

参数:

  • buffer: Array<Byte> - 存储读出数据的缓冲区。

返回值:

  • Int64 - 读取的数据长度。

异常:

  • SocketException - 当 buffer 大小为 0 或者因系统原因读取失败时,抛出异常。

func setSocketOption(Int32, Int32, CPointer<Unit>, UIntNative)

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: CPointer<Unit> - 参数值。
  • valueLength: UIntNative - 参数值长度。

异常:

func setSocketOptionBool(Int32, Int32, Bool)

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: Bool - 参数值。

异常:

func setSocketOptionIntNative(Int32, Int32, IntNative)

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: IntNative - 参数值。

异常:

func toString()

public override func toString(): String

功能:返回当前 TcpSocket 的状态信息。

返回值:

func write(Array<Byte>)

public override func write(payload: Array<Byte>): Unit

功能:写入报文。超时情况按 writeTimeout 决定,详见 writeTimeout

参数:

  • payload: Array<Byte> - 存储写入数据的缓冲区。

异常:

  • SocketException - 当 buffer 大小为 0 或者当因系统原因写入失败时,抛出异常。

operator func !=(TcpSocket)

public override operator func !=(other: TcpSocket): Bool

功能:判断两个 TcpSocket 实例是否不等。

参数:

返回值:

  • Bool - 如果两个 TcpSocket 实例不等,则返回 true;否则,返回 false

operator func ==(TcpSocket)

public override operator func ==(other: TcpSocket): Bool

功能:判断两个 TcpSocket 实例是否相等。

参数:

返回值:

  • Bool - 如果两个 TcpSocket 实例相等,则返回 true;否则,返回 false

class UdpSocket

public class UdpSocket <: DatagramSocket {
    public init(bindAt!: SocketAddress)
    public init(bindAt!: UInt16)
}

功能:提供 udp 报文通信。

UDPSocket 创建实例后,需要调用 bind() 绑定,可在不与远端建连的前提下接受报文。不过,UDPSocket 也可以通过 connect()/disconnect() 接口进行建连。 UDP 协议要求传输报文大小不可超过 64KB 。 UDPSocket 需要被显式 close() 。可以参阅 DatagramSocket 获取更多信息。

父类型:

prop localAddress

public override prop localAddress: SocketAddress

功能:读取 Socket 将要或已经被绑定的本地地址。

类型:SocketAddress

异常:

  • SocketException - 当 Socket 已经被关闭或无可用的本地地址(本地地址未配置并且套接字未连接)时,抛出异常。

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能:设置和读取 SO_RCVBUF 属性。

类型:Int64

异常:

prop receiveTimeout

public override mut prop receiveTimeout: ?Duration

功能:设置和读取 receive/receiveFrom 操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值;过大时将设置为最大超时时间(263-1 纳秒);默认值为 None

类型:?Duration

异常:

prop remoteAddress

public override prop remoteAddress: ?SocketAddress

功能:读取 Socket 已经连接的远端地址,当 Socket 未连接时返回 None

类型:?SocketAddress

异常:

prop reuseAddress

public mut prop reuseAddress: Bool

功能:设置和读取 SO_REUSEADDR 属性。

属性默认以及生效后的行为取决于系统,使用前,请参阅不同系统针对此属性 SO_REUSEADDR/SOCK_REUSEADDR 的说明文档。

类型:Bool

prop reusePort

public mut prop reusePort: Bool

功能:设置和读取 SO_REUSEPORT 属性。

Windows 上可使用 SO_REUSEADDR,但无 SO_REUSEPORT 属性,因此会抛出异常。 属性默认以及配置生效后的行为取决于系统,使用前,请参阅不同系统针对此属性 SO_REUSEPORT 的说明文档。

类型:Bool

异常:

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能:设置和读取 SO_SNDBUF 属性。

类型:Int64

异常:

prop sendTimeout

public override mut prop sendTimeout: ?Duration

功能:设置和读取 send/sendTo 操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值;过大时将设置为最大超时时间(263-1 纳秒);默认值为 None

类型:?Duration

init(SocketAddress)

public init(bindAt!: SocketAddress)

功能:创建一个未绑定的 UDPSocket 实例。

参数:

异常:

init(UInt64)

public init(bindAt!: UInt16)

功能:创建一个未绑定的 UDPSocket 实例。

参数:

  • bindAt!: UInt16 - 绑定端口。

func bind()

public func bind(): Unit

功能:绑定本地端口失败后需要 close 套接字,不支持多次重试。

异常:

func close()

public override func close(): Unit

功能:关闭套接字,所有操作除了 close/isClosed 之外,均不允许再调用。接口允许多次调用。

func connect(SocketAddress)

public func connect(remote: SocketAddress): Unit

功能:连接特定远端地址,可通过 disconnect 撤销配置。

仅接受该远端地址的报文。必须在调用 bind 后执行。此操作执行后,端口将开始接收 ICMP 报文,若收到异常报文后,可能导致 send/sendTo 执行失败。

参数:

异常:

  • IllegalArgumentException - 当远端地址不合法时,抛出异常。
  • SocketException - 当端口未绑定、连接因系统原因无法建立或者 Windows 平台下远端地址为全零地址时,抛出异常。

func disconnect()

public func disconnect(): Unit

功能:停止连接。取消仅收取特定对端报文。可在 connect 前调用,可多次调用。

func getSocketOption(Int32, Int32, CPointer<Unit>, CPointer<UIntNative>)

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能:获取指定的套接字参数。

参数:

异常:

func getSocketOptionBool(Int32, Int32)

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能:获取指定的套接字参数。从 IntNative 强转而来。0 => false,非 0 => true

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

  • Bool - 指定的套接字参数。从 IntNative 强转而来。0 => false,非 0 => true

异常:

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能:获取指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

异常:

func isClosed()

public override func isClosed(): Bool

功能:判断套接字是否通过调用 close 显式关闭。

返回值:

  • Bool - 如果该套接字已调用 close 显示关闭,则返回 true;否则,返回 false

func receive(Array<Byte>)

public func receive(buffer: Array<Byte>): Int64

功能:从 connect 连接到的地址收取报文。

参数:

  • buffer: Array<Byte> - 存储收取到的报文的地址

返回值:

  • Int64 - 收取到的报文大小。

func receiveFrom(Array<Byte>)

public override func receiveFrom(buffer: Array<Byte>): (SocketAddress, Int64)

功能:接收报文。

参数:

  • buffer: Array<Byte> - 存储收取到报文的缓存地址

返回值:

  • (SocketAddress, Int64) - 收取到的报文的发送端地址,及实际收取到的报文大小,可能为 0 或者大于参数 buffer 的大小。

异常:

func send(Array<Byte>)

public func send(payload: Array<Byte>): Unit

功能:发送报文到 connect 连接到的地址。

参数:

  • payload: Array<Byte> - 发送报文内容。

异常:

  • SocketException - 当 payload 的大小超出系统限制或者系统发送失败(例如:当 connect 被调用,并且收到异常 ICMP 报文时,发送失败)时,抛出异常。

func sendTo(SocketAddress, Array<Byte>)

public override func sendTo(recipient: SocketAddress, payload: Array<Byte>): Unit

功能:发送报文。当没有足够的缓存地址时可能会被阻塞。

参数:

异常:

  • SocketException - 当 payload 的大小超出系统限制、系统发送失败(例如:当 connect 被调用,并且收到异常 ICMP 报文时,发送失败)、Windows 平台下远端地址为全零地址或者 macOS 平台下 connect 被调用后调用 sendTo 时,抛出异常。

func setSocketOption(Int32, Int32, CPointer<Unit>, UIntNative)

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: CPointer<Unit> - 参数值。
  • valueLength: UIntNative - 参数值长度。

异常:

func setSocketOptionBool(Int32, Int32, Bool)

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: Bool - 参数值。

异常:

func setSocketOptionIntNative(Int32, Int32, IntNative)

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: IntNative - 参数值。

异常:

func toString()

public override func toString(): String

功能:返回当前 UdpSocket 的状态信息。

返回值:

class UnixDatagramSocket

public class UnixDatagramSocket <: DatagramSocket {
    public init(bindAt!: SocketAddress)
    public init(bindAt!: String)
}

功能:提供基于数据包的主机通讯能力。

UnixDatagramSocket 实例创建后,应当显式调用 bind() 接口绑定。Unix 数据包套接字不需要连接,不需要与远端握手多次。不过用户也可以通过 connect/disconnect 接口与远端建连和断连。 不同于 UDP,UDS 没有数据包大小限制,限制来源于操作系统和接口实现。 套接字资源需要用 close 接口显式回收。可参阅 DatagramSocket 获取更多信息。

注意:

  • 该类型不支持在 Windows 平台上运行。

父类型:

prop localAddress

public override prop localAddress: SocketAddress

功能:读取 socket 将要或已经绑定的本地地址。

类型:SocketAddress

异常:

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能:设置和读取 SO_RCVBUF 属性,提供一种方式指定发包缓存大小。选项的生效情况取决于系统。

类型:Int64

异常:

prop receiveTimeout

public override mut prop receiveTimeout: ?Duration

功能:设置和读取 receive/receiveFrom 操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值;过大时将设置为最大超时时间(263-1 纳秒);默认值为 None

类型:?Duration

异常:

prop remoteAddress

public override prop remoteAddress: ?SocketAddress

功能:读取 Socket 已经连接的远端地址,当 Socket 未连接时返回 None

类型:?SocketAddress

异常:

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能:设置和读取 SO_SNDBUF 属性,提供一种方式指定发包缓存大小。选项的生效情况取决于系统。

类型:Int64

异常:

prop sendTimeout

public override mut prop sendTimeout: ?Duration

功能:设置和读取 send/sendTo 操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值;过大时将设置为最大超时时间(263-1 纳秒);默认值为 None

类型:?Duration

异常:

init(SocketAddress)

public init(bindAt!: SocketAddress)

功能:创建一个未连接的 UnixDatagramSocket 实例。

此文件类型可通过 isSock() 判断是否存在,可通过 unlink() 接口删除。

参数:

  • bindAt!: SocketAddress - 连接的套接字地址。地址应当不存在,在 bind 时会创建。

异常:

init(String)

public init(bindAt!: String)

功能:创建一个未连接的 UnixDatagramSocket 实例。

此文件类型可通过 isSock() 判断是否存在,可通过 unlink() 接口删除。

参数:

  • bindAt!: String - 连接的文件地址。文件地址应当不存在,在 bind 时会创建。

异常:

func bind()

public func bind(): Unit

功能:绑定一个 Unix datagram 套接字,并创建监听队列。

此接口自动在本地地址中创建一个套接字文件,如该文件已存在则会绑定失败。此文件类型可通过 isSock 判断是否存在,可通过 unlink() 接口删除,失败后需要 close 套接字,不支持多次重试。

异常:

  • SocketException - 当文件地址已存在,或文件创建失败时,抛出异常。

func close()

public override func close(): Unit

功能:关闭套接字,所有操作除了 close/isClosed 之外,均不允许再调用。接口允许多次调用。

func connect(SocketAddress)

public func connect(remote: SocketAddress): Unit

功能:连接特定远端地址,可通过 disconnect 撤销配置。

仅接受该远端地址的报文。默认执行 bind,因此不需额外调用 bind。此操作执行后,端口将开始接收 ICMP 报文,若收到异常报文后,可能导致 send/sendTo 执行失败。

参数:

异常:

func connect(String)

public func connect(remotePath: String): Unit

功能:连接特定远端地址,可通过 disconnect 撤销配置。

仅接受该远端地址的报文。必须在 bind 后调用。此操作执行后,端口将开始接收 ICMP 报文,若收到异常报文后,可能导致 send/sendTo 执行失败。

参数:

  • remotePath: String - 远端文件地址。

异常:

func disconnect()

public func disconnect(): Unit

功能:停止连接。取消仅收取特定对端报文。可在 connect 前调用,可多次调用。

异常:

func getSocketOption(Int32, Int32, CPointer<Unit>, CPointer<UIntNative>)

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能:获取指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: CPointer<Unit> - 参数值。
  • valueLength: CPointer<UIntNative> - 参数值长度。

异常:

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能:获取指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

  • IntNative - 返回指定的套接字参数值。

异常:

func isClosed()

public override func isClosed(): Bool

功能:判断套接字是否通过调用 close 显式关闭。

返回值:

  • Bool - 返回套接字是否已经通过调用 close 显式关闭。是则返回 true;否则,返回 false

func receive(Array<Byte>)

public func receive(buffer: Array<Byte>): Int64

功能:从 connect 连接到的地址收取报文。

参数:

  • buffer: Array<Byte> - 存储收取到的报文的地址。

返回值:

  • Int64 - 收取到的报文大小。

func receiveFrom(Array<Byte>)

public override func receiveFrom(buffer: Array<Byte>): (SocketAddress, Int64)

功能:收取报文。

参数:

  • buffer: Array<Byte> - 存储收取到报文的地址。

返回值:

  • (SocketAddress, Int64) - 收取到的报文的发送端地址,及实际收取到的报文大小,可能为 0 或者大于参数 buffer 的大小。

异常:

func send(Array<Byte>)

public func send(payload: Array<Byte>): Unit

功能:发送报文到 connect 连接到的地址。

参数:

  • payload: Array<Byte> - 发送报文内容。

异常:

  • SocketException - 当 payload 的大小超出系统限制或者系统发送失败时,抛出异常。

func sendTo(SocketAddress, Array<Byte>)

public override func sendTo(recipient: SocketAddress, payload: Array<Byte>): Unit

功能:发送报文。当没有足够的缓存地址时可能会被阻塞。

参数:

异常:

  • SocketException - 当 payload 的大小超出系统限制、系统发送失败(例如:当 connect 被调用,并且收到异常 ICMP 报文时,发送将失败)或者 macOS 平台下 connect 被调用后调用 sendTo 时,抛出异常。

func setSocketOption(Int32, Int32, CPointer<Unit>, UIntNative)

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: CPointer<Unit> - 参数值。
  • valueLength: UIntNative - 参数值长度。

异常:

func setSocketOptionBool(Int32, Int32, Bool)

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: Bool - 参数值。

异常:

func setSocketOptionIntNative(Int32, Int32,IntNative)

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: IntNative - 参数值。

异常:

func getSocketOptionBool(Int32, Int32)

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能:获取指定的套接字参数。从 IntNative 强转而来。0 => false,非 0 => true

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

  • Bool - 返回指定的套接字参数值。从 IntNative 强转而来。0 => false,非 0 => true

异常:

func toString()

public override func toString(): String

功能:返回当前 UDS 的状态信息。

返回值:

  • String - 包含当前 UDS 状态信息的字符串。

class UnixServerSocket

public class UnixServerSocket <: ServerSocket

功能:提供基于双工流的主机通讯服务端。

UnixServerSocket 监听连接,创建后可以通过属性和 setSocketOptionXX 接口配置属性值。需要调用 bind() 接口绑定本地地址开始监听连接。可以通过 accept() 接口接受连接。

注意:

  • 该类型不支持在 Windows 平台上运行。

父类型:

prop backlogSize

public mut prop backlogSize: Int64

功能:设置和读取 backlog 大小。仅可在调用 bind 前调用,否则将抛出异常。 变量是否生效取决于系统行为。

类型:Int64

异常:

prop localAddress

public override prop localAddress: SocketAddress

功能:读取 Socket 将要或已经被绑定的本地地址。

类型:SocketAddress

异常:

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能:设置和读取 SO_RCVBUF 属性。

类型:Int64

异常:

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能:设置和读取 SO_SNDBUF 属性。

类型:Int64

异常:

init(SocketAddress)

public init(bindAt!: SocketAddress)

功能:创建一个未连接的 UnixServerSocket 实例。

参数:

init(String)

public init(bindAt!: String)

功能:创建一个未连接的 UnixServerSocket 实例。

此文件类型可通过 isSock 判断是否存在,可通过 unlink() 接口删除。

参数:

  • bindAt!: String - 连接的文件地址。

异常:

func accept()

public override func accept(): UnixSocket

功能:等待接受一个客户端的连接,或从队列中读取连接。

返回值:

func accept(?Duration)

public override func accept(timeout!: ?Duration): UnixSocket

功能:等待接受一个客户端的连接,或从队列中读取连接。

参数:

返回值:

异常:

func bind()

public override func bind(): Unit

功能:绑定一个 Unix domain 套接字,并创建监听队列。

此接口自动在本地地址中创建一个套接字文件,如该文件已存在则会绑定失败。此文件类型可通过 isSock 接口判断是否存在,可通过 unlink() 接口删除,失败后需要 close 套接字,不支持多次重试。

异常:

func close()

public override func close(): Unit

功能:关闭套接字,该套接字的所有操作除了 close/isClosed 之外,均不允许再调用。此接口允许多次调用。

func getSocketOption(Int32, Int32, CPointer<Unit>, CPointer<UIntNative>)

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能:获取指定的套接字参数。

参数:

异常:

func getSocketOptionBool(Int32, Int32)

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能:获取指定的套接字参数。从 IntNative 强转而来。0 => false,非 0 => true

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

  • Bool - 返回指定的套接字参数。从 IntNative 强转而来。0 => false,非 0 => true

异常:

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能:获取返回值为整型的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

异常:

func isClosed()

public override func isClosed(): Bool

功能:判断套接字是否通过调用 close 显式关闭。

func setSocketOption(Int32, Int32, CPointer<Unit>, UIntNative)

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能:设置返回值为整型的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: CPointer<Unit> - 参数值。
  • valueLength: UIntNative - 参数值长度。

异常:

func setSocketOptionBool(Int32, Int32, Bool)

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: Bool - 参数值。

异常:

func setSocketOptionIntNative(Int32, Int32, IntNative)

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: IntNative - 参数值。

异常:

func toString()

public override func toString(): String

功能:返回当前 UnixServerSocket 的状态信息。

返回值:

class UnixSocket

public class UnixSocket <: StreamingSocket {
    public init(address: SocketAddress)
    public init(path: String)
}

功能:提供基于双工流的主机通讯客户端。

UnixSocket 实例创建后应调用 connect() 接口创建连接,并且在结束时显式调用 close() 回收资源。可参阅 StreamingSocket 获取更多信息。

注意:

  • 该类型不支持在 Windows 平台上运行。

父类型:

prop localAddress

public override prop localAddress: SocketAddress

功能:读取 Socket 将要或已经被绑定的本地地址。

类型:SocketAddress

异常:

  • SocketException - 当 Socket 已经被关闭或无可用的本地地址(本地地址未配置并且套接字未连接)时,抛出异常。

prop readTimeout

public override mut prop readTimeout: ?Duration

功能:设置和读取读操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值,过大时将设置为None,默认值为 None

类型:?Duration

异常:

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能:设置和读取 SO_RCVBUF 属性。

类型:Int64

异常:

prop remoteAddress

public override prop remoteAddress: SocketAddress

功能:读取 Socket 已经或将要连接的远端地址。

类型:SocketAddress

异常:

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能:设置和读取 SO_SNDBUF 属性。

类型:Int64

异常:

prop writeTimeout

public override mut prop writeTimeout: ?Duration

功能:设置和读取写操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值;过大时将设置为最大超时时间(263-1 纳秒);默认值为 None

类型:?Duration

异常:

init(SocketAddress)

public init(address: SocketAddress)

功能:创建一个未连接的 UnixSocket 实例。

参数:

init(String)

public init(path: String)

功能:创建一个未连接的 UnixSocket 实例。

此文件类型可通过 isSock 判断是否存在,可通过 unlink() 接口删除。

参数:

  • path: String - 连接的文件地址。

异常:

func close()

public func close(): Unit

功能:关闭套接字,所有操作除了 close/isClosed 之外,均不允许再调用。接口允许多次调用。

func connect(?Duration)

public func connect(timeout!: ?Duration = None): Unit

功能:建立远端连接,对端拒绝时连接失败,会自动绑定本地地址,因此不需要进行额外的绑定操作。

参数:

  • timeout!: ?Duration - 超时时间,None 表示无超时时间。Unix 与 Tcp 不同,队列已满时,调用立即返回错误,而非重试阻塞等待。

异常:

func getSocketOption(Int32, Int32, CPointer<Unit>, CPointer<UIntNative>)

public func getSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: CPointer<UIntNative>
): Unit

功能:获取指定的套接字参数。

参数:

异常:

func getSocketOptionBool(Int32, Int32)

public func getSocketOptionBool(
    level: Int32,
    option: Int32
): Bool

功能:获取指定的套接字参数。从 IntNative 强转而来。0 => false,非 0 => true

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

  • Bool - 返回指定的套接字参数值。从 IntNative 强转而来。0 => false,非 0 => true

异常:

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能:获取指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE

返回值:

异常:

func isClosed()

public func isClosed(): Bool

功能:判断套接字是否通过调用 close 显式关闭。

返回值:

  • Bool - 返回套接字是否已经调用 close 显示关闭。是则返回 true;否则,返回 false

func read(Array<Byte>)

public override func read(buffer: Array<Byte>): Int64

功能:读取报文。超时情况按 readTimeout 决定,详见 readTimeout

参数:

  • buffer: Array<Byte> - 读取的数据存储变量。

返回值:

  • Int64 - 读取的数据长度。

异常:

  • SocketException - 当 buffer 大小为 0 或者因系统原因读取失败时,抛出异常。

func setSocketOption(Int32, Int32, CPointer<Unit>, UIntNative)

public func setSocketOption(
    level: Int32,
    option: Int32,
    value: CPointer<Unit>,
    valueLength: UIntNative
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: CPointer<Unit> - 参数值。
  • valueLength: UIntNative - 参数值长度。

异常:

func setSocketOptionBool(Int32, Int32, Bool)

public func setSocketOptionBool(
    level: Int32,
    option: Int32,
    value: Bool
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: Bool - 参数值。

异常:

func setSocketOptionIntNative(Int32, Int32, IntNative)

public func setSocketOptionIntNative(
    level: Int32,
    option: Int32,
    value: IntNative
): Unit

功能:设置指定的套接字参数。

参数:

  • level: Int32 - 层级,例如 SOL_SOCKET
  • option: Int32 - 参数,例如 SO_KEEPALIVE
  • value: IntNative - 参数值。

异常:

func toString()

public override func toString(): String

功能:返回当前 UnixSocket 的状态信息。

返回值:

func write(Array<Byte>)

public override func write(buffer: Array<Byte>): Unit

功能:读取写入。超时情况按 writeTimeout 决定,详见 writeTimeout

参数:

  • buffer: Array<Byte> - 写入的数据存储变量

异常:

  • SocketException - 当 buffer 大小为 0 时抛出异常,当因系统原因写入失败时,抛出异常。

class UnixSocketAddress

public class UnixSocketAddress <: SocketAddress & Equatable<UnixSocketAddress>

功能:此类实现了 Unix Domain Socket 地址,Unix Domain Socket 地址封装了Unix Domain Socket 绑定或连接到的文件系统路径,路径长度不可超过 108。

如果路径是空字符串,那么表示它是 unnamed 地址,如果路径以\0 开头,那么它是 abstract 地址。路径中间不可包含 \0

父类型:

prop family

public prop family: AddressFamily

功能:获取当前 UnixSocketAddress 对象的地址族,总是 AddressFamily.UNIX

类型:AddressFamily

prop size

public prop size: Int64

功能:获取当前 UnixSocketAddress 对象的原始字节长度。

类型:Int64

init(Array<Byte>)

public init(address: Array<Byte>)

功能:根据 Array<Byte> 表示的文件系统路径构造 UnixSocketAddress 地址。

参数:

  • address: Array<Byte> - 文件系统路径字节数组。

异常:

init(String)

public init(address: String)

功能:根据字符串表示的文件系统路径构造 UnixSocketAddress 地址。

参数:

  • address: String - 文件系统路径字符串。

异常:

func getAddressBytes()

public func getAddressBytes(): Array<Byte>

功能:返回此 UnixSocketAddress 对象的原始IP地址,内容布局与 sockaddr_un 形式一致。

返回值:

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let udsa1_1: UnixSocketAddress = UnixSocketAddress("/tmp/server1.sock")    
    @Assert(udsa1_1.getAddressBytes(), "\u{1}\u{0}/tmp/server1.sock".toArray())
}

func hashCode()

public func hashCode(): Int64

功能:获取 hashcode 值。

返回值:

  • Int64 - hashcode 值。

func toString()

public func toString(): String

功能:返回当前 UnixSocketAddress 的文本表示字符串。

返回值:

示例:

import std.net.*
import std.unittest.*
import std.unittest.testmacro.*

main () {
    let expect1 = "/tmp/server1.sock"
    let expect2 = "\u{0}/tmp/server1.sock"
    let udsa1_1: UnixSocketAddress = UnixSocketAddress("/tmp/server1.sock")
    let udsa2_1: UnixSocketAddress = UnixSocketAddress("/tmp/server1.sock".toArray())
    let udsa2_2: UnixSocketAddress = UnixSocketAddress("/tmp/server1.sock\u{0}\u{0}".toArray())
    let udsa3_1: UnixSocketAddress = UnixSocketAddress("\u{0}/tmp/server1.sock")
    let udsa4_1: UnixSocketAddress = UnixSocketAddress("\u{0}/tmp/server1.sock".toArray())
    let udsa4_2: UnixSocketAddress = UnixSocketAddress("\u{0}/tmp/server1.sock\u{0}\u{0}".toArray())
    @Assert(udsa1_1.toString(), expect1)
    @Assert(udsa2_1.toString(), expect1)
    @Assert(udsa2_2.toString(), expect1)
    @Assert(udsa3_1.toString(), expect2)
    @Assert(udsa1_1, udsa2_1)
    @Assert(udsa1_1, udsa2_2)
    @Assert(udsa3_1, udsa4_1)
    @Assert(udsa3_1, udsa4_2)
    @Assert(udsa4_1.toString(), expect2)
    @Assert(udsa4_2.toString(), expect2)

    try {
        UnixSocketAddress("/tmp/server1\u{0}.sock")
    } catch (e: IllegalArgumentException) {
        @Assert(true)
    }

    try {
        UnixSocketAddress("/tmp/server1.sock\u{0}\u{0}")
    } catch (e: IllegalArgumentException) {
        @Assert(true)
    }
    try {
        UnixSocketAddress("\u{0}/tmp/server1.sock\u{0}\u{0}")
    } catch (e: IllegalArgumentException) {
        @Assert(true)
    }
    try {
        UnixSocketAddress("/tmp/server1\u{0}.sock".toArray())
    } catch (e: IllegalArgumentException) {
        @Assert(true)
    }
    return
}

operator func ==(UnixSocketAddress)

public operator func ==(rhs: UnixSocketAddress): Bool

功能:判断两个 UnixSocketAddress 对象是否相等。

参数:

返回值:

operator func !=(UnixSocketAddress)

public operator func !=(rhs: UnixSocketAddress): Bool

功能:判断两个 UnixSocketAddress 对象是否不等。

参数:

返回值:

枚举

enum SocketNet

public enum SocketNet <: ToString & Equatable<SocketNet> {
    | TCP
    | UDP
    | UNIX
}

功能:传输层协议类型。

父类型:

TCP

TCP

功能:代表 TCP 协议。

UDP

UDP

功能:代表 UDP 协议。

UNIX

UNIX

功能:代表 UNIX 协议。

func toString()

public func toString(): String

功能:将枚举值转换为字符串。

返回值:

  • String - 转换后的字符串。

operator func !=(SocketNet)

public operator func !=(that: SocketNet): Bool

功能:判断两个 SocketNet 是否不相等。

参数:

返回值:

  • Bool - 如果不相等,则返回 true;否则,返回 false

operator func ==(SocketNet)

public operator func ==(that: SocketNet): Bool

功能:判断两个 SocketNet 是否相等。

参数:

返回值:

  • Bool - 如果相等,则返回 true;否则,返回 false

结构体

struct AddressFamily

public struct AddressFamily <: ToString & Equatable<AddressFamily> {
    public static const INET: AddressFamily
    public static const INET6: AddressFamily
    public static const NETLINK: AddressFamily
    public static const UNIX: AddressFamily
    public static const UNSPEC: AddressFamily
    public let name: String
    public let value: Int32
}

功能:AddressFamily 地址族用于指示 Socket 的寻址方案,常用的有 INET / INET6 / UNIX 地址族。地址族标识符最初在 RFC 2453 中定义。

父类型:

static const INET

public static const INET: AddressFamily

功能:IPv4 地址族。

类型:AddressFamily

static const INET6

public static const INET6: AddressFamily

功能:IPv6 地址族。

类型:AddressFamily

public static const NETLINK: AddressFamily

功能:NetLink 地址族,仅 Linux 下支持。

类型:AddressFamily

static const UNIX

public static const UNIX: AddressFamily

功能:unix domain socket 地址族。

类型:AddressFamily

static const UNSPEC

public static const UNSPEC: AddressFamily

功能:未指定的地址族。

类型:AddressFamily

let name: String

public let name: String

功能:地址族名。

类型:String

let value: Int32

public let value: Int32

功能:地址族值。

类型:Int32

const init(String, Int32)

public const init(name: String, value: Int32)

功能:常量构造函数,创建 AddressFamily 对象。

参数:

  • name: String - 地址族名。
  • value: Int32 - 地址族值。

func toString()

public func toString(): String

功能:获取地址族对应的名称。

返回值:

  • String - 当前地址族的名称。

operator func ==(AddressFamily)

public operator func ==(rhs: AddressFamily): Bool

功能:比较地址族值是否相等。

参数:

返回值:

  • Bool - 如果两个 AddressFamily 对象相等,则返回 true;否则,返回 false

operator func !=(AddressFamily)

public operator func !=(rhs: AddressFamily): Bool

功能:比较地址族值是否不等。

参数:

返回值:

  • Bool - 如果两个 AddressFamily 对象不等,则返回 true;否则,返回 false

struct OptionLevel

public struct OptionLevel {
    public static const ICMP: Int32
    public static const IP: Int32
    public static const RAW: Int32
    public static const SOCKET: Int32
    public static const TCP: Int32
    public static const UDP: Int32
}

功能:提供了常用的套接字选项级别。

static const ICMP

public static const ICMP: Int32

功能:控制 ICMP 协议行为的套接字选项级别。

类型:Int32

static const IP

public static const IP: Int32

功能:控制 IP 协议行为的套接字选项级别。

类型:Int32

static const RAW

public static const RAW: Int32

功能:控制 RAW 协议行为的套接字选项级别。

类型:Int32

static const SOCKET

public static const SOCKET: Int32

功能:控制基本套接字行为的套接字选项级别。

类型:Int32

static const TCP

public static const TCP: Int32

功能:控制 TCP 协议行为的套接字选项级别。

类型:Int32

static const UDP

public static const UDP: Int32

功能:控制 UDP 协议行为的套接字选项级别。

类型:Int32

struct OptionName

public struct OptionName {
    public static const IP_HDRINCL: Int32
    public static const IP_TOS: Int32
    public static const IP_TTL: Int32
    public static const SO_ACCEPTCONN: Int32
    public static const SO_BROADCAST: Int32
    public static const SO_DEBUG: Int32
    public static const SO_DONTROUTE: Int32
    public static const SO_ERROR: Int32
    public static const SO_KEEPALIVE: Int32
    public static const SO_LINGER: Int32
    public static const SO_OOBINLINE: Int32
    public static const SO_RCVBUF: Int32
    public static const SO_RCVTIMEO: Int32
    public static const SO_REUSEADDR: Int32
    public static const SO_SNDBUF: Int32
    public static const SO_SNDTIMEO: Int32
    public static const TCP_KEEPCNT: Int32
    public static const TCP_KEEPIDLE: Int32
    public static const TCP_KEEPINTVL: Int32
    public static const TCP_NODELAY: Int32
}

功能:提供了常用的套接字选项。

static const IP_HDRINCL

public static const IP_HDRINCL: Int32

功能:用于在发送数据包时指定 IP 头部是否由应用程序提供的套接字选项。

类型:Int32

static const IP_TOS

public static const IP_TOS: Int32

功能:用于指定数据包服务类型和优先级的套接字选项。

类型:Int32

static const IP_TTL

public static const IP_TTL: Int32

功能:用于限制IP数据包在网络中传输最大跳数的套接字选项。

类型:Int32

static const SO_ACCEPTCONN

public static const SO_ACCEPTCONN: Int32

功能:用于查询套接字是否处于监听状态的套接字选项。

类型:Int32

static const SO_BROADCAST

public static const SO_BROADCAST: Int32

功能:用于设置套接字是否允许发送广播消息的套接字选项。

类型:Int32

static const SO_DEBUG

public static const SO_DEBUG: Int32

功能:用于启用或禁用调试模式的套接字选项。

类型:Int32

static const SO_DONTROUTE

public static const SO_DONTROUTE: Int32

功能:用于在连接套接字时,不路由套接字数据包的套接字选项。

类型:Int32

static const SO_ERROR

public static const SO_ERROR: Int32

功能:获取和清除套接字上错误状态的套接字选项。

类型:Int32

static const SO_KEEPALIVE

public static const SO_KEEPALIVE: Int32

功能:用于检测 TCP 连接是否仍然处于活动状态的套接字选项。

类型:Int32

static const SO_LINGER

public static const SO_LINGER: Int32

功能:用于设置套接字关闭时行为的套接字选项。

类型:Int32

static const SO_OOBINLINE

public static const SO_OOBINLINE: Int32

功能:用于控制接收带外数据方式的套接字选项。

类型:Int32

static const SO_RCVBUF

public static const SO_RCVBUF: Int32

功能:用于设置套接字接收缓冲区大小的套接字选项。

类型:Int32

static const SO_RCVTIMEO

public static const SO_RCVTIMEO: Int32

功能:用于设置套接字接收数据超时时间的套接字选项。

类型:Int32

static const SO_REUSEADDR

public static const SO_REUSEADDR: Int32

功能:用于在套接字关闭后立即释放其绑定端口,以便其他套接字可以立即绑定该端口的套接字选项。

类型:Int32

static const SO_SNDBUF

public static const SO_SNDBUF: Int32

功能:用于设置套接字发送缓冲区大小的套接字选项。

类型:Int32

static const SO_SNDTIMEO

public static const SO_SNDTIMEO: Int32

功能:用于设置套接字发送数据超时时间的套接字选项。

类型:Int32

static const TCP_KEEPCNT

public static const TCP_KEEPCNT: Int32

功能:用于控制 TCP 连接中发送保持存活探测报文次数的套接字选项。

类型:Int32

static const TCP_KEEPIDLE

public static const TCP_KEEPIDLE: Int32

功能:用于设置在没有收到对端确认的情况下,TCP 保持连接最大次数的套接字选项。

类型:Int32

static const TCP_KEEPINTVL

public static const TCP_KEEPINTVL: Int32

功能:用于设置 TCP 保持连接时发送探测报文时间间隔的套接字选项。

类型:Int32

static const TCP_NODELAY

public static const TCP_NODELAY: Int32

功能:用于控制 TCP 协议延迟行为的套接字选项。

类型:Int32

struct ProtocolType

public struct ProtocolType <: Equatable<ProtocolType> & ToString & Hashable {
    public static let ICMP: ProtocolType
    public static let IPV4: ProtocolType
    public static let IPV6: ProtocolType
    public static let RAW: ProtocolType
    public static let TCP: ProtocolType
    public static let UDP: ProtocolType
    public static let Unspecified: ProtocolType
    public init(protocol: Int32)
}

功能:提供了常用的套接字协议,以及通过指定 Int32 值来构建套接字协议的功能。

父类型:

static let ICMP

public static let ICMP: ProtocolType

功能:指定协议类型为 ICMP

类型:ProtocolType

static let IPV4

public static let IPV4: ProtocolType

功能:指定协议类型为 IPv4

类型:ProtocolType

static let IPV6

public static let IPV6: ProtocolType

功能:指定协议类型为 IPv6

类型:ProtocolType

static let RAW

public static let RAW: ProtocolType

功能:指定协议类型为 RAW

类型:ProtocolType

static let TCP

public static let TCP: ProtocolType

功能:指定协议类型为 TCP

类型:ProtocolType

static let UDP

public static let UDP: ProtocolType

功能:指定协议类型为 UDP

类型:ProtocolType

static let Unspecified

public static let Unspecified: ProtocolType

功能:不指定协议类型。

类型:ProtocolType

init(Int32)

public init(protocol: Int32)

功能:通过指定套接字协议值创建协议。

参数:

  • protocol: Int32 - 套接字协议值。

func hashCode()

public func hashCode(): Int64

功能:返回当前 ProtocolType 实例的哈希值。

返回值:

func toString()

public func toString(): String

功能:返回当前 ProtocolType 实例的字符串表示。

返回值:

operator func !=(ProtocolType)

public operator func !=(r: ProtocolType): Bool

功能:判断两个 ProtocolType 实例是否不等。

参数:

返回值:

  • Bool - 当二者代表的 Int32 值不等时,返回 true;否则,返回 false

operator func ==(ProtocolType)

public operator func ==(r: ProtocolType): Bool

功能:判断两个 ProtocolType 实例是否相等。

参数:

返回值:

  • Bool - 当二者代表的 Int32 值相等时,返回 true;否则,返回 false

struct RawAddress

public struct RawAddress {
    public init(addr: Array<Byte>)
}

功能:提供了 RawSocket 的通信地址创建和获取功能。

prop addr

public prop addr: Array<Byte>

功能:获取地址。

类型:Array<Byte>

init(Array<Byte>)

public init(addr: Array<Byte>)

功能:根据字节数组创建地址。

参数:

  • addr: Array<Byte> - 存储地址的字节数组。

struct SocketDomain

public struct SocketDomain <: Equatable<SocketDomain> & ToString & Hashable {
    public static let IPV4: SocketDomain
    public static let IPV6: SocketDomain
    public static let NETLINK: SocketDomain
    public static let PACKET: SocketDomain
    public static let UNIX: SocketDomain
    public init(domain: Int32)
}

功能:提供了常用的套接字通信域,以及通过指定 Int32 值来构建套接字通信域的功能。

父类型:

static let IPV4

public static let IPV4: SocketDomain

功能:IPv4 通信域。

类型:SocketDomain

static let IPV6

public static let IPV6: SocketDomain

功能:IPv6 通信域。

类型:SocketDomain

public static let NETLINK: SocketDomain

功能:内核和用户空间进程之间通信。

注意:

  • 该常量在 Windows 平台不提供。

类型:SocketDomain

static let PACKET

public static let PACKET: SocketDomain

功能:允许用户空间程序直接访问网络数据包。

注意:

  • 该常量在 Windows 平台不提供。

类型:SocketDomain

static let UNIX

public static let UNIX: SocketDomain

功能:本机通信。

类型:SocketDomain

init(Int32)

public init(domain: Int32)

功能:根据指定通信域值创建套接字通信域。

参数:

  • domain: Int32 - 通信域值。

func hashCode()

public func hashCode(): Int64

功能:返回当前 SocketDomain 实例的哈希值。

返回值:

func toString()

public func toString(): String

功能:返回当前 SocketDomain 实例的字符串表示。

返回值:

operator func !=(SocketDomain)

public operator func !=(r: SocketDomain): Bool

功能:比较两个 SocketDomain 实例是否不等。

参数:

返回值:

  • Bool - 当二者代表的 Int32 值不等时,返回 true;否则,返回 false

operator func ==(SocketDomain)

public operator func ==(r: SocketDomain): Bool

功能:比较两个 SocketDomain 实例是否相等。

参数:

返回值:

  • Bool - 当二者代表的 Int32 值相等时,返回 true;否则,返回 false

struct SocketKeepAliveConfig

public struct SocketKeepAliveConfig <: ToString & Equatable<SocketKeepAliveConfig> {
    public let count: UInt32
    public let idle: Duration
    public let interval: Duration
    public init(idle!: Duration = Duration.second * 45, interval!: Duration = Duration.second * 5, count!: UInt32 = 5)
}

功能:TCP KeepAlive 属性配置。

父类型:

let count

public let count: UInt32

功能:查询连接是否失效的报文个数。

类型:UInt32

let idle

public let idle: Duration

功能:允许连接空闲的时长,空闲超长将关闭连接。

类型:Duration

let interval

public let interval: Duration

功能:保活报文发送周期。

类型:Duration

init(Duration, Duration, UInt32)

public init(idle!: Duration = Duration.second * 45, interval!: Duration = Duration.second * 5, count!: UInt32 = 5)

功能:初始化 SocketKeepAliveConfig 实例对象。

参数:

  • idle!: Duration - 允许空闲的时长,默认 45 秒。
  • interval!: Duration - 保活报文发送周期,默认 45 秒。
  • count!: UInt32 - 查询连接是否失效的报文个数, 默认 5 个。

异常:

func toString()

public override func toString(): String

功能:将 TCP KeepAlive 属性配置转换为字符串。

返回值:

  • String - 转换后的字符串。

operator func !=(SocketKeepAliveConfig)

public override operator func !=(other: SocketKeepAliveConfig): Bool

功能:判断两个 SocketKeepAliveConfig 实例是否不等。

参数:

返回值:

  • Bool - 如果不等,则返回 true;否则,返回 false

operator func ==(SocketKeepAliveConfig)

public override operator func ==(other: SocketKeepAliveConfig): Bool

功能:判断两个 SocketKeepAliveConfig 实例是否相等。

参数:

返回值:

  • Bool - 如果相等,则返回 true;否则,返回 false

struct SocketOptions

public struct SocketOptions {
    public static const IPPROTO_TCP
    public static const IPPROTO_UDP
    public static const SOL_SOCKET
    public static const SO_BINDTODEVICE
    public static const SO_KEEPALIVE
    public static const SO_LINGER
    public static const SO_RCVBUF
    public static const SO_REUSEADDR
    public static const SO_REUSEPORT
    public static const SO_SNDBUF
    public static const TCP_NODELAY
    public static const TCP_QUICKACK
}

功能:SocketOptions 存储了设置套接字选项的一些参数常量方便后续调用。

const IPPROTO_TCP

public static const IPPROTO_TCP: Int32 = IPPROTO_TCP

功能:常数,用于将套接字选项的 level 层级设为 IPPROTO_TCP

类型:Int32

const IPPROTO_UDP

public static const IPPROTO_UDP: Int32 = IPPROTO_UDP

功能:常数,用于将套接字选项的 level 层级设为 IPPROTO_UDP

类型:Int32

const SOL_SOCKET

public static const SOL_SOCKET: Int32 = SOL_SOCKET

功能:常数,用于将套接字选项的 level 层级设为 SOL_SOCKET

类型:Int32

const SO_BINDTODEVICE

public static const SO_BINDTODEVICE: Int32 = SOCK_BINDTODEVICE

功能:常数,用于将套接字选项的 optname 设为 SO_BINDTODEVICE

类型:Int32

const SO_KEEPALIVE

public static const SO_KEEPALIVE: Int32 = SOCK_KEEPALIVE

功能:常数,用于将套接字选项的 optname 设为 SO_KEEPALIVE

类型:Int32

const SO_LINGER

public static const SO_LINGER: Int32 = SOCK_LINGER

功能:常数,用于将套接字选项的 optname 设为 SO_LINGER

类型:Int32

const SO_RCVBUF

public static const SO_RCVBUF: Int32 = SOCK_RCVBUF

功能:常数,用于将套接字选项的 optname 设为 SO_RCVBUF

类型:Int32

const SO_REUSEADDR

public static const SO_REUSEADDR: Int32 = SOCK_REUSEADDR

功能:常数,用于将套接字选项的 optname 设为 SO_REUSEADDR

类型:Int32

const SO_REUSEPORT

public static const SO_REUSEPORT: Int32 = SOCK_REUSEPORT

功能:常数,用于将套接字选项的 optname 设为 SO_REUSEPORT

类型:Int32

const SO_SNDBUF

public static const SO_SNDBUF: Int32 = SOCK_SNDBUF

功能:常数,用于将套接字选项的 optname 设为 SO_SNDBUF

类型:Int32

const TCP_NODELAY

public static const TCP_NODELAY: Int32 = SOCK_TCP_NODELAY

功能:常数,用于将套接字选项的 optname 设为 TCP_NODELAY

类型:Int32

const TCP_QUICKACK

public static const TCP_QUICKACK: Int32 = SOCK_TCP_QUICKACK

功能:常数,用于将套接字选项的 optname 设为 TCP_QUICKACK

类型:Int32

struct SocketType

public struct SocketType <: Equatable<SocketType> & ToString & Hashable {
    public static let DATAGRAM: SocketType
    public static let RAW: SocketType
    public static let SEQPACKET: SocketType
    public static let STREAM: SocketType
    public init(`type`: Int32)
}

功能:提供了常用的套接字类型,以及通过指定 Int32 值来构建套接字类型的功能。

父类型:

static let DATAGRAM

public static let DATAGRAM: SocketType

功能:数据报套接字类型。

类型:SocketType

static let RAW

public static let RAW: SocketType

功能:原始套接字类型。

类型:SocketType

static let SEQPACKET

public static let SEQPACKET: SocketType

功能:有序数据包套接字类型。

类型:SocketType

static let STREAM

public static let STREAM: SocketType

功能:流式套接字类型。

类型:SocketType

init(Int32)

public init(`type`: Int32)

功能:通过指定套接字类型值创建套接字类型。

参数:

  • `type`: Int32 - 套接字类型值。

func hashCode()

public func hashCode(): Int64

功能:返回当前 SocketType 实例的哈希值。

返回值:

func toString()

public func toString(): String

功能:返回当前 SocketType 实例的字符串表示。

返回值:

operator func !=(SocketType)

public operator func !=(r: SocketType): Bool

功能:判断两个 SocketType 实例是否不等。

参数:

返回值:

  • Bool - 当二者代表的 Int32 值不等时,返回 true;否则,返回 false

operator func ==(SocketType)

public operator func ==(r: SocketType): Bool

功能:判断两个 SocketType 实例是否相等。

参数:

返回值:

  • Bool - 当二者代表的 Int32 值相等时,返回 true;否则,返回 false

异常类

class SocketException

public class SocketException <: IOException {
    public init()
    public init(message: String)
}

功能:提供套接字相关的异常处理。

父类型:

init()

public init()

功能:创建 SocketException 实例。

init(String)

public init(message: String)

功能:根据异常信息创建 SocketException 实例。

参数:

  • message: String - 异常提示信息。

class SocketTimeoutException

public class SocketTimeoutException <: Exception {
    public init()
    public init(message: String)
}

功能:提供套接字操作超时相关的异常处理。

父类型:

init()

public init()

功能:创建 SocketTimeoutException 实例。

init(String)

public init(message: String)

功能:根据异常信息创建 SocketTimeoutException 实例。

参数:

  • message: String - 异常提示信息。

属性配置使用用例

属性配置

import std.net.*
import std.time.*
import std.sync.*

main (){
   try (tcpSocket = TcpSocket("127.0.0.1", 80)) {
      tcpSocket.readTimeout = Duration.second
      tcpSocket.noDelay = false
      tcpSocket.linger = Duration.minute

      tcpSocket.keepAlive = SocketKeepAliveConfig(
         interval: Duration.second * 7,
         count: 15
      )
   }
}

增加自定义属性

import std.net.*

extend TcpSocket {
    public mut prop customNoDelay: Int64 {
        get() {
            Int64(getSocketOptionIntNative(SocketOptions.IPPROTO_TCP, SocketOptions.TCP_NODELAY))
        }
        set(value) {
            setSocketOptionIntNative(SocketOptions.IPPROTO_TCP, SocketOptions.TCP_NODELAY, IntNative(value))
        }
    }
}

main() {
    let socket = TcpSocket("127.0.0.1", 0)
    socket.customNoDelay = 1
    println(socket.customNoDelay)
}

运行结果:

1

TCP 使用示例

import std.net.*
import std.time.*
import std.sync.*

let SERVER_PORT: UInt16 = 33333

func runTcpServer() {
    try (serverSocket = TcpServerSocket(bindAt: SERVER_PORT)) {
        serverSocket.bind()

        try (client = serverSocket.accept()) {
            let buf = Array<Byte>(10, repeat: 0)
            let count = client.read(buf)

            // Server read 3 bytes: [1, 2, 3, 0, 0, 0, 0, 0, 0, 0]
            println("Server read ${count} bytes: ${buf}")
        }
    }
}

main(): Int64 {
    spawn {
        runTcpServer()
    }
    sleep(Duration.millisecond * 500)

    try (socket = TcpSocket("127.0.0.1", SERVER_PORT)) {
        socket.connect()
        socket.write([1, 2, 3])
    }

    return 0
}

运行结果:

Server read 3 bytes: [1, 2, 3, 0, 0, 0, 0, 0, 0, 0]

UDP 使用示例

import std.net.*
import std.time.*
import std.sync.*

let SERVER_PORT: UInt16 = 33333

func runUpdServer() {
    try (serverSocket = UdpSocket(bindAt: SERVER_PORT)) {
        serverSocket.bind()

        let buf = Array<Byte>(3, repeat: 0)

        let (clientAddr, count) = serverSocket.receiveFrom(buf)
        let sender = (clientAddr as IPSocketAddress)?.address.toString() ?? ""

        // Server receive 3 bytes: [1, 2, 3] from 127.0.0.1
        println("Server receive ${count} bytes: ${buf} from ${sender}")
    }
}

main(): Int64 {
    spawn {
        runUpdServer()
    }
    sleep(Duration.second)

    try (udpSocket = UdpSocket(bindAt: 0)) { // random port
        udpSocket.sendTimeout = Duration.second * 2
        udpSocket.bind()
        udpSocket.sendTo(
            IPSocketAddress("127.0.0.1", SERVER_PORT),
            [1, 2, 3]
        )
    }

    return 0
}

运行结果:

Server receive 3 bytes: [1, 2, 3] from 127.0.0.1

UNIX 使用示例

import std.net.*
import std.time.*
import std.sync.*

let SOCKET_PATH = "/tmp/tmpsock"

func runUnixServer() {
    try (serverSocket = UnixServerSocket(bindAt: SOCKET_PATH)) {
        serverSocket.bind()

        try (client = serverSocket.accept()) {
            client.write("hello".toArray())
        }
    }
}

main(): Int64 {
    spawn {
        runUnixServer()
    }
    sleep(Duration.second)

    try (socket = UnixSocket(SOCKET_PATH)) {
        socket.connect()

        let buf = Array<Byte>(10, repeat: 0)
        socket.read(buf)

        println(String.fromUtf8(buf)) // hello
    }

    return 0
}

运行结果:

hello

UnixDatagram 使用示例

import std.net.*
import std.time.*
import std.sync.*
import std.fs.*
import std.random.*
import std.process.*

func createTempFile(): String {
    let tempDir: Path = Process.current.tempDirectory

    let index: String = Random().nextUInt64().toString()

    return tempDir.join("tmp${index}").toString()
}

func runUnixDatagramServer(serverPath: String, clientPath: String) {
    try (serverSocket = UnixDatagramSocket(bindAt: serverPath)) {
        serverSocket.bind()

        let buf = Array<Byte>(3, repeat: 0)

        let (clientAddr, read) = serverSocket.receiveFrom(buf)

        if (read == 3 && buf == [1, 2, 3]) {
            println("server received")
        }
        if (clientAddr.toString() == clientPath) {
            println("client address correct")
        }
    }
}

main(): Int64 {
    let clientPath = createTempFile()
    let serverPath = createTempFile()
    spawn {
        runUnixDatagramServer(serverPath, clientPath)
    }
    sleep(Duration.second)

    try (unixSocket = UnixDatagramSocket(bindAt: clientPath)) {
        unixSocket.sendTimeout = Duration.second * 2
        unixSocket.bind()
        unixSocket.connect(serverPath)

        unixSocket.send([1, 2, 3])
        sleep(Duration.second)
    }

    return 0
}

运行结果:

server received
client address correct

std.objectpool 包

功能介绍

objectpool 包提供了对象缓存和复用的功能。

在面向对象语言中,对象的申请和释放普遍实现复杂,耗时较长,很可能成为应用程序的性能瓶颈。仓颉对象的申请和释放也面临同样的问题。对象池通过缓存、复用对象,减少对象的申请和释放,有效提高程序性能。

本包 ObjectPool 类实现了将指定类型的对象进行缓存和复用,调用 put 方法可将使用完毕的对象放入对象池缓存,调用 get 方法可从对象池缓存中取出待使用的对象。

此外,为了减少竞争,进一步提升对象存取的效率,ObjectPool 在实现中根据当前所在仓颉线程的 id 在不同数组中进行对象存取。

注意:

1、由于 ObjectPool 在实现中根据仓颉线程 id 进行存取,将导致存和取分布在不同仓颉线程的情况下,存入的对象难以被取到。因此应该在存和取均匀分布在各个仓颉线程的场景下使用该对象池。

2、暂不支持自动缩减容量。

API列表

类名功能
ObjectPool此类提供了一个并发安全的对象缓存类型,该类型可以储存已经分配内存但未使用的对象。

class ObjectPool<T> where T <: Object

public class ObjectPool<T> where T <: Object

功能: 此类提供了一个并发安全的对象缓存类型,该类型可以储存已经分配内存但未使用的对象。

说明:

  1. 当一个对象不需要使用时可以将对象存入 ObjectPool,当需要使用对象时再从该 ObjectPool 中取出。
  2. 储存在一个 ObjectPool 中的对象只能是同一种类型。
  3. 在一个 ObjectPool 对象的生命周期结束前,该 ObjectPool 对象中存储的对象不会被释放。

示例:

import std.objectpool.*
class City {
    var id: Int64 = 0
    var name: String = ""
}

func resetCity(c: City): City {
    let city = c
    city.id = 0
    city.name = ""
    return city
}

main() {
    let cityPool = ObjectPool({ => City()}, resetFunc: resetCity)
    let cityA = cityPool.get()
    cityA.id = 30
    cityA.name = "A"
    println("id: ${cityA.id}, name: ${cityA.name}")
    cityPool.put(cityA)
}

运行结果:

id: 30, name: A

init(() -> T, Option<(T) -> T>)

public init(newFunc: () -> T, resetFunc!: Option<(T) -> T> = None)

功能:创建新的 ObjectPool 对象。

参数:

  • newFunc: () ->T - 当调用 get 方法时,若从 ObjectPool 中获取对象失败,则调用 newFn 创建一个新对象, newFunc 应保证并发安全。
  • resetFunc!: Option<(T) ->T> - 调用 get 方法时会调用 resetFunc 重置对象状态,resetFunc 为 None 表示不重置, resetFunc 应保证并发安全。

func get()

public func get(): T

功能:尝试从 ObjectPool 中获取对象, 若从 ObjectPool 中获取对象失败,则调用 newFunc 创建新的对象并返回该对象get 的对象不使用之后应该通过 put 归还给 ObjectPool

返回值:

  • T - 从 ObjectPool 中获取到的对象或调用 newFunc 新建的对象。

func put(T)

public func put(item: T): Unit

功能:尝试将对象放入 ObjectPool 中,不保证一定会将对象放入 ObjectPool在对一个对象调用 put 后不应该再对该对象进行任何操作,否则可能导致不可期问题。

参数:

std.posix 包

功能介绍

posix 包主要适配 POSIX 系统接口。

本包提供多平台统一操控能力,目前支持 Linux 平台,macOS 平台,Windows 平台与 HarmonyOS 平台。

API 列表

函数

函数名功能支持平台
open(String, Int32)打开文件并为其返回新的文件描述符,或在失败时返回 -1Linux Windows macOS HarmonyOS
open(String, Int32, UInt32)打开文件并为其返回新的文件描述符,或在失败时返回 -1Linux Windows macOS HarmonyOS
access(String, Int32)判断某个文件是否具有某种权限,具有返回 0,否则返回 -1Linux Windows macOS HarmonyOS
chdir(String)通过指定路径的方式,更改调用进程的当前工作目录。Linux Windows macOS HarmonyOS
chmod(String, UInt32)修改文件访问权限。Linux Windows macOS HarmonyOS
chown(String, UInt32, UInt32)修改文件所有者和文件所有者所属组。Linux macOS HarmonyOS
close(Int32)关闭文件,close 将会触发数据写回磁盘,并释放文件占用的资源。Linux Windows macOS HarmonyOS
creat(String, UInt32)创建文件并为其返回文件描述符,或在失败时返回 -1Linux Windows macOS HarmonyOS
dup(Int32)用于复制旧 fd 参数指定的文件描述符并返回。Linux Windows macOS HarmonyOS
dup2(Int32, Int32)用于复制 oldfd 参数指定的文件描述符,并将其返回到 newfd 参数。Linux Windows macOS HarmonyOS
faccessat(Int32, String, Int32, Int32)判断 fd 对应的文件是否具有某种权限,具有返回 0,否则返回 -1Linux macOS HarmonyOS
fchdir(Int32)通过指定文件路径的描述符,更改调用进程的当前工作目录。Linux macOS HarmonyOS
fchmod(Int32, UInt32)修改文件描述符对应的文件访问权限。Linux Windows macOS HarmonyOS
fchmodat(Int32, String, UInt32, Int32)修改文件描述符对应的文件访问权限。Linux Windows macOS HarmonyOS
fchown(Int32, UInt32, UInt32)修改 fd 对应的文件所有者和文件所有者所属组。Linux macOS HarmonyOS
fchownat(Int32, String, UInt32, UInt32, Int32)修改文件描述符对应的文件所有者和文件所有者所属组。Linux macOS HarmonyOS
getcwd()获取当前执行进程工作目录的绝对路径。Linux Windows macOS HarmonyOS
getgid()获取用户组 IDLinux macOS HarmonyOS
getgroups(Int32, CPointer<UInt32>)获取当前用户所属组的代码。Linux macOS HarmonyOS
gethostname()获取主机名称,此名称通常是 TCP/IP 网络上主机的名称。Linux macOS HarmonyOS
getlogin()获取当前登录名。Linux macOS HarmonyOS
getos()/proc/version 文件中获取 Linux 系统的信息。Linux
getpgid(Int32)获取 pid 指定的进程的 PGID,如果 pid 为零,返回调用进程的进程 IDLinux macOS HarmonyOS
getpgrp()获取调用进程的父进程 IDLinux macOS HarmonyOS
getpid()获取调用进程的进程 ID(PID)Linux Windows macOS HarmonyOS
getppid()获取调用进程的父进程 IDLinux macOS HarmonyOS
getuid()获取调用进程的真实用户 IDLinux macOS HarmonyOS
isBlk(String)检查传入对象是否为块设备,并返回布尔类型。Linux Windows macOS HarmonyOS
isChr(String)检查传入对象是否为字符设备,返回布尔类型。Linux Windows macOS HarmonyOS
isDir(String)检查传入对象是否为文件夹,返回布尔类型。Linux Windows macOS HarmonyOS
isFIFO(String)检查传入对象是否为 FIFO 文件,返回布尔类型。Linux macOS HarmonyOS
isLnk(String)检查传入对象是否为软链路,返回布尔类型。Linux macOS HarmonyOS
isReg(String)检查传入对象是否为普通文件,返回布尔类型。Linux Windows macOS HarmonyOS
isSock(String)检查传入对象是否为套接字文件,返回布尔类型。Linux macOS HarmonyOS
isType(String, UInt32)检查文件是否为指定模式的文件。Linux macOS HarmonyOS
isatty(Int32)用于测试文件描述符是否引用终端,成功时返回 true,否则返回 falseLinux Windows macOS HarmonyOS
kill(Int32, Int32)系统调用可用于向任何进程组或进程发送任何信号。Linux macOS HarmonyOS
killpg(Int32, Int32)将信号 sig 发送到进程组 pgrp,如果 pgrp0,则 killpg() 将信号发送到调用进程的进程组。Linux macOS HarmonyOS
lchown(String, UInt32, UInt32)修改文件链接本身所有者和所有者所属组。Linux macOS
link(String, String)为存在的文件创建链接,一个文件可以有多个指向其 i-node 的目录条目。Linux macOS HarmonyOS
linkat(Int32, String, Int32, String, Int32)创建相对于目录文件描述符的文件链接。Linux macOS HarmonyOS
lseek(Int32, Int64, Int32)当文件进行读或写时,读或写位置相应增加。Linux Windows macOS HarmonyOS
nice(Int32)更改当前线程的优先级。Linux macOS HarmonyOS
open64(String, Int32)打开文件并为其返回新的文件描述符,或在失败时返回 -1Linux HarmonyOS
open64(String, Int32, UInt32)打开文件并为其返回新的文件描述符,或在失败时返回 -1Linux HarmonyOS
openat(Int32, String, Int32)打开文件并为其返回新的文件描述符,或在失败时返回 -1Linux macOS HarmonyOS
openat(Int32, String, Int32, UInt32)打开文件并为其返回新的文件描述符,或在失败时返回 -1Linux macOS HarmonyOS
openat64(Int32, String, Int32)打开文件并为其返回新的文件描述符,或在失败时返回 -1Linux macOS HarmonyOS
openat64(Int32, String, Int32, UInt32)打开文件并为其返回新的文件描述符,或在失败时返回 -1Linux macOS HarmonyOS
pread(Int32, CPointer<UInt8>, UIntNative, Int32)fd 指向的文件的 nbyte 字节传输到 buffer 指向的内存中。Linux macOS HarmonyOS
pwrite(Int32, CPointer<UInt8>, UIntNative, Int32)buffer 指向的内存中 nbyte 字节从指定偏移位置开始写入到 fd 指向的文件。Linux macOS HarmonyOS
read(Int32, CPointer<UInt8>, UIntNative)fd 指向的文件的 nbyte 字节传输到 buffer 指向的内存中。Linux Windows macOS HarmonyOS
remove(String)删除文件或目录。Linux Windows macOS HarmonyOS
rename(String, String)重命名文件,如果需要将会移动文件所在目录。Linux Windows macOS HarmonyOS
renameat(Int32, String, Int32, String)重命名文件,如果需要将会移动文件所在目录。Linux macOS HarmonyOS
setgid(UInt32)设置调用进程的有效组 ID,需要适当的权限。Linux macOS
sethostname(String)设置主机名,仅超级用户可以调用。Linux macOS
setpgid(Int32, Int32)此函数将参数 pid 指定的组 ID 设置为参数 pgrp 指定的组 IDLinux macOS HarmonyOS
setpgrp()将当前进程所属的组 ID 设置为当前进程的进程 ID,此函数等同于调用 setpgid(0, 0)。Linux macOS HarmonyOS
setuid(UInt32)设置调用进程的有效用户 ID,需要适当的权限。Linux macOS
symlink(String, String)创建一个名为 symPath 链接到 path 所指定的文件。Linux macOS HarmonyOS
symlinkat(String, Int32, String)创建一个名为 symPath 链接到 pathfd 所指定的文件。Linux macOS HarmonyOS
ttyname(Int32)返回终端名称。Linux Windows macOS HarmonyOS
umask(UInt32)设置权限掩码。Linux Windows macOS HarmonyOS
unlink(String)从文件系统中删除文件。Linux macOS HarmonyOS
unlinkat(Int32, String, Int32)从文件系统中删除文件。Linux macOS HarmonyOS
write(Int32, CPointer<UInt8>, UIntNative)buffer 指向的内存中 nbyte 字节写入到 fd 指向的文件。Linux Windows macOS HarmonyOS

常量

常量名功能支持平台
AT_EMPTY_PATH表示在文件系统中空路径(即没有指定任何文件或目录)时返回的文件描述符,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux Windows HarmonyOS
AT_REMOVEDIR如果指定了 AT_REMOVEDIR 标志,则对 pathname 执行等效于 rmdir(2) 的操作,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux Windows macOS HarmonyOS
O_CLOEXEC在某些多线程程序中,使用此标志是必不可少的。因为在一个线程同时打开文件描述符,而另一个线程执行 fork(2)execve(2) 场景下使用单独的 fcntl(2) F_SETFD 操作设置 FD_CLOEXEC 标志并不足以避免竞争条件,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux macOS HarmonyOS
O_DIRECTORY如果 pathname 指定的文件不是目录,则打开文件失败,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux macOS HarmonyOS
O_CREAT如果要打开的文件不存在,则自动创建该文件,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux Windows macOS HarmonyOS
O_DSYNC每次写入都会等待物理 I/O 完成,但如果写操作不影响读取刚写入的数据,则不等待文件属性更新,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux macOS HarmonyOS
O_EXCL如同时设置 O_CREAT,则此指令检查文件是否存在。如果文件不存在,则创建文件。否则,打开文件出错。此外,如果同时设置了 O_CREATO_EXCL,并且要打开的文件是符号链接,则打开文件失败,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux Windows macOS HarmonyOS
O_NOCTTY如要打开的文件是终端设备,则该文件不会成为这个进程的控制终端,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux macOS HarmonyOS
O_NOFOLLOWpathname 指定的文件是单符号链接,则打开文件失败,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux macOS HarmonyOS
O_NONBLOCK以非阻塞的方式打开文件,即 I/O 操作不会导致调用进程等待,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux macOS HarmonyOS
O_SYNC同步打开文件,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux macOS HarmonyOS
O_RDONLY以只读方式打开文件,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux Windows macOS HarmonyOS
O_RDWR以读写模式打开文件,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux Windows macOS HarmonyOS
O_WRONLY以只写方式打开文件,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux Windows macOS HarmonyOS
O_APPEND读取或写入文件时,数据将从文件末尾移动。即写入的数据将附加到文件的末尾,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux Windows macOS HarmonyOS
O_RSYNC此标志仅影响读取操作,必须与 O_SYNCO_DSYNC 结合使用。如果有必要,它将导致读取调用阻塞,直到正在读取的数据(可能还有元数据)刷新到磁盘,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux HarmonyOS
O_TRUNC如果文件存在且打开可写,则此标志将文件长度清除为 0,文件中以前存储的数据消失,适用函数 openopen64openatopenat64,所属函数参数 oflagLinux Windows macOS HarmonyOS
R_OK测试文件读权限,适用函数 accessfaccessat,所属函数参数 modeLinux Windows macOS HarmonyOS
W_OK测试文件写权限,适用函数 accessfaccessat,所属函数参数 modeLinux Windows macOS HarmonyOS
X_OK测试文件执行权限,适用函数 accessfaccessat,所属函数参数 modeLinux Windows macOS HarmonyOS
F_OK测试文件是否存在,适用函数 accessfaccessat,所属函数参数 modeLinux Windows macOS HarmonyOS
SEEK_SET偏移参数表示新的读写位置,适用函数 lseek,所属函数参数 whenceLinux Windows macOS HarmonyOS
SEEK_CUR向当前读或写位置添加偏移量,适用函数 lseek,所属函数参数 whenceLinux Windows macOS HarmonyOS
SEEK_END将读写位置设置为文件末尾,并添加偏移量,适用函数 lseek,所属函数参数 whenceLinux Windows macOS HarmonyOS
SIGABRT异常终止,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGBUS硬件故障,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGFPE算术错误,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGKILL终止,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGCONT暂停过程的继续,默认操作继续或忽略,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGHUP连接已断开,默认操作已终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGINT终端中断字符,默认动作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGQUIT终端退出字符,默认动作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGILL硬件指令无效,默认动作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGTRAP硬件故障,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGIOT硬件故障,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGIO异步 IO,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGPIPE写入未读进程的管道,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGALRM计时器到期,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGPWR电源故障或重启,系统调用无效,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows HarmonyOS
SIGSEGV内存引用无效,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGSTOP停止,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGTERM终止,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGSTKFLT协处理器堆栈故障,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows HarmonyOS
SIGCHLD子进程状态更改,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGTSTP终端停止符号,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGTTIN后台读取控件 tty,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGTTOU后台写控制 tty,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGURG紧急情况(套接字),忽略默认操作,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGUSR1用户定义的信号,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGUSR2用户定义的信号,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGVTALRM虚拟时间警报,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGPROF摘要超时,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGWINCH终端窗口大小更改,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGXCPUCPU 占用率超过上限,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
SIGXFSZ文件长度超过上限,默认操作终止,适用函数 killkillpg,所属函数参数 sigLinux Windows macOS HarmonyOS
S_IRUSR表示文件所有者具有读权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS
S_IWUSR表示文件所有者具有写权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS
S_IRGRP表示文件用户组具有读权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS
S_IWGRP表示文件用户组具有写权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS
S_IFREG文件类型为一般文件,适用函数 isType, 所属函数参数 modeLinux Windows macOS HarmonyOS
S_IFBLK文件类型为块设备,适用函数 isType, 所属函数参数 modeLinux Windows macOS HarmonyOS
S_IFDIR文件类型为目录,适用函数 isType, 所属函数参数 modeLinux Windows macOS HarmonyOS
S_IFCHR文件类型为字符设备,适用函数 isType, 所属函数参数 modeLinux Windows macOS HarmonyOS
S_IFIFO文件类型为 FIFO 文件,适用函数 isType, 所属函数参数 modeLinux Windows macOS HarmonyOS
S_IFLNK文件类型为软连接,适用函数 isType, 所属函数参数 modeLinux Windows macOS HarmonyOS
S_IFSOCK文件类型为套接字文件,适用函数 isType, 所属函数参数 modeLinux Windows macOS HarmonyOS
S_IROTH表示其他用户对文件具有读权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS
S_IRWXG表示文件用户组具有读、写、执行权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS
S_IRWXU表示文件所有者具有读、写和执行权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS
S_IWOTH表示其他用户对文件具有写权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS
S_IXOTH表示其他用户对文件具有执行权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS
S_IRWXO表示其他用户对文件具有读、写和执行权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS
S_IXGRP表示文件用户组具有执行权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS
S_IXUSR表示文件所有者具有执行权限,适用函数 openopen64openatopenat64chmod(mode)fchmod(mode)fchmodat(mode)creat, 所属函数参数 flagLinux Windows macOS HarmonyOS

常量&变量

const AT_EMPTY_PATH

public const AT_EMPTY_PATH: Int32

功能:表示在文件系统中空路径(即没有指定任何文件或目录)时返回的文件描述符,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const AT_REMOVEDIR

public const AT_REMOVEDIR: Int32

功能:如果指定了 AT_REMOVEDIR 标志,则对 pathname 执行等效于 rmdir(2) 的操作,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const F_OK

public const F_OK: Int32

功能:测试文件是否存在,适用函数 accessfaccessat,所属函数参数 mode

类型:Int32

const O_APPEND

public const O_APPEND: Int32

功能:读取或写入文件时,数据将从文件末尾移动。即写入的数据将附加到文件的末尾,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_CLOEXEC

public const O_CLOEXEC: Int32

功能:在某些多线程程序中,使用此标志是必不可少的。因为在一个线程同时打开文件描述符,而另一个线程执行 fork(2)execve(2) 场景下使用单独的 fcntl(2) F_SETFD 操作设置 FD_CLOEXEC 标志并不足以避免竞争条件,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_CREAT

public const O_CREAT: Int32

功能:如果要打开的文件不存在,则自动创建该文件,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_DIRECTORY

public const O_DIRECTORY: Int32

功能:如果 pathname 指定的文件不是目录,则打开文件失败,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_DSYNC

public const O_DSYNC: Int32

功能:每次写入都会等待物理 I/O 完成,但如果写操作不影响读取刚写入的数据,则不等待文件属性更新,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_EXCL

public const O_EXCL: Int32

功能:如同时设置 O_CREAT,则此指令检查文件是否存在。如果文件不存在,则创建文件。否则,打开文件出错。此外,如果同时设置了 O_CREATO_EXCL,并且要打开的文件是符号链接,则打开文件失败,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_NOCTTY

public const O_NOCTTY: Int32

功能:如要打开的文件是终端设备,则该文件不会成为这个进程的控制终端,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_NOFOLLOW

public const O_NOFOLLOW: Int32

功能:如 pathname 指定的文件是单符号连接,则打开文件失败,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_NONBLOCK

public const O_NONBLOCK: Int32

功能:以非阻塞的方式打开文件,即 I/O 操作不会导致调用进程等待,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_RDONLY

public const O_RDONLY: Int32

功能:以只读方式打开文件,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_RDWR

public const O_RDWR: Int32

功能:以读写模式打开文件,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_RSYNC

public const O_RSYNC: Int32

功能:此标志仅影响读取操作,必须与 O_SYNCO_DSYNC 结合使用。如果有必要,它将导致读取调用阻塞,直到正在读取的数据(可能还有元数据)刷新到磁盘,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_SYNC

public const O_SYNC: Int32

功能:同步打开文件,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_TRUNC

public const O_TRUNC: Int32

功能:如果文件存在且打开可写,则此标志将文件长度清除为 0,文件中以前存储的数据消失,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const O_WRONLY

public const O_WRONLY: Int32

功能:以只写方式打开文件,适用函数 openopen64openatopenat64,所属函数参数 oflag

类型:Int32

const R_OK

public const R_OK: Int32

功能:测试文件读权限,适用函数 accessfaccessat,所属函数参数 mode

类型:Int32

const SEEK_CUR

public const SEEK_CUR: Int32

功能:向当前读或写位置添加偏移量,适用函数 lseek,所属函数参数 whence

类型:Int32

const SEEK_END

public const SEEK_END: Int32

功能:将读写位置设置为文件末尾,并添加偏移量,适用函数 lseek,所属函数参数 whence

类型:Int32

const SEEK_SET

public const SEEK_SET: Int32

功能:偏移参数表示新的读写位置,适用函数 lseek,所属函数参数 whence

类型:Int32

const SIGABRT

public const SIGABRT: Int32

功能:异常终止,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGALRM

public const SIGALRM: Int32

功能:计时器到期,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGBUS

public const SIGBUS: Int32

功能:硬件故障,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGCHLD

public const SIGCHLD: Int32

功能:子进程状态更改,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGCONT

public const SIGCONT: Int32

功能:暂停过程的继续,默认操作继续或忽略,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGFPE

public const SIGFPE: Int32

功能:算术错误,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGHUP

public const SIGHUP: Int32

功能:连接已断开,默认操作已终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGILL

public const SIGILL: Int32

功能:硬件指令无效,默认动作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGINT

public const SIGINT: Int32

功能:终端中断字符,默认动作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGIO

public const SIGIO: Int32

功能:异步 IO,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGIOT

public const SIGIOT: Int32

功能:硬件故障,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGKILL

public const SIGKILL: Int32

功能:终止,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGPIPE

public const SIGPIPE: Int32

功能:写入未读进程的管道,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGPROF

public const SIGPROF: Int32

功能:摘要超时,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGPWR

public const SIGPWR: Int32

功能:电源故障或重启,系统调用无效,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGQUIT

public const SIGQUIT: Int32

功能:终端退出字符,默认动作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGSEGV

public const SIGSEGV: Int32

功能:内存引用无效,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGSTKFLT

public const SIGSTKFLT: Int32

功能:协处理器堆栈故障,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGSTOP

public const SIGSTOP: Int32

功能:停止,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGTERM

public const SIGTERM: Int32

功能:终止,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGTRAP

public const SIGTRAP: Int32

功能:硬件故障,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGTSTP

public const SIGTSTP: Int32

功能:终端停止符号,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGTTIN

public const SIGTTIN: Int32

功能:后台读取控件 tty,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGTTOU

public const SIGTTOU: Int32

功能:后台写控制 tty,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGURG

public const SIGURG: Int32

功能:紧急情况(套接字),忽略默认操作,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGUSR1

public const SIGUSR1: Int32

功能:用户定义的信号,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGUSR2

public const SIGUSR2: Int32

功能:用户定义的信号,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGVTALRM

public const SIGVTALRM: Int32

功能:虚拟时间警报,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGWINCH

public const SIGWINCH: Int32

功能:终端窗口大小更改,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGXCPU

public const SIGXCPU: Int32

功能:CPU 占用率超过上限,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const SIGXFSZ

public const SIGXFSZ: Int32

功能:文件长度超过上限,默认操作终止,适用函数 killkillpg,所属函数参数 sig

类型:Int32

const S_IFBLK

public const S_IFBLK: UInt32

功能:文件类型为块设备,适用函数 isType, 所属函数参数 mode

类型:UInt32

const S_IFCHR

public const S_IFCHR: UInt32

功能:文件类型为字符设备,适用函数 isType, 所属函数参数 mode

类型:UInt32

const S_IFDIR

public const S_IFDIR: UInt32

功能:文件类型为目录,适用函数 isType, 所属函数参数 mode

类型:UInt32

const S_IFIFO

public const S_IFIFO: UInt32

功能:文件类型为 FIFO 文件,适用函数 isType, 所属函数参数 mode

类型:UInt32

const S_IFLNK

public const S_IFLNK: UInt32

功能:文件类型为软连接,适用函数 isType, 所属函数参数 mode

类型:UInt32

const S_IFREG

public const S_IFREG: UInt32

功能:文件类型为一般文件,适用函数 isType, 所属函数参数 mode

类型:UInt32

const S_IFSOCK

public const S_IFSOCK: UInt32

功能:文件类型为套接字文件,适用函数 isType, 所属函数参数 mode

类型:UInt32

const S_IRGRP

public const S_IRGRP: UInt32

功能:表示文件用户组具有读权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

类型:UInt32

const S_IROTH

public const S_IROTH: UInt32

功能:表示其他用户对文件具有读权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

类型:UInt32

const S_IRUSR

public const S_IRUSR: UInt32

功能:表示文件所有者具有读权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

类型:UInt32

const S_IRWXG

public const S_IRWXG: UInt32

功能:表示文件用户组具有读、写、执行权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

类型:UInt32

const S_IRWXO

public const S_IRWXO: UInt32

功能:表示其他用户对文件具有读、写和执行权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

类型:UInt32

const S_IRWXU

public const S_IRWXU: UInt32

功能:表示文件所有者具有读、写和执行权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

类型:UInt32

const S_IWGRP

public const S_IWGRP: UInt32

功能:表示文件用户组具有写权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

类型:UInt32

const S_IWOTH

public const S_IWOTH: UInt32

功能:表示其他用户对文件具有写权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

类型:UInt32

const S_IWUSR

public const S_IWUSR: UInt32

功能:表示文件所有者具有写权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

类型:UInt32

const S_IXGRP

public const S_IXGRP: UInt32

功能:表示文件用户组具有执行权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

类型:UInt32

const S_IXOTH

public const S_IXOTH: UInt32

功能:表示其他用户对文件具有执行权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

类型:UInt32

const S_IXUSR

public const S_IXUSR: UInt32

功能:表示文件所有者具有执行权限,适用函数 open,open64,openat,openat64,chmod(mode),fchmod(mode),fchmodat(mode),creat, 所属函数参数 flag

const W_OK

public const W_OK: Int32

功能:测试文件写权限,适用函数 accessfaccessat,所属函数参数 mode

类型:UInt32

const X_OK

public const X_OK: Int32

功能:测试文件执行权限,适用函数 accessfaccessat,所属函数参数 mode

类型:Int32

函数

func open(String, Int32)

public func `open`(path: String, oflag: Int32): Int32

功能:打开文件并为其返回新的文件描述符,或在失败时返回 -1

说明:

  • 当文件打开方式参数 oflag 设置为 O_CREAT 时,可以通过参数设置文件权限。
  • O_RDONLYO_RDWRO_WRONLY 作为 oflag 取值为互斥关系,但可以与其他操作标识一起使用,如 O_APPEND

参数:

  • path: String - 文件路径。
  • oflag: Int32 - 文件打开的方式。

返回值:

  • Int32 - 返回新的文件描述符,执行失败时返回 -1

异常:

func open(String, Int32, UInt32)

public func `open`(path: String, oflag: Int32, flag: UInt32): Int32

功能:打开文件并为其返回新的文件描述符,或在失败时返回 -1。path 代表文件路径,oflag 代表文件打开的方式,其中 O_RDONLYO_RDWRO_WRONLY 作为 oflag 取值为互斥关系,但可以与其他操作标识一起使用,如 O_APPEND 操作。

说明:

  • 当文件打开方式参数 oflag 设置为 O_CREAT 时,可以通过参数设置文件权限。
  • O_RDONLYO_RDWRO_WRONLY 作为 oflag 取值为互斥关系,但可以与其他操作标识一起使用,如 O_APPEND

参数:

  • path: String - 文件路径。
  • oflag: Int32 - 文件打开的方式。
  • flag: UInt32 - 如果 oflag 设置了 O_CREAT 并且需要创建新文件,则 flag 参数标识对新文件的权限,否则 flag 不改变文件权限。

返回值:

  • Int32 - 返回新的文件描述符,执行失败时返回 -1

异常:

func access(String, Int32)

public func access(path: String, mode: Int32): Int32

功能:判断某个文件是否具有某种权限,具有返回 0,否则返回 -1

说明:

  • mode 为指定权限,传入类型 R_OKW_OKX_OKF_OK

参数:

  • path: String - 文件路径。
  • mode: Int32 - 待检查的权限。

返回值:

  • Int32 - 文件具有待检查的权限返回 0,否则返回 -1

异常:

func chdir(String)

public func chdir(path: String): Int32

功能:通过指定路径的方式,更改调用进程的当前工作目录。

参数:

  • path: String - 改变后的路径。

返回值:

  • Int32 - 设置成功,返回 0,设置失败, 返回 -1

func chmod(String, UInt32)

public func chmod(path: String, mode: UInt32): Int32

功能:修改文件访问权限。

说明:

  • Windows 环境下,所有文件和目录都是可读的,chmod() 不能更改文件的可读权限;
  • Windows 环境下,文件的可执行权限通过文件扩展名设置,所有目录都是可执行的,chmod() 不能更改文件和目录的可执行权限。

参数:

  • path: String - 文件路径。
  • mode: UInt32 - 要修改的权限。

返回值:

  • Int32 - 操作成功时返回 0,失败时返回 -1。当 mode 为非法参数时,chmod 会忽略该参数,返回 0

异常:

func chown(String, UInt32, UInt32)

public func chown(path: String, owner: UInt32, group: UInt32): Int32

功能:修改文件所有者和文件所有者所属组。

参数:

  • path: String - 文件路径。
  • owner: UInt32 - 所有者 uid
  • group: UInt32 - 指定 gid 参数。

返回值:

  • Int32 - 操作成功时返回 0,失败时返回 -1

异常:

func close(Int32)

public func close(fd: Int32): Int32

功能:关闭文件,close 将会触发数据写回磁盘,并释放文件占用的资源。

参数:

  • fd: Int32 - 文件描述符。

返回值:

  • Int32 - 成功时返回 0,失败时返回 -1

func creat(String, UInt32)

public func creat(path: String, flag: UInt32): Int32

功能:创建文件并为其返回文件描述符,或在失败时返回 -1

参数:

  • path: String - 文件路径。
  • flag: UInt32 - 创建文件的权限。

返回值:

  • Int32 - 返回文件描述符,执行失败时返回 -1

异常:

func dup(Int32)

public func dup(fd: Int32): Int32

功能:用于复制旧 fd 参数指定的文件描述符并返回。此新文件描述符和旧的参数 fd 引用同一文件,共享文件各种状态。共享所有的锁定、读写位置和各项权限或标志等。

参数:

  • fd: Int32 - 文件描述符。

返回值:

  • Int32 - 返回最小且未使用的文件描述符,执行失败时返回 -1

func dup2(Int32, Int32)

public func dup2(fd: Int32, fd2: Int32): Int32

功能:用于复制 oldfd 参数指定的文件描述符,并将其返回到 newfd 参数。如果参数 newfd 是打开的文件描述符,则 newfd 指定的文件将首先关闭。

参数:

  • fd: Int32 - oldfd 参数指定的文件描述符。
  • fd2: Int32 - newfd 参数指定的文件描述符。

返回值:

  • Int32 - fd2 文件描述符。

func faccessat(Int32, String, Int32, Int32)

public func faccessat(fd: Int32, path: String, mode: Int32, flag: Int32): Int32

功能:判断 fd 对应的文件是否具有某种权限,具有返回 0,否则返回 -1

说明:

  • mode 为指定权限,传入类型 R_OKW_OKX_OKF_OK

参数:

  • fd: Int32 - 文件描述符。
  • path: String - 文件路径。
  • mode: Int32 - 待检查的权限。
  • flag: Int32 - 将以下一个或多个值按位或运算获取。(512)使用有效的用户和组 ID 执行访问检查,默认情况下使用有效 ID(256) 如果路径名是符号链接,不会取消引用而是返回有关链接本身信息。

返回值:

  • Int32 - 文件具有待检查的权限返回 0,否则返回 -1

异常:

func fchdir(Int32)

public func fchdir(fd: Int32): Int32

功能:通过指定文件路径的描述符,更改调用进程的当前工作目录。

参数:

  • fd: Int32 - 改变后的文件路径的描述符

返回值:

  • Int32 - 设置成功,返回 0,设置失败, 返回 -1

func fchmod(Int32, UInt32)

public func fchmod(fd: Int32, mode: UInt32): Int32

功能:修改文件描述符对应的文件访问权限。

参数:

  • fd: Int32 - 文件描述符。
  • mode: UInt32 - 要修改的权限。

返回值:

  • Int32 - 操作成功时返回 0,失败时返回 -1

异常:

func fchmodat(Int32, String, UInt32, Int32)

public func fchmodat(fd: Int32, path: String, mode: UInt32, flag: Int32): Int32

功能:修改文件描述符对应的文件访问权限。

说明:

  • path 为相对路径且 fd 为特殊值 AT_FDCWD 时,则路径将相对于调用进程的当前工作目录。
  • path 为相对路径且 fdAT_FDCWD 时,则路径将相对于 fd 引用的文件所属目录。
  • path 为绝对路径时 fd 参数将被忽略。

参数:

  • fd: Int32 - 文件描述符。
  • path: String - 文件路径。
  • mode: UInt32 - 要修改的权限。
  • flag: Int32 - 取值可为 0,或 (256) 如果路径名是符号链接,不会取消引用它,而是返回有关链接本身的信息。

返回值:

  • Int32 - 操作成功时返回 0,失败时返回 -1

异常:

func fchown(Int32, UInt32, UInt32)

public func fchown(fd: Int32, owner: UInt32, group: UInt32): Int32

功能:修改 fd 对应的文件所有者和文件所有者所属组。

参数:

  • fd: Int32 - 文件描述符。
  • owner: UInt32 - 所有者 uid
  • group: UInt32 - 指定 gid 参数。

返回值:

  • Int32 - 操作成功时返回 0,失败时返回 -1

func fchownat(Int32, String, UInt32, UInt32, Int32)

public func fchownat(fd: Int32, path: String, owner: UInt32, group: UInt32, flag: Int32): Int32

功能:修改文件描述符对应的文件所有者和文件所有者所属组。

说明:

  • path 为相对路径且 fd 为特殊值 AT_FDCWD 时,则路径将相对于调用进程的当前工作目录。
  • path 为相对路径且 fdAT_FDCWD 时,则路径将相对于 fd 引用的文件所属目录。
  • path 为绝对路径时 fd 参数将被忽略。

参数:

  • fd: Int32 - 文件描述符。
  • path: String - 文件路径。
  • owner: UInt32 - 所有者 uid
  • group: UInt32 - 指定 gid 参数。
  • flag: Int32 - 取值可为 0,或 (256) 如果路径名是符号链接,不会取消引用它,而是返回有关链接本身的信息。

返回值:

  • Int32 - 操作成功时返回 0,失败时返回 -1

异常:

func getcwd()

public func getcwd(): String

功能:获取当前执行进程工作目录的绝对路径。

返回值:

  • String - 操作成功,返回包含路径信息的字符串,操作失败则返回空字符串。

func getgid()

public func getgid(): UInt32

功能:获取用户组 ID

返回值:

  • UInt32 - 当前用户组 ID

func getgroups(Int32, CPointer<UInt32>)

public unsafe func getgroups(size: Int32, gidArray: CPointer<UInt32>): Int32

功能:获取当前用户所属组的代码。

说明:

  • 如果 gidArray 参数大小的值为零,则函数仅返回表示用户所属的组数,不会向 gidArray 中放入 gid

参数:

  • size: Int32 - gidArray 可以容纳的 gid 的数量。
  • gidArray: CPointer<UInt32> - 存放 gid 信息。

返回值:

  • Int32 - 执行成功,返回组代码,执行失败, 返回 -1

func gethostname()

public func gethostname(): String

功能:获取主机名称,此名称通常是 TCP/IP 网络上主机的名称。

返回值:

  • String - 获取到的主机的名称字符串, 获取失败则返回空字符串。

func getlogin()

public func getlogin(): String

功能:获取当前登录名。

返回值:

  • String - 操作成功时返回登录名,失败时返回空字串。

func getos()

public func getos(): String

功能:从 /proc/version 文件中获取 Linux 系统的信息。例如: Linux version 4.15.0-142-generic (buildd@lgw01-amd64-036) (gcc version 7.5.0 (Ubuntu 7.5.0-3ubuntu1~18.04)) #146-Ubuntu SMP Tue Apr 13 01:11:19 UTC 2021

返回值:

  • String - 获取到的 Linux 系统的信息字符串。

func getpgid(Int32)

public func getpgid(pid: Int32): Int32

功能:获取 pid 指定的进程的 PGID,如果 pid 为零,返回调用进程的进程 ID

参数:

  • pid: Int32 - 目标进程 ID

返回值:

  • Int32 - 执行成功,返回进程组 ID,执行失败, 返回 -1

func getpgrp()

public func getpgrp(): Int32

功能:获取调用进程的父进程 ID

返回值:

  • Int32 - 返回调用进程的父进程 ID

func getpid()

public func getpid(): Int32

功能:获取调用进程的进程 ID(PID)

返回值:

  • Int32 - 返回调用进程的进程 ID(PID)

func getppid()

public func getppid(): Int32

功能:获取调用进程的父进程 ID

返回值:

  • Int32 - 返回调用进程的父进程 ID

func getuid()

public func getuid(): UInt32

功能:获取调用进程的真实用户 ID

返回值:

  • UInt32 - 当前真实用户 ID

func isBlk(String)

public func isBlk(path: String): Bool

功能:检查传入对象是否为块设备,并返回布尔类型。

参数:

  • path: String - 文件路径。

返回值:

  • Bool - 如果是,返回 true,否则返回 false

func isChr(String)

public func isChr(path: String): Bool

功能:检查传入对象是否为字符设备,返回布尔类型。

参数:

  • path: String - 文件路径。

返回值:

  • Bool - 如果是,返回 true,否则返回 false

func isDir(String)

public func isDir(path: String): Bool

功能:检查传入对象是否为文件夹,返回布尔类型。

参数:

  • path: String - 文件路径。

返回值:

  • Bool - 如果是,返回 true,否则返回 false

func isFIFO(String)

public func isFIFO(path: String): Bool

功能:检查传入对象是否为 FIFO 文件,返回布尔类型。

参数:

  • path: String - 文件路径。

返回值:

  • Bool - 如果是,返回 true,否则返回 false

func isLnk(String)

public func isLnk(path: String): Bool

功能:检查传入对象是否为软链路,返回布尔类型。

参数:

  • path: String - 文件路径。

返回值:

  • Bool - 如果是,返回 true,否则返回 false

func isReg(String)

public func isReg(path: String): Bool

功能:检查传入对象是否为普通文件,返回布尔类型。

参数:

  • path: String - 文件路径。

返回值:

  • Bool - 如果是,返回 true,否则返回 false

func isSock(String)

public func isSock(path: String): Bool

功能:检查传入对象是否为套接字文件,返回布尔类型。

参数:

  • path: String - 文件路径。

返回值:

  • Bool - 如果是,返回 true,否则返回 false

func isType(String, UInt32)

public func isType(path: String, mode: UInt32): Bool

功能:检查文件是否为指定模式的文件。如果是,返回 ture,否则返回 false。根据模式的不同值确定不同的类型。

参数:

  • path: String - 文件路径。
  • mode: UInt32 - 判断参数。

返回值:

  • Bool - 如果是指定模式的文件,返回 true,否则返回 false

func isatty(Int32)

public func isatty(fd: Int32): Bool

功能:用于测试文件描述符是否引用终端,成功时返回 true,否则返回 false

参数:

  • fd: Int32 - 文件描述符。

返回值:

  • Bool - 操作成功时返回 true,否则返回 false

func kill(Int32, Int32)

public func kill(pid: Int32, sig: Int32): Int32

功能:系统调用可用于向任何进程组或进程发送任何信号。

说明:

  • 如果 pid 大于 0,则信号 sig 将发送到 pid 对应的进程。
  • 如果 pid 等于 0,然后 sig 被发送到调用进程的进程组中的每个进程。
  • 如果 pid 等于 -1,则 sig 被发送到调用进程有权发送信号的每个进程。
  • 如果 pid 小于 -1,则将 sig 发送到 ID-pid 的进程组中的每个进程。

参数:

  • pid: Int32 - 进程 ID
  • sig: Int32 - 信号 ID

返回值:

  • Int32 - 操作成功时返回 0,否则返回 -1

func killpg(Int32, Int32)

public func killpg(pgid: Int32, sig: Int32): Int32

功能:将信号 sig 发送到进程组 pgrp,如果 pgrp0,则 killpg() 将信号发送到调用进程的进程组。

参数:

  • pgid: Int32 - 组 ID
  • sig: Int32 - 信号 ID

返回值:

  • Int32 - 操作成功时返回 0,否则返回 -1

func lchown(String, UInt32, UInt32)

public func lchown(path: String, owner: UInt32, group: UInt32): Int32

功能:修改文件链接本身所有者和所有者所属组。

参数:

  • path: String - 字符串类型的文件路径。
  • owner: UInt32 - 所有者 uid
  • group: UInt32 - 指定 gid 参数。

返回值:

  • Int32 - 操作成功时返回 0,失败时返回 -1

异常:

func link(String, String)

public func link(path: String, newpath: String): Int32

功能:为存在的文件创建链接,一个文件可以有多个指向其 i-node 的目录条目。

参数:

  • path: String - 文件路径。
  • newpath: String - 其他文件路径。

返回值:

  • Int32 - 成功返回 0,错误返回 -1

异常:

func linkat(Int32, String, Int32, String, Int32)

public func linkat(fd: Int32, path: String, nfd: Int32, newPath: String, lflag: Int32): Int32

功能:创建相对于目录文件描述符的文件链接。

说明:

  • path 为相对路径且 fd 为特殊值 AT_FDCWD 时,则路径将相对于调用进程的当前工作目录。
  • path 为相对路径且 fdAT_FDCWD 时,则路径将相对于 fd 引用的文件所属目录。
  • path 为绝对路径时 fd 参数将被忽略。
  • newPath 的场景与 path 相同,只是当 newPath 为相对路径时是相对于 nfd 引用的文件所属目录。

参数:

  • fd: Int32 - 文件描述符。
  • path: String - 文件路径。
  • nfd: Int32 - 其他文件描述符。
  • newPath: String - 其他文件路径,如果 newpath 存在,则不会覆盖。
  • lflag: Int32 - AT_EMPTY_PATHAT_SYMLINK_FOLLOW0

返回值:

  • Int32 - 成功返回 0,错误返回 -1

异常:

func lseek(Int32, Int64, Int32)

public func lseek(fd: Int32, offset: Int64, whence: Int32): Int64

功能:当文件进行读或写时,读或写位置相应增加。本函数用于控制文件的读或写位置。调用成功时,返回当前读写位置,即从文件开头开始的字节数。如果发生错误,返回 -1。

参数:

  • fd: Int32 - 打开文件的文件描述符。
  • offset: Int64 - 偏移量。
  • whence: Int32 - 表示控制模式。

返回值:

  • Int64 - 调用成功时,返回当前读写位置,即从文件开头开始的字节数。

func nice(Int32)

public func nice(inc: Int32): Int32

功能:更改当前线程的优先级。

说明:

  • 只有超级用户才能使用负的 inc 值,表示优先级高,进程执行得更快。 inc 代表当前进程的优先级,取值的范围是 +19(低优先级)到 -20
  • 成功时返回新值,失败时返回 -1inc 在值大于 19 时,返回最大值 19

参数:

  • inc: Int32 - 当前进程的优先级, 值的范围是 +19(低优先级)到 -20

返回值:

  • Int32 - 返回新优先级值。

func open64(String, Int32)

public func open64(path: String, oflag: Int32): Int32

功能:打开文件并为其返回新的文件描述符,或在失败时返回 -1

说明:

  • 当文件打开方式参数 oflag 设置为 O_CREAT 时,可以通过参数设置文件权限。
  • O_RDONLYO_RDWRO_WRONLY 作为 oflag 取值为互斥关系,但可以与其他操作标识一起使用,如 O_APPEND

参数:

  • path: String - 文件路径。
  • oflag: Int32 - 文件打开的方式。

返回值:

  • Int32 - 返回新的文件描述符,执行失败时返回 -1

异常:

func open64(String, Int32, UInt32)

public func open64(path: String, oflag: Int32, flag: UInt32): Int32

功能:打开文件并为其返回新的文件描述符,或在失败时返回 -1

说明:

  • 当文件打开方式参数 oflag 设置为 O_CREAT 时,可以通过参数设置文件权限。
  • O_RDONLYO_RDWRO_WRONLY 作为 oflag 取值为互斥关系,但可以与其他操作标识一起使用,如 O_APPEND

参数:

  • path: String - 文件路径。
  • oflag: Int32 - 文件打开的方式。
  • flag: UInt32 - 如果 oflag 设置了 O_CREAT 并且需要创建新文件,则 flag 参数标识对新文件的权限,否则 flag 不改变文件权限。

返回值:

  • Int32 - 返回新的文件描述符,执行失败时返回 -1

异常:

func openat(Int32, String, Int32)

public func openat(fd: Int32, path: String, oflag: Int32): Int32

功能:打开文件并为其返回新的文件描述符,或在失败时返回 -1

说明:

  • 当文件打开方式参数 oflag 设置为 O_CREAT 时,可以通过参数设置文件权限。
  • O_RDONLYO_RDWRO_WRONLY 作为 oflag 取值为互斥关系,但可以与其他操作标识一起使用,如 O_APPEND

参数:

  • fd: Int32 - 路径的文件描述符。
  • path: String - 文件路径。
  • oflag: Int32 - 文件打开的方式。

返回值:

  • Int32 - 返回新的文件描述符,执行失败时返回 -1

异常:

func openat(Int32, String, Int32, UInt32)

public func openat(fd: Int32, path: String, oflag: Int32, flag: UInt32): Int32

功能:打开文件并为其返回新的文件描述符,或在失败时返回 -1

说明:

  • 当文件打开方式参数 oflag 设置为 O_CREAT 时,可以通过参数设置文件权限。
  • O_RDONLYO_RDWRO_WRONLY 作为 oflag 取值为互斥关系,但可以与其他操作标识一起使用,如 O_APPEND

参数:

  • fd: Int32 - 路径的文件描述符。
  • path: String - 文件路径。
  • oflag: Int32 - 文件打开的方式。
  • flag: UInt32 - 如果 oflag 设置了 O_CREAT 并且需要创建新文件,则 flag 参数标识对新文件的权限,否则 flag 不改变文件权限。

返回值:

  • Int32 - 返回新的文件描述符,执行失败时返回 -1

异常:

func openat64(Int32, String, Int32)

public func openat64(fd: Int32, path: String, oflag: Int32): Int32

功能:打开文件并为其返回新的文件描述符,或在失败时返回 -1

说明:

  • 当文件打开方式参数 oflag 设置为 O_CREAT 时,可以通过参数设置文件权限。
  • O_RDONLYO_RDWRO_WRONLY 作为 oflag 取值为互斥关系,但可以与其他操作标识一起使用,如 O_APPEND

参数:

  • fd: Int32 - 路径的文件描述符。
  • path: String - 文件路径。
  • oflag: Int32 - 文件打开的方式。

返回值:

  • Int32 - 返回新的文件描述符,执行失败时返回 -1

异常:

func openat64(Int32, String, Int32, UInt32)

public func openat64(fd: Int32, path: String, oflag: Int32, flag: UInt32): Int32

功能:打开文件并为其返回新的文件描述符,或在失败时返回 -1

说明:

  • 当文件打开方式参数 oflag 设置为 O_CREAT 时,可以通过参数设置文件权限。
  • O_RDONLYO_RDWRO_WRONLY 作为 oflag 取值为互斥关系,但可以与其他操作标识一起使用,如 O_APPEND

参数:

  • fd: Int32 - 路径的文件描述符。
  • path: String - 文件路径。
  • oflag: Int32 - 文件打开的方式。
  • flag: UInt32 - 如果 oflag 设置了 O_CREAT 并且需要创建新文件,则 flag 参数标识对新文件的权限,否则 flag 不改变文件权限。

返回值:

  • Int32 - 返回新的文件描述符,执行失败时返回 -1

异常:

func pread(Int32, CPointer<UInt8>, UIntNative, Int32)

public unsafe func pread(fd: Int32, buffer: CPointer<UInt8>, nbyte: UIntNative, offset: Int32): IntNative

功能:将 fd 指向的文件的 nbyte 字节传输到 buffer 指向的内存中。如果 nbyte0,则函数无效果,并返回 0。返回值是实际读取的字节数。返回值为 0 表示到达文件末尾或无法读取数据。此外,文件的读写位置随着读取字节的变化而变化。

说明:

  • 建议 nbyte 的大小与 buffer 的大小相同,且 buffer 的大小小于或等于 150000 字节。

参数:

  • fd: Int32 - 待读取文件的文件描述符。
  • buffer: CPointer<UInt8> - 缓冲区容器。
  • nbyte: UIntNative - 读取字节数,建议采用 buffer.size
  • offset: Int32 - 读取位置的偏移量。

返回值:

  • IntNative - 返回实际读取字节数,读取无效时返回 -1

func pwrite(Int32, CPointer<UInt8>, UIntNative, Int32)

public unsafe func pwrite(fd: Int32, buffer: CPointer<UInt8>, nbyte: UIntNative, offset: Int32): IntNative

功能:将 buffer 指向的内存中 nbyte 字节从指定偏移位置开始写入到 fd 指向的文件。指定文件的读写位置会随之移动。

说明:

  • 建议 nbyte 的大小与 buffer 的大小相同,且 buffer 的大小小于或等于 150000 字节。

参数:

  • fd: Int32 - 待读取文件的文件描述符。
  • buffer: CPointer<UInt8> - 缓冲区容器。
  • nbyte: UIntNative - 读取字节数,建议采用 buffer.size
  • offset: Int32 - 读取位置的偏移量。

返回值:

  • IntNative - 返回实际写入数,执行失败时返回 -1

func read(Int32, CPointer<UInt8>, UIntNative)

public unsafe func read(fd: Int32, buffer: CPointer<UInt8>, nbyte: UIntNative): IntNative

功能:将 fd 指向的文件的 nbyte 字节传输到 buffer 指向的内存中。如果 nbyte0,则函数无效果,并返回 0。返回值是实际读取的字节数。返回值为 0 表示到达文件末尾或无法读取数据。此外,文件的读写位置随着读取字节的变化而变化。

说明:

  • 建议 nbyte 的大小与 buffer 的大小相同,且 buffer 的大小小于或等于 150000 字节。

参数:

  • fd: Int32 - 待读取文件的文件描述符。
  • buffer: CPointer<UInt8> - 缓冲区容器。
  • nbyte: UIntNative - 读取字节数,建议采用 buffer.size

返回值:

  • IntNative - 返回实际读取字节数,读取无效时返回 -1

func remove(String)

public func remove(path: String): Int32

功能:删除文件或目录。

说明:

  • 对于文件,remove() 等同于 unlink()。
  • 对于目录,remove() 等同于 rmdir()。

参数:

  • path: String - 文件路径。

返回值:

  • Int32 - 成功返回 0,错误返回 -1

异常:

func rename(String, String)

public func rename(oldName: String, newName: String): Int32

功能:重命名文件,如果需要将会移动文件所在目录。文件的任何其他硬链接不受影响。旧路径打开的文件描述符也不受影响。

说明:

各种限制将决定重命名操作是否成功,具体场景如下:

  • 如果 newName 已经存在,它将被原子替换,这样另一个尝试访问 newName 的进程就不会发现它丢失,但是可能会有一个窗口,其中旧路径和新路径都引用要重命名的文件。
  • 如果旧路径和新路径是引用同一文件的现有硬链接,则重命名不做任何操作,并返回成功状态。
  • 如果 newName 存在,但操作因某种原因失败,则重命名保证保留 newName 的实例。
  • oldName 可以指定目录。在这种情况下,newName 必须不存在,或者它必须指定空目录。
  • 如果旧路径引用符号链接,则链接将重命名;如果新路径引用符号链接,则链接将被覆盖。

参数:

  • oldName: String - 文件名(含路径)。
  • newName: String - 文件名(含路径)。

返回值:

  • Int32 - 成功返回 0,错误返回 -1

异常:

func renameat(Int32, String, Int32, String)

public func renameat(oldfd: Int32, oldName: String, newfd: Int32, newName: String): Int32

功能:重命名文件,如果需要将会移动文件所在目录。

说明:

renameat() 与 rename() 处理相同,此处仅描述两者差异点:

  • oldName 为相对路径且 oldfd 为特殊值 AT_FDCWD 时,则路径将相对于调用进程的当前工作目录。
  • oldName 为相对路径且 oldfdAT_FDCWD 时,则路径将相对于 oldfd 引用的文件所属目录。
  • oldName 为绝对路径时 oldfd 参数将被忽略。
  • newName 的场景与 oldName 相同,只是当 newName 为相对路径时是相对于 newfd 引用的文件所属目录。

参数:

  • oldfd: Int32 - 文件描述符。
  • oldName: String - 文件名。
  • newName: String - 文件名。
  • newfd: Int32 - 文件描述符。

返回值:

  • Int32 - 成功返回 0,错误返回 -1

异常:

func setgid(UInt32)

public func setgid(id: UInt32): Int32

功能:设置调用进程的有效组 ID,需要适当的权限。

参数:

  • id: UInt32 - 调用进程的有效组 ID 号。

返回值:

  • Int32 - 设置成功,返回 0,设置失败, 返回 -1

func sethostname(String)

public func sethostname(buf: String): Int32

功能:设置主机名,仅超级用户可以调用。

参数:

  • buf: String - 需要设置的主机名。

返回值:

  • Int32 - 设置成功,返回 0,设置失败, 返回 -1

异常:

func setpgid(Int32, Int32)

public func setpgid(pid: Int32, pgrp: Int32): Int32

功能:此函数将参数 pid 指定的组 ID 设置为参数 pgrp 指定的组 ID。 如果 pid0,则使用当前进程的组 ID

参数:

  • pid: Int32 - 进程 ID
  • pgrp: Int32 - 进程组 ID

返回值:

  • Int32 - 执行成功,返回组 ID,执行失败, 返回 -1

func setpgrp()

public func setpgrp(): Int32

功能:将当前进程所属的组 ID 设置为当前进程的进程 ID,此函数等同于调用 setpgid(0, 0)。

返回值:

  • Int32 - 执行成功,返回当前进程的组 ID,执行失败, 返回 -1

func setuid(UInt32)

public func setuid(id: UInt32): Int32

功能:设置调用进程的有效用户 ID,需要适当的权限。

参数:

  • id: UInt32 - 调用进程的有效用户 ID 号。

返回值:

  • Int32 - 设置成功,返回 0,设置失败, 返回 -1

func symlink(String, String)

public func symlink(path: String, symPath: String): Int32

功能:创建一个名为 symPath 链接到 path 所指定的文件。

说明:

  • 符号链接在运行时被解释为链接的内容已被替换到要查找文件或目录的路径中。
  • 符号链接可能包含..路径组件,这些组件(如果在链接的开头使用)引用链接所在目录的父目录。
  • 符号链接(也称为软链接)可以指向现有文件或不存在的文件,后者被称为悬空链接。
  • 符号链接的权限是不相关的,在跟踪链接时,所有权将被忽略,但当请求删除或重命名链接并且链接位于设置了粘滞位的目录中时,所有权将被检查。
  • 如果 symPath 已存在,则不会被覆盖。

参数:

  • path: String - 文件路径。
  • symPath: String - 链接文件路径。

返回值:

  • Int32 - 成功返回 0,错误返回 -1

异常:

func symlinkat(String, Int32, String)

public func symlinkat(path: String, fd: Int32, symPath: String): Int32

功能:创建一个名为 symPath 链接到 pathfd 所指定的文件。

说明:

  • symPath 为相对路径且 fd 为特殊值 AT_FDCWD 时,则路径将相对于调用进程的当前工作目录。
  • symPath 为相对路径且 fdAT_FDCWD 时,则路径将相对于 fd 引用的文件所属目录。
  • symPath 为绝对路径时 fd 参数将被忽略。

参数:

  • path: String - 文件路径。
  • fd: Int32 - 文件描述符。
  • symPath: String - 链接文件路径。

返回值:

  • Int32 - 成功返回 0,错误返回 -1

异常:

func ttyname(Int32)

public func ttyname(fd: Int32): String

功能:返回终端名称。

参数:

  • fd: Int32 - 文件描述符。

返回值:

  • String - 操作成功时返回路径名,失败时,返回 NULL

func umask(UInt32)

public func umask(cmask: UInt32): UInt32

功能:设置权限掩码。

参数:

  • cmask: UInt32 - 文件权限参数。

返回值:

  • UInt32 - 返回文件上一个掩码的值。

func unlink(String)

public func unlink(path: String): Int32

功能:从文件系统中删除文件。

说明:

  • 如果 path 是指向文件的最后一个链接,并且没有进程打开该文件,则该文件将被删除,它使用的空间可供重复使用。
  • 如果 path 是指向文件的最后一个链接,但仍然有进程打开该文件,该文件将一直存在,直到引用它的最后一个文件描述符关闭。
  • 如果 path 引用了符号链接,则该链接将被删除。
  • 如果 path 引用了套接字、FIFO 或设备,则该文件将被删除,但打开对象的进程可能会继续使用它。

参数:

  • path: String - 文件路径。

返回值:

  • Int32 - 成功返回 0,错误返回 -1

异常:

func unlinkat(Int32, String, Int32)

public func unlinkat(fd: Int32, path: String, ulflag: Int32): Int32

功能:从文件系统中删除文件。

说明:

该函数系统调用的操作方式与 unlink 函数完全相同,但此处描述的差异除外:

  • path 为相对路径且 fd 为特殊值 AT_FDCWD 时,则路径将相对于调用进程的当前工作目录。
  • path 为相对路径且 fdAT_FDCWD 时,则路径将相对于 fd 引用的文件所属目录。
  • path 为绝对路径时 fd 参数将被忽略。

参数:

  • fd: Int32 - 文件描述符。
  • path: String - 文件路径。
  • ulflag: Int32 - 可以指定为 0,或者可以设置为控制 unlinkat() 操作的标志值按位或运算。标志值当前取值仅支持 AT_REMOVEDIR

返回值:

  • Int32 - 成功返回 0,错误返回 -1

异常:

func write(Int32, CPointer<UInt8>, UIntNative)

public unsafe func write(fd: Int32, buffer: CPointer<UInt8>, nbyte: UIntNative): IntNative

功能:将 buffer 指向的内存中 nbyte 字节写入到 fd 指向的文件。指定文件的读写位置会随之移动。

说明:

建议 nbyte 的大小与 buffer 的大小相同,且 buffer 的大小小于或等于 150000 字节。

参数:

  • fd: Int32 - 待写入文件的文件描述符。
  • buffer: CPointer<UInt8> - 缓冲区容器。
  • nbyte: UIntNative - 读取字节数,建议采用 buffer.size

返回值:

  • IntNative - 返回实际读取字节数,读取无效时返回 -1

文件内容相关操作

下面是文件内容相关操作示例。

代码如下:

import std.posix.*

main(): Int64 {
    var fd = `open`("textcase.txt", O_RDWR | O_APPEND | O_CREAT, S_IRWXU)
    println("fd ==> ${fd}")
    close(fd)
    var fd2 = `open`("textcase.txt", O_RDWR)
    var len = lseek(fd2, 0, SEEK_END)
    println("len ==> ${len}")
    close(fd2)
    var str1 = unsafe{LibC.mallocCString(" ")}
    var buf = str1.getChars()
    var fd3 = `open`("textcase.txt", O_RDWR)
    var readNum = unsafe { read(fd3, buf, 2) }
    unsafe{ LibC.free(str1)}
    println("readNum ==> ${readNum}")
    close(fd3)
    var str2 = unsafe{LibC.mallocCString("123456")}
    var buf2 = str2.getChars()

    var fd4 = `open`("textcase.txt", O_RDWR)
    var fd5 = dup(fd4)
    var writeNum = unsafe { write(fd5, buf2, UIntNative(str2.size())) }
    unsafe { LibC.free(str2)}
    println("writeNum ==> ${writeNum}")
    close(fd4)
    return 0
}

可能出现的运行结果如下:

fd ==> 3
len ==> 6
readNum ==> 2
writeNum ==> 6

文件信息相关操作

下面是文件信息相关操作示例,以下示例不支持 Windows 平台。

代码如下:

import std.posix.*

main(): Int64 {
    var result1: Bool = isType("/notdirs", S_IFDIR)
    println("result ==> ${result1}")
    var result2: Bool = isDir("/dev")
    println("result ==> ${result2}")
    var result3 = access("./oscfg.cfg", F_OK)
    println("result ==> ${result3}")
    var result4 = chmod("oscfg.cfg", UInt32(S_IXUSR))
    println("result ==> ${result4}")
    return 0
}

运行结果如下:

result ==> false
result ==> true
result ==> -1
result ==> -1

获取各类系统信息

下面是获取各类系统信息示例,以下示例不支持 Windows 平台。

代码如下:

import std.posix.*

main(): Int64 {
    /* 系统名称相关 */
    var os_info = getos()
    println("os info ==> ${os_info}")
    var hostname = gethostname()
    println("hostname ==> ${hostname}")
    var logname: String = getlogin()
    println("logname ==> ${logname}")

    /* 程序运行路径相关函数 */
    var chagePath = "/"
    var chdir_restlt = chdir(chagePath)
    println("chdir_restlt ==> ${chdir_restlt}")
    var cwd_path: String = getcwd()
    println("cwd_path ==> ${cwd_path}")

    /* 系统 id 相关函数 getpgid */
    var arr: CString = unsafe { LibC.mallocCString(" ") }
    var a: CPointer<UInt8> = arr.getChars()
    var cp: CPointer<UInt32> = CPointer<UInt32>(a)
    var getg = unsafe{ getgroups(0, cp)}
    var s: String = " "
    for (_ in 0..getg) {
        s = s + "\0"
    }
    println(getg)
    var local: UInt32 = 0
    for (temp in 0..getg) {
        unsafe { local = cp.read(Int64(temp)) }
        println("getgroups ==> ${local.toString()}")
    }
    unsafe { LibC.free(arr)}
    return 0
}

运行结果如下(根据系统不同返回结果可能不同):

Linux version 4.15.0-159-generic (buildd@lgw01-amd64-055) (gcc version 7.5.0 (Ubuntu 7.5.0-3ubuntu1~18.04)) #167-Ubuntu SMP Tue Sep 21 08:55:05 UTC 2021
hostname ==> e124e6e0fe0f
logname ==> root
chdir_restlt ==> 0
cwd_path ==> /
1
getgroups ==> 1309868064

进程相关信息操作

下面是进程相关信息操作示例,以下示例不支持 Windows 平台。

代码如下:

import std.posix.*

main(): Int64 {
    var result = nice(200)
    print("${result}")
    var result1 = kill(0, SIGCHLD)
    println(result1)
    var result2 = killpg(0, SIGURG)
    println("result ==> ${result2}")
    if (isatty(0) && isatty(1) && isatty(2)) {
            print("true01 ")
        } else {
            print("false01 ")
        }
        if (isatty(-23) || isatty(4) || isatty(455) || isatty(43332)) {
            print("true02 ")
        } else {
            println("false02")
        }
        return 0
}

运行结果如下:

190
result ==> 0
true01 false02

std.process 包

功能介绍

process 包主要提供 Process 进程操作接口,主要包括进程创建,标准流获取,进程等待,进程信息查询等。

本包提供多平台统一操控能力,目前支持 Linux 平台,macOS 平台,Windows 平台与 HarmonyOS 平台。

API 列表

类名功能
CurrentProcess此类为当前进程类,继承 Process 类,提供对当前进程操作相关功能。
Process此类为进程类,提供进程操作相关功能。
SubProcess此类为子进程类,继承 Process 类,提供对子进程操作相关功能。

枚举

枚举名功能
ProcessRedirect用于在创建进程时设置子进程标准流的重定向模式。

异常类

异常类名功能
ProcessExceptionprocess 包的异常类。

兼容性说明

class Process

成员支持平台
currentLinux Windows macOS HarmonyOS
pidLinux Windows macOS HarmonyOS
nameLinux Windows macOS HarmonyOS
commandLinux Windows macOS HarmonyOS
argumentsLinux macOS HarmonyOS
commandLineLinux macOS HarmonyOS
workingDirectoryLinux macOS HarmonyOS
environmentLinux HarmonyOS
of(Int64)Linux Windows macOS HarmonyOS
start(String, Array, Path, Map<String, String>, ProcessRedirect, ProcessRedirect, ProcessRedirect)Linux Windows macOS HarmonyOS
run(String, Array, Path, Map<String, String>, ProcessRedirect, ProcessRedirect, ProcessRedirect, Duration)Linux Windows macOS HarmonyOS
runOutput(String, Array, Path, Map<String, String>, ProcessRedirect, ProcessRedirect, ProcessRedirect)Linux Windows macOS HarmonyOS
terminate(Bool)Linux Windows macOS HarmonyOS

class CurrentProcss

成员支持平台
argumentsLinux Windows macOS HarmonyOS
homeDirectoryLinux Windows macOS
tempDirectoryLinux Windows macOS
stdInLinux Windows macOS HarmonyOS
stdOutLinux Windows macOS HarmonyOS
stdErrLinux Windows macOS HarmonyOS
atExit(() -> Unit)Linux Windows macOS HarmonyOS
exit(Int64)Linux Windows macOS HarmonyOS
getEnv(String)Linux Windows macOS HarmonyOS
removeEnv(String)Linux Windows macOS HarmonyOS
setEnv(String, String)Linux Windows macOS HarmonyOS

class SubProcess

成员支持平台
stdInLinux Windows macOS HarmonyOS
stdOutLinux Windows macOS HarmonyOS
stdErrLinux Windows macOS HarmonyOS
wait(Duration)Linux Windows macOS HarmonyOS
waitOutput()Linux Windows macOS HarmonyOS

class CurrentProcess

public class CurrentProcess <: Process

功能:此类为当前进程类,继承 Process 类,提供对当前进程操作相关功能。

说明:

提供功能具体如下:

  • 提供获取当前进程标准流(stdInstdOutstdErr)机制。
  • 提供当前进程退出注册回调函数机制。
  • 提供当前进程退出机制,允许设置退出状态码。

父类型:

prop arguments

public prop arguments: Array<String>

功能:返回当前进程参数列表,例如当前进程命令行为 a.out ab cd ef,其中 a.out 是程序名,则返回的列表包含三个元素 ab cd ef。

说明:

  • 使用 C 语言调用仓颉动态库方式时,通过 int SetCJCommandLineArgs(int argc, const char* argv[]) 设置的命令行参数,在使用当前进程的 arguments 获取时,将会被舍弃掉第一个参数。

类型:Array<String>

prop homeDirectory

public prop homeDirectory: Path

功能:获取 home 目录的路径。

类型:Path

prop stdErr

public prop stdErr: OutputStream

功能:获取当前进程标准错误流。

类型:OutputStream

prop stdIn

public prop stdIn: InputStream

功能:获取当前进程标准输入流。

类型:InputStream

prop stdOut

public prop stdOut: OutputStream

功能:获取当前进程标准输出流。

类型:OutputStream

prop tempDirectory

public prop tempDirectory: Path

功能:获取临时目录的路径。从环境变量中获取 TMPDIRTMPTEMPTEMPDIR 环境变量。如果以上值在环境变量中均不存在,则默认返回 /tmp 目录。

类型:Path

func atExit(() -> Unit)

public func atExit(callback: () -> Unit): Unit

功能:注册回调函数,当前进程退出时执行注册函数。

注意:

请不要使用C语言 atexit 函数,避免出现不可期问题。

参数:

  • callback: () ->Unit - 需要被注册回调的函数。

func exit(Int64)

public func exit(code: Int64): Nothing

功能:进程退出函数,执行到此函数直接结束当前进程,并且通过入参 code 设置返回状态码。

参数:

  • code: Int64 - 当前进程退出状态码。

func getEnv(String)

public func getEnv(k: String): Option<String>

功能:获取指定名称的环境变量值。

参数:

  • k: String - 环境变量名称。

返回值:

异常:

func removeEnv(String)

public func removeEnv(k: String): Unit

功能:通过指定环境变量名称移除环境变量。

参数:

  • k: String - 环境变量名称。

异常:

func setEnv(String, String)

public func setEnv(k: String, v: String): Unit

功能:用于设置一对环境变量。如果设置了同名环境变量,原始环境变量值将被覆盖。

参数:

  • k: String - 环境变量名称。
  • v: String - 环境变量值。

异常:

class Process

public open class Process

功能:此类为进程类,提供进程操作相关功能。

说明:

提供功能具体如下:

  • 提供获取当前进程实例的功能。
  • 提供根据进程 id 绑定进程实例的功能。
  • 提供根据输入信息创建子进程的功能。
  • 提供获取进程信息的功能。
  • 提供关闭进程的功能,允许设置是否强制关闭进程。

static prop current

public static prop current: CurrentProcess

功能:获取当前进程实例。

类型:CurrentProcess

prop arguments

public prop arguments: Array<String>

功能:获取进程参数。Windows 平台下无法在非特权 API 下获取到本属性,暂不支持获取。

类型:Array<String>

异常:

  • ProcessException - 当进程不存在或对应进程为僵尸进程,或在 Windows 平台下暂不支持场景,无法获取进程参数时,抛出异常。

prop command

public prop command: String

功能:获取进程命令。

类型:String

异常:

  • ProcessException - 当进程不存在或对应进程为僵尸进程,无法获取进程命令时,抛出异常。

prop commandLine

public prop commandLine: Array<String>

功能:获取进程命令行。Windows 平台当前进程可获取,其他场景下无法在非特权 API 下获取到本属性,暂不支持获取。

类型:Array<String>

异常:

  • ProcessException - 当进程不存在或对应进程为僵尸进程,或在 Windows 平台下暂不支持场景,无法获取进程命令行时,抛出异常。

prop environment

public prop environment: Map<String, String>

功能:获取进程环境变量。Windows 平台当前进程可获取,其他场景下无法在非特权 API 下获取到本属性,暂不支持获取。

类型:Map<String, String>

异常:

  • ProcessException - 当进程不存在或对应进程为僵尸进程,或在 Windows 平台下暂不支持场景,无法获取进程环境变量时,抛出异常。

prop name

public prop name: String

功能:获取进程名。

类型:String

异常:

  • ProcessException - 当进程不存在或对应进程为僵尸进程,无法获取进程名时,抛出异常。

prop pid

public prop pid: Int64

功能:获取进程 id

类型:Int64

prop workingDirectory

public prop workingDirectory: Path

功能:获取进程工作路径。Windows 平台当前进程可获取,其他场景下无法在非特权 API 下获取到本属性,暂不支持获取。

类型:Path

异常:

  • ProcessException - 当进程不存在或对应进程为僵尸进程,或在 Windows 平台下暂不支持场景,无法获取进程工作路径时,抛出异常。

static func of(Int64)

public static func of(pid: Int64): Process

功能:根据输入进程 id 绑定一个进程实例。

参数:

  • pid: Int64 - 进程 id

返回值:

  • Process - 返回进程 id 对应的进程实例。

异常:

static func run(String, Array<String>, ?Path, ?Map<String, String>, ProcessRedirect, ProcessRedirect,ProcessRedirect, ?Duration)

public static func run(command: String,
                      arguments: Array<String>,
                      workingDirectory!: ?Path = None,
                      environment!: ?Map<String, String> = None,
                      stdIn!: ProcessRedirect = Inherit,
                      stdOut!: ProcessRedirect = Inherit,
                      stdErr!: ProcessRedirect = Inherit,
                      timeout!: ?Duration = None): Int64

功能:根据输入参数创建并运行一个子进程,等待该子进程运行完毕并返回子进程退出状态。

注意:

  • Windows 平台上,在子进程执行完成后立即删除子进程的可执行文件可能删除失败并抛出异常,异常信息为 Access is denied,如果遇到该问题,可以在一小段延迟后重新尝试删除该文件,详细实现可参考示例。

参数:

  • command: String - 指定子进程命令,command 不允许包含空字符。
  • arguments: Array<String> - 指定子进程参数,arguments 不允许数组中字符串中包含空字符。
  • workingDirectory!: ?Path - 命名可选参数,指定子进程的工作路径,默认继承当前进程工作路径,路径必须为存在的目录且不允许为空路径或包含空字符。
  • environment!: ?Map<String, String> - 命名可选参数,指定子进程环境变量,默认继承当前进程环境变量,key 不允许字符串中包含空字符或 '=',value 不允许字符串中包含空字符。
  • stdIn!: ProcessRedirect - 命名可选参数,指定子进程重定向标准输入,默认继承当前进程标准输入。
  • stdOut!: ProcessRedirect - 命名可选参数,指定子进程重定向标准输出,默认继承当前进程标准输出。
  • stdErr!: ProcessRedirect - 命名可选参数,指定子进程重定向标准错误,默认继承当前进程标准错误。
  • timeout!: ?Duration - 命名可选参数,指定等待子进程超时时间,默认为不超时, timeout 指定为 0 或负值时表示不超时。

返回值:

  • Int64 - 返回子进程退出状态,若子进程正常退出,返回子进程退出码,若子进程被信号杀死,返回导致子进程终止的信号编号。

异常:

  • IllegalArgumentException - 当入参 command 包含空字符,或者 arguments 数组中字符串中包含空字符,或者 workingDirectory 不是存在的目录或为空路径或包含空字符,或者 environment 表中 key 字符串中包含空字符或 '=',或 value 字符串中包含空字符,或者 stdInstdOutstdErr 输入为文件模式,输入的文件已被关闭或删除时,抛出异常。
  • ProcessException - 当内存分配失败或 command 对应的命令不存在或等待超时,抛出异常。

static func runOutput(String, Array<String>, ?Path, ?Map<String, String>, ProcessRedirect, ProcessRedirect, ProcessRedirect)

public static func runOutput(command: String,
                            arguments: Array<String>,
                            workingDirectory!: ?Path = None,
                            environment!: ?Map<String, String> = None,
                            stdIn!: ProcessRedirect = Inherit,
                            stdOut!: ProcessRedirect = Pipe,
                            stdErr!: ProcessRedirect = Pipe): (Int64, Array<Byte>, Array<Byte>)

功能:根据输入参数创建并运行一个子进程,等待该子进程运行完毕并返回子进程退出状态、标准输出和标准错误。输出流、错误流中包含大量输出的场景不适用于本函数,建议通过 SubProcess 中提供的标准流属性结合 wait 函数自行处理。

参数:

  • command: String - 指定子进程命令,command 不允许包含空字符。
  • arguments: Array<String> - 指定子进程参数,arguments 不允许数组中字符串中包含空字符。
  • workingDirectory!: ?Path - 命名可选参数,指定子进程的工作路径,默认继承当前进程工作路径,路径必须为存在的目录且不允许为空路径或包含空字符。
  • environment!: ?Map<String, String> - 命名可选参数,指定子进程环境变量,默认继承当前进程环境变量,key 不允许字符串中包含空字符或 '=',value 不允许字符串中包含空字符。
  • stdIn!: ProcessRedirect - 命名可选参数,指定子进程重定向标准输入,默认继承当前进程标准输入。
  • stdOut!: ProcessRedirect - 命名可选参数,指定子进程重定向标准输出,默认继承当前进程标准输出。
  • stdErr!: ProcessRedirect - 命名可选参数,指定子进程重定向标准错误,默认继承当前进程标准错误。

返回值:

  • (Int64, Array<Byte>, Array<Byte>) - 子进程执行返回结果,包含子进程退出状态(若子进程正常退出,返回子进程退出码,若子进程被信号杀死,返回导致子进程终止的信号编号),进程标准输出结果和进程错误结果。

异常:

  • IllegalArgumentException - 当入参 command 包含空字符,或者 arguments 数组中字符串中包含空字符,或者 workingDirectory 不是存在的目录或为空路径或包含空字符,或者 environment 表中 key 字符串中包含空字符或 '=',或 value 字符串中包含空字符,或者 stdInstdOutstdErr 输入为文件模式,输入的文件已被关闭或删除时,抛出异常。
  • ProcessException - 当内存分配失败,或者 command 对应的命令不存在,或者子进程不存在,或者标准流读取异常时,抛出异常。

static func start(String, Array<String>, ?Path, ?Map<String, String>, ProcessRedirect, ProcessRedirect, ProcessRedirect)

public static func start(command: String,
                        arguments: Array<String>,
                        workingDirectory!: ?Path = None,
                        environment!: ?Map<String, String> = None,
                        stdIn!: ProcessRedirect = Inherit,
                        stdOut!: ProcessRedirect = Inherit,
                        stdErr!: ProcessRedirect = Inherit): SubProcess

功能:根据输入参数创建并运行一个子进程,并返回一个子进程实例。调用该函数创建子进程后,需要调用 waitwaitOutput 函数,否则该子进程结束后成为的僵尸进程的资源不会被回收。

参数:

  • command: String - 指定子进程命令,command 不允许包含空字符。
  • arguments: Array<String> - 指定子进程参数,arguments 不允许数组中字符串中包含空字符。
  • workingDirectory!: ?Path - 命名可选参数,指定子进程的工作路径,默认继承当前进程工作路径,路径必须为存在的目录且不允许为空路径或包含空字符。
  • environment!: ?Map<String, String> - 命名可选参数,指定子进程环境变量,默认继承当前进程环境变量,key 不允许字符串中包含空字符或 '=',value 不允许字符串中包含空字符。
  • stdIn!: ProcessRedirect - 命名可选参数,指定子进程重定向标准输入,默认继承当前进程标准输入。
  • stdOut!: ProcessRedirect - 命名可选参数,指定子进程重定向标准输出,默认继承当前进程标准输出。
  • stdErr!: ProcessRedirect - 命名可选参数,指定子进程重定向标准错误,默认继承当前进程标准错误。

返回值:

异常:

  • IllegalArgumentException - 当入参 command 包含空字符,或者 arguments 数组中字符串中包含空字符,或者 workingDirectory 不是存在的目录或为空路径或包含空字符,或者 environment 表中 key 字符串中包含空字符或 '=',或 value 字符串中包含空字符,或者 stdInstdOutstdErr 输入为文件模式,输入的文件已被关闭或删除时,抛出异常。
  • ProcessException - 当内存分配失败或 command 对应的命令不存在时,抛出异常。

func terminate(Bool)

public func terminate(force!: Bool = false): Unit

功能:终止进程,子进程执行返回结果,包含子进程退出状态(若子进程正常退出,返回子进程退出码,若子进程被信号杀死,返回导致子进程终止的信号编号),进程标准输出结果和进程错误结果。

参数:

  • force!: Bool - 命名可选参数,指定是否强制关闭进程,默认为 false,若设置为 false,对应进程可以在释放资源后结束;若设置为 true,对应进程将被直接杀死。Windows 平台实现为强制关闭进程。

异常:

  • ProcessException - 如果进程不存在,不允许终止,则抛出异常。

class SubProcess

public class SubProcess <: Process

功能:此类为子进程类,继承 Process 类,提供对子进程操作相关功能。

说明:

提供功能具体如下:

  • 提供获取子进程标准流(stdInstdOutstdErr)机制。
  • 提供等待子进程执行返回退出状态码机制,允许设置等待超时时长。
  • 提供等待子进程执行返回输出结果(包含运行正常、异常结果)机制,允许设置等待超时时长。

父类型:

prop stdErr

public prop stdErr: InputStream

功能:获取输入流,连接到子进程标准错误流。

类型:InputStream

prop stdIn

public prop stdIn: OutputStream

功能:获取输出流,连接到子进程标准输入流。

类型:OutputStream

prop stdOut

public prop stdOut: InputStream

功能:获取输入流,连接到子进程标准输出流。

类型:InputStream

func wait(?Duration)

public func wait(timeout!: ?Duration = None): Int64

功能:阻塞当前进程等待子进程任务执行完成并返回子进程退出状态码,允许指定等待超时时间。对于需要操作标准流的场景(Pipe 模式),使用者需要优先处理标准流,避免子进程标准流缓冲区满后调用本函数产生死锁。

说明:

超时时间处理机制:

  • 未传参、 timeout 值为 None 或值小于等于 Duration.Zero 时,阻塞等待直至子进程执行返回。
  • timeout 值大于 Duration.Zero 时,阻塞等待子进程执行返回或等待超时后抛出超时异常。

参数:

  • timeout!: ?Duration - 命名可选参数,设置等待子进程超时时间,默认为 None

返回值:

  • Int64 - 返回子进程退出状态。若子进程正常退出,返回子进程退出码,若子进程被信号杀死,返回导致子进程终止的信号编号。

异常:

func waitOutput()

public func waitOutput(): (Int64, Array<Byte>, Array<Byte>)

功能:阻塞当前进程等待子进程任务执行完成,并返回子进程退出状态码、返回结果(包含输出流和错误流返回结果)。输出流、错误流中包含大量输出的场景不适用于本函数,建议通过 SubProcess 中提供的标准流属性结合 wait 函数自行处理。

返回值:

  • (Int64, Array<Byte>, Array<Byte>) - 子进程执行返回结果,包含子进程退出状态(若子进程正常退出,返回子进程退出码,若子进程被信号杀死,返回导致子进程终止的信号编号),进程标准输出结果和进程错误结果。

异常:

  • ProcessException - 当子进程不存在,或者标准流读取异常时,抛出异常。

枚举

enum ProcessRedirect

public enum ProcessRedirect {
    | Inherit
    | Pipe
    | FromFile(File)
    | Discard
}

功能:该枚举类型用于在创建进程时设置子进程标准流的重定向模式。

Discard

Discard

功能:构造一个标准流重定向枚举实例,表示子进程标准流将被丢弃。此模式下标准流属性不可读取或写入。

FromFile(File)

FromFile(File)

功能:构造一个标准流重定向枚举实例,表示子进程标准流将被重定向至指定的文件。重定向标准输入流将从指定文件读取,重定向标准输出流或标准错误流将写入至指定文件。重定向文件需保证存在且未关闭,否则不允许重定向。此模式下标准流属性不可读取或写入。参数 File 为指定存在且未关闭文件实例,创建子进程时,重定向标准流至该指定文件。

Inherit

Inherit

功能:构造一个标准流重定向枚举实例,表示子进程标准流将继承当前进程的标准流。此模式下标准流属性不可读取或写入。

Pipe

Pipe

功能:构造一个标准流重定向枚举实例,表示子进程标准流将被重定向至管道,并通过管道与当前进程连接。重定向标准输入流可通过管道向子进程写入数据,重定向标准输出流或标准错误流可通过管道读取子进程输出结果。此模式下可通过标准流属性读取或写入数据。

异常

class ProcessException

public class ProcessException <: IOException {
    init(message: String)
}

功能:process 包的异常类。

父类型:

init(String)

public init(message: String)

功能:创建 ProcessException 实例。

参数:

  • message: String - 异常提示信息。

当前进程相关操作

下面是当前进程相关操作示例,以下示例不支持 Windows 平台。

代码如下:

import std.process.*

main(): Int64 {
    let curProcess = Process.current
    println(curProcess.pid)
    println(curProcess.name)
    println(curProcess.command)
    println(curProcess.arguments.toString())
    println(curProcess.commandLine.toString())
    println(curProcess.workingDirectory.toString())
    curProcess.atExit(printText)
    curProcess.exit(0)
    return 0
}

func printText(): Unit {
    println("hello cangjie!")
}

运行结果可能如下(输出结果中main为当前进程执行命令名,回调执行完成后当前进程会退出):

75590
./main
./main
[]
[./main]
/root/code/Process/test
hello cangjie!

Windows 平台子进程结束后删除子进程可执行文件

下面是 Windows 平台子进程结束后删除子进程可执行文件失败后的处理示例。

代码如下:

import std.process.*
import std.io.*
import std.fs.*
import std.time.*
import std.sync.*

// 以Windows平台相关命令举例说明, 以下用例需要在当前目录下提前创建 “test.exe” 可执行文件
main(): Int64 {
    Process.runOutput("cmd.exe", "/c", "test.exe")
    for (_ in 0..5) {
        try {
            remove(".\\test.exe")
            break
        } catch (e: FSException) {
            if (e.message != "Failed to recursive delete directory: \"Access is denied.\".") {
                throw e
            }
            sleep(Duration.millisecond * 5)
        }
    }
    println("delete file success.")
    return 0
}

运行结果可能如下:

delete file success.

任意进程相关操作

下面是任意进程相关操作示例,以下示例不支持 Windows 平台。

代码如下:

import std.process.*
import std.fs.*

main(): Int64 {
    let echoProcess: SubProcess = Process.start("sleep", "10s")
    let ofProcess: Process = Process.of(echoProcess.pid)
    println(ofProcess.pid)
    println(ofProcess.name)
    println(ofProcess.command)
    println(ofProcess.arguments.toString())
    println(ofProcess.commandLine.toString())
    ofProcess.terminate(force: true)
    return 0
}

运行结果可能如下:

78980
sleep
sleep
[10s]
[sleep, 10s]

子进程相关操作

下面是子进程相关操作示例,以下示例不支持 Windows 平台。

代码如下:

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

// 以Linux平台相关命令举例说明, 以下用例需要提前创建 “/root/code/Process/test” 目录
main(): Int64 {
    let sleepProcess: SubProcess = Process.start("sleep", "10s", workingDirectory: Path("/root/code/Process/test"))
    println(sleepProcess.pid)
    println(sleepProcess.name)
    println(sleepProcess.command)
    println(sleepProcess.arguments.toString())
    println(sleepProcess.commandLine.toString())
    println(sleepProcess.workingDirectory.toString())
    sleepProcess.terminate(force: true)
    let rtnCode = sleepProcess.wait()
    println("sleepProcess rtnCode: ${rtnCode}")

    let echoProcess: SubProcess = Process.start("echo", "hello cangjie!", stdOut: ProcessRedirect.Pipe)
    let strReader: StringReader<InputStream> = StringReader(echoProcess.stdOut)
    println(strReader.readToEnd())
    return 0
}

运行结果可能如下:

45090
sleep 10s
sleep
[10s]
[sleep, 10s]
/root/code/Process/test
sleepProcess rtnCode: 9
hello cangjie!

std.overflow 包

功能介绍

overflow 包提供了整数运算溢出时的处理能力。

在整数运算时,若运算结果大于其类型最大值或小于其类型最小值即是溢出。默认情况下,出现溢出时会抛出异常。

overflow 包提供了四种溢出处理策略,并定义了对应的接口,列举如下:

策略接口描述
返回 OptionCheckedOp当整数运算出现溢出,返回 None
饱和SaturatingOp当计算结果大于目标类型的 MAX 值,返回 MAX 值;当计算结果小于目标类型的 MIN 值,返回 MIN 值。
抛出异常ThrowingOp当整数运算出现溢出,抛出异常。
高位截断WrappingOp当整数运算出现溢出,将运算结果中超出目标类型位数的高位截断。

overflow 包中通过扩展为所有的整数类型提供了这些接口的实现,用户可以用同样的方式为其他类型实现 overflow 接口。

API 列表

接口

接口名功能
CheckedOp当整数运算出现溢出,返回 None
SaturatingOp当整数运算出现溢出,饱和处理。
ThrowingOp当整数运算出现溢出,抛出异常。
WrappingOp当整数运算出现溢出,将运算结果中超出目标类型位数的高位截断。

异常类

类名功能
OvershiftException移位运算时移位位数超过操作数位数时抛出的异常。
UndershiftException移位运算时移位位数小于 0 时抛出的异常。

接口

interface CheckedOp<T>

public interface CheckedOp<T> {
    func checkedAdd(y: T): ?T
    func checkedDec(): ?T
    func checkedDiv(y: T): ?T
    func checkedInc(): ?T
    func checkedMod(y: T): ?T
    func checkedMul(y: T): ?T
    func checkedNeg(): ?T
    func checkedShl(y: T): ?T
    func checkedShr(y: T): ?T
    func checkedSub(y: T): ?T
}

功能:当整数运算出现溢出,返回 None

func checkedAdd(T)

func checkedAdd(y: T): ?T

功能:使用返回 Option 策略的加法运算。

当运算出现溢出时,返回 ?T.None,否则返回运算结果。

参数:

  • y: T - 加数。

返回值:

  • ?T - 加法运算结果。

func checkedDec()

func checkedDec(): ?T

功能:使用返回 Option 策略的自减运算。

当运算出现溢出时,返回 ?T.None,否则返回运算结果。

返回值:

  • ?T - 自减运算结果。

func checkedDiv(T)

func checkedDiv(y: T): ?T

功能:使用返回 Option 策略的除法运算。

当运算出现溢出时,返回 ?T.None,否则返回运算结果。

参数:

  • y: T - 除数。

返回值:

  • ?T - 除法运算结果。

func checkedInc()

func checkedInc(): ?T

功能:使用返回 Option 策略的自增运算。

当运算出现溢出时,返回 ?T.None,否则返回运算结果。

返回值:

  • ?T - 自增运算结果。

func checkedMod(T)

func checkedMod(y: T): ?T

功能:使用返回 Option 策略的取余运算。

当运算出现溢出时,返回 ?T.None,否则返回运算结果。

参数:

  • y: T - 除数。

返回值:

  • ?T - 取余运算结果。

func checkedMul(T)

func checkedMul(y: T): ?T

功能:使用返回 Option 策略的乘法运算。

当运算出现溢出时,返回 ?T.None,否则返回运算结果。

参数:

  • y: T - 乘数。

返回值:

  • ?T - 乘法运算结果。

func checkedNeg()

func checkedNeg(): ?T

功能:使用返回 Option 策略的负号运算。

当运算出现溢出时,返回 ?T.None,否则返回运算结果。

返回值:

  • ?T - 负号运算结果。

func checkedShl(T)

func checkedShl(y: T): ?T

功能:使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?T.None,否则返回运算结果。

参数:

  • y: T - 移位位数。

返回值:

  • ?T - 左移运算结果。

func checkedShr(T)

func checkedShr(y: T): ?T

功能:使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?T.None,否则返回运算结果。

参数:

  • y: T - 移位位数。

返回值:

  • ?T - 右移运算结果。

func checkedSub(T)

func checkedSub(y: T): ?T

功能:使用返回 Option 策略的减法运算。

当运算出现溢出时,返回 ?T.None,否则返回运算结果。

参数:

  • y: T - 减数。

返回值:

  • ?T - 减法运算结果。

extend Int16 <: CheckedOp<Int16>

extend Int16 <: CheckedOp<Int16>

功能:为 Int16 实现 CheckedOp 接口。

父类型:

func checkedAdd(Int16)

public func checkedAdd(y: Int16): ?Int16

功能:使用返回 Option 策略的加法运算。

当运算出现溢出时,返回 ?Int16.None,否则返回运算结果。

参数:

返回值:

  • ?Int16 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?Int16

功能:使用返回 Option 策略的自减运算。

当运算出现溢出时,返回 ?Int16.None,否则返回运算结果。

返回值:

  • ?Int16 - 自减运算结果。

func checkedDiv(Int16)

public func checkedDiv(y: Int16): ?Int16

功能:使用返回 Option 策略的除法运算。

当运算出现溢出时,返回 ?Int16.None,否则返回运算结果。

参数:

返回值:

  • ?Int16 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?Int16

功能:使用返回 Option 策略的自增运算。

当运算出现溢出时,返回 ?Int16.None,否则返回运算结果。

返回值:

  • ?Int16 - 自增运算结果。

func checkedMod(Int16)

public func checkedMod(y: Int16): ?Int16

功能:使用返回 Option 策略的取余运算。

当运算出现溢出时,返回 ?Int16.None,否则返回运算结果。

参数:

返回值:

  • ?Int16 - 取余运算结果。

func checkedMul(Int16)

public func checkedMul(y: Int16): ?Int16

功能:使用返回 Option 策略的乘法运算。

当运算出现溢出时,返回 ?Int16.None,否则返回运算结果。

参数:

返回值:

  • ?Int16 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?Int16

功能:使用返回 Option 策略的负号运算。

当运算出现溢出时,返回 ?Int16.None,否则返回运算结果。

返回值:

  • ?Int16 - 负号运算结果。

func checkedShl(Int16)

public func checkedShl(y: Int16): ?Int16

功能:使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?Int16.None,否则返回运算结果。

参数:

  • y: Int16 - 移位位数。

返回值:

  • ?Int16 - 左移运算结果。

func checkedShr(Int16)

public func checkedShr(y: Int16): ?Int16

功能:使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?Int16.None,否则返回运算结果。

参数:

  • y: Int16 - 移位位数。

返回值:

  • ?Int16 - 右移运算结果。

func checkedSub(Int16)

public func checkedSub(y: Int16): ?Int16

功能:使用返回 Option 策略的减法运算。

当运算出现溢出时,返回 ?Int16.None,否则返回运算结果。

参数:

返回值:

  • ?Int16 - 减法运算结果。

extend Int32 <: CheckedOp<Int32>

extend Int32 <: CheckedOp<Int32>

功能:为 Int32 实现 CheckedOp 接口。

父类型:

func checkedAdd(Int32)

public func checkedAdd(y: Int32): ?Int32

功能:使用返回 Option 策略的加法运算。

当运算出现溢出时,返回 ?Int32.None,否则返回运算结果。

参数:

返回值:

  • ?Int32 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?Int32

功能:使用返回 Option 策略的自减运算。

当运算出现溢出时,返回 ?Int32.None,否则返回运算结果。

返回值:

  • ?Int32 - 自减运算结果。

func checkedDiv(Int32)

public func checkedDiv(y: Int32): ?Int32

功能:使用返回 Option 策略的除法运算。

当运算出现溢出时,返回 ?Int32.None,否则返回运算结果。

参数:

返回值:

  • ?Int32 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?Int32

功能:使用返回 Option 策略的自增运算。

当运算出现溢出时,返回 ?Int32.None,否则返回运算结果。

返回值:

  • ?Int32 - 自增运算结果。

func checkedMod(Int32)

public func checkedMod(y: Int32): ?Int32

功能:使用返回 Option 策略的取余运算。

当运算出现溢出时,返回 ?Int32.None,否则返回运算结果。

参数:

返回值:

  • ?Int32 - 取余运算结果。

func checkedMul(Int32)

public func checkedMul(y: Int32): ?Int32

功能:使用返回 Option 策略的乘法运算。

当运算出现溢出时,返回 ?Int32.None,否则返回运算结果。

参数:

返回值:

  • ?Int32 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?Int32

功能:使用返回 Option 策略的负号运算。

当运算出现溢出时,返回 ?Int32.None,否则返回运算结果。

返回值:

  • ?Int32 - 负号运算结果。

func checkedShl(Int32)

public func checkedShl(y: Int32): ?Int32

功能:使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?Int32.None,否则返回运算结果。

参数:

  • y: Int32 - 移位位数。

返回值:

  • ?Int32 - 左移运算结果。

func checkedShr(Int32)

public func checkedShr(y: Int32): ?Int32

功能:使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?Int32.None,否则返回运算结果。

参数:

  • y: Int32 - 移位位数。

返回值:

  • ?Int32 - 右移运算结果。

func checkedSub(Int32)

public func checkedSub(y: Int32): ?Int32

功能:使用返回 Option 策略的减法运算。

当运算出现溢出时,返回 ?Int32.None,否则返回运算结果。

参数:

返回值:

  • ?Int32 - 减法运算结果。

extend Int64 <: CheckedOp<Int64>

extend Int64 <: CheckedOp<Int64>

功能:为 Int64 实现 CheckedOp 接口。

父类型:

func checkedAdd(Int64)

public func checkedAdd(y: Int64): ?Int64

功能:使用返回 Option 策略的加法运算。

当运算出现溢出时,返回 ?Int64.None,否则返回运算结果。

参数:

返回值:

  • ?Int64 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?Int64

功能:使用返回 Option 策略的自减运算。

当运算出现溢出时,返回 ?Int64.None,否则返回运算结果。

返回值:

  • ?Int64 - 自减运算结果。

func checkedDiv(Int64)

public func checkedDiv(y: Int64): ?Int64

功能:使用返回 Option 策略的除法运算。

当运算出现溢出时,返回 ?Int64.None,否则返回运算结果。

参数:

返回值:

  • ?Int64 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?Int64

功能:使用返回 Option 策略的自增运算。

当运算出现溢出时,返回 ?Int64.None,否则返回运算结果。

返回值:

  • ?Int64 - 自增运算结果。

func checkedMod(Int64)

public func checkedMod(y: Int64): ?Int64

功能:使用返回 Option 策略的取余运算。

当运算出现溢出时,返回 ?Int64.None,否则返回运算结果。

参数:

返回值:

  • ?Int64 - 取余运算结果。

func checkedMul(Int64)

public func checkedMul(y: Int64): ?Int64

功能:使用返回 Option 策略的乘法运算。

当运算出现溢出时,返回 ?Int64.None,否则返回运算结果。

参数:

返回值:

  • ?Int64 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?Int64

功能:使用返回 Option 策略的负号运算。

当运算出现溢出时,返回 ?Int64.None,否则返回运算结果。

返回值:

  • ?Int64 - 负号运算结果。

func checkedPow(UInt64)

public func checkedPow(y: UInt64): ?Int64

功能:使用返回 Option 策略的幂运算。

当运算出现溢出时,返回 ?Int64.None,否则返回运算结果。

参数:

返回值:

  • ?Int64 - 幂运算结果。

func checkedShl(Int64)

public func checkedShl(y: Int64): ?Int64

功能:使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?Int64.None,否则返回运算结果。

参数:

  • y: Int64 - 移位位数。

返回值:

  • ?Int64 - 左移运算结果。

func checkedShr(Int64)

public func checkedShr(y: Int64): ?Int64

功能:使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?Int64.None,否则返回运算结果。

参数:

  • y: Int64 - 移位位数。

返回值:

  • ?Int64 - 右移运算结果。

func checkedSub(Int64)

public func checkedSub(y: Int64): ?Int64

功能:使用返回 Option 策略的减法运算。

当运算出现溢出时,返回 ?Int64.None,否则返回运算结果。

参数:

返回值:

  • ?Int64 - 减法运算结果。

extend Int8 <: CheckedOp<Int8>

extend Int8 <: CheckedOp<Int8>

功能:为 Int8 实现 CheckedOp 接口。

父类型:

func checkedAdd(Int8)

public func checkedAdd(y: Int8): ?Int8

功能:使用返回 Option 策略的加法运算。

当运算出现溢出时,返回 ?Int8.None,否则返回运算结果。

参数:

  • y: Int8 - 加数。

返回值:

  • ?Int8 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?Int8

功能:使用返回 Option 策略的自减运算。

当运算出现溢出时,返回 ?Int8.None,否则返回运算结果。

返回值:

  • ?Int8 - 自减运算结果。

func checkedDiv(Int8)

public func checkedDiv(y: Int8): ?Int8

功能:使用返回 Option 策略的除法运算。

当运算出现溢出时,返回 ?Int8.None,否则返回运算结果。

参数:

  • y: Int8 - 除数。

返回值:

  • ?Int8 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?Int8

功能:使用返回 Option 策略的自增运算。

当运算出现溢出时,返回 ?Int8.None,否则返回运算结果。

返回值:

  • ?Int8 - 自增运算结果。

func checkedMod(Int8)

public func checkedMod(y: Int8): ?Int8

功能:使用返回 Option 策略的取余运算。

当运算出现溢出时,返回 ?Int8.None,否则返回运算结果。

参数:

  • y: Int8 - 除数。

返回值:

  • ?Int8 - 取余运算结果。

func checkedMul(Int8)

public func checkedMul(y: Int8): ?Int8

功能:使用返回 Option 策略的乘法运算。

当运算出现溢出时,返回 ?Int8.None,否则返回运算结果。

参数:

  • y: Int8 - 乘数。

返回值:

  • ?Int8 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?Int8

功能:使用返回 Option 策略的负号运算。

当运算出现溢出时,返回 ?Int8.None,否则返回运算结果。

返回值:

  • ?Int8 - 负号运算结果。

func checkedShl(Int8)

public func checkedShl(y: Int8): ?Int8

功能:使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?Int8.None,否则返回运算结果。

参数:

  • y: Int8 - 移位位数。

返回值:

  • ?Int8 - 左移运算结果。

func checkedShr(Int8)

public func checkedShr(y: Int8): ?Int8

功能:使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?Int8.None,否则返回运算结果。

参数:

  • y: Int8 - 移位位数。

返回值:

  • ?Int8 - 右移运算结果。

func checkedSub(Int8)

public func checkedSub(y: Int8): ?Int8

功能:使用返回 Option 策略的减法运算。

当运算出现溢出时,返回 ?Int8.None,否则返回运算结果。

参数:

  • y: Int8 - 减数。

返回值:

  • ?Int8 - 减法运算结果。

extend IntNative <: CheckedOp<IntNative>

extend IntNative <: CheckedOp<IntNative>

功能:为 IntNative 实现 CheckedOp 接口。

父类型:

func checkedAdd(IntNative)

public func checkedAdd(y: IntNative): ?IntNative

功能:使用返回 Option 策略的加法运算。

当运算出现溢出时,返回 ?IntNative.None,否则返回运算结果。

参数:

返回值:

func checkedDec()

public func checkedDec(): ?IntNative

功能:使用返回 Option 策略的自减运算。

当运算出现溢出时,返回 ?IntNative.None,否则返回运算结果。

返回值:

func checkedDiv(IntNative)

public func checkedDiv(y: IntNative): ?IntNative

功能:使用返回 Option 策略的除法运算。

当运算出现溢出时,返回 ?IntNative.None,否则返回运算结果。

参数:

返回值:

func checkedInc()

public func checkedInc(): ?IntNative

功能:使用返回 Option 策略的自增运算。

当运算出现溢出时,返回 ?IntNative.None,否则返回运算结果。

返回值:

func checkedMod(IntNative)

public func checkedMod(y: IntNative): ?IntNative

功能:使用返回 Option 策略的取余运算。

当运算出现溢出时,返回 ?IntNative.None,否则返回运算结果。

参数:

返回值:

func checkedMul(IntNative)

public func checkedMul(y: IntNative): ?IntNative

功能:使用返回 Option 策略的乘法运算。

当运算出现溢出时,返回 ?IntNative.None,否则返回运算结果。

参数:

返回值:

func checkedNeg()

public func checkedNeg(): ?IntNative

功能:使用返回 Option 策略的负号运算。

当运算出现溢出时,返回 ?IntNative.None,否则返回运算结果。

返回值:

func checkedShl(IntNative)

public func checkedShl(y: IntNative): ?IntNative

功能:使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?IntNative.None,否则返回运算结果。

参数:

返回值:

func checkedShr(IntNative)

public func checkedShr(y: IntNative): ?IntNative

功能:使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数或小于 0 时,返回 ?IntNative.None,否则返回运算结果。

参数:

返回值:

func checkedSub(IntNative)

public func checkedSub(y: IntNative): ?IntNative

功能:使用返回 Option 策略的减法运算。

当运算出现溢出时,返回 ?IntNative.None,否则返回运算结果。

参数:

返回值:

extend UInt16 <: CheckedOp<UInt16>

extend UInt16 <: CheckedOp<UInt16>

功能:为 UInt16 实现 CheckedOp 接口。

父类型:

func checkedAdd(UInt16)

public func checkedAdd(y: UInt16): ?UInt16

功能:使用返回 Option 策略的加法运算。

当运算出现溢出时,返回 ?UInt16.None,否则返回运算结果。

参数:

返回值:

  • ?UInt16 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?UInt16

功能:使用返回 Option 策略的自减运算。

当运算出现溢出时,返回 ?UInt16.None,否则返回运算结果。

返回值:

  • ?UInt16 - 自减运算结果。

func checkedDiv(UInt16)

public func checkedDiv(y: UInt16): ?UInt16

功能:使用返回 Option 策略的除法运算。

当运算出现溢出时,返回 ?UInt16.None,否则返回运算结果。

参数:

返回值:

  • ?UInt16 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?UInt16

功能:使用返回 Option 策略的自增运算。

当运算出现溢出时,返回 ?UInt16.None,否则返回运算结果。

返回值:

  • ?UInt16 - 自增运算结果。

func checkedMod(UInt16)

public func checkedMod(y: UInt16): ?UInt16

功能:使用返回 Option 策略的取余运算。

当运算出现溢出时,返回 ?UInt16.None,否则返回运算结果。

参数:

返回值:

  • ?UInt16 - 取余运算结果。

func checkedMul(UInt16)

public func checkedMul(y: UInt16): ?UInt16

功能:使用返回 Option 策略的乘法运算。

当运算出现溢出时,返回 ?UInt16.None,否则返回运算结果。

参数:

返回值:

  • ?UInt16 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?UInt16

功能:使用返回 Option 策略的负号运算。

当运算出现溢出时,返回 ?UInt16.None,否则返回运算结果。

返回值:

  • ?UInt16 - 负号运算结果。

func checkedShl(UInt16)

public func checkedShl(y: UInt16): ?UInt16

功能:使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数时,返回 ?UInt16.None,否则返回运算结果。

参数:

返回值:

  • ?UInt16 - 左移运算结果。

func checkedShr(UInt16)

public func checkedShr(y: UInt16): ?UInt16

功能:使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数时,返回 ?UInt16.None,否则返回运算结果。

参数:

返回值:

  • ?UInt16 - 右移运算结果。

func checkedSub(UInt16)

public func checkedSub(y: UInt16): ?UInt16

功能:使用返回 Option 策略的减法运算。

当运算出现溢出时,返回 ?UInt16.None,否则返回运算结果。

参数:

返回值:

  • ?UInt16 - 减法运算结果。

extend UInt32 <: CheckedOp<UInt32>

extend UInt32 <: CheckedOp<UInt32>

功能:为 UInt32 实现 CheckedOp 接口。

父类型:

func checkedAdd(UInt32)

public func checkedAdd(y: UInt32): ?UInt32

功能:使用返回 Option 策略的加法运算。

当运算出现溢出时,返回 ?UInt32.None,否则返回运算结果。

参数:

返回值:

  • ?UInt32 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?UInt32

功能:使用返回 Option 策略的自减运算。

当运算出现溢出时,返回 ?UInt32.None,否则返回运算结果。

返回值:

  • ?UInt32 - 自减运算结果。

func checkedDiv(UInt32)

public func checkedDiv(y: UInt32): ?UInt32

功能:使用返回 Option 策略的除法运算。

当运算出现溢出时,返回 ?UInt32.None,否则返回运算结果。

参数:

返回值:

  • ?UInt32 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?UInt32

功能:使用返回 Option 策略的自增运算。

当运算出现溢出时,返回 ?UInt32.None,否则返回运算结果。

返回值:

  • ?UInt32 - 自增运算结果。

func checkedMod(UInt32)

public func checkedMod(y: UInt32): ?UInt32

功能:使用返回 Option 策略的取余运算。

当运算出现溢出时,返回 ?UInt32.None,否则返回运算结果。

参数:

返回值:

  • ?UInt32 - 取余运算结果。

func checkedMul(UInt32)

public func checkedMul(y: UInt32): ?UInt32

功能:使用返回 Option 策略的乘法运算。

当运算出现溢出时,返回 ?UInt32.None,否则返回运算结果。

参数:

返回值:

  • ?UInt32 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?UInt32

功能:使用返回 Option 策略的负号运算。

当运算出现溢出时,返回 ?UInt32.None,否则返回运算结果。

返回值:

  • ?UInt32 - 负号运算结果。

func checkedShl(UInt32)

public func checkedShl(y: UInt32): ?UInt32

功能:使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数时,返回 ?UInt32.None,否则返回运算结果。

参数:

返回值:

  • ?UInt32 - 左移运算结果。

func checkedShr(UInt32)

public func checkedShr(y: UInt32): ?UInt32

功能:使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数时,返回 ?UInt32.None,否则返回运算结果。

参数:

返回值:

  • ?UInt32 - 右移运算结果。

func checkedSub(UInt32)

public func checkedSub(y: UInt32): ?UInt32

功能:使用返回 Option 策略的减法运算。

当运算出现溢出时,返回 ?UInt32.None,否则返回运算结果。

参数:

返回值:

  • ?UInt32 - 减法运算结果。

extend UInt64 <: CheckedOp<UInt64>

extend UInt64 <: CheckedOp<UInt64>

功能:为 UInt64 实现 CheckedOp 接口。

父类型:

func checkedAdd(UInt64)

public func checkedAdd(y: UInt64): ?UInt64

功能:使用返回 Option 策略的加法运算。

当运算出现溢出时,返回 ?UInt64.None,否则返回运算结果。

参数:

返回值:

  • ?UInt64 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?UInt64

功能:使用返回 Option 策略的自减运算。

当运算出现溢出时,返回 ?UInt64.None,否则返回运算结果。

返回值:

  • ?UInt64 - 自减运算结果。

func checkedDiv(UInt64)

public func checkedDiv(y: UInt64): ?UInt64

功能:使用返回 Option 策略的除法运算。

当运算出现溢出时,返回 ?UInt64.None,否则返回运算结果。

参数:

返回值:

  • ?UInt64 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?UInt64

功能:使用返回 Option 策略的自增运算。

当运算出现溢出时,返回 ?UInt64.None,否则返回运算结果。

返回值:

  • ?UInt64 - 自增运算结果。

func checkedMod(UInt64)

public func checkedMod(y: UInt64): ?UInt64

功能:使用返回 Option 策略的取余运算。

当运算出现溢出时,返回 ?UInt64.None,否则返回运算结果。

参数:

返回值:

  • ?UInt64 - 取余运算结果。

func checkedMul(UInt64)

public func checkedMul(y: UInt64): ?UInt64

功能:使用返回 Option 策略的乘法运算。

当运算出现溢出时,返回 ?UInt64.None,否则返回运算结果。

参数:

返回值:

  • ?UInt64 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?UInt64

功能:使用返回 Option 策略的负号运算。

当运算出现溢出时,返回 ?UInt64.None,否则返回运算结果。

返回值:

  • ?UInt64 - 负号运算结果。

func checkedShl(UInt64)

public func checkedShl(y: UInt64): ?UInt64

功能:使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数时,返回 ?UInt64.None,否则返回运算结果。

参数:

返回值:

  • ?UInt64 - 左移运算结果。

func checkedShr(UInt64)

public func checkedShr(y: UInt64): ?UInt64

功能:使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数时,返回 ?UInt64.None,否则返回运算结果。

参数:

返回值:

  • ?UInt64 - 右移运算结果。

func checkedSub(UInt64)

public func checkedSub(y: UInt64): ?UInt64

功能:使用返回 Option 策略的减法运算。

当运算出现溢出时,返回 ?UInt64.None,否则返回运算结果。

参数:

返回值:

  • ?UInt64 - 减法运算结果。

extend UInt8 <: CheckedOp<UInt8>

extend UInt8 <: CheckedOp<UInt8>

功能:为 UInt8 实现 CheckedOp 接口。

父类型:

func checkedAdd(UInt8)

public func checkedAdd(y: UInt8): ?UInt8

功能:使用返回 Option 策略的加法运算。

当运算出现溢出时,返回 ?UInt8.None,否则返回运算结果。

参数:

返回值:

  • ?UInt8 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?UInt8

功能:使用返回 Option 策略的自减运算。

当运算出现溢出时,返回 ?UInt8.None,否则返回运算结果。

返回值:

  • ?UInt8 - 自减运算结果。

func checkedDiv(UInt8)

public func checkedDiv(y: UInt8): ?UInt8

功能:使用返回 Option 策略的除法运算。

当运算出现溢出时,返回 ?UInt8.None,否则返回运算结果。

参数:

返回值:

  • ?UInt8 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?UInt8

功能:使用返回 Option 策略的自增运算。

当运算出现溢出时,返回 ?UInt8.None,否则返回运算结果。

返回值:

  • ?UInt8 - 自增运算结果。

func checkedMod(UInt8)

public func checkedMod(y: UInt8): ?UInt8

功能:使用返回 Option 策略的取余运算。

当运算出现溢出时,返回 ?UInt8.None,否则返回运算结果。

参数:

返回值:

  • ?UInt8 - 取余运算结果。

func checkedMul(UInt8)

public func checkedMul(y: UInt8): ?UInt8

功能:使用返回 Option 策略的乘法运算。

当运算出现溢出时,返回 ?UInt8.None,否则返回运算结果。

参数:

返回值:

  • ?UInt8 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?UInt8

功能:使用返回 Option 策略的负号运算。

当运算出现溢出时,返回 ?UInt8.None,否则返回运算结果。

返回值:

  • ?UInt8 - 负号运算结果。

func checkedShl(UInt8)

public func checkedShl(y: UInt8): ?UInt8

功能:使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数时,返回 ?UInt8.None,否则返回运算结果。

参数:

  • y: UInt8 - 移位位数。

返回值:

  • ?UInt8 - 左移运算结果。

func checkedShr(UInt8)

public func checkedShr(y: UInt8): ?UInt8

功能:使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数时,返回 ?UInt8.None,否则返回运算结果。

参数:

  • y: UInt8 - 移位位数。

返回值:

  • ?UInt8 - 右移运算结果。

func checkedSub(UInt8)

public func checkedSub(y: UInt8): ?UInt8

功能:使用返回 Option 策略的减法运算。

当运算出现溢出时,返回 ?UInt8.None,否则返回运算结果。

参数:

返回值:

  • ?UInt8 - 减法运算结果。

extend UIntNative <: CheckedOp<UIntNative>

extend UIntNative <: CheckedOp<UIntNative>

功能:为 UIntNative 实现 CheckedOp 接口。

父类型:

func checkedAdd(UIntNative)

public func checkedAdd(y: UIntNative): ?UIntNative

功能:使用返回 Option 策略的加法运算。

当运算出现溢出时,返回 ?UIntNative.None,否则返回运算结果。

参数:

返回值:

func checkedDec()

public func checkedDec(): ?UIntNative

功能:使用返回 Option 策略的自减运算。

当运算出现溢出时,返回 ?UIntNative.None,否则返回运算结果。

返回值:

func checkedDiv(UIntNative)

public func checkedDiv(y: UIntNative): ?UIntNative

功能:使用返回 Option 策略的除法运算。

当运算出现溢出时,返回 ?UIntNative.None,否则返回运算结果。

参数:

返回值:

func checkedInc()

public func checkedInc(): ?UIntNative

功能:使用返回 Option 策略的自增运算。

当运算出现溢出时,返回 ?UIntNative.None,否则返回运算结果。

返回值:

func checkedMod(UIntNative)

public func checkedMod(y: UIntNative): ?UIntNative

功能:使用返回 Option 策略的取余运算。

当运算出现溢出时,返回 ?UIntNative.None,否则返回运算结果。

参数:

返回值:

func checkedMul(UIntNative)

public func checkedMul(y: UIntNative): ?UIntNative

功能:使用返回 Option 策略的乘法运算。

当运算出现溢出时,返回 ?UIntNative.None,否则返回运算结果。

参数:

返回值:

func checkedNeg()

public func checkedNeg(): ?UIntNative

功能:使用返回 Option 策略的负号运算。

当运算出现溢出时,返回 ?UIntNative.None,否则返回运算结果。

返回值:

func checkedShl(UIntNative)

public func checkedShl(y: UIntNative): ?UIntNative

功能:使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数时,返回 ?UIntNative.None,否则返回运算结果。

参数:

返回值:

func checkedShr(UIntNative)

public func checkedShr(y: UIntNative): ?UIntNative

功能:使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数时,返回 ?UIntNative.None,否则返回运算结果。

参数:

返回值:

func checkedSub(UIntNative)

public func checkedSub(y: UIntNative): ?UIntNative

功能:使用返回 Option 策略的减法运算。

当运算出现溢出时,返回 ?UIntNative.None,否则返回运算结果。

参数:

返回值:

interface SaturatingOp<T>

public interface SaturatingOp<T> {
    func saturatingAdd(y: T): T
    func saturatingDec(): T
    func saturatingDiv(y: T): T
    func saturatingInc(): T
    func saturatingMod(y: T): T
    func saturatingMul(y: T): T
    func saturatingNeg(): T
    func saturatingShl(y: T): T
    func saturatingShr(y: T): T
    func saturatingSub(y: T): T
}

功能:当整数运算出现溢出,饱和处理。

func saturatingAdd(T)

func saturatingAdd(y: T): T

功能:使用饱和策略的加法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

  • y: T - 加数。

返回值:

  • T - 加法运算结果。

func saturatingDec()

func saturatingDec(): T

功能:使用饱和策略的自减运算。

当运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • T - 自减运算结果。

func saturatingDiv(T)

func saturatingDiv(y: T): T

功能:使用饱和策略的除法运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

  • y: T - 除数。

返回值:

  • T - 除法运算结果。

func saturatingInc()

func saturatingInc(): T

功能:使用饱和策略的自增运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

返回值:

  • T - 自增运算结果。

func saturatingMod(T)

func saturatingMod(y: T): T

功能:使用饱和策略的取余运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

  • y: T - 除数。

返回值:

  • T - 取余运算结果。

func saturatingMul(T)

func saturatingMul(y: T): T

功能:使用饱和策略的乘法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

  • y: T - 乘数。

返回值:

  • T - 乘法运算结果。

func saturatingNeg()

func saturatingNeg(): T

功能:使用饱和策略的负号运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • T - 负号运算结果。

func saturatingShl(T)

func saturatingShl(y: T): T

功能:使用饱和策略的左移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: T - 移位位数。

返回值:

  • T - 左移运算结果。

func saturatingShr(T)

func saturatingShr(y: T): T

功能:使用饱和策略的右移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: T - 移位位数。

返回值:

  • T - 右移运算结果。

func saturatingSub(T)

func saturatingSub(y: T): T

功能:使用饱和策略的减法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

  • y: T - 减数。

返回值:

  • T - 减法运算结果。

extend Int16 <: SaturatingOp<Int16>

extend Int16 <: SaturatingOp<Int16>

功能:为 Int16 实现 SaturatingOp 接口。

父类型:

func saturatingAdd(Int16)

public func saturatingAdd(y: Int16): Int16

功能:使用饱和策略的加法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • Int16 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): Int16

功能:使用饱和策略的自减运算。

当运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • Int16 - 自减运算结果。

func saturatingDiv(Int16)

public func saturatingDiv(y: Int16): Int16

功能:使用饱和策略的除法运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • Int16 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): Int16

功能:使用饱和策略的自增运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

返回值:

  • Int16 - 自增运算结果。

func saturatingMod(Int16)

public func saturatingMod(y: Int16): Int16

功能:使用饱和策略的取余运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • Int16 - 取余运算结果。

func saturatingMul(Int16)

public func saturatingMul(y: Int16): Int16

功能:使用饱和策略的乘法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • Int16 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): Int16

功能:使用饱和策略的负号运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • Int16 - 负号运算结果。

func saturatingShl(Int16)

public func saturatingShl(y: Int16): Int16

功能:使用饱和策略的左移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: Int16 - 移位位数。

返回值:

  • Int16 - 左移运算结果。

func saturatingShr(Int16)

public func saturatingShr(y: Int16): Int16

功能:使用饱和策略的右移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: Int16 - 移位位数。

返回值:

  • Int16 - 右移运算结果。

func saturatingSub(Int16)

public func saturatingSub(y: Int16): Int16

功能:使用饱和策略的减法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • Int16 - 减法运算结果。

extend Int32 <: SaturatingOp<Int32>

extend Int32 <: SaturatingOp<Int32>

功能:为 Int32 实现 SaturatingOp 接口。

父类型:

func saturatingAdd(Int32)

public func saturatingAdd(y: Int32): Int32

功能:使用饱和策略的加法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • Int32 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): Int32

功能:使用饱和策略的自减运算。

当运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • Int32 - 自减运算结果。

func saturatingDiv(Int32)

public func saturatingDiv(y: Int32): Int32

功能:使用饱和策略的除法运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • Int32 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): Int32

功能:使用饱和策略的自增运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

返回值:

  • Int32 - 自增运算结果。

func saturatingMod(Int32)

public func saturatingMod(y: Int32): Int32

功能:使用饱和策略的取余运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • Int32 - 取余运算结果。

func saturatingMul(Int32)

public func saturatingMul(y: Int32): Int32

功能:使用饱和策略的乘法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • Int32 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): Int32

功能:使用饱和策略的负号运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • Int32 - 负号运算结果。

func saturatingShl(Int32)

public func saturatingShl(y: Int32): Int32

功能:使用饱和策略的左移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: Int32 - 移位位数。

返回值:

  • Int32 - 左移运算结果。

func saturatingShr(Int32)

public func saturatingShr(y: Int32): Int32

功能:使用饱和策略的右移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: Int32 - 移位位数。

返回值:

  • Int32 - 右移运算结果。

func saturatingSub(Int32)

public func saturatingSub(y: Int32): Int32

功能:使用饱和策略的减法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • Int32 - 减法运算结果。

extend Int64 <: SaturatingOp<Int64>

extend Int64 <: SaturatingOp<Int64>

功能:为 Int64 实现 SaturatingOp 接口。

父类型:

func saturatingAdd(Int64)

public func saturatingAdd(y: Int64): Int64

功能:使用饱和策略的加法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • Int64 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): Int64

功能:使用饱和策略的自减运算。

当运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • Int64 - 自减运算结果。

func saturatingDiv(Int64)

public func saturatingDiv(y: Int64): Int64

功能:使用饱和策略的除法运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • Int64 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): Int64

功能:使用饱和策略的自增运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

返回值:

  • Int64 - 自增运算结果。

func saturatingMod(Int64)

public func saturatingMod(y: Int64): Int64

功能:使用饱和策略的取余运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • Int64 - 取余运算结果。

func saturatingMul(Int64)

public func saturatingMul(y: Int64): Int64

功能:使用饱和策略的乘法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • Int64 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): Int64

功能:使用饱和策略的负号运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • Int64 - 负号运算结果。

func saturatingPow(UInt64)

public func saturatingPow(y: UInt64): Int64

功能:使用饱和策略的幂运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • Int64 - 幂运算结果。

func saturatingShl(Int64)

public func saturatingShl(y: Int64): Int64

功能:使用饱和策略的左移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: Int64 - 移位位数。

返回值:

  • Int64 - 左移运算结果。

func saturatingShr(Int64)

public func saturatingShr(y: Int64): Int64

功能:使用饱和策略的右移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: Int64 - 移位位数。

返回值:

  • Int64 - 右移运算结果。

func saturatingSub(Int64)

public func saturatingSub(y: Int64): Int64

功能:使用饱和策略的减法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • Int64 - 减法运算结果。

extend Int8 <: SaturatingOp<Int8>

extend Int8 <: SaturatingOp<Int8>

功能:为 Int8 实现 SaturatingOp 接口。

父类型:

func saturatingAdd(Int8)

public func saturatingAdd(y: Int8): Int8

功能:使用饱和策略的加法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

  • y: Int8 - 加数。

返回值:

  • Int8 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): Int8

功能:使用饱和策略的自减运算。

当运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • Int8 - 自减运算结果。

func saturatingDiv(Int8)

public func saturatingDiv(y: Int8): Int8

功能:使用饱和策略的除法运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

  • y: Int8 - 除数。

返回值:

  • Int8 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): Int8

功能:使用饱和策略的自增运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

返回值:

  • Int8 - 自增运算结果。

func saturatingMod(Int8)

public func saturatingMod(y: Int8): Int8

功能:使用饱和策略的取余运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

  • y: Int8 - 除数。

返回值:

  • Int8 - 取余运算结果。

func saturatingMul(Int8)

public func saturatingMul(y: Int8): Int8

功能:使用饱和策略的乘法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

  • y: Int8 - 乘数。

返回值:

  • Int8 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): Int8

功能:使用饱和策略的负号运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • Int8 - 负号运算结果。

func saturatingShl(Int8)

public func saturatingShl(y: Int8): Int8

功能:使用饱和策略的左移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: Int8 - 移位位数。

返回值:

  • Int8 - 左移运算结果。

func saturatingShr(Int8)

public func saturatingShr(y: Int8): Int8

功能:使用饱和策略的右移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: Int8 - 移位位数。

返回值:

  • Int8 - 右移运算结果。

func saturatingSub(Int8)

public func saturatingSub(y: Int8): Int8

功能:使用饱和策略的减法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

  • y: Int8 - 减数。

返回值:

  • Int8 - 减法运算结果。

extend IntNative <: SaturatingOp<IntNative>

extend IntNative <: SaturatingOp<IntNative>

功能:为 IntNative 实现 SaturatingOp 接口。

父类型:

func saturatingAdd(IntNative)

public func saturatingAdd(y: IntNative): IntNative

功能:使用饱和策略的加法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

func saturatingDec()

public func saturatingDec(): IntNative

功能:使用饱和策略的自减运算。

当运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

func saturatingDiv(IntNative)

public func saturatingDiv(y: IntNative): IntNative

功能:使用饱和策略的除法运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

func saturatingInc()

public func saturatingInc(): IntNative

功能:使用饱和策略的自增运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

返回值:

func saturatingMod(IntNative)

public func saturatingMod(y: IntNative): IntNative

功能:使用饱和策略的取余运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

func saturatingMul(IntNative)

public func saturatingMul(y: IntNative): IntNative

功能:使用饱和策略的乘法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

func saturatingNeg()

public func saturatingNeg(): IntNative

功能:使用饱和策略的负号运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

func saturatingShl(IntNative)

public func saturatingShl(y: IntNative): IntNative

功能:使用饱和策略的左移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

返回值:

func saturatingShr(IntNative)

public func saturatingShr(y: IntNative): IntNative

功能:使用饱和策略的右移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

返回值:

func saturatingSub(IntNative)

public func saturatingSub(y: IntNative): IntNative

功能:使用饱和策略的减法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

extend UInt16 <: SaturatingOp<UInt16>

extend UInt16 <: SaturatingOp<UInt16>

功能:为 UInt16 实现 SaturatingOp 接口。

父类型:

func saturatingAdd(UInt16)

public func saturatingAdd(y: UInt16): UInt16

功能:使用饱和策略的加法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt16 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): UInt16

功能:使用饱和策略的自减运算。

当运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • UInt16 - 自减运算结果。

func saturatingDiv(UInt16)

public func saturatingDiv(y: UInt16): UInt16

功能:使用饱和策略的除法运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • UInt16 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): UInt16

功能:使用饱和策略的自增运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

返回值:

  • UInt16 - 自增运算结果。

func saturatingMod(UInt16)

public func saturatingMod(y: UInt16): UInt16

功能:使用饱和策略的取余运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • UInt16 - 取余运算结果。

func saturatingMul(UInt16)

public func saturatingMul(y: UInt16): UInt16

功能:使用饱和策略的乘法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt16 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): UInt16

功能:使用饱和策略的负号运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • UInt16 - 负号运算结果。

func saturatingShl(UInt16)

public func saturatingShl(y: UInt16): UInt16

功能:使用饱和策略的左移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

返回值:

  • UInt16 - 左移运算结果。

func saturatingShr(UInt16)

public func saturatingShr(y: UInt16): UInt16

功能:使用饱和策略的右移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

返回值:

  • UInt16 - 右移运算结果。

func saturatingSub(UInt16)

public func saturatingSub(y: UInt16): UInt16

功能:使用饱和策略的减法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt16 - 减法运算结果。

extend UInt32 <: SaturatingOp<UInt32>

extend UInt32 <: SaturatingOp<UInt32>

功能:为 UInt32 实现 SaturatingOp 接口。

父类型:

func saturatingAdd(UInt32)

public func saturatingAdd(y: UInt32): UInt32

功能:使用饱和策略的加法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt32 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): UInt32

功能:使用饱和策略的自减运算。

当运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • UInt32 - 自减运算结果。

func saturatingDiv(UInt32)

public func saturatingDiv(y: UInt32): UInt32

功能:使用饱和策略的除法运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • UInt32 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): UInt32

功能:使用饱和策略的自增运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

返回值:

  • UInt32 - 自增运算结果。

func saturatingMod(UInt32)

public func saturatingMod(y: UInt32): UInt32

功能:使用饱和策略的取余运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • UInt32 - 取余运算结果。

func saturatingMul(UInt32)

public func saturatingMul(y: UInt32): UInt32

功能:使用饱和策略的乘法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt32 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): UInt32

功能:使用饱和策略的负号运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • UInt32 - 负号运算结果。

func saturatingShl(UInt32)

public func saturatingShl(y: UInt32): UInt32

功能:使用饱和策略的左移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

返回值:

  • UInt32 - 左移运算结果。

func saturatingShr(UInt32)

public func saturatingShr(y: UInt32): UInt32

功能:使用饱和策略的右移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

返回值:

  • UInt32 - 右移运算结果。

func saturatingSub(UInt32)

public func saturatingSub(y: UInt32): UInt32

功能:使用饱和策略的减法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt32 - 减法运算结果。

extend UInt64 <: SaturatingOp<UInt64>

extend UInt64 <: SaturatingOp<UInt64>

功能:为 UInt64 实现 SaturatingOp 接口。

父类型:

func saturatingAdd(UInt64)

public func saturatingAdd(y: UInt64): UInt64

功能:使用饱和策略的加法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt64 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): UInt64

功能:使用饱和策略的自减运算。

当运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • UInt64 - 自减运算结果。

func saturatingDiv(UInt64)

public func saturatingDiv(y: UInt64): UInt64

功能:使用饱和策略的除法运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • UInt64 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): UInt64

功能:使用饱和策略的自增运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

返回值:

  • UInt64 - 自增运算结果。

func saturatingMod(UInt64)

public func saturatingMod(y: UInt64): UInt64

功能:使用饱和策略的取余运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • UInt64 - 取余运算结果。

func saturatingMul(UInt64)

public func saturatingMul(y: UInt64): UInt64

功能:使用饱和策略的乘法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt64 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): UInt64

功能:使用饱和策略的负号运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • UInt64 - 负号运算结果。

func saturatingShl(UInt64)

public func saturatingShl(y: UInt64): UInt64

功能:使用饱和策略的左移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

返回值:

  • UInt64 - 左移运算结果。

func saturatingShr(UInt64)

public func saturatingShr(y: UInt64): UInt64

功能:使用饱和策略的右移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

返回值:

  • UInt64 - 右移运算结果。

func saturatingSub(UInt64)

public func saturatingSub(y: UInt64): UInt64

功能:使用饱和策略的减法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt64 - 减法运算结果。

extend UInt8 <: SaturatingOp<UInt8>

extend UInt8 <: SaturatingOp<UInt8>

功能:为 UInt8 实现 SaturatingOp 接口。

父类型:

func saturatingAdd(UInt8)

public func saturatingAdd(y: UInt8): UInt8

功能:使用饱和策略的加法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt8 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): UInt8

功能:使用饱和策略的自减运算。

当运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • UInt8 - 自减运算结果。

func saturatingDiv(UInt8)

public func saturatingDiv(y: UInt8): UInt8

功能:使用饱和策略的除法运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • UInt8 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): UInt8

功能:使用饱和策略的自增运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

返回值:

  • UInt8 - 自增运算结果。

func saturatingMod(UInt8)

public func saturatingMod(y: UInt8): UInt8

功能:使用饱和策略的取余运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

  • UInt8 - 取余运算结果。

func saturatingMul(UInt8)

public func saturatingMul(y: UInt8): UInt8

功能:使用饱和策略的乘法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt8 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): UInt8

功能:使用饱和策略的负号运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

  • UInt8 - 负号运算结果。

func saturatingShl(UInt8)

public func saturatingShl(y: UInt8): UInt8

功能:使用饱和策略的左移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: UInt8 - 移位位数。

返回值:

  • UInt8 - 左移运算结果。

func saturatingShr(UInt8)

public func saturatingShr(y: UInt8): UInt8

功能:使用饱和策略的右移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

  • y: UInt8 - 移位位数。

返回值:

  • UInt8 - 右移运算结果。

func saturatingSub(UInt8)

public func saturatingSub(y: UInt8): UInt8

功能:使用饱和策略的减法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

  • UInt8 - 减法运算结果。

extend UIntNative <: SaturatingOp<UIntNative>

extend UIntNative <: SaturatingOp<UIntNative>

功能:为 UIntNative 实现 SaturatingOp 接口。

父类型:

func saturatingAdd(UIntNative)

public func saturatingAdd(y: UIntNative): UIntNative

功能:使用饱和策略的加法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

func saturatingDec()

public func saturatingDec(): UIntNative

功能:使用饱和策略的自减运算。

当运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

func saturatingDiv(UIntNative)

public func saturatingDiv(y: UIntNative): UIntNative

功能:使用饱和策略的除法运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

func saturatingInc()

public func saturatingInc(): UIntNative

功能:使用饱和策略的自增运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

返回值:

func saturatingMod(UIntNative)

public func saturatingMod(y: UIntNative): UIntNative

功能:使用饱和策略的取余运算。

当运算出现上溢时,返回操作数类型的最大值,否则返回运算结果。

参数:

返回值:

func saturatingMul(UIntNative)

public func saturatingMul(y: UIntNative): UIntNative

功能:使用饱和策略的乘法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

func saturatingNeg()

public func saturatingNeg(): UIntNative

功能:使用饱和策略的负号运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

返回值:

func saturatingShl(UIntNative)

public func saturatingShl(y: UIntNative): UIntNative

功能:使用饱和策略的左移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

返回值:

func saturatingShr(UIntNative)

public func saturatingShr(y: UIntNative): UIntNative

功能:使用饱和策略的右移运算。

当移位位数大于等于操作数位数时,将移位位数置为操作数位数 - 1,移位位数小于 0 时,将移位位数置为 0,否则返回运算结果。

参数:

返回值:

func saturatingSub(UIntNative)

public func saturatingSub(y: UIntNative): UIntNative

功能:使用饱和策略的减法运算。

当运算出现上溢时,返回操作数类型的最大值,运算出现下溢时,返回操作数类型的最小值,否则返回运算结果。

参数:

返回值:

interface ThrowingOp<T>

public interface ThrowingOp<T> {
    func throwingAdd(y: T): T
    func throwingDec(): T
    func throwingDiv(y: T): T
    func throwingInc(): T
    func throwingMod(y: T): T
    func throwingMul(y: T): T
    func throwingNeg(): T
    func throwingShl(y: T): T
    func throwingShr(y: T): T
    func throwingSub(y: T): T
}

功能:当整数运算出现溢出,抛出异常。

func throwingAdd(T)

func throwingAdd(y: T): T

功能:使用抛出异常策略的加法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

  • y: T - 加数。

返回值:

  • T - 加法运算结果。

异常:

func throwingDec()

func throwingDec(): T

功能:使用抛出异常策略的自减运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • T - 自减运算结果。

异常:

func throwingDiv(T)

func throwingDiv(y: T): T

功能:使用抛出异常策略的除法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

  • y: T - 除数。

返回值:

  • T - 除法运算结果。

异常:

func throwingInc()

func throwingInc(): T

功能:使用抛出异常策略的自增运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • T - 自增运算结果。

异常:

func throwingMod(T)

func throwingMod(y: T): T

功能:使用抛出异常策略的取余运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

  • y: T - 除数。

返回值:

  • T - 取余运算结果。

异常:

func throwingMul(T)

func throwingMul(y: T): T

功能:使用抛出异常策略的乘法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

  • y: T - 乘数。

返回值:

  • T - 乘法运算结果。

异常:

func throwingNeg()

func throwingNeg(): T

功能:使用抛出异常策略的负号运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • T - 负号运算结果。

异常:

func throwingShl(T)

func throwingShl(y: T): T

功能:使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,抛出异常,否则返回运算结果。

参数:

  • y: T - 移位位数。

返回值:

  • T - 左移运算结果。

异常:

func throwingShr(T)

func throwingShr(y: T): T

功能:右移运算。

当移位位数大于等于操作数位数时,抛出异常,否则返回运算结果。

参数:

  • y: T - 移位位数。

返回值:

  • T - 右移运算结果。

异常:

func throwingSub(T)

func throwingSub(y: T): T

功能:使用抛出异常策略的减法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

  • y: T - 减数。

返回值:

  • T - 减法运算结果。

异常:

extend Int16 <: ThrowingOp<Int16>

extend Int16 <: ThrowingOp<Int16>

功能:为 Int16 实现 ThrowingOp 接口。

父类型:

func throwingAdd(Int16)

public func throwingAdd(y: Int16): Int16

功能:使用抛出异常策略的加法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int16 - 加法运算结果。

异常:

func throwingDec()

public func throwingDec(): Int16

功能:使用抛出异常策略的自减运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int16 - 自减运算结果。

异常:

func throwingDiv(Int16)

public func throwingDiv(y: Int16): Int16

功能:使用抛出异常策略的除法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int16 - 除法运算结果。

异常:

func throwingInc()

public func throwingInc(): Int16

功能:使用抛出异常策略的自增运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int16 - 自增运算结果。

异常:

func throwingMod(Int16)

public func throwingMod(y: Int16): Int16

功能:使用抛出异常策略的取余运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int16 - 取余运算结果。

异常:

func throwingMul(Int16)

public func throwingMul(y: Int16): Int16

功能:使用抛出异常策略的乘法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int16 - 乘法运算结果。

异常:

func throwingNeg()

public func throwingNeg(): Int16

功能:使用抛出异常策略的负号运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int16 - 负号运算结果。

异常:

func throwingShl(Int16)

public func throwingShl(y: Int16): Int16

功能:使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,抛出异常,否则返回运算结果。

参数:

  • y: Int16 - 移位位数。

返回值:

  • Int16 - 左移运算结果。

异常:

func throwingShr(Int16)

public func throwingShr(y: Int16): Int16

功能:右移运算。

当移位位数大于等于操作数位数时,抛出异常,否则返回运算结果。

参数:

  • y: Int16 - 移位位数。

返回值:

  • Int16 - 右移运算结果。

异常:

func throwingSub(Int16)

public func throwingSub(y: Int16): Int16

功能:使用抛出异常策略的减法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int16 - 减法运算结果。

异常:

extend Int32 <: ThrowingOp<Int32>

extend Int32 <: ThrowingOp<Int32>

功能:为 Int32 实现 ThrowingOp 接口。

父类型:

func throwingAdd(Int32)

public func throwingAdd(y: Int32): Int32

功能:使用抛出异常策略的加法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int32 - 加法运算结果。

异常:

func throwingDec()

public func throwingDec(): Int32

功能:使用抛出异常策略的自减运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int32 - 自减运算结果。

异常:

func throwingDiv(Int32)

public func throwingDiv(y: Int32): Int32

功能:使用抛出异常策略的除法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int32 - 除法运算结果。

异常:

func throwingInc()

public func throwingInc(): Int32

功能:使用抛出异常策略的自增运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int32 - 自增运算结果。

异常:

func throwingMod(Int32)

public func throwingMod(y: Int32): Int32

功能:使用抛出异常策略的取余运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int32 - 取余运算结果。

异常:

func throwingMul(Int32)

public func throwingMul(y: Int32): Int32

功能:使用抛出异常策略的乘法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int32 - 乘法运算结果。

异常:

func throwingNeg()

public func throwingNeg(): Int32

功能:使用抛出异常策略的负号运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int32 - 负号运算结果。

异常:

func throwingShl(Int32)

public func throwingShl(y: Int32): Int32

功能:使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,抛出异常,否则返回运算结果。

参数:

  • y: Int32 - 移位位数。

返回值:

  • Int32 - 左移运算结果。

异常:

func throwingShr(Int32)

public func throwingShr(y: Int32): Int32

功能:右移运算。

当移位位数大于等于操作数位数时,抛出异常,否则返回运算结果。

参数:

  • y: Int32 - 移位位数。

返回值:

  • Int32 - 右移运算结果。

异常:

func throwingSub(Int32)

public func throwingSub(y: Int32): Int32

功能:使用抛出异常策略的减法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int32 - 减法运算结果。

异常:

extend Int64 <: ThrowingOp<Int64>

extend Int64 <: ThrowingOp<Int64>

功能:为 Int64 实现 ThrowingOp 接口。

父类型:

func throwingAdd(Int64)

public func throwingAdd(y: Int64): Int64

功能:使用抛出异常策略的加法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int64 - 加法运算结果。

异常:

func throwingDec()

public func throwingDec(): Int64

功能:使用抛出异常策略的自减运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int64 - 自减运算结果。

异常:

func throwingDiv(Int64)

public func throwingDiv(y: Int64): Int64

功能:使用抛出异常策略的除法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int64 - 除法运算结果。

异常:

func throwingInc()

public func throwingInc(): Int64

功能:使用抛出异常策略的自增运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int64 - 自增运算结果。

异常:

func throwingMod(Int64)

public func throwingMod(y: Int64): Int64

功能:使用抛出异常策略的取余运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int64 - 取余运算结果。

异常:

func throwingMul(Int64)

public func throwingMul(y: Int64): Int64

功能:使用抛出异常策略的乘法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int64 - 乘法运算结果。

异常:

func throwingNeg()

public func throwingNeg(): Int64

功能:使用抛出异常策略的负号运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int64 - 负号运算结果。

异常:

func throwingPow(UInt64)

public func throwingPow(y: UInt64): Int64

功能:使用抛出异常策略的幂运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int64 - 幂运算结果。

异常:

func throwingShl(Int64)

public func throwingShl(y: Int64): Int64

功能:使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,抛出异常,否则返回运算结果。

参数:

  • y: Int64 - 移位位数。

返回值:

  • Int64 - 左移运算结果。

异常:

func throwingShr(Int64)

public func throwingShr(y: Int64): Int64

功能:右移运算。

当移位位数大于等于操作数位数时,抛出异常,否则返回运算结果。

参数:

  • y: Int64 - 移位位数。

返回值:

  • Int64 - 右移运算结果。

异常:

func throwingSub(Int64)

public func throwingSub(y: Int64): Int64

功能:使用抛出异常策略的减法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • Int64 - 减法运算结果。

异常:

extend Int8 <: ThrowingOp<Int8>

extend Int8 <: ThrowingOp<Int8>

功能:为 Int8 实现 ThrowingOp 接口。

父类型:

func throwingAdd(Int8)

public func throwingAdd(y: Int8): Int8

功能:使用抛出异常策略的加法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

  • y: Int8 - 加数。

返回值:

  • Int8 - 加法运算结果。

异常:

func throwingDec()

public func throwingDec(): Int8

功能:使用抛出异常策略的自减运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int8 - 自减运算结果。

异常:

func throwingDiv(Int8)

public func throwingDiv(y: Int8): Int8

功能:使用抛出异常策略的除法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

  • y: Int8 - 除数。

返回值:

  • Int8 - 除法运算结果。

异常:

func throwingInc()

public func throwingInc(): Int8

功能:使用抛出异常策略的自增运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int8 - 自增运算结果。

异常:

func throwingMod(Int8)

public func throwingMod(y: Int8): Int8

功能:使用抛出异常策略的取余运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

  • y: Int8 - 除数。

返回值:

  • Int8 - 取余运算结果。

异常:

func throwingMul(Int8)

public func throwingMul(y: Int8): Int8

功能:使用抛出异常策略的乘法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

  • y: Int8 - 乘数。

返回值:

  • Int8 - 乘法运算结果。

异常:

func throwingNeg()

public func throwingNeg(): Int8

功能:使用抛出异常策略的负号运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • Int8 - 负号运算结果。

异常:

func throwingShl(Int8)

public func throwingShl(y: Int8): Int8

功能:使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,抛出异常,否则返回运算结果。

参数:

  • y: Int8 - 移位位数。

返回值:

  • Int8 - 左移运算结果。

异常:

func throwingShr(Int8)

public func throwingShr(y: Int8): Int8

功能:右移运算。

当移位位数大于等于操作数位数时,抛出异常,否则返回运算结果。

参数:

  • y: Int8 - 移位位数。

返回值:

  • Int8 - 右移运算结果。

异常:

func throwingSub(Int8)

public func throwingSub(y: Int8): Int8

功能:使用抛出异常策略的减法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

  • y: Int8 - 减数。

返回值:

  • Int8 - 减法运算结果。

异常:

extend IntNative <: ThrowingOp<IntNative>

extend IntNative <: ThrowingOp<IntNative>

功能:为 IntNative 实现 ThrowingOp 接口。

父类型:

func throwingAdd(IntNative)

public func throwingAdd(y: IntNative): IntNative

功能:使用抛出异常策略的加法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingDec()

public func throwingDec(): IntNative

功能:使用抛出异常策略的自减运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

异常:

func throwingDiv(IntNative)

public func throwingDiv(y: IntNative): IntNative

功能:使用抛出异常策略的除法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingInc()

public func throwingInc(): IntNative

功能:使用抛出异常策略的自增运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

异常:

func throwingMod(IntNative)

public func throwingMod(y: IntNative): IntNative

功能:使用抛出异常策略的取余运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingMul(IntNative)

public func throwingMul(y: IntNative): IntNative

功能:使用抛出异常策略的乘法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingNeg()

public func throwingNeg(): IntNative

功能:使用抛出异常策略的负号运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

异常:

func throwingShl(IntNative)

public func throwingShl(y: IntNative): IntNative

功能:使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingShr(IntNative)

public func throwingShr(y: IntNative): IntNative

功能:右移运算。

当移位位数大于等于操作数位数时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingSub(IntNative)

public func throwingSub(y: IntNative): IntNative

功能:使用抛出异常策略的减法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

extend UInt16 <: ThrowingOp<UInt16>

extend UInt16 <: ThrowingOp<UInt16>

功能:为 UInt16 实现 ThrowingOp 接口。

父类型:

func throwingAdd(UInt16)

public func throwingAdd(y: UInt16): UInt16

功能:使用抛出异常策略的加法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt16 - 加法运算结果。

异常:

func throwingDec()

public func throwingDec(): UInt16

功能:使用抛出异常策略的自减运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt16 - 自减运算结果。

异常:

func throwingDiv(UInt16)

public func throwingDiv(y: UInt16): UInt16

功能:使用抛出异常策略的除法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt16 - 除法运算结果。

异常:

func throwingInc()

public func throwingInc(): UInt16

功能:使用抛出异常策略的自增运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt16 - 自增运算结果。

异常:

func throwingMod(UInt16)

public func throwingMod(y: UInt16): UInt16

功能:使用抛出异常策略的取余运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt16 - 取余运算结果。

异常:

func throwingMul(UInt16)

public func throwingMul(y: UInt16): UInt16

功能:使用抛出异常策略的乘法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt16 - 乘法运算结果。

异常:

func throwingNeg()

public func throwingNeg(): UInt16

功能:使用抛出异常策略的负号运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt16 - 负号运算结果。

异常:

func throwingShl(UInt16)

public func throwingShl(y: UInt16): UInt16

功能:使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt16 - 左移运算结果。

异常:

func throwingShr(UInt16)

public func throwingShr(y: UInt16): UInt16

功能:右移运算。

当移位位数大于等于操作数位数时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt16 - 右移运算结果。

异常:

func throwingSub(UInt16)

public func throwingSub(y: UInt16): UInt16

功能:使用抛出异常策略的减法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt16 - 减法运算结果。

异常:

extend UInt32 <: ThrowingOp<UInt32>

extend UInt32 <: ThrowingOp<UInt32>

功能:为 UInt32 实现 ThrowingOp 接口。

父类型:

func throwingAdd(UInt32)

public func throwingAdd(y: UInt32): UInt32

功能:使用抛出异常策略的加法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt32 - 加法运算结果。

异常:

func throwingDec()

public func throwingDec(): UInt32

功能:使用抛出异常策略的自减运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt32 - 自减运算结果。

异常:

func throwingDiv(UInt32)

public func throwingDiv(y: UInt32): UInt32

功能:使用抛出异常策略的除法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt32 - 除法运算结果。

异常:

func throwingInc()

public func throwingInc(): UInt32

功能:使用抛出异常策略的自增运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt32 - 自增运算结果。

异常:

func throwingMod(UInt32)

public func throwingMod(y: UInt32): UInt32

功能:使用抛出异常策略的取余运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt32 - 取余运算结果。

异常:

func throwingMul(UInt32)

public func throwingMul(y: UInt32): UInt32

功能:使用抛出异常策略的乘法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt32 - 乘法运算结果。

异常:

func throwingNeg()

public func throwingNeg(): UInt32

功能:使用抛出异常策略的负号运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt32 - 负号运算结果。

异常:

func throwingShl(UInt32)

public func throwingShl(y: UInt32): UInt32

功能:使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt32 - 左移运算结果。

异常:

func throwingShr(UInt32)

public func throwingShr(y: UInt32): UInt32

功能:右移运算。

当移位位数大于等于操作数位数时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt32 - 右移运算结果。

异常:

func throwingSub(UInt32)

public func throwingSub(y: UInt32): UInt32

功能:使用抛出异常策略的减法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt32 - 减法运算结果。

异常:

extend UInt64 <: ThrowingOp<UInt64>

extend UInt64 <: ThrowingOp<UInt64>

功能:为 UInt64 实现 ThrowingOp 接口。

父类型:

func throwingAdd(UInt64)

public func throwingAdd(y: UInt64): UInt64

功能:使用抛出异常策略的加法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt64 - 加法运算结果。

异常:

func throwingDec()

public func throwingDec(): UInt64

功能:使用抛出异常策略的自减运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt64 - 自减运算结果。

异常:

func throwingDiv(UInt64)

public func throwingDiv(y: UInt64): UInt64

功能:使用抛出异常策略的除法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt64 - 除法运算结果。

异常:

func throwingInc()

public func throwingInc(): UInt64

功能:使用抛出异常策略的自增运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt64 - 自增运算结果。

异常:

func throwingMod(UInt64)

public func throwingMod(y: UInt64): UInt64

功能:使用抛出异常策略的取余运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt64 - 取余运算结果。

异常:

func throwingMul(UInt64)

public func throwingMul(y: UInt64): UInt64

功能:使用抛出异常策略的乘法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt64 - 乘法运算结果。

异常:

func throwingNeg()

public func throwingNeg(): UInt64

功能:使用抛出异常策略的负号运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt64 - 负号运算结果。

异常:

func throwingShl(UInt64)

public func throwingShl(y: UInt64): UInt64

功能:使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt64 - 左移运算结果。

异常:

func throwingShr(UInt64)

public func throwingShr(y: UInt64): UInt64

功能:右移运算。

当移位位数大于等于操作数位数时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt64 - 右移运算结果。

异常:

func throwingSub(UInt64)

public func throwingSub(y: UInt64): UInt64

功能:使用抛出异常策略的减法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt64 - 减法运算结果。

异常:

extend UInt8 <: ThrowingOp<UInt8>

extend UInt8 <: ThrowingOp<UInt8>

功能:为 UInt8 实现 ThrowingOp 接口。

父类型:

func throwingAdd(UInt8)

public func throwingAdd(y: UInt8): UInt8

功能:使用抛出异常策略的加法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt8 - 加法运算结果。

异常:

func throwingDec()

public func throwingDec(): UInt8

功能:使用抛出异常策略的自减运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt8 - 自减运算结果。

异常:

func throwingDiv(UInt8)

public func throwingDiv(y: UInt8): UInt8

功能:使用抛出异常策略的除法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt8 - 除法运算结果。

异常:

func throwingInc()

public func throwingInc(): UInt8

功能:使用抛出异常策略的自增运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt8 - 自增运算结果。

异常:

func throwingMod(UInt8)

public func throwingMod(y: UInt8): UInt8

功能:使用抛出异常策略的取余运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt8 - 取余运算结果。

异常:

func throwingMul(UInt8)

public func throwingMul(y: UInt8): UInt8

功能:使用抛出异常策略的乘法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt8 - 乘法运算结果。

异常:

func throwingNeg()

public func throwingNeg(): UInt8

功能:使用抛出异常策略的负号运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

  • UInt8 - 负号运算结果。

异常:

func throwingShl(UInt8)

public func throwingShl(y: UInt8): UInt8

功能:使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,抛出异常,否则返回运算结果。

参数:

  • y: UInt8 - 移位位数。

返回值:

  • UInt8 - 左移运算结果。

异常:

func throwingShr(UInt8)

public func throwingShr(y: UInt8): UInt8

功能:右移运算。

当移位位数大于等于操作数位数时,抛出异常,否则返回运算结果。

参数:

  • y: UInt8 - 移位位数。

返回值:

  • UInt8 - 右移运算结果。

异常:

func throwingSub(UInt8)

public func throwingSub(y: UInt8): UInt8

功能:使用抛出异常策略的减法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

  • UInt8 - 减法运算结果。

异常:

extend UIntNative <: ThrowingOp<UIntNative>

extend UIntNative <: ThrowingOp<UIntNative>

功能:为 UIntNative 实现 ThrowingOp 接口。

父类型:

func throwingAdd(UIntNative)

public func throwingAdd(y: UIntNative): UIntNative

功能:使用抛出异常策略的加法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingDec()

public func throwingDec(): UIntNative

功能:使用抛出异常策略的自减运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

异常:

func throwingDiv(UIntNative)

public func throwingDiv(y: UIntNative): UIntNative

功能:使用抛出异常策略的除法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingInc()

public func throwingInc(): UIntNative

功能:使用抛出异常策略的自增运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

异常:

func throwingMod(UIntNative)

public func throwingMod(y: UIntNative): UIntNative

功能:使用抛出异常策略的取余运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingMul(UIntNative)

public func throwingMul(y: UIntNative): UIntNative

功能:使用抛出异常策略的乘法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingNeg()

public func throwingNeg(): UIntNative

功能:使用抛出异常策略的负号运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

返回值:

异常:

func throwingShl(UIntNative)

public func throwingShl(y: UIntNative): UIntNative

功能:使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingShr(UIntNative)

public func throwingShr(y: UIntNative): UIntNative

功能:右移运算。

当移位位数大于等于操作数位数时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

func throwingSub(UIntNative)

public func throwingSub(y: UIntNative): UIntNative

功能:使用抛出异常策略的减法运算。

当运算出现溢出时,抛出异常,否则返回运算结果。

参数:

返回值:

异常:

interface WrappingOp<T>

public interface WrappingOp<T> {
    func wrappingAdd(y: T): T
    func wrappingDec(): T
    func wrappingDiv(y: T): T
    func wrappingInc(): T
    func wrappingMod(y: T): T
    func wrappingMul(y: T): T
    func wrappingNeg(): T
    func wrappingShl(y: T): T
    func wrappingShr(y: T): T
    func wrappingSub(y: T): T
}

功能:当整数运算出现溢出,高位截断。

func wrappingAdd(T)

func wrappingAdd(y: T): T

功能:使用高位截断策略的加法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

  • y: T - 加数。

返回值:

  • T - 加法运算结果。

func wrappingDec()

func wrappingDec(): T

功能:使用高位截断策略的自减运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • T - 自减运算结果。

func wrappingDiv(T)

func wrappingDiv(y: T): T

功能:使用高位截断策略的除法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

  • y: T - 除数。

返回值:

  • T - 除法运算结果。

func wrappingInc()

func wrappingInc(): T

功能:使用高位截断策略的自增运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • T - 自增运算结果。

func wrappingMod(T)

func wrappingMod(y: T): T

功能:使用高位截断策略的取余运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

  • y: T - 除数。

返回值:

  • T - 取余运算结果。

func wrappingMul(T)

func wrappingMul(y: T): T

功能:使用高位截断策略的乘法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

  • y: T - 乘数。

返回值:

  • T - 乘法运算结果。

func wrappingNeg()

func wrappingNeg(): T

功能:使用高位截断策略的负号运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • T - 负号运算结果。

func wrappingShl(T)

func wrappingShl(y: T): T

功能:使用高位截断策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时,高位截断。例如,对 Int8 类型的数进行移位,当 y (移位位数)超大于等于 8时,仅取 y 的低 3 位作为移位位数,以此保证移位位数在 0 到 7 之间。

参数:

  • y: T - 移位位数。

返回值:

  • T - 左移运算结果。

func wrappingShr(T)

func wrappingShr(y: T): T

功能:使用高位截断策略的右移运算。

当移位位数大于等于操作数位数或小于 0 时,高位截断。例如,对 Int8 类型的数进行移位,当 y (移位位数)超大于等于 8时,仅取 y 的低 3 位作为移位位数,以此保证移位位数在 0 到 7 之间。

参数:

  • y: T - 移位位数。

返回值:

  • T - 右移运算结果。

func wrappingSub(T)

func wrappingSub(y: T): T

功能:使用高位截断策略的减法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

  • y: T - 减数。

返回值:

  • T - 减法运算结果。

extend Int16 <: WrappingOp<Int16>

extend Int16 <: WrappingOp<Int16>

功能:为 Int16 实现 WrappingOp 接口。

父类型:

func wrappingAdd(Int16)

public func wrappingAdd(y: Int16): Int16

功能:使用高位截断策略的加法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int16 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): Int16

功能:使用高位截断策略的自减运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int16 - 自减运算结果。

func wrappingDiv(Int16)

public func wrappingDiv(y: Int16): Int16

功能:使用高位截断策略的除法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int16 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): Int16

功能:使用高位截断策略的自增运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int16 - 自增运算结果。

func wrappingMod(Int16)

public func wrappingMod(y: Int16): Int16

功能:使用高位截断策略的取余运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int16 - 取余运算结果。

func wrappingMul(Int16)

public func wrappingMul(y: Int16): Int16

功能:使用高位截断策略的乘法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int16 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): Int16

功能:使用高位截断策略的负号运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int16 - 负号运算结果。

func wrappingShl(Int16)

public func wrappingShl(y: Int16): Int16

功能:使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数或小于 0 时,取右操作数的低 4 位作为移位位数。

参数:

  • y: Int16 - 移位位数。

返回值:

  • Int16 - 左移运算结果。

func wrappingShr(Int16)

public func wrappingShr(y: Int16): Int16

功能:使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数或小于 0 时,取右操作数的低 4 位作为移位位数。

参数:

  • y: Int16 - 移位位数。

返回值:

  • Int16 - 右移运算结果。

func wrappingSub(Int16)

public func wrappingSub(y: Int16): Int16

功能:使用高位截断策略的减法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int16 - 减法运算结果。

extend Int32 <: WrappingOp<Int32>

extend Int32 <: WrappingOp<Int32>

功能:为 Int32 实现 WrappingOp 接口。

父类型:

func wrappingAdd(Int32)

public func wrappingAdd(y: Int32): Int32

功能:使用高位截断策略的加法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int32 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): Int32

功能:使用高位截断策略的自减运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int32 - 自减运算结果。

func wrappingDiv(Int32)

public func wrappingDiv(y: Int32): Int32

功能:使用高位截断策略的除法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int32 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): Int32

功能:使用高位截断策略的自增运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int32 - 自增运算结果。

func wrappingMod(Int32)

public func wrappingMod(y: Int32): Int32

功能:使用高位截断策略的取余运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int32 - 取余运算结果。

func wrappingMul(Int32)

public func wrappingMul(y: Int32): Int32

功能:使用高位截断策略的乘法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int32 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): Int32

功能:使用高位截断策略的负号运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int32 - 负号运算结果。

func wrappingShl(Int32)

public func wrappingShl(y: Int32): Int32

功能:使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数或小于 0 时,取右操作数的低 5 位作为移位位数。

参数:

  • y: Int32 - 移位位数。

返回值:

  • Int32 - 左移运算结果。

func wrappingShr(Int32)

public func wrappingShr(y: Int32): Int32

功能:使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数或小于 0 时,取右操作数的低 5 位作为移位位数。

参数:

  • y: Int32 - 移位位数。

返回值:

  • Int32 - 右移运算结果。

func wrappingSub(Int32)

public func wrappingSub(y: Int32): Int32

功能:使用高位截断策略的减法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int32 - 减法运算结果。

extend Int64 <: WrappingOp<Int64>

extend Int64 <: WrappingOp<Int64>

功能:为 Int64 实现 WrappingOp 接口。

父类型:

func wrappingAdd(Int64)

public func wrappingAdd(y: Int64): Int64

功能:使用高位截断策略的加法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int64 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): Int64

功能:使用高位截断策略的自减运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int64 - 自减运算结果。

func wrappingDiv(Int64)

public func wrappingDiv(y: Int64): Int64

功能:使用高位截断策略的除法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int64 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): Int64

功能:使用高位截断策略的自增运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int64 - 自增运算结果。

func wrappingMod(Int64)

public func wrappingMod(y: Int64): Int64

功能:使用高位截断策略的取余运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int64 - 取余运算结果。

func wrappingMul(Int64)

public func wrappingMul(y: Int64): Int64

功能:使用高位截断策略的乘法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int64 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): Int64

功能:使用高位截断策略的负号运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int64 - 负号运算结果。

func wrappingPow(UInt64)

public func wrappingPow(y: UInt64): Int64

功能:使用高位截断策略的幂运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int64 - 幂运算结果。

func wrappingShl(Int64)

public func wrappingShl(y: Int64): Int64

功能:使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数或小于 0 时,取右操作数的低 6 位作为移位位数。

参数:

  • y: Int64 - 移位位数。

返回值:

  • Int64 - 左移运算结果。

func wrappingShr(Int64)

public func wrappingShr(y: Int64): Int64

功能:使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数或小于 0 时,取右操作数的低 6 位作为移位位数。

参数:

  • y: Int64 - 移位位数。

返回值:

  • Int64 - 右移运算结果。

func wrappingSub(Int64)

public func wrappingSub(y: Int64): Int64

功能:使用高位截断策略的减法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • Int64 - 减法运算结果。

extend Int8 <: WrappingOp<Int8>

extend Int8 <: WrappingOp<Int8>

功能:为 Int8 实现 WrappingOp 接口。

父类型:

func wrappingAdd(Int8)

public func wrappingAdd(y: Int8): Int8

功能:使用高位截断策略的加法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

  • y: Int8 - 加数。

返回值:

  • Int8 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): Int8

功能:使用高位截断策略的自减运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int8 - 自减运算结果。

func wrappingDiv(Int8)

public func wrappingDiv(y: Int8): Int8

功能:使用高位截断策略的除法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

  • y: Int8 - 除数。

返回值:

  • Int8 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): Int8

功能:使用高位截断策略的自增运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int8 - 自增运算结果。

func wrappingMod(Int8)

public func wrappingMod(y: Int8): Int8

功能:使用高位截断策略的取余运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

  • y: Int8 - 除数。

返回值:

  • Int8 - 取余运算结果。

func wrappingMul(Int8)

public func wrappingMul(y: Int8): Int8

功能:使用高位截断策略的乘法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

  • y: Int8 - 乘数。

返回值:

  • Int8 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): Int8

功能:使用高位截断策略的负号运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • Int8 - 负号运算结果。

func wrappingShl(Int8)

public func wrappingShl(y: Int8): Int8

功能:使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数或小于 0 时,取右操作数的低 3 位作为移位位数。

参数:

  • y: Int8 - 移位位数。

返回值:

  • Int8 - 左移运算结果。

func wrappingShr(Int8)

public func wrappingShr(y: Int8): Int8

功能:使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数或小于 0 时,取右操作数的低 3 位作为移位位数。

参数:

  • y: Int8 - 移位位数。

返回值:

  • Int8 - 右移运算结果。

func wrappingSub(Int8)

public func wrappingSub(y: Int8): Int8

功能:使用高位截断策略的减法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

  • y: Int8 - 减数。

返回值:

  • Int8 - 减法运算结果。

extend IntNative <: WrappingOp<IntNative>

extend IntNative <: WrappingOp<IntNative>

功能:为 IntNative 实现 WrappingOp 接口。

父类型:

func wrappingAdd(IntNative)

public func wrappingAdd(y: IntNative): IntNative

功能:使用高位截断策略的加法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

func wrappingDec()

public func wrappingDec(): IntNative

功能:使用高位截断策略的自减运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

func wrappingDiv(IntNative)

public func wrappingDiv(y: IntNative): IntNative

功能:使用高位截断策略的除法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

func wrappingInc()

public func wrappingInc(): IntNative

功能:使用高位截断策略的自增运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

func wrappingMod(IntNative)

public func wrappingMod(y: IntNative): IntNative

功能:使用高位截断策略的取余运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

func wrappingMul(IntNative)

public func wrappingMul(y: IntNative): IntNative

功能:使用高位截断策略的乘法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

func wrappingNeg()

public func wrappingNeg(): IntNative

功能:使用高位截断策略的负号运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

func wrappingShl(IntNative)

public func wrappingShl(y: IntNative): IntNative

功能:使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数或小于 0 时,取右操作数的低位作为移位位数,具体取的位数取决于当前系统下 IntNative 的位数。

参数:

返回值:

func wrappingShr(IntNative)

public func wrappingShr(y: IntNative): IntNative

功能:使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数或小于 0 时,取右操作数的低位作为移位位数,具体取的位数取决于当前系统下 IntNative 的位数。

参数:

返回值:

func wrappingSub(IntNative)

public func wrappingSub(y: IntNative): IntNative

功能:使用高位截断策略的减法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

extend UInt16 <: WrappingOp<UInt16>

extend UInt16 <: WrappingOp<UInt16>

功能:为 UInt16 实现 WrappingOp 接口。

父类型:

func wrappingAdd(UInt16)

public func wrappingAdd(y: UInt16): UInt16

功能:使用高位截断策略的加法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt16 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): UInt16

功能:使用高位截断策略的自减运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt16 - 自减运算结果。

func wrappingDiv(UInt16)

public func wrappingDiv(y: UInt16): UInt16

功能:使用高位截断策略的除法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt16 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): UInt16

功能:使用高位截断策略的自增运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt16 - 自增运算结果。

func wrappingMod(UInt16)

public func wrappingMod(y: UInt16): UInt16

功能:使用高位截断策略的取余运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt16 - 取余运算结果。

func wrappingMul(UInt16)

public func wrappingMul(y: UInt16): UInt16

功能:使用高位截断策略的乘法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt16 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): UInt16

功能:使用高位截断策略的负号运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt16 - 负号运算结果。

func wrappingShl(UInt16)

public func wrappingShl(y: UInt16): UInt16

功能:使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数时,取右操作数的低 4 位作为移位位数。

参数:

返回值:

  • UInt16 - 左移运算结果。

func wrappingShr(UInt16)

public func wrappingShr(y: UInt16): UInt16

功能:使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数时,取右操作数的低 4 位作为移位位数。

参数:

返回值:

  • UInt16 - 右移运算结果。

func wrappingSub(UInt16)

public func wrappingSub(y: UInt16): UInt16

功能:使用高位截断策略的减法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt16 - 减法运算结果。

extend UInt32 <: WrappingOp<UInt32>

extend UInt32 <: WrappingOp<UInt32>

功能:为 UInt32 实现 WrappingOp 接口。

父类型:

func wrappingAdd(UInt32)

public func wrappingAdd(y: UInt32): UInt32

功能:使用高位截断策略的加法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt32 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): UInt32

功能:使用高位截断策略的自减运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt32 - 自减运算结果。

func wrappingDiv(UInt32)

public func wrappingDiv(y: UInt32): UInt32

功能:使用高位截断策略的除法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt32 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): UInt32

功能:使用高位截断策略的自增运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt32 - 自增运算结果。

func wrappingMod(UInt32)

public func wrappingMod(y: UInt32): UInt32

功能:使用高位截断策略的取余运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt32 - 取余运算结果。

func wrappingMul(UInt32)

public func wrappingMul(y: UInt32): UInt32

功能:使用高位截断策略的乘法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt32 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): UInt32

功能:使用高位截断策略的负号运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt32 - 负号运算结果。

func wrappingShl(UInt32)

public func wrappingShl(y: UInt32): UInt32

功能:使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数时,取右操作数的低 5 位作为移位位数。

参数:

返回值:

  • UInt32 - 左移运算结果。

func wrappingShr(UInt32)

public func wrappingShr(y: UInt32): UInt32

功能:使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数时,取右操作数的低 5 位作为移位位数。

参数:

返回值:

  • UInt32 - 右移运算结果。

func wrappingSub(UInt32)

public func wrappingSub(y: UInt32): UInt32

功能:使用高位截断策略的减法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt32 - 减法运算结果。

extend UInt64 <: WrappingOp<UInt64>

extend UInt64 <: WrappingOp<UInt64>

功能:为 UInt64 实现 WrappingOp 接口。

父类型:

func wrappingAdd(UInt64)

public func wrappingAdd(y: UInt64): UInt64

功能:使用高位截断策略的加法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt64 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): UInt64

功能:使用高位截断策略的自减运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt64 - 自减运算结果。

func wrappingDiv(UInt64)

public func wrappingDiv(y: UInt64): UInt64

功能:使用高位截断策略的除法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt64 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): UInt64

功能:使用高位截断策略的自增运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt64 - 自增运算结果。

func wrappingMod(UInt64)

public func wrappingMod(y: UInt64): UInt64

功能:使用高位截断策略的取余运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt64 - 取余运算结果。

func wrappingMul(UInt64)

public func wrappingMul(y: UInt64): UInt64

功能:使用高位截断策略的乘法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt64 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): UInt64

功能:使用高位截断策略的负号运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt64 - 负号运算结果。

func wrappingShl(UInt64)

public func wrappingShl(y: UInt64): UInt64

功能:使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数时,取右操作数的低 6 位作为移位位数。

参数:

返回值:

  • UInt64 - 左移运算结果。

func wrappingShr(UInt64)

public func wrappingShr(y: UInt64): UInt64

功能:使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数时,取右操作数的低 6 位作为移位位数。

参数:

返回值:

  • UInt64 - 右移运算结果。

func wrappingSub(UInt64)

public func wrappingSub(y: UInt64): UInt64

功能:使用高位截断策略的减法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt64 - 减法运算结果。

extend UInt8 <: WrappingOp<UInt8>

extend UInt8 <: WrappingOp<UInt8>

功能:为 UInt8 实现 WrappingOp 接口。

父类型:

func wrappingAdd(UInt8)

public func wrappingAdd(y: UInt8): UInt8

功能:使用高位截断策略的加法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt8 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): UInt8

功能:使用高位截断策略的自减运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt8 - 自减运算结果。

func wrappingDiv(UInt8)

public func wrappingDiv(y: UInt8): UInt8

功能:使用高位截断策略的除法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt8 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): UInt8

功能:使用高位截断策略的自增运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt8 - 自增运算结果。

func wrappingMod(UInt8)

public func wrappingMod(y: UInt8): UInt8

功能:使用高位截断策略的取余运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt8 - 取余运算结果。

func wrappingMul(UInt8)

public func wrappingMul(y: UInt8): UInt8

功能:使用高位截断策略的乘法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt8 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): UInt8

功能:使用高位截断策略的负号运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

  • UInt8 - 负号运算结果。

func wrappingShl(UInt8)

public func wrappingShl(y: UInt8): UInt8

功能:使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数时,取右操作数的低 3 位作为移位位数。

参数:

  • y: UInt8 - 移位位数。

返回值:

  • UInt8 - 左移运算结果。

func wrappingShr(UInt8)

public func wrappingShr(y: UInt8): UInt8

功能:使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数时,取右操作数的低 3 位作为移位位数。

参数:

  • y: UInt8 - 移位位数。

返回值:

  • UInt8 - 右移运算结果。

func wrappingSub(UInt8)

public func wrappingSub(y: UInt8): UInt8

功能:使用高位截断策略的减法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

  • UInt8 - 减法运算结果。

extend UIntNative <: WrappingOp<UIntNative>

extend UIntNative <: WrappingOp<UIntNative>

功能:为 UIntNative 实现 WrappingOp 接口。

父类型:

func wrappingAdd(UIntNative)

public func wrappingAdd(y: UIntNative): UIntNative

功能:使用高位截断策略的加法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

func wrappingDec()

public func wrappingDec(): UIntNative

功能:使用高位截断策略的自减运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

func wrappingDiv(UIntNative)

public func wrappingDiv(y: UIntNative): UIntNative

功能:使用高位截断策略的除法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

func wrappingInc()

public func wrappingInc(): UIntNative

功能:使用高位截断策略的自增运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

func wrappingMod(UIntNative)

public func wrappingMod(y: UIntNative): UIntNative

功能:使用高位截断策略的取余运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

func wrappingMul(UIntNative)

public func wrappingMul(y: UIntNative): UIntNative

功能:使用高位截断策略的乘法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

func wrappingNeg()

public func wrappingNeg(): UIntNative

功能:使用高位截断策略的负号运算。

当运算出现溢出时,高位截断,否则返回运算结果。

返回值:

func wrappingShl(UIntNative)

public func wrappingShl(y: UIntNative): UIntNative

功能:使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数时,取右操作数的低位作为移位位数,具体取的位数取决于当前系统下 UIntNative 的位数。

参数:

返回值:

func wrappingShr(UIntNative)

public func wrappingShr(y: UIntNative): UIntNative

功能:使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数时,取右操作数的低位作为移位位数,具体取的位数取决于当前系统下 UIntNative 的位数。

参数:

返回值:

func wrappingSub(UIntNative)

public func wrappingSub(y: UIntNative): UIntNative

功能:使用高位截断策略的减法运算。

当运算出现溢出时,高位截断,否则返回运算结果。

参数:

返回值:

异常类

class OvershiftException

public class OvershiftException <: Exception {
    public init()
    public init(message: String)
}

功能:移位运算中,当移位位数超过操作数位数时抛出的异常。

父类型:

init()

public init()

功能:创建 OvershiftException 实例。

init(String)

public init(message: String)

功能:创建带有异常信息 message 的 OvershiftException 实例。

参数:

  • message: String - 异常信息。

class UndershiftException

public class UndershiftException <: Exception {
    public init()
    public init(message: String)
}

功能:移位运算中,当移位位数小于 0 时抛出的异常。

父类型:

init()

public init()

功能:创建 UndershiftException 实例。

init(String)

public init(message: String)

功能:创建带有异常信息 message 的 UndershiftException 实例。

参数:

  • message: String - 异常信息。

返回 Option 策略的示例

下面是返回 Option 策略的示例,示例中尝试运算 Int64.Max 的平方,发生溢出,返回 None。

import std.overflow.*
import std.math.*

main() {
    let a: Int64 = Int64.Max
    println(a.checkedPow(UInt64(2)))
}

运行结果如下:

None

饱和策略的示例

下面是饱和策略的示例,示例中尝试运算 UInt16.Max 乘 16,运算结果超过 UInt16 的最大值,发生上溢,故返回 UInt16 的最大值。

import std.overflow.*
import std.math.*

main() {
    let a: UInt16 = UInt16.Max
    println(a.saturatingMul(16))
}

运行结果如下:

65535

抛出异常策略的示例

下面是抛出异常策略的示例,示例中尝试运算 Int64.Max + 1,发生溢出,抛出 OverflowException。

import std.overflow.*
import std.math.*

main() {
    let a: Int64 = Int64.Max
    println(a.throwingAdd(1))
}

运行结果如下:

An exception has occurred:
OverflowException: add

高位截断策略的示例

下面是高位截断策略的示例,示例中尝试运算 UInt8.Max + 1,UInt8.Max 二进制表示为 0b11111111,UInt8.Max + 1 为 0b100000000,由于 UInt8 只能储存 8 位,高位截断后结果为 0。

import std.overflow.*
import std.math.*

main() {
    let a: UInt8 = UInt8.Max
    println(a.wrappingAdd(1))
}

运行结果如下:

0

std.random 包

功能介绍

random 包提供生成伪随机数的能力。

API列表

类名功能
Random提供生成伪随机数的相关功能。

class Random

public open class Random

功能: 提供生成伪随机数的相关功能。

示例:

import std.random.*
main() {
    let m: Random = Random()
    /* 创建 Random 对象并设置种子来获取随机对象 */
    m.seed = 3
    let b: Bool = m.nextBool()
    let c: Int8 = m.nextInt8()
    print("b=${b is Bool},")/* 对象也可以是 Bool 类型 */
    println("c=${c is Int8}")
    return 0
}

运行结果:

b=true,c=true

prop seed

public open mut prop seed: UInt64

功能: 设置或者获取种子的大小,如果设置相同随机种子,生成的伪随机数列表相同。

类型:UInt64

init()

public init()

功能: 默认无参构造函数创建新的 Random 对象。

init(UInt64)

public init(seed: UInt64)

功能:使用随机数种子创建新的 Random 对象。

参数:

  • seed: UInt64 - 随机数种子,如果设置相同随机种子,生成的伪随机数列表相同。

func next(UInt64)

public open func next(bits: UInt64): UInt64

功能: 生成一个用户指定位长的随机整数。

参数:

  • bits: UInt64 - 要生成的伪随机数的位数,取值范围 (0, 64]。

返回值:

  • UInt64 - 用户指定位长的伪随机数。

异常:

func nextBool()

public open func nextBool(): Bool

功能:获取一个布尔类型的伪随机值。

返回值:

  • Bool - 一个 Bool 类型的伪随机数。

func nextFloat16()

public open func nextFloat16(): Float16

功能:获取一个 Float16 类型的伪随机数,其范围为 [0.0, 1.0)。

返回值:

func nextFloat32()

public open func nextFloat32(): Float32

功能:获取一个 Float32 类型的伪随机数,其范围为 [0.0, 1.0)。

返回值:

func nextFloat64()

public open func nextFloat64(): Float64

功能:获取一个 Float64 类型的伪随机数,其范围为 [0.0, 1.0)。

返回值:

func nextGaussianFloat16(Float16, Float16)

public func nextGaussianFloat16(mean!: Float16 = 0.0, sigma!: Float16 = 1.0): Float16

功能:获取一个 Float16 类型的符合指定均值与标准差的高斯分布的随机数。

默认获取一个 Float16 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数。其中均值是期望值,可解释为位置参数,决定了分布的位置,标准差可解释为尺度参数,决定了分布的幅度。此函数调用了函数 nextGaussianFloat16Implement 得到返回值,所以当子类继承 Random 并覆写 nextGaussianFloat64Implement 函数时,调用子类的该函数将会返回覆写的函数的返回值。

参数:

  • mean!: Float16 - 均值,默认值 0.0。
  • sigma!: Float16 - 标准差,默认值 1.0。

返回值:

func nextGaussianFloat16Implement(Float16, Float16)

protected open func nextGaussianFloat16Implement(mean: Float16, sigma: Float16): Float16

功能: nextGaussianFloat16 的实现函数,获取一个 Float16 类型的符合指定均值与标准差的高斯分布的随机数。

获取一个 Float16 类型,且符合均值为 mean 标准差为 sigma 的高斯分布的随机数。其中均值是期望值,可解释为位置参数,决定了分布的位置,标准差可解释为尺度参数,决定了分布的幅度。此函数是 nextGaussianFloat16 的实现函数,非公开,当子类继承 Random 并覆写此函数时,调用子类的 nextGaussianFloat16 函数将会返回此函数的返回值。

参数:

返回值:

func nextGaussianFloat32(Float32, Float32)

public func nextGaussianFloat32(mean!: Float32 = 0.0, sigma!: Float32 = 1.0): Float32

功能:获取一个 Float32 类型的符合指定均值与标准差的高斯分布的随机数。

默认获取一个 Float32 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数。其中均值是期望值,可解释为位置参数,决定了分布的位置,标准差可解释为尺度参数,决定了分布的幅度。此函数调用了函数 nextGaussianFloat32Implement 得到返回值,所以当子类继承 Random 并覆写 nextGaussianFloat64Implement 函数时,调用子类的该函数将会返回覆写的函数的返回值。

参数:

  • mean!: Float32 - 均值,默认值 0.0。
  • sigma!: Float32 - 标准差,默认值 1.0。

返回值:

func nextGaussianFloat32Implement(Float32, Float32)

protected open func nextGaussianFloat32Implement(mean: Float32, sigma: Float32): Float32

功能: nextGaussianFloat32 的实现函数,获取一个 Float32 类型的符合指定均值与标准差的高斯分布的随机数。

获取一个 Float32 类型,且符合均值为 mean 标准差为 sigma 的高斯分布的随机数。其中均值是期望值,可解释为位置参数,决定了分布的位置,标准差可解释为尺度参数,决定了分布的幅度。此函数是 nextGaussianFloat32 的实现函数,非公开,当子类继承 Random 并覆写此函数时,调用子类的 nextGaussianFloat32 函数将会返回此函数的返回值。

参数:

返回值:

func nextGaussianFloat64(Float64, Float64)

public func nextGaussianFloat64(mean!: Float64 = 0.0, sigma!: Float64 = 1.0): Float64

功能:获取一个 Float64 类型的符合指定均值与标准差的高斯分布的随机数。

默认获取一个 Float64 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数。其中均值是期望值,可解释为位置参数,决定了分布的位置,标准差可解释为尺度参数,决定了分布的幅度。此函数调用了函数 nextGaussianFloat64Implement 得到返回值,所以当子类继承 Random 并覆写 nextGaussianFloat64Implement 函数时,调用子类的该函数将会返回覆写的函数的返回值。

参数:

  • mean!: Float64 - 均值,默认值 0.0。
  • sigma!: Float64 - 标准差,默认值 1.0。

返回值:

func nextGaussianFloat64Implement(Float64, Float64)

protected open func nextGaussianFloat64Implement(mean: Float64, sigma: Float64): Float64

功能: nextGaussianFloat64 的实现函数,获取一个 Float64 类型的符合指定均值与标准差的高斯分布的随机数。

获取一个 Float64 类型,且符合均值为 mean 标准差为 sigma 的高斯分布的随机数。其中均值是期望值,可解释为位置参数,决定了分布的位置,标准差可解释为尺度参数,决定了分布的幅度。此函数是 nextGaussianFloat64 的实现函数,非公开,当子类继承 Random 并覆写此函数时,调用子类的 nextGaussianFloat64 函数将会返回此函数的返回值。

参数:

返回值:

func nextInt16()

public open func nextInt16(): Int16

功能:获取一个 Int16 类型的伪随机数。

返回值:

func nextInt16(Int16)

public open func nextInt16(upper: Int16): Int16

功能:获取一个范围在 [0, upper) 的 Int16 类型的伪随机数。

参数:

  • upper: Int16 - 表示生成的伪随机数范围上界(不包括 upper),取值范围 (0, Int16.Max]。

返回值:

异常:

func nextInt32()

public open func nextInt32(): Int32

功能:获取一个 Int32 类型的伪随机数。

返回值:

func nextInt32(Int32)

public open func nextInt32(upper: Int32): Int32

功能:获取一个范围在 [0, upper) 的 Int32 类型的伪随机数。

参数:

  • upper: Int32 - 表示生成的伪随机数范围上界(不包括 upper),取值范围 (0, Int32.Max]。

返回值:

异常:

func nextInt64()

public open func nextInt64(): Int64

功能:获取一个 Int64 类型的伪随机数。

返回值:

func nextInt64(Int64)

public open func nextInt64(upper: Int64): Int64

功能:获取一个范围在 [0, upper) 的 Int64 类型的伪随机数。

参数:

  • upper: Int64 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, Int64.Max]。

返回值:

异常:

func nextInt8()

public open func nextInt8(): Int8

功能:获取一个 Int8 类型的伪随机数。

返回值:

  • Int8 - 一个 Int8 类型的伪随机数。

func nextInt8(Int8): Int8

public open func nextInt8(upper: Int8): Int8

功能:获取一个范围在 [0, upper) 的 Int8 类型的伪随机数。

参数:

  • upper: Int8 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, Int8.Max]。

返回值:

  • Int8 - 一个 Int8 类型的伪随机数。

异常:

func nextUInt16()

public open func nextUInt16(): UInt16

功能:获取一个 UInt16 类型的伪随机数。

返回值:

func nextUInt16(UInt16)

public open func nextUInt16(upper: UInt16): UInt16

功能:获取一个范围在 [0, upper) 的 UInt16 类型的伪随机数。

参数:

  • upper: UInt16 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, UInt16.Max]。

返回值:

异常:

func nextUInt32()

public open func nextUInt32(): UInt32

功能:获取一个 UInt32 类型的伪随机数。

返回值:

func nextUInt32(UInt32)

public open func nextUInt32(upper: UInt32): UInt32

功能:获取一个范围在 [0, upper) 的 UInt32 类型的伪随机数。

参数:

  • upper: UInt32 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, UInt32.Max]。

返回值:

异常:

func nextUInt64()

public open func nextUInt64(): UInt64

功能:获取一个 UInt64 类型的伪随机数。

返回值:

func nextUInt64(UInt64)

public open func nextUInt64(upper: UInt64): UInt64

功能:获取一个范围在 [0, upper) 的 UInt64 类型的伪随机数。

参数:

  • upper: UInt64 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, UInt64.Max]。

返回值:

异常:

func nextUInt8()

public open func nextUInt8(): UInt8

功能:获取一个 UInt8 类型的伪随机数。

返回值:

func nextUInt8(UInt8)

public open func nextUInt8(upper: UInt8): UInt8

功能:获取一个范围在 [0, upper) 的 UInt8 类型的伪随机数。

参数:

  • upper: UInt8 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, UInt8.Max]。

返回值:

异常:

func nextUInt8s(Array<UInt8>)

public open func nextUInt8s(array: Array<UInt8>): Array<UInt8>

功能:生成随机数替换入参数组中的每个元素。

参数:

返回值:

std.reflect 包

功能介绍

reflect 包提供了反射功能,使得程序在运行时能够获取到各种实例的类型信息,并进行各种读写和调用操作。

本包暂不支持 macOS 平台。

注意:

  • 对于全局信息仓颉的反射功能只能访问公开的全局变量和全局函数。
  • 对于当前所在包,仓颉的反射功能可以访问所有全局定义的类型,而对于外部导入的包或动态加载的模块,则只能访问其中公开的全局定义的类型。
  • 对于成员信息仓颉的反射功能只能访问类型内的公开成员(实例/静态成员变量/属性/函数),使用非 public 修饰符修饰的或缺省修饰符的成员均是不可见的。
  • 目前,仓颉的反射功能尚不支持 Nothing 类型、函数类型、元组类型、enum 类型和带有泛型的 struct 类型。

API 列表

函数

函数名功能
parseParameterTypes(String)将字符串转换为包含具体类型信息的函数签名,以便 getStaticFunction 等函数使用。

类名功能
TypeInfoTypeInfo提供了所有数据类型通用的操作接口,支持用户进行反射操作。
ClassTypeInfo描述class类型的类型信息。
InterfaceTypeInfo描述interface类型的类型信息。
PrimitiveTypeInfo描述原始数据类型的类型信息。
StructTypeInfo描述struct类型的类型信息。
InfoList信息列表,用于保存只读的反射信息。
ConstructorInfo描述构造函数信息。
ParameterInfo描述函数形参信息。
InstanceFunctionInfo描述实例成员函数信息。
StaticFunctionInfo描述静态成员函数信息。
InstancePropertyInfo描述实例成员属性信息。
StaticPropertyInfo描述静态成员属性信息。
InstanceVariableInfo描述实例成员变量信息。
StaticVariableInfo描述静态成员变量信息。
ModuleInfo描述模块信息,提供了仓颉动态模块加载、缓存能力以及模块内包信息查询能力。
PackageInfo描述包信息。
GlobalFunctionInfo描述全局函数信息。
GlobalVariableInfo描述全局变量信息。

枚举

枚举名功能
ModifierInfo描述修饰符信息。

异常类

异常类名功能
ReflectExceptionReflectException 为 Reflect 包的基异常类。
InfoNotFoundException表示无法找到对应信息异常。
MisMatchException表示调用对应函数抛出异常。
IllegalSetException表示对不可变类型进行更改异常。
IllegalTypeException表示类型不匹配异常。
InvocationTargetException表示调用函数包装异常。

函数

func parseParameterTypes(String)

public func parseParameterTypes(parameterTypes: String): Array<TypeInfo>

功能:从字符串中解析出参数类型,并将其转换为类型数组,以便getStaticFunction等函数使用。

函数参数类型限定名称为函数类型的参数类型部分,不包含参数名、默认值,也不包含最外层的 ()。 因此对于下面的一个仓颉函数:

import m1.p1.T1
func f(a: Int64, b: T1, c!: Int64 = 0, d!: Int64 = 0): Int64 { ... }

其限定名称应该为"Int64, m1/p1.T1, Int64, Int64"。对于无参函数的限定名称应该为 ""

参数:

  • parameterTypes: String - 函数参数类型限定名称。

返回值:

异常:

class ClassTypeInfo

public class ClassTypeInfo <: TypeInfo

功能:描述 class 类型的类型信息。

父类型:

prop constructors

public prop constructors: Collection<ConstructorInfo>

功能:获取该 ClassTypeInfo 对应的 class 的所有公开构造函数信息,返回对应集合。

注意:

  • 如果该 class 类型无任何公开构造函数,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<ConstructorInfo>

prop instanceVariables

public prop instanceVariables: Collection<InstanceVariableInfo>

功能:获取该 ClassTypeInfo 对应的 class 的所有公开实例成员变量信息,返回对应集合。

注意:

  • 如果该 class 类型无任何公开实例成员变量,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 该集合不包含任何继承而来的公开实例成员变量。

类型:Collection<InstanceVariableInfo>

prop sealedSubclasses

public prop sealedSubclasses: Collection<ClassTypeInfo>

功能:如果该 ClassTypeInfo 对应的 class 类型拥有 sealed 语义,则获取该 class 类型所在包内的所有子类的类型信息,返回对应集合。

注意:

  • 如果该 class 类型不拥有 sealed 语义,则返回空集合。
  • 如果该 class 类型拥有 sealed 语义,那么获得的集合必不可能是空集合,因为该 class 类型本身就是自己的子类。

类型:Collection<ClassTypeInfo>

prop staticVariables

public prop staticVariables: Collection<StaticVariableInfo>

功能:获取该 ClassTypeInfo 对应的 class 的所有公开静态成员变量信息,返回对应集合。

注意:

  • 如果该 class 类型无任何公开静态成员变量,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 该集合不包含任何继承而来的公开静态成员变量。

类型:Collection<StaticVariableInfo>

prop superClass

public prop superClass: Option<ClassTypeInfo>

功能:获取该 class 类型信息所对应的 class 类型的直接父类。

注意:

理论上只有 class Object 没有直接父类。

类型:Option<ClassTypeInfo>

func construct(Array<Any>)

public func construct(args: Array<Any>): Any

功能:在该 ClassTypeInfo 对应的 class 类型中根据实参列表搜索匹配的构造函数并调用,传入实参列表,返回调用结果。

参数:

返回值:

  • Any - 该 class 类型的实例。

异常:

func getConstructor(Array<TypeInfo>)

public func getConstructor(parameterTypes: Array<TypeInfo>): ConstructorInfo

功能:尝试在该 ClassTypeInfo 对应的 class 类型中获取与给定形参类型信息列表匹配的公开构造函数的信息。

参数:

返回值:

  • ConstructorInfo - 如果成功匹配则返回该公开构造函数的信息。

异常:

func getInstanceVariable(String)

public func getInstanceVariable(name: String): InstanceVariableInfo

功能:给定变量名称,尝试获取该 ClassTypeInfo 所对应的 class 类型中匹配的实例成员变量的信息。

参数:

  • name: String - 变量名称。

返回值:

异常:

func getStaticVariable(String)

public func getStaticVariable(name: String): StaticVariableInfo

功能:给定变量名称,尝试获取该 ClassTypeInfo 所对应的 class 类型中匹配的静态成员变量的信息。

参数:

  • name: String - 变量名称。

返回值:

异常:

func isAbstract()

public func isAbstract(): Bool

功能:判断该 ClassTypeInfo 对应的 class 类型是否是抽象类。

返回值:

  • Bool - 如果该 ClassTypeInfo 对应的 class 类型是抽象类则返回 true,否则返回 false

func isOpen()

public func isOpen(): Bool

功能:判断该 ClassTypeInfo 对应的 class 类型是否拥有 open 语义。

注意:

并不是只有被 open 修饰符所修饰的 class 类型定义才拥有 open 语义,如: abstract class 无论是否被 open 修饰符修饰都会拥有 open 语义。

返回值:

  • Bool - 如果该 ClassTypeInfo 对应的 class 类型拥有 open 语义则返回 true,否则返回 false

func isSealed()

public func isSealed(): Bool

功能:判断该 ClassTypeInfo 对应的 class 类型是否拥有 sealed 语义。

返回值:

  • Bool - 如果该 ClassTypeInfo 对应的 class 类型拥有 sealed 语义则返回 true,否则返回 false

class ConstructorInfo

public class ConstructorInfo <: Equatable<ConstructorInfo> & Hashable & ToString

功能:描述构造函数信息。

父类型:

prop annotations

public prop annotations: Collection<Annotation>

功能:获取所有作用于该 ConstructorInfo 对应的构造函数的注解,返回对应集合。

注意:

  • 如果无任何注解作用于该构造函数信息所对应的构造函数,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<Annotation>

prop parameters

public prop parameters: InfoList<ParameterInfo>

功能:获取该 ConstructorInfo 所对应的构造函数的形参类型列表。

类型:InfoList<ParameterInfo>

func apply(Array<Any>)

public func apply(args: Array<Any>): Any

功能:调用该 ConstructorInfo 对应的构造函数,传入实参列表,并返回调用结果。

注意:

  • 目前,实参不支持 struct 类型的实例。
  • 目前,struct 类型中定义的构造函数不支持被调用。

参数:

返回值:

  • Any - 由该构造函数构造得到的类型实例。

异常:

  • InvocationTargetException - 如果该构造函数信息所对应的构造函数所属的类型是抽象类,则会抛出异常。
  • IllegalArgumentException - 如果实参列表 args 中的实参的数目与该构造函数信息所对应的构造函数的形参列表中的形参的数目不等,则抛出异常。
  • IllegalTypeException - 如果实参列表 args 中的任何一个实参的运行时类型不是该构造函数信息所对应的构造函数的对应形参的声明类型的子类型,则抛出异常。
  • Exception - 如果被调用的构造函数信息所对应的构造函数内部抛出异常,则该异常将被封装为 Exception 异常并抛出。

func findAnnotation<T>() where T <: Annotation

public func findAnnotation<T>(): Option<T> where T <: Annotation

功能:尝试获取作用于该 ConstructorInfo 对应的构造函数且拥有给定限定名称的注解。

返回值:

  • Option<T> - 如果成功匹配则返回该注解,否则返回 None

func hashCode()

public func hashCode(): Int64

功能:获取该构造器信息的哈希值。

返回值:

  • Int64 - 该构造器信息的哈希值。

func toString()

public func toString(): String

功能:获取字符串形式的该构造函数信息。

返回值:

  • String - 字符串形式的该构造函数信息。

operator func !=(ConstructorInfo)

public operator func !=(that: ConstructorInfo): Bool

功能:判断该构造器信息与给定的另一个构造器信息是否不等。

参数:

返回值:

  • Bool - 如果该构造器信息与 that 不等则返回 true,否则返回 false

operator func ==(ConstructorInfo)

public operator func ==(that: ConstructorInfo): Bool

功能:判断该构造器信息与给定的另一个构造器信息是否相等。

参数:

返回值:

  • Bool - 如果该构造器信息与 that 相等则返回 true,否则返回 false

class GlobalFunctionInfo

public class GlobalFunctionInfo <: Equatable<GlobalFunctionInfo> & Hashable & ToString

功能:描述全局函数信息。

父类型:

prop name

public prop name: String

功能:获取该 GlobalFunctionInfo 对应的全局函数的名称。

注意:

构成重载的所有全局函数将拥有相同的名称。

类型:String

prop parameters

public prop parameters: InfoList<ParameterInfo>

功能:获取该 GlobalFunctionInfo 对应的全局函数的形参信息列表。

类型:InfoList<ParameterInfo>

prop returnType

public prop returnType: TypeInfo

功能:获取该 GlobalFunctionInfo 对应的全局函数的返回类型的类型信息。

类型:TypeInfo

func apply(Array<Any>)

public func apply(args: Array<Any>): Any

功能:调用该 GlobalFunctionInfo 对应的全局函数,传入实参列表,返回调用结果。

注意:

目前,实参不支持 struct 类型的实例。

参数:

返回值:

  • Any - 该全局函数的调用结果。

异常:

  • IllegalArgumentException - 如果实参列表 args 中的实参的数目与该全局函数信息所对应的全局函数的形参列表中的形参的数目不等,则抛出异常。
  • IllegalTypeException - 如果实参列表 args 中的任何一个实参的运行时类型不是该全局函数信息所对应的全局函数的对应形参的声明类型的子类型,则抛出异常。
  • Exception - 如果被调用的全局函数信息所对应全局函数内部抛出异常,则该异常将被封装为 Exception 异常并抛出。

func hashCode()

public func hashCode(): Int64

功能:获取该全局函数信息的哈希值。

返回值:

  • Int64 - 该全局函数信息的哈希值。

func toString()

public func toString(): String

功能:获取字符串形式的该全局函数信息。

返回值:

  • String - 字符串形式的该全局函数信息。

operator func ==(GlobalFunctionInfo)

public operator func ==(that: GlobalFunctionInfo): Bool

功能:判断该全局函数信息与给定的另一个全局函数信息是否相等。

参数:

返回值:

  • Bool - 如果该全局函数信息与 that 相等则返回 true,否则返回 false

operator func !=(GlobalFunctionInfo)

public operator func !=(that: GlobalFunctionInfo): Bool

功能:判断该全局函数信息与给定的另一个全局函数信息是否不等。

参数:

返回值:

  • Bool - 如果该全局函数信息与 that 不等则返回 true,否则返回 false

class GlobalVariableInfo

public class GlobalVariableInfo <: Equatable<GlobalVariableInfo> & Hashable & ToString

功能:描述全局变量信息。

父类型:

prop name

public prop name: String

功能:获取该 GlobalVariableInfo 对应的全局变量的名称。

类型:String

prop typeInfo

public prop typeInfo: TypeInfo

功能:获取该 GlobalVariableInfo 对应的全局变量的声明类型的类型信息。

类型:TypeInfo

func getValue()

public func getValue(): Any

功能:获取该 GlobalVariableInfo 对应的全局变量的值。

返回值:

  • Any - 该全局变量的值。

func hashCode()

public func hashCode(): Int64

功能:获取该全局变量信息的哈希值。

返回值:

  • Int64 - 该全局变量信息的哈希值。

func isMutable()

public func isMutable(): Bool

功能:判断该 GlobalVariableInfo 对应的全局变量是否可修改。

注意:

  • 如果实例成员变量被 var 修饰符所修饰,则该全局变量可被修改。
  • 如果实例成员变量被 let 修饰符所修饰,则该全局变量不可被修改。
  • 任何类型为 struct 的全局变量均不可修改。

返回值:

  • Bool - 如果该全局变量可被修改则返回 true ,否则返回 false

func setValue(Any)

public func setValue(newValue: Any): Unit

功能:设置该 GlobalVariableInfo 对应的全局变量的值。

参数:

  • newValue: Any - 新的值。

异常:

  • IllegalSetException - 如果该全局变量信息所对应的全局变量不可修改,则抛出异常。
  • IllegalTypeException - 如果新值 newValue 的运行时类型不是全局变量信息所对应的全局变量的声明类型的子类型,则抛出异常。

func toString()

public func toString(): String

功能:获取字符串形式的该全局变量信息。

返回值:

  • String - 字符串形式的该全局变量信息。

operator func ==(GlobalVariableInfo)

public operator func ==(that: GlobalVariableInfo): Bool

功能:判断该全局变量信息与给定的另一个全局变量信息是否相等。

参数:

返回值:

  • Bool - 如果该全局变量信息与 that 相等则返回 true,否则返回 false

operator func !=(GlobalVariableInfo)

public operator func !=(that: GlobalVariableInfo): Bool

功能:判断该全局变量信息与给定的另一个全局变量信息是否不等。

参数:

返回值:

  • Bool - 如果该全局变量信息与 that 不等则返回 true,否则返回 false

class InfoList

public class InfoList<T> <: Collection<T>

功能:信息列表,用于保存只读的反射信息。

父类型:

prop size

public prop size: Int64

功能:获取该信息列表中的元素个数。

类型:Int64

func get(Int64)

public func get(index: Int64): ?T

功能:尝试获取该信息列表指定位置上的元素。

参数:

  • index: Int64 - 位置索引。

返回值:

  • ?T - 该信息列表指定位置上的元素。

func isEmpty()

public func isEmpty(): Bool

功能:判断该信息列表是否为空。

返回值:

  • Bool - 如果该信息列表为空则返回 true,否则返回 false

func iterator()

public func iterator(): Iterator<T>

功能:获取该信息列表的迭代器。

返回值:

  • Iterator<T> - 该信息列表的迭代器。

operator func [](Int64)

public operator func [](index: Int64): T

功能:获取该信息列表指定位置上的元素。

参数:

  • index: Int64 - 位置索引。

返回值:

  • T - 该信息列表指定位置上的元素。

异常:

class InstanceFunctionInfo

public class InstanceFunctionInfo <: Equatable<InstanceFunctionInfo> & Hashable & ToString

功能:描述实例成员函数信息。

父类型:

prop annotations

public prop annotations: Collection<Annotation>

功能:获取所有作用于该 InstanceFunctionInfo 对应的实例成员函数的注解,返回对应集合。

注意:

  • 如果无任何注解作用于该实例成员函数信息所对应的实例成员函数,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<Annotation>

prop modifiers

public prop modifiers: Collection<ModifierInfo>

功能:获取该 InstanceFunctionInfo 对应的实例成员函数所拥有的所有修饰符的信息,返回对应集合。

注意:

  • 如果该实例成员函数无任何修饰符,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 即便未被某修饰符修饰,如果拥有该修饰符的语义,该修饰符信息也将被包括在该集合中。

类型:Collection<ModifierInfo>

prop name

public prop name: String

功能:获取该 InstanceFunctionInfo 对应的实例成员函数的名称。

注意:

  • 构成重载的所有实例成员函数将拥有相同的名称。
  • 操作符重载函数的名称就是该操作符本身的符号内容,如"+","*","[]"。

类型:String

prop parameters

public prop parameters: InfoList<ParameterInfo>

功能:获取该 InstanceFunctionInfo 对应的实例成员函数的形参信息列表。

类型:InfoList<ParameterInfo>

prop returnType

public prop returnType: TypeInfo

功能:获取该 InstanceFunctionInfo 对应的实例成员函数的返回值类型的类型信息。

类型:TypeInfo

func apply(Any, Array<Any>)

public func apply(instance: Any, args: Array<Any>): Any

功能:调用该 InstanceFunctionInfo 对应实例成员函数,指定实例并传入实参列表,返回调用结果。

注意:

  • 目前,实例 instance 不支持 struct 类型的实例。
  • 目前,实参不支持 struct 类型的实例。

参数:

  • instance: Any - 实例。
  • args: Array<Any> - 实参列表。

返回值:

  • Any - 该实例成员函数的调用结果。

异常:

  • InvocationTargetException - 如果该实例成员函数信息所对应的实例成员函数是抽象的,则抛出异常。
  • IllegalTypeException - 如果实例 instance 的运行时类型与该实例成员函数信息所对应的实例成员函数所属的类型不严格相同,则抛出异常。
  • IllegalArgumentException - 如果实参列表 args 中的实参的数目与该实例成员函数信息所对应的实例成员函数的形参列表中的形参的数目不等,则抛出异常。
  • IllegalTypeException - 如果实参列表 args 中的任何一个实参的运行时类型不是该实例成员函数信息所对应的实例成员函数的对应形参的声明类型的子类型,则抛出异常。
  • Exception - 如果被调用的实例成员函数信息所对应的实例成员函数内部抛出异常,则该异常将被封装为 Exception 异常并抛出。

func findAnnotation<T>() where T <: Annotation

public func findAnnotation<T>(): Option<T> where T <: Annotation

功能:尝试获取作用于该 InstanceFunctionInfo 对应的实例成员函数且拥有给定限定名称的注解。

返回值:

  • Option<T> - 如果成功匹配则返回该注解,否则返回 None

func hashCode()

public func hashCode(): Int64

功能:获取该实例成员函数信息的哈希值。

返回值:

  • Int64 - 该实例成员函数信息的哈希值。

func isAbstract()

public func isAbstract(): Bool

功能:判断 InstanceFunctionInfo 所对应的实例成员函数是否拥有 abstract 语义。

返回值:

  • Bool - 如果该实例成员函数拥有 abstract 语义则返回 true,否则返回 false

func isOpen()

public func isOpen(): Bool

功能:判断该 InstanceFunctionInfo 对应的实例成员函数是否拥有 open 语义。

返回值:

  • Bool - 如果该实例成员函数拥有 open 语义则返回 true,否则返回 false

注意:

interface 类型中的实例成员函数默认均拥有 open 语义。

func toString()

public func toString(): String

功能:获取字符串形式的该实例成员函数信息。

返回值:

  • String - 字符串形式的该实例成员函数信息。

operator func ==(InstanceFunctionInfo)

public operator func ==(that: InstanceFunctionInfo): Bool

功能:判断该实例成员函数信息与给定的另一个实例成员函数信息是否相等。

参数:

返回值:

  • Bool - 如果该实例成员函数信息与 that 相等则返回 true,否则返回 false

operator func !=(InstanceFunctionInfo)

public operator func !=(that: InstanceFunctionInfo): Bool

功能:判断该实例成员函数信息与给定的另一个实例成员函数信息是否不等。

参数:

返回值:

  • Bool - 如果该实例成员函数信息与 that 不等则返回 true,否则返回 false

class InstancePropertyInfo

public class InstancePropertyInfo <: Equatable<InstancePropertyInfo> & Hashable & ToString

功能:描述实例成员属性信息。

父类型:

prop annotations

public prop annotations: Collection<Annotation>

功能:获取所有作用于该 InstancePropertyInfo 对应的实例成员属性的注解,返回对应集合。

注意:

  • 如果无任何注解作用于该实例成员属性信息所对应的实例成员属性,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<Annotation>

prop modifiers

public prop modifiers: Collection<ModifierInfo>

功能:获取该 InstancePropertyInfo 对应的实例成员属性所拥有的所有修饰符的信息,返回对应集合。

注意:

  • 如果该实例成员属性无任何修饰符,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 即便未被某修饰符修饰,如果拥有该修饰符的语义,该修饰符信息也将被包括在该集合中。

类型:Collection<ModifierInfo>

prop name

public prop name: String

功能:获取该 InstancePropertyInfo 对应的实例成员属性的名称。

类型:String

prop typeInfo

public prop typeInfo: TypeInfo

功能:获取该 InstancePropertyInfo 对应的实例成员属性的声明类型的类型信息。

类型:TypeInfo

func findAnnotation<T>() where T <: Annotation

public func findAnnotation<T>(): Option<T> where T <: Annotation

功能:尝试获取作用于该 InstancePropertyInfo 对应的实例成员属性且拥有给定限定名称的注解。

返回值:

  • Option<T> - 如果成功匹配则返回该注解,否则返回 None

func getValue(Any)

public func getValue(instance: Any): Any

功能:获取该 InstancePropertyInfo 对应的实例成员属性在给定实例中的值。

注意:

目前,实例 instance 不支持 struct 类型的实例。

参数:

  • instance: Any - 实例。

返回值:

  • Any - 该实例成员属性在实例 instance 中的值。

异常:

  • IllegalTypeException - 如果实例 instance 的运行时类型与该实例成员属性信息所对应的实例成员属性所属的类型不严格相同,则抛出异常。

func hashCode()

public func hashCode(): Int64

功能:获取该实例成员属性信息的哈希值。

返回值:

  • Int64 - 该实例成员属性信息的哈希值。

func isMutable()

public func isMutable(): Bool

功能:判断该 InstancePropertyInfo 对应的实例成员属性是否可修改。

注意:

  • 如果实例成员属性被 mut 修饰符所修饰,则该实例成员属性可被修改,否则不可被修改。
  • 任何 struct 类型的实例的任何实例成员属性均不可修改。
  • 任何类型为 struct 的实例成员属性均不可修改。

返回值:

  • Bool - 如果该实例成员属性信息所对应的实例成员属性可被修改则返回 true ,否则返回 false

func setValue(Any, Any)

public func setValue(instance: Any, newValue: Any): Unit

功能:设置该 InstancePropertyInfo 对应的实例成员属性在给定实例中的值。

注意:

目前,实例 instance 不支持 struct 类型的实例。

参数:

  • instance: Any - 实例。
  • newValue: Any - 新值。

异常:

  • IllegalSetException - 如果该实例成员属性信息所对应的实例成员属性不可修改,则抛出异常。
  • IllegalTypeException - 如果实例 instance 的运行时类型与该实例成员属性信息所对应的实例成员属性所属的类型不严格相同,则抛出异常。
  • IllegalTypeException - 如果新值 newValue 的运行时类型不是该实例成员属性信息所对应的实例成员属性的声明类型的子类型,则抛出异常。

func toString()

public func toString(): String

功能:获取字符串形式的该实例成员属性信息。

返回值:

  • String - 字符串形式的该实例成员属性信息。

operator func !=(InstancePropertyInfo)

public operator func !=(that: InstancePropertyInfo): Bool

功能:判断该实例成员属性信息与给定的另一个实例成员属性信息是否不等。

参数:

返回值:

  • Bool - 如果该实例成员属性信息与 that 不等则返回 true,否则返回 false

operator func ==(InstancePropertyInfo)

public operator func ==(that: InstancePropertyInfo): Bool

功能:判断该实例成员属性信息与给定的另一个实例成员属性信息是否相等。

参数:

返回值:

  • Bool - 如果该实例成员属性信息与 that 相等则返回 true,否则返回 false

class InstanceVariableInfo

public class InstanceVariableInfo <: Equatable<InstanceVariableInfo> & Hashable & ToString

功能:描述实例成员变量信息。

父类型:

prop annotations

public prop annotations: Collection<Annotation>

功能:获取所有作用于该 InstanceVariableInfo 对应的实例成员变量的注解,返回对应集合。

注意:

  • 如果无任何注解作用于该实例成员变量信息所对应的实例成员变量,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<Annotation>

prop modifiers

public prop modifiers: Collection<ModifierInfo>

功能:获取该 InstanceVariableInfo 对应的实例成员变量所拥有的所有修饰符的信息,返回对应集合。

注意:

  • 如果该实例成员变量无任何修饰符,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 即便未被某修饰符修饰,如果拥有该修饰符的语义,该修饰符信息也将被包括在该集合中。

类型:Collection<ModifierInfo>

prop name

public prop name: String

功能:获取该 InstanceVariableInfo 对应的实例成员变量的名称。

类型:String

prop typeInfo

public prop typeInfo: TypeInfo

功能:获取该 InstanceVariableInfo 对应的实例成员变量的声明类型的类型信息。

类型:TypeInfo

func findAnnotation<T>() where T <: Annotation

public func findAnnotation<T>(): Option<T> where T <: Annotation

功能:尝试获取作用于该 InstanceVariableInfo 对应的实例成员变量且拥有给定限定名称的注解。

返回值:

  • Option<T> - 如果成功匹配则返回该注解,否则返回 None

func getValue(Any)

public func getValue(instance: Any): Any

功能:获取该 InstanceVariableInfo 对应的实例成员变量在给定实例中的值。

注意:

  • 目前,实例 instance 不支持 struct 类型的实例。
  • 目前,返回值不支持为 struct 类型的实例。

参数:

  • instance: Any - 实例。

返回值:

  • Any - 该实例成员变量在实例 instance 中的值。

异常:

  • IllegalTypeException - 如果实例 instance 的运行时类型与该实例成员变量信息所对应的实例成员变量所属的类型不严格相同,则抛出异常。

func hashCode()

public func hashCode(): Int64

功能:获取该实例成员变量信息的哈希值。

返回值:

  • Int64 - 该实例成员变量信息的哈希值。

func isMutable()

public func isMutable(): Bool

功能:判断该 InstanceVariableInfo 对应的实例成员变量是否可修改。

注意:

  • 如果实例成员变量被 var 修饰符所修饰,则该实例成员变量可被修改。
  • 如果实例成员变量被 let 修饰符所修饰,则该实例成员变量不可被修改。
  • 任何 struct 类型的实例的任何实例成员变量均不可修改。
  • 任何类型为 struct 的实例成员变量均不可修改。

返回值:

  • Bool - 如果该实例成员变量信息所对应的实例成员变量可被修改则返回 true ,否则返回 false

func setValue(Any, Any)

public func setValue(instance: Any, newValue: Any): Unit

功能:设置该 InstanceVariableInfo 对应的实例成员变量在给定实例中的值。

注意:

目前,实例 instance 不支持 struct 类型的实例。

参数:

  • instance: Any - 实例。
  • newValue: Any - 新值。

异常:

  • IllegalSetException - 如果该实例成员变量信息所对应的实例成员变量不可修改,则抛出异常。
  • IllegalTypeException - 如果实例 instance 的运行时类型与该实例成员变量信息所对应的实例成员变量所属的类型不严格相同,则抛出异常。
  • IllegalTypeException - 如果新值 newValue 的运行时类型不是该实例成员变量信息所对应的实例成员变量的声明类型的子类型,则抛出异常。

func toString()

public func toString(): String

功能:获取字符串形式的该实例成员变量信息。

返回值:

  • String - 字符串形式的该实例成员变量信息。

operator func ==(InstanceVariableInfo)

public operator func ==(that: InstanceVariableInfo): Bool

功能:判断该实例成员变量信息与给定的另一个实例成员变量信息是否相等。

参数:

返回值:

  • Bool - 如果该实例成员变量信息与 that 相等则返回 true,否则返回 false

operator func !=(InstanceVariableInfo)

public operator func !=(that: InstanceVariableInfo): Bool

功能:判断该实例成员变量信息与给定的另一个实例成员变量信息是否不等。

参数:

返回值:

  • Bool - 如果该实例成员变量信息与 that 不等则返回 true,否则返回 false

class InterfaceTypeInfo

public class InterfaceTypeInfo <: TypeInfo

功能:interface 类型的类型信息。

父类型:

prop sealedSubtypes

public prop sealedSubtypes: Collection<TypeInfo>

功能:如果该 InterfaceTypeInfo 所对应的 interface 类型拥有 sealed 语义,则获取该 interface 类型所在包内的所有子类型的类型信息,返回对应集合。

注意:

  • 如果该 interface 类型不拥有 sealed 语义,则返回空集合。
  • 如果该 interface 类型拥有 sealed 语义,那么获得的集合必不可能是空集合,因为该 interface 类型本身就是自己的子类型。

类型:Collection<TypeInfo>

func isSealed()

public func isSealed(): Bool

功能:判断该 InterfaceTypeInfo 所对应的 interface 类型是否拥有 sealed 语义。

返回值:

  • Bool - 如果该 interface 类型拥有 sealed 语义则返回 true,否则返回 false

class ModuleInfo

public class ModuleInfo <: Equatable<ModuleInfo> & Hashable & ToString

功能:描述模块信息,提供了仓颉动态模块加载、缓存能力以及模块内包信息查询能力。

仓颉动态模块是仓颉编译器生成的一种特殊二进制文件,这种文件可以被外部的仓颉程序在运行时被加载与使用。

仓颉动态库模块在不同操作系统中以共享库(.so 文件)、动态链接库(.dll 文件)等文件形式存在。

注意:

任一模块下不允许包含拥有相同限定名称的包。

父类型:

prop name

public prop name: String

功能:获取该 ModuleInfo 对应的模块的名称。

注意:

  • 模块的名称由被加载的模块的文件名决定,该文件名的格式为 lib<module_name>_<package_name>(.<package_name>)*
  • <module_name><package_name> 均不允许为空。
  • 由于当前实现的局限性,<module_name> 中如果包含下划线 "_" 字符,可能出现非预期的加载错误。

类型:String

prop packages

public prop packages: Collection<PackageInfo>

功能:获取该模块中包含的所有包。

类型:Collection<PackageInfo>

prop version

public prop version: String

功能:获取该 ModuleInfo 对应的模块的版本号。

注意:

由于目前动态库中尚无版本信息,获取到的版本号总是 1.0

类型:String

static func find(String)

public static func find(moduleName: String): Option<ModuleInfo>

功能:尝试在所有已加载的仓颉动态库模块中获取与给定模块名称匹配的模块的信息。

参数:

  • moduleName: String - 仓颉动态库模块名称。

返回值:

  • Option<ModuleInfo> - 如果匹配成功则返回该模块的信息,否则返回 None

static func load(String)

public static func load(path: String): ModuleInfo

功能:运行时动态加载指定路径下的一个仓颉动态库模块并获得该模块的信息。

注意:

  • 为了提升兼容性,路径 path 中的共享库文件名不需要后缀名(如 .so.dll 等)。
  • 由于当前实现局限性,具有相同模块名称的动态库不能被同时加载,否则将抛出异常。如 m/am/a.bm/a.c 这三个包所对应的共享库的加载是互斥的。

参数:

  • path: String - 共享库文件的绝对路径或相对路径。

异常:

func getPackageInfo(String)

public func getPackageInfo(packageName: String): PackageInfo

功能:尝试在该 ModuleInfo 对应的模块中获取与给定包的名称或限定名称匹配的包的信息。

参数:

  • packageName: String - 包的名称或限定名称。

返回值:

  • PackageInfo - 如果匹配成功则返回该包的信息。

异常:

func hashCode()

public func hashCode(): Int64

功能:获取该模块信息的哈希值。

返回值:

  • Int64 - 该模块信息的哈希值。

注意:

内部实现为该模块信息的名称和版本号字符串的哈希值。

func toString()

public func toString(): String

功能:获取字符串形式的该模块信息。

返回值:

  • String - 字符串形式的该模块信息。

注意:

内容为该模块的名称和版本号。

operator func !=(ModuleInfo)

public operator func !=(that: ModuleInfo): Bool

功能:判断该模块信息与给定的另一个模块信息是否不等。

参数:

  • that: ModuleInfo - 被比较相等性的另一个模块信息。

返回值:

  • Bool - 如果该模块信息与 that 不等则返回 true,否则返回 false

operator func ==(ModuleInfo)

public operator func ==(that: ModuleInfo): Bool

功能:判断该模块信息与给定的另一个模块信息是否相等。

参数:

  • that: ModuleInfo - 被比较相等性的另一个模块信息。

返回值:

  • Bool - 如果该模块信息与 that 相等则返回 true,否则返回 false

class PackageInfo

public class PackageInfo <: Equatable<PackageInfo> & Hashable & ToString

功能:描述包信息。

父类型:

prop functions

public prop functions: Collection<GlobalFunctionInfo>

功能:获取该 PackageInfo 对应的包中所有公开全局函数的信息所组成的列表。

类型:Collection<GlobalFunctionInfo>

prop name

public prop name: String

功能:获取该包信息所对应的包的名称。

注意:

包的名称不包含其所在的模块名称和其父包的名称,例如限定名称为 a/b.c.d 的包的名称是 d

类型:String

prop qualifiedName

public prop qualifiedName: String

功能:获取该 PackageInfo 对应的包的限定名称。

注意:

包的限定名称的格式是 (module_name/)?(default|package_name)(.package_name)*,例如限定名称为 a/b.c.d 的包位于模块 a 下的 b 包里的 c 包里。

类型:String

prop typeInfos

public prop typeInfos: Collection<TypeInfo>

功能:获取该 PackageInfo 对应的包中所有全局定义的公开类型的类型信息,返回对应集合。

注意:

目前该列表不包含所有反射尚未支持的类型。

类型:Collection<TypeInfo>

prop variables

public prop variables: Collection<GlobalVariableInfo>

功能:获取该 PackageInfo 对应的包中所有公开全局变量的信息所组成的列表。

类型:Collection<GlobalVariableInfo>

func getFunction(String, Array<TypeInfo>)

public func getFunction(name: String, parameterTypes: Array<TypeInfo>): GlobalFunctionInfo

功能:尝试在该 PackageInfo 对应的包中获取拥有给定函数名称且与给定形参类型信息列表匹配的公开全局函数的信息。

参数:

  • name: String - 全局函数的名称。
  • parameterTypes: Array<TypeInfo> - 形参类型信息列表。

异常:

func getTypeInfo(String)

public func getTypeInfo(qualifiedName: String): TypeInfo

功能:尝试在该 PackageInfo 对应的包中获取拥有给定类型名称的全局定义的公开类型的类型信息。

参数:

  • qualifiedName: String - 类型的限定名称

返回值:

  • TypeInfo - 如果成功匹配则返回该全局定义的公开类型的类型信息。

异常:

func getVariable(String)

public func getVariable(name: String): GlobalVariableInfo

功能:尝试在该 PackageInfo 对应的包中获取拥有给定变量名称的公开全局变量的信息。

参数:

  • name: String - 全局变量的名称。

异常:

func hashCode()

public func hashCode(): Int64

功能:获取该包信息的哈希值。

返回值:

  • Int64 - 该包信息的哈希值。

func toString()

public func toString(): String

功能:获取字符串形式的该包信息。

注意:

内部实现为该包信息的限定名称字符串。

返回值:

  • String - 字符串形式的该包信息。

operator func !=(PackageInfo)

public operator func !=(that: PackageInfo): Bool

功能:判断该包信息与给定的另一个包信息是否不等。

注意:

内部实现为比较两个包信息的限定名称是否相等。

参数:

  • that: PackageInfo - 被比较相等性的另一个包信息。

返回值:

  • Bool - 如果该包信息与 that 不等则返回 true,否则返回 false

operator func ==(PackageInfo)

public operator func ==(that: PackageInfo): Bool

功能:判断该包信息与给定的另一个包信息是否相等。

注意:

内部实现为比较两个包信息的限定名称是否相等。

参数:

  • that: PackageInfo - 被比较相等性的另一个包信息。

返回值:

  • Bool - 如果该包信息与 that 相等则返回 true,否则返回 false

class ParameterInfo

public class ParameterInfo <: Equatable<ParameterInfo> & Hashable & ToString

功能:描述函数形参信息。

父类型:

prop annotations

public prop annotations: Collection<Annotation>

功能:获取所有作用于该 ParameterInfo 对应的函数形参的注解,返回对应集合。

注意:

  • 如果无任何注解作用于该函数形参信息所对应的函数形参,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<Annotation>

prop index

public prop index: Int64

功能:获知该 ParameterInfo 对应的形参是其所在函数的第几个形参。

注意:

index 从0开始计数。

类型:Int64

prop name

public prop name: String

功能:获取该 ParameterInfo 对应的形参的名称。

类型:String

prop typeInfo

public prop typeInfo: TypeInfo

功能:获取该 ParameterInfo 对应的函数形参的声明类型所对应的类型信息。

类型:TypeInfo

func findAnnotation<T>() where T <: Annotation

public func findAnnotation<T>(): Option<T> where T <: Annotation

功能:尝试获取作用于该 ParameterInfo 对应的函数形参且拥有给定限定名称的注解。

返回值:

  • Option<T> - 如果成功匹配则返回该注解,否则返回 None

func hashCode()

public func hashCode(): Int64

功能:获取该函数形参信息的哈希值。

返回值:

  • Int64 - 该函数形参信息的哈希值。

func toString()

public func toString(): String

功能:获取字符串形式的该函数形参信息。

返回值:

  • String - 字符串形式的该函数形参信息。

operator func !=(ParameterInfo)

public operator func !=(that: ParameterInfo): Bool

功能:判断该函数形参信息与给定的另一个函数形参信息是否不等。

参数:

  • that: ParameterInfo - 被比较相等性的另一个函数形参信息。

返回值:

  • Bool - 如果该函数形参信息与 that 不等则返回 true,否则返回 false

operator func ==(ParameterInfo)

public operator func ==(that: ParameterInfo): Bool

功能:判断该函数形参信息与给定的另一个函数形参信息是否相等。

参数:

  • that: ParameterInfo - 被比较相等性的另一个函数形参信息。

返回值:

  • Bool - 如果该函数形参信息与 that 相等则返回 true,否则返回 false

class PrimitiveTypeInfo

public class PrimitiveTypeInfo <: TypeInfo

功能:描述原始数据类型的类型信息。

原始数据类型包括无类型(Nothing)、单元类型(Unit)、字符类型(Rune)、布尔类型(Bool),整形类型(Int8Int16Int32Int64IntNativeUInt8UInt16UInt32UInt64UIntNative)和浮点类型(Float16Float32Float64)。

注意:

目前尚不支持 Nothing 原始数据类型。

父类型:

class StaticFunctionInfo

public class StaticFunctionInfo <: Equatable<StaticFunctionInfo> & Hashable & ToString

功能:描述静态成员函数信息。

父类型:

prop annotations

public prop annotations: Collection<Annotation>

功能:获取所有作用于该 StaticFunctionInfo 对应的静态成员函数的注解,返回对应集合。

注意:

  • 如果无任何注解作用于该 StaticFunctionInfo 对应的静态成员函数,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<Annotation>

prop modifiers

public prop modifiers: Collection<ModifierInfo>

功能:获取该 StaticFunctionInfo 对应的静态成员函数所拥有的所有修饰符的信息,返回对应集合。

注意:

  • 如果该静态成员函数无任何修饰符,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 即便未被某修饰符修饰,如果拥有该修饰符的语义,该修饰符信息也将被包括在该集合中。

类型:Collection<ModifierInfo>

prop name

public prop name: String

功能:获取该 StaticFunctionInfo 对应的静态成员函数的名称。

注意:

构成重载的所有静态成员函数将拥有相同的名称。

类型:String

prop parameters

public prop parameters: InfoList<ParameterInfo>

功能:获取该 StaticFunctionInfo 对应的静态成员函数的形参信息列表。

类型:InfoList<ParameterInfo>

prop returnType

public prop returnType: TypeInfo

功能:获取该 StaticFunctionInfo 对应的静态成员函数的返回值类型的类型信息。

类型:TypeInfo

func apply(Array<Any>)

public func apply(args: Array<Any>): Any

功能:调用该 StaticFunctionInfo 对应静态成员函数,传入实参列表并返回调用结果。

注意:

目前,实参不支持 struct 类型的实例。

参数:

返回值:

  • Any - 该静态成员函数的调用结果。

异常:

  • IllegalArgumentException - 如果实参列表 args 中的实参的数目与该静态成员函数信息所对应的静态成员函数的形参列表中的形参的数目不等,则抛出异常。
  • IllegalTypeException - 如果实参列表 args 中的任何一个实参的运行时类型不是该静态成员函数信息所对应的静态成员函数的对应形参的声明类型的子类型,则抛出异常。
  • Exception - 如果被调用的静态成员函数信息所对应的静态成员函数内部抛出异常,则该异常将被封装为 Exception 异常并抛出。

func findAnnotation<T>() where T <: Annotation

public func findAnnotation<T>(): Option<T> where T <: Annotation

功能:尝试获取作用于 StaticFunctionInfo 对应的静态成员函数且拥有给定限定名称的注解。

返回值:

  • Option<T> - 如果成功匹配则返回该注解,否则返回 None

func hashCode()

public func hashCode(): Int64

功能:获取该静态成员函数信息的哈希值。

返回值:

  • Int64 - 该静态成员函数信息的哈希值。

func toString()

public func toString(): String

功能:获取字符串形式的该静态成员函数信息。

返回值:

  • String - 字符串形式的该静态成员函数信息。

operator func !=(StaticFunctionInfo)

public operator func !=(that: StaticFunctionInfo): Bool

功能:判断该静态成员函数信息与给定的另一个静态成员函数信息是否不等。

参数:

返回值:

  • Bool - 如果该静态成员函数信息与 that 不等则返回 true,否则返回 false

operator func ==(StaticFunctionInfo)

public operator func ==(that: StaticFunctionInfo): Bool

功能:判断该静态成员函数信息与给定的另一个静态成员函数信息是否相等。

参数:

返回值:

  • Bool - 如果该静态成员函数信息与 that 相等则返回 true,否则返回 false

class StaticPropertyInfo

public class StaticPropertyInfo <: Equatable<StaticPropertyInfo> & Hashable & ToString

静态成员属性信息。

父类型:

prop annotations

public prop annotations: Collection<Annotation>

功能:获取所有作用于该 StaticPropertyInfo 所对应的静态成员属性的注解所组成的集合。

注意:

  • 如果无任何注解作用于该静态成员属性信息所对应的静态成员属性,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<Annotation>

prop modifiers

public prop modifiers: Collection<ModifierInfo>

功能:获取该 StaticPropertyInfo 对应的静态成员属性所拥有的所有修饰符的信息,返回对应集合。

注意:

  • 如果该静态成员属性无任何修饰符,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 目前获取到的修饰符集合内容较为混乱,尚未统一。

类型:Collection<ModifierInfo>

prop name

public prop name: String

功能:获取该 StaticPropertyInfo 对应的静态成员属性的名称。

类型:String

prop typeInfo

public prop typeInfo: TypeInfo

功能:获取该 StaticPropertyInfo 对应的静态成员属性的声明类型的类型信息。

类型:TypeInfo

func findAnnotation<T>() where T <: Annotation

public func findAnnotation<T>(): Option<T> where T <: Annotation

功能:尝试获取作用于该 StaticPropertyInfo 对应的静态成员属性且拥有给定限定名称的注解。

返回值:

  • Option<T> - 如果成功匹配则返回该注解,否则返回 None

func getValue()

public func getValue(): Any

功能:获取该 StaticPropertyInfo 对应的静态成员属性的值。

注意:

如果该静态成员属性缺少合法实现,如 interface 类型中的抽象静态成员属性,则应抛出 UnsupportedException 异常,但由于后端尚未支持,故尚未实现。

返回值:

  • Any - 该静态成员属性的值。

func hashCode()

public func hashCode(): Int64

功能:获取该静态成员属性信息的哈希值。

返回值:

  • Int64 - 该静态成员属性信息的哈希值。

func isMutable()

public func isMutable(): Bool

功能:判断该静态成员属性信息所对应的静态成员属性是否可修改。

返回值:

  • Bool - 如果该静态成员属性信息所对应的静态成员属性可被修改则返回 true ,否则返回 false

注意:

  • 如果静态成员属性被 mut 修饰符所修饰,则该静态成员属性可被修改,否则不可被修改。
  • 任何 struct 类型的任何静态成员属性均不可修改。
  • 任何类型为 struct 的静态成员属性均不可修改。

func setValue(Any)

public func setValue(newValue: Any): Unit

功能:设置该 StaticPropertyInfo 对应的静态成员属性的值。

注意:

如果该静态成员属性缺少合法实现,如 interface 类型中的抽象静态成员属性,则应抛出 UnsupportedException 异常,但由于后端尚未支持,故尚未实现。

参数:

  • newValue: Any - 新值。

异常:

  • IllegalSetException - 如果该静态成员属性信息所对应的静态成员属性不可修改,则抛出异常。
  • IllegalTypeException - 如果新值 newValue 的运行时类型不是该静态成员属性信息所对应的静态成员属性的声明类型的子类型,则抛出异常。

func toString()

public func toString(): String

功能:获取字符串形式的该静态成员属性信息。

返回值:

  • String - 字符串形式的该静态成员属性信息。

operator func !=(StaticPropertyInfo)

public operator func !=(that: StaticPropertyInfo): Bool

功能:判断该静态成员属性信息与给定的另一个静态成员属性信息是否不等。

参数:

返回值:

  • Bool - 如果该静态成员属性信息与 that 不等则返回 true,否则返回 false

operator func ==(StaticPropertyInfo)

public operator func ==(that: StaticPropertyInfo): Bool

功能:判断该静态成员属性信息与给定的另一个静态成员属性信息是否相等。

参数:

返回值:

  • Bool - 如果该静态成员属性信息与 that 相等则返回 true,否则返回 false

class StaticVariableInfo

public class StaticVariableInfo <: Equatable<StaticVariableInfo> & Hashable & ToString

功能:描述静态成员变量信息。

父类型:

prop annotations

public prop annotations: Collection<Annotation>

功能:获取所有作用于该 StaticVariableInfo 对应的静态成员变量的注解,返回对应集合。

注意:

  • 如果无任何注解作用于该 StaticVariableInfo 对应的静态成员变量,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<Annotation>

prop modifiers

public prop modifiers: Collection<ModifierInfo>

功能:获取该 StaticVariableInfo 对应的静态成员变量所拥有的所有修饰符的信息,返回对应集合。

注意:

  • 如果该静态成员变量无任何修饰符,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 目前获取到的修饰符集合内容较为混乱,尚未统一。

类型:Collection<ModifierInfo>

prop name

public prop name: String

功能:获取该 StaticVariableInfo 对应的静态成员变量的名称。

类型:String

prop typeInfo

public prop typeInfo: TypeInfo

功能:获取该 StaticVariableInfo 对应的静态成员变量的声明类型的类型信息。

类型:TypeInfo

func findAnnotation<T>() where T <: Annotation

public func findAnnotation<T>(): Option<T> where T <: Annotation

功能:尝试获取作用于该 StaticVariableInfo 对应的静态成员变量且拥有给定限定名称的注解。

返回值:

  • Option<T> - 如果成功匹配则返回该注解,否则返回 None

func getValue()

public func getValue(): Any

功能:获取该 StaticVariableInfo 对应的静态成员变量的值。

返回值:

  • Any - 该静态成员变量的值。

注意:

  • 返回值不支持为 struct 类型。

func hashCode()

public func hashCode(): Int64

功能:获取该静态成员变量信息的哈希值。

返回值:

  • Int64 - 该静态成员变量信息的哈希值。

func isMutable()

public func isMutable(): Bool

功能:判断该 StaticVariableInfo 对应的静态成员变量是否可修改。

注意:

  • 如果静态成员变量被 var 修饰符所修饰,则该静态成员变量可被修改。
  • 如果静态成员变量被 let 修饰符所修饰,则该静态成员变量不可被修改。
  • 任何 struct 类型的任何静态成员变量均不可修改。
  • 任何类型为 struct 的静态成员变量均不可修改。

返回值:

  • Bool - 如果该静态成员变量信息所对应的静态成员变量可被修改则返回 true ,否则返回 false

func setValue(Any)

public func setValue(newValue: Any): Unit

功能:设置该 StaticVariableInfo 对应的静态成员变量的值。

参数:

  • newValue: Any - 新值。

异常:

  • IllegalSetException - 如果该 StaticVariableInfo 对应的静态成员变量不可修改,则抛出异常。
  • IllegalTypeException - 如果新值 newValue 的运行时类型不是该静态成员变量信息所对应的静态成员变量的声明类型的子类型,则抛出异常。

func toString()

public func toString(): String

功能:获取字符串形式的该静态成员变量信息。

返回值:

  • String - 字符串形式的该静态成员变量信息。

operator func !=(StaticVariableInfo)

public operator func !=(that: StaticVariableInfo): Bool

功能:判断该静态成员变量信息与给定的另一个静态成员变量信息是否不等。

参数:

返回值:

  • Bool - 如果该静态成员变量信息与 that 不等则返回 true,否则返回 false

operator func ==(StaticVariableInfo)

public operator func ==(that: StaticVariableInfo): Bool

功能:判断该静态成员变量信息与给定的另一个静态成员变量信息是否相等。

参数:

返回值:

  • Bool - 如果该静态成员变量信息与 that 相等则返回 true,否则返回 false

class StructTypeInfo

public class StructTypeInfo <: TypeInfo

功能:描述 struct 类型的类型信息。

父类型:

prop constructors

public prop constructors: Collection<ConstructorInfo>

功能:获取该 StructTypeInfo 对应的 struct 的所有公开构造函数信息,返回对应集合。

注意:

  • 如果该 struct 类型无任何公开构造函数,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<ConstructorInfo>

prop instanceVariables

public prop instanceVariables: Collection<InstanceVariableInfo>

功能:获取该 StructTypeInfo 对应的 struct 的所有公开实例成员变量信息,返回对应集合。

注意:

  • 如果该 struct 类型无任何公开实例成员变量,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<InstanceVariableInfo>

prop staticVariables

public prop staticVariables: Collection<StaticVariableInfo>

功能:获取该 StructTypeInfo 对应的 struct 的所有公开静态成员变量信息,返回对应集合。

注意:

  • 如果该 struct 类型无任何公开静态成员变量,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<StaticVariableInfo>

func construct(Array<Any>)

public func construct(args: Array<Any>): Any

功能:在该 StructTypeInfo 对应的 struct 类型中根据实参列表搜索匹配的构造函数并调用,传入实参列表,返回调用结果。

参数:

返回值:

  • Any - 该 struct 类型的实例。

异常:

注意:

由于 construct 函数本质上调用的是 apply 函数,而目前 struct 类型中定义的构造函数不支持被调用 apply 函数,故该函数目前无法正常使用

func getConstructor(Array<TypeInfo>)

public func getConstructor(parameterTypes: Array<TypeInfo>): ConstructorInfo

功能:尝试在该 StructTypeInfo 对应的 struct 类型中获取与给定形参类型信息列表匹配的公开构造函数的信息。

参数:

返回值:

  • ConstructorInfo - 如果成功匹配则返回该公开构造函数的信息。

异常:

func getInstanceVariable(String)

public func getInstanceVariable(name: String): InstanceVariableInfo

功能:给定变量名称,尝试获取该 StructTypeInfo 对应的 struct 类型中匹配的实例成员变量的信息。

参数:

  • name: String - 变量名称。

返回值:

异常:

func getStaticVariable(String)

public func getStaticVariable(name: String): StaticVariableInfo

功能:给定变量名称,尝试获取该 StructTypeInfo 对应的 struct 类型中匹配的静态成员变量的信息。

参数:

  • name: String - 变量名称。

返回值:

异常:

class TypeInfo

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

功能:TypeInfo 提供了所有数据类型通用的操作接口。开发者通常无需向下转型为更具体的数据类型,如 ClassTypeInfo 等,就能进行反射操作。

TypeInfo 的子类包括 PrimitiveTypeInfoStructTypeInfoClassTypeInfoInterfaceTypeInfo,分别对应基本数据类型,struct 数据类型,class 数据类型和 interface 数据类型的类型信息。

说明

类型的限定名称为(module_name/)?(default|package_name)(.package_name)*.(type_name)

父类型:

prop annotations

public prop annotations: Collection<Annotation>

功能:获取所有作用于该 TypeInfo 对应的类型的注解,返回对应集合。

注意:

  • 如果无任何注解作用于该类型信息所对应的类型,则返回空集合。
  • 该集合不保证遍历顺序恒定。

类型:Collection<Annotation>

prop instanceFunctions

public prop instanceFunctions: Collection<InstanceFunctionInfo>

功能:获取该 TypeInfo 对应类型的所有公开实例成员函数信息,返回对应集合。

注意:

  • 如果该 TypeInfo 对应的类型无任何公开实例成员函数,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 如果该类型信息所对应的类型是 structclass 类型,则该集合包含从其他 interface 类型继承而来的非抽象的实例成员函数的信息。

类型:Collection<InstanceFunctionInfo>

prop instanceProperties

public prop instanceProperties: Collection<InstancePropertyInfo>

功能:获取该 TypeInfo 对应类型的所有公开实例成员属性信息,返回对应集合。

注意:

  • 如果该 TypeInfo 对应的类型无任何公开实例成员属性,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 如果该类型信息所对应的类型是 structclass 类型,则该集合包含从其他 interface 类型继承而来的非抽象的实例成员属性的信息。

类型:Collection<InstancePropertyInfo>

prop modifiers

public prop modifiers: Collection<ModifierInfo>

功能:获取该 TypeInfo 对应的类型拥有的所有修饰符的信息,返回对应集合。

注意:

  • 如果该类型无任何修饰符,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • interface 类型默认拥有 open 语义,故返回的集合总是包含 open 修饰符。
  • 由于反射功能只能对所有被 public 访问控制修饰符所修饰的类型进行操作,故将忽略所有访问控制修饰符。

类型:Collection<ModifierInfo>

prop name

public prop name: String

功能:获取该 TypeInfo 对应的类型的名称。

注意:

  • 该名称不包含任何模块名和包名前缀。
  • 类型别名的类型信息就是实际类型其本身的类型信息,所以该函数并不会返回类型别名本身的名称而是实际类型的名称,如类型别名 Byte 的类型信息的名称是 UInt8 而不是 Byte

类型:String

prop qualifiedName

public prop qualifiedName: String

功能:获取该 TypeInfo 对应的类型的限定名称。

注意:

  • 限定名称包含模块名和包名前缀。
  • 特别的,仓颉内置数据类型,以及位于 std 模块 core 包下的所有类型的限定名称都是不带有任何模块名和包名前缀的。
  • 在缺省模块名和包名的上下文中定义的所有类型,均无模块名前缀,但拥有包名前缀"default",如:"default.MyType"。

类型:String

prop staticFunctions

public prop staticFunctions: Collection<StaticFunctionInfo>

功能:获取该 TypeInfo 对应类型的所有公开静态成员函数信息,返回对应集合。

注意:

  • 如果该 TypeInfo 对应的类型无任何公开静态成员函数,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 如果该类型信息所对应的类型是 structclassinterface 类型,则该集合包含从其他 interface 类型继承而来的非抽象的静态成员函数的信息。

类型:Collection<StaticFunctionInfo>

prop staticProperties

public prop staticProperties: Collection<StaticPropertyInfo>

功能:获取该 TypeInfo 对应类型的所有公开静态成员属性信息,返回对应集合。

注意:

  • 如果该 TypeInfo 对应的类型无任何公开静态成员属性,则返回空集合。
  • 该集合不保证遍历顺序恒定。
  • 如果该类型信息所对应的类型是 structclassinterface 类型,则该集合包含从其他 interface 类型继承而来的非抽象的静态成员属性的信息。

类型:Collection<StaticPropertyInfo>

prop superInterfaces

public prop superInterfaces: Collection<InterfaceTypeInfo>

功能:获取该 TypeInfo 对应的类型直接实现的所有 interface 类型的信息,返回对应集合。

注意:

  • 所有类型均默认直接实现 interface Any 类型。
  • 该集合不保证遍历顺序恒定。
  • 目前, struct 类型只支持获取到 interface Any 类型。

类型:Collection<InterfaceTypeInfo>

static func get(String)

public static func get(qualifiedName: String): TypeInfo

功能:获取给定的类型的限定名称所对应的类型的 TypeInfo

注意:

  • 未实例化的泛型类型的类型信息无法被获取。
  • 目前, 类型的限定名称 qualifiedName 不支持 Nothing 类型、函数类型、元组类型、enum 类型和带有泛型的 struct 类型的限定名称。

参数:

  • qualifiedName: String - 类型的限定名称。

返回值:

  • TypeInfo - 类型的限定名称 qualifiedName 所对应的类型的类型信息。

异常:

  • InfoNotFoundException - 如果无法获取与给定类型的限定名称 qualifiedName 匹配的类型所对应的类型信息,则抛出异常。

static func of(Any)

public static func of(a: Any): TypeInfo

功能:获取给定的任意类型的实例的运行时类型所对应的类型信息。

运行时类型是指在程序运行时,通过动态绑定确定的类型,运行时类型与实例对象相绑定。在继承等场景下运行时类型和静态类型可能不一致。

注意:

目前,实例 a 不支持运行时类型为函数类型,元组类型,enum 类型和带有泛型的 struct 类型的实例。

参数:

  • a: Any - 实例。

返回值:

  • TypeInfo - 实例 a 的运行时类型所对应的类型信息。

异常:

  • InfoNotFoundException - 如果无法获得实例 a 的运行时类型所对应的类型信息,则抛出异常。

static func of(Object)

public static func of(a: Object): ClassTypeInfo

功能:获取给定的 class 类型的实例的运行时类型所对应的 class 类型信息。

参数:

  • a: Object - class 类型的实例。

返回值:

  • ClassTypeInfo - class 类型的实例 a 的运行时类型所对应的 class 类型信息。

异常:

  • InfoNotFoundException - 如果无法获得实例 a 的运行时类型所对应的 class 类型信息,则抛出异常。

static func of<T>()

public static func of<T>(): TypeInfo

功能:获取给定类型对应的类型信息。

注意:

  • 目前,泛型 T 不支持 Nothing 类型、函数类型,元组类型,enum 类型和带有泛型的 struct 类型。
  • T 支持传入类型别名,包括内置类型别名(如 IntUIntRune 等)与用户自定义类型别名。

返回值:

  • TypeInfo - T 类型对应的类型信息。

异常:

func findAnnotation<T>() where T <: Annotation

public func findAnnotation<T>(): Option<T> where T <: Annotation

功能:尝试获取作用于该 TypeInfo 对应的类型且拥有给定限定名称的注解。

返回值:

  • Option<T> - 如果成功匹配则返回该注解,否则返回 None

func getInstanceFunction(String, Array<TypeInfo>)

public func getInstanceFunction(name: String, parameterTypes: Array<TypeInfo>): InstanceFunctionInfo

功能:给定函数名称与函数形参类型列表所对应的类型信息列表,尝试获取该类型中匹配的实例成员函数的信息。

参数:

  • name: String - 函数名称。
  • parameterTypes: Array<TypeInfo> - 函数形参类型列表所对应的类型信息列表。

返回值:

异常:

func getInstanceProperty(String)

public func getInstanceProperty(name: String): InstancePropertyInfo

功能:尝试获取该类型中与给定属性名称匹配的实例成员属性的信息。

参数:

  • name: String - 属性名称。

返回值:

异常:

func getStaticFunction(String, Array<TypeInfo>)

public func getStaticFunction(name: String, parameterTypes: Array<TypeInfo>): StaticFunctionInfo

功能:通过给定函数名称与函数形参类型列表所对应的类型信息列表,尝试获取该类型中匹配的静态成员函数的信息。

参数:

  • name: String - 函数名称。
  • parameterTypes: Array<TypeInfo> - 函数形参类型列表所对应的类型信息列表。

返回值:

异常:

func getStaticProperty(String)

public func getStaticProperty(name: String): StaticPropertyInfo

功能:尝试获取该类型中与给定属性名称匹配的静态成员属性的信息。

参数:

  • name: String - 属性名称。

返回值:

异常:

func hashCode()

public func hashCode(): Int64

功能:获取该类型信息的哈希值。

注意:

内部实现为该类型信息的限定名称字符串的哈希值。

返回值:

  • Int64 - 该类型信息的哈希值。

func isSubtypeOf(TypeInfo)

public func isSubtypeOf(supertype: TypeInfo): Bool

功能:判断当前 TypeInfo 实例对应的类型是否是参数中指定的 TypeInfo 实例表示的类型的子类型。

注意:

由于目前所有 struct 类型均无法获得其实现的 interface 类型,所以在做 struct 是否为某 interface 的子类型的判断时总是返回 false

参数:

  • supertype: TypeInfo - 目标类型的类型信息。

返回值:

  • Bool - 如果该 TypeInfo 对应的类型是 supertype 所对应的类型的子类型则返回 true,否则返回 false

func toString()

public func toString(): String

功能:获取字符串形式的该类型信息。

注意:

内部实现为该类型信息的限定名称字符串。

返回值:

  • String - 字符串形式的该类型信息。

operator func !=(TypeInfo)

public operator func !=(that: TypeInfo): Bool

功能:判断该类型信息与给定的另一个类型信息是否不等。

参数:

  • that: TypeInfo - 被比较相等性的另一个类型信息。

返回值:

  • Bool - 如果该类型信息的限定名称与 that 不等则返回 true,否则返回 false

operator func ==(TypeInfo)

public operator func ==(that: TypeInfo): Bool

功能:判断该类型信息与给定的另一个类型信息是否相等。

参数:

  • that: TypeInfo - 被比较相等性的另一个类型信息。

返回值:

  • Bool - 如果该类型信息的限定名称与 that 相等则返回 true,否则返回 false

枚举

enum ModifierInfo

public enum ModifierInfo <: Equatable<ModifierInfo> & Hashable & ToString  {
    | Open
    | Override
    | Redef
    | Abstract
    | Sealed
    | Mut
    | Static
}

修饰符信息。

注意:

由于开发者通过反射功能获取到的类型信息均来自于公开的类型,这些类型都必定拥有 public 的访问控制语义,因此修饰符信息并不包含任何访问控制相关的修饰符。

父类型:

Abstract

Abstract

功能:表示 abstract 修饰符。

Mut

Mut

功能:表示 mut 修饰符。

Open

Open

功能:表示 open 修饰符。

Override

Override

功能:表示 override 修饰符。

Redef

Redef

功能:表示 redef 修饰符。

Sealed

Sealed

功能:表示 sealed 修饰符。

Static

Static

功能:表示 static 修饰符。

func hashCode()

public func hashCode(): Int64

功能:获取该修饰符信息的哈希值。

返回值:

  • Int64 - 该修饰符信息的哈希值。

注意:

内部实现为该修饰符关键字字符串的哈希值。

func toString()

public func toString(): String

功能:获取字符串形式的该修饰符信息。

返回值:

  • String - 字符串形式的该修饰符信息。

注意:

字符串形式的修饰符信息即为修饰符关键字的标识符。

operator func ==(ModifierInfo)

public operator func ==(that: ModifierInfo): Bool

功能:判断该修饰符信息与给定的另一个修饰符信息是否相等。

参数:

  • that: ModifierInfo - 被比较相等性的另一个修饰符信息。

返回值:

  • Bool - 如果该修饰符信息与 that 相等则返回 true,否则返回 false

注意:

修饰符信息的相等性的语义等价于 enum 类型实例的相等性的语义。

operator func !=(ModifierInfo)

public operator func !=(that: ModifierInfo): Bool

功能:判断该修饰符信息与给定的另一个修饰符信息是否不等。

注意:

修饰符信息的相等性的语义等价于 enum 类型实例的相等性的语义。

参数:

  • that: ModifierInfo - 被比较相等性的另一个修饰符信息。

返回值:

  • Bool - 如果该修饰符信息与 that 不等则返回 true,否则返回 false

异常类

class IllegalSetException

public class IllegalSetException <: ReflectException {
    public init()
    public init(message: String)
}

功能:IllegalSetException 为对不可变类型进行更改异常。

父类型:

init()

public init()

功能:创建 IllegalSetException 实例。

init(String)

public init(message: String)

功能:根据异常信息创建 IllegalSetException 实例。

参数:

  • message: String - 异常信息。

class IllegalTypeException

public class IllegalTypeException <: ReflectException {
    public init()
    public init(message: String)
}

功能:IllegalTypeException 为类型不匹配异常。

父类型:

init()

public init()

功能:创建 IllegalTypeException 实例。

init(String)

public init(message: String)

功能:根据异常信息创建 IllegalTypeException 实例。

参数:

  • message: String - 异常信息。

class InfoNotFoundException

public class InfoNotFoundException <: ReflectException {
    public init()
    public init(message: String)
}

功能:InfoNotFoundException 为无法找到对应信息异常。

父类型:

init()

public init()

功能:创建 InfoNotFoundException 实例。

init(String)

public init(message: String)

功能:根据异常信息创建 InfoNotFoundException 实例。

参数:

  • message: String - 异常信息。

class InvocationTargetException

public class InvocationTargetException <: ReflectException {
    public init()
    public init(message: String)
}

功能:InvocationTargetException 为调用函数包装异常。

父类型:

init()

public init()

功能:创建 InvocationTargetException 实例。

init(String)

public init(message: String)

功能:根据异常信息创建 InvocationTargetException 实例。

参数:

  • message: String - 异常信息。

class MisMatchException

public class MisMatchException <: ReflectException {
    public init()
    public init(message: String)
}

功能:MisMatchException 为调用对应函数抛出异常。

父类型:

init()

public init()

功能:创建 MisMatchException 实例。

init(String)

public init(message: String)

功能:根据异常信息创建 MisMatchException 实例。

参数:

  • message: String - 异常信息。

class ReflectException

public open class ReflectException <: Exception {
    public init()
    public init(message: String)
}

功能:ReflectException 为 Reflect 包的基异常类。

父类型:

init()

public init()

功能:创建 ReflectException 实例。

init(String)

public init(message: String)

功能:根据异常信息创建 ReflectException 实例。

参数:

  • message: String - 异常信息。

注解的使用

通过反射获取实例上注解的值。

代码如下:

import std.reflect.*

main() {
    let ti = TypeInfo.of(Test())
    let annotation = ti.findAnnotation<A>()
    if (let Some(a) <- annotation) {
        println(a.name)
    }
}

@A["Annotation"]
public class Test {}

@Annotation
public class A {
    const A(let name: String) {}
}

运行结果如下:

Annotation

动态加载的使用

在项目根目录 myProject 下分别创建两个目录 myModuleDirectorymyExecutableDirectory,分别在其中使用 cjpm 构建仓颉动态库模块和可执行文件,该可执行文件将在动态加载该仓颉动态库模块后通过反射对动态库模块中的全局变量进行操作。

$ mkdir -p myProject && cd myProject
$ mkdir -p myPackage && cd myPackage
# 在 myPackage 目录下执行该命令初始化该仓颉动态库模块的目录结构,如此便可对 myPackage 下的仓颉功能进行动态编译。
$ cjpm init --type=dynamic --name myPackage
cjpm init success
$ cat << EOF > src/myPackage.cj
package myPackage

public var myPublicGlobalVariable0: Int64 = 2333
public let myPublicGlobalVariable1 = MyPublicType("Initializing myPublicGlobalVariable1 in myPackage")

public class MyPublicType {
    public MyPublicType(message: String) {
        println(message)
    }

    public static func myPublicStaticMemeberFunction() {
        println("myPackage.MyPublicType.myPublicStaticMemeberFunction is called.")
    }

    static let myStaticVariable = MyPublicType("Initializing myStaticVariable in myPackage.MyPublicType")
}
EOF
# 使用 cjpm 构建该仓颉动态库模块。
$ cjpm build
cjpm build success
$ cd .. && mkdir -p myExecutableDirectory && cd myExecutableDirectory
$ cjpm init
$ cat << EOF > src/main.cj
package myExecutableDirectory
import std.reflect.*

main(): Unit {
    // 加载仓颉动态库。
    let myModule = ModuleInfo.load("../myPackage/target/release/myPackage/libmyPackage.so")
    println(myModule.name)
    let myPackage = myModule.getPackageInfo("myPackage")
    println(myPackage.name)
    TypeInfo.get("myPackage.MyPublicType") |> println

    let myPublicGlobalVariable0 = myPackage.getVariable("myPublicGlobalVariable0")
    (myPublicGlobalVariable0.getValue() as Int64).getOrThrow() |> println
    myPublicGlobalVariable0.setValue(666)
    (myPublicGlobalVariable0.getValue() as Int64).getOrThrow() |> println
}
EOF

# 构建并运行可执行程序。
$ cjpm run
Initializing myPublicGlobalVariable1 in myPackage
Initializing myStaticVariable in myPackage.MyPublicType
myPackage
myPackage
myPackage.MyPublicType
2333
666

cjpm run finished
$ tree ..
..
├── myExecutableDirectory
│   ├── cjpm.lock
│   ├── cjpm.toml
│   ├── src
│   │   └── main.cj
│   └── target
│       └── release
│           ├── bin
│           │   ├── main
│           │   ├── myExecutableDirectory.bchir2
│           │   └── myExecutableDirectory.cjo
│           ├── myExecutableDirectory
│           │   └── incremental-cache.json
│           └── myExecutableDirectory-cache.json
└── myPackage
    ├── cjpm.lock
    ├── cjpm.toml
    ├── src
    │   └── myPackage.cj
    └── target
        └── release
            ├── bin
            ├── myPackage
            │   ├── incremental-cache.json
            │   ├── libmyPackage.so
            │   ├── myPackage.bchir2
            │   └── myPackage.cjo
            └── myPackage-cache.json

12 directories, 16 files

注意:

由于当前 ModuleInfo.load 函数根据文件名来判断包名,因此不允许修改该文件名,否则将抛出无法找到仓颉动态库模块文件的异常。

成员信息的使用

import std.reflect.*

public class Rectangular {
    public var length = 4
    public var width = 5
    public func area(): Int64 {
        return length * width
    }
}

main(): Unit {
    let a = Rectangular()
    let ty = TypeInfo.of(a)
    const zl = 3
    let members = ty.instanceVariables.toArray()
    println((members[0].getValue(a) as Int64).getOrThrow())
    println((members[1].getValue(a) as Int64).getOrThrow())
    members[0].setValue(a, zl)
    members[1].setValue(a, zl)
    println((members[0].getValue(a) as Int64).getOrThrow())
    println((members[1].getValue(a) as Int64).getOrThrow())
    println(a.area())
    let funcs = ty.instanceFunctions.toArray()
    if (funcs[0].returnType.name == "Int64"){
        println("The area of the square is ${zl**2}")
    }
    return
}

运行结果如下:

4
5
3
3
9
The area of the square is 9

TypeInfo 的使用

package Demo

import std.reflect.*

public class Foo {
    public let item = 0

    public func f() {}
}

main() {
    let a = Foo()
    let ty: TypeInfo = TypeInfo.of(a)
    println(ty.name)
    println(ty.qualifiedName)
    println(ty.instanceFunctions.size)
}

运行结果如下:

Foo
Demo.Foo
1

std.regex 包

功能介绍

regex 包使用正则表达式分析处理文本的能力(仅支持 ASCII 编码字符串),支持查找、分割、替换、验证等功能。

regex 规则集

当前仓颉的正则表达式仅支持以下规则,使用不支持的规则会导致输出结果与预期不符。

字符描述
\将下一个字符标记为一个特殊字符(File Format Escape,清单见本表)、或一个原义字符(Identity Escape,有^$()*+?.[{\|共计 12 个)、或一个向后引用(backreferences)。例如,“n”匹配字符“n”。\n匹配一个换行符。序列\匹配\,而(则匹配(
^匹配输入字符串的开始位置。如果设置了 RegexOption 中的多行模式 multiLine(),^也匹配\n\r之后的位置。
$匹配输入字符串的结束位置。
*匹配前面的子表达式零次或多次。例如,zo*能匹配zzo以及zoo*等价于{0,}
+匹配前面的子表达式一次或多次。例如,zo+能匹配zo以及zoo,但不能匹配z+等价于{1,}
?匹配前面的子表达式零次或一次。例如,do(es)?可以匹配does中的dodoes?等价于{0,1}
{n}n 是一个非负整数。匹配确定的 n 次。例如,o{2}不能匹配Bob中的o,但是能匹配food中的两个o
{n,}n 是一个非负整数。至少匹配 n 次。例如,o{2,}不能匹配Bob中的o,但能匹配foooood中的所有oo{1,}等价于o+o{0,}则等价于o*
{n,m}m 和 n 均为非负整数,其中 n<=m。最少匹配 n 次且最多匹配 m 次。例如,o{1,3}将匹配fooooood中的前三个oo{0,1}等价于o?。请注意在逗号和两个数之间不能有空格。
?非贪心量化(Non-greedy quantifiers):当该字符紧跟在任何一个其他重复修饰符(*,+,?,{n},{n,},{n,m})后面时,匹配模式是非贪婪的。非贪婪模式尽可能少的匹配所搜索的字符串,而默认的贪婪模式则尽可能多的匹配所搜索的字符串。例如,对于字符串ooooo+?将匹配单个o,而o+将匹配所有o
.匹配除\n之外的任何单个字符。要匹配包括\n在内的任何字符,请使用像(.\|\n)的模式。
(pattern)匹配 pattern 并获取这一匹配的子字符串。该子字符串用于向后引用。所获取的匹配可以从产生的 Matches 集合中得到。要匹配圆括号字符,请使用\(\)。可带数量后缀。
x\|y没有包围在()里,其范围是整个正则表达式。例如,z|food 能匹配zfood。(?:z|f)ood 则匹配zoodfood
[xyz]字符集合(character class)。匹配所包含的任意一个字符。例如,[abc]可以匹配plain中的a。特殊字符仅有反斜线\保持特殊含义,用于转义字符。其它特殊字符如星号、加号、各种括号等均作为普通字符。脱字符^如果出现在首位则表示负值字符集合;如果出现在字符串中间就仅作为普通字符。连字符 - 如果出现在字符串中间表示字符范围描述;如果如果出现在首位(或末尾)则仅作为普通字符。右方括号应转义出现,也可以作为首位字符出现。
[^xyz]排除型字符集合(negated character classes)。匹配未列出的任意字符。例如,[^abc]可以匹配plain中的plin
[a-z]字符范围。匹配指定范围内的任意字符。例如,[a-z]可以匹配az范围内的任意小写字母字符。
[^a-z]排除型的字符范围。匹配任何不在指定范围内的任意字符。例如,[^a-z]可以匹配任何不在az范围内的任意字符。
\b匹配一个单词边界,也就是指单词和空格间的位置。例如,er\b可以匹配never中的er,但不能匹配verb中的er
\B匹配非单词边界。er\B能匹配verb中的er,但不能匹配never中的er
\d匹配一个数字字符。等价于[0-9]
\D匹配一个非数字字符。等价于[^0-9]
\f匹配一个换页符。等价于\x0c
\n匹配一个换行符。等价于\x0a
\r匹配一个回车符。等价于\x0d
\s匹配任何空白字符,包括空格、制表符、换页符等等。等价于[\f\n\r\t\v]
\S匹配任何非空白字符。等价于[^\f\n\r\t\v]
\t匹配一个制表符。等价于\x09
\v匹配\n\v\f\r\x85
\w匹配包括下划线的任何单词字符。等价于[A-Za-z0-9_]
\W匹配任何非单词字符。等价于[^A-Za-z0-9_]
\xnm十六进制转义字符序列。匹配两个十六进制数字 nm 表示的字符。例如,\x41匹配A。正则表达式中可以使用 ASCII 码。
\num向后引用(back-reference)一个子字符串(substring),该子字符串与正则表达式的第 num 个用括号围起来的捕捉群(capture group)子表达式(subexpression)匹配。其中 num 是从 1 开始的十进制正整数,Regex 捕获组上限为 63。例如:(.)\1匹配两个连续的相同字符。
(?:pattern)匹配 pattern 但不获取匹配的子字符串(shy groups),也就是说这是一个非获取匹配,不存储匹配的子字符串用于向后引用。这在使用或字符(\|)来组合一个模式的各个部分是很有用。
(?=pattern)正向肯定预查(look ahead positive assert),在任何匹配 pattern 的字符串开始处匹配查找字符串。这是一个非获取匹配,也就是说,该匹配不需要获取供以后使用。例如,Windows(?=95\|98\|NT\|2000)能匹配Windows2000中的Windows,但不能匹配Windows3.1中的Windows。预查不消耗字符,也就是说,在一个匹配发生后,在最后一次匹配之后立即开始下一次匹配的搜索,而不是从包含预查的字符之后开始。
(?!pattern)正向否定预查(negative assert),在任何不匹配 pattern 的字符串开始处匹配查找字符串。这是一个非获取匹配,也就是说,该匹配不需要获取供以后使用。例如Windows(?!95\|98\|NT\|2000)能匹配Windows3.1中的Windows,但不能匹配Windows2000中的Windows。预查不消耗字符,也就是说,在一个匹配发生后,在最后一次匹配之后立即开始下一次匹配的搜索,而不是从包含预查的字符之后开始。
(?<=pattern)反向(look behind)肯定预查,与正向肯定预查类似,只是方向相反。例如,(?<=95\|98\|NT\|2000)Windows能匹配2000Windows中的Windows,但不能匹配3.1Windows中的Windows
(?<!pattern)反向否定预查,与正向否定预查类似,只是方向相反。例如(?<!95\|98\|NT\|2000)Windows能匹配3.1Windows中的Windows,但不能匹配2000Windows中的Windows
(?i)通过规则指定部分规则忽略大小写。当前 Regex 仅支持全局忽略大小写,当该选项被指定时,会被当做全局忽略大小写对待。
(?-i)通过规则指定部分规则大小写敏感。 当前 Regex 默认大小写敏感,该选项仅做编译兼容处理,不做敏感处理。
+单独一个加号,不是转义的\+
*单独一个星号,不是转义的\*
-单独一个减号,不是转义的\-
]单独一个右中括号,不是转义的\]
}单独一个右大括号,不是转义的\}
[[:alpha:]]表示任意大小写字母。
[[:^alpha:]]表示除大小写字母以外的任意字符。
[[:lower:]]表示任意小写字母。
[[:^lower:]]表示除小写字母以外的任意字符。
[[:upper:]]表示任意大写字母。
[[:^upper:]]表示除大写字母以外的任意字符。
[[:digit:]]表示0到9之间的任意单个数字。
[[:^digit:]]表示除0到9之间的单个数字以外的任意字符。
[[:xdigit:]]表示十六进制的字母和数字。
[[:^xdigit:]]表示除十六进制的字母和数字以外的任意字符。
[[:alnum:]]表示任意数字或字母。
[[:^alnum:]]表示除数字或字母以外的任意字符。
[[:space:]]表示任意空白字符,包括"空格"、"tab键"等。
[[:^space:]]表示除空白字符以外的任意字符。
[[:punct:]]表示任意标点符号。
[[:^punct:]]表示除任意标点符号以外的任意字符。

在仓颉中,还存在一些特殊的规则:

  1. ?+* 前面的字符不可量化时,会被忽略;特例:(*|** 开头时 * 会被视为普通字符。

  2. *? 在匹配全部 *? 之前的字符组成的字符串时,会匹配不到该字符。

  3. 正则表达式的捕获组的最大个数为 63,编译后的最大规则长度为 65535。

  4. 暂不支持的场景:((pattern1){m1,n1}pattern2){m2,n2},即:

    • 组定义 1 被{m1,n1}修饰;
    • 组定义 1 被组定义 2 包裹;
    • 组定义 2 被{m2,n2}修饰。

API 列表

类名功能
Matcher正则匹配器,用于扫描输入序列并进行匹配。
MatchData存储正则表达式匹配结果,并提供对正则匹配结果进行查询的函数。
Regex用来指定编译类型和输入序列。
RegexOption用于指定正则匹配的模式。

结构体

结构体名功能
Position用来存储位置信息,表示的是一个前闭后开区间。

异常类

异常类名功能
RegexException提供 regex 相关的异常处理。

class MatchData

public class MatchData {}

功能:存储正则表达式匹配结果,并提供对正则匹配结果进行查询的函数。

func groupNumber()

public func groupNumber(): Int64

功能:获取捕获组的个数。

返回值:

  • Int64 - 捕获组的个数。

func matchPosition()

public func matchPosition(): Position

功能:获取上一次匹配到的子字符串在输入字符串中起始位置和末尾位置的索引。

返回值:

  • Position - 匹配结果位置信息。

func matchPosition(Int64)

public func matchPosition(group: Int64): Position

功能:根据给定的索引获取上一次匹配中该捕获组匹配到的子字符串在输入字符串中的位置信息。

参数:

  • group: Int64 - 指定组。

返回值:

  • Position - 对应捕获组的位置信息。

异常:

func matchStr()

public func matchStr(): String

功能:获取上一次匹配到的子字符串,结果与调用 matchStr(0) 相同。

返回值:

  • String - 匹配到的子字符串。

异常:

func matchStr(Int64)

public func matchStr(group: Int64): String

功能:根据给定的索引获取上一次匹配中该捕获组匹配到的子字符串。

捕获组的索引从 1 开始,索引为 0 表示获取整个正则表达式的匹配结果。

参数:

  • group: Int64 - 指定组。

返回值:

  • String - 匹配到的子字符串。

异常:

class Matcher

public class Matcher {
    public init(re: Regex, input: String)
}

功能:正则匹配器,用于扫描输入序列并进行匹配。

注意:

  • 要匹配的字符串最大长度不得超过 231-1。
  • 要使用 replaceAll 替换的字符串最大长度不得超过 230-2。

init(Regex, String)

public init(re: Regex, input: String)

功能:使用传入的正则表达式和输入序列创建 Matcher 实例。

参数:

  • re: Regex - 正则表达式。
  • input: String - 输入序列。

异常:

func allCount()

public func allCount(): Int64

功能:获取正则表示式的匹配结果总数。

默认是从头到尾匹配的结果,使用了 setRegion 后只会在设置的范围内查找。

返回值:

  • Int64 - 匹配结果总数。

func find()

public func find(): Option<MatchData>

功能:自当前字符串偏移位置起,查找第一个匹配到的子序列。

find 调用一次,当前偏移位置为最新一次匹配到的子序列后第一个字符位置,下次调用时,find 从当前位置开始匹配。

返回值:

异常:

func find(Int64)

public func find(index: Int64): Option<MatchData>

功能:重置该匹配器索引位置,从 index 对应的位置处开始对输入序列进行匹配,返回匹配到的子序列。

返回值:

异常:

func findAll()

public func findAll(): Option<Array<MatchData>>

功能:对整个输入序列进行匹配,查找所有匹配到的子序列。

返回值:

异常:

  • RegexException - 当重置匹配器内存分配失败或申请内存失败时,抛出异常。

func fullMatch()

public func fullMatch(): Option<MatchData>

功能:对整个输入序列进行匹配。

返回值:

func getString()

public func getString(): String

功能:获取匹配序列。

返回值:

func matchStart()

public func matchStart(): Option<MatchData>

功能:对输入序列的头部进行匹配。

返回值:

异常:

func region()

public func region(): Position

功能:返回匹配器的区域设置。

返回值:

  • Position - 匹配器的区域设置。

func replace(String)

public func replace(replacement: String): String

功能:自当前字符串偏移位置起,匹配到的第一个子序列替换为目标字符串,并将当前索引位置设置到匹配子序列的下一个位置。

参数:

  • replacement: String - 指定替换字符串。

返回值:

  • String - 替换后字符串。

异常:

func replace(String, Int64)

public func replace(replacement: String, index: Int64): String

功能:从输入序列的 index 位置起匹配正则,将匹配到的第一个子序列替换为目标字符串。

参数:

  • replacement: String - 指定替换字符串。
  • index: Int64 - 匹配开始位置。

返回值:

  • String - 替换后字符串。

异常:

func replaceAll(String)

public func replaceAll(replacement: String): String

功能:将输入序列中所有与正则匹配的子序列替换为给定的目标字符串。

参数:

  • replacement: String - 指定替换字符串。

返回值:

  • String - 替换后的字符串。

异常:

  • RegexException - 当重置匹配器失败时,或者 c 侧申请内存失败,或者替换字符串时发生了 GC 时,抛出异常。
  • IllegalArgumentException - 当 replacement 长度大于 230-2,或者 replacement 包含空字符时,抛出异常。

func replaceAll(String, Int64)

public func replaceAll(replacement: String, limit: Int64): String

功能:将输入序列中与正则匹配的前 limit 个子序列替换为给定的替换字符串。

参数:

  • limit: Int64 - 替换次数。如果 limit 等于 0,返回原来的序列;如果 limit 为负数,将尽可能多次的替换。
  • replacement: String - 指定替换字符串。

返回值:

  • String - 替换后字符串。

异常:

  • RegexException - 当重置匹配器失败时,或者 c 侧申请内存失败,或者替换字符串时发生了 GC 时,抛出异常。
  • IllegalArgumentException - 当 replacement 长度大于 230-2,或者 replacement 包含空字符时,抛出异常。

func resetRegion()

public func resetRegion(): Matcher

功能:重置匹配器开始位置和结束位置。

返回值:

异常:

func resetString(String)

public func resetString(input: String): Matcher

功能:重设匹配序列,并重置匹配器。

参数:

  • input: String - 新的匹配序列。

返回值:

异常:

func setRegion(Int64, Int64)

public func setRegion(beginIndex: Int64, endIndex: Int64): Matcher

功能:设置匹配器可搜索区域的位置信息,具体位置由指定的 begin 和 end 决定。

参数:

  • beginIndex: Int64 - 区域开始位置。
  • endIndex: Int64 - 区域结束位置。

返回值:

异常:

  • IndexOutOfBoundsException - 当 beginIndex 小于0,或 beginIndex 大于输入序列的 size 时,抛出异常;当 endIndex 小于0,或 endIndex 大于输入序列的 size 时,抛出异常;当 beginIndex 大于 endIndex 时,抛出异常。

func split()

public func split(): Array<String>

功能:将给定的输入序列根据正则尽可能的分割成多个子序列。

返回值:

func split(Int64)

public func split(limit: Int64): Array<String>

功能:将给定的输入序列根据正则尽可能的分割成多个子序列 (最多分割成 limit 个子串)。

参数:

  • limit: Int64 - 最多分割的子串个数。

返回值:

  • Array<String> - 如果 limit>0,返回最多 limit 个子串;如果 limit<=0,返回最大可分割数个子串。

异常:

class Regex

public class Regex {
    public init(s: String)
    public init(s: String, option: RegexOption)
}

功能:用来指定编译类型和输入序列。

正则匹配规则详见 regex 规则集。

init(String)

public init(s: String)

功能:创建 Regex 实例, 匹配模式为普通模式。

参数:

  • s: String - 正则表达式。

异常:

init(String, RegexOption)

public init(s: String, option: RegexOption)

功能:使用指定的模式创建一个 Regex 实例。

参数:

异常:

func matcher(String)

public func matcher(input: String): Matcher

功能:创建匹配器。

参数:

  • input: String - 要匹配的字符串,字符串长度最大 231 - 1。

返回值:

异常:

func matches(String)

public func matches(input: String): Option<MatchData>

功能:创建匹配器,并将入参 input 与正则表达式进行完全匹配。

参数:

  • input: String - 要匹配的字符串,字符串长度最大 231 - 1。

返回值:

异常:

func string()

public func string(): String

功能:获取正则的输入序列。

返回值:

class RegexOption

public class RegexOption <: ToString {
    public init()
}

功能:用于指定正则匹配的模式。

默认的正则匹配算法为 NFA ,匹配运行次数上限为 1000000。

父类型:

init()

public init()

功能:创建一个 RegexOption 实例, 匹配模式为普通模式(NORMAL)。

func ignoreCase()

public func ignoreCase(): RegexOption

功能:修改 RegexOption,修改匹配模式为忽略大小写(IGNORECASE)。

返回值:

func multiLine()

public func multiLine(): RegexOption

功能:修改 RegexOption,修改匹配模式为多行文本模式(MULTILINE)。

返回值:

func toString()

public func toString(): String

功能:获取 RegexOption 当前表示的正则匹配模式。

返回值:

  • String - 正则匹配模式。

结构体

struct Position

public struct Position

功能:用来存储位置信息,表示的是一个前闭后开区间。

prop end

public prop end: Int64

功能:区间结束位置。

类型:Int64

prop start

public prop start: Int64

功能:区间开始位置。

类型:Int64

异常

class RegexException

public class RegexException <: Exception {
    public init()
    public init(message: String)
}

功能:提供正则的异常处理。

父类型:

init()

public init()

功能:创建 RegexException 实例。

init(String)

public init(message: String)

功能:根据异常信息创建 RegexException 实例。

参数:

  • message: String - 异常提示信息。

regex 示例

RegexOption 获取当前正则匹配模式

import std.regex.*

main(): Unit {
    var a = RegexOption()
    println(a.toString())
    a = RegexOption().ignoreCase()
    println(a.toString())
    a = RegexOption().multiLine()
    println(a.toString())
    a = RegexOption().multiLine().ignoreCase()
    println(a.toString())
}

运行结果:

NORMAL,NFA
IGNORECASE,NFA
MULTILINE,NFA
MULTILINE,IGNORECASE,NFA

Regex 匹配大小写

import std.regex.*

main(): Unit {
    let r1 = Regex("ab")
    let r2 = Regex("ab", RegexOption().ignoreCase())
    match (r1.matches("aB")) {
        case Some(r) => println(r.matchStr())
        case None => println("None")
    }
    match (r2.matches("aB")) {
        case Some(r) => println(r.matchStr())
        case None => println("None")
    }
}

运行结果:

None
aB

MatchOption 匹配多行

import std.regex.*

main(): Unit {
    let rule = ##"^(\w+)\s(\d+)*$"##
    let pattern: String = """
Joe 164
Sam 208
Allison 211
Gwen 171
"""

    let r1 = Regex(rule, RegexOption().multiLine())
    var arr = r1.matcher(pattern).findAll() ?? Array<MatchData>()
    for (md in arr) {
        println(md.matchStr())
    }
}

运行结果:

Joe 164
Sam 208
Allison 211
Gwen 171

Matcher 和 MatchData 的使用

import std.regex.*

main(): Unit {
    let r = Regex(#"a\wa"#).matcher("1aba12ada555")
    for (_ in 0..2) {
        let matchData = r.find()
        match (matchData) {
            case Some(md) =>
                println(md.matchStr())
                let pos = md.matchPosition()
                println("[${pos.start}, ${pos.end})")
            case None => println("None")
        }
    }
}

运行结果:

aba
[1, 4)
ada
[6, 9)

Matcher 中 resetString/fullMatch/matchStart 函数

import std.regex.*

main(): Unit {
    let r = Regex("\\d+")
    let m = r.matcher("13588123456")
    let matchData1 = m.fullMatch()
    m.resetString("13588abc")
    let matchData2 = m.matchStart()
    m.resetString("abc13588123abc")
    let matchData3 = m.matchStart()
    match (matchData1) {
        case Some(md) => println(md.matchStr())
        case None => println("None")
    }
    match (matchData2) {
        case Some(md) => println(md.matchStr())
        case None => println("None")
    }
    match (matchData3) {
        case Some(md) => println(md.matchStr())
        case None => println("None")
    }
}

运行结果:

13588123456
13588
None

Matcher 中 replace/replaceAll 函数

import std.regex.*

main(): Unit {
    let r = Regex("\\d").matcher("a1b1c2d3f4")
    println(r.replace("X")) //replace a digit once with X
    println(r.replace("X", 2)) //replace once from index 4
    println(r.replaceAll("X")) //replace all digit with X
    println(r.replaceAll("X", 2)) //replace all at most 2 times
    println(r.replaceAll("X", -1)) //replace all digit with X
}

运行结果:

aXb1c2d3f4
a1bXc2d3f4
aXbXcXdXfX
aXbXc2d3f4
aXbXcXdXfX

Matcher 获取匹配总数

import std.regex.*

main(): Unit {
    var matcher = Regex("a+b").matcher("1ab2aab3aaab4aaaab")
    println(matcher.allCount())
}

运行结果:

4

MatchData 中 groupNumber 函数

import std.regex.*

main(): Unit {
    var r = Regex("(a+c)(a?b)()(()?c+((e|s([a-h]*))))")
    var m = r.matcher("aacbcsdedd")
    var matchData = m.find()
    match (matchData) {
        case Some(s) =>
            println("groupNum : ${s.groupNumber()}")
            if (s.groupNumber() > 0) {
                for (i in 1..=s.groupNumber()) {
                    println("group[${i}] : ${s.matchStr(i)}")
                    var pos = s.matchPosition(i)
                    println("position : [${pos.start}, ${pos.end})")
                }
            }
        case None => ()
    }
}

运行结果:

groupNum : 8
group[1] : aac
position : [0, 3)
group[2] : b
position : [3, 4)
group[3] :
position : [4, 4)
group[4] : csdedd
position : [4, 10)
group[5] :
position : [10, 10)
group[6] : sdedd
position : [5, 10)
group[7] : sdedd
position : [5, 10)
group[8] : dedd
position : [6, 10)

std.runtime 包

功能介绍

runtime 包的作用是与程序的运行时环境进行交互,提供了一系列函数和变量,用于控制、管理和监视程序的执行。

CangJie 语言使用自动垃圾回收机制来管理内存,runtime 包提供了手动触发垃圾回收、设置垃圾回收的阈值、获取内存统计信息等功能,用于对垃圾回收进行调控和监测。

API 列表

函数

函数名功能
GC(Bool)执行 GC。
SetGCThreshold(UInt64)修改用户期望触发 GC 的内存阈值,当仓颉堆大小超过该值时,触发 GC,单位为 KB。

结构体

结构体名功能
MemoryInfo提供获取一些堆内存统计数据的接口。
ProcessorInfo提供获取一些处理器信息的接口。
ThreadInfo提供获取一些仓颉线程统计数据的接口。

函数

func GC(Bool)

public func GC(heavy!: Bool = false): Unit

功能:执行 GC

参数:

  • heavy!: Bool - GC 执行程度,如果为 true,执行会慢,内存收集的多一些,默认值为 false。

func SetGCThreshold(UInt64)

public func SetGCThreshold(value: UInt64): Unit

功能:修改用户期望触发 GC 的内存阈值,当仓颉堆大小超过该值时,触发 GC,单位为 KB。

参数:

  • value: UInt64 - 用户期望触发 GC 的内存阈值。

示例: 设置用户期望的 GC 的内存阈值为 2MB。

import std.runtime.*
main() {
  SetGCThreshold(2048)
}

结构体

struct MemoryInfo

public struct MemoryInfo

功能:提供获取一些堆内存统计数据的接口。

static prop allocatedHeapSize

public static prop allocatedHeapSize: Int64

功能:获取仓颉堆已被使用的大小,单位为 byte。

类型:Int64

static prop heapPhysicalMemory

public static prop heapPhysicalMemory: Int64

功能:在 Linux 平台下获取仓颉堆实际占用的物理内存大小, 单位为 byte。在 Windows 及 macOs 平台下获取仓颉进程实际占用的物理内存大小, 单位为 byte。

类型:Int64

static prop maxHeapSize

public static prop maxHeapSize: Int64

功能:获取仓颉堆可以使用的最大值,单位为 byte。

实例:

import std.runtime.*
main() {
  println(MemoryInfo.maxHeapSize)
}

运行结果(以实际环境为准):

268435456

类型:Int64

struct ProcessorInfo

public struct ProcessorInfo

功能:提供获取一些处理器信息的接口。

static prop processorCount

public static prop processorCount: Int64

功能:获取处理器数量。

类型:Int64

struct ThreadInfo

public struct ThreadInfo

功能:提供获取一些仓颉线程统计数据的接口。

static prop blockingThreadCount

public static prop blockingThreadCount: Int64

功能:获取阻塞的仓颉线程数。

类型:Int64

static prop nativeThreadCount

public static prop nativeThreadCount: Int64

功能:获取物理线程数。

类型:Int64

static prop threadCount

public static prop threadCount: Int64

功能:获取仓颉当前的线程数量。

类型:Int64

std.socket 包

功能介绍

socket 包未来2个版本后将废弃,期间保留原类型的导出,请参考 net 包进行迁移。

std.sort 包

功能介绍

sort 包提供数组类型的排序函数。

根据排序方式,本包提供了稳定排序和不稳定排序两套实现。稳定排序是指,相等元素的前后顺序在排序前后保持不变。反之,不稳定排序是指,不保证相等元素的前后顺序在排序前后保持一致。

本包提供了一组带泛型的排序函数,可用来对元素为 T 类型的数组进行排序。排序必然要求元素是可以比较的,因此,这组函数进一步分为两类:1、要求 T 实现 Comparable<T> 接口,2、将 T 相关的比较函数作为参数传入函数。

此外,本包提供辅助接口 SortByExtensionSortExtension,可用来为其他类型实现与排序相关的函数。

API列表

函数

函数名功能
stableSort<T>(Array<T>) where T <: Comparable<T>对数组进行稳定升序排序。
stableSort<T>(Array<T>, (T, T) -> Ordering)对数组进行稳定升序排序。
unstableSort<T>(Array<T>) where T <: Comparable<T>对数组进行不稳定升序排序。
unstableSort<T>(Array<T>, (T, T) -> Ordering)对数组进行不稳定升序排序。

接口

接口名功能
SortByExtension此接口作为排序相关的辅助接口,内部为空。
SortExtension此接口作为排序相关的辅助接口,内部为空。

函数

func stableSort<T>(Array<T>) where T <: Comparable<T>

public func stableSort<T>(data: Array<T>): Unit where T <: Comparable<T>

功能:对数组进行稳定升序排序。

参数:

  • data: Array<T> - 需要排序的数组。

func stableSort<T>(Array<T>, (T, T) -> Ordering)

public func stableSort<T>(data: Array<T>, comparator: (T, T) -> Ordering): Unit

功能:对数组进行稳定排序。

用户可传入自定义的比较函数 comparator,如果 comparator 的返回值为 Ordering.GT,排序后 t1t2 后;如果 comparator 的返回值为 Ordering.LT,排序后 t1t2 前;如果 comparator 的返回值为 Ordering.EQ,排序后 t1t2 的位置较排序前保持不变。

参数:

  • data: Array<T> - 需要排序的数组。
  • comparator: (T, T) ->Ordering - 用户传入的比较函数。

func unstableSort<T>(Array<T>) where T <: Comparable<T>

public func unstableSort<T>(data: Array<T>): Unit where T <: Comparable<T>

功能:对数组进行不稳定升序排序。

参数:

  • data: Array<T> - 需要排序的数组。

func unstableSort<T>(Array<T>, (T, T) -> Ordering)

public func unstableSort<T>(data: Array<T>, comparator: (T, T) -> Ordering): Unit

功能:对数组进行不稳定排序。

用户可传入自定义的比较函数 comparator,如果 comparator 的返回值为 Ordering.GT,排序后 t1t2 后;如果 comparator 的返回值为 Ordering.LT,排序后 t1t2 前;如果 comparator 的返回值为 Ordering.EQ,排序后 t1t2 的位置较排序前保持不变。

参数:

  • data: Array<T> - 需要排序的数组。
  • comparator: (T, T) ->Ordering - 用户传入的比较函数。

接口

interface SortByExtension

public interface SortByExtension

功能: 此接口作为排序相关的辅助接口,内部为空。

extend<T> Array<T> <: SortByExtension

extend<T> Array<T> <: SortByExtension

功能: 此扩展用于实现 ArraysortBy 函数。

父类型:

func sortBy(Bool, (T, T) -> Ordering)

public func sortBy(stable!: Bool = false, comparator!: (T, T) -> Ordering): Unit

功能:通过传入的比较函数,根据其返回值 Ordering 类型的结果,可对数组进行自定义排序。

参数:

  • stable!: Bool - 是否使用稳定排序。
  • comparator!: (T, T) ->Ordering - 用户传入的比较函数,如,comparator: (t1: T, t2: T) -> Ordering,如果 comparator 的返回值为 Ordering.GT,排序后 t1t2 后;如果 comparator 的返回值为 Ordering.LT,排序后 t1t2 前;如果 comparator 的返回值为 Ordering.EQ,且为稳定排序那么 t1t2 的位置较排序前保持不变; 如果 comparator 的返回值为 Ordering.EQ,且为不稳定排序,那么 t1t2 顺序不确定

interface SortExtension

public interface SortExtension

功能: 此接口作为排序相关的辅助接口,内部为空。

extend<T> Array<T> <: SortExtension where T <: Comparable<T>

extend<T> Array<T> <: SortExtension where T <: Comparable<T>

功能: 此扩展用于实现 Arraysort/sortDescending 函数。

父类型:

func sort(Bool)

public func sort(stable!: Bool = false): Unit

功能:以升序的方式排序 Array

参数:

  • stable!: Bool - 是否使用稳定排序。

func sortDescending(Bool)

public func sortDescending(stable!: Bool = false): Unit

功能:以降序的方式排序 Array

参数:

  • stable!: Bool - 是否使用稳定排序。

对 Array 进行排序

创建一个无序Array,并这个 Array 进行升序排序,利用 isAse 判断排序后是否为升序。

代码:

import std.sort.*
import std.random.*

main(): Unit {
    let r: Random = Random()
    let arr: Array<Int64> = Array<Int64>(70000, { _ => r.nextInt64() })
    arr.sortBy(stable: true){ rht: Int64, lht: Int64 =>
        if (rht < lht) {
            return Ordering.LT
        }
        if (rht > lht) {
            return Ordering.GT
        }
        return Ordering.EQ
    }

    println(isAse(arr))
}

func isAse(t: Array<Int64>) {
    var item: Int64 = t[0]
    for (i in 1..t.size) {
        if (item > t[i]) {
            return false
        }
        item = t[i]
    }
    return true
}

运行结果:

true

std.sync 包

功能介绍

sync 包提供并发编程相关的能力。

随着越来越多的计算机开始使用多核处理器,要充分发挥多核的优势,并发编程也变得越来越重要。

不同编程语言会以不同的方式实现线程。一些编程语言通过调用操作系统 API 来创建线程,意味着每个语言线程对应一个操作系统线程,一般称之为 1:1 的线程模型;也有一些编程语言提供特殊的线程实现,允许多个语言线程在不同数量的操作系统线程的上下文中切换执行,这种也被称为 M:N 的线程模型,即 M 个语言线程在 N 个操作系统线程上调度执行,其中 M 和 N 不一定相等。

仓颉编程语言希望给开发者提供一个友好、高效、统一的并发编程界面,让开发者无需关心操作系统线程、用户态线程等概念上的差异,同时屏蔽底层实现细节,因此我们只提供一个仓颉线程的概念。仓颉线程采用的是 M:N 线程模型的实现,因此本质上它是一种用户态的轻量级线程,支持抢占,且相比操作系统线程内存资源占用更小。

当开发者希望并发执行某一段代码时,只需创建一个仓颉线程即可。

要创建一个新的仓颉线程,可以使用关键字 spawn 并传递一个无形参的 lambda 表达式,该 lambda 表达式即为我们想在新线程中执行的代码。

示例:

通过 spawn 关键字创建一个仓颉线程:


main () {
    spawn {
        // 在新线程中执行
        println("Thread: ${Thread.currentThread.id}")
    }
    // 在主线程中执行
    println("Thread: ${Thread.currentThread.id}")
    sleep(Duration.second)

    0
}

sync 包主要提供了不同类型的原子操作,可重入互斥锁及其接口,利用共享变量的线程同步机制以及定时器的功能。

原子操作提供了包括整数类型、Bool 类型和引用类型的原子操作。

其中整数类型包括:Int8、Int16、Int32、Int64、UInt8、UInt16、UInt32、UInt64。

整数类型的原子操作支持基本的读(load)写(store)、交换(swap/compareAndSwap)以及算术运算(fetchAdd/fetchSub)等操作,需要注意的是:

  • 交换操作和算术操作的返回值是修改前的值。

  • compareAndSwap 是判断当前原子变量的值是否等于指定值,如果等于,则使用另一值替换;否则不替换。

Bool 类型和引用类型的原子操作只提供读写和交换操作,需要注意的是:

引用类型原子操作只对引用类型有效。

可重入互斥锁 ReentrantMutex 在使用的时候存在诸多不便,比如稍不注意会忘了解锁,或者在持有互斥锁的情况下抛出异常不能自动释放持有的锁等。因此,仓颉编程语言提供 synchronized 关键字,搭配 ReentrantMutex 一起使用,来解决类似的问题。

通过在 synchronized 后面加上一个可重入互斥锁实例,对其后面修饰的代码块进行保护,可以使得任意时刻最多只有一个线程可以执行被保护的代码:

  • 一个线程在进入 synchronized 修饰的代码块之前,会自动获取 ReentrantMutex 实例对应的锁,如果无法获取锁,则当前线程被阻塞。
  • 一个线程在退出 synchronized 修饰的代码块之前(包括在代码块中使用 breakcontinuereturnthrow 等控制转移表达式),会自动释放该 ReentrantMutex 实例的锁。

示例:

在每个 for 循环的线程进入 synchronized 代码块前,会自动获取 mtx 实例对应的锁,在退出代码块前,会释放 mtx 实例对应的锁。

import std.sync.ReentrantMutex

main () {
    let mtx = ReentrantMutex()
    let cnt = Box<Int64>(0)

    for (_ in 0..10) {
        spawn {
            synchronized(mtx) {
                cnt.value ++
                println("count: ${cnt.value}")
            }
        }
    }

    sleep(Duration.second)
    0
}

API 列表

常量&变量

常量&变量名功能
DefaultMemoryOrder默认内存顺序,详见枚举 MemoryOrder

接口

接口名功能
IReentrantMutex提供可重入互斥锁接口。

类名功能
AtomicBool提供 Bool 类型的原子操作相关函数。
AtomicInt16提供 Int16 类型的原子操作相关函数。
AtomicInt32提供 Int32 类型的原子操作相关函数。
AtomicInt64提供 Int64 类型的原子操作相关函数。
AtomicInt8提供 Int8 类型的原子操作相关函数。
AtomicOptionReference提供引用类型原子操作相关函数。
AtomicReference引用类型原子操作相关函数。
AtomicUInt16提供 UInt16 类型的原子操作相关函数。
AtomicUInt32提供 UInt32 类型的原子操作相关函数。
AtomicUInt64提供 UInt64 类型的原子操作相关函数。
AtomicUInt8提供 UInt8 类型的原子操作相关函数。
Barrier提供协调多个线程一起执行到某一个程序点的功能。
Monitor提供使线程阻塞并等待来自另一个线程的信号以恢复执行的功能。
MultiConditionMonitor提供对同一个互斥锁绑定多个条件变量的功能。
ReentrantMutex提供可重入锁相关功能。
ReentrantReadMutex提供可重入读写锁中的读锁类型。
ReentrantReadWriteMutex提供可重入读写锁相关功能。
ReentrantWriteMutex提供可重入读写锁中的写锁类型。
Semaphore提供信号量相关功能。
SyncCounter提供倒数计数器功能。
Timer提供定时器功能。

枚举

枚举类型功能
MemoryOrder内存顺序类型枚举。
ReadWriteMutexMode读写锁公平模式枚举。
CatchupStyle重复性任务定时器需要使用的追平策略枚举。

结构体

结构体功能
ConditionID用于表示互斥锁的条件变量,详见 MultiConditionMonitor

异常类

异常类名功能
IllegalSynchronizationStateException此类为非法同步状态异常。

常量&变量

let DefaultMemoryOrder

public let DefaultMemoryOrder: MemoryOrder = MemoryOrder.SeqCst

功能:默认内存顺序,详见枚举 MemoryOrder

类型:MemoryOrder

接口

interface IReentrantMutex

public interface IReentrantMutex

功能:提供实现可重入互斥锁的接口。

注意:

开发者在实现该接口时需要保证底层互斥锁确实支持嵌套锁,否则在嵌套使用时,将会产生死锁问题。

func lock()

func lock(): Unit

功能:锁定互斥体。

如果互斥体已被锁定,则阻塞当前线程。

func tryLock()

func tryLock(): Bool

功能:尝试锁定互斥体。

返回值:

  • Bool - 如果互斥体已被锁定,则返回 false;反之,则锁定互斥体并返回 true。

func unlock()

func unlock(): Unit

功能:解锁互斥体。

如果互斥体被重复加锁了 N 次,那么需要调用 N 次该函数来完全解锁。一旦互斥体被完全解锁,如果有其他线程阻塞在此锁上,则唤醒其中一个线程。

异常:

class AtomicBool

public class AtomicBool

功能:提供 Bool 类型的原子操作相关函数。

init(Bool)

public init(val: Bool)

功能:构造一个封装 Bool 数据类型的原子类型 AtomicBool 的实例,其内部数据初始值为入参 val 的值。

参数:

  • val: Bool - 原子类型的初始值。

func compareAndSwap(Bool, Bool)

public func compareAndSwap(old: Bool, new: Bool): Bool

功能:CAS(Compare and Swap)操作,采用默认内存排序方式

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,则写入参数 new 指定的值,并返回 true;否则,不写入值,并返回 false

参数:

  • old: Bool - 与当前原子类型进行比较的值。
  • new: Bool - 比较结果相等时,写入原子类型的值。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func compareAndSwap(Bool, Bool, MemoryOrder, MemoryOrder)

public func compareAndSwap(old: Bool, new: Bool, successOrder!: MemoryOrder, failureOrder!: MemoryOrder): Bool

功能:CAS 操作,成功时使用 successOrder 指定的内存排序方式,失败时则使用 failureOrder 指定的内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,写入参数 new 指定的值,返回 true;否则,不写入值,并返回 false

参数:

  • old: Bool - 与当前原子类型进行比较的值。
  • new: Bool - 比较结果相等时,写入原子类型的值。
  • successOrder!: MemoryOrder - CAS 操作成功时,执行“读 > 修改 > 写”操作需要的内存排序方式。
  • failureOrder!: MemoryOrder - CAS 操作失败时,执行“读”操作需要的内存排序方式。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func load()

public func load(): Bool

功能:读取操作,采用默认内存排序方式,读取原子类型的值。

返回值:

  • Bool - 当前原子类型的值。

func load(MemoryOrder)

public func load(memoryOrder!: MemoryOrder): Bool

功能:读取操作,采用参数 memoryOrder 指定的内存排序方式,读取原子类型的值。

参数:

  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Bool - 当前原子类型的值。

func store(Bool)

public func store(val: Bool): Unit

功能:写入操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Bool - 写入原子类型的值。

func store(Bool, MemoryOrder)

public func store(val: Bool, memoryOrder!: MemoryOrder): Unit

功能:写入操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Bool - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

func swap(Bool)

public func swap(val: Bool): Bool

功能:交换操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Bool - 写入原子类型的值。

返回值:

  • Bool - 写入前的值。

func swap(Bool, MemoryOrder)

public func swap(val: Bool, memoryOrder!: MemoryOrder): Bool

功能:交换操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Bool - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Bool - 写入前的值。

class AtomicInt16

public class AtomicInt16

功能:提供 Int16 类型的原子操作相关函数。

init(Int16)

public init(val: Int16)

功能:构造一个封装 Int16 数据类型的原子类型 AtomicInt16 的实例,其内部数据初始值为入参 val 的值。

参数:

  • val: Int16 - 原子类型的初始值。

func compareAndSwap(Int16, Int16)

public func compareAndSwap(old: Int16, new: Int16): Bool

功能:CAS 操作,采用默认内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,则写入参数 new 指定的值,并返回 true;否则,不写入值,并返回 false

参数:

  • old: Int16 - 与当前原子类型进行比较的值。
  • new: Int16 - 比较结果相等时,写入原子类型的值。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func compareAndSwap(Int16, Int16, MemoryOrder, MemoryOrder)

public func compareAndSwap(old: Int16, new: Int16, successOrder!: MemoryOrder, failureOrder!: MemoryOrder): Bool

功能:CAS 操作,成功时使用 successOrder 指定的内存排序方式,失败时则使用 failureOrder 指定的内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,写入参数 new 指定的值,返回 true;否则,不写入值,并返回 false

参数:

  • old: Int16 - 与当前原子类型进行比较的值。
  • new: Int16 - 比较结果相等时,写入原子类型的值。
  • successOrder!: MemoryOrder - CAS 操作成功时,执行“读 > 修改 > 写”操作需要的内存排序方式。
  • failureOrder!: MemoryOrder - CAS 操作失败时,执行“读”操作需要的内存排序方式。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func fetchAdd(Int16)

public func fetchAdd(val: Int16): Int16

功能:采用默认内存排序方式,将原子类型的值与参数 val 进行加操作,将结果写入当前原子类型实例,并返回加操作前的值。

参数:

  • val: Int16 - 与原子类型进行加操作的值。

返回值:

  • Int16 - 执行加操作前的值。

func fetchAdd(Int16, MemoryOrder)

public func fetchAdd(val: Int16, memoryOrder!: MemoryOrder): Int16

功能:采用参数 memoryOrder 指定的内存排序方式,将原子类型的值与参数 val 进行加操作。将结果写入当前原子类型实例,并返回加法运算前的值。

参数:

  • val: Int16 - 与原子类型进行加操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int16 - 执行加操作前的值。

func fetchAnd(Int16)

public func fetchAnd(val: Int16): Int16

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: Int16 - 与原子类型进行与操作的值。

返回值:

  • Int16 - 执行与操作前的值。

func fetchAnd(Int16, MemoryOrder)

public func fetchAnd(val: Int16, memoryOrder!: MemoryOrder): Int16

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: Int16 - 与原子类型进行与操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int16 - 执行与操作前的值。

func fetchOr(Int16)

public func fetchOr(val: Int16): Int16

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: Int16 - 与原子类型进行或操作的值。

返回值:

  • Int16 - 执行或操作前的值。

func fetchOr(Int16, MemoryOrder)

public func fetchOr(val: Int16, memoryOrder!: MemoryOrder): Int16

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: Int16 - 与原子类型进行或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int16 - 执行或操作前的值。

func fetchSub(Int16)

public func fetchSub(val: Int16): Int16

功能:采用默认内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: Int16 - 与原子类型进行减操作的值。

返回值:

  • Int16 - 执行减操作前的值。

func fetchSub(Int16, MemoryOrder)

public func fetchSub(val: Int16, memoryOrder!: MemoryOrder): Int16

功能:采用参数 memoryOrder 指定的内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: Int16 - 与原子类型进行减操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int16 - 执行减操作前的值。

func fetchXor(Int16)

public func fetchXor(val: Int16): Int16

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: Int16 - 与原子类型进行异或操作的值。

返回值:

  • Int16 - 执行异或操作前的值。

func fetchXor(Int16, MemoryOrder)

public func fetchXor(val: Int16, memoryOrder!: MemoryOrder): Int16

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: Int16 - 与原子类型进行异或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int16 - 执行异或操作前的值。

func load()

public func load(): Int16

功能:读取操作,采用默认内存排序方式,读取原子类型的值。

返回值:

  • Int16 - 当前原子类型的值。

func load(MemoryOrder)

public func load(memoryOrder!: MemoryOrder): Int16

功能:读取操作,采用参数 memoryOrder 指定的内存排序方式,读取原子类型的值。

参数:

  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int16 - 当前原子类型的值。

func store(Int16)

public func store(val: Int16): Unit

功能:写入操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Int16 - 写入原子类型的值。

func store(Int16, MemoryOrder)

public func store(val: Int16, memoryOrder!: MemoryOrder): Unit

功能:写入操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Int16 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

func swap(Int16)

public func swap(val: Int16): Int16

功能:交换操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Int16 - 写入原子类型的值。

返回值:

  • Int16 - 写入前的值。

func swap(Int16, MemoryOrder)

public func swap(val: Int16, memoryOrder!: MemoryOrder): Int16

功能:交换操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Int16 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int16 - 写入前的值。

class AtomicInt32

public class AtomicInt32

功能:提供 Int32 类型的原子操作相关函数。

init(Int32)

public init(val: Int32)

功能:构造一个封装 Int32 数据类型的原子类型 AtomicInt32 的实例,其内部数据初始值为入参 val 的值。

参数:

  • val: Int32 - 原子类型的初始值。

func compareAndSwap(Int32, Int32)

public func compareAndSwap(old: Int32, new: Int32): Bool

功能:CAS 操作,采用默认内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,则写入参数 new 指定的值,并返回 true;否则,不写入值,并返回 false

参数:

  • old: Int32 - 与当前原子类型进行比较的值。
  • new: Int32 - 比较结果相等时,写入原子类型的值。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func compareAndSwap(Int32, Int32, MemoryOrDer, MemoryOrder)

public func compareAndSwap(old: Int32, new: Int32, successOrder!: MemoryOrder, failureOrder!: MemoryOrder): Bool

功能:CAS 操作,成功时使用 successOrder 指定的内存排序方式,失败时则使用 failureOrder 指定的内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,写入参数 new 指定的值,返回 true;否则,不写入值,并返回 false

参数:

  • old: Int32 - 与当前原子类型进行比较的值。
  • new: Int32 - 比较结果相等时,写入原子类型的值。
  • successOrder!: MemoryOrder - CAS 操作成功时,执行“读 > 修改 > 写”操作需要的内存排序方式。
  • failureOrder!: MemoryOrder - CAS 操作失败时,执行“读”操作需要的内存排序方式。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func fetchAdd(Int32)

public func fetchAdd(val: Int32): Int32

功能:采用默认内存排序方式,将原子类型的值与参数 val 进行加操作,将结果写入当前原子类型实例,并返回加操作前的值。

参数:

  • val: Int32 - 与原子类型进行加操作的值。

返回值:

  • Int32 - 执行加操作前的值。

func fetchAdd(Int32, MemoryOrder)

public func fetchAdd(val: Int32, memoryOrder!: MemoryOrder): Int32

功能:采用参数 memoryOrder 指定的内存排序方式,将原子类型的值与参数 val 进行加操作。将结果写入当前原子类型实例,并返回加法运算前的值。

参数:

  • val: Int32 - 与原子类型进行加操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int32 - 执行加操作前的值。

func fetchAnd(Int32)

public func fetchAnd(val: Int32): Int32

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: Int32 - 与原子类型进行与操作的值。

返回值:

  • Int32 - 执行与操作前的值。

func fetchAnd(Int32, MemoryOrder)

public func fetchAnd(val: Int32, memoryOrder!: MemoryOrder): Int32

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: Int32 - 与原子类型进行与操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int32 - 执行与操作前的值。

func fetchOr(Int32)

public func fetchOr(val: Int32): Int32

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: Int32 - 与原子类型进行或操作的值。

返回值:

  • Int32 - 执行或操作前的值。

func fetchOr(Int32, MemoryOrder)

public func fetchOr(val: Int32, memoryOrder!: MemoryOrder): Int32

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: Int32 - 与原子类型进行或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int32 - 执行或操作前的值。

func fetchSub(Int32)

public func fetchSub(val: Int32): Int32

功能:采用默认内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: Int32 - 与原子类型进行减操作的值。

返回值:

  • Int32 - 执行减操作前的值。

func fetchSub(Int32, MemoryOrder)

public func fetchSub(val: Int32, memoryOrder!: MemoryOrder): Int32

功能:采用参数 memoryOrder 指定的内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: Int32 - 与原子类型进行减操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int32 - 执行减操作前的值。

func fetchXor(Int32)

public func fetchXor(val: Int32): Int32

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: Int32 - 与原子类型进行异或操作的值。

返回值:

  • Int32 - 执行异或操作前的值。

func fetchXor(Int32, MemoryOrder)

public func fetchXor(val: Int32, memoryOrder!: MemoryOrder): Int32

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: Int32 - 与原子类型进行异或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int32 - 执行异或操作前的值。

func load()

public func load(): Int32

功能:读取操作,采用默认内存排序方式,读取原子类型的值。

返回值:

  • Int32 - 当前原子类型的值。

func load(MemoryOrder)

public func load(memoryOrder!: MemoryOrder): Int32

功能:读取操作,采用参数 memoryOrder 指定的内存排序方式,读取原子类型的值。

参数:

  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int32 - 当前原子类型的值。

func store(Int32)

public func store(val: Int32): Unit

功能:写入操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Int32 - 写入原子类型的值。

func store(Int32, MemoryOrder)

public func store(val: Int32, memoryOrder!: MemoryOrder): Unit

功能:写入操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Int32 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

func swap(Int32)

public func swap(val: Int32): Int32

功能:交换操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Int32 - 写入原子类型的值。

返回值:

  • Int32 - 写入前的值。

func swap(Int32, MemoryOrder)

public func swap(val: Int32, memoryOrder!: MemoryOrder): Int32

功能:交换操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Int32 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int32 - 写入前的值。

class AtomicInt64

public class AtomicInt64

功能:提供 Int64 类型的原子操作相关函数。

init(Int64)

public init(val: Int64)

功能:构造一个封装 Int64 数据类型的原子类型 AtomicInt64 的实例,其内部数据初始值为入参 val 的值。

参数:

  • val: Int64 - 原子类型的初始值。

func compareAndSwap(Int64, Int64)

public func compareAndSwap(old: Int64, new: Int64): Bool

功能:CAS 操作,采用默认内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,则写入参数 new 指定的值,并返回 true;否则,不写入值,并返回 false

参数:

  • old: Int64 - 与当前原子类型进行比较的值。
  • new: Int64 - 比较结果相等时,写入原子类型的值。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func compareAndSwap(Int64, Int64, MemoryOrder, MemoryOrder)

public func compareAndSwap(old: Int64, new: Int64, successOrder!: MemoryOrder, failureOrder!: MemoryOrder): Bool

功能:CAS 操作,成功时使用 successOrder 指定的内存排序方式,失败时则使用 failureOrder 指定的内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,写入参数 new 指定的值,返回 true;否则,不写入值,并返回 false

参数:

  • old: Int64 - 与当前原子类型进行比较的值。
  • new: Int64 - 比较结果相等时,写入原子类型的值。
  • successOrder!: MemoryOrder - CAS 操作成功时,执行“读 > 修改 > 写”操作需要的内存排序方式。
  • failureOrder!: MemoryOrder - CAS 操作失败时,执行“读”操作需要的内存排序方式。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func fetchAdd(Int64)

public func fetchAdd(val: Int64): Int64

功能:采用默认内存排序方式,将原子类型的值与参数 val 进行加操作,将结果写入当前原子类型实例,并返回加操作前的值。

参数:

  • val: Int64 - 与原子类型进行加操作的值。

返回值:

  • Int64 - 执行加操作前的值。

func fetchAdd(Int64, MemoryOrder)

public func fetchAdd(val: Int64, memoryOrder!: MemoryOrder): Int64

功能:采用参数 memoryOrder 指定的内存排序方式,将原子类型的值与参数 val 进行加操作。将结果写入当前原子类型实例,并返回加法运算前的值。

参数:

  • val: Int64 - 与原子类型进行加操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int64 - 执行加操作前的值。

func fetchAnd(Int64)

public func fetchAnd(val: Int64): Int64

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: Int64 - 与原子类型进行与操作的值。

返回值:

  • Int64 - 执行与操作前的值。

func fetchAnd(Int64, MemoryOrder)

public func fetchAnd(val: Int64, memoryOrder!: MemoryOrder): Int64

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: Int64 - 与原子类型进行与操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int64 - 执行与操作前的值。

func fetchOr(Int64)

public func fetchOr(val: Int64): Int64

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: Int64 - 与原子类型进行或操作的值。

返回值:

  • Int64 - 执行或操作前的值。

func fetchOr(Int64, MemoryOrder)

public func fetchOr(val: Int64, memoryOrder!: MemoryOrder): Int64

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: Int64 - 与原子类型进行或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int64 - 执行或操作前的值。

func fetchSub(Int64)

public func fetchSub(val: Int64): Int64

功能:采用默认内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: Int64 - 与原子类型进行减操作的值。

返回值:

  • Int64 - 执行减操作前的值。

func fetchSub(Int64, MemoryOrder)

public func fetchSub(val: Int64, memoryOrder!: MemoryOrder): Int64

功能:采用参数 memoryOrder 指定的内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: Int64 - 与原子类型进行减操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int64 - 执行减操作前的值。

func fetchXor(Int64)

public func fetchXor(val: Int64): Int64

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: Int64 - 与原子类型进行异或操作的值。

返回值:

  • Int64 - 执行异或操作前的值。

func fetchXor(Int64, MemoryOrder)

public func fetchXor(val: Int64, memoryOrder!: MemoryOrder): Int64

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: Int64 - 与原子类型进行异或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int64 - 执行异或操作前的值。

func load()

public func load(): Int64

功能:读取操作,采用默认内存排序方式,读取原子类型的值。

返回值:

  • Int64 - 当前原子类型的值。

func load(MemoryOrder)

public func load(memoryOrder!: MemoryOrder): Int64

功能:读取操作,采用参数 memoryOrder 指定的内存排序方式,读取原子类型的值。

参数:

  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int64 - 当前原子类型的值。

func store(Int64)

public func store(val: Int64): Unit

功能:写入操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Int64 - 写入原子类型的值。

func store(Int64, MemoryOrder)

public func store(val: Int64, memoryOrder!: MemoryOrder): Unit

功能:写入操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Int64 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

func swap(Int64)

public func swap(val: Int64): Int64

功能:交换操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Int64 - 写入原子类型的值。

返回值:

  • Int64 - 写入前的值。

func swap(Int64, MemoryOrder)

public func swap(val: Int64, memoryOrder!: MemoryOrder): Int64

功能:交换操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Int64 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int64 - 写入前的值。

class AtomicInt8

public class AtomicInt8

功能:提供 Int8 类型的原子操作相关函数。

init(Int8)

public init(val: Int8)

功能:构造一个封装 Int8 数据类型的原子类型 AtomicInt8 的实例,其内部数据初始值为入参 val 的值。

参数:

  • val: Int8 - 原子类型的初始值。

func compareAndSwap(Int8, Int8)

public func compareAndSwap(old: Int8, new: Int8): Bool

功能:CAS 操作,采用默认内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,则写入参数 new 指定的值,并返回 true;否则,不写入值,并返回 false

参数:

  • old: Int8 - 与当前原子类型进行比较的值。
  • new: Int8 - 比较结果相等时,写入原子类型的值。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func compareAndSwap(Int8, Int8, MemoryOrder, MemoryOrder)

public func compareAndSwap(old: Int8, new: Int8, successOrder!: MemoryOrder, failureOrder!: MemoryOrder): Bool

功能:CAS 操作,成功时使用 successOrder 指定的内存排序方式,失败时则使用 failureOrder 指定的内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,写入参数 new 指定的值,返回 true;否则,不写入值,并返回 false

参数:

  • old: Int8 - 与当前原子类型进行比较的值。
  • new: Int8 - 比较结果相等时,写入原子类型的值。
  • successOrder!: MemoryOrder - CAS 操作成功时,执行“读 > 修改 > 写”操作需要的内存排序方式。
  • failureOrder!: MemoryOrder - CAS 操作失败时,执行“读”操作需要的内存排序方式。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func fetchAdd(Int8)

public func fetchAdd(val: Int8): Int8

功能:采用默认内存排序方式,将原子类型的值与参数 val 进行加操作,将结果写入当前原子类型实例,并返回加操作前的值。

参数:

  • val: Int8 - 与原子类型进行加操作的值。

返回值:

  • Int8 - 执行加操作前的值。

func fetchAdd(Int8, MemoryOrder)

public func fetchAdd(val: Int8, memoryOrder!: MemoryOrder): Int8

功能:采用参数 memoryOrder 指定的内存排序方式,将原子类型的值与参数 val 进行加操作。将结果写入当前原子类型实例,并返回加法运算前的值。

参数:

  • val: Int8 - 与原子类型进行加操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int8 - 执行加操作前的值。

func fetchAnd(Int8)

public func fetchAnd(val: Int8): Int8

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: Int8 - 与原子类型进行与操作的值。

返回值:

  • Int8 - 执行与操作前的值。

func fetchAnd(Int8, MemoryOrder)

public func fetchAnd(val: Int8, memoryOrder!: MemoryOrder): Int8

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: Int8 - 与原子类型进行与操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int8 - 执行与操作前的值。

func fetchOr(Int8)

public func fetchOr(val: Int8): Int8

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: Int8 - 与原子类型进行或操作的值。

返回值:

  • Int8 - 执行或操作前的值。

func fetchOr(Int8, MemoryOrder)

public func fetchOr(val: Int8, memoryOrder!: MemoryOrder): Int8

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: Int8 - 与原子类型进行或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int8 - 执行或操作前的值。

func fetchSub(Int8)

public func fetchSub(val: Int8): Int8

功能:采用默认内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: Int8 - 与原子类型进行减操作的值。

返回值:

  • Int8 - 执行减操作前的值。

func fetchSub(Int8, MemoryOrder)

public func fetchSub(val: Int8, memoryOrder!: MemoryOrder): Int8

功能:采用参数 memoryOrder 指定的内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: Int8 - 与原子类型进行减操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int8 - 执行减操作前的值。

func fetchXor(Int8)

public func fetchXor(val: Int8): Int8

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: Int8 - 与原子类型进行异或操作的值。

返回值:

  • Int8 - 执行异或操作前的值。

func fetchXor(Int8, MemoryOrder)

public func fetchXor(val: Int8, memoryOrder!: MemoryOrder): Int8

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: Int8 - 与原子类型进行异或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int8 - 执行异或操作前的值。

func load()

public func load(): Int8

功能:读取操作,采用默认内存排序方式,读取原子类型的值。

返回值:

  • Int8 - 当前原子类型的值。

func load(MemoryOrder)

public func load(memoryOrder!: MemoryOrder): Int8

功能:读取操作,采用参数 memoryOrder 指定的内存排序方式,读取原子类型的值。

参数:

  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int8 - 当前原子类型的值。

func store(Int8)

public func store(val: Int8): Unit

功能:写入操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Int8 - 写入原子类型的值。

func store(Int8, MemoryOrder)

public func store(val: Int8, memoryOrder!: MemoryOrder): Unit

功能:写入操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Int8 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

func swap(Int8)

public func swap(val: Int8): Int8

功能:交换操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Int8 - 写入原子类型的值。

返回值:

  • Int8 - 写入前的值。

func swap(Int8, MemoryOrder)

public func swap(val: Int8, memoryOrder!: MemoryOrder): Int8

功能:交换操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Int8 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Int8 - 写入前的值。

class AtomicOptionReference

public class AtomicOptionReference<T> where T <: Object

功能:提供引用类型原子操作相关函数。

该引用类型必须是 Object 的子类。

init()

public init()

功能:构造一个空的 AtomicOptionReference 实例。

init(Option<T>)

public init(val: Option<T>)

功能:构造一个封装 Option<T> 数据类型的原子类型 AtomicOptionReference 的实例,其内部数据初始值为入参 val 的值。

参数:

  • val: Option<T> - 原子类型的初始值。

func compareAndSwap(Option<T>, Option<T>)

public func compareAndSwap(old: Option<T>, new: Option<T>): Bool

功能:CAS 操作,采用默认内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,则写入参数 new 指定的值,并返回 true;否则,不写入值,并返回 false

参数:

  • old: Option<T> - 与当前原子类型进行比较的值。
  • new: Option<T> - 比较结果相等时,写入原子类型的值。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func compareAndSwap(Option<T>, Option<T>, MemoryOrder, MemoryOrder)

public func compareAndSwap(old: Option<T>, new: Option<T>, successOrder!: MemoryOrder, failureOrder!: MemoryOrder): Bool

功能:CAS 操作,成功时使用 successOrder 指定的内存排序方式,失败时则使用 failureOrder 指定的内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,写入参数 new 指定的值,返回 true;否则,不写入值,并返回 false

参数:

  • old: Option<T> - 与当前原子类型进行比较的值。
  • new: Option<T> - 比较结果相等时,写入原子类型的值。
  • successOrder!: MemoryOrder - CAS 操作成功时,执行“读 > 修改 > 写”操作需要的内存排序方式。
  • failureOrder!: MemoryOrder - CAS 操作失败时,执行“读”操作需要的内存排序方式。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func load()

public func load(): Option<T>

功能:读取操作,采用默认内存排序方式,读取原子类型的值。

返回值:

  • Option<T> - 当前原子类型的值。

func load(MemoryOrder)

public func load(memoryOrder!: MemoryOrder): Option<T>

功能:读取操作,采用参数 memoryOrder 指定的内存排序方式,读取原子类型的值。

参数:

  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Option<T> - 当前原子类型的值。

func store(Option<T>)

public func store(val: Option<T>): Unit

功能:写入操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Option<T> - 写入原子类型的值。

func store(Option<T>, MemoryOrder)

public func store(val: Option<T>, memoryOrder!: MemoryOrder): Unit

功能:写入操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: Option<T> - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

func swap(Option<T>)

public func swap(val: Option<T>): Option<T>

功能:交换操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Option<T> - 写入原子类型的值。

返回值:

  • Option<T> - 写入前的值。

func swap(Option<T>, MemoryOrder)

public func swap(val: Option<T>, memoryOrder!: MemoryOrder): Option<T>

功能:交换操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: Option<T> - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • Option<T> - 写入前的值。

class AtomicReference

public class AtomicReference<T> where T <: Object

功能:引用类型原子操作相关函数。

该引用类型必须是 Object 的子类。

init(T)

public init(val: T)

功能:构造一个封装 T 数据类型的原子类型 AtomicReference 的实例,其内部数据初始值为入参 val 的值。

参数:

  • val: T - 原子类型的初始值。

func compareAndSwap(T, T)

public func compareAndSwap(old: T, new: T): Bool

功能:CAS 操作,采用默认内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,则写入参数 new 指定的值,并返回 true;否则,不写入值,并返回 false

参数:

  • old: T - 与当前原子类型进行比较的值。
  • new: T - 比较结果相等时,写入原子类型的值。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func compareAndSwap(T, T, MemoryOrder, MemoryOrder)

public func compareAndSwap(old: T, new: T, successOrder!: MemoryOrder, failureOrder!: MemoryOrder): Bool

功能:CAS 操作,成功时使用 successOrder 指定的内存排序方式,失败时则使用 failureOrder 指定的内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,写入参数 new 指定的值,返回 true;否则,不写入值,并返回 false

参数:

  • old: T - 与当前原子类型进行比较的值。
  • new: T - 比较结果相等时,写入原子类型的值。
  • successOrder!: MemoryOrder - CAS 操作成功时,执行“读 > 修改 > 写”操作需要的内存排序方式。
  • failureOrder!: MemoryOrder - CAS 操作失败时,执行“读”操作需要的内存排序方式。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func load()

public func load(): T

功能:读取操作,采用默认内存排序方式,读取原子类型的值。

返回值:

  • T - 当前原子类型的值。

func load(MemoryOrder)

public func load(memoryOrder!: MemoryOrder): T

功能:读取操作,采用参数 memoryOrder 指定的内存排序方式,读取原子类型的值。

参数:

  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • T - 当前原子类型的值。

func store(T)

public func store(val: T): Unit

功能:写入操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: T - 写入原子类型的值。

func store(T, MemoryOrder)

public func store(val: T, memoryOrder!: MemoryOrder): Unit

功能:写入操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: T - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

func swap(T)

public func swap(val: T): T

功能:交换操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: T - 写入原子类型的值。

返回值:

  • T - 写入前的值。

func swap(T, MemoryOrder)

public func swap(val: T, memoryOrder!: MemoryOrder): T

功能:交换操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: T - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • T - 写入前的值。

class AtomicUInt16

public class AtomicUInt16

功能:提供 UInt16 类型的原子操作相关函数。

init(UInt16)

public init(val: UInt16)

功能:构造一个封装 UInt16 数据类型的原子类型 AtomicUInt16 的实例,其内部数据初始值为入参 val 的值。

参数:

  • val: UInt16 - 原子类型的初始值。

func compareAndSwap(UInt16, UInt16)

public func compareAndSwap(old: UInt16, new: UInt16): Bool

功能:CAS 操作,采用默认内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,则写入参数 new 指定的值,并返回 true;否则,不写入值,并返回 false

参数:

  • old: UInt16 - 与当前原子类型进行比较的值。
  • new: UInt16 - 比较结果相等时,写入原子类型的值。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func compareAndSwap(UInt16, UInt16, MemoryOrder, MemoryOrder)

public func compareAndSwap(old: UInt16, new: UInt16, successOrder!: MemoryOrder, failureOrder!: MemoryOrder): Bool

功能:CAS 操作,成功时使用 successOrder 指定的内存排序方式,失败时则使用 failureOrder 指定的内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,写入参数 new 指定的值,返回 true;否则,不写入值,并返回 false

参数:

  • old: UInt16 - 与当前原子类型进行比较的值。
  • new: UInt16 - 比较结果相等时,写入原子类型的值。
  • successOrder!: MemoryOrder - CAS 操作成功时,执行“读 > 修改 > 写”操作需要的内存排序方式。
  • failureOrder!: MemoryOrder - CAS 操作失败时,执行“读”操作需要的内存排序方式。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func fetchAdd(UInt16)

public func fetchAdd(val: UInt16): UInt16

功能:采用默认内存排序方式,将原子类型的值与参数 val 进行加操作,将结果写入当前原子类型实例,并返回加操作前的值。

参数:

  • val: UInt16 - 与原子类型进行加操作的值。

返回值:

  • UInt16 - 执行加操作前的值。

func fetchAdd(UInt16, MemoryOrder)

public func fetchAdd(val: UInt16, memoryOrder!: MemoryOrder): UInt16

功能:采用参数 memoryOrder 指定的内存排序方式,将原子类型的值与参数 val 进行加操作。将结果写入当前原子类型实例,并返回加法运算前的值。

参数:

  • val: UInt16 - 与原子类型进行加操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt16 - 执行加操作前的值。

func fetchAnd(UInt16)

public func fetchAnd(val: UInt16): UInt16

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: UInt16 - 与原子类型进行与操作的值。

返回值:

  • UInt16 - 执行与操作前的值。

func fetchAnd(UInt16, MemoryOrder)

public func fetchAnd(val: UInt16, memoryOrder!: MemoryOrder): UInt16

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: UInt16 - 与原子类型进行与操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt16 - 执行与操作前的值。

func fetchOr(UInt16)

public func fetchOr(val: UInt16): UInt16

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: UInt16 - 与原子类型进行或操作的值。

返回值:

  • UInt16 - 执行或操作前的值。

func fetchOr(UInt16, MemoryOrder)

public func fetchOr(val: UInt16, memoryOrder!: MemoryOrder): UInt16

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: UInt16 - 与原子类型进行或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt16 - 执行或操作前的值。

func fetchSub(UInt16)

public func fetchSub(val: UInt16): UInt16

功能:采用默认内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: UInt16 - 与原子类型进行减操作的值。

返回值:

  • UInt16 - 执行减操作前的值。

func fetchSub(UInt16, MemoryOrder)

public func fetchSub(val: UInt16, memoryOrder!: MemoryOrder): UInt16

功能:采用参数 memoryOrder 指定的内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: UInt16 - 与原子类型进行减操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt16 - 执行减操作前的值。

func fetchXor(UInt16)

public func fetchXor(val: UInt16): UInt16

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: UInt16 - 与原子类型进行异或操作的值。

返回值:

  • UInt16 - 执行异或操作前的值。

func fetchXor(UInt16, MemoryOrder)

public func fetchXor(val: UInt16, memoryOrder!: MemoryOrder): UInt16

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: UInt16 - 与原子类型进行异或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt16 - 执行异或操作前的值。

func load()

public func load(): UInt16

功能:读取操作,采用默认内存排序方式,读取原子类型的值。

返回值:

  • UInt16 - 当前原子类型的值。

func load(MemoryOrder)

public func load(memoryOrder!: MemoryOrder): UInt16

功能:读取操作,采用参数 memoryOrder 指定的内存排序方式,读取原子类型的值。

参数:

  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt16 - 当前原子类型的值。

func store(UInt16)

public func store(val: UInt16): Unit

功能:写入操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: UInt16 - 写入原子类型的值。

func store(UInt16, MemoryOrder)

public func store(val: UInt16, memoryOrder!: MemoryOrder): Unit

功能:写入操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: UInt16 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

func swap(UInt16)

public func swap(val: UInt16): UInt16

功能:交换操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: UInt16 - 写入原子类型的值。

返回值:

func swap(UInt16, MemoryOrder)

public func swap(val: UInt16, memoryOrder!: MemoryOrder): UInt16

功能:交换操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: UInt16 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

class AtomicUInt32

public class AtomicUInt32

功能:提供 UInt32 类型的原子操作相关函数。

init(UInt32)

public init(val: UInt32)

功能:构造一个封装 UInt32 数据类型的原子类型 AtomicUInt32 的实例,其内部数据初始值为入参 val 的值。

参数:

  • val: UInt32 - 原子类型的初始值。

func compareAndSwap(UInt32, UInt32)

public func compareAndSwap(old: UInt32, new: UInt32): Bool

功能:CAS 操作,采用默认内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,则写入参数 new 指定的值,并返回 true;否则,不写入值,并返回 false

参数:

  • old: UInt32 - 与当前原子类型进行比较的值。
  • new: UInt32 - 比较结果相等时,写入原子类型的值。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func compareAndSwap(UInt32, UInt32, MemoryOrder, MemoryOrder)

public func compareAndSwap(old: UInt32, new: UInt32, successOrder!: MemoryOrder, failureOrder!: MemoryOrder): Bool

功能:CAS 操作,成功时使用 successOrder 指定的内存排序方式,失败时则使用 failureOrder 指定的内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,写入参数 new 指定的值,返回 true;否则,不写入值,并返回 false

参数:

  • old: UInt32 - 与当前原子类型进行比较的值。
  • new: UInt32 - 比较结果相等时,写入原子类型的值。
  • successOrder!: MemoryOrder - CAS 操作成功时,执行“读 > 修改 > 写”操作需要的内存排序方式。
  • failureOrder!: MemoryOrder - CAS 操作失败时,执行“读”操作需要的内存排序方式。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func fetchAdd(UInt32)

public func fetchAdd(val: UInt32): UInt32

功能:采用默认内存排序方式,将原子类型的值与参数 val 进行加操作,将结果写入当前原子类型实例,并返回加操作前的值。

参数:

  • val: UInt32 - 与原子类型进行加操作的值。

返回值:

  • UInt32 - 执行加操作前的值。

func fetchAdd(UInt32, MemoryOrder)

public func fetchAdd(val: UInt32, memoryOrder!: MemoryOrder): UInt32

功能:采用参数 memoryOrder 指定的内存排序方式,将原子类型的值与参数 val 进行加操作。将结果写入当前原子类型实例,并返回加法运算前的值。

参数:

  • val: UInt32 - 与原子类型进行加操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt32 - 执行加操作前的值。

func fetchAnd(UInt32)

public func fetchAnd(val: UInt32): UInt32

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: UInt32 - 与原子类型进行与操作的值。

返回值:

  • UInt32 - 执行与操作前的值。

func fetchAnd(UInt32, MemoryOrder)

public func fetchAnd(val: UInt32, memoryOrder!: MemoryOrder): UInt32

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: UInt32 - 与原子类型进行与操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt32 - 执行与操作前的值。

func fetchOr(UInt32)

public func fetchOr(val: UInt32): UInt32

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: UInt32 - 与原子类型进行或操作的值。

返回值:

  • UInt32 - 执行或操作前的值。

func fetchOr(UInt32, MemoryOrder)

public func fetchOr(val: UInt32, memoryOrder!: MemoryOrder): UInt32

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: UInt32 - 与原子类型进行或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt32 - 执行或操作前的值。

func fetchSub(UInt32)

public func fetchSub(val: UInt32): UInt32

功能:采用默认内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: UInt32 - 与原子类型进行减操作的值。

返回值:

  • UInt32 - 执行减操作前的值。

func fetchSub(UInt32, MemoryOrder)

public func fetchSub(val: UInt32, memoryOrder!: MemoryOrder): UInt32

功能:采用参数 memoryOrder 指定的内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: UInt32 - 与原子类型进行减操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt32 - 执行减操作前的值。

func fetchXor(UInt32)

public func fetchXor(val: UInt32): UInt32

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: UInt32 - 与原子类型进行异或操作的值。

返回值:

  • UInt32 - 执行异或操作前的值。

func fetchXor(UInt32, MemoryOrder)

public func fetchXor(val: UInt32, memoryOrder!: MemoryOrder): UInt32

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: UInt32 - 与原子类型进行异或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt32 - 执行异或操作前的值。

func load()

public func load(): UInt32

功能:读取操作,采用默认内存排序方式,读取原子类型的值。

返回值:

  • UInt32 - 当前原子类型的值。

func load(MemoryOrder)

public func load(memoryOrder!: MemoryOrder): UInt32

功能:读取操作,采用参数 memoryOrder 指定的内存排序方式,读取原子类型的值。

参数:

  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt32 - 当前原子类型的值。

func store(UInt32)

public func store(val: UInt32): Unit

功能:写入操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: UInt32 - 写入原子类型的值。

func store(UInt32, MemoryOrder)

public func store(val: UInt32, memoryOrder!: MemoryOrder): Unit

功能:写入操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: UInt32 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

func swap(UInt32)

public func swap(val: UInt32): UInt32

功能:交换操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: UInt32 - 写入原子类型的值。

返回值:

func swap(UInt32, MemoryOrder)

public func swap(val: UInt32, memoryOrder!: MemoryOrder): UInt32

功能:交换操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: UInt32 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

class AtomicUInt64

public class AtomicUInt64

功能:提供 UInt64 类型的原子操作相关函数。

init(UInt64)

public init(val: UInt64)

功能:构造一个封装 UInt64 数据类型的原子类型 AtomicUInt64 的实例,其内部数据初始值为入参 val 的值。

参数:

  • val: UInt64 - 原子类型的初始值。

func compareAndSwap(UInt64, UInt64)

public func compareAndSwap(old: UInt64, new: UInt64): Bool

功能:CAS 操作,采用默认内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,则写入参数 new 指定的值,并返回 true;否则,不写入值,并返回 false

参数:

  • old: UInt64 - 与当前原子类型进行比较的值。
  • new: UInt64 - 比较结果相等时,写入原子类型的值。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func compareAndSwap(UInt64, UInt64, MemoryOrder, MemoryOrder)

public func compareAndSwap(old: UInt64, new: UInt64, successOrder!: MemoryOrder, failureOrder!: MemoryOrder): Bool

功能:CAS 操作,成功时使用 successOrder 指定的内存排序方式,失败时则使用 failureOrder 指定的内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,写入参数 new 指定的值,返回 true;否则,不写入值,并返回 false

参数:

  • old: UInt64 - 与当前原子类型进行比较的值。
  • new: UInt64 - 比较结果相等时,写入原子类型的值。
  • successOrder!: MemoryOrder - CAS 操作成功时,执行“读 > 修改 > 写”操作需要的内存排序方式。
  • failureOrder!: MemoryOrder - CAS 操作失败时,执行“读”操作需要的内存排序方式。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func fetchAdd(UInt64)

public func fetchAdd(val: UInt64): UInt64

功能:采用默认内存排序方式,将原子类型的值与参数 val 进行加操作,将结果写入当前原子类型实例,并返回加操作前的值。

参数:

  • val: UInt64 - 与原子类型进行加操作的值。

返回值:

  • UInt64 - 执行加操作前的值。

func fetchAdd(UInt64, MemoryOrder)

public func fetchAdd(val: UInt64, memoryOrder!: MemoryOrder): UInt64

功能:采用参数 memoryOrder 指定的内存排序方式,将原子类型的值与参数 val 进行加操作。将结果写入当前原子类型实例,并返回加法运算前的值。

参数:

  • val: UInt64 - 与原子类型进行加操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt64 - 执行加操作前的值。

func fetchAnd(UInt64)

public func fetchAnd(val: UInt64): UInt64

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: UInt64 - 与原子类型进行与操作的值。

返回值:

  • UInt64 - 执行与操作前的值。

func fetchAnd(UInt64, MemoryOrder)

public func fetchAnd(val: UInt64, memoryOrder!: MemoryOrder): UInt64

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: UInt64 - 与原子类型进行与操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt64 - 执行与操作前的值。

func fetchOr(UInt64)

public func fetchOr(val: UInt64): UInt64

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: UInt64 - 与原子类型进行或操作的值。

返回值:

  • UInt64 - 执行或操作前的值。

func fetchOr(UInt64, MemoryOrder)

public func fetchOr(val: UInt64, memoryOrder!: MemoryOrder): UInt64

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: UInt64 - 与原子类型进行或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt64 - 执行或操作前的值。

func fetchSub(UInt64)

public func fetchSub(val: UInt64): UInt64

功能:采用默认内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: UInt64 - 与原子类型进行减操作的值。

返回值:

  • UInt64 - 执行减操作前的值。

func fetchSub(UInt64, MemoryOrder)

public func fetchSub(val: UInt64, memoryOrder!: MemoryOrder): UInt64

功能:采用参数 memoryOrder 指定的内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: UInt64 - 与原子类型进行减操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt64 - 执行减操作前的值。

func fetchXor(UInt64)

public func fetchXor(val: UInt64): UInt64

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: UInt64 - 与原子类型进行异或操作的值。

返回值:

  • UInt64 - 执行异或操作前的值。

func fetchXor(UInt64, MemoryOrder)

public func fetchXor(val: UInt64, memoryOrder!: MemoryOrder): UInt64

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: UInt64 - 与原子类型进行异或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt64 - 执行异或操作前的值。

func load()

public func load(): UInt64

功能:读取操作,采用默认内存排序方式,读取原子类型的值。

返回值:

  • UInt64 - 当前原子类型的值。

func load(MemoryOrder)

public func load(memoryOrder!: MemoryOrder): UInt64

功能:读取操作,采用参数 memoryOrder 指定的内存排序方式,读取原子类型的值。

参数:

  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt64 - 当前原子类型的值。

func store(UInt64)

public func store(val: UInt64): Unit

功能:写入操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: UInt64 - 写入原子类型的值。

func store(UInt64, MemoryOrder)

public func store(val: UInt64, memoryOrder!: MemoryOrder): Unit

功能:写入操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: UInt64 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

func swap(UInt64)

public func swap(val: UInt64): UInt64

功能:交换操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: UInt64 - 写入原子类型的值。

返回值:

func swap(UInt64, MemoryOrder)

public func swap(val: UInt64, memoryOrder!: MemoryOrder): UInt64

功能:交换操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: UInt64 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

class AtomicUInt8

public class AtomicUInt8

功能:提供 UInt8 类型的原子操作相关函数。

init(UInt8)

public init(val: UInt8)

功能:构造一个封装 UInt8 数据类型的原子类型 AtomicUInt8 的实例,其内部数据初始值为入参 val 的值。

参数:

  • val: UInt8 - 原子类型的初始值。

func compareAndSwap(UInt8, UInt8)

public func compareAndSwap(old: UInt8, new: UInt8): Bool

功能:CAS 操作,采用默认内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,则写入参数 new 指定的值,并返回 true;否则,不写入值,并返回 false

参数:

  • old: UInt8 - 与当前原子类型进行比较的值。
  • new: UInt8 - 比较结果相等时,写入原子类型的值。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func compareAndSwap(UInt8, UInt8, MemoryOrder, MemoryOrder)

public func compareAndSwap(old: UInt8, new: UInt8, successOrder!: MemoryOrder, failureOrder!: MemoryOrder): Bool

功能:CAS 操作,成功时使用 successOrder 指定的内存排序方式,失败时则使用 failureOrder 指定的内存排序方式。

比较当前原子类型的值与参数 old 指定的值是否相等。若相等,写入参数 new 指定的值,返回 true;否则,不写入值,并返回 false

参数:

  • old: UInt8 - 与当前原子类型进行比较的值。
  • new: UInt8 - 比较结果相等时,写入原子类型的值。
  • successOrder!: MemoryOrder - CAS 操作成功时,执行“读 > 修改 > 写”操作需要的内存排序方式。
  • failureOrder!: MemoryOrder - CAS 操作失败时,执行“读”操作需要的内存排序方式。

返回值:

  • Bool - 比较后交换成功返回 true,否则返回 false

func fetchAdd(UInt8)

public func fetchAdd(val: UInt8): UInt8

功能:采用默认内存排序方式,将原子类型的值与参数 val 进行加操作,将结果写入当前原子类型实例,并返回加操作前的值。

参数:

  • val: UInt8 - 与原子类型进行加操作的值。

返回值:

  • UInt8 - 执行加操作前的值。

func fetchAdd(UInt8, MemoryOrder)

public func fetchAdd(val: UInt8, memoryOrder!: MemoryOrder): UInt8

功能:采用参数 memoryOrder 指定的内存排序方式,将原子类型的值与参数 val 进行加操作。将结果写入当前原子类型实例,并返回加法运算前的值。

参数:

  • val: UInt8 - 与原子类型进行加操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt8 - 执行加操作前的值。

func fetchAnd(UInt8)

public func fetchAnd(val: UInt8): UInt8

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: UInt8 - 与原子类型进行与操作的值。

返回值:

  • UInt8 - 执行与操作前的值。

func fetchAnd(UInt8, MemoryOrder)

public func fetchAnd(val: UInt8, memoryOrder!: MemoryOrder): UInt8

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行与操作。将结果写入当前原子类型实例,并返回与操作前的值。

参数:

  • val: UInt8 - 与原子类型进行与操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt8 - 执行与操作前的值。

func fetchOr(UInt8)

public func fetchOr(val: UInt8): UInt8

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: UInt8 - 与原子类型进行或操作的值。

返回值:

  • UInt8 - 执行或操作前的值。

func fetchOr(UInt8, MemoryOrder)

public func fetchOr(val: UInt8, memoryOrder!: MemoryOrder): UInt8

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行或操作。将结果写入当前原子类型实例,并返回或操作前的值。

参数:

  • val: UInt8 - 与原子类型进行或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt8 - 执行或操作前的值。

func fetchSub(UInt8)

public func fetchSub(val: UInt8): UInt8

功能:采用默认内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: UInt8 - 与原子类型进行减操作的值。

返回值:

  • UInt8 - 执行减操作前的值。

func fetchSub(UInt8, MemoryOrder)

public func fetchSub(val: UInt8, memoryOrder!: MemoryOrder): UInt8

功能:采用参数 memoryOrder 指定的内存排序方式,以原子类型的值为被减数,参数 val 为减数,做减操作。将结果写入当前原子类型实例,并返回减操作前的值。

参数:

  • val: UInt8 - 与原子类型进行减操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt8 - 执行减操作前的值。

func fetchXor(UInt8)

public func fetchXor(val: UInt8): UInt8

功能:采用默认内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: UInt8 - 与原子类型进行异或操作的值。

返回值:

  • UInt8 - 执行异或操作前的值。

func fetchXor(UInt8, MemoryOrder)

public func fetchXor(val: UInt8, memoryOrder!: MemoryOrder): UInt8

功能:采用参数 memoryOrder 指定的内存排序方式,将当前原子类型实例的值与参数 val 进行异或操作。将结果写入当前原子类型实例,并返回异或操作前的值。

参数:

  • val: UInt8 - 与原子类型进行异或操作的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt8 - 执行异或操作前的值。

func load()

public func load(): UInt8

功能:读取操作,采用默认内存排序方式,读取原子类型的值。

返回值:

  • UInt8 - 当前原子类型的值。

func load(MemoryOrder)

public func load(memoryOrder!: MemoryOrder): UInt8

功能:读取操作,采用参数 memoryOrder 指定的内存排序方式,读取原子类型的值。

参数:

  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt8 - 当前原子类型的值。

func store(UInt8)

public func store(val: UInt8): Unit

功能:写入操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: UInt8 - 写入原子类型的值。

func store(UInt8, MemoryOrder)

public func store(val: UInt8, memoryOrder!: MemoryOrder): Unit

功能:写入操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型。

参数:

  • val: UInt8 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

func swap(UInt8)

public func swap(val: UInt8): UInt8

功能:交换操作,采用默认内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: UInt8 - 写入原子类型的值。

返回值:

  • UInt8 - 写入前的值。

func swap(UInt8, MemoryOrder)

public func swap(val: UInt8, memoryOrder!: MemoryOrder): UInt8

功能:交换操作,采用参数 memoryOrder 指定的内存排序方式,将参数 val 指定的值写入原子类型,并返回写入前的值。

参数:

  • val: UInt8 - 写入原子类型的值。
  • memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值:

  • UInt8 - 写入前的值。

class Barrier

public class Barrier

功能:提供协调多个线程一起执行到某一个程序点的功能。

率先达到程序点的线程将进入阻塞状态,当所有线程都达到程序点后,才一起继续执行。

init(Int64)

public init(count: Int64)

功能:创建 Barrier 对象。

参数:

  • count: Int64 - 表示需要协调的线程数。

异常:

func wait(Duration)

public func wait(timeout!: Duration = Duration.Max): Unit

功能:线程进入 Barrier 等待点。

如果 Barrier 对象所有调用 wait 的次数(即进入等待点的线程数)等于初始值,那么唤醒所有等待的线程;如果调用 wait 方法次数仍小于初始值,那么当前线程进入阻塞状态直到被唤醒或者等待时间超过 timeout;如果调用 wait 次数已大于初始值,那么线程继续执行。

参数:

class Monitor

public class Monitor <: ReentrantMutex

功能:提供使线程阻塞并等待来自另一个线程的信号以恢复执行的功能。

这是一种利用共享变量进行线程同步的机制,当一些线程因等待共享变量的某个条件成立而挂起时,另一些线程改变共享的变量,使条件成立, 然后执行唤醒操作。这使得挂起的线程被唤醒后可以继续执行。

父类型:

init()

public init()

功能:通过默认构造函数创建 Monitor

func notify()

public func notify(): Unit

功能:唤醒一个等待在该 Montior 上的线程。

异常:

func notifyAll()

public func notifyAll(): Unit

功能:唤醒所有等待在该 Montior 上的线程。

异常:

func wait(Duration)

public func wait(timeout!: Duration = Duration.Max): Bool

功能:当前线程挂起,直到对应的 notify 函数被调用,或者挂起时间超过 timeout

参数:

返回值:

  • Bool - 如果 Monitor 被其它线程唤醒,返回 true;如果超时,则返回 false

异常:

class MultiConditionMonitor

public class MultiConditionMonitor <: ReentrantMutex

功能:提供对同一个互斥锁绑定多个条件变量的功能。

注意:

  • 该类应仅当在 Monitor 类不足以实现高级并发算法时被使用。
  • 初始化时,MultiConditionMonitor 没有与之相关的条件变量。
  • 每次调用 newCondition 将创建一个新的等待队列并与当前对象关联,并返回ConditionID类型实例作为唯一标识符。

父类型:

init()

public init()

功能:通过默认构造函数创建 MultiConditionMonitor

func newCondition()

public func newCondition(): ConditionID

功能:创建一个与该 Monitor 相关的 ConditionID,可能被用来实现 “单互斥体多等待队列” 的并发原语。

返回值:

异常:

func notify(ConditionID)

public func notify(condID: ConditionID): Unit

功能:唤醒等待在所指定的条件变量的线程(如果有)。

参数:

异常:

func notifyAll(ConditionID)

public func notifyAll(condID: ConditionID): Unit

功能:唤醒所有等待在所指定的条件变量的线程(如果有)。

参数:

异常:

func wait(ConditionID, Duration)

public func wait(condID: ConditionID, timeout!: Duration = Duration.Max): Bool

功能:当前线程挂起,直到对应的 notify 函数被调用。

参数:

返回值:

  • Bool - 如果该 Monitor 指定的条件变量被其它线程唤醒,返回 true;如果超时,则返回 false

异常:

class ReentrantMutex

public open class ReentrantMutex <: IReentrantMutex

功能:提供可重入锁相关功能。

可重入互斥锁的作用是对临界区加以保护,使得任意时刻最多只有一个线程能够执行临界区的代码。 当一个线程试图获取一个已被其他线程持有的锁时,该线程会被阻塞,直到锁被释放,该线程才会被唤醒,可重入是指线程获取该锁后可再次获得该锁。

注意:

  • ReentrantMutex 是内置的互斥锁,开发者需要保证不继承它。
  • 在访问共享数据之前,必须尝试获取锁。
  • 处理完共享数据后,必须进行解锁,以便其他线程可以获得锁。

父类型:

init()

public init()

功能:创建可重入互斥锁。

异常:

func lock()

public open func lock(): Unit

功能:锁定互斥体,如果互斥体已被锁定,则阻塞。

func tryLock()

public open func tryLock(): Bool

功能:尝试锁定互斥体。

返回值:

  • Bool - 如果互斥体已被锁定,则返回 false;反之,则锁定互斥体并返回 true

func unlock

public open func unlock(): Unit

功能:解锁互斥体。

如果互斥体被重复加锁了 N 次,那么需要调用 N 次该函数来完全解锁,一旦互斥体被完全解锁,如果有其他线程阻塞在此锁上,那么唤醒他们中的一个。

异常:

class ReentrantReadMutex

public class ReentrantReadMutex <: ReentrantMutex

功能:提供可重入读写锁中的读锁类型。

父类型:

func lock()

public func lock(): Unit

功能:获取读锁。

注意:

  • 在公平模式下,如果没有其他线程持有或等待写锁,或是当前线程已持有读锁,则立即持有读锁;否则,当前线程进入等待状态。
  • 在非公平模式下,如果没有其他线程持有或等待写锁,则立即持有读锁;如果有其他线程持有写锁,当前线程进入等待状态;否则,线程是否能立即持有读锁不做保证。
  • 多个线程可以同时持有读锁并且一个线程可以重复多次持有读锁;如果一个线程持有写锁,那么它仍可以持有读锁。

func tryLock()

public func tryLock(): Bool

功能:尝试获取读锁。该方法获取读锁时并不遵循公平模式。

返回值:

  • Bool - 若成功获取读锁,返回 true;若未能获取读锁,返回 false

func unlock()

public func unlock(): Unit

功能:释放读锁。如果一个线程多次持有读锁,那么仅当释放操作和获取操作数量相同时才释放读锁;如果读锁被释放并且存在线程等待写锁,那么唤醒其中一个线程。

异常:

class ReentrantReadWriteMutex

public class ReentrantReadWriteMutex

功能:提供可重入读写锁相关功能。

它和普通互斥锁的差异在于:读写锁同时携带两个互斥锁,分别为“读锁”以及“写锁”,并且它允许多个线程同时持有读锁。

读写锁的特殊性质说明:

  • 写互斥性:只有唯一的线程能够持有写锁。当一个线程持有写锁,而其他线程再次获取锁(读锁或是写锁)时将被阻塞。
  • 读并发性:允许多个线程同时持有读锁。当一个线程持有读锁,其他线程仍然可以获取读锁。但其他线程获取写锁时将被阻塞。
  • 可重入性:一个线程可以重复获取锁。
    • 当线程已持有写锁时,它可以继续获取写锁或者读锁。只有当锁释放操作和获取操作一一对应时,锁才被完全释放。
    • 当线程已持有读锁时,它可以继续获取读锁。当锁释放操作和获取操作一一对应时,锁才被完全释放。注意,不允许在持有读锁的情况下获取写锁,这将抛出异常。
  • 锁降级:一个线程在经历“持有写锁--持有读锁--释放写锁”后,它持有的是读锁而不再是写锁。
  • 读写公平性:读写锁支持两种不同的模式,分别为“公平”及“非公平”模式。
    • 在非公平模式下,读写锁对线程获取锁的顺序不做任何保证。
    • 在公平模式下,当线程获取读锁时(当前线程未持有读锁),如果写锁已被获取或是存在线程等待写锁,那么当前线程无法获取读锁并进入等待。
    • 在公平模式下,写锁释放会优先唤醒所有读线程、读锁释放会优先唤醒一个等待写锁的线程。当存在多个线程等待写锁,他们之间被唤醒的先后顺序并不做保证。

prop readMutex

public prop readMutex: ReentrantReadMutex

功能:获取读锁。

类型:ReentrantReadMutex

prop writeMutex

public prop writeMutex: ReentrantWriteMutex

功能:获取写锁。

类型:ReentrantWriteMutex

init(ReadWriteMutexMode)

public init(mode!: ReadWriteMutexMode = ReadWriteMutexMode.Unfair)

功能:构造读写锁。

参数:

  • mode!: ReadWriteMutexMode - 读写锁模式,默认值为 Unfair,即构造“非公平”的读写锁。

class ReentrantWriteMutex

public class ReentrantWriteMutex <: ReentrantMutex

功能:提供可重入读写锁中的写锁类型。

父类型:

func lock()

public func lock(): Unit

功能:获取写锁。只允许唯一线程能够持有写锁,且该线程能多次重复持有写锁。如果存在其他线程持有写锁或是读锁,那么当前线程进入等待状态。

异常:

func tryLock()

public func tryLock(): Bool

功能:尝试获取写锁。该方法获取读锁时并不遵循公平模式。

返回值:

  • Bool - 若成功获取写锁,返回 true;若未能获取写锁,返回 false

func unlock()

public func unlock(): Unit

功能:释放写锁。

注意:

  • 如果一个线程多次持有读锁,那么仅当释放操作和获取操作数量相同时才释放读锁;如果读锁被释放并且存在线程等待写锁,那么唤醒其中一个线程。
  • 在公平模式下,如果写锁被释放并且存在线程等待读锁,那么优先唤醒这些等待线程;如果没有线程等待读锁,但存在线程等待写锁,那么唤醒其中一个线程。
  • 在非公平模式下,如果写锁被释放,优先唤醒等待写锁的线程还是等待读锁的线程不做保证,交由具体实现决定。

异常:

class Semaphore

public class Semaphore

功能:提供信号量相关功能。

Semaphore 可以被视为携带计数器的 Monitor,常用于控制并发访问共享资源的线程数量。

prop count

public prop count: Int64

功能:返回当前内部计数器的值。

类型:Int64

init(Int64)

public init(count: Int64)

功能:创建一个 Semaphore 对象并初始化内部计数器的值。

参数:

异常:

func acquire(Int64)

public func acquire(amount!: Int64 = 1): Unit

功能:向 Semaphore 对象获取指定值。

如果当前计数器小于要求的数值,那么当前线程将被阻塞,直到获取满足数量的值后才被唤醒。

参数:

  • amount!: Int64 - 向对象内部计数器中获取的数值,默认值为 1。

异常:

func release(Int64)

public func release(amount!: Int64 = 1): Unit

功能:向 Semaphore 对象释放指定值。

如果内部计数器在累加释放值后能够满足当前阻塞在 Semaphore 对象的线程,那么将得到满足的线程唤醒;内部计数器的值不会大于初始值,即如果计数器的值在累加后大于初始值,那么仍被设置为初始值。所有在调用 release 之前的操作都先发生于调用 acquire/tryAcquire 之后的操作。

参数:

  • amount!: Int64 - 向对象内部计数器中释放的数值,默认值为 1。

返回值:

  • Unit - 如果当前计数器小于要求的数值,则获取失败并返回 false;成功获取值时返回 true

异常:

func tryAcquire(Int64)

public func tryAcquire(amount!: Int64 = 1): Bool

功能:尝试向 Semaphore 对象获取指定值。

该方法不会阻塞线程。如果有多个线程并发执行获取操作,则无法保证线程间的获取顺序。

参数:

  • amount!: Int64 - 向对象内部计数器中获取的数值,默认值为 1。

返回值:

  • Bool - 如果当前计数器小于要求的数值,则获取失败并返回 false;成功获取值时返回 true

异常:

class SyncCounter

public class SyncCounter

功能:提供倒数计数器功能。

线程可以等待计数器变为零。

prop count

public prop count: Int64

功能:获取计数器的当前值。

类型:Int64

init(Int64)

public init(count: Int64)

功能:创建倒数计数器。

参数:

异常:

func dec()

public func dec(): Unit

功能:计数器减一。

如果计数器变为零,那么唤醒所有等待的线程;如果计数器已经为零,那么数值保持不变。

func waitUntilZero(Duration)

public func waitUntilZero(timeout!: Duration = Duration.Max): Unit

功能:当前线程等待直到计数器变为零,或等待时间超过 timeout

参数:

class Timer

public class Timer <: Equatable<Timer> & Hashable

功能:提供定时器功能。

用于在指定时间点或指定时间间隔后,执行指定任务一次或多次。

注意:

  • Timer 隐式包含了 spawn 操作,即,每个 Timer 会创建一个线程用于执行该 Timer 关联的 Task。
  • 每个 Timer 只能在初始化时绑定一个 Task,初始化完成后,无法重置关联的 Task。
  • 只有关联 Task 执行完毕,或 使用 cancel 接口主动取消 TimerTimer 的生命周期才会结束,之后才能被 GC 回收。换句话说,在 Timer 关联的 Task 执行完毕或 Timer 被主动取消前,Timer 实例均不会被 GC 回收,从而确保关联 Task 可以被正常执行。
  • 系统繁忙时,Task 的触发时间可能会被影响。Timer 不保证 Task 的触发时间一定准时。Timer 保证 Task 的触发时间小于等于当前时间。
  • Timer 不会主动捕获关联 Task 抛出的异常。只要 Task 有未被捕获的异常,Timer 就会失效。
  • Timer 通常按使用方式分为 一次性任务定时器 和 重复性任务定时器两种,一次性任务定时器 Task 只会执行一次,重复性任务定时器 Task 会按指定周期执行, 直到使用 cancel 接口主动取消 或者 达到 Timer 创建时指定的结束条件。

父类型:

static func after(Duration, ()->?Duration)

public static func after(delay: Duration, task: () -> Option<Duration>): Timer

功能:初始化一个 Timer,关联的 Task 被调度执行的次数取决于它的返回值。如果定时器第一次触发的时间点小于当前时间,关联的 Task 会立刻被调度执行。如果关联 Task 的返回值为 Option.None,该 Timer 将会失效,并停止调度关联 Task。如果关联 Task 的返回值为 Option.Some(v) 且 v 大于 Duration.Zero,下次运行前的最小时间间隔将被设置为 v。否则,关联 Task 会立刻再次被调度执行。

参数:

  • delay: Duration - 从现在开始到关联 Task 首次被调度执行的时间间隔
  • task: () ->Option<Duration> - 该 Timer 调度执行的 Task

返回值:

static func once(Duration, ()->Unit)

public static func once(delay: Duration, task: ()->Unit): Timer

功能:设置并启动一次性定时任务,返回控制这个任务的 Timer 对象实例。

参数:

  • delay: 从现在开始到 Task 被执行的时间间隔。取值范围 [Duration.Min, Duration.Max],小于或等于 Duration.Zero 时 Task 将立即被执行。
  • task: 待定时执行的任务。

返回值: Timer 对象实例。

示例:

import std.time.MonoTime

main() {
    let start = MonoTime.now()
    Timer.once(Duration.second, {=>
        println("Tick at: ${MonoTime.now() - start}")
    })

    sleep(Duration.second * 2)
    0
}

运行结果:

Tick at: 1s2ms74us551ns

static func repeat(Duration, Duration, ()->Unit, CatchupStyle)

public static func repeat(delay: Duration, interval: Duration, task: ()->Unit, style!: CatchupStyle = Burst): Timer

功能:设置并启动重复性定时任务,返回控制这个任务的 Timer 对象实例。

参数:

  • delay: 从现在开始到 Task 被执行的时间间隔。取值范围 [Duration.Min, Duration.Max],小于或等于 Duration.Zero 时 Task 将立即被执行。
  • interval: 两次 Task 之间的时间间隔。取值范围 (Duration.Zero, Duration.Max]。
  • task: 待定时执行的任务。
  • style: 追平策略,默认 Burst。当 Task 执行时间过长时,后续任务执行时间点可能发生延迟,不同的追平策略适用于不同的场景,详见 CatchupStyle 说明。

返回值: Timer 对象实例。

异常:

示例:

import std.sync.{Timer}
import std.time.{MonoTime}

main() {
    let start = MonoTime.now()
    let timer = Timer.repeat(Duration.second, Duration.second, {=>
        println("Tick at: ${MonoTime.now() - start}")
    })


    sleep(Duration.second * 5)
    timer.cancel()

    0
}

运行结果:

Tick at: 1s2ms72us188ns
Tick at: 2s4ms185us160ns
Tick at: 3s6ms275us464ns
Tick at: 4s8ms18us399ns
Tick at: 5s9ms621us394ns

static func repeatDuring(Duration, Duration, Duration, ()->Unit, CatchupStyle)

public static func repeatDuring(period: Duration, delay: Duration, interval: Duration, task: () -> Unit, style!: CatchupStyle = Burst): Timer

功能:设置并启动重复性定时任务,指定重复周期的最大持续时间,返回控制这个任务的 Timer 对象实例。

参数:

  • period: 重复周期的最大持续时间,从 delay 之后开始计时。取值范围 (Duration.Zero, Duration.Max]。
  • delay: 从现在开始到 Task 被执行的时间间隔。取值范围 [Duration.Min, Duration.Max],小于或等于 Duration.Zero时 Task 将立即被执行。
  • interval: 两次 Task 之间的时间间隔。取值范围 (Duration.Zero, Duration.Max]。
  • task: 待定时执行的任务。
  • style: 追平策略,默认 Burst。当 Task 执行时间过长时,后续任务执行时间点可能发生延迟,不同的追平策略适用于不同的场景,详见 CatchupStyle 说明。

返回值: Timer 对象实例。

异常:

示例:

import std.sync.{Timer}
import std.time.{MonoTime}

main() {
    let start = MonoTime.now()
    Timer.repeatDuring(Duration.second * 5, Duration.second, Duration.second, {=>
        println("Tick at: ${MonoTime.now() - start}")
    })

    sleep(Duration.second * 7)
    0
}

运行结果:

Tick at: 1s2ms372us626ns
Tick at: 2s4ms714us879ns
Tick at: 3s6ms769us623ns
Tick at: 4s8ms780us235ns
Tick at: 5s660us104ns
Tick at: 6s3ms257us508ns

static func repeatTimes(Int64, Duration, Duration, ()->Unit, CatchupStyle)

public static func repeatTimes(count: Int64, delay: Duration, interval: Duration, task: () -> Unit, style!: CatchupStyle = Burst): Timer

功能:设置并启动重复性定时任务,指定 Task 最大执行次数,返回控制这个任务的 Timer 对象实例。

参数:

  • count: Task 最大执行次数。取值范围 (0, Int64.Max]。
  • delay: 从现在开始到 Task 被执行的时间间隔。取值范围 [Duration.Min, Duration.Max],小于或等于 Duration.Zero 时 Task 将立即被执行。
  • interval: 两次 Task 之间的时间间隔。取值范围 (Duration.Zero, Duration.Max]。
  • task: 待定时执行的任务。
  • style: 追平策略,默认 Burst。当 Task 执行时间过长时,后续任务执行时间点可能发生延迟,不同的追平策略适用于不同的场景,详见 CatchupStyle 说明。

返回值: Timer 对象实例。

异常:

示例:

import std.sync.{Timer}
import std.time.{MonoTime}

main() {
    let start = MonoTime.now()
    Timer.repeatTimes(3, Duration.second, Duration.second, {=>
        println("Tick at: ${MonoTime.now() - start}")
    })

    sleep(Duration.second * 4)
    0
}

运行结果:

Tick at: 1s2ms855us251ns
Tick at: 2s5ms390us18ns
Tick at: 3s7ms935us552ns

func cancel()

public func cancel(): Unit

功能:取消该 Timer,关联 Task 将不再被调度执行。

如果调用该函数时关联 Task 正在执行,不会打断当前运行。该函数不会阻塞当前线程。调用该函数多次等同于只调用一次。

func hashCode()

public func hashCode(): Int64

功能:获取 Timer 对象的哈希值。

返回值: Timer 对象的哈希值。

operator func !=(Timer)

public operator func !=(rhs: Timer): Bool

功能:判断当前 Timer 与入参 rhs 指定的 Timer 是否不是同一个实例。

返回值:

  • Bool - 若两个 Timer 不是同一个实例,则返回 true,否则返回 false

operator func ==(Timer)

public operator func ==(rhs: Timer): Bool

功能:判断当前 Timer 与入参 rhs 指定的 Timer 是否是同一个实例。

返回值:

  • Bool - 若两个 Timer 是同一个实例,则返回 true,否则返回 false

枚举

enum CatchupStyle

public enum CatchupStyle {
    | Delay
    | Burst
    | Skip
}

功能:重复性任务定时器需要使用的追平策略枚举。

当任务执行时间过长时,后续任务执行时间点可能发生延迟,不同的追平策略适用于不同的场景:

  • Delay 适用于不关心任务开始的时间点,需要两次任务执行之间的时间间隔固定的场景。
  • Burst 适用于定时任务之间有先后关系,需要依次执行任务的场景。
  • Skip 适用于定时任务之间没有先后关系,可以忽略中间任务的场景。

示例:

该示例创建了一个 Timer,该 Timer 会执行 3 次任务,从创建开始 1 秒后开始执行,每间隔 1 秒执行下一次任务,追平策略采用 Delay

import std.sync.{Timer, CatchupStyle}
import std.time.{MonoTime}

main() {
    let start = MonoTime.now()
    Timer.repeatTimes(3, Duration.second, Duration.second, {=>
        println("Tick at: ${MonoTime.now() - start}")
    }, style: Delay)

    sleep(Duration.second * 4)
    0
}

Burst

Burst

功能:该策略下,每个任务的开始时间间隔固定,当任务执行时间大于设定的任务触发间隔时间时,依次执行错过的时间点上的任务,直到追平。

Delay

Delay

功能:该策略下,上一次任务结束与下一次任务开始的时间间隔总是固定的,即下一次任务的开始时间 = 上一次任务的结束时间 + 设定的任务触发间隔时间。

Skip

Skip

功能:该策略下,每个任务的开始时间间隔固定,当任务执行时间大于设定的任务触发间隔时间时,将跳过后面错过的时间点,以尽快追平。

enum MemoryOrder

public enum MemoryOrder {
    | SeqCst
}

功能:内存顺序类型枚举。

内存顺序主要是指内存的读(load)写(store)操作的顺序,出于性能优化考虑编译器或CPU可能对指令进行重新排序,内存顺序枚举用来表示排序策略。

SeqCst

SeqCst

功能:用于表示顺序一致的顺序,即禁止了指令重排,确保该原子操作之前的所有原子操作都先于该操作之后的原子操作完成。

enum ReadWriteMutexMode

public enum ReadWriteMutexMode {
    | Unfair
    | Fair
}

功能:读写锁公平模式枚举。

锁的公平性是指,当同时有多个线程在等同一把锁时,是否按照等待顺序依次获得锁。

Fair

Fair

功能:用于表示读写锁公平模式,当锁被释放时,最早等待锁的线程先获得锁。

Unfair

Unfair

功能:用于表示读写锁非公平模式,当锁被释放时,任一等待中的线程可能获得锁。

结构体

struct ConditionID

public struct ConditionID

功能:用于表示互斥锁的条件变量,详见 MultiConditionMonitor

异常类

class IllegalSynchronizationStateException

public class IllegalSynchronizationStateException <: Exception

功能:此类为非法同步状态异常。

父类型:

init()

public init()

功能:创建一个 IllegalSynchronizationStateException 实例。

init(String)

public init(message: String)

功能:创建一个 IllegalSynchronizationStateException 实例,其信息由参数 message 指定。

参数:

  • message: String - 预定义消息。

Atomic、Monitor 和 Timer 的使用

Atomic 的使用

在多线程程序中,使用原子操作实现计数:

import std.sync.*
import std.time.*
import std.collection.*

let count = AtomicInt64(0)

main(): Int64 {
    let list = ArrayList<Future<Int64>>()

    /* 创建 1000 个线程 */
    for (_ in 0..1000) {
        let fut = spawn {
            sleep(Duration.millisecond) /* 睡眠 1 毫秒 */
            count.fetchAdd(1)
        }
        list.append(fut)
    }

    /* 等待所有线程完成 */
    for (f in list) {
        f.get()
    }

    var val = count.load()
    println("count = ${val}")
    return 0
}

输出结果:

count = 1000

Monitor 的使用

示例:

在不同线程中,使用 Monitor 实现挂起和唤醒线程:

import std.sync.*

var mon = Monitor()
var flag: Bool = true

main(): Int64 {
    let fut = spawn {
        mon.lock()
        while (flag) {
            println("New thread: before wait")
            mon.wait()
            println("New thread: after wait")
        }
        mon.unlock()
    }

    /* 睡眠 10 毫秒,以确保新线程可以执行 */
    sleep(10 * Duration.millisecond)

    mon.lock()
    println("Main thread: set flag")
    flag = false
    mon.unlock()

    println("Main thread: notify")
    mon.lock()
    mon.notifyAll()
    mon.unlock()

    /* 等待新线程完成 */
    fut.get()
    return 0
}

输出结果:

New thread: before wait
Main thread: set flag
Main thread: notify
New thread: after wait

Timer 的使用

示例:

使用 Timer 创建一次性和重复性任务:

import std.sync.*

main(): Int64 {
    let count = AtomicInt8(0)

    Timer.once(50 * Duration.millisecond) { =>
        println("run only once")
        count.fetchAdd(1)
    }

    let timer = Timer.repeat(100 * Duration.millisecond, 200 * Duration.millisecond, { =>
        println("run repetitively")
        count.fetchAdd(10)
    })

    sleep(Duration.second)
    timer.cancel()
    sleep(500 * Duration.millisecond)
    println("count = ${count.load()}")
    0
}

输出结果:

run only once
run repetitively
run repetitively
run repetitively
run repetitively
run repetitively
count = 51

std.time 包

功能介绍

time 包提供了与时间相关的类型,包括日期时间,时间间隔,单调时间和时区等,并提供了计算和比较的功能。

时间字符串格式

字符串解析时间有以下要求:

  • 字符串必须包含描述具体年月日的信息:如公元年(y)+ 月(M)和日(d),或公元年(y)和一年中的第几天(D)。

  • 如果不包含时分秒的描述信息,则均默认为 0;如果不包含时区信息,则默认为当前时区 TimeZone.Local。

  • 对同一字母表示的格式不允许两次取值,如不允许两次对公元年(y)格式的赋值;表示时区的 O 和 Z 两种格式同样不允许一起出现。

  • 其余的部分字母的格式会作为辅助信息验证,如“2023-04-24-Mon”使用格式“yyyy-MM-dd-www”进行解析时,会验证“Mon”的正确性。

字母含义

字母含义
a上下午
y公元年
Y基于周的年
M月份
d
D以年算的天数
w以周算的天
W基于 ISO-8601 标准的周
h12小时制的小时
H24小时制的小时
m分钟数
s秒数
S小于一秒的部分
z时区名和时区 ID
Z距零时区偏移
O时区偏移
G纪年

各字母对应规则如下。

规则

上下午

合法个数为 1,表示上午或者下午,固定为“AM”或“PM”。

字母数量解析输出
1、3、4解析 4 位数年份,如 2023、0001等。输出最少 4 位数年份,如 2023、0001、99999 等,不足 4 位则补 0。
2解析 2 位数年份,如 23、69 等,其中 xx >= 69 的会解析为 19xx,否则为 20xx,负数同理。输出 2 位或 4 位以上个数年份,如 23、69 等,其中 [1969, 1999] 会输出为 [69, 99],[2000, 2068] 会输出为 [00, 68],负数同理。其余情况至少输出 4 位,不足 4 位则补 0。
5 ~ 9解析对应数量位数年份。输出对应数量位数年份,不足则补 0。

字母数量解析输出
1解析 1 ~ 2 位数字,如 1、 01、 11 等。输出 1 ~ 2 位数字,如 1、 11 等。
2解析 2 位数字,如 01、11 等。输出 2 位数字,如 01、11 等。
3解析简写的月,如 Jan、Dec 等。输出简写的月,如 Jan、Dec 等。
4解析完整书写的月,如 January、December 等。输出完整书写的月,如 January、December 等。

数值

不同 number 类型数据的表示范围根据实际值大小变动。

字母数量解析输出
1解析 1 ~ 2 位数字,如 1、01、11 等。输出 1 ~ 2 位数字,如 1、 11 等。
2解析 2 位数字,如 01、11 等。输出 2 位数字,如 01、11 等。

小数秒

字母数量解析输出
1解析 3 位数字,如 001、123 等作为毫秒。输出 3 位数字,如 001、123 等作为毫秒。
2解析 6 位数字,如 000001、123456 等作为微秒。输出 6 位数字,如 000001、123456 等作为微秒。
3解析 9 位数字,如 000000001、123456789 等作为纳秒。输出 9 位数字,如 000000001、123456789 等作为纳秒。

时区偏移量

字母数量解析输出
1解析格式如:+08、-08 等。输出格式如:+08、-08 等,若偏移量不为整小时,则会截断。
2解析格式如:+08:00、-08:59 等。输出格式如:+08:00、-08:59 等,偏移量不为整分钟,则会截断。
3解析格式如:+08:00:00、-08:59:59 等。输出格式如:+08:00:00、-08:59:59 等。
4解析格式如:+08:00:00、-08:59:59 等。输出格式如:case2 或 case3、偏移量为 0 时,输出 Z。

时区名和时区 ID

字母数量解析输出
1、2、3解析格式如:CST、GMT 等。输出格式如:CST、GMT 等。
4解析时区 ID,格式如:“Asia/Shanghai”等。输出时区 ID,格式如:“Asia/Shanghai”等。

距零时区偏移

字母数量解析输出
1解析格式如:GMT+0、GMT+10 等。输出格式如:GMT+0、GMT+10 等。
2解析格式如:GMT+00:00、GMT+10:00 等。输出格式如:GMT+00:00、GMT+10:00 等。
3解析格式如:GMT+00:00:00、GMT+10:00:00 等。输出格式如:GMT+00:00:00、GMT+10:00:00 等。
4数量为 2 或 3 的格式。数量为 2 或 3 的格式。

以年算的天数

字母数量解析输出
1解析格式如:1、 01、001 等 1 ~ 3 位数字。输出格式如:1、12、123 等 1 ~ 3 位数字。
2解析格式如:01、001 等 2 ~ 3 位数字。输出格式如:001、012、123 等 2 ~ 3 位数字。

以周算的天

字母数量解析输出
1解析 1 位数字,如 0、6 等、0 表示周日,其余表示周一至周六。输出 1 位数字,如 0、 6 等、0 表示周日,其余表示周一至周六。
2解析 2 位数字,如 00、06 等,00 表示周日,其余表示周一至周六。解析 2 位数字,如 00、06 等,00 表示周日,其余表示周一至周六。
3解析简写的周,如 Sun、Sat 等。解析简写的周,如 Sun、Sat 等。
4解析完整书写的周,如 Sunday、Saturday 等。解析完整书写的周,如 Sunday、Saturday 等。

纪年

字母数量解析输出
1解析 A。输出 A。
2解析 AD。输出 AD。
3解析 Anno Domini。输出 Anno Domini。

API 列表

类名功能
DateTimeFormat提供时间格式的功能,用于解析和生成 DateTime
TimeZoneTimeZone 表示时区,记录了某一地区在不同时间较零时区的时间偏移,提供了从系统加载时区、自定义时区等功能。

枚举

枚举名功能
DayOfWeekDayOfWeek 表示一周中的某一天,提供了与 Int64 类型转换,相等性判别以及获取枚举值的字符串表示的功能。
MonthMonth 用以表示月份,表示一年中的某一月,提供了与 Int64 类型转换和计算,相等性判别以及获取枚举值的字符串表示的功能。

结构体

结构体名功能
DateTimeDateTime 表示日期时间,是一个描述某一时间点的时间类型,提供了基于时区的日期时间读取、计算、比较、转换,以及序列化和反序列化等功能。
MonoTimeMonoTime 表示单调时间,是一个用来衡量经过时间的时间类型,类似于一直运行的秒表,提供了获取当前时间,计算和比较等功能。

异常类

异常类名功能
InvalidDataExceptionInvalidDataException 表示加载时区时的异常。
TimeParseExceptionTimeParseException 表示解析时间字符串时的异常。

class DateTimeFormat

public class DateTimeFormat {
    public static prop RFC1123: DateTimeFormat
    public static prop RFC3339: DateTimeFormat
    public prop format: String
}

功能:提供时间格式的功能,用于解析和生成 DateTime

static prop RFC1123

public static prop RFC1123: DateTimeFormat

功能:提供 RFC1123 时间格式,时间字符串格式为 www, dd MMM yyyy HH:mm:ss z

类型:DateTimeFormat

static prop RFC3339

public static prop RFC3339: DateTimeFormat

功能:提供 RFC3339 时间格式,时间字符串格式为 yyyy-MM-ddTHH:mm:ssOOOO

类型:DateTimeFormat

prop format: String

public prop format: String

功能:DateTimeFormat实例的字符串格式。

类型:String

static func of(String)

public static func of(format: String): DateTimeFormat

功能:根据字符串创建具体的 DateTimeFormat 类型实例。

字符串的具体格式见时间字符串格式

参数:

  • format: String - 字符串格式

返回值:

异常:

class TimeZone

public class TimeZone <: ToString & Equatable<TimeZone> {
    public init(id: String, offset: Duration)
}

功能:TimeZone 表示时区,记录了某一地区在不同时间较零时区的时间偏移,提供了从系统加载时区、自定义时区等功能。

父类型:

static let Local

public static let Local: TimeZone

功能:获取本地时区。

Local 从系统环境变量 TZ 中获取时区 ID,并根据该时区 ID 从系统时区文件中加载时区。其行为与函数load相同。

环境变量 TZ 的取值为标准时区 ID 格式(各操作系统遵循相同规范),例如“Asia/Shanghai”。

若环境变量 TZ 未设置或者为空,加载本地时区的规则如下:

  • 在 Linux/Unix like 系统上:加载系统路径“/etc/localtime”链接,时区名与“/etc/localtime”指向的相对路径名相同,例如“Asia/Shanghai”。
  • 如果上一条执行失败或者在 Windows 系统上,返回 ID 为 “UTC&偏移量” 的时区,例如“Asia/Shanghai”对应的时区为“UTC+08:00”。

类型:TimeZone

static let UTC

public static let UTC: TimeZone

功能:获取 UTC 时区。

类型:TimeZone

prop id

public prop id: String

功能:获取当前 TimeZone 实例所关联的时区 ID。

类型:String

init(String, Duration)

public init(id: String, offset: Duration)

功能:使用指定的时区 ID 和偏移量构造一个自定义 TimeZone 实例。

参数:

  • id: String - 时区 ID。使用“/”作为分隔符,例如“Asia/Shanghai”,各操作系统使用相同规范。
  • offset: Duration - 相对 UTC 时区的偏移量,精度为秒,向东为正、向西为负。取值范围为 (-25 * Duration.hour, 26 * Duration.hour)。

异常:

static func load(String)

public static func load(id: String): TimeZone

功能:从系统中加载参数 id 指定的时区。

  • 在 Linux 、 macOS 和 HarmonyOS 系统中,若存在环境变量 CJ_TZPATH,则使用环境变量指定的路径加载时区文件(若存在多个通过分隔符 “:” 分开的环境变量值,则按照分隔路径的先后顺序依次查找时区文件,并加载第一个找到的时区文件),否则从系统时区文件目录(Linux 和 macOS 为 "/usr/share/zoneinfo",HarmonyOS 为 "/system/etc/zoneinfo")加载时区。
  • 在 Windows 系统中,用户需下载时区文件并编译,设置环境变量 CJ_TZPATH 指向 zoneinfo 目录(若存在多个通过分隔符 “;” 分开的环境变量值,则按照分隔路径的先后顺序依次查找时区文件,并加载第一个找到的时区文件),否则会导致异常。

参数:

返回值:

异常:

  • IllegalArgumentException - 当参数 id 为空,或长度超过 4096 字节,或不符合标准时区 ID 格式时,抛出异常。
  • InvalidDataException - 当时区文件加载失败(找不到文件,文件解析失败等)时,抛出异常。

static func loadFromPaths(String, Array<String>)

public static func loadFromPaths(id: String, tzpaths: Array<String>): TimeZone

功能:根据参数 tzpaths 指定的时区文件目录,加载参数 id 指定的时区。

加载时区时,将从第一个被读取成功的时区文件路径中加载时区。时区文件格式需要满足时区信息格式

参数:

返回值:

异常:

  • IllegalArgumentException - 当 id 为空,或长度超过 4096 字节,或不符合标准时区 ID 格式时,抛出异常。
  • InvalidDataException - 当时区文件加载失败(找不到文件,文件解析失败等)时,抛出异常。

static func loadFromTZData(String, Array<UInt8>)

public static func loadFromTZData(id: String, data: Array<UInt8>): TimeZone

功能:使用指定的时区 ID 和时区数据构造一个自定义 TimeZone 实例。id 可以是任何合法字符串,data 需要满足 IANA 时区文件格式,加载成功时获得 TimeZone 实例,否则抛出异常。

参数:

返回值:

异常:

func toString()

public func toString(): String

功能:获取本 TimeZone 实例时区 ID 的字符串表示。

返回值:

  • String - 时区 ID 的字符串表示。

operator func !=(TimeZone)

public operator func !=(r: TimeZone): Bool

功能:判断当前 TimeZone 实例的引用是否不等于 r 的引用。

参数:

返回值:

  • Bool - truefalse。当前 TimeZone 实例的引用不等于 r 的引用时,返回 true;否则,返回 false

operator func ==(TimeZone)

public operator func ==(r: TimeZone): Bool

功能:判断当前 TimeZone 实例的引用是否等于 r 的引用。

参数:

返回值:

  • Bool - truefalse。当前 TimeZone 实例的引用等于 r 的引用时,返回 true;否则,返回 false

枚举

enum DayOfWeek

public enum DayOfWeek <: ToString {
    | Sunday
    | Monday
    | Tuesday
    | Wednesday
    | Thursday
    | Friday
    | Saturday
}

功能:DayOfWeek 表示一周中的某一天,提供了与 Int64 类型转换,相等性判别以及获取枚举值的字符串表示的功能。

父类型:

Friday

Friday

功能:构造一个表示周五的 DayOfWeek 实例。

Monday

Monday

功能:构造一个表示周一的 DayOfWeek 实例。

Saturday

Saturday

功能:构造一个表示周六的 DayOfWeek 实例。

Sunday

Sunday

功能:构造一个表示周日的 DayOfWeek 实例。

Thursday

Thursday

功能:构造一个表示周四的 DayOfWeek 实例。

Tuesday

Tuesday

功能:构造一个表示周二的 DayOfWeek 实例。

Wednesday

Wednesday

功能:构造一个表示周三的 DayOfWeek 实例。

static func of(Int64)

public static func of(dayOfWeek: Int64): DayOfWeek

功能:获取参数 dayOfWeek 对应的 DayOfWeek 实例。

参数:

  • dayOfWeek: Int64 - 周几的整数表示,合法范围为 [0, 6]。其中,0 表示周日,1 至 6 表示周一至周六。

返回值:

异常:

func toString()

public func toString(): String

功能:返回当前 DayOfWeek 实例的字符串表示,如 "Monday" 表示周一。

返回值:

func value()

public func value(): Int64

功能:获取当前 DayOfWeek 实例的整数表示,周日表示为 0,周一至周六表示为 1 至 6。

返回值:

operator func !=(DayOfWeek)

public operator func !=(r: DayOfWeek): Bool

功能:判断当前 DayOfWeekr 是否不为一周中的同一天。

参数:

返回值:

  • Bool - truefalse。当前 DayOfWeek 实例不等于 r 时,返回 true;否则,返回 false

operator func ==(DayOfWeek)

public operator func ==(r: DayOfWeek): Bool

功能:判断当前 DayOfWeekr 是否表示一周中的同一天。

参数:

返回值:

  • Bool - truefalse。当前 DayOfWeek 实例等于 r 时,返回 true;否则,返回 false

enum Month

public enum Month <: ToString {
    | January
    | February
    | March
    | April
    | May
    | June
    | July
    | August
    | September
    | October
    | November
    | December
}

功能:Month 用以表示月份,表示一年中的某一月,提供了与 Int64 类型转换和计算,相等性判别以及获取枚举值的字符串表示的功能。

父类型:

April

April

功能:构造一个表示四月的 Month 实例。

August

August

功能:构造一个表示八月的 Month 实例。

December

December

功能:构造一个表示十二月的 Month 实例。

February

February

功能:构造一个表示二月的 Month 实例。

January

January

功能:构造一个表示一月的 Month 实例。

July

July

功能:构造一个表示七月的 Month 实例。

June

June

功能:构造一个表示六月的 Month 实例。

March

March

功能:构造一个表示三月的 Month 实例。

May

May

功能:构造一个表示五月的 Month 实例。

November

November

功能:构造一个表示十一月的 Month 实例。

October

October

功能:构造一个表示十月的 Month 实例。

September

September

功能:构造一个表示九月的 Month 实例。

static func of(Int64)

public static func of(mon: Int64): Month

功能:获取参数 mon 对应 Month 类型实例。

参数:

  • mon: Int64 - 整数形式的月,合法范围为 [1, 12],分别表示一年中的十二个月。

返回值:

  • Month - 参数 mon 对应的 Month 类型实例。

异常:

func toString()

public func toString(): String

功能:返回当前 Month 实例的字符串表示,如 "January" 表示一月。

返回值:

func value()

public func value(): Int64

功能:获取当前 Month 实例的整数表示,一月至十二月分别表示为 1 至 12。

返回值:

operator func !=(Month)

public operator func !=(r: Month): Bool

功能:判断当前 Month 实例和 r 是否不为同一个月。

参数:

返回值:

  • Bool - 当前 Month 实例是否不等于 r

operator func +(Int64)

public operator func +(n: Int64): Month

功能:计算基于当前日历月份 n 个月之后(n 为正数时)的日历月份。若 n 为负数,则表示当月之前。

参数:

  • n: Int64 - 后多少月的数量。

返回值:

  • Month - n 月后的月份。

operator func -(Int64)

public operator func -(n: Int64): Month

功能:计算基于当前日历月份 n 个前之后(n 为正数时)的日历月份。若 n 为负数,则表示当月之后。

参数:

  • n: Int64 - 前多少月的数量。

返回值:

  • Month - n 月前的月份。

operator func ==(Month)

public operator func ==(r: Month): Bool

功能:判断当前 Month 实例和 r 是否表示同一个月。

参数:

返回值:

  • Bool - truefalse。当前 Month 实例等于 r 时,返回 true;否则,返回 false

结构体

struct DateTime

public struct DateTime <: ToString & Hashable & Comparable<DateTime>

功能:DateTime 表示日期时间,是一个描述某一时间点的时间类型,提供了基于时区的日期时间读取、计算、比较、转换,以及序列化和反序列化等功能。

  • DateTime 是不可变的类型,包含了日期,时间和时区信息。可表示的时间区间为 [-999,999,999-01-01T00:00:00.000000000, 999,999,999-12-31T23:59:59.999999999],该区间适用于任何合法的时区。

  • 以下为 DateTimenownowUTC 函数获取当前时间使用的系统调用函数:

    系统系统调用函数时钟类型
    Linuxclock_gettimeCLOCK_REALTIME
    Windowsclock_gettimeCLOCK_REALTIME
    macOSclock_gettimeCLOCK_REALTIME

父类型:

static prop UnixEpoch

public static prop UnixEpoch: DateTime

功能:获取 Unix 时间纪元,即表示零时区 1970年1月1日0时0分0秒0纳秒DateTime 实例。

类型:DateTime

prop dayOfMonth

public prop dayOfMonth: Int64

功能:获取 DateTime 实例基于当前月第几日。

类型:Int64

prop dayOfWeek

public prop dayOfWeek: DayOfWeek

功能:获取 DateTime 实例基于当前周的第几日。

类型:DayOfWeek

prop dayOfYear

public prop dayOfYear: Int64

功能:获取 DateTime 实例基于当前年份的第几日。

类型:Int64

prop hour

public prop hour: Int64

功能:获取 DateTime 实例的小时。

类型:Int64

prop isoWeek

public prop isoWeek: (Int64, Int64)

功能:获取 DateTime 实例基于 ISO8601 标准的年份和基于年的周数。

类型:(Int64, Int64)

prop minute

public prop minute: Int64

功能:获取 DateTime 实例的分钟。

类型:Int64

prop month

public prop month: Month

功能:获取 DateTime 实例的月份。

类型:Month

prop monthValue

public prop monthValue: Int64

功能:获取 DateTime 实例以数字形式表示的月份。

类型:Int64

prop nanosecond

public prop nanosecond: Int64

功能:获取 DateTime 实例的纳秒。

类型:Int64

prop second

public prop second: Int64

功能:获取 DateTime 实例的秒。

类型:Int64

prop year

public prop year: Int64

功能:获取 DateTime 实例的年份。

类型:Int64

prop zone

public prop zone: TimeZone

功能:获取 DateTime 实例所关联的时区。

类型:TimeZone

prop zoneId

public prop zoneId: String

功能:获取 DateTime 实例所关联的 TimeZone 实例的时区 ID。

类型:String

prop zoneOffset

public prop zoneOffset: Duration

功能:获取 DateTime 实例所关联的 TimeZone 实例的时间偏移。

类型:Duration

static func fromUnixTimeStamp(Duration)

public static func fromUnixTimeStamp(d: Duration): DateTime

功能:获取自 UnixEpoch 开始,参数 d 指定时间间隔后的日期时间。

参数:

返回值:

异常:

static func now(TimeZone)

public static func now(timeZone!: TimeZone = TimeZone.Local): DateTime

功能:获取参数 timeZone 指定时区的当前时间。该方法获取的当前时间受系统时间影响,如存在使用不受系统时间影响的计时场景,可使用 MonoTime.now() 替代。

参数:

  • timeZone!: TimeZone - 时区,默认为本地时区。

返回值:

  • DateTime - 返回指定时区当前时间。

static func nowUTC()

public static func nowUTC(): DateTime

功能:获取 UTC 时区的当前时间。该方法获取的当前时间受系统时间影响,如存在使用不受系统时间影响的计时场景,可使用 MonoTime.now() 替代。

返回值:

static func of(Int64, Int64, Int64, Int64, Int64, Int64, Int64, TimeZone)

public static func of(
    year!: Int64,
    month!: Int64,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0,
    timeZone!: TimeZone = TimeZone.Local
): DateTime

功能:根据参数指定的年、月、日、时、分、秒、纳秒、时区构造 DateTime 实例。

参数:

  • year!: Int64 - 年,范围[-999,999,999, 999,999,999]。
  • month!: Int64 - 月,范围[1, 12]。
  • dayOfMonth!: Int64 - 日,范围[1, 31],最大取值需要跟 month 匹配,可能是 28、29、30、31。
  • hour!: Int64 - 时,范围[0, 23]。
  • minute!: Int64 - 分,范围[0, 59]。
  • second!: Int64 - 秒,范围[0, 59]。
  • nanosecond!: Int64 - 纳秒,范围[0, 999,999,999]。
  • timeZone!: TimeZone - 时区。

返回值:

异常:

static func of(Int64, Month, Int64, Int64, Int64, Int64, Int64, TimeZone)

public static func of(
    year!: Int64,
    month!: Month,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0,
    timeZone!: TimeZone = TimeZone.Local
): DateTime

功能:根据参数指定的年、月、日、时、分、秒、纳秒、时区构造 DateTime 实例。

参数:

  • year!: Int64 - 年,范围[-999,999,999, 999,999,999]。
  • month!: Month - 月,Month 类型。
  • dayOfMonth!: Int64 - 日,范围[1, 31],最大取值需要跟 month 匹配,可能是 28、29、30、31。
  • hour!: Int64 - 时,范围[0, 23]。
  • minute!: Int64 - 分,范围[0, 59]。
  • second!: Int64 - 秒,范围[0, 59]。
  • nanosecond!: Int64 - 纳秒,范围[0, 999,999,999]。
  • timeZone!: TimeZone - 时区。

返回值:

异常:

static func ofEpoch(Int64, Int64)

public static func ofEpoch(second!: Int64, nanosecond!: Int64): DateTime

功能:根据入参 secondnanosecond 构造 DateTime 实例。入参 second 表示 unix 时间的秒部分,nanosecond 表示 unix 时间的纳秒部分。unix 时间以 UnixEpoch 开始计算,nanosecond 的范围不可以超过[0, 999,999,999],否则抛出异常。

参数:

  • second!: Int64 - unix 时间的秒部分。
  • nanosecond!: Int64 - unix 时间的纳秒部分,范围不可以超过[0, 999,999,999]。

返回值:

异常:

static func ofUTC(Int64, Int64, Int64, Int64, Int64, Int64, Int64, TimeZone)

public static func ofUTC(
    year!: Int64,
    month!: Int64,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0
): DateTime

功能:根据参数指定的年、月、日、时、分、秒、纳秒构造 UTC 时区 DateTime 实例。

参数:

  • year!: Int64 - 年,范围[-999,999,999, 999,999,999]。
  • month!: Int64 - 月,范围[1, 12]。
  • dayOfMonth!: Int64 - 日,范围[1, 31],最大取值需要跟 month 匹配,可能是 28、29、30、31。
  • hour!: Int64 - 时,范围[0, 23]。
  • minute!: Int64 - 分,范围[0, 59]。
  • second!: Int64 - 秒,范围[0, 59]。
  • nanosecond!: Int64 - 纳秒,范围[0, 999,999,999]。

返回值:

异常:

static func ofUTC(Int64, Month, Int64, Int64, Int64, Int64, Int64, TimeZone)

public static func ofUTC(
    year!: Int64,
    month!: Month,
    dayOfMonth!: Int64,
    hour!: Int64 = 0,
    minute!: Int64 = 0,
    second!: Int64 = 0,
    nanosecond!: Int64 = 0
): DateTime

功能:根据参数指定的年、月、日、时、分、秒、纳秒构造 UTC 时区 DateTime 实例。

参数:

  • year!: Int64 - 年,范围[-999,999,999, 999,999,999]。
  • month!: Month - 月,Month 类型
  • dayOfMonth!: Int64 - 日, 范围[1, 31],最大取值需要跟 month 匹配,可能是 28、29、30、31。
  • hour!: Int64 - 时,范围[0, 23]。
  • minute!: Int64 - 分,范围[0, 59]。
  • second!: Int64 - 秒,范围[0, 59]。
  • nanosecond!: Int64 - 纳秒,范围[0, 999,999,999]。

返回值:

异常:

static func parse(String)

public static func parse(str: String): DateTime

功能:从参数 str 中解析得到时间,解析成功时返回 DateTime 实例。

参数:

  • str: String - 时间字符串,格式为 RFC3339date-time 格式,可包含小数秒,如 "2023-04-10T08:00:00[.123456]+08:00"([] 中的内容表示可选项)。

返回值:

异常:

static func parse(String, String)

public static func parse(str: String, format: String): DateTime

功能:根据 format 指定的时间格式,从字符串 str 中解析得到时间,解析成功时返回 DateTime 实例,解析具体规格可见下文“从字符串中解析得到时间”模块。

参数:

  • str: String - 时间字符串,例如:"2023/04/10 08:00:00 +08:00"。
  • format: String - 时间字符串的格式,例如:"yyyy/MM/dd HH:mm:ss OOOO"。格式说明详见时间字符串格式

返回值:

  • DateTime - 根据参数 format 指定的时间格式,从参数 str 中解析出的 DateTime 实例。

异常:

static func parse(String, DateTimeFormat)

public static func parse(str: String, format: DateTimeFormat): DateTime

功能:根据 format 指定的时间格式,从字符串 str 中解析得到时间,解析成功时返回 DateTime 实例,解析具体规格可见下文“从字符串中解析得到时间”模块。

参数:

  • str: String - 时间字符串,例如:"2023/04/10 08:00:00 +08:00"。
  • format: DateTimeFormat - 时间格式,例如:"yyyy/MM/dd HH:mm:ss OOOO"对应的时间格式。格式说明详见时间字符串格式

返回值:

  • DateTime - 根据参数 format 指定的时间格式,从参数 str 中解析出的 DateTime 实例。

异常:

func addDays(Int64)

public func addDays(n: Int64): DateTime

功能:获取 DateTime 实例 n 天之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

func addHours(Int64)

public func addHours(n: Int64): DateTime

功能:获取 DateTime 实例 n 小时之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

func addMinutes(Int64)

public func addMinutes(n: Int64): DateTime

功能:获取 DateTime 实例 n 分钟之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

func addMonths(Int64)

public func addMonths(n: Int64): DateTime

功能:获取 DateTime 实例 n 月之后的时间,返回新的 DateTime 实例。

注意:

由于月的间隔不固定,若设 dt 表示 “2020年3月30日”,dt.addMonths(1) 不会返回非法日期“2020年3月31日”。为了尽量返回有效的日期,会偏移到当月最后一天,返回“2020年4月30日”。

参数:

返回值:

异常:

func addNanoseconds(Int64)

public func addNanoseconds(n: Int64): DateTime

功能:获取 DateTime 实例 n 纳秒之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

func addSeconds(Int64)

public func addSeconds(n: Int64): DateTime

功能:获取 DateTime 实例 n 秒之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

func addWeeks(Int64)

public func addWeeks(n: Int64): DateTime

功能:获取 DateTime 实例 n 周之后的时间,返回新的 DateTime 实例。

参数:

返回值:

异常:

功能:获取入参 n 周之后的时间,返回新的 DateTime 实例。

func addYears(Int64)

public func addYears(n: Int64): DateTime

功能:获取 DateTime 实例 n 年之后的时间,返回新的 DateTime 实例。

注意:

由于年的间隔不固定,若设 dt 表示 “2020年2月29日”,dt.addYears(1) 不会返回非法日期“2021年2月29日”。为了尽量返回有效的日期,会偏移到当月最后一天,返回 “2021年2月28日”。

参数:

返回值:

异常:

func compare(DateTime)

public func compare(rhs: DateTime): Ordering

功能:判断一个 DateTime 实例与参数 rhs 的大小关系。如果大于,返回 Ordering.GT;如果等于,返回 Ordering.EQ;如果小于,返回 Ordering.LT。

参数:

返回值:

func hashCode()

public func hashCode(): Int64

功能:获取 DateTime 实例的哈希值。

返回值:

func inLocal()

public func inLocal(): DateTime

功能:获取 DateTime 实例在本地时区的时间。

返回值:

异常:

func inTimeZone(TimeZone)

public func inTimeZone(timeZone: TimeZone): DateTime

功能:获取 DateTime 实例在参数 timeZone 指定时区的时间。

参数:

返回值:

异常:

func inUTC()

public func inUTC(): DateTime

功能:获取 DateTime 实例在 UTC 时区的时间。

返回值:

异常:

func toString()

public func toString(): String

功能:返回一个表示 DateTime 实例的字符串,其格式为 RFC3339date-time 格式,如果时间包含纳秒信息(不为零),会打印出小数秒。

返回值:

func toString(String)

public func toString(format: String): String

功能:返回一个表示 DateTime 实例的字符串,其格式由参数 format 指定。格式说明详见时间字符串格式

参数:

  • format: String - 返回字符串的格式,其格式可为 "yyyy/MM/dd HH:mm:ss OOOO"。

返回值:

异常:

func toString(DateTimeFormat)

public func toString(format: DateTimeFormat): String

功能:返回一个表示 DateTime 实例的字符串,其格式由参数 format 指定。格式说明详见时间字符串格式

参数:

  • format: DateTimeFormat - 时间格式,其格式可为 "yyyy/MM/dd HH:mm:ss OOOO"。

返回值:

异常:

func toUnixTimeStamp()

public func toUnixTimeStamp(): Duration

功能:获取当前实例自 UnixEpoch 的时间间隔。

返回值:

operator func !=(DateTime)

public operator func !=(r: DateTime): Bool

功能:判断当前 DateTime 实例是否不等于 r

若两个 DateTime 不相等,那么它们指向的不是同一 UTC 时间。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例不等于 r 时,返回 true;否则,返回 false

operator func +(Duration)

public operator func +(r: Duration): DateTime

功能:实现 DateTime 类型和 Duration 类型加法,即 DateTime + Duration 运算。

参数:

  • r: Duration - 加法的右操作数。

返回值:

异常:

operator func -(DateTime)

public operator func -(r: DateTime): Duration

功能:实现 DateTime 类型之间的减法,即 DateTime - DateTime 运算。

参数:

  • r: DateTime - 减法的右操作数。

返回值:

operator func -(Duration)

public operator func -(r: Duration): DateTime

功能:实现 DateTime 类型和 Duration 类型减法,即 DateTime - Duration 运算。

参数:

  • r: Duration - 减法的右操作数。

返回值:

异常:

operator func <(DateTime)

public operator func <(r: DateTime): Bool

功能:判断当前 DateTime 实例是否早于 r(指向更早的 UTC 时间的 DateTime 更小)。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例早于 r 时,返回 true;否则,返回 false

operator func <=(DateTime)

public operator func <=(r: DateTime): Bool

功能:判断当前 DateTime 实例是否早于或等于 r(指向更早的 UTC 时间的 DateTime 更小)。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例早于或等于 r 时,返回 true;否则,返回 false

operator func ==(DateTime)

public operator func ==(r: DateTime): Bool

功能:判断当前 DateTime 实例是否等于 r

若两个 DateTime 相等,那么它们指向同一 UTC 时间。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例等于 r 时,返回 true;否则,返回 false

operator func >(DateTime)

public operator func >(r: DateTime): Bool

功能:判断当前 DateTime 实例是否晚于 r(指向更晚的 UTC 时间的 DateTime 更大)。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例晚于 r 时,返回 true;否则,返回 false

operator func >=(DateTime)

public operator func >=(r: DateTime): Bool

功能:判断当前 DateTime 实例是否晚于或等于 r(指向更晚的 UTC 时间的 DateTime 更大)。

参数:

返回值:

  • Bool - truefalse。当前 DateTime 实例晚于或等于 r 时,返回 true;否则,返回 false

struct MonoTime

public struct MonoTime <: Hashable & Comparable<MonoTime>

功能:MonoTime 表示单调时间,是一个用来衡量经过时间的时间类型,类似于一直运行的秒表,提供了获取当前时间,计算和比较等功能。

  • MonoTime 可表示的范围为 Duration.ZeroDuration.Max,数值表示为 [0, 263)(单位为秒),精度为纳秒。通过 now 方法创建的 MonoTime 总是晚于先使用该方式创建的 MonoTime,常用于性能测试和时间优先的任务队列。

  • 以下为 MonoTimenow 函数获取当前时间使用的系统调用函数:

    系统系统调用函数时钟类型
    Linuxclock_gettimeCLOCK_MONOTONIC
    Windowsclock_gettimeCLOCK_MONOTONIC
    macOSclock_gettimeCLOCK_MONOTONIC

父类型:

static func now()

public static func now(): MonoTime

功能:获取与当前时间对应的 MonoTime

返回值:

func compare(MonoTime)

public func compare(rhs: MonoTime): Ordering

功能:判断一个 MonoTime 实例与参数 rhs 的大小关系。如果大于,返回 Ordering.GT;如果等于,返回 Ordering.EQ;如果小于,返回 Ordering.LT。

参数:

返回值:

func hashCode()

public func hashCode(): Int64

功能:获取当前 MonoTime 实例的哈希值。

返回值:

operator func !=(MonoTime)

public operator func !=(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否不等于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例不等于 r 时,返回 true;否则,返回 false

operator func +(Duration)

public operator func +(r: Duration): MonoTime

功能:实现 MonoTime 类型和 Duration 类型加法,即 MonoTime + Duration 运算。

参数:

返回值:

  • MonoTime - 参数 r 表示时间间隔后的单调时间。

异常:

operator func -(Duration)

public operator func -(r: Duration): MonoTime

功能:实现 MonoTime 类型和 Duration 类型减法,即 MonoTime - Duration 运算。

参数:

返回值:

  • MonoTime - 参数 r 表示时间间隔前的单调时间。

异常:

operator func -(MonoTime)

public operator func -(r: MonoTime): Duration

功能:实现 MonoTime 类型之间的减法,即 MonoTime - MonoTime 运算。

参数:

返回值:

  • Duration - 当前实例距 r 经过的时间间隔。

operator func <(MonoTime)

public operator func <(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否早于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例早于 r 时,返回 true;否则,返回 false

operator func <=(MonoTime)

public operator func <=(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否早于或等于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例早于或等于 r 时,返回 true;否则,返回 false

operator func ==(MonoTime)

public operator func ==(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否等于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例等于 r 时,返回 true;否则,返回 false

operator func >(MonoTime)

public operator func >(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否晚于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例晚于 r 时,返回 true;否则,返回 false

operator func >=(MonoTime)

public operator func >=(r: MonoTime): Bool

功能:判断当前 MonoTime 实例是否晚于或等于 r

参数:

返回值:

  • Bool - truefalse。当前 MonoTime 实例晚于或等于 r 时,返回 true;否则,返回 false

异常类

class InvalidDataException

public class InvalidDataException <: Exception {
    public init()
    public init(message: String)
}

功能:InvalidDataException 表示加载时区时的异常。

父类型:

init()

public init()

功能:构造一个 InvalidDataException 实例。

init(String)

public init(message: String)

功能:根据参数 message 指定的异常信息,构造一个 InvalidDataException 实例。

参数:

  • message: String - 预定义消息。

class TimeParseException

public class TimeParseException <: Exception {
    public init()
    public init(message: String)
}

功能:TimeParseException 表示解析时间字符串时的异常。

父类型:

init()

public init()

功能:构造一个 TimeParseException 实例。

init(String)

public init(message: String)

功能:根据参数 message 指定的异常信息,构造一个 TimeParseException 实例。

参数:

  • message: String - 预定义消息。

DateTime 比较

该示例选取中国标准时间(CST,时区 ID 为“Asia/Shanghai”)和美国东部夏令时时间(EDT,时区 ID 为“America/New_York”)进行时间比较。

说明:

示例中使用 TimeZone.load 函数加载时区信息,在不同平台上加载时区信息有不同的依赖,用户需按其要求进行设置。

import std.time.*

main() {
    let tzSH = TimeZone.load("Asia/Shanghai")
    let tzNY = TimeZone.load("America/New_York")
    // 2024-05-25T00:00:00Z
    let shanghai1 = DateTime.of(year: 2024, month: May, dayOfMonth: 25, hour: 8, timeZone: tzSH)
    let new_york1 = DateTime.of(year: 2024, month: May, dayOfMonth: 24, hour: 20, timeZone: tzNY)

    // 2024-05-25T01:00:00Z
    let shanghai2 = DateTime.of(year: 2024, month: May, dayOfMonth: 25, hour: 9, timeZone: tzSH)
    let new_york2 = DateTime.of(year: 2024, month: May, dayOfMonth: 24, hour: 21, timeZone: tzNY)

    println(shanghai1 == new_york1)
    println(shanghai1 != new_york2)
    println(shanghai1 <= new_york2)
    println(shanghai1 < new_york2)
    println(shanghai2 >= new_york1)
    println(shanghai2 > new_york1)
}

运行结果:

true
true
true
true
true
true

DateTime 与 String 类型的转换

该示例演示了如何通过格式化字符串 pattern,对时间进行格式化打印,以及从格式化字符串中解析时间。

说明:

示例中使用 TimeZone.load 函数加载时区信息,在不同平台上加载时区信息有不同的依赖,用户需按其要求进行设置。

import std.time.*

main() {
    let pattern = "yyyy/MM/dd HH:mm:ssSSS OO"
    let datetime = DateTime.of(
        year: 2024,
        month: May,
        dayOfMonth: 22,
        hour: 12,
        minute: 34,
        second: 56,
        nanosecond: 789000000,
        timeZone: TimeZone.load("Asia/Shanghai")
    )
    let str = datetime.toString(pattern)
    println(str)
    println(DateTime.parse(str, pattern))
}

运行结果

2024/05/22 12:34:56789000000 +08:00
2024-05-22T12:34:56.789+08:00

获取日期时间信息

该示例演示了如何获取日期时间的年、月、日等信息。

说明:

示例中使用 TimeZone.load 函数加载时区信息,在不同平台上加载时区信息有不同的依赖,用户需按其要求进行设置。

import std.time.*

main() {
    let datetime = DateTime.of(
        year: 2024,
        month: May,
        dayOfMonth: 22,
        hour: 12,
        minute: 34,
        second: 56,
        nanosecond: 789000000,
        timeZone: TimeZone.load("Asia/Shanghai")
    )

    let yr = datetime.year
    let mon = datetime.month
    let day = datetime.dayOfMonth
    let hr = datetime.hour
    let min = datetime.minute
    let sec = datetime.second
    let ns = datetime.nanosecond
    let zoneId = datetime.zoneId
    let offset = datetime.zoneOffset
    let dayOfWeek = datetime.dayOfWeek
    let dayOfYear = datetime.dayOfYear
    let (isoYear, isoWeek) = datetime.isoWeek

    println("datetime is ${yr}, ${mon}, ${day}, ${hr}, ${min}, ${sec}, ${ns}, ${zoneId}, ${offset}")
    println("datetime.toString() = ${datetime}")
    println("${dayOfWeek}, ${dayOfYear}th day, ${isoWeek}th week of ${isoYear}")
}

运行结果

datetime is 2024, May, 22, 12, 34, 56, 789000000, Asia/Shanghai, 8h
datetime.toString() = 2024-05-22T12:34:56.789+08:00
Wednesday, 143th day, 21th week of 2024

同一时间在不同时区的本地时间

该示例演示了如何将一个中国标准时间,转换为同一时间下 UTC 和美国东部夏令时时间。

说明:

示例中使用 TimeZone.load 函数加载时区信息,在不同平台上加载时区信息有不同的依赖,用户需按其要求进行设置。

import std.time.*

main() {
    let datetime = DateTime.of(year: 2024, month: May, dayOfMonth: 22, hour: 12, timeZone: TimeZone.load("Asia/Shanghai"))

    println("CST: ${datetime}")
    println("UTC: ${datetime.inUTC()}")
    println("EDT: ${datetime.inTimeZone(TimeZone.load("America/New_York"))}")
}

运行结果

CST: 2024-05-22T12:00:00+08:00
UTC: 2024-05-22T04:00:00Z
EDT: 2024-05-22T00:00:00-04:00

利用 MonoTime 作计时

该示例演示了如何通过 MonoTime 类型进行计时。

import std.time.*

const count = 10000
main() {
    let start = MonoTime.now()
    for (_ in 0..count) {
        DateTime.now()
    }
    let end = MonoTime.now()
    let result = end - start
    println("total cost: ${result.toNanoseconds()}ns")
}

运行结果(以实际结果为准)

total cost: 951159ns

std.unicode 包

功能介绍

unicode 包提供了按 unicode 编码标准处理字符的能力。

Unicode 是一种字符编码标准,旨在为所有语言和符号提供一个统一的编码方案,以便在计算机系统中交换和处理文本。

Unicode 编码标准将每个字符用唯一的码点表示,同时为每个字符定义了若干属性,如类别(字母、数字、标点等)、脚本(拉丁字母、希腊字母、汉字等)、大小写映射(大写或小写映射关系)、变音符号(是否带有变音符号,如重音符号)。

本包提供了 UnicodeExtension 接口类型,用于为其他类型扩展 Unicode 相关的字符操作。并为 RuneString 类型实现了若干扩展方法,包括字符类型判断、字符大小写转换等。

API 列表

接口

接口名功能
UnicodeExtensionUnicode 字符集相关扩展的接口,用于为其他类型扩展 Unicode 字符集相关的操作。

接口

interface UnicodeExtension

public interface UnicodeExtension

功能:Unicode 字符集相关扩展的接口,用于为其他类型扩展 Unicode 字符集相关的操作。

可用于为 RuneString 类型增加一系列与 Unicode 字符集相关的扩展函数,包括字符类型判断,字符大小写转换,删除空白字符等。

extend Rune <: UnicodeExtension

extend Rune <: UnicodeExtension

父类型:

func isLetter()

public func isLetter(): Bool

功能:判断字符是否是 Unicode 字母字符。

返回值:

  • Bool - 如果该字符是 Unicode 字母字符,返回 true,否则返回 false

示例:

import std.unicode.*

main(): Unit {
    println(r'a'.isLetter())
    println(r'1'.isLetter())
}

运行结果:

true
false

func isLowerCase()

public func isLowerCase(): Bool

功能:判断字符是否是 Unicode 小写字符。

返回值:

  • Bool - 如果该字符是 Unicode 小写字符,返回 true,否则返回 false

示例:

import std.unicode.*

main(): Unit {
    println(r'a'.isLowerCase())
    println(r'A'.isLowerCase())
}

运行结果:

true
false

func isNumber()

public func isNumber(): Bool

功能:判断字符是否是 Unicode 数字字符。

返回值:

  • Bool - 如果该字符是 Unicode 数字字符,返回 true,否则返回 false

示例:

import std.unicode.*

main(): Unit {
    println(r'a'.isNumber())
    println(r'1'.isNumber())
}

运行结果:

false
true

func isTitleCase()

public func isTitleCase(): Bool

功能:判断字符是否是 Unicode 标题化字符。

Unicode 中的标题化字符指的是一种特殊的字母形式,它们在某些语言中用于表示标题中每个单词的首字母大写的形式。这些字母由特殊的字符表示,例如U+01C5(Dž)和U+01F1(DZ)。这些字符通常用于一些东欧语言,如克罗地亚语和塞尔维亚语。

标题化字符包括:0x01C50x01C80x01CB0x01F20x1F88 - 0x1F8F0x1F98 - 0x1F9F0x1F98 - 0x1F9F0x1FA8 - 0x1FAF0x1FBC0x1FCC0x1FFC

返回值:

  • Bool - 如果该字符是 Unicode 标题大写字符,返回 true,否则返回 false

示例:

import std.unicode.*

main(): Unit {
    println(r'Dž'.isTitleCase())
}

运行结果:

true

func isUpperCase()

public func isUpperCase(): Bool

功能::判断字符是否是 Unicode 大写字符。

返回值:

  • Bool - 如果该字符是 Unicode 大写字符,返回 true,否则返回 false

示例:

import std.unicode.*

main(): Unit {
    println(r'a'.isUpperCase())
    println(r'A'.isUpperCase())
}

运行结果:

false
true

func isWhiteSpace()

public func isWhiteSpace(): Bool

功能:判断字符是否是 Unicode 空白字符。

空白字符包括 0x00090x000A0x000B0x000C0x000D0x00200x00850x00A00X16800X20000X20010X20020X20030X20040X20050X20060X20070X20080X20090X200A0X20280X20290X202F0X205F0X3000

返回值:

  • Bool - 如果该字符是 Unicode 空白字符,返回 true,否则返回 false

示例:

import std.unicode.*

main(): Unit {
    println(r' '.isWhiteSpace())
}

运行结果:

true

func toLowerCase()

public func toLowerCase(): Rune

功能:获取该字符对应的 Unicode 小写字符。

返回值:

  • Rune - 当前字符对应的小写字符。

示例:

import std.unicode.*

main(): Unit {
    println(r'A'.toLowerCase())
}

运行结果:

a

func toTitleCase()

public func toTitleCase(): Rune

功能:获取该字符对应的 Unicode 标题大写字符。

返回值:

  • Rune - 当前字符对应的标题大写字符。

示例:

import std.unicode.*

main(): Unit {
    println(r'a'.toTitleCase())
}

运行结果:

A

func toUpperCase()

public func toUpperCase(): Rune

功能:获取该字符对应的 Unicode 大写字符。

返回值:

  • Rune - 当前字符对应的小写字符。

示例:

import std.unicode.*

main(): Unit {
    println(r'a'.toUpperCase())
}

运行结果:

A

extend String <: UnicodeExtension

extend String <: UnicodeExtension

父类型:

func isBlank()

public func isBlank(): Bool

功能:判断当前字符串是否为空,或仅包含 Unicode 字符集中的空字符。

空白字符包括 0x00090x000A0x000B0x000C0x000D0x00200x00850x00A00X16800X20000X20010X20020X20030X20040X20050X20060X20070X20080X20090X200A0X20280X20290X202F0X205F0X3000

返回值:

  • Bool - 如果字符串为空,或仅包含空字符,返回 true,否则返回 false

示例:

import std.unicode.*

main(): Unit {
    println(" \t\n\r".isBlank())
}

运行结果:

true

func toLower()

public func toLower(): String

功能:将当前字符串中所有 Unicode 字符集范围内的大写字符转化为小写字符。

返回值:

  • String - 转换后的全小写字符串。

异常:

示例:

import std.unicode.*

main(): Unit {
    println("AbcDEF".toLower())
}

运行结果:

abcdef

func toTitle()

public func toTitle(): String

功能:将当前字符串中 Unicode 字符集范围内可以转换为标题大写字符的转换为标题大写字符。

返回值:

  • String - 转换后的标题大写字符串。

异常:

示例:

import std.unicode.*

main(): Unit {
    println("AbcDEF".toTitle())
}

运行结果:

ABCDEF

func toUpper()

public func toUpper(): String

功能:将当前字符串中所有 Unicode 字符集范围内的小写字符转化为大写字符。

返回值:

  • String - 转换后的全大写字符串。

异常:

示例:

import std.unicode.*

main(): Unit {
    println("AbcDEF".toUpper())
}

运行结果:

ABCDEF

func trim()

public func trim(): String

功能:去除原字符串开头结尾以空字符组成的子字符串,空字符定义见 Rune 类型的扩展函数 isWhiteSpace

返回值:

  • String - 去除首尾空字符后的字符串。

异常:

示例:

import std.unicode.*

main(): Unit {
    println("\nx \t ".trim())
}

运行结果:

x

func trimLeft()

public func trimLeft(): String

功能:去除原字符串开头以空字符组成的子字符串,空字符定义见 Rune 类型的扩展函数 isWhiteSpace

返回值:

  • String - 去除开头空字符后的字符串。

异常:

示例:

import std.unicode.*

main(): Unit {
    println("  x  ".trimLeft())
}

运行结果:

x

func trimRight()

public func trimRight(): String

功能:去除原字符串结尾以空字符组成的子字符串,空字符定义见 Rune 类型的扩展函数 isWhiteSpace

返回值:

  • String - 去除结尾空字符后的字符串。

异常:

示例:

import std.unicode.*

main(): Unit {
    println("  x  ".trimRight())
}

运行结果:

  x

std.unittest 包

功能介绍

Unittest 库用于编写仓颉项目单元测试代码,提供包括代码编写、运行和调测在内的基本功能,并为有经验的用户提供的一些高级功能。 仓颉单元测试支持 cjc 编译器(单包编译模式)和 cjpm 包管理器( 多包模式)。

用户可通过快速入门写出第一个单元测试程序。同时文档对于一些基础概念及用法做了说明并附有示例代码,另外,对于一些高阶特性例如参数化测试等做了进一步说明。

如下 API 从其他包中重导出,因此用户亦可以只导入 unittest 即可使用。

从 unittest.common 包中重导出:

接口

接口名功能
DataProviderDataStrategy 的组件,用于提供测试数据, T 指定提供者提供的数据类型。
DataShrinkerDataStrategy 的组件,用于在测试期间缩减数据,T 指定该收缩器处理的数据类型。
DataStrategy为参数化测试提供数据的策略,T 指定该策略操作的数据类型。

类名功能
Configuration存储 @Configure 宏生成的 unittest 配置数据的对象。Configuration 是一个类似 HashMap 的类,但它的键不是键和值类型,而是 String 类型,和任何给定类型的值。
ConfigurationKey配置项的键值对象。提供判等及 hashCode 方法。

从 unittest.prop_test 包中重导出:

函数

函数名功能
random<T>()该函数生成 T 类型的随机数据,其中 T 必须实现接口 Arbitrary<T> 。该函数的返回值是参数化测试的一种参数源。

接口

接口名功能
Arbitrary生成 T 类型随机值的接口。
Shrink将 T 类型的值缩减到多个“更小”的值。

API 列表

函数

函数名功能
assertCaughtUnexpectedE(String, String, String, Option<AssertionCtx>)捕获的异常不符合预期,记录信息,抛出异常。
assertEqual<T>(String, String, T, T, Option<AssertionCtx>)比较 expectedactual 值是否相等。若不等,直接抛出异常。
csv<T>(String, Rune, Rune, Rune, Option<Rune>, Option<Array<String>>, Array<UInt64>, Array<UInt64>, Bool)该函数可从 csv 文件中读取类型 T 的数据值,其中 T 必须可被序列化。该函数的返回值是参数化测试的一种参数源。
defaultConfiguration()生成默认的配置信息。
entryMain(TestPackage)提供给 cjc --test 使用,框架执行测试用例的入口函数。
expectCaughtUnexpectedE(String,String,String, Option<AssertionCtx>)捕获的异常不符合预期,记录信息,不抛出异常。
expectEqual(String, String, T, T, Option<AssertionCtx>)比较 expectedactual 值是否相等。记录比较结果,不抛出异常。
fail(String)使该用例失败,直接抛出异常。
failExpect(String)使该用例失败,记录信息,不抛出异常。
invokeCustomAssert<T>(Array<String>, String, (AssertionCtx) -> T, Option<AssertionCtx>)运行在 @Test, @TestCase, 或 @CustomAssertion 宏中使用的 @Assert\[caller\](passerArgs) 指定的用户定义断言函数。
invokeCustomExpect<T>(Array<String>, String, (AssertionCtx) -> Any, Option<AssertionCtx>)运行在 @Test, @TestCase, 或 @CustomAssertion 宏中使用的 @Expect\[caller\](passerArgs) 指定的用户定义断言函数。
json<T>(String)该函数可从 JSON 文件中读取类型 T 的数据值,其中 T 必须可被序列化。该函数的返回值是参数化测试的一种参数源。
tsv<T>(String, Rune, Rune, Option<Rune>, Option<Array<String>>, Array<UInt64>, Array<UInt64>, Bool)该函数可从 tsv 文件中读取类型 T 的数据值,其中 T 必须可被序列化。该函数的返回值是参数化测试的一种参数源。

类型别名

类型别名功能
MeasurementUnitTable用于为性能测试指定 Measurement 实例。

接口

接口名功能
BenchInputProvider用于处理性能测试的接口,其中需要在每次性能测试调用之前执行一些代码或者性能测试的输入发生了变化,并且每次都必须从头开始生成。
BenchmarkConfig空接口,区分部分 Configuration 函数为性能相关配置。
BenchmarkInputMarker当我们不知道 T 时,该接口能够检测 BenchInputProvider<T>
Generator生成器生成 T 类型的值。
Measurement在性能测试过程中可以收集和分析各种数据的接口。性能测试期间使用的 Measurement 的具体实例在 @Measure 宏中指定(例如在类声明中)。
TestClass提供创建 TestSuite 的方法。

类名功能
AssertionCtx存储用户定义的断言的状态。提供用于编写​​用户定义断言的方法。
Benchmark该类提供创建和运行单个性能测试用例的方法。
BenchReport提供性能用例执行结果报告处理能力。
CartesianProductProcessor笛卡尔积处理器。
ConsoleReporter打印单元测试用例结果或者性能测试用例结果到控制台。
CsvReporter打印性能测试用例结果数据到 Csv 文件上。
CsvRawReporter打印性能测试用例结果数据,该数据只有批次的原始测量值,到 Csv 文件上。
CsvStrategyDataStrategy 对 CSV 数据格式的序列化实现。
DataStrategyProcessor所有 DataStrategy 组件的基类。该类的实例由 @Strategy 宏或成员函数创建。
FlatMapProcessor对参数数据进行 FlatMap 的处理器。
FlatMapStrategyProcessor对参数数据进行 FlatMap 的处理器。
InputParameter入参对象类型。
JsonStrategyDataStrategy 对 JSON 数据格式的序列化实现。
LazyCyclicNode用于在一个循环中一个接一个地推进类型擦除的内部惰性迭代器。
MapProcessor对参数数据进行 Map 的处理器。
PowerAssertDiagramBuilderPowerAssert 输出结果构造器。
RandomDataProvider使用随机数据生成的 DataProvider 接口的实现。
RandomDataShrinker使用随机数据生成的 DataShrinker 接口的实现。
RandomDataStrategy使用随机数据生成的 DataStrategy 接口的实现。
RawStatsReporter未处理的性能测试数据报告器。仅给框架内部使用。
Report打印测试用例结果报告的基类。
SerializableProvider获取序列化数据 DataProvider 接口的实现。
SimpleProcessor简单的数据策略处理器。对 DataStrategyProcessor 的一种实现。
TestGroup提供构建和运行测试组合方法的类。
TestGroupBuilder提供配置测试组合的方法的构造器。
TestPackage用例包对象。
TestReport单元测试执行结果报告。
TestSuite提供构建和执行测试套方法的类。
TestSuiteBuilder提供配置测试套方法的测试套构造器。
UnitTestCase提供创建和执行单元测试用例的方法的类。
XmlReporter打印单元测试用例结果数据到 Xml 文件上。

枚举

枚举名功能
ExplicitGcType用于指定 @Configure 宏的 explicitGC 配置参数。表示 GC 执行的三种不同方式。
TimeUnit可以在 TimeNow 类构造函数中使用的时间单位。

结构体

结构体名功能
BatchInputProvider输入提供程序,在执行之前在缓冲区中生成整个基准批次的输入。
BatchSizeOneInputProvider基准输入提供程序,在每次执行基准之前生成输入。
GenerateEachInputProvider基准输入提供程序,在每次执行基准之前生成输入。
ImmutableInputProvider最简单的输入提供程序,只需为基准测试的每次调用复制数据。适用于基准测试不会改变输入的情况。它在框架内默认使用。
TimeNowMeasurement 的实现,用于测量执行一个函数所花费的时间。

异常类

异常名功能
AssertException@Expect / @Assert 检查失败时所抛出的异常。
AssertIntermediateException@PowerAssert 检查失败时所抛出的异常。
UnittestCliOptionsFormatException控制台选项格式错误抛出的异常。
UnittestException框架通用异常。

函数

func assertCaughtUnexpectedE(String, String, String, Option<AssertionCtx>)

public func assertCaughtUnexpectedE(
    message: String,
    expectedExceptions: String,
    caughtException: String,
    optParentCtx!: ?AssertionCtx = None
): Nothing

功能:捕获的异常不符合预期,记录信息,抛出异常。

参数:

  • message: String - 不符合预期时的提示信息。
  • expectedExceptions: String - 期望的捕获的异常。
  • caughtException: String - 实际捕获的异常。
  • optParentCtx!: Option<AssertionCtx> - 存储嵌套断言失败消息的上下文。

func assertEqual<T>(String, String, T, T, Option<AssertionCtx>): Unit where T <: Equatable<T>

public func assertEqual<T>(
    leftStr: String,
    rightStr: String,
    expected: T,
    actual: T,
    optParentCtx!: ?AssertionCtx = None): Unit where T <: Equatable<T>

功能:比较 expectedactual 值是否相等。若不等,直接抛出异常。

参数:

  • leftStr: String - 期望的表达式的字符串。
  • rightStr: String - 实际的表达式的字符串。
  • expected: T - 期望的值。
  • actual: T - 实际值。
  • optParentCtx!: Option<AssertionCtx> - 存储嵌套断言失败消息的上下文。

func csv<T>(String, Rune, Rune, Rune, Option<Rune>, Option<Array<String>>, Array<UInt64>, Array<UInt64>, Bool) where T <: Serializable<T>

public func csv<T>(
 fileName: String,
 delimiter!: Rune = ',',
 quoteChar!: Rune = '"',
 escapeChar!: Rune = '"',
 commentChar!: Option<Rune> = None,
 header!: Option<Array<String>> = None,
 skipRows!: Array<UInt64> = [],
 skipColumns!: Array<UInt64> = [],
 skipEmptyLines!: Bool = false
): CsvStrategy<T> where T <: Serializable<T>

功能:该函数可从 csv 文件中读取类型 T 的数据值,其中 T 必须可被序列化。该函数的返回值是参数化测试的一种参数源。

参数:

  • fileName: String - CSV 格式的文件地址,可为相对地址,不限制后缀名。
  • delimiter!: Rune - 一行中作为元素分隔符的符号。默认值为 , (逗号)。
  • quoteChar!: Rune - 括住元素的符号。默认值为 " (双引号)。
  • escapeChar!: Rune :转义括住元素的符号。默认值为 " (双引号)。
  • commentChar!: Option<Rune> - 注释符号,跳过一行。必须在一行的最左侧。默认值是 None (不存在注释符号)。
  • header!: Option<Array<String>> - 提供一种方式覆盖第一行。
    • 当 header 被指定时,文件的第一行将被作为数据行,指定的 header 将被使用。
    • 当 header 被指定,同时第一行通过指定 skipRows 被跳过时,第一行将被忽略,指定的 header 将被使用。
    • 当 header 未被指定时,即值为 None 时,文件的第一行将被作为表头。此为默认值。
  • skipRows!: Array<UInt64> - 指定需被跳过的数据行号,行号从 0 开始。默认值为空数组 []
  • skipColumns!: Array<UInt64> - 指定需被跳过的数据列号,列号从 0 开始。当有数据列被跳过,并且用户指定了自定义的 header 时,该 header 将按照跳过后的实际数据列对应。默认值为空数据 []
  • skipEmptyLines!: Bool - 指定是否需要跳过空行。默认值为 false

返回值:

  • CsvStrategy<T> 对象,T 可被序列化,数据值从 CSV 文件中读取。

func defaultConfiguration()

public func defaultConfiguration(): Configuration

功能:生成默认的配置信息。

返回值:

func entryMain(TestPackage)

public func entryMain(testPackage: TestPackage): Int64

功能:提供给 cjc --test 使用,框架执行测试用例的入口函数。

参数:

返回值:

  • Int64 - 执行结果。

func expectCaughtUnexpectedE(String, String, String, Option<AssertionCtx>)

public func expectCaughtUnexpectedE(
    message: String,
    expectedExceptions: String,
    caughtException: String,
    optParentCtx!: ?AssertionCtx = None
): Unit

功能:捕获的异常不符合预期,记录信息,不抛出异常。

参数:

  • message: String - 不符合预期时的提示信息。
  • expectedExceptions: String - 期望的捕获的异常。
  • caughtException: String - 实际捕获的异常。
  • optParentCtx!: Option<AssertionCtx> - 存储嵌套断言失败消息的上下文。

func expectEqual<T>(String, String, T, T, Option<AssertionCtx>): Unit where T <: Equatable<T>

public func expectEqual<T>(
    leftStr: String,
    rightStr: String,
    expected: T,
    actual: T,
    optParentCtx!: ?AssertionCtx
): Unit where T <: Equatable<T>

功能:比较 expectedactual 值是否相等。记录比较结果,不抛出异常。

参数:

  • leftStr: String - 期望的表达式的字符串。
  • rightStr: String - 实际的表达式的字符串。
  • expected: T - 期望的值。
  • actual: T - 实际值。
  • optParentCtx!: Option<AssertionCtx> - 存储嵌套断言失败消息的上下文。

func fail(String)

public func fail(message: String): Nothing 

功能:使该用例失败,直接抛出异常。

参数:

  • message: String - 失败信息。

func failExpect(String)

public func failExpect(message: String): Unit 

功能:使该用例失败,记录信息,不抛出异常。

参数:

  • message: String - 失败信息。

func invokeCustomAssert<T>(Array<String>, String, (AssertionCtx) -> T, Option<AssertionCtx>)

public func invokeCustomAssert<T>(
    passerdArgs: Array<String>,
    caller: String,
    assert: (AssertionCtx) -> T,
    optParentCtx!: ?AssertionCtx = None
): T 

功能:运行在 @Test, @TestCase, 或 @CustomAssertion 宏中使用的 @Assert\[caller\](passerArgs) 指定的用户定义断言函数。

参数:

  • passedArgs: Array<String> - 未处理的已传递参数。
  • caller: String - 调用的自定义断言的名称。
  • assert: (AssertionCtx) -> T - 捕获带有正确参数的断言调用。
  • optParentCtx!: Option<AssertionCtx> - 存储嵌套断言失败消息的上下文。

返回值:

  • T - 由用户定义的断言返回的值。

func invokeCustomExpect(Array<String>, String, (AssertionCtx) -> Any, Option<AssertionCtx>)

public func invokeCustomExpect(
    passerdArgs: Array<String>,
    caller: String,
    expect: (AssertionCtx) -> Any,
    optParentCtx!: ?AssertionCtx = None
): Unit

功能:运行在 @Test, @TestCase, 或 @CustomAssertion 宏中使用的 @Expect\[caller\](passerArgs) 指定的用户定义断言函数。

参数:

  • passedArgs: Array<String> - 未处理的已传递参数。
  • caller: String - 调用的自定义断言的名称。
  • expect: (AssertionCtx) -> Any - 捕获带有正确参数的断言调用。
  • optParentCtx!: Option<AssertionCtx> - 存储嵌套断言失败消息的上下文。

func json<T>(String) where T <: Serializable<T>

public func json<T>(fileName: String): JsonStrategy<T> where T <: Serializable<T>

功能:该函数可从 JSON 文件中读取类型 T 的数据值,其中 T 必须可被序列化。该函数的返回值是参数化测试的一种参数源。

参数:

  • fileName: String - JSON 格式的文件地址,可为相对地址。

返回值:

  • JsonStrategy<T> - T 可被序列化,数据值从 JSON 文件中读取。

示例:

@Test[user in json("users.json")]
func test_user_age(user: User): Unit {
    @Expect(user.age, 100)
}

json 文件示例:

[
    {
        "age": 100
    },
    {
        "age": 100
    }
]

创建一种被用作测试函数参数的类,该类实现接口 Serializable

import serialization.serialization.*
import std.convert.*
class User <: Serializable<User> {
    User(let age: Int64) {}

    public func serialize(): DataModel {
        DataModelStruct()
          .add(Field("age", DataModelInt(age)))
    }

    public static func deserialize(dm: DataModel): User {
        if (let Some(dms) <- (dm as DataModelStruct)) {
          if (let Some(age) <- (dms.get("age") as DataModelInt)) {
            return User(age.getValue())
          }
        }

        throw Exception("Can't deserialize user.")
    }
}

任何实现 Serializable 的类型都可以用作参数类型,包括默认值:

@Test[user in json("numbers.json")]
func test(value: Int64)
@Test[user in json("names.json")]
func test(name: String)

func tsv<T>(String, Rune, Rune, Option<Rune>, Option<Array<String>>, Array<UInt64>, Array<UInt64>, Bool) where T <: Serializable<T>

public func tsv<T>(
    fileName: String,
    quoteChar!: Rune = '"',
    escapeChar!: Rune = '"',
    commentChar!: Option<Rune> = None,
    header!: Option<Array<String>> = None,
    skipRows!: Array<UInt64> = [],
    skipColumns!: Array<UInt64> = [],
    skipEmptyLines!: Bool = false
): CsvStrategy<T> where T <: Serializable<T>

功能:该函数可从 tsv 文件中读取类型 T 的数据值,其中 T 必须可被序列化。该函数的返回值是参数化测试的一种参数源。

参数:

  • fileName: String - TSV 格式的文件地址,可为相对地址,不限制后缀名。
  • quoteChar!: Rune - 括住元素的符号。默认值为 " (双引号)。
  • escapeChar!: Rune - 转义括住元素的符号。默认值为 " (双引号)。
  • commentChar!: Option<Rune> - 注释符号,跳过一行。必须在一行的最左侧。默认值是 None (不存在注释符号)。
  • header!: Option<Array<String>> - 提供一种方式覆盖第一行。
    • 当 header 被指定时,文件的第一行将被作为数据行,指定的 header 将被使用。
    • 当 header 被指定,同时第一行通过指定 skipRows 被跳过时,第一行将被忽略,指定的 header 将被使用。
    • 当 header 未被指定时,即值为 None 时,文件的第一行(跳过后的实际数据)将被作为表头。此为默认值。
  • skipRows!: Array<UInt64> - 指定需被跳过的数据行号,行号从 0 开始。默认值为空数组 []
  • skipColumns!: Array<UInt64> - 指定需被跳过的数据列号,列号从 0 开始。当有数据列被跳过,并且用户指定了自定义的 header 时,该 header 将按照跳过后的实际数据列对应。默认值为空数据 []
  • skipEmptyLines!: Bool - 指定是否需要跳过空行。默认值为 false

返回值:

  • CsvStrategy<T> - T 可被序列化,数据值从 TSV 文件中读取。

示例:

在单元测试中,可以通过传入 csv/tsv 文件地址进行参数化测试。

CSV 文件每一行的数据应当被表示成一个 Serializable<T> 对象,它的成员名是文件每一列头的值,成员值是 DataModelString 类型的对应列号上的值。

举例来说,有一个 testdata.csv 文件,具有如下内容:

username,age
Alex Great,21
Donald Sweet,28

有几种方式可以序列化上述数据:

  1. 将数据表示为 HashMap<String, String> 类型。

    具体示例为:

    import std.collection.HashMap
    import std.unittest.*
    import std.unittest.testmacro.*
    
    
    @Test[user in csv("testdata.csv")]
    func testUser(user: HashMap<String, String>) {
        @Assert(user["username"] == "Alex Great" || user["username"] == "Donald Sweet")
        @Assert(user["age"] == "21" || user["age"] == "28")
    }
    
  2. 将数据表示为 Serializable<T> 类型数据,其 String 类型的数据可被反序列化为 DataModelStruct 格式对象。

具体示例为:

import serialization.serialization.*
import std.convert.*
import std.unittest.*
import std.unittest.testmacro.*


public class User <: Serializable<User> {
    public User(let name: String, let age: UInt32) {}

    public func serialize(): DataModel {
        let dms = DataModelStruct()
        dms.add(Field("username", DataModelString(name)))
        dms.add(Field("age", DataModelString(age.toString())))
        return dms
    }

    static public func deserialize(dm: DataModel): User {
        var data: DataModelStruct = match (dm) {
            case dms: DataModelStruct => dms
            case _ => throw DataModelException("this data is not DataModelStruct")
        }

        let name = String.deserialize(data.get("username"))
        let age = String.deserialize(data.get("age"))
        return User(name, UInt32.parse(age))
    }
}

@Test[user in csv("testdata.csv")]
func testUser(user: User) {
   @Assert(user.name == "Alex Great" || user.name == "Donald Sweet")
   @Assert(user.age == 21 || user.age == 28)
}

类型别名

type MeasurementUnitTable

type MeasurementUnitTable = Array<(Float64, String)>

功能:用作 Measurement 中性能测试结果单位转换表的“边界-单位”对数组的别名。 要显示的性能测试结果值是根据归一化期间的边界从该表计算得出的。 例如,对于时间单位,它可以遵循 [(1.0, "ns"), (1_000.0, "us"), (1_000_000.0, "ms"), (1_000_000_000.0, "s"), ...]

接口

interface BenchInputProvider

public interface BenchInputProvider<T> <: BenchmarkInputMarker  {
    mut func get(idx: Int64): T
    mut func reset(max: Int64)
}

功能:用于处理性能测试的接口,其中需要在每次性能测试调用之前执行一些代码或者性能测试的输入发生了变化,并且每次都必须从头开始生成。 要使用此功能,您的 DataStrategy 实现应返回此接口的实现者。 推荐的方法是使用 @Strategy 宏。

父类型:

mut func get(Int64)

mut func get(idx: Int64): T

功能:获取元素,该函数的执行时间包含在基准测量中,然后作为框架开销计算的一部分从结果中排除。

参数:

  • idx : Int64 - 元素索引值。

返回值:

  • T - 元素值。

mut func reset(Int64)

mut func reset(max: Int64)

功能:在基准测量之前调用。调用此函数后,后续的 get(i) 调用必须成功获取 [0, max) 中的 i

参数:

  • max : Int64 - 最大值。

interface BenchmarkConfig

public interface BenchmarkConfig{}

功能:空接口,区分部分 Configuration 函数为性能相关配置。

interface BenchmarkInputMarker

public interface BenchmarkInputMarker

功能:当我们不知道 T 时,该接口能够检测 BenchInputProvider<T>

interface Generator<T>

public interface Generator<T> {
    func next(): T
}

功能:生成器生成 T 类型的值。

func next()

func next(): T

功能:获取生成出来的 T 类型的值。

返回值:

  • T - 生成的 T 类型的值。

interface Measurement

public interface Measurement {
    prop conversionTable: MeasurementUnitTable
    prop name: String
    func measure(): Float64
}

功能:该接口指定如何在性能测试期间测量数据以及如何在报告中显示数据。 实现接口的实例可以作为宏 @Measure 的属性传递。

prop conversionTable: MeasurementUnitTable

prop conversionTable: MeasurementUnitTable

功能:用于在性能测试报告中构建测量值的表示。 包含测量单位的边界对。 根据值的边界,使用最合适的单位。 对于 CSV 格式报告,始终选择下限以简化结果处理。 默认值为 [(1.0, "")]

类型:MeasurementUnitTable

prop name: String

prop name: String

功能:当前 Measurement 类型的唯一显示名称。 有助于区分报告表中的不同测量类型。 默认值为 Measurement

类型:String

func measure()

func measure(): Float64

功能:将用于统计分析的测量运行时间的方法。

返回值:

  • Float64 - 测量得到的数据。

interface Reporter

sealed interface Reporter <TReport, TReturn>

功能:报告器基础接口。

interface TestClass

public interface TestClass {
    func asTestSuite(): TestSuite
}

功能:提供创建 TestSuite 的方法。

func asTestSuite()

func asTestSuite(): TestSuite

功能:创建 TestSuite 的方法。

返回值:

class AssertionCtx

public class AssertionCtx

功能: 存储用户定义的断言的状态。提供用于编写​​用户定义断言的方法。

prop args

public prop args: String

功能: 返回以逗号分隔的未解析的用户定义断言参数的字符串。

类型: String

prop caller

public prop caller: String

功能:获取用户定义的断言函数的标识符。

类型: String

prop hasErrors

public prop hasErrors: Bool

功能: 如果用户定义内的任何断言失败,则为 true 。否则为 false

类型: Bool

func arg(String)

public func arg(key: String): String

功能: 返回表示原始传递的标识符的参数值的字符串表达,与参数列表中的标识符匹配。

参数:

  • key: String - 函数参数列表中的标识符。

返回值:

  • String - 对应标识符的参数值字符串表达。

func fail(String)

public func fail(message: String): Nothing 

功能: 存储失败信息,在用户定义的断言函数中提供并抛出 AssertExpection

参数:

  • message: String - 失败信息。

func fail<PP>(PP)

public func fail<PP>(pt: PP): Nothing where PP <: PrettyPrintable

功能: 存储失败信息,在用户定义的断言函数中提供并抛出 AssertExpection

参数:

func failExpect(String)

public func failExpect(message: String): Unit 

功能: 存储失败信息,在用户定义的断言函数内提供并继续函数执行。

参数:

  • message: String - 失败信息。

func failExpect<PP>(PP)

public func failExpect<PP>(pt: PP): Unit where PP <: PrettyPrintable

功能: 存储失败信息,在用户定义的断言函数内提供并继续函数执行。

参数:

func setArgsAliases(Array<String>)

public func setArgsAliases(aliases: Array<String>): Unit

功能: 设置别名以通过函数 arg 访问未解析的用户定义的断言函数参数。框架内部使用,用户无需使用该函数。

参数:

class Benchmark

public class Benchmark {}

功能:该类提供创建和运行单个性能测试用例的方法。

prop name

public prop name: String

功能:获取用例名称。

类型:String

func run()

public func run(): BenchReport 

功能:运行该性能用例。

返回值:

static func create(String, Configuration, () -> Unit)

public static func create(name: String, configuration!: Configuration = Configuration(), body!: () -> Unit): Benchmark

功能:创建一个性能测试用例对象。

参数:

  • name : String - 用例名称。
  • configuration!: Configuration - 用例配置信息。
  • body!: () -> Unit - 用例执行体。

返回值:

static func createParameterized<T>(String, DataStrategy<T>, Configuration, (T) -> Unit)

public static func createParameterized<T>(name: String, strategy: DataStrategy<T>, configuration!: Configuration = Configuration(), body!: (T) -> Unit): Benchmark

功能:创建一个参数化的性能测试用例对象。

参数:

  • name : String - 用例名称。
  • strategy : DataStrategy - 参数数据策略。
  • configuration!: Configuration - 用例配置信息。
  • body!: () -> Unit - 用例执行体。

返回值:

static func createParameterized<T>(String, DataStrategyProcessor<T>, Configuration, (T) -> Unit)

public static func createParameterized<T>(name: String, strategy: DataStrategyProcessor<T>, configuration!: Configuration = Configuration(), body!: (T) -> Unit): Benchmark

功能:创建一个参数化的性能测试用例对象。

参数:

返回值:

class BenchReport

public class BenchReport <: Report {}

功能:提供性能用例执行结果报告处理能力。

父类型:

func reportTo<T>(Reporter<BenchReport, T>)

public func reportTo<T>(reporter: Reporter<BenchReport, T>): T

功能:打印性能用例结果报告。

参数:

返回值:

  • T : 打印结果返回值。一般为 Unit 类型。

class CartesianProductProcessor

public class CartesianProductProcessor<T0,T1> <: DataStrategyProcessor<(T0,T1)> {}

功能:笛卡尔积处理器。

父类型:

init(DataStrategyProcessor<T0>, DataStrategyProcessor<T1>)

public CartesianProductProcessor(let left: DataStrategyProcessor<T0>, let right: DataStrategyProcessor<T1>)

功能:构造函数

参数:

class ConsoleReporter

public class ConsoleReporter <: Reporter<TestReport, Unit> & Reporter<BenchReport, Unit>{
    public ConsoleReporter(let colored!: Bool = true)
}

功能:打印单元测试用例结果或者性能测试用例结果到控制台。

父类型:

init(Bool)

public ConsoleReporter(let colored!: Bool = true)

功能:构造函数。

参数:

  • colored!: Bool - 是否使用带颜色的打印,默认带颜色。

class TextReporter

public class TextReporter<PP> <: Reporter<TestReport, PP> & Reporter<BenchReport, PP>
        where PP <: PrettyPrinter {
    public TextReporter(let into!: PP)
}

功能:将单元测试用例结果或性能测试结果打印到 PrettyPrinter 的子类。格式与 ConsoleReporter 相同。

父类型:

init(PP)

public TextReporter(let into!: PP)

功能: 构造器。

参数:

class CsvReporter

public class CsvReporter <: Reporter<BenchReport, Unit> {
    public CsvReporter(let directory: Directory)
}

功能:打印性能测试用例结果数据到 Csv 文件上。

父类型:

init(Directory)

public CsvReporter(let directory: Directory)

功能:构造函数。

参数:

  • directory: Directory - 打印文件生成地址。

class CsvRawReporter

public class CsvRawReporter <: Reporter<BenchReport, Unit> {
    public CsvRawReporter(let directory: Directory)
}

功能:打印性能测试用例结果数据,该数据只有批次的原始测量值,到 Csv 文件上。

父类型:

init(Directory)

public CsvRawReporter(let directory: Directory)

功能:构造函数。

参数:

  • directory: Directory - 打印文件生成地址。

class CsvStrategy

public class CsvStrategy<T> <: DataStrategy<T> where T <: Serializable<T> {}

功能:DataStrategy 对 CSV 数据格式的序列化实现。

父类型:

func provider(Configuration)

public override func provider(configuration: Configuration): SerializableProvider<T>

功能:生成序列化数据迭代器。

参数:

返回值:

class DataStrategyProcessor

abstract sealed class DataStrategyProcessor<T> {}

功能:所有 DataStrategy 组件的基类。该类的实例由 @Strategy 宏或成员函数创建。

prop isInfinite

protected prop isInfinite: Bool

功能: 获取该策略是否为无限。

类型:Bool

func intoBenchmark(String, Configuration, (T, Int64, Int64) -> Float64)

public func intoBenchmark(
    caseName!: String,
    configuration!: Configuration,
    doRun!: (T, Int64, Int64) -> Float64
): Benchmark

功能:宏生成的代码使用的辅助函数。用于创建使用该策略的性能测试用例。

参数:

  • caseName!: String - 用例名称。
  • configuration!: Configuration - 配置信息。
  • doRun!: (T, Int64, Int64) -> Float64 - 性能测试用例执行体。

返回值:

func intoUnitTestCase(String, Configuration, (T) -> Unit)

public func intoUnitTestCase(
    caseName!: String,
    configuration!: Configuration,
    doRun!: (T) -> Unit
): UnitTestCase

功能:宏生成的代码使用的辅助函数。用于创建使用该策略的测试用例。

参数:

  • caseName!: String - 用例名称。
  • configuration!: Configuration - 配置信息。
  • doRun!: (T) -> Unit - 性能测试用例执行体。

返回值:

func lastItemInfo()

protected func lastItemInfo(): Array<InputParameter>

功能:获取上一个处理条目的信息。

返回值:

func lastItem(Configuration)

protected func lastItem(configuration: Configuration): T

功能:获取上一个处理条目。

参数:

返回值:

  • T - 上一个处理条目。

func provide(Configuration)

protected func provide(configuration: Configuration): Iterable<T>

功能:生成依据配置信息和数据策略生成的数据迭代器。

参数:

返回值:

func shrinkLastItem(Configuration, LazyCyclicNode)

protected func shrinkLastItem(configuration: Configuration, engine: LazyCyclicNode): Iterable<T>

功能:收缩上一个条目。

参数:

返回值:

  • Iterable<T> - 收缩后的数据迭代器。

static func start(DataStrategy<T>, String)

public static func start(s: DataStrategy<T>, name: String): SimpleProcessor<T>

功能:DataStrategy 的组合和映射的起点。

参数:

返回值:

static func start<U>(() -> DataStrategy<U>, String)

public static func start<U>(f: () -> DataStrategy<U>, name: String): DataStrategyProcessor<U> where U <: BenchInputProvider < T >

功能:DataStrategy 的组合和映射的起点。

参数:

  • s: () -> DataStrategy<U> - 生成数据策略的闭包。
  • name: String - 用例名称。

返回值:

static func start(() -> DataStrategy<T>, String, Int64)

public static func start(f: () -> DataStrategy<T>, name: String, x!: Int64 = 0): SimpleProcessor<T>

功能:DataStrategy 的组合和映射的起点。

参数:

  • s: () -> DataStrategy<T> - 生成数据策略的闭包。
  • name: String - 用例名称。
  • x!: Int64 - 为实现不同返回值的重构增加的参数。

返回值:

static func start(() -> DataStrategyProcessor<T>, String)

public static func start(f: () -> DataStrategyProcessor<T>, name: String): DataStrategyProcessor<T>

功能:DataStrategy 的组合和映射的起点。

参数:

返回值:

static func start<U>(() -> DataStrategyProcessor<U>, String, Int64)

public static func start<U>(f: () -> DataStrategyProcessor<U>, name: String, x!: Int64 = 0):
    DataStrategyProcessor<U> where U <: BenchInputProvider<T>

功能:DataStrategy 的组合和映射的起点。

参数:

  • s: () -> DataStrategyProcessor<U> - 生成数据策略处理器的闭包。
  • name: String - 用例名称。
  • x!: Int64 - 为实现不同返回值的重构增加的参数。

返回值:

extend <T> DataStrategyProcessor<T>

extend <T> DataStrategyProcessor<T> {}

func map<R>((T) -> R)

public func map<R>(f: (T) -> R): MapProcessor<T, R> 

功能:简单地将 f 应用于原始数据策略的每个项目。 Shrink 也会发生在原始输入上,然后进行映射。

参数:

  • f: (T) -> R - 需要增加的处理逻辑函数。

返回值:

func mapWithConfig<R>((T, Configuration) -> R)

public func mapWithConfig<R>(f: (T, Configuration) -> R): MapProcessor<T, R>

功能:可以访问当前的 Configuration ,只需将 f 应用于原始数据策略的每个项目。 Shrink 也会发生在原始输入上,然后进行映射。

参数:

  • f: (T, Configuration) -> R - 需要增加的处理逻辑函数。

返回值:

func flatMap<R>((T) -> DataProvider<R>)

public func flatMap<R>(f: (T) -> DataProvider<R>): FlatMapProcessor<T, R>

功能:简单地将 f 应用于原始数据策略的每个项目,然后展平结果。 Shrink 也会发生在原始输入上,然后进行 flatMap

参数:

  • f: (T) -> DataProvider<R> - 需要增加的处理逻辑函数。

返回值:

func flatMapStrategy((T) -> DataStrategy<R>)

public func flatMapStrategy<R>(f: (T) -> DataStrategy<R>): FlatMapStrategyProcessor<T, R>

功能:简单地将 f 应用于原始数据策略的每个项目,然后展平结果。 Shrink 是通过返回的策略而不是原始输入来完成的。

参数:

  • f: (T) -> DataStrategy<R> - 需要增加的处理逻辑函数。

返回值:

func product(DataStrategyProcessor<R>)

public func product<R>(p: DataStrategyProcessor<R>): CartesianProductProcessor<T, R>

功能:笛卡尔积组合器创建包含原始策略中元素的所有可能排列的数据策略。 对于无限策略,它首先迭代所有有限的子策略,然后才推进无限的子策略。 Shrink 独立且统一地发生在原始策略的每个元素上。

参数:

返回值:

class FlatMapProcessor

public class FlatMapProcessor<T,R> <: DataStrategyProcessor<R> {}

功能:对参数数据进行 FlatMap 的处理器。

父类型:

class FlatMapStrategyProcessor

public class FlatMapStrategyProcessor<T,R> <: DataStrategyProcessor<R> {}

功能:对参数数据进行 FlatMap 的处理器。

父类型:

class InputParameter

public class InputParameter {}

功能:入参对象类型

class JsonStrategy

public class JsonStrategy<T> <: DataStrategy<T> where T <: Serializable<T> {}

功能:DataStrategy 对 JSON 数据格式的序列化实现。

父类型:

func provider(Configuration)

public override func provider(configuration: Configuration): SerializableProvider<T>

功能:生成序列化数据迭代器。

参数:

返回值:

  • SerializableProvider<T> - 序列化迭代器对象。

class LazyCyclicNode

public open class LazyCyclicNode {}

功能:用于在一个循环中一个接一个地推进类型擦除的内部惰性迭代器。

func advance()

protected open func advance(): ?Unit

功能:前进一个值。

返回值:

  • ?Unit - 当无法前进时返回 None ,否则返回 Unit 。

func recover()

protected open func recover(): Unit

功能: 恢复或后退一个值。

class MapProcessor

public class MapProcessor<T,R> <: DataStrategyProcessor<R> {}

功能:对参数数据进行 Map 的处理器。

父类型:

class PowerAssertDiagramBuilder

public class PowerAssertDiagramBuilder {
    public init(expression: String)
}

功能:PowerAssert 输出结果构造器。

init(String, Int64)

public init(expression: String)

功能:构造函数。

参数:

  • expression: String - 表达式字符串。

func r<T>(T, String, Int64)

public func r<T>(value: T, exprAsText: String, position: Int64): T 

功能:记录对比数据。

参数:

  • value: T - 被记录的数据。
  • exprAsText: String - 表达式字符串。
  • position: Int64 - 位置信息。

返回值:

  • T - 被记录的数据。

func r(String, String, Int64)

public func r(value: String, exprAsText: String, position: Int64): String

功能:记录对比数据。

参数:

  • value: String - 被记录的数据。
  • exprAsText: String - 表达式字符串。
  • position: Int64 - 位置信息。

返回值:

  • String - 被记录的数据。

func r(Rune, String, Int64)

public func r(value: Rune, exprAsText: String, position: Int64): Rune

功能:记录对比数据。

参数:

  • value: Rune - 被记录的数据。
  • exprAsText: String - 表达式字符串。
  • position: Int64 - 位置信息。

返回值:

  • Rune - 被记录的数据。

func h(Exception, String, Int64)

public func h(exception: Exception, exprAsText: String, position: Int64): Nothing

功能:处理异常。

参数:

  • exception: Exception - 需要被处理的异常。
  • exprAsText: String - 表达式字符串。
  • position: Int64 - 位置信息。

func w(Bool)

public func w(passed: Bool): Unit

功能:当用例通过时返回成功结果,失败时抛出异常并打印对比结果。

参数:

  • passed: Bool - 用例是否通过。

class RandomDataProvider

public class RandomDataProvider<T> <: DataProvider<T> where T <: Arbitrary<T> {
    public RandomDataProvider(private let configuration: Configuration)
}

功能:使用随机数据生成的 DataProvider 接口的实现。

父类型:

init(Configuration)

public RandomDataProvider(private let configuration: Configuration)

功能:构造一个随机数据提供者的对象。

参数:

  • configuration: Configuration - 配置对象,必须包含一个随机生成器,名称为 random ,类型为 random.Random

异常:

prop isInfinite

public override prop isInfinite: Bool

功能:是否生成无限的数据。

类型:Bool

func provide()

public override func provide(): Iterable<T>

功能:提供随机化生成的数据。

返回值:

  • Iterable<T> - 从 T 的任意实例创建的无限迭代器。

class RandomDataShrinker

public class RandomDataShrinker<T> <: DataShrinker<T> {}

功能:使用随机数据生成的 DataShrinker 接口的实现。

父类型:

func shrinker(T)

public override func shrink(value: T): Iterable<T>

功能:获取值的缩减器。

参数:

  • value: T - 参数值。

返回值:

  • Iterable<T> - 如果参数实现了 Shrink 接口,则返回缩减后的迭代器,如果未实现,则返回空的数组。

class RandomDataStrategy

public class RandomDataStrategy<T> <: DataStrategy<T> where T <: Arbitrary<T>{}

功能:使用随机数据生成的 DataStrategy 接口的实现。

父类型:

func provider(Configuration)

public override func provider(configuration: Configuration): RandomDataProvider<T>

功能:获取随机数据的提供者。

参数:

返回值:

func shrinker(Configuration)

public override func shrinker(_: Configuration): RandomDataShrinker<T>

功能:获取随机数据的缩减器。

参数:

返回值:

class Report

sealed abstract class Report {}

功能:打印测试用例结果报告的基类。

prop errorCount

public prop errorCount: Int64

功能:获取错误的用例个数。

类型:Int64

prop caseCount

public prop caseCount: Int64

功能:获取用例个数。

类型:Int64

prop passedCount

public prop passedCount:   Int64

功能:获取通过的用例个数。

类型:Int64

prop failedCount

public prop failedCount:   Int64

功能:获取失败的用例个数。

类型:Int64

prop skippedCount

public prop skippedCount:   Int64

功能:获取跳过的用例个数。

类型:Int64

class RawStatsReporter

public class RawStatsReporter <: Reporter<BenchReport, HashMap<String, (Float64, Float64)>> {
    public RawStatsReporter()
}

功能:未处理的性能测试数据报告器。仅给框架内部使用。

父类型:

init()

public RawStatsReporter()

功能:构造器。

class SerializableProvider

public class SerializableProvider<T> <: DataProvider<T> where T <: Serializable<T> {}

功能:获取序列化数据 DataProvider 接口的实现。

父类型:

prop isInfinite

public prop isInfinite: Bool

功能:是否生成无限的数据。

Bool

func provide()

public override func provide(): Iterable<T> 

功能:获取数据迭代器。

返回值:

class SimpleProcessor

public class SimpleProcessor<T> <: DataStrategyProcessor<T> {}

功能:简单的数据策略处理器。对 DataStrategyProcessor 的一种实现。

父类型:

init(() -> DataStrategy<T>, String)

public SimpleProcessor(let buildDelegate:() -> DataStrategy<T>, let name: String)

功能:构造函数。

参数:

  • buildDelegate : () -> DataStrategy<T> - 生成数据策略的闭包。
  • name : String - 处理器名称。

class TestGroup

public class TestGroup {}

功能:提供构建和运行测试组合方法的类。

prop name

public prop name: String

功能:获取测试组合名称。

类型:String

func runBenchmarks()

public func runBenchmarks(): BenchReport

功能:运行所有性能测试用例。

返回值:

func runBenchmarks(Configuration)

public func runBenchmarks(Configuration): BenchReport

功能:带运行配置得执行所有性能测试用例。

参数:

返回值:

func runTests()

public func runTests(): TestReport

功能:执行所有单元测试用例。

返回值:

func runTests(Configuration)

public func runTests(configuration: Configuration): TestReport

功能:带运行配置得执行所有单元测试用例。

参数:

返回值:

static func builder(String)

public static func builder(name: String): TestGroupBuilder

功能:创建测试组合构造器。

参数:

  • name : String - 测试组合名称。

返回值:

static func builder(TestGroup)

public static func builder(group: TestGroup): TestGroupBuilder

功能:创建测试组合构造器。

参数:

返回值:

class TestGroupBuilder

public class TestGroupBuilder {}

功能:提供配置测试组合的方法的构造器。

func add(Benchmark)

public func add(benchmark: Benchmark): TestGroupBuilder

功能:为测试组合增加性能测试用例。

参数:

  • benchmark : Benchmark - 性能测试用例。

返回值:

func add(TestSuite)

public func add(suite: TestSuite): TestGroupBuilder

功能:为测试组合增加单元测试套。

参数:

返回值:

func add(UnitTestCase)

public func add(test: UnitTestCase): TestGroupBuilder

功能:为测试组合增加单元测试用例。

参数:

返回值:

func build()

public func build(): TestGroup

功能:配置完成后,构建测试组合对象。

返回值:

func configure(Configuration)

public func configure(configuration: Configuration): TestGroupBuilder

功能:为测试组合配置配置信息。

参数:

返回值:

func setName(String)

public func setName(name: String): TestGroupBuilder

功能:为测试组合设置名称。

参数:

返回值:

class TestPackage

public class TestPackage {
    public TestPackage(let name: String)
}

功能:用例包对象。

init(String)

public TestPackage(let name: String)

功能:构造函数。

参数:

  • name: String - 用例包名称。

func registerCase(() -> UnitTestCase)

public func registerCase(testCase: () -> UnitTestCase): Unit

功能:注册单元测试用例。

参数:

  • testCase: () -> UnitTestCase - 单元测试用例生成闭包。

func registerSuite(() -> TestSuite)

public func registerSuite(suite: () -> TestSuite): Unit

功能:注册测试套。

参数:

  • suite: () -> TestSuite - 测试套生成闭包。

func registerBench(() -> Benchmark)

public func registerBench(bench: () -> Benchmark): Unit

功能:注册性能用例。

参数:

  • bench: () -> Benchmark - 性能用例生成闭包。

class TestReport

public class TestReport <: Report {}

功能:单元测试执行结果报告。

父类型:

func reportTo<T>(Reporter<TestReport, T>)

public func reportTo<T>(reporter: Reporter<TestReport, T>): T

功能:打印单元测试执行报告。

参数:

返回值:

  • T : 打印返回值,一般为 Unit 。

class TestSuite

public class TestSuite {}

功能:提供构建和执行测试套方法的类。

prop name

public prop name: String

功能:获取测试套名称。

类型:String

func runBenchmarks()

public func runBenchmarks(): BenchReport 

功能:运行所有性能测试用例。

返回值:

func runBenchmarks(Configuration)

public func runBenchmarks(configuration: Configuration): BenchReport

功能:带配置信息得运行所有性能测试用例。

参数:

返回值:

func runTests()

public func runTests(): TestReport

功能:运行测试套。

返回值:

func runTests(Configuration)

public func runTests(configuration: Configuration): TestReport

功能:带配置信息得运行测试套。

参数:

返回值:

static func builder(String)

public static func builder(name: String): TestSuiteBuilder

功能:创建测试套构建器。

参数:

  • name : String - 测试套名称。

返回值:

static func builder(TestSuite)

public static func builder(suite: TestSuite): TestSuiteBuilder

功能:创建测试套构建器。

参数:

返回值:

class TestSuiteBuilder

public class TestSuiteBuilder {}

功能:提供配置测试套方法的测试套构造器。

add(Benchmark)

public func add(benchmark: Benchmark): TestSuiteBuilder

功能:为测试套添加性能用例。

参数:

  • benchmark : Benchmark - 性能测试用例。

返回值:

add(UnitTestCase)

public func add(test: UnitTestCase): TestSuiteBuilder

功能:为测试套添加单元测试用例。

参数:

返回值:

afterAll(() -> Unit)

public func afterAll(body: () -> Unit): TestSuiteBuilder

功能:为测试套添加在所有用例执行完成后执行的生命周期管理闭包。

参数:

  • body : () -> Unit - 执行体。

返回值:

afterEach(() -> Unit)

public func afterEach(body: () -> Unit): TestSuiteBuilder

功能:为测试套添加在每个用例执行完成后执行的生命周期管理闭包。

参数:

  • body : () -> Unit - 执行体。

返回值:

afterEach((String) -> Unit)

public func afterEach(body: (String) -> Unit): TestSuiteBuilder

功能:为测试套添加在每个用例执行完成后执行的生命周期管理闭包。

参数:

  • body : (String) -> Unit - 执行体。

返回值:

beforeAll(() -> Unit)

public func beforeAll(body: () -> Unit): TestSuiteBuilder

功能:为测试套添加在所有用例执行前执行的生命周期管理闭包。

参数:

  • body : () -> Unit - 执行体。

返回值:

beforeEach(() -> Unit)

public func beforeEach(body: () -> Unit): TestSuiteBuilder

功能:为测试套添加在每个用例执行前执行的生命周期管理闭包。

参数:

  • body : () -> Unit - 执行体。

返回值:

beforeEach((String) -> Unit)

public func beforeEach(body: (String) -> Unit): TestSuiteBuilder

功能:为测试套添加在每个用例执行前执行的生命周期管理闭包。

参数:

  • body : (String) -> Unit - 执行体。

返回值:

build()

public func build(): TestSuite

功能:配置完成后构造测试套。

返回值:

configure(Configuration)

public func configure(configuration: Configuration): TestSuiteBuilder

功能:为测试套添加配置信息。

参数:

返回值:

setName(String)

public func setName(name: String): TestSuiteBuilder

功能:为测试套设置名称。

参数:

  • name : String - 测试套名称。

返回值:

class UnitTestCase

public class UnitTestCase {}

功能:提供创建和执行单元测试用例的方法的类。

prop name

public prop name: String

功能:获取单元测试名称。

类型:String

func run()

public func run(): TestReport 

功能:运行单元测试用例。

返回值:

static func create(String, Configuration, () -> Unit)

public static func create(name: String, configuration!: Configuration = Configuration(), body!: () -> Unit): UnitTestCase

功能:创建单元测试用例。

参数:

  • name : String - 用例名称。
  • configuration!: Configuration - 用例配置信息。
  • body!: () -> Unit - 用例执行体。

返回值:

static func createParameterized<T>(String, DataStrategy<T>, Configuration, (T) -> Unit)

public static func createParameterized<T>(name: String, strategy: DataStrategy<T>, configuration!: Configuration = Configuration(), body!: (T) -> Unit): UnitTestCase

功能:创建参数化的单元测试用例。

参数:

  • name : String - 用例名称。
  • strategy : DataStrategy - 参数数据策略。
  • configuration!: Configuration - 用例配置信息。
  • body!: () -> Unit - 用例执行体。

返回值:

static func createParameterized<T>(String, DataStrategyProcessor<T>, Configuration, (T) -> Unit)

public static func createParameterized<T>(name: String, strategy: DataStrategyProcessor<T>, configuration!: Configuration = Configuration(), body!: (T) -> Unit): UnitTestCase

功能:创建参数化的单元测试用例。

参数:

返回值:

class XmlReporter

public class XmlReporter <: Reporter<TestReport, Unit> {
    public XmlReporter(let directory: Directory)
}

功能:打印单元测试用例结果数据到 Xml 文件上。

父类型:

init(Directory)

public XmlReporter(let directory: Directory)

功能:构造函数。

参数:

  • directory: Directory - 打印文件生成地址。

枚举

enum ExplicitGcType

public enum ExplicitGcType <: ToString {
    Disabled |
    Heavy |
    Light
}

功能:用于指定 @Configure 宏的 explicitGC 配置参数。表示 GC 执行的三种不同方式。

父类型:

Disabled

Disabled

功能: GC 不会被框架显式调用。

Heavy

Heavy

功能:std.runtime.GC(heavy: true) 将在性能测试执行期间由框架显式调用。

Light

Light

功能:std.runtime.GC(heavy: false) 将在 Benchmark 函数执行期间由框架显式调用。这是默认设置。

func toString()

public override func toString(): String

功能:GC 执行的三种不同方式字符串。

返回值:

  • String - GC 执行的三种不同方式字符串。

enum TimeUnit

public enum TimeUnit {
    | Micros
    | Millis
    | Nanos
    | Seconds
}

功能:可以在 TimeNow 构造函数中使用的时间单位。

Micros

Micros

功能: 单位为微秒。

Millis

Millis

功能: 单位为毫秒。

Nanos

Nanos

功能: 单位为纳秒。

Seconds

Seconds

功能: 单位为秒。

结构体

struct BatchInputProvider

public struct BatchInputProvider<T> <: BenchInputProvider<T> {
    public BatchInputProvider(let builder: () -> T)
}

功能:输入提供程序,在执行之前在缓冲区中生成整个基准批次的输入。

父类型:

init(() -> T)

public BatchInputProvider(let builder: () -> T)

功能: 默认构造函数。

参数:

  • builder: () -> T - 用于生成基准测试输入的闭包。

mut func get(Int64)

public mut func get(idx: Int64): T

功能:获取元素,该函数的执行时间包含在基准测量中,然后作为框架开销计算的一部分从结果中排除。

参数:

  • idx : Int64 - 元素索引值。

返回值:

  • T - 元素值。

mut func reset(Int64)

public mut func reset(max: Int64)

功能:在基准测量之前调用。调用此函数后,后续的 get(i) 调用必须成功获取 [0, max) 中的 i

参数:

  • max : Int64 - 最大值。

struct BatchSizeOneInputProvider

public struct BatchSizeOneInputProvider<T> <: BenchInputProvider<T>{
    public BatchSizeOneInputProvider(let builder: () -> T)
}

功能:基准输入提供程序,在每次执行基准之前生成输入。 与 GenerateEachInputProvider 的区别在于,当批量大小为 1 时,我们可以测量。 每个基准测试调用都是独立的,因此输入生成永远不会包含在测量中。 如果 GenerateEachInputProvider 给出的结果质量较差,则应使用。 这种情况可能会发生,因为生成输入所需的时间比实际基准要多得多,或者如果输入生成的执行时间非常不稳定。

父类型:

init(() -> T)

public BatchSizeOneInputProvider(let builder: () -> T)

功能: 默认构造函数。

参数:

  • builder: () -> T - 用于生成基准测试输入的 lambda 。

mut func get(Int64)

public mut func get(idx: Int64): T

功能:获取元素,该函数的执行时间包含在基准测量中,然后作为框架开销计算的一部分从结果中排除。

参数:

  • idx : Int64 - 元素索引值。

返回值:

  • T - 元素值。

mut func reset(Int64)

public mut func reset(max: Int64)

功能:在基准测量之前调用。调用此函数后,后续的 get(i) 调用必须成功获取 [0, max) 中的 i

参数:

  • max : Int64 - 最大值。

struct GenerateEachInputProvider

public struct GenerateEachInputProvider<T> <: BenchInputProvider<T>{
    public GenerateEachInputProvider(let builder: () -> T)
}

功能:基准输入提供程序,在每次执行基准之前生成输入。 生成时间包含在基准测量中,然后作为框架开销计算的一部分从最终结果中排除。

父类型:

init(() -> T)

public GenerateEachInputProvider(let builder: () -> T)

功能: 默认构造函数。

参数:

  • builder: () -> T - 用于生成基准测试输入的闭包。

mut func get(Int64)

public mut func get(idx: Int64): T

功能:获取元素,该函数的执行时间包含在基准测量中,然后作为框架开销计算的一部分从结果中排除。

参数:

  • idx : Int64 - 元素索引值。

返回值:

  • T - 元素值。

mut func reset(Int64)

public mut func reset(max: Int64)

功能:在基准测量之前调用。调用此函数后,后续的 get(i) 调用必须成功获取 [0, max) 中的 i

参数:

  • max : Int64 - 最大值。

struct ImmutableInputProvider

public struct ImmutableInputProvider<T> <: BenchInputProvider<T> {
    public ImmutableInputProvider(let data: T)
}

功能:最简单的输入提供程序,只需为基准测试的每次调用复制数据。适用于基准测试不会改变输入的情况。它在框架内默认使用。

父类型:

init(T)

public ImmutableInputProvider(let data: T)

功能: 默认构造函数。

参数:

  • data: T - 基准测试的输入。

mut func get(Int64)

public mut func get(idx: Int64): T

功能:获取元素,该函数的执行时间包含在基准测量中,然后作为框架开销计算的一部分从结果中排除。

参数:

  • idx : Int64 - 元素索引值。

返回值:

  • T - 元素值。

static func createOrExisting(T, Int64)

public static func createOrExisting(arg: T, x!:Int64=0): ImmutableInputProvider<T>

功能:创建或获取一个 ImmutableInputProvider 对象。

参数:

  • arg : T - 提供器需复制的参数。
  • x!: Int64 - 为实现重载而增加的参数。

返回值:

  • ImmutableInputProvider<T> - 输入提供器。

static func createOrExisting<U>(U): U where U <: BenchInputProvider<T>

public static func createOrExisting<U>(arg: U): U where U <: BenchInputProvider<T>

功能:创建或获取一个 BenchInputProvider 的子类型对象。

参数:

  • arg : T - 提供器需复制的参数。

返回值:

  • U where U <: BenchInputProvider<T> - 输入提供器。

struct TimeNow

public struct TimeNow <: Measurement {
    public prop conversionTable: MeasurementUnitTable
    public prop name: String
    public init()
    public init(unit: ?TimeUnit)
}

功能:Measurement 的实现,用于测量执行一个函数所花费的时间。

父类型:

prop conversionTable: MeasurementUnitTable

prop conversionTable: MeasurementUnitTable

功能:提供当前时间的单位换算表。 例如 [(1.0, "ns"), (1e3, "us"), (1e6, "ms"), (1e9, "s")]。 详见 MeasurementUnitTable

类型:MeasurementUnitTable

prop name: String

prop name: String

功能:提供当前时间单位唯一的显示名称,例如:Duration(ns)Duration(s)

类型:String

init()

public init()

功能:自动选择输出格式的默认构造函数。

init(?TimeUnit)

public init(unit: ?TimeUnit) 

功能: unit 参数用于指定打印结果时将使用的时间单位。

参数:

  • unit: ?TimeUnit - 指定的时间单位。

func measure()

public func measure(): Float64

功能:获取当前时间用于统计分析。

返回值:

  • Float64 - 计算得到的数据,用于统计分析。

异常类

class AssertException

public class AssertException <: Exception {
    public init()
    public init(message: String)
}

功能:@Expect / @Assert 检查失败时所抛出的异常。

父类型:

init()

public init(message: String)

功能:构造函数。

init(String)

public init(message: String)

功能:构造函数。

参数:

  • message: String - 指定的异常信息。

class AssertIntermediateException

public class AssertIntermediateException <: Exception {
    public let expression: String
    public let originalException: Exception
}

功能:@PowerAssert 检查失败时所抛出的异常。

父类型:

let expression

public let expression: String

功能:检查的表达式。

类型:String

let originalException

public let originalException: Exception

功能:原始的类型信息。

类型:Exception

func getOriginalStackTrace

public func getOriginalStackTrace(): String

功能:获取原始的栈信息。

返回值:

class UnittestCliOptionsFormatException

public class UnittestCliOptionsFormatException <: UnittestException

功能:控制台选项格式错误抛出的异常。

父类型:

class UnittestException

public open class UnittestException <: Exception

功能:框架通用异常。 父类型:

Unittest 快速入门

先编写一个简单的仓颉函数:

package example

func add(left: Int64, right: Int64) {
    return left + right
}

将这个函数保存在 add.cj 文件中,开始编写该函数的测试代码:

package example

@Test
func addTest() {
    @Expect(add(2, 3), 5)
}

测试包含如下组件:

  • @Test 宏,配置在 addTest 函数上,表示这是一个测试函数。
  • @Expect 宏,作为断言,检查输入的两个参数是否相等。在这个例子中,两个参数分别是 add 函数的结果 add(2, 3) 和预期值 5

将这个测试函数保存在 add_test.cj 文件中,和代码函数一起在 add.cj 中运行。

cjc add.cj add_test.cj --test -o add_test
./add_test

正常情况下,将得到如下类似输出:

-------------------------------------------------------------------------------------------------
TP: default, time elapsed: 59363 ns, Result:
    TCS: TestCase_addTest, time elapsed: 32231 ns, RESULT:
    [ PASSED ] CASE: addTest (28473 ns)
    Summary: TOTAL: 1
    PASSED: 1, SKIPPED: 0, ERROR: 0
    FAILED: 0
--------------------------------------------------------------------------------------------------

至此,我们就完成了测试的构建和运行。 下面我们来详细介绍一下用来构建测试的 cjc 命令。

    待测试的代码文件
    ↓
cjc add.cj add_test.cj --test -o add_test
           ↑           ↑
           |           --test 表明在测试模式下构建生成二进制文件
           测试文件

注意,对于复杂项目来说,不建议直接运行 cjc 编译器。 对于结构庞大的大型项目,建议使用 cjpm 包管理器。 以 cjpm 项目测试为例。

首先创建一个简单的 cjpm 项目,其中包含一个名为 example 的包。 项目的文件结构如下所示(借用 cjc 示例中的文件):

- src
  |
  +- example
     |
     +- add.cj
     +- add_test.cj

原文件已指明它们属于 example 包,因此只需运行以下命令即可初始化 cjpm 项目:

cjpm init example example

cjpm 包管理器内置支持运行单元测试,所以直接运行即可:

cjpm test

此命令会运行项目所有包中的测试,统一生成如下类似输出:

--------------------------------------------------------------------------------------------------
TP: example/example, time elapsed: 60989 ns, Result:
    TCS: TestCase_addTest, time elapsed: 32804 ns, RESULT:
    [ PASSED ] CASE: addTest (29195 ns)
    Summary: TOTAL: 1
    PASSED: 1, SKIPPED: 0, ERROR: 0
    FAILED: 0
--------------------------------------------------------------------------------------------------

注意,无需指定 --test 或任何其他特殊选项。 默认情况下,cjpm 使用项目中的文件名来确认文件应该在测试模式还是正常模式下编译。 示例包中, add_test.cj 是测试文件,文件名以 _test.cj 结尾。 正常构建时,二进制文件或库的构建不包含这些文件。

单元测试框架 API 已经存在于 std 模块的 unittest 包中,宏也存在于 std 模块的 unittest.testmacro 包中,因此不需要在测试文件中显式导入。

如需了解更多关于 unittest 框架的基本概念,请参考单元测试基础

Unittest 基础概念及用法

测试及测试用例

测试是用 @Test 宏标记的实体,会在测试过程中执行。 仓颉 unittest 框架中有两种测试:测试类和测试函数。 测试函数相对简单,每个函数包含全部测试运行的代码。 测试类适用于为测试引入更深层次的结构,或者覆盖测试生命周期行为的场景。

每个测试类由若干个测试用例组成,每个测试用例用 @TestCase 宏标记。 每个测试用例都是测试类内部的一个函数。 上一节中的示例,相同的测试可以改写为如下所示的测试类:

func add(a:Int64, b:Int64) {
    a + b
}
@Test
class AddTests {
    @TestCase
    func addTest() {
        @Expect(add(2, 3), 5)
    }

    @TestCase
    func addZero() {
        @Expect(add(2, 0), 2)
    }
}

测试函数即函数中包含单个测试用例的测试。这种情况下不需要使用 @TestCase 宏。

cjpm test 中运行这个新的测试类会生成如下类似输出:

--------------------------------------------------------------------------------------------------
TP: example/example, time elapsed: 67369 ns, Result:
    TCS: AddTests, time elapsed: 31828 ns, RESULT:
    [ PASSED ] CASE: addTest (25650 ns)
    [ PASSED ] CASE: addZero (4312 ns)
    Summary: TOTAL: 2
    PASSED: 2, SKIPPED: 0, ERROR: 0
    FAILED: 0
--------------------------------------------------------------------------------------------------
cjpm test success

断言

断言是在测试用例函数体内执行的单个条件检查,用以判断代码是否正常运行。 断言有两种:@Expect@Assert 。 创建一个错误的测试来说明两者的区别:

func add(a:Int64, b:Int64) {
    a + b
}
@Test
func testAddIncorrect() {
    @Expect(add(3, 3), 5)
}

运行测试失败,并生成以下结果(仅展示与此测试相关的部分):

    TCS: TestCase_testAddIncorrect, time elapsed: 4236 ns, RESULT:
    [ FAILED ] CASE: testAddIncorrect (3491 ns)
    Expect Failed: `(add ( 3 , 3 ) == 5)`
       left: 6
      right: 5

在这个例子中,用 @Assert 替换 @Expect 不会有什么变化。添加一个检查项后,再次运行:

func add(a:Int64, b:Int64) {
    a + b
}
@Test
func testAddIncorrect() {
    @Expect(add(3, 3), 5)
    @Expect(add(5, 3), 9)
}

运行测试失败,并生成以下结果(仅展示与此测试相关的部分):

    TCS: TestCase_testAddIncorrect, time elapsed: 5058 ns, RESULT:
    [ FAILED ] CASE: testAddIncorrect (4212 ns)
    Expect Failed: `(add ( 3 , 3 ) == 5)`
       left: 6
      right: 5

    Expect Failed: `(add ( 5 , 3 ) == 9)`
       left: 8
      right: 9

可以在输出中看到这两个检查的结果。 但是,如果用 @Assert 替换 @Expect

func add(a:Int64, b:Int64) {
    a + b
}
@Test
func testAddIncorrectAssert() {
    @Assert(add(3, 3), 5)
    @Assert(add(5, 3), 9)
}

可以得到以下输出:

    TCS: TestCase_testAddIncorrectAssert, time elapsed: 31653 ns, RESULT:
    [ FAILED ] CASE: testAddIncorrectAssert (30893 ns)
    Assert Failed: `(add ( 3 , 3 ) == 5)`
       left: 6
      right: 5

可以看到,只有第一个 @Assert 检查失败了,其余的测试甚至都没有运行。 这是因为 @Assert 宏采用的是快速失败(fail-fast)机制:一旦首次断言失败,整个测试用例都失败,后续的断言不再检查。

在涉及大量断言的大型测试中,这一点非常重要,尤其是在循环中使用断言时。 并不需要等到全部失败,首次失败后用户即可感知。

在测试中选择 @Assert 还是 @Expect 取决于测试场景的复杂程度,以及是否需要采用快速失败机制。

使用 unittest 提供的两种断言宏时,可采用如下方式:

  • 相等断言,其中 @Assert(a, b)@Expect(a, b) 的两个参数 ab ,检查他们的参数值是否相等;假设 a 的类型为 Ab 的类型为 BA 必须实现了 Equatable<B> 。
  • 布尔断言 @Assert(c)@Expect(c) ,其参数 cBool 类型,参数值 truefalse

断言的第二种形式 @Assert(c) 可以视为 @Assert(c, true) 的简写形式。

失败断言

失败断言可以让测试用例运行失败。@Fail 采用快速失败机制,运行至此断言则整个测试用例失败,后续断言都不再检查。@FailExpect 运行至此断言会使得用例失败,但后续断言依然会被检查。 前述宏的参数为描述失败原因的字符串,@Fail 的返回值类型为 Nothing@FailExpect 的类型为 Unit

举例来说:

@Test
func validate_even_number_generator() {
    let even = generateRandomEven()
    if (even % 2 == 1) {
        @Fail("Not even number was generated: ${even}")
    }
}

会输出如下错误信息:

    [ FAILED ] CASE: validate_even_number_generator (54313 ns)
    Assert Failed: `(Not even number was generated: 111)`

预期异常的断言

运行至此断言当预期抛出的异常类型未被抛出时,用例将失败,@AssertThrows 将不再进行后续检查,而 @ExpectThrows 将继续检查。 前述宏的属性入参为预期抛出的异常类型列表,通过 | 隔离不同异常类型,当没有属性入参时预期抛出异常基类 Exception 。入参为预期抛出异常的表达式或代码块。

举例来说:

// No.1
@AssertThrows(throw Exception())
 
// 语义上与 No.1 相同
@AssertThrows[Exception](throw Exception())
 
@AssertThrows[IllegalStateException | NoneValueException](random.seed = 42u64)
 
@ExpectThrows[OutOfMemoryError](foo())
 
@ExpectThrows({
    foo()
    boo()
})
 
@ExpectThrows[OutOfMemoryError]({
    for (i in list) {
        foo(i)
    }
})

@AssertThrows 的返回类型

如果指定的异常不超过一个,则返回类型与预期抛出的异常类型相同:

let e: NoneValueException = @AssertThrows[NoneValueException](foo())

如果指定的异常超过一个,则返回类型为预期抛出的异常类型的最小公共超类型:

// A <: C
// B <: C
let e: C = @AssertThrows[A | B](foo())

@ExpectThrows 的返回类型

@ExpectThrows 检查失败后也会继续执行,在指定的异常不超过一个时,它返回的类型是 Option<T>,其中 T 是预期的异常类型:

let e: ?NoneValueException = @ExpectThrows[NoneValueException](foo())

在指定的异常超过一个时,返回的类型是 ?Exception :

let e: ?Exception = @ExpectThrows[NoneValueException | IllegalMemoryException](foo())

测试生命周期

测试用例之间有时可以共享创建或清理代码。测试框架支持4个生命周期步骤,分别通过相应的宏来设置。只能为 @Test 测试类指定生命周期步骤,不能为 @Test 顶层函数指定生命周期步骤。

生命周期
@BeforeAll在所有测试用例之前运行
@BeforeEach在每个测试用例之前运行一次
@AfterEach在每个测试用例之后运行一次
@AfterAll在所有测试用例完成后运行

这些宏必须配置在 @Test 测试类的成员或静态函数上。@BeforeAll@AfterAll 函数不能声明任何参数。 @BeforeEach@AfterEach 函数可以声明一个 String 类型的参数(或者不声明参数)。

@Test
class FooTest {
    @BeforeAll
    func setup() {
        //在测试执行前运行这段代码。
    }
}

每个宏可以应用于单个测试类内的多个函数。可以在单个函数上配置多个生命周期宏。生命周期宏不能配置在标有 @TestCase 或类似宏的函数上。

如果多个函数被标记为相同的生命周期步骤,则可以按照它们在代码中声明的顺序(从上到下)执行。

测试框架确保:

  1. 标记为 Before all 的步骤在所有测试用例运行之前,至少运行一次。
  2. 对于测试类中的每个测试用例 TC : 1) 标记为 Before each 的步骤在 TC 之前运行一次。 2) 运行 TC 。 3) 标记为 After each 的步骤在 TC 之后运行一次。
  3. 在测试类中的所有测试用例之后运行标记为 After all 的步骤。

注意:

如果没有运行测试用例,上述并不适用。

简单场景中,标识为 before allafter all 的步骤只运行一次。但也有例外:

  • 对于类型参数化测试,标识为 before/after all 的步骤运行的数量为每个类型参数的组合数。
  • 如果多个测试用例在不同的进程中并行执行,则每个进程中标识为 before/after all 的步骤都将运行一次。

@BeforeEach@AfterEach 可以访问正在创建或删除的测试用例,只需要在相应的函数中指定一个 String 类型的参数即可。

@Test
class Foo {
    @BeforeEach
    func prepareData(testCaseName: String) {
        //测试用例函数的名称作为参数
        //本例中的"bar"
    }

    @AfterEach
    func cleanup() {
        //不指定参数也可以
    }

    @TestCase
    func bar() {}
}

参数化测试或参数化性能测试配置生命周期时,注意标识为 before eachafter each 的步骤仅在执行测试用例或基准之前或之后为其所有参数执行一次。也就是说,从生命周期的角度看,使用不同参数执行多次的测试主体会被视为单个测试用例。

如果参数化测试的每个参数都需要单独创建清理,需要将相应的代码配置在测试用例主体本身中。此外,还可以访问参数本身。

测试配置

单元测试框架中其他更高级的功能可能需要额外配置。 参考如下三种方式配置测试:

  • 使用 @Configure
  • 直接在运行测试时或在 cjpm test 测试中使用命令行参数
  • 使用 cjpm 配置文件

运行配置

使用方法

运行 cjc 编译的可执行文件 test ,添加参数选项

./test --bench --filter MyTest.*Test,-stringTest

--bench

默认情况下,只有被 @TestCase 修饰的函数会被执行。在使用 --bench 的情况下只执行 @Bench 宏修饰的用例。

--filter

如果您希望以测试类和测试用例过滤出测试的子集,可以使用 --filter=测试类名.测试用例名 的形式来筛选匹配的用例,例如:

  1. --filter=* 匹配所有测试类
  2. --filter=*.* 匹配所有测试类所有测试用例(结果和*相同)
  3. --filter=*.*Test,*.*case* 匹配所有测试类中以 Test 结尾的用例,或者所有测试类中名字中带有 case 的测试用例
  4. --filter=MyTest*.*Test,*.*case*,-*.*myTest 匹配所有 MyTest 开头测试类中以 Test 结尾的用例,或者名字中带有 case的用例,或者名字中不带有 myTest 的测试用例

另外,--filter 后有 = 和无 = 均支持。

--include-tags

若需按 @Tag 宏中指定的类别选择测试的子集,则可使用 --include-tags--exclude-tags 运行选项。例如:

  1. --include-tags=Unittest 运行所有的带有 @Tag[Unittest] 的测试用例。
  2. --include-tags=Unittest,Smoke 运行所有的带有 @Tag[Unittest]和/或@Tag[Smoke] 的测试用例。
  3. --include-tags=Unittest+Smoke 运行所有的带有 @Tag[Unittest]@Tag[Smoke] 的测试用例。
  4. --include-tags=Unittest+Smoke+JiraTask3271,Backend 运行所有的带有 @Tag[Backend]和/或@Tag[Unittest, Smoke, JiraTask3271] 的测试用例。

** 注意 ** 如果没有符合指定标签类别的测试用例。框架将不运行任何内容。 可以与 exclude-tags 结合。详见 --exclude-tags

--exclude-tags

若需按 @Tag 宏中指定的类别选择测试的子集,则可使用 --include-tags--exclude-tags 运行选项。例如:

  1. --exclude-tags=Unittest 运行所有的带有 @Tag[Unittest] 的测试用例。
  2. --exclude-tags=Unittest,Smoke 运行所有的带有 @Tag[Unittest]和/或@Tag[Smoke] 的测试用例。
  3. --exclude-tags=Unittest+Smoke 运行所有的同时带有 @Tag[Unittest]@Tag[Smoke] 的测试用例。
  4. --include-tags=Unittest --exclude-tags=Smoke 运行所有带有 @Tag[Unittest] 但不带有 @Tag[Smoke] 的测试用例。

** 注意 ** exclude-tags 的优先级高于 include-tags,如果用例被排除,则必定不会被执行,例如 --include-tags=Unittest+Smoke --exclude-tags=Smoke 则带有 @Tag[Smoke] 的用例不会被执行。

--timeout-each=timeout

使用 --timeout-each=timeout 选项等同于对所有的测试类使用 @Timeout[timeout] 修饰。若代码中已有 @Timeout[timeout] ,则将被代码中的超时时间覆盖,即选项的超时时间配置优先级低于代码中超时时间配置。

timeout 的值应符合以下语法: number ('millis' | 's' | 'm' | 'h') 例如: 10s, 9millis 等。

  • millis : 毫秒
  • s : 秒
  • m : 分钟
  • h : 小时

--parallel

打开 --parallel 选项将使测试框架在单独的多个进程中并行执行不同的测试类。 测试类之间应该是相互独立的,不依赖于共享的可变的状态值。 程序静态初始化可能会发生多次。 不允许与 --bench 同时使用。由于性能用例对底层资源敏感,用例是否并行执行,将影响性能用例的结果,因此禁止与 --bench 同时使用。

  • --parallel=<BOOL> <BOOL> 可为 truefalse ,指定为 true 时,测试类可被并行运行,并行进程个数将受运行系统上的CPU核数控制。另外,--parallel 可省略 =true
  • --parallel=nCores 指定了并行的测试进程个数应该等于可用的 CPU 核数。
  • --parallel=NUMBER 指定了并行的测试进程个数值。该数值应该为正整数。
  • --parallel=NUMBERnCores 指定了并行的测试进程个数值为可用的 CPU 核数的指定数值倍。该数值应该为正数(支持浮点数或整数)。

--option=value

--option=value 形式提供的任何非上述的选项均按以下规则处理并转换为配置参数(类似于 @Configure 宏处理的参数),并按顺序应用:

optionvalue 为任意自定义的运行配置选项键值对,option 可以为任意通过 - 连接的英文字符,转换到 @Configure 时将转换为小驼峰格式。value 的格式规则如下:

注:当前未检查 optionvalue 的合法性,并且选项的优先级低于代码中 @Configure 的优先级。

  • 如果省略 =value 部分,则该选项被视为 Booltrue , 例如:--no-color 生成配置条目 noColor = true
  • 如果 value 严格为 truefalse ,则该选项被视为具有相应含义的 Bool值:--no-color=false 生成配置条目 noColor = false
  • 如果 value 是有效的十进制整数,则该选项被视为 Int64 值 , 例如:--random-seed=42 生成配置条目 randomSeed = 42
  • 如果 value 是有效的十进制小数,则该选项被视为 Float64 值 , 例如:--angle=42.0 生成配置条目 angle = 42
  • 如果 value 是带引号的字符串文字(被 " 符号包围),则该选项将被视为 String 类型,并且该值是通过解码 " 符号之间的字符串值来生成的,并处理转义符号,例如 \n\t\" 作为对应的字符值。例如,选项 --mode="ABC \"2\"" 生成配置条目 mode = "ABC \"2\""
  • 除上述情况外 value 值将被视为 String 类型,该值从所提供的选项中逐字获取。例如, --mode=ABC23[1,2,3] 生成配置条目 mode = "ABC23[1,2,3]"

--report-path=path

该选项用于指定执行后生成测试报告的目录路径。默认情况下,如果不明确指定选项,将不会生成报告。

--report-format=value

该选项用于指定测试执行后生成的报告的格式。

目前,单元测试仅支持默认的 xml 格式。

基准测试支持:

  • csv:csv 报告中有统计数据。
  • csv-raw: csv-raw 报告中只有批次的原始测量值。

基准测试的默认使用的格式为:

  • csv

--capture-output

此选项使能测试用例的打印输出捕获。 默认情况下,在 cjpm test 执行时使能捕获,否则禁用捕获。 当测试用例打印输出捕获未使能时,打印输出将立即传播到单元测试输出。否则,单元测试将收集和处理测试用例的打印输出。

需要捕获打印输出的场景如下:

  • 使用 --parallel 执行时防止测试输出交错。
  • 隐藏已通过测试的输出以使单元测试报告更加清晰。
  • 将每个测试用例的输出分开,以查看哪个测试用例打印了什么。

--no-capture-output

此选项禁用测试用例打印输出捕获。 默认情况下,在 cjpm test 执行中启用捕获,否则禁用捕获。

使测试用例打印输出立即传播到单元测试输出。

--show-all-output

单元测试框架将打印报告中的所有输出,包括通过的测试用例的输出。 如果禁用测试输出捕获,则此选项失效。

--coverage-guided

单元测试框架将使能覆盖率引导的随机参数化测试

--baseline-path=path

此选项指定用于比较的性能报告所在的路径。默认情况下,使用 '--report-path' 的值。

参数化测试

参数化测试入门

仓颉 unittest 框架支持参数化测试,格式为数据 DSL ,测试中框架自动插入输入参数。

如下为复杂代码示例,用函数对数组排序:

package example

func sort(array: Array<Int64>): Unit {
    for (i in 0..array.size) {
        var minIndex = i
        for (j in i..array.size) {
            if (array[j] < array[minIndex]) {
                minIndex = j
            }
        }
        (array[i], array[minIndex]) = (array[minIndex], array[i])
    }
}

这个函数不是最优最高效的排序实现,但仍可以达成目的。 来测试一下。

package example

@Test
func testSort() {
    let arr = [45, 5, -1, 0, 1, 2]
    sort(arr)
    @Expect(arr, [-1, 0, 1, 2, 5, 45])
}

测试结果显示,函数在单个输入的情况下可用。 接下来测试,如果数组只包含等值元素,排序函数还是否可用。

@Test
func testAllEqual() {
    let arr = [0, 0, 0, 0]
    let expected = [0, 0, 0, 0]
    sort(arr)
    @Expect(expected, arr)
}

测试结果显示函数可用,但还是不能确认是否适用于所有大小的数组。 接下来测试参数化数组的大小。

@Test[size in [0, 1, 50, 100, 1000]]
func testAllEqual(size: Int64) {
    let arr = Array(size, repeat: 0)
    let expected = Array(size, repeat: 0)
    sort(arr)
    @Expect(expected, arr)
}

至此,参数化测试已完成。 这种是最简单的参数化测试,即值驱动测试,直接在代码中列出测试运行的值。 参数化测试的参数可以不止一个。 不仅可以指定排序函数的大小,还可以指定待测试的元素。

@Test[
    size in [0, 1, 50, 100, 1000],
    item in (-1..20)
]
func testAllEqual(size: Int64, item: Int64) {
    let arr = Array(size, repeat: item)
    let expected = Array(size, repeat: item)
    sort(arr)
    @Expect(expected, arr)
}

注意,item 的取值范围为 -1..20 ,不是一个数组。 那么,运行这个测试,结果会如何? 参数 sizeitem 的取值会进行组合再测试和返回结果。 因此,测试函数时,不要配置过多参数;否则组合数量过大,导致测试变慢。 上述例子中,size 参数值有5个,item 参数值有21个,共有21×5=105种组合。

注意,值驱动测试不限于整型或内置类型。 也可以和任何仓颉类型一起使用。 参考如下测试:

@Test[
    array in [
        [],
        [1, 2, 3],
        [1, 2, 3, 4, 5],
        [5, 4, 3, 2, 1],
        [-1, 0],
        [-20]
    ]
]
func testDifferentArrays(array: Array<Int64>) {
    //测试数组是否已排序
    for (i in 0..(array.size - 1)) {
        @Expect(array[i] <= array[i + 1])
    }
}

这里,直接以参数的形式提供测试的数据。

当然,用数组来测试代码可能过于笨重。 有时,对于这样的泛型函数,随机生成数据可能会更容易些。 接下来看一种更高级的参数化测试:随机测试。 通过调用函数 unittest.random<T>() 替换值驱动测试的数组或范围来创建随机测试:

@Test[
    array in random()
]
func testRandomArrays(array: Array<Int64>) {
    //测试数组是否已排序
    for (i in 0..(array.size - 1)) {
        @Expect(array[i] <= array[i + 1])
    }
}

这个测试本质上是生成大量完全随机的数值(默认为200个),用这些值来测试代码。 数值并不完全随机,偏向于边界值,如特定类型的零、最大值和最小值、空集合等。

特别注明:通常建议随机化测试与手工编写的测试混用,实践表明可以互为补充。

为了更好地描述随机测试,先把排序函数放一边,编写下面这样一个测试:

@Test[
    array in random()
]
func testNonsense(array: Array<Int64>) {
    if (array.size < 2) { return }
    @Expect(array[0] <= array[1] + 500)
}

运行后,会生成如下类似输出:

[ FAILED ] CASE: testNonsense (1159229 ns)
    REASON: After 4 generation steps and 200 reduction steps:
        array = [0, -453923686263, 0]
    with randomSeed = 1702373121372171563

    Expect Failed: `(array [ 0 ] <= array [ 1 ] + 500 == true)`
       left: false
      right: true

结果可见,数组[0, -453923686263, 0]测试失败。 再运行一次:

[ FAILED ] CASE: testNonsense (1904718 ns)
    REASON: After 5 generation steps and 200 reduction steps:
        array = [0, -1196768422]
    with randomSeed = 1702373320782980551

    Expect Failed: `(array [ 0 ] <= array [ 1 ] + 500 == true)`
       left: false
      right: true

同样,测试失败,但值都不同。 为什么会这样呢? 因为随机测试本质上是随机的,所以每次都会生成新的随机值。 在各种不同的数据上测试函数,可能很好用;但是对于某些测试,这意味着多次运行中,有时成功,有时失败,不利于共享测试结果。 随机测试是一个强大的工具,但在使用时也需要了解这些弊端。

测试结果每次都不一样,如何向其他开发者展示结果呢? 答案很简单,就在运行测试时得到的输出中:

with randomSeed = 1702373320782980551

以上提供了一个随机种子,可以在测试中用作配置项。 改写测试如下:

@Test[
    array in random()
]
@Configure[randomSeed: 1702373320782980551]
func testNonsense(array: Array<Int64>) {
    if (array.size < 2) { return }
    @Expect(array[0] <= array[1] + 500)
}

运行结果如下:

[ FAILED ] CASE: testNonsense (1910109 ns)
    REASON: After 5 generation steps and 200 reduction steps:
        array = [0, -1196768422]
    with randomSeed = 1702373320782980551

    Expect Failed: `(array [ 0 ] <= array [ 1 ] + 500 == true)`
       left: false
      right: true

注意,此次运行生成的值、生成值所用的步骤和随机种子与上次运行完全相同。 这种机制让随机测试可重复,可以保存在测试套件中与其他开发人员共享。 您也可以只从随机测试中获取数据(如本例中的数组值[0, -1196768422]),用这些值编写新测试。

快速看看失败的测试生成的输出。

    REASON: After 5 generation steps and 200 reduction steps:
        array = [0, -1196768422]
    with randomSeed = 1702373320782980551

输出中包含几个重要信息:

  • 测试失败前数据生成的步骤数:即测试失败前运行的迭代次数。
  • 数据减量的步骤数:随机测试有缩减测试数据的机制,数据量减小后更方便操作,且提升了可读性。
  • 导致测试失败的实际数据:按顺序列出所有参数(在本例中,只有一个参数 array )以及它们实际导致测试失败的值。其中参数应实现 ToString 接口,否则将只打印占位符。
  • 以及前面提到的随机种子,用于重现随机测试。

有些测试比较棘手,需要调整随机生成的步骤数。 可以通过如下两个配置项控制:generationStepsreductionSteps 。 随机测试一个最大的优点是,只要设置了足够多的步骤,它可以运行很长时间,这样就可以检查数百万个值。

为了不使测试太耗时,默认 generationStepsreductionSteps 的最大值都是200。 通过这两个配置参数,就可以设置框架的最大步骤数。 例如,对于上面的这个小测试,参数设置为一个大的数值可能没有多大意义。之前的运行已经表明,通常不到10步,测试就会失败。

类型参数化测试

虽然当前排序实现仅针对整型数组排序,但本质上也可以对其他任何类型排序。 可以改写 sort 函数变成泛型函数,允许它对任意类型进行排序。 注意,元素必须是可比较的,这样才能排序。

package example

func sort<T>(array: Array<T>): Unit where T <: Comparable<T> {
    for (i in 0..array.size) {
        var minIndex = i
        for (j in i..array.size) {
            if (array[j] < array[minIndex]) {
                minIndex = j
            }
        }
        (array[i], array[minIndex]) = (array[minIndex], array[i])
    }
}

所有测试均继续正常运行,可知排序函数已广泛适用。 但是,是否真的适用于整型以外的类型呢?

用示例中的 testDifferentArrays 编写一个新的测试,对其他类型(如字符串)进行测试:

@Test[
    array in [
        [],
        ["1","2","3"],
        ["1","2","3","4","5"],
        ["5","4","3","2","1"]
    ]
]
func testDifferentArraysString(array: Array<String>) {
    //测试数组是否已排序
    let sorted = array.clone()
    sort(sorted)
    for (i in 0..(sorted.size - 1)) {
        @Expect(sorted[i] <= sorted[i + 1])
    }
}

运行测试可知,测试正常。 注意,两个测试的主体和断言完全相同。 试想,如果泛型函数的测试也可以泛型,不是更方便吗?

回到之前的随机测试示例:

@Test[array in random()]
func testRandomArrays(array: Array<Int64>) {
    let sorted = array.clone()
    sort(sorted)
    for (i in 0..(sorted.size - 1)) {
        @Expect(sorted[i] <= sorted[i + 1])
    }
}

测试是广泛适用的,可以看到元素类型不限于 Int64 ,也可以是任何类型 T ,例如:

  • 可以比较:需要实现 Comparable<T> ;
  • 可以随机生成实例:需要实现 Arbitrary<T> ;

将这个测试改写为一个泛型函数:

@Test[array in random()]
func testRandomArrays<T>(array: Array<T>) where T <: Comparable<T> & Arbitrary<T> {
    let sorted = array.clone()
    sort(sorted)
    for (i in 0..(sorted.size - 1)) {
        @Expect(sorted[i] <= sorted[i + 1])
    }
}

编译运行后,遇到了一个问题:

An exception has occurred:
MacroException: Generic function testRandomArrays requires a @Types macro to set up generic arguments

当然,要运行测试某些类型,需要先有这些类型。 用 @Types 宏设置测试,这样就可以运行测试 Int64Float64String 这些类型了。

@Test[array in random()]
@Types[T in <Int64, Float64, String>]
func testRandomArrays<T>(array: Array<T>) where T <: Comparable<T> & Arbitrary<T> {
    let sorted = array.clone()
    sort(sorted)
    for (i in 0..(sorted.size - 1)) {
        @Expect(sorted[i] <= sorted[i + 1])
    }
}

现在,运行测试,将编译并生成以下输出:

    TCS: TestCase_testRandomArrays, time elapsed: 2491737752 ns, RESULT:
    [ PASSED ] CASE: testRandomArrays<Int64> (208846446 ns)
    [ PASSED ] CASE: testRandomArrays<Float64> (172845910 ns)
    [ PASSED ] CASE: testRandomArrays<String> (2110037787 ns)

注意,每个类型,测试都是单独运行的,因为行为可能大不相同。 @Types 宏可以用于任何参数化的测试用例,包括测试函数和测试类。

重用、组合和映射参数策略

现在以 HashSet 为例。从测试 contains 开始。

@Test[data in random()]
func testHashSetContains(data: Array<Int64>) {
    let hashSet = HashSet(len)
    hashSet.putAll(data)
 
    for (element in data){
        @Assert(hashSet.contains(element))
    }
}

效果很好。现在尝试测试 remove

@Test[data in random()]
func testHashSetRemove(data: Array<Int64>) {
    let hashSet = HashSet(len)
    hashSet.putAll(data)
 
    for (element in data){
        @Assert(hashSet.remove(element))
    }
}

表面上看应该可以正常工作。然而很快就可以注意到它无法正常工作,因为随机生成的数组可能包含重复项,这会导致第二次删除调用失败。所以这里想要的是生成一些没有重复的数组。

var counter = 0
@OverflowWrapping
func generateUniqArray(len: Int64, start: Int64){
    let rng = Random(start)
    let step = Int64.Max / len
    counter = 0
    Array(len, { _ => 
        counter += rng.nextInt64()%step 
        counter
    } )
}

@Test[len in random(), start in random()]
func testHashSetRemove(len: Int64, start: Int64) {
    let data = generateUniqArray(len,start)
    let hashSet = HashSet(len)
    hashSet.putAll(data)
 
    for (element in data){
        @Assert(hashSet.remove(element))
    }
}

然而,即使将数据生成转移到一个单独的函数中,如果想在多个不同的测试之间重用它,它仍然会有相当多的重复。此外,在准备代码和测试代码之间的界限非常不明确。因此,为了解决上述问题,测试框架以 @Strategy 宏的形式提供了方便的 API,允许组合和映射现有策略。

var counter = 0
@Strategy[len in random(), start in random()]
@OverflowWrapping
func generateUniqArray(len: Int64, start: Int64): Array<Int64>{
    let rng = Random(start)
    let step = Int64.Max / len
    counter = 0
    Array(len, { _ => 
        counter += rng.nextInt64()%step 
        counter
    } )
}

现在,只需要这样的输入,就可以使用该策略:

@Test[data in generateUniqArray]
func testHashSetRemove(data: Array<Int64>) {
    let hashSet = HashSet()
    hashSet.putAll(data)
 
    for (element in data){
        @Assert(hashSet.remove(element))
    }
}
 
@Test[data in generateUniqArray]
func testHashSetToArray(data: Array<Int64>) {
    let hashSet = HashSet()
    hashSet.putAll(data)
 
    let result = hashSet.toArray()
    result.sort()
    data.sort()
    @Assert(result == data)
}

覆盖率引导的随机参数化测试

如上所述,随机测试对于有能力的人来说是一个强大的工具,但它们也有一些局限性。 例如:

@Test[x in random()]
func testX(x: Int64) {
    @Expect(x != 1234567)
}

虽然这样的测试看起来很简单,但如果运行它,可能不会得到预期的结果:

--------------------------------------------------------------------------------------------------
TP: default, time elapsed: 1393856 ns, RESULT:
    TCS: TestCase_testX, time elapsed: 1393856 ns, RESULT:
    [ PASSED ] CASE: testX (1378439 ns)
Summary: TOTAL: 1
    PASSED: 1, SKIPPED: 0, ERROR: 0
    FAILED: 0
--------------------------------------------------------------------------------------------------

而且即使你将生成步骤的数量增加到几百万,这个测试也可能不会失败,因为随机测试是随机的,生成精确的非常规数字的概率极低。 虽然此测试看起来是自动生成的,并且不能真正代表生产代码,但它显示了随机代码在更现实的场景中可能面临的相同问题,从而大大减少了其在更高级用途中的应用,例如查找代码中的安全缺陷。

为解决这个问题,仓颉单元测试框架引入了一项基于 security-fuzzing 测试技术的高级特性:覆盖率引导的随机参数化单元测试。该特性针对的是那些希望对其代码进行更细致的测试,同时仍然享受随机测试的可用性和易用性的用户。

使用覆盖率引导的单元测试,需要执行以下步骤:

  • 该项目必须在编译器支持 SanitizerCoverage 的情况下进行编译。具体需要以下两个选项:--sanitizer-coverage-trace-pc-guard--sanitizer-coverage-trace-compares
  • 用例可执行文件必须配置 --coverage-guided 选项。
  • 测试的生成步骤参数必须根据代码的复杂性增加,以允许覆盖引导算法继续进行。

如果我们使用编译器选项 --sanitizer-coverage-trace-pc-guard--sanitizer-coverage-trace-compares 编译上面的示例,然后使用 --coverage-guided 选项运行它,我们得到类似于以下内容的结果:

--------------------------------------------------------------------------------------------------
TP: default, time elapsed: 2004749 ns, RESULT:
    TCS: TestCase_testX, time elapsed: 2004749 ns, RESULT:
    [ FAILED ] CASE: testX (17380 ns)
    REASON: After 48 generation steps and 3 reduction steps:
        x = 1234567
    with randomSeed = 1721033700363557083
    Expect Failed: `(x != 1234567 == true)`
       left: false
      right: true

Summary: TOTAL: 1
    PASSED: 0, SKIPPED: 0, ERROR: 0
    FAILED: 1, listed below:
            TCS: TestCase_testX, CASE: testX
--------------------------------------------------------------------------------------------------

正如我们所看到的,测试在极少数生成步骤中失败(本例中为 48 个,但是,由于总是随机测试,结果可能会有所不同),但一般来说,建议至少将测试的生成步骤配置为数十万步。因此用例的执行时间可能会很长。

动态测试

动态测试入门

仓颉测试框架支持动态测试,其支持在存在编译期未知的测试数据时构造测试用例。关键场景如下:

  • 创建基于外部数据的测试套。
  • 创建基于参数或配置文件的测试套。

通过与普通测试用例对比,可以看到如何通过 @TestBuilder 来构造动态测试用例。

如下是一个通过 @Test/@TestCase 构造的简单测试套:

@Test
class A {
    @TestCase
    func f() { @Assert(false) }

    @TestCase[x in [1, 2]]
    func g(x: Int) {
        @Assert( x >= 1 )
    }
}

通过 @TestBuilder 可以创建跟上述测试套相同逻辑的动态测试套 :

@TestBuilder
public func buildCustomTestSuite(): TestSuite {
   let suiteBuilder = TestSuite.builder("A")
   let caseConfiguration = Configuration()
   suiteBuilder.add(
       UnitTestCase.create("f", configuration: caseConfiguration) { @Assert(false) })
   suiteBuilder.add(
       UnitTestCase.createParameterized("g", [1, 2]) { value => @Assert( value >= 1 ) })
   suiteBuilder.build()
}

TestSuite 创建了一个 TestSuiteBuilder 对象,该对象支持添加用例。用例通过 UnitTestCase 类中的静态函数构造。该类支持构造简单用例或者参数化用例。 TestSuiteBuilder 被配置完毕后,最终创建生成一个 TestSuite 对象,作为被 @TestBuilder 修饰的函数的返回值。

当上述代码通过 --test 编译后再执行,输出结果与 @Test/@TestCase 构造的测试套一致。

--------------------------------------------------------------------------------------------------
TP: default, time elapsed: 121592 ns, RESULT:
    TCS: A, time elapsed: 121592 ns, RESULT:
    [ PASSED ] CASE: g (13969 ns)
    [ FAILED ] CASE: f (91641 ns)
    Assert Failed: `(false == true)`
       left: false
      right: true

Summary: TOTAL: 2
    PASSED: 1, SKIPPED: 0, ERROR: 0
    FAILED: 1, listed below:
            TCS: A, CASE: f
--------------------------------------------------------------------------------------------------

@TestBuilder 有如下约束:

  • 它只能修饰顶层函数,且该函数不能是 foreign 函数。
  • 它的返回值类型必须被显式指定,且必须为 TestSuite 类型。
  • 它可以与 @Configure / @Timeout / @Parallel 宏组合使用,不允许与 unittest.testmacro 包中其他的宏组合。

运行动态测试并获取输出

如果需要不从单元测试框架运行测试用例,而是从程序内部运行测试,则可以借助 TestSuite runTests() 函数来实现。

例如:

import std.unittest.*

main() {
   let suiteBuilder = TestSuite.builder("A")
   let caseConfiguration = Configuration()
   suiteBuilder.add(
       UnitTestCase.create("f", configuration: caseConfiguration) { @Assert(false) })
   suiteBuilder.add(
       UnitTestCase.createParameterized("g", [1, 2]) { value => @Assert( value >= 1 ) })
   let suite = suiteBuilder.build()
   let report = suite.runTests()
}

runTests 函数返回 Report 类的实例。您可以使用 Report 对象执行以下操作:

  • 使用 ConsoleReporter 类将其打印到控制台: report.reportTo(ConsoleReporter(colored: true))
  • 使用 TextReporter 类打印到任何 PrettyPrinter 实现: report.reportTo(TextReporter(into: PrettyText()))
  • 将结果输出为支持的格式之一,例如 XML( XmlReporter ,仅用于单元测试,不用于性能测试)或 CSV( CsvReporterCsvRawReporter ,仅用于性能测试)。

std.unittest.mock 包

功能介绍

unittest.mock 包提供仓颉单元测试的mock 框架,提供 API 用于创建和配置mock 对象,这些 mock 对象与真实对象拥有签名一致的 API 。mock 测试技术支持隔离测试代码,测试用例使用 mock 对象编码,实现外部依赖消除。

mock 框架具有以下特性:

  • 创建 mock 对象和 spy 对象:测试时无需修改生产代码。
  • 简单的配置 API :可配置 mock/spy 对象的行为。
  • 单元测试框架部分:无缝集成单元测试框架的其他特性,错误输出可读。
  • 自动验证配置行为:大多数情况下不需要多余的验证代码。
  • 提供验证 API:用于测试系统内部的复杂交互。

用户使用场景包括:

  • 简化测试设置和代码。
  • 测试异常场景。
  • 用轻量级 mock 对象替换代价高的依赖,提高测试性能。
  • 验证测试复杂场景,如调用的顺序/数量。

用户可通过快速入门写出第一个带 mock 的测试程序。同时文档对于一些基础概念及用法做了说明并附有示例代码,另外,针对配置 API ()的高阶用法做了进一步说明。

API 列表

函数

函数名功能
mock<T>()创建类型 T 的 mock object, 这个对象默认情况下,所有的成员函数、属性或运算符重载函数没有任何具体实现。
mock<T>(Array<StubMode>)创建类型 T 的 mock object , 参数指定了桩的模式
spy<T>(T)创建类型 T 的 spy object ( mock object 的扩展,对象的成员拥有默认实现的“骨架”对象)。 这个对象包装了所传入的对象,并且默认情况下成员函数、属性或运算符重载函数实现为对这个传入的实例对象的对应成员函数、属性或运算符重载函数的调用。

接口

接口名功能
ValueListener<T>此接口提供了多个成员函数以支持“监听”传入给桩签名的参数。

类名功能
ActionSelector此抽象类提供了为成员函数指定一个操作 API ,并允许链式调用的方法。
AnyMatcher任意参数匹配器,即桩签名允许任意的参数。
ArgumentMatcher参数匹配器抽象类,该类与其子类可作为桩签名的入参类型。
CardinalitySelector此接口提供了可定义桩签名的最近一次行为的执行次数的 API 。
ConfigureMock配置 mock object
Continuation此类提供了可继续定义桩签名的行为的 API 。
GetterActionSelector此类提供了为属性 Getter 函数指定一个操作 API ,并允许链式调用的方法。
Matchers该类提供生成匹配器的静态函数。匹配器对象仅可通过此处的静态函数生成。匹配器可在桩链中使用。
MethodActionSelector此类提供了为成员函数指定一个操作 API ,并允许链式调用。
MockFramework提供用例执行所需的框架准备与结束回收阶段的函数。
NoneMatcher参数值为 None 的匹配器。
OrderedVerifier此类型用于收集 “验证语句”, 可在 ordered 函数中动态传入验证行为。
SetterActionSelector此类提供了为属性 Setter 函数指定一个操作 API ,并允许链式调用的方法。
SyntheticField合成字段。
TypedMatcher参数类型匹配器。
UnorderedVerifier此类型用于收集 “验证语句”, 可在 unordered 函数中动态传入验证行为。
VerifyVerify 提供了一系列静态方法来支持定义所需验证的动作,如 thatordered 以及 unorder
VerifyStatement此类型表示对“桩签名”在验证范围内的单个验证验证语句(即上文中的“验证语句”),提供了成员函数指定“桩签名”的执行次数。

枚举

枚举名功能
Exhaustiveness此枚举类型用于指定 unordered 函数的验证模式,包含两种模式。
MockSessionKind控制允许在 MockSession 使用的的类型。
StubMode控制桩的模式

函数

func mock<T>()

public func mock<T>(): T

功能:创建类型 T 的 mock object, 这个对象默认情况下,所有的成员函数、属性或运算符重载函数没有任何具体实现。 可以通过 @On 指定这个对象的成员函数、属性或运算符重载函数的行为。

返回值:

  • T - 类型 T 的 mock object

func mock<T>(Array<StubMode>)

public func mock<T>(modes: Array<StubMode>): T

功能:创建类型 T 的 mock object , 参数指定了桩的模式

参数:

  • modes: Array<StubMode> - 指定桩的模式,可以为多个。

返回值:

  • T - 类型 T 的 mock object

func spy<T>(T)

public func spy<T>(objectToSpyOn: T): T

功能:创建类型 T 的 spy objectmock object 的扩展,对象的成员拥有默认实现的“骨架”对象)。 这个对象包装了所传入的对象,并且默认情况下成员函数、属性或运算符重载函数实现为对这个传入的实例对象的对应成员函数、属性或运算符重载函数的调用。 可以通过 @On 重载这个对象的成员函数、属性或运算符重载函数的行为。

参数:

  • objectToSpyOn: T - 传入实例对象,默认情况下,使用该对象的实现。

返回值:

  • T - 类型 T 的 spy object

接口

interface ValueListener<T>

public interface ValueListener<T> {
    func lastValue(): Option<T>
    func allValues(): Array<T>
    func addCallback(callback: (T) -> Unit): Unit
    static func new(): ValueListener<T>
    static func onEach(callback: (T) -> Unit): ValueListener<T>
}

功能:此接口提供了多个成员函数以支持“监听”传入给桩签名的参数。 即对每次调用中传入桩签名的参数进行指定的操作( addCallback()onEach 中的闭包函数即为对参数进行的操作内容)。 一般与参数匹配器生成函数 argThat 或者 capture 配合使用。 值侦听器与参数捕获器一同作为参数匹配器的一种被传入到桩签名中,作为入参。在定义桩签名的参数值范围的同时检查参数值。

举例来说:

struct Animal {
    Animal(
        let name: String,
        let info: String
    ) {}
}

abstract class AnimalUi {
    func showAnimal(animal: Animal): Unit
}

let animals = [Animal("Smokey", "Cat, age: 5"), Animal("Daisy", "Dog, age: 9")]

@Test func testAnimal(): Unit {
    let ui = mock<AnimalUi>()
    // 定义了一个值监听器:检查每个值,当值不满足条件时抛出异常。
    let listener = ValueListener<Animal>.onEach { animal =>
        if (animal.name == "Smokey") {
            @Assert(animal.info.contains("Cat"))
        }
    }
    // 定义一个桩签名的“桩行为”,参数匹配器为可执行上述值监听器的参数捕获器。
    @On(ui.showAnimal(capture(listener))).returns(())

    for (animal in animals) {
        // 此处将捕获传入的 animal 对象,并对其执行值监听器中的检查行为。
        ui.showAnimal(animal)
    }
}

func addCallback((T) -> Unit)

func addCallback(callback: (T) -> Unit): Unit

功能:为当前“值监听器”对象增加闭包函数,该函数将处理传入的参数值。

参数:

  • callback: (T) ->Unit - 处理参数值的闭包函数

func allValues()

func allValues(): Array<T>

功能:返回当前“值监听器”对象已所处理的所有值。

返回值:

  • Array<T> - 返回“值监听器”对象所处理的所有值列表

func lastValue()

func lastValue(): Option<T>

功能:返回当前“值监听器”对象所处理的最后一个值。

返回值:

  • Option<T> - 返回“值监听器”对象所处理的最后一个值,不存在时,返回 None 。

func new()

static func new(): ValueListener<T>

功能:创建一个新的“值监听器”对象,不包含任何处理参数的闭包方法。

返回值:

func onEach((T) -> Unit)

static func onEach(callback: (T) -> Unit): ValueListener<T>

功能:创建一个新的“值监听器”对象,带有一个处理参数的闭包方法。

参数:

  • callback: (T) ->Unit - 处理参数值的闭包函数。

返回值:

class ActionSelector

public sealed abstract class ActionSelector {}

功能:此抽象类提供了为成员函数指定一个操作 API ,并允许链式调用的方法。 入参为 mock objectspy object 的某个成员函数的调用表达式的 @On 宏调用表达式,将返回 ActionSelector 的实例。即,此类或其子类中的 API 可为成员函数插入桩代码。

func fails()

func fails(): Unit

功能:定义调用桩签名将导致测试失败,执行至桩签名即抛出 AssertionException 异常的行为。

class AnyMatcher

public class AnyMatcher <: ArgumentMatcher {}

功能:任意参数匹配器,即桩签名允许任意的参数。

父类型:

func matchesAny(Any)

public func matchesAny(_: Any)

功能:匹配任意类型的任意值。

参数:

  • _: Any - 被检查的输入参数。任意类型的任意值。

返回值:

  • Bool - 固定为 true

extend AnyMatcher

extend AnyMatcher {}

功能:扩展 AnyMatcher

func value<T>()

public func value<T>(): T

功能:框架需要调用的参数匹配器的返回值。

返回值:

  • T - 与实际入参类型匹配的值。

class ArgumentMatcher

public abstract class ArgumentMatcher {}

功能:参数匹配器抽象类,该类与其子类可作为桩签名的入参类型。

func withDescription(String)

public func withDescription(description: String): ArgumentMatcher

功能:配置参数匹配器抛出异常时的描述信息。

参数:

  • description: String - 描述信息。

返回值:

  • ArgumentMatcher - 被配置的参数匹配器。

func forParameter(String)

public func forParameter(name: String): ArgumentMatcher

功能:配置所匹配的参数名称。

参数:

  • name: String - 所匹配的参数名称。

返回值:

  • ArgumentMatcher - 被配置的参数匹配器。

func matchesAny(Any)

public func matchesAny(arg: Any)

功能:匹配任意类型的任意值。

参数:

  • arg: Any - 被检查的输入参数。任意类型的任意值。

返回值:

  • Bool - 匹配结果 。

class CardinalitySelector

public class CardinalitySelector<A> where A <: ActionSelector {}

功能:此类提供了可定义桩签名的最近一次行为的执行次数的 API 。 例如:@On(foo.bar()).returns("Predefined value").atLeastOnce() 。 为方便表达,后文将桩签名的最近一次行为称为“桩行为”。 此接口提供的 API 提供的验证能力如下:

func anyTimes()

func anyTimes(): Unit

功能:定义“桩行为”可以执行任意次数。此函数对桩签名的调用次数不做任何校验。

func atLeastOnce()

func atLeastOnce(): Unit

功能:定义“桩行为”最少被执行一次。验证不到一次时,抛出异常。

异常:

func atLeastTimes(Int64)

func atLeastTimes(minTimesExpected: Int64): Unit

功能:定义“桩行为”最少被执行指定次数的行为。验证实际执行次数低于最少指定次数时,抛出异常。

参数:

  • minTimesExpected: Int64 - 预期“桩行为”最少被执行的次数。

异常:

func once()

func once(): Continuation<R>

功能:定义“桩行为”仅被执行一次。此函数将在验证桩签名执行次数超出一次时,抛出异常。

返回值:

异常:

func times(Int64)

func times(expectedTimes: Int64): Continuation<R>

功能:定义“桩行为”被执行指定次数。验证不是指定次数时,抛出异常。

参数:

  • expectedTimes: Int64 - 预期“桩行为”被执行的次数。

返回值:

异常:

func times(Int64, Int64)

func times(min!: Int64, max!: Int64): Unit

功能:定义“桩行为”执行指定次数范围。验证超出指定次数范围时,抛出异常。

参数:

  • min!: Int64 - 预期“桩行为”被执行的最小次数。
  • max!: Int64 - 预期“桩行为”被执行的最大次数。

异常:

class ConfigureMock

public class ConfigureMock {}

功能:配置 mock object

static func stubGetter<TObj, TRet>(() -> TRet,TObj,String,String,String,Int64)

public static func stubGetter<TObj, TRet>(
    stubCall: () -> TRet,
    objectReference: TObj,
    objectName: String,
    fieldOrPropertyName: String,
    callDescription: String,
    lineNumber: Int64
): GetterActionSelector<TRet> 

功能:创建针对属性的 Getter 方法插入桩代码的操作器对象。

参数:

  • stubCall: () -> TRet - 桩签名对应的调用表达式。
  • objectReference: TObj - 被插桩的对象的引用。
  • objectName: String - 被插桩的对象的名称。
  • fieldOrPropertyName: String - 被插桩的字段或属性名称。
  • callDescription: String - 桩签名对应的调用表达式的字符串表达。
  • lineNumber: Int64 - 对应的调用表达式的行号。

返回值:

static func stubMethod<TObj, TRet>(() -> TRet,Array<ArgumentMatcher>,TObj,String,String,String,Int64)

public static func stubMethod<TObj, TRet>(
    stubCall: () -> TRet,
    matchers: Array<ArgumentMatcher>,
    objectReference: TObj,
    objectName: String,
    methodName: String,
    callDescription: String,
    lineNumber: Int64
): MethodActionSelector<TRet> 

功能:创建针对普通成员方法插入桩代码的操作器对象。

参数:

  • stubCall: () -> TRet - 桩签名对应的调用表达式。
  • matchers: Array<ArgumentMatcher> - 对应入参的参数匹配器。
  • objectReference: TObj - 被插桩的对象的引用。
  • objectName: String - 被插桩的对象的名称。
  • methodName: String - 被插桩的方法名称。
  • callDescription: String - 桩签名对应的调用表达式的字符串表达。
  • lineNumber: Int64 - 对应的调用表达式的行号。

返回值:

static func stubSetter<TObj, TRet>(() -> Unit, () -> TArg,ArgumentMatcher,TObj,String,String,String,Int64)

public static func stubSetter<TObj, TArg>(
    stubCall: () -> Unit,
    _: () -> TArg,
    matcher: ArgumentMatcher,
    objectReference: TObj,
    objectName: String,
    fieldOrPropertyName: String,
    callDescription: String,
    lineNumber: Int64
): SetterActionSelector<TArg>

功能:创建针对属性 Setter 方法插入桩代码的操作器对象。

参数:

  • stubCall: () -> Unit - 桩签名对应的调用表达式。
  • _: () -> TArg - 用于捕获属性或者字段的类型。
  • matcher: ArgumentMatcher - 入参的参数匹配器。
  • objectReference: TObj - 被插桩的对象的引用。
  • objectName: String - 被插桩的对象的名称。
  • fieldOrPropertyName: String - 被插桩的属性或字段的名称。
  • callDescription: String - 桩签名对应的调用表达式的字符串表达。
  • lineNumber: Int64 - 对应的调用表达式的行号。

返回值:

class Continuation

public class Continuation<A> where A <: ActionSelector {}

功能:此类提供了可继续定义桩签名的行为的 API 。 此类提供的方法能力如下:

  • 允许当先前的操作得到满足时,桩签名将执行额外的操作。仅当后面跟着一个行为定义时,Continuation 实例才有意义。
  • 当先前的操作未得到满足时,将抛出 MockFrameworkException 异常。并不保证抛出此异常的确切位置。

func then()

func then(): A

功能: 当链中的先前操作完成时,返回 ActionSelector 的子类对象。

返回值:

异常:

class GetterActionSelector

public class GetterActionSelector<TRet> <: ActionSelector {}

功能:此类提供了为属性 Getter 函数指定一个操作 API ,并允许链式调用的方法。 入参为 mock objectspy object 的某个成员函数的调用表达式的 @On 宏调用表达式,将返回 ActionSelector 的实例。即,此类或其子类中的 API 可为成员函数插入桩代码。

父类型:

func getsField(SyntheticField<TRet>)

public func getsField(field: SyntheticField<TRet>): CardinalitySelector<GetterActionSelector<TRet>> 

功能:读取合成字段

参数:

返回值:

func getsOriginal()

public func getsOriginal(): CardinalitySelector<GetterActionSelector<TRet>> 

功能:读取原始属性或获取原始实例中的字段值。

返回值:

func returns(TRet)

public func returns(value: TRet): CardinalitySelector<GetterActionSelector<TRet>>

功能:指定返回值。

参数:

  • value: TRet - 指定的返回的值。

返回值:

func returns(() -> TRet)

public func returns(valueFactory: () -> TRet): CardinalitySelector<GetterActionSelector<TRet>>

功能:指定返回值。

参数:

  • valueFactory: () -> TRet - 指定的返回的值生成器。

返回值:

func returnsConsecutively(Array<TRet>)

public func returnsConsecutively(values: Array<TRet>)

功能:指定返回多个值。

参数:

  • values: Array<TRet> - 指定的返回的多个值。

返回值:

func returnsConsecutively(ArrayList<TRet>)

public func returnsConsecutively(values: ArrayList<TRet>)

功能:指定返回多个值。

参数:

  • values: ArrayList<TRet> - 指定的返回的多个值。

返回值:

func throws(Exception)

public func throws(exception: Exception): CardinalitySelector<GetterActionSelector<TRet>>

功能:指定抛出异常。

参数:

  • exception: Exception - 指定的抛出的异常。

返回值:

func throws(() -> Exception)

public func throws(exceptionFactory: () -> Exception): CardinalitySelector<GetterActionSelector<TRet>>

功能:指定抛出异常。

参数:

  • exceptionFactory: () -> Exception - 指定的抛出的异常的生成器。

返回值:

extend MethodActionSelector<Unit>

extend MethodActionSelector<Unit> {}

功能:扩展 MethodActionSelector

func returns()

public func returns(): CardinalitySelector<MethodActionSelector<TRet>> 

功能:指定桩函数什么都不做。

返回值:

class Matchers

public class Matchers {}

功能:该类提供生成匹配器的静态函数。匹配器对象仅可通过此处的静态函数生成。匹配器可在桩链中使用。

例如:@On(foo.bar(ofType<Int64>())).returns(1)

参数匹配器可以在 @On 宏调用表达式入参处使用,来描述期望将哪些参数传递到桩签名中。参数匹配器有两个最常见的用途:

  • 为不同的参数指定不同的行为。例如:

    // 当 bar 的入参为 5 时,返回某个值
    @On(foo.bar(eq(5))).returns(...)
    // 当 bar 的入参为 6 时,抛出异常
    @On(foo.bar(eq(6))).throws(...)
    
  • 确保只有某些参数被传递到某些桩签名中。

    let foo = mock<Foo>()
    // bar 的入参只能为正数,否则将抛出 UnhandledCallException 异常
    @On(foo.bar(argThat<Int64> { arg => arg > 0 })).returns(...)
    

    注意:

    上例仅适用于 mock objectspy object 的行为不同。

    let foo = spy(Foo())
    // 当 bar 的入参不为正数时,将调用 Foo() 对象的成员函数。
    @On(foo.bar(argThat<Int64> { arg => arg <= 0 })).fails()
    

static func any()

public static func any(): AnyMatcher

功能:允许将任何值作为参数。

返回值:

  • AnyMatcher - 允许任意值的参数匹配器。

static func argThat<T>(ValueListener<T>, (T) -> Bool)

public static func argThat<T>(listener: ValueListener<T>, predicate: (T) -> Bool): TypedMatcher<T>

功能:通过传入的 predicate 闭包函数过滤传入的参数值,允许 listener 值监听器对满足条件的传入参数值进行处理。

参数:

  • listener: ValueListener<T> - 值监听器。
  • predicate: (T) ->Bool - 过滤器,可通过此函数定义过滤参数值的匹配条件。

返回值:

  • TypedMatcher<T> - 拥有值监听器和过滤器的类型匹配器。

static func argThat<T>((T) -> Bool)

public static func argThat<T>(predicate: (T) -> Bool): TypedMatcher<T>

功能:根据提供的过滤器闭包过滤输入值。

参数:

  • predicate: (T) ->Bool - 过滤器。

返回值:

static func argThatNot<T>((T) -> Bool)

public static func argThatNot<T>(predicate: (T) -> Bool): TypedMatcher<T>

功能:根据提供的过滤器闭包过滤输入值。

参数:

  • predicate: (T) ->Bool - 过滤器。

返回值:

static func capture<T>(ValueListener<T>)

public static func capture<T>(listener: ValueListener<T>): TypedMatcher<T>

允许 listener 值监听器对类型为 T 的传入参数值进行处理。当 capture 的类型参数未指定时,将使用值监听器的类型参数值。

参数:

返回值:

注意:值监听器不允许在 @Called 的参数范围内使用。

static func default<T>(T)

public static func default<T>(target: T): TypedMatcher<T>

功能:根据结构(更高优先级)或引用相等性来匹配值。如果传入的参数既不是 Equatable<T> 也不是引用类型,则会在运行时抛出异常(编译期不做检查)。

参数:

  • target: T - 必须通过结构或引用相等来匹配的匹配对象。

返回值:

异常:

static func eq<T>(T)

public static func eq<T>(target: T): TypedMatcher<T> where T <: Equatable<T>

功能:根据与提供的值的结构相等性过滤输入值。

参数:

  • target: T - 匹配对象。

返回值:

  • TypedMatcher<T> - 仅允许结构上等于给定值的参数匹配器。

static func ofType<T>()

public static func ofType<T>(): TypedMatcher<T>

功能:根据类型过滤输入值。

返回值:

  • TypedMatcher<T> - 仅允许特定类型的类型匹配器。

static func same<T>(T) where T <: Object

public static func same<T>(target: T): TypedMatcher<T> where T <: Object

功能:根据与所提供对象的引用相等性来过滤输入值。

参数:

  • target: T - 匹配对象。

返回值:

  • TypedMatcher<T> - 仅允许与给定对象引用相等的参数的参数匹配器。

extend Matchers

extend Matchers {}

功能:扩展 Matchers

static func none()

public static func none(): NoneMatcher

功能:过滤值为 None 的入参值。

返回值:

class MethodActionSelector

public class MethodActionSelector<TRet> <: ActionSelector {}

功能:此类提供了为成员函数指定一个操作 API ,并允许链式调用。 入参为 mock objectspy object 的某个成员函数的调用表达式的 @On 宏调用表达式,将返回 ActionSelector<R> 的实例(其中 R 代表正在配置的函数成员的返回值类型)。 即,此类中的 API 可为成员函数插入桩代码。

父类型:

func callsOriginal()

func callsOriginal(): CardinalitySelector<R>

功能:定义桩签名执行原始代码逻辑的行为。

返回值:

func returns(() -> R)

func returns(valueFactory: () -> R): CardinalitySelector<R>

功能:定义桩签名返回指定的值的行为,该值由传入的闭包生成。

参数:

  • valueFactory: () ->R - 生成预期返回值的闭包函数(生成器)。

返回值:

func returns(R)

func returns(value: R): CardinalitySelector<R>

功能:定义桩签名返回指定值的行为。

参数:

  • value: R - 预期桩签名的返回值。

返回值:

func returnsConsecutively(Array<R>)

func returnsConsecutively(values: Array<R>): Continuation<R>

功能:定义桩签名按列表顺序返回指定的值的行为。桩签名将被调用多次,次数与数组内值的个数相同。

参数:

  • values: Array<R> - 桩签名的返回值列表。

返回值:

异常:

func returnsConsecutively(ArrayList<R>)

func returnsConsecutively(values: ArrayList<R>): Continuation<R>

功能:定义桩签名按列表顺序返回指定的值的行为。桩签名将被连续调用多次,次数与数组列表内值的个数相同。

参数:

  • values: ArrayList<R> - 桩签名的返回值列表。

返回值:

异常:

func throws(() -> Exception)

func throws(exceptionFactory: () -> Exception): CardinalitySelector<R>

功能:定义桩签名抛出异常的行为,异常由参数闭包函数生成。

说明:

throws vs fails

throws 意味着测试桩签名抛出异常后的行为是测试的目的。例如,当某些服务不可用时,系统是否可以正确恢复等。 fails 意味着调用桩签名将导致测试失败。即,如果系统行为正确,则永远不应调用该桩签名。

参数:

  • exceptionFactory: () ->Exception - 构造预期桩签名抛出的异常对象的闭包函数(生成器)。

返回值:

func throws(Exception)

func throws(exception: Exception): CardinalitySelector<R>

功能:定义桩签名抛出异常的行为。

参数:

  • exception: Exception - 预期桩签名抛出的异常对象。

返回值:

class MockFramework

public class MockFramework {}

功能:提供用例执行所需的框架准备与结束回收阶段的函数。

static func openSession

public static func openSession(name: String, sessionKind: MockSessionKind): Unit

功能:打开一个新会话。会话形成一个类似堆栈的结构。 会话关闭的顺序与开始时的顺序相反。 在给定会话期间创建的 mock object 只能在该会话或其任何内部会话内部访问。 每个会话都保留自己的调用日志,因此对最新打开会话内进行的调用执行任何验证, 只有在会议结束时才能验证期望。

参数:

static func closeSession

public static func closeSession(): Unit

功能:打开一个新会话。会话形成一个类似堆栈的结构。 会话关闭的顺序与开始时的顺序相反。 在给定会话期间创建的 mock object 只能在该会话或其任何内部会话内部访问。 每个会话都保留自己的调用日志,因此对最新打开会话内进行的调用执行任何验证, 只有在会议结束时才能验证期望。

异常:

class NoneMatcher

public class NoneMatcher <: ArgumentMatcher {}

功能:参数值为 None 的匹配器。

父类型:

func matchesAny

public override func matchesAny(arg: Any): Bool

功能:匹配任意输入值,值为 None 时返回 true

参数:

  • arg: Any - 待匹配的入参值。

返回值:

  • Bool - 当输入为 None 时返回 true ,否则返回 false

extend NoneMatcher

extend NoneMatcher {}

功能:扩展 NoneMatcher

func value<T>()

public func value<T>(): Option<T>

功能:框架需要调用的参数匹配器的返回值。

返回值:

  • Option<T> - 与实际入参值类型匹配的值。

class OrderedVerifier

public class OrderedVerifier {}

功能:此类型用于收集 “验证语句”,可在 ordered 函数中动态传入验证行为。

func checkThat(VerifyStatement)

public func checkThat(statement: VerifyStatement): OrderedVerifier

功能:添加一条 “验证语句”。

参数:

返回值:

class SetterActionSelector

public class SetterActionSelector<TRet> <: ActionSelector {}

功能:此类提供了为属性 Setter 函数指定一个操作 API ,并允许链式调用的方法。 入参为 mock objectspy object 的某个成员函数的调用表达式的 @On 宏调用表达式,将返回 ActionSelector 的实例。即,此类或其子类中的 API 可为成员函数插入桩代码。

父类型:

func doesNothing()

public func doesNothing(): CardinalitySelector<SetterActionSelector<TArg>>

功能:指定该属性或字段不做任何动作。

返回值:

func setsOriginal()

public func setsOriginal(): CardinalitySelector<SetterActionSelector<TArg>>

功能:设置原始属性或获取原始实例中的字段值。

返回值:

func setsField(SyntheticField<TRet>)

public func setsField(field: SyntheticField<TArg>): CardinalitySelector<SetterActionSelector<TArg>>

功能:设置合成字段

参数:

返回值:

func throws(Exception)

public func throws(exception: Exception): CardinalitySelector<GetterActionSelector<TRet>>

功能:指定抛出异常。

参数:

  • exception: Exception - 指定的抛出的异常。

返回值:

func throws(() -> Exception)

public func throws(exceptionFactory: () -> Exception): CardinalitySelector<GetterActionSelector<TRet>>

功能:指定抛出异常。

参数:

  • exceptionFactory: () -> Exception - 指定的抛出的异常的生成器。

返回值:

class SyntheticField

public class SyntheticField<T> {}

功能:合成字段。用于处理可变属性和字段。

static func create(T)

public static func create(initialValue!: T): SyntheticField<T>

功能:创建合成字段。

参数:

  • initialValue!: T - 初始值。

返回值:

class TypedMatcher

public abstract class TypedMatcher<T> <: ArgumentMatcher {}

功能:参数类型匹配器。

父类型:

func matches(T)

public func matches(arg: T): Bool

功能:检查入参类型是否与预期相符。

参数:

  • arg: T - 待检查的入参。

返回值:

  • Bool - 若类型匹配则返回 true ,否则返回 false

func matchesAny(Any)

public func matchesAny(arg: Any): Bool

功能:检查入参类型是否与预期相符。

参数:

  • arg: Any - 待检查的入参。

返回值:

  • Bool - 若类型匹配则返回 true ,否则返回 false

extend<T> TypedMatcher<T>

extend<T> TypedMatcher<T> {}

功能:扩展 TypedMatcher

func value<T>()

public func value<T>(): T

功能:框架需要调用的参数匹配器的返回值。

返回值:

  • T - 与实际入参值类型匹配的值。

class UnorderedVerifier

public class UnorderedVerifier{
    public func checkThat(statement: VerifyStatement):UnorderedVerifier
}

功能:此类型用于收集 “验证语句”, 可在 unordered 函数中动态传入验证行为。

func checkThat(VerifyStatement)

public func checkThat(statement: VerifyStatement):UnorderedVerifier

功能:添加一条 “验证语句”。

参数:

返回值:

class Verify

public class Verify {}

功能:Verify 提供了一系列静态方法来支持定义所需验证的动作,如 thatordered 以及 unorder

一个验证动作可以包含多个由 @Called 生成的验证语句,来描述需要验证的动作。 通常验证的范围为所在测试用例的函数体,但 Verify 提供了 clearInvocationLog 函数来清除此前的执行记录,以缩小验证范围。 行为验证是指,验证“桩签名”的操作是否按所定义的方式执行,当验证实际执行与定义不一致时,将抛出异常。

具体支持验证的行为如下:

  • 所指定的“桩签名”是否被执行。
  • 所指定的“桩签名”是否执行指定的次数。
  • 所指定的“桩签名”在执行时,被传入的参数是否满足要求。
  • 所指定的多个“桩签名”的调用顺序是否满足要求。

行为验证主要通过以下两个步骤完成:

  • 通过调用 Verify 的静态方法定义一个验证动作。
  • 通过 @Called 宏调用表达式定义所需验证的 “桩签名”的执行动作。为简化表达,后文将其称为“验证语句”。

举例来说:

let foo = mock<Foo>()
// 定义“桩签名”的“桩行为”
@On(foo.bar().returns(1))
// 实际“桩签名”在用例中的执行情况
foo.bar()
// 验证“桩签名”的执行情况:foo.bar() 至少执行了一次
Verify.that(@Called(foo.bar()))

值得注意的是, CardinalitySelector<R> 提供了一些 API ,其支持验证一些行为 。因此,用户可自由选择不同的方式进行行为验证。

static func clearInvocationLog()

public static func clearInvocationLog(): Unit

功能:清除前序的执行记录,以缩小验证范围。

static func noInteractions(Array<Object>)

public static func noInteractions(mocks: Array<Object>): Unit

功能:在验证范围内,对象没有任何执行动作时,验证通过。

参数:

异常:

static func ordered((OrderedVerifier) -> Unit)

public static func ordered( collectStatements: (OrderedVerifier) -> Unit): Unit

功能:此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义,并且校验执行顺序。默认情况下,“验证语句”的执行次数为一次。 传入列表中的“验证语句”必须是不相交的(即当单个调用行为,可以匹配多个“验证语句”时,将抛出异常)。 “验证语句”通过入参中的闭包动态增加。 验证模式为 exhaustive (全量匹配,验证范围内的所有执行情况都应在验证动作中被指定)。

参数:

  • collectStatements: (OrderedVerifier) ->Unit - 支持可动态增加“验证语句”的闭包。

异常:

static func ordered(Array<VerifyStatement>)

public static func ordered(statements: Array<VerifyStatement>): Unit

功能:此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义,并且校验执行顺序。默认情况下,“验证语句”的执行次数为一次。 传入列表中的“验证语句”必须是不相交的(即当单个调用行为,可以匹配多个“验证语句”时,将抛出异常)。 验证模式为 exhaustive (全量匹配,验证范围内的所有执行情况都应在验证动作中被指定)。

举例来说:

for (i in 0..4) {
    foo.bar(i % 2)
}

Verify.ordered(
    @Called(foo.bar(0)),
    @Called(foo.bar(1)),
    @Called(foo.bar(0)),
    @Called(foo.bar(1)),
)

// 将抛出异常,验证范围内有 4 次 foo.bar() 表达式的执行动作,此处只验证了2次执行。
Verify.ordered(
    @Called(foo.bar(0)),
    @Called(foo.bar(_)),
)

参数:

  • statements: Array<VerifyStatement> - 所需验证的“验证语句”。

异常:

static func that(VerifyStatement)

public static func that(statement: VerifyStatement): Unit

功能:验证是否正确执行了传入的单个“验证语句”。

参数:

异常:

static func unordered((UnorderedVerifier) -> Unit)

public static func unordered(collectStatements: (UnorderedVerifier) -> Unit): Unit

功能:此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义,并且不校验执行顺序。默认情况下,“验证语句”的执行次数为至少一次。 传入列表中的“验证语句”必须是不相交的(即当单个调用行为,可以匹配多个“验证语句”时,将抛出异常)。 验证模式为 exhaustive (全量匹配,验证范围内的所有执行情况都应在验证动作中被指定)。 “验证语句”通过入参中的闭包动态增加。举例来说:


let totalTimes = getTimes()
for (i in 0..totalTimes) {
    foo.bar(i % 2)
}
// 通过闭包使得“验证语句”可以通过 totalTimes 的值确定内容
Verify.unordered { v =>
    for (j in 0..totalTimes) {
        v.checkThat(@Called(foo.bar(eq(j % 2))))
    }
}

参数:

异常:

static func unordered(Array<VerifyStatement>)

public static func unordered(statements: Array<VerifyStatement>): Unit

功能:此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义,并且不校验执行顺序。默认情况下,“验证语句”的执行次数为至少一次。 传入列表中的“验证语句”必须是不相交的(即当单个调用行为,可以匹配多个“验证语句”时,将抛出异常)。 验证模式为 exhaustive (全量匹配,验证范围内的所有执行情况都应在验证动作中被指定)。

举例来说:

let foo = mock<Foo>()
for (i in 0..4) {
    foo.bar(i % 2)
}

// 验证 bar() 在传入参数为 0 或 1 的情况下均至少执行一次
Verify.unordered(
    @Called(foo.bar(0)),
    @Called(foo.bar(1))
)

// 此处的验证动作将抛出异常,因为 `foo.bar(_)` 包含了 `foo.bar(1)`
Verify.unordered(
    @Called(foo.bar(_)).times(2),
    @Called(foo.bar(1)).times(2)
)
// 可以通过如下方式进行验证
// 验证入参为 1 的调用表达式执行了2次
Verify.that(@Called(foo.bar(1)).times(2))
// 验证任意入参的调用表达式执行了2次
Verify.that(@Called(foo.bar(_)).times(2)) // called four times in total

参数:

  • statements: Array<VerifyStatement> - 待验证的多条“验证语句”,变长参数语法支持参数省略 []

异常:

static func unordered(Exhaustiveness, (UnorderedVerifier) -> Unit)

public static func unordered(exhaustive: Exhaustiveness, collectStatements: (UnorderedVerifier) -> Unit): Unit

功能:此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义,并且不校验执行顺序。默认情况下,“验证语句”的执行次数为至少一次。 传入列表中的“验证语句”必须是不相交的(即当单个调用行为,可以匹配多个“验证语句”时,将抛出异常)。 “验证语句”通过入参中的闭包动态增加。

参数:

异常:

static func unordered(Exhaustiveness, Array<VerifyStatement>)

public static func unordered(exhaustive: Exhaustiveness, statements: Array<VerifyStatement>): Unit

功能:此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义,并且不校验执行顺序。默认情况下,“验证语句”的执行次数为至少一次。 传入列表中的“验证语句”必须是不相交的(即当单个调用行为,可以匹配多个“验证语句”时,将抛出异常)。

参数:

异常:

class VerifyStatement

public class VerifyStatement {}

功能:此类型表示对“桩签名”在验证范围内的单个验证验证语句(即上文中的“验证语句”),提供了成员函数指定“桩签名”的执行次数。 该类型的对象仅可通过 @Called 宏调用表达式创建。 对一个对象连续调用多个成员函数没有意义,并且会抛出异常。即,执行次数仅可被指定一次。 当未调用成员函数指定执行次数时,将基于语句所在的验证动作类型定义默认的执行次数验证值。例如在 Verify.ordered() 中的“验证语句”默认为验证执行一次。

func atLeastOnce()

public func atLeastOnce(): VerifyStatement

功能:指定此“验证语句”验证在验证范围内“桩签名”最少被执行一次。

返回值:

异常:

  • MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时,将抛出异常。

func atLeastTimes(Int64)

public func atLeastTimes(minTimesExpected: Int64): VerifyStatement

功能:指定此“验证语句”验证在验证范围内“桩签名”最少执行指定的次数。

参数:

  • minTimesExpected: Int64 - 预期验证的执行最少次数。

返回值:

异常:

  • MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时,将抛出异常。

func once()

public func once(): VerifyStatement

功能:指定此“验证语句”验证在验证范围内“桩签名”仅被执行一次。

返回值:

异常:

  • MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时,将抛出异常。

func times(Int64)

public func times(expectedTimes: Int64): VerifyStatement

功能:指定此“验证语句”验证在验证范围内“桩签名”被执行指定次数。

参数:

  • expectedTimes: Int64 - 预期验证的执行次数。

返回值:

异常:

  • MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时,将抛出异常。

func times(Int64, Int64)

public func times(min!: Int64, max!: Int64): VerifyStatement

功能:指定此“验证语句”验证在验证范围内“桩签名”的执行次数在指定范围内。

参数:

  • min!: Int64 - 预期验证的最小执行次数。
  • max!: Int64 - 预期验证的最大执行次数。

返回值:

异常:

  • MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时,将抛出异常。

枚举

enum Exhaustiveness

public enum Exhaustiveness {
    Exhaustive | Partial
}

功能:此枚举类型用于指定 unordered 函数的验证模式,包含两种模式。 Exhaustive 模式要求对于验证范围内的所有桩签名,均需在验证动作中定义。 Partial 模式的要求较松,可以忽略“桩签名”在验证范围内未被验证动作定义的执行行为。

举例来说:

for (i in 0..6) {
    foo.bar(i % 3)
}

// 此处验证动作将抛出异常,因为 foo.bar()在验证范围内一共执行了 6 次,而此处的验证动作仅指定了 4 次执行行为。
Verify.unordered(
    @Called(foo.bar(1)).times(2),
    @Called(foo.bar(2)).times(2)
)

// 此处验证动作可以成功,指定了 Partial 模式后,2 次未在验证动作中定义的执行行为将被忽略。
Verify.unordered(Partial,
    @Called(foo.bar(1)).times(2),
    @Called(foo.bar(2)).times(2)
)

Exhaustive

Exhaustive

功能:要求在验证范围内的每一次“桩签名”的调用均需在验证动作中被定义。

Partial

Partial

功能:允许验证范围内存在未在验证动作中被定义的“桩签名”的调用行为。

enum MockSessionKind

public enum MockSessionKind {
    | Forbidden
    | Stateless
    | Verifiable
}

功能:控制允许在 MockSession 使用的的类型。 只能验证在 VerifiableSession 中创建的桩的期望。

Forbidden

功能:不允许使用

Stateless

功能:只允许无状态的。 不允许本质上有状态的操作,例如 returnsConsequively 和基数说明符( cardinality specifier, 指定预期执行次数的表达式)。

Verifiable

功能:允许任意

enum StubMode

public enum StubMode {
    | ReturnsDefaults
    | SyntheticFields
} 

功能:控制桩的模式

ReturnsDefaults

功能:Mock object 将为基础类型返回默认的值。用于简化 mock object 的配置步骤。 这些默认值一般为空或 0 。 支持的基础类型为:Unit, 数值类型( 如 Int64 ), option 类型, Bool, String, Array, ArrayList, HashSet, HashMap 。

SyntheticFields

功能:Mock object 会将其可变属性和字段视为可变字段。 与直接使用 SyntheticField 类似,但更简洁。 读取未初始化的字段将导致错误。

异常类

class ExpectationFailedException

public open class ExpectationFailedException <: PrettyException {}

功能:在测试执行期间违反了 mock 配置期间设置的一个或多个期望。

父类型:

class MockFrameworkException

public class MockFrameworkException <: PrettyException {}

功能:框架异常信息,用户使用 API 不满足框架要求时,抛出该异常。

父类型:

class MockFrameworkInternalError

public class MockFrameworkInternalError <: PrettyException {}

功能:框架异常信息,用户不应期望该异常被抛出。

父类型:

class PrettyException

public abstract class PrettyException <: Exception & PrettyPrintable {}

功能:支持 PrettyPrintable 的异常类型,可以较好得打印异常信息。

父类型:

func pprint

public func pprint(to: PrettyPrinter): PrettyPrinter

功能:支持较好得颜色打印、缩进格式打印异常信息。

参数:

返回值:

class UnhandledCallException

public class UnhandledCallException <: PrettyException {}

功能:提供的均未处理该调用。

父类型:

class UnnecessaryStubbingException

public class UnnecessaryStubbingException <: PrettyException {}

功能:指示被测试的代码从未触发

父类型:

class UnstubbedInvocationException

public class UnstubbedInvocationException <: PrettyException {}

功能:未提供与此调用匹配的

父类型:

class VerificationFailedException

public class VerificationFailedException <: PrettyException {}

功能:验证失败时,框架所抛出的异常。 父类型:

mock 框架入门

使用 mock 框架

mock 框架本身是仓颉标准库中单元测试的一部分。使用 mock 框架前,需将 unittest.mock.*unittest.mock.mockmacro.* 导入到测试文件中。

如果使用 cjpm 工具,仅需运行 cjpm test 命令即可自动启用 mock 框架。

如果直接使用 cjc ,参见使用 cjc

示例

常见 mock 测试用例:

  • 调用mock 构造函数创建 mock/spy 对象。
  • 调用配置 API设置 mock 行为。
  • 使用 mock 对象替代测试代码依赖。
  • (可选)调用验证 API来验证测试代码与 mock/spy 对象之间的交互。

以如下简单API为例:

public interface Repository {
    func requestData(id: UInt64, timeoutMs: Int): String
}

public class Controller {
    public Controller(
        private let repo: Repository
    ) {}

    public func findData(id: UInt64): ?String {
        try {
            return repo.requestData(id, 100)
        }
        catch (e: TimeoutException) {
            return None
        }
    }
}

public class TimeoutException <: Exception {}

如果 Repository 实现不理想,比如可能包含复杂的依赖关系,实现在其他包中,或者测试太慢,mock 框架可以在不创建依赖的情况下测试 Controller

测试 findData 方法:

//导入mock框架包
import std.unittest.mock.*
import std.unittest.mock.mockmacro.*

@Test
class ControllerTest {
    let testId: UInt64 = 100
    let testResponse = "foo"

    @TestCase
    func testFindSuccessfully() {
        //只需要创建mock,不用创建真正的Repository
        let repository = mock<Repository>()

        //使用@On宏配置testData行为
        @On(repository.requestData(testId, _)).returns(testResponse)

        //创建真正的Controller测试以便测试实际的实现
        let controller = Controller(repository)

        //运行测试代码
        let result = controller.findData(testId)

        //对结果运行断言
        @Assert(result == Some(testResponse))
    }

    @TestCase
    func testTimeout() {
        let repository = mock<Repository>()

        //设置getData抛出异常
        @On(repository.requestData(testId, _)).throws(TimeoutException())

        let controller = Controller(repository)

        //底层实现抛出异常时,测试行为
        let result = controller.findData(testId)

        //对结果运行断言
        @Assert(result == None)
    }
}

mock 基础概念及用法

创建 mock 对象

mock 构造函数可以通过调用 mock<T>spy<T> 函数来创建两种对象:mockspy,其中 T 表示被 mock 的类或接口。

public func mock<T>(): T
public func spy<T>(objectToSpyOn: T): T

mock 作为骨架对象,默认不对成员进行任何操作。 spy 作为一种特殊的 mock 对象用于封装某个类或接口的当前实例。默认情况下,spy 对象将其成员调用委托给底层对象。 其他方面,spy 和 mock 对象非常相似。

只有(包括 final 类和 sealed 类)和接口支持 mock 。

参阅使用 mock 和 spy 对象

配置 API

配置 API 是框架的核心,可以定义 mock/spy 对象成员的行为(或重新定义 spy 对象)。 配置 API 的入口是 @On 宏调用。

@On(storage.getComments(testId)).returns(testComments)

示例中,如果 mock 对象 storage 接收getComments 方法的调用,并且指定了参数 testId ,则返回 testComment

如上行为即为打桩,桩(Stub, 模拟还未实现或无法在测试环境中执行的组件)需在测试用例主体内部先定义。

只有类和接口的实例成员(包括 final 成员)才能打桩。以下实体不能打桩:

  • 静态成员
  • 扩展成员
  • 顶层函数,包括外部函数

一个完整的桩声明包含以下部分:

  1. @On 宏调用中描述的桩签名
  2. 用于描述桩行为的操作
  3. (可选)用于设置预期的基数说明符( cardinality specifier, 指定预期执行次数的表达式)。
  4. (可选)续体( continuation, 支持链式调用的表达式)。

mock 框架拦截匹配桩签名的调用,并执行桩声明中指定的操作。只能拦截 spy 对象和 mock 对象的成员。

桩签名

桩签名定义了与特定调用子集匹配的一组条件,包括以下部分:

  • mock/spy 对象的引用,必须是单个标识符。
  • 成员调用。
  • 特定格式的参数调用,参见参数匹配器

签名可以匹配以下实体:

  • 方法
  • 属性 getter
  • 属性 setter
  • 字段读操作
  • 字段写操作

只要 mock/spy 对象调用相应的成员,并且所有参数(若有)都与相应的参数匹配器匹配时,桩签名就会匹配调用。

方法的桩的签名结构:<mock object name>.<method name>(<argument matcher>*)

@On(foo.method(0, 1))                 // 带参数 0 和 1 的方法调用
@On(foo.method(param1: 0, param2: 1)) // 带命名参数的方法调用

当桩属性 getter/setter 或字段读/写操作时,使用 <mock object name>.<property or field name><mock object name>.<property or field name> = <argument matcher>

@On(foo.prop)      //属性 getter
@On(foo.prop = 3)  //参数为3的属性 setter

对运算符函数打桩时,运算符的接收者必须是对 mock/spy 对象的单个引用,而运算符的参数必须是参数匹配器。

@On(foo + 3)  // 'operator func +',参数为3
@On(foo[0])   // 'operator func []',参数为0

参数匹配器

每个桩签名必须包含所有参数的参数匹配器。单个参数匹配器定义了一个条件,用于接受所有可能参数值的某个子集。 每个匹配器都是通过调用 Matchers 类的静态方法来定义的。 例如 Matchers.any() 是一个允许任何参数的有效匹配器。为了方便起见,提供省略 Matcher. 前缀的语法糖。

预定义的匹配器包括:

匹配器描述语法糖
any()任何参数_ 符号
eq(value: Equatable)value 结构相等( structural equality ,对象的值相等,不一定内存相同)的参数允许使用单个 identifier 和常量字面量
same(reference: Object)reference 引用相等(referential equality, 对象的引用相等,内存相同)的参数允许单个identifier
ofType<T>()仅匹配 T 类型的值-
argThat(predicate: (T) -> Bool)仅匹配由 predicate 筛选出的 T 类型的值-
none()匹配选项类型的 None-

如果使用单个标识符作为参数匹配器,则优先选择结构相等的参数。

如果方法有默认参数,并且没有显式指定该参数,则使用 any() 匹配器。

示例:

let p = mock<Printer>()         // 假设print采用ToString类型的单个参数。

@On(p.print(_))                 // 可以使用“_”特殊字符代替 any() 。

@On(p.print(eq("foo")))         // 只匹配“foo”参数。
@On(p.print("foo"))             // 常量字符串可以省略显式匹配器。

let predefined = "foo"          // 可以传递单个标识符,而不是参数匹配器。
@On(p.print(predefined))        // 如果类型相等,则使用结构相等来匹配。

@On(p.print(ofType<Bar>()))     // 仅匹配Bar类型的参数。

// 对于更复杂的匹配器,鼓励使用以下模式。
let hasQuestionMark = { arg: String => arg.contains("?") }
@On(p.print(argThat(hasQuestionMark)))  // 只匹配包含问号的字符串。

正确选择函数重载依赖仓颉类型推断机制。可以使用 ofType 来解决与类型推断有关的编译时问题。

重要规则:函数调用作为参数匹配器时,会视为对匹配器的调用。

@On(foo.bar(calculateArgument())) // 不正确,calculateArgument()不是匹配器。

let expectedArgument = calculateArgument()
@On(foo.bar(expectedArgument))    // 正确,只要 'expectedArgument' 是可等价的和/或引用类型。

操作 API

mock 框架提供 API 来指定桩操作。触发桩后,打桩成员会执行指定的操作。如果调用与相应的 @On 宏调用指定的签名匹配,则会触发桩。

每个桩函数必须指定一个操作。 @On 宏调用返回的 ActionSelector 子类型会定义可用操作。操作列表取决于所打桩的实体。

通用(操作)

适用于所有桩的操作。

  • throws(exception: Exception):抛出 exception
  • throws(exceptionFactory: () -> Exception):调用 exceptionFactory 去构造桩触发时抛出的异常。
  • fails():如果触发了桩,则测试失败。

throws 用于测试桩成员抛出异常时的系统行为。fails 用于测试桩成员是否未被调用。

@On(service.request()).throws(TimeoutException())

方法和属性/字段 Getter

R 表示对应成员的返回类型。

  • returns():不做任何操作并返回 (),仅当 RUnit 时可用。
  • returns(value: R):返回 value
  • returns(valueFactory: () -> R):调用 valueFactory 去构造桩触发时抛出的异常。
  • returnsConsecutively(values: Array<R>), returnsConsecutively(values: ArrayList<R>):触发桩时,返回 values 中的下一个元素。
@On(foo.bar()).returns(2) // 返回 0
@On(foo.bar()).returnsConsecutively(1, 2, 3) // 依次返回 1,2,3

属性/字段 Setter

  • doesNothing():忽略调用,不做任何操作。类似于返回 Unit 的函数的 returns()。 更多信息详见这里

spy 操作

对于 spy 对象,可以使用其他操作来委托监控实例。

  • callsOriginal() :调用原始方法。
  • getsOriginal() :调用原始属性 getter 或获取原始实例中的字段值。
  • setsOriginal() :调用原始属性 setter 或设置原始实例中的字段值。

预期

定义桩时会隐式或显式地向桩附加预期。桩可以定义期望的基数。操作failsreturnsConcesecutively 除外)返回CardinalitySelector 的实例,该实例可以使用基数说明符自定义预期。

CardinalitySelector 定义了如下函数:

  • once()
  • atLeastOnce()
  • anyTimes()
  • times(expectedTimes: Int64)
  • times(min!: Int64, max!: Int64)
  • atLeastTimes(minTimesExpected: Int64)

anyTimes 说明符用于提升预期,即如果桩从未被触发,测试也不会失败。其他说明符都暗示了测试代码中特定桩的调用次数上下限。只要桩被触发的次数比预期的多,测试就会立即失败。下限在测试代码执行完毕后进行检查。

示例:

// example_test.cj
@Test
func tooFewInvocations() {
    let foo = mock<Foo>()
    @On(foo.bar()).returns().times(2)
    foo.bar()
}

输出:

Expectation failed
    Too few invocations for stub foo.bar() declared at example_test.cj:9.
        Required: exactly 2 times
        Actual: 1
        Invocations handled by this stub occured at:
            example_test.cj:6

如果没有自定义预期,mock框架使用默认预期:

操作默认期望基数允许自定义基数
fails不可调用
returnsatLeastOnce
returnsConsecutivelytimes(values.size)
throwsatLeastOnce
doesNothingatLeastOnce
(calls/gets/sets)OriginalatLeastOnce

桩链

returnsConsecutively 操作,oncetimes(n) 基数说明符返回一个续体实例。顾名思义,续体表示可以继续使用链,即指定某操作在前一个操作完全完成时立即执行。

续体本身只提供了一个返回新 ActionSelectorthen() 函数。链上的所有操作都适用相同的规则。如果调用了 then() ,则必须指定新的操作。

总预期为各个链预期之和。如果在测试中指定了一个复杂的链,那么链的所有部分都会被触发。

@On(foo.bar()).returnsConsecutively(1, 2, 3, 4)
//同下
@On(foo.bar()).returnsConsecutively(1, 2).then().returnsConsecutively(3, 4)
// 指定了一个桩,总共必须调用 NUM_OF_RETRIES 次
@On(service.request()).throws(TimeoutException()).times(NUM_OF_RETRIES - 1). // 请求会先超时几次
    then().returns(response).once() // 第一个成功响应之后,停止发送请求

使用 spy 和 mock 对象

spy 对象和 mock 对象在配置上是类似的,只不过 spy 对象监控的是当前实例。

主要区别如下:成员调用没有触发任何桩时,spy 对象调用底层实例的原始实现,mock 对象抛出运行时错误(并且测试失败)。

mock 对象无需创建真正的依赖来测试 API ,只需配置特定测试场景所需的行为。

spy 对象支持重写真实实例的可观察行为。只有通过 spy 对象引用的调用才会被拦截。创建 spy 对象对原始 spy 实例的引用无影响。spy 调用自己的方法不会被拦截。

let serviceSpy = spy(service)
// 模拟超时,继续使用真正的实现
@On(serviceSpy.request()).throws(TimeoutException()).once().then().callsOriginal()
// 测试代码必须使用'serviceSpy'引用

mock 依赖

接口始终可以被 mock 。从另一个包 mock 一个类时,类本身和它的超类必须按特定方式编译, 即只能 mock 预编译库(如 stdlib )中的接口,不能 mock 类。

使用 cjc 编译

对于 cjc 来说,mock 是通过 --mock 标志来控制的。 如果想 mock 特定包中的类 p ,添加 --mock=on 标志到 cjc 进行调用。

在编译依赖 p 的包时,也必须添加此标志。

在测试中使用mock对象( cjc--test )不需要额外的标志。

使用 cjpm 编译

cjpm 会自动检测 mock 使用,并生成正确的 cjc 调用,确保可以从任何从源代码编译的包中 mock 类。

还可以使用 cjpm 配置文件控制哪些包支持 mock 。

桩使用指南

mock/spy 对象和桩的使用方法多种多样。本文介绍了不同的模式和用例,便于用户编写 mock 框架的可维护且简洁的测试用例。

桩的工作原理

通过在测试用例内部调用 @On 宏来声明,该声明在特定测试用例执行完成之前有效。多个测试用例之间可以共享桩

mock 框架处理 mock/spy 对象成员调用时的顺序如下:

  • 查找特定成员的桩。后声明的桩优先于之前声明的桩。测试用例主体内部声明的桩优先于共享桩。
  • 应用每个桩的参数匹配器。如果所有参数都成功匹配,则执行该桩定义的操作。
  • 如果找不到桩,或者没有与实际参数匹配的桩,则应用默认行为:对于 mock 对象,上报未打桩调用错误;对于 spy 对象,调用监控实例的原始成员。

无论是否为单个成员定义了多个桩,每个桩都有自己的预期,需要满足这些预期才能通过测试。

@On(foo.bar(1)).returns(1)
@On(foo.bar(2)).returns(2)

foo.bar(2)
// 第一个桩已定义但从未使用,测试失败

重新定义桩

如果希望在测试中更改桩的行为,可以重新定义桩。

@On(service.request()).returns(testData)
// 使用服务

@On(service.request()).throws(Exception())
// 测试服务开始失败时会发生什么事情

同一成员定义多个桩

根据不同参数,可以使用多个桩来定义不同的行为。

示例:

@On(storage.get(_)).returns(None)                  // 1
@On(storage.get(TEST_ID)).returns(Some(TEST_DATA)) // 2

示例中,storage 为除 TEST_ID 之外的所有参数返回 None 。 如果从未使用 TEST_ID 参数调用 get ,则测试失败,因为桩 2 未使用。如果始终使用 TEST_ID 参数调用 get ,则测试失败,因为桩 1 未使用。这些限制确保测试代码是纯净的,让开发人员知道桩何时变为未使用。如果用例不需要此功能,则使用 anyTimes() 基数说明符来提升这些预期。

// 实现经常更改,但不希望测试中断
// 使用 anyTimes 提升与测试本身无关的预期
@On(storage.get(_)).returns(None).anyTimes()
@On(storage.get(TEST_ID)).returns(Some(TEST_DATA)) // 测试必须调用正在测试的内容

鉴于桩优先级是从下到上,以下用法都不正确。

@On(storage.get(TEST_ID)).returns(Some(TEST_DATA)) // 不正确,这个桩永远不会被触发
@On(storage.get(_)).returns(None)                  // 在上面的桩始终会被隐藏

您还可以使用预期来检查调用的参数。

let renderer = spy(Renderer())

@On(renderer.render(_)).fails()
let isVisible = { c: Component => c.isVisible }
@On(renderer.render(argThat(isVisible))).callsOriginal() // 只允许可见的组件

共享 mock 对象和桩

测试需要大量使用 mock 对象时可以多个测试用例共享 mock 对象和/或桩。 可以在任何位置创建 mock 或 spy 对象。然而,如果误将 mock 对象从一个测试用例泄漏到另一个测试用例,可能导致顺序依赖问题或测试不稳定。因此,不建议这样操作,mock 框架也会检测这类情况。 在同一测试类下的测试用例之间共享 mock 或 spy 对象时,可以将它们放在该类的实例变量中。

桩声明中隐含了预期,因此更难处理共享桩。测试用例之间不能共享预期。 只有2个位置可以声明桩:

  • 测试用例主体(无论是 @Test 函数还是@Test类中的@TestCase):检查预期。
  • @Test 类中的 beforeAll 中:在测试用例之间共享桩。这样的桩不能声明预期,预期也不会被检查。不允许使用基数说明符。只允许 returns(value)throws(exception)fails()callsOriginal()无状态操作。可以将这些桩视为具有隐式 anyTimes() 基数。

如果测试用例的预期相同,则可以在测试用例主体中提取和调用函数(测试类中非测试用例的成员函数)。

使用 beforeAll

@Test
class TestFoo {
    let foo = mock<Foo>()

    //单元测试框架会在执行测试用例之前调用以下内容
    public func beforeAll(): Unit {
        //在所有测试用例之间共享默认行为
        //此桩无需在每个测试用例中使用
        @On(foo.bar(_)).returns("default")
    }

    @TestCase
    func testZero() {
        @On(foo.bar(0)).returns("zero") //本测试用例中需要使用此桩
        foo.bar(0) //返回 "zero"
        foo.bar(1) //返回 "default"
    }

    @TestCase
    func testOne() {
        @On(foo.bar(0)).returns("one")
        foo.bar(0) //返回 "one"
    }
}

使用函数:

@Test
class TestFoo {
    let foo = mock<Foo>()

    func setupDefaultStubs() {
        @On(foo.bar(_)).returns("default")
    }

    @TestCase
    func testZero() {
        setupDefaultStubs()
        @On(foo.bar(0)).returns("zero")

        foo.bar(0) //返回"zero"
        foo.bar(1) //返回"default"
    }

    @TestCase
    func testOne() {
        setupDefaultStubs()
        @On(foo.bar(0)).returns("zero")
        foo.bar(0) //返回"zero"

        //预期失败,桩已声明但从未使用
    }
}

要在测试类构造函数中声明桩。无法保证何时调用测试类构造函数。

捕获参数

mock 框架使用 captor(ValueListener) 参数匹配器捕获参数来检查传递到桩成员的实际参数。只要触发了桩,ValueListener 就会拦截相应的参数,并检查参数和/或添加验证参数。

每次调用时,还可以使用 ValueListener.onEach 静态函数来验证某个条件。接受 lambda 后,触发桩时都会调用这个 lambda 。lambda 用于接收参数的值。

let renderer = spy(TextRenderer())
let markUpRenderer = MarkupRenderer(renderer)

// 创建验证器
let validator = ValueListener.onEach { str: String =>
    @Assert(str == "must be bold")
}

// 使用 'capture' 参数匹配器绑定参数到验证器
@On(renderer.renderBold(capture(validator))).callsOriginal() // 如果从来没有调用过,则测试失败

markUpRenderer.render("text inside tag <b>must be bold</b>")

另外 ValueListener 还提供了 allValues()lastValue() 函数来检查参数。模式如下:

//创建捕获器
let captor = ValueListener<String>.new()

//使用'capture'参数匹配器绑定参数到捕获器
@On(renderer.renderBold(capture(captor))).callsOriginal()

markUpRenderer.render("text inside tag <b>must be bold</b>")

let argumentValues = captor.allValues()
@Assert(argumentValues.size == 1 && argumentValues[0] == "must be bold")

argThat 匹配器是一个结合了参数过滤和捕获的重载函数。argThat(listener, filter) 接受 ValueListener 实例和 filter 谓词。listener 只收集通过 filter 检查的参数。

let filter = { arg: String => arg.contains("bold") }
let captor = ValueListener<String>.new()

// 失败,除非参数被拦截,但下面已经声明了桩
@On(renderer.renderBold(_)).fails()
// 只收集包含 "bold" 的字符串
@On(renderer.renderBold(argThat(captor, filter))).callsOriginal()

markUpRenderer.render("text inside tag <b>must be bold</b>")

// 可以使用 'captor' 对象检查所有过滤参数
@Assert(captor.lastValue() == "must be bold")

参数捕获器可以与 mock 和 spy 对象一起使用。但是,在 @Called 宏中不允许使用此类参数匹配器。

自定义和使用参数匹配器

为了避免重复使用相同的参数匹配器,可以自定义参数匹配器。

如下示例为在测试用例之间共享匹配器:

@On(foo.bar(oddNumbers())).returns("Odd")
@On(foo.bar(evenNumbers())).returns("Even")
foo.bar(0) // "Even"
foo.bar(1) // "Odd"

由于每个匹配器都只是 Matchers 类的静态函数,因此可以使用扩展来自定义参数匹配器。新参数匹配器需要调用现有的(实例)。

extend Matchers {
    static func evenNumbers(): TypedMatcher<Int> {
        argThat { arg: Int => arg % 2 == 0}
    }

    static func oddNumbers(): TypedMatcher<Int> {
        argThat { arg: Int => arg % 2 == 1}
    }
}

函数参数匹配器可以包含参数。

extend Matchers {
    //只接受Int参数。
    static func isDivisibleBy(n: Int): TypedMatcher<Int> {
        argThat { arg: Int => arg % n == 0}
    }
}

大多数匹配器函数都指定了返回类型 TypedMatcher<T> 。这样的匹配器只接受类型为 T 。在桩声明中使用参数匹配器调用时,类型为 T 的值应该是被打桩函数或属性 setter 的有效参数。换句话说,类型 T 应该是参数子类型或与参数实际类型相同。

设置属性和字段

字段和属性打桩的方式与方法相同,可以依相同操作来配置返回值。

setter 类似于返回 Unit 的函数。特殊操作 doesNothing() 可用于 setter。

可变属性打桩的常用模式如下:

@On(foo.prop).returns("value")  //配置getter
@On(foo.prop = _).doesNothing() //忽略setter调用

极少场景下,我们期望可变属性的行为与字段的行为相同。要创建合成字段(框架生成的字段),请使用 SyntheticField.create 静态函数。合成字段存储由 mock 框架来管理。适用于 mock 含有可变属性和字段的接口或抽象类的场景。

执行 getsFieldsetsField 桩操作将字段绑定到特定的调用,这些操作可以将预期配置为任何其他操作。

interface Foo {
    mut prop bar: String
}

@Test
func test() {
    let foo = mock<Foo>()
    let syntheticField = SyntheticField.create(initialValue: "initial")
    @On(foo.bar).getsField(syntheticField)     // 对属性的读取访问即为读取合成字段
    @On(foo.bar = _).setsField(syntheticField) // 为属性写入新值

    //此时'bar'属性表现为字段
}

如果多个测试用例之间共享 SyntheticField 对象,则该字段本身的值会在每个测试用例之前重置为 initialValue ,避免在测试之间共享可变状态。

桩的模式

通常,当一些调用匹配不到任何桩时将抛出异常。 但是,对于某些常见情况, mock 对象可以配置增加默认行为,此时,当匹配不到任何桩时,将执行默认行为。这通过启用桩模式来实现。 有两种可用的模式 ReturnsDefaultsSyntheticFields 。 这些模式通过枚举类型 StubMode 表示。可以通过在创建 mock 对象时将其传递给 mock 函数来为特定的 mock 对象启用桩模式。

public func mock<T>(modes: Array<StubMode>): T

桩模式可用于在配置 mock 对象时减少代码,并且它们可以与显式桩自由组合。显式的桩始终优先于其默认行为。 请注意,使用桩模式不会对 mock 对象的成员强加任何期望。 当用例是检查是否仅调用 mock 对象的某些特定成员,则应谨慎使用桩模式。被测对象的行为可能会以不期望的方式发生变化,但测试仍可能通过。

ReturnsDefaults 模式

在此模式下,当成员的返回类型在如下表格中时,无需显式配置桩,即可调用。

let foo = mock<Foo>(ReturnsDefaults)
@Assert(foo.isPretty(), false)

此类成员返回的默认值也如如下表格所示。

类型默认值
Boolfalse
numbers0
Stringempty string
OptionNone
ArrayList, HashSet, Arraynew empty collection
HashMapnew empty map

ReturnsDefaults 模式仅对如下成员生效:

  • 返回值为支持类型(如上表)的成员函数。
  • 类型为支持类型(如上表)的属性读取器和字段。

SyntheticFields 模式

SyntheticFields 模式可简化对 SyntheticField 的配置动作,详见 设置属性和字段 章节。 SyntheticFields 将通过 mock 框架为所有属性和字段隐式创建对应类型的合成字段。但是,这些字段只能在被赋值后读取。仅对可变属性和字段生效。

let foo = mock<Foo>(SyntheticFields)
// can simply assign a value to a mutable property
foo.bar = "Hello"
@Assert(foo.bar, "Hello")

赋给属性和字段的值仅在相应的测试用例中可见。 当同时启用 SyntheticFieldsReturnsDefaults 时,赋的值优先于默认值。但是,只要字段或属性尚未被赋值,就可以使用默认值。

let foo = mock<Foo>(ReturnsDefaults, SyntheticFields)
@Assert(foo.bar, "")
foo.bar = "Hello"
@Assert(foo.bar, "Hello")

mock 框架验证 API

验证 API 是 mock 框架的一部分,其功能如下:

  • 验证是否进行了某些调用。
  • 验证特定调用的次数。
  • 验证是否使用特定参数进行调用。
  • 验证调用是否按特定顺序进行。

验证通过检查在执行测试期间构建的调用日志来运行断言。调用日志涵盖让 mockspy 对象在测试中可访问的所有调用。只能验证在 mock/spy 对象上进行的调用。

Verify 类是验证 API 的入口。 @Called 宏用于构建关于代码的断言。

@Called 宏调用构造了一个 验证语句 ,即根据调用日志检查代码的单个断言。 Verify 类本身是静态方法的集合。诸如 thatorderedunordered 等方法可构造验证块

示例

let foo = mock<Foo>()
//配置foo
@On(foo.bar()).returns()
foo.bar()
Verify.that(@Called(foo.bar())) //验证bar至少被调用一次

验证语句和 @Called

验证语句由 VerifyStatement 类表示。 VerifyStatement 实例由 @Called 宏创建。

@Called 宏调用接受桩签名,类似于 @On 宏,并且适用参数匹配器的规则。

示例:

@Called(foo.bar(1, _)) //匹配bar方法调用的验证语句,其中第一个参数为'1'
@Called(foo.baz)       //匹配baz属性getter调用的验证语句

VerifyStatement 类提供的 API 类似于桩配置时可用的基数说明符。

基数函数为:

  • once()
  • atLeastOnce()
  • times(expectedTimes: Int64)
  • times(min!: Int64, max!: Int64)
  • atLeastTimes(minTimesExpected: Int64)
  • never()

调用这些函数会返回相同的 VerifyStatement 实例。同一语句不能重置基数,且必须在语句传递到验证块生成器函数之前设置基数。如果没有显式设置基数,则使用默认基数。

Verify.that(@Called(foo.bar()).atLeastOnce())
Verify.that(@Called(foo.bar()).once())

验证块

验证块通常包含一个或多个验证语句,且检查块中的语句会构成更复杂的断言。

在调用验证块时会立即验证,不验证之后发生的任何调用。 验证块不会改变调用日志的状态:日志中的每个调用都可以被任意数量的块检查。独立检查各个块,前后块之间没有依赖关系。除非在块之间发生了一些调用,或者手动清除了调用日志,否则调用验证块的顺序并不重要。

验证语句本身不执行任何类型的验证,必须传递到验证块中进行验证。

单个验证块仅检查在块内验证语句中提到的 mock/spy 对象上的调用,忽略对其他对象的调用。

Verify 类包含几个构建验证块的静态方法。有序验证块用于检查调用的确切顺序。无序验证块只验证调用的次数。

有序

如需检查一个或多个对象的调用顺序,使用 ordered 验证块生成器。

ordered 静态函数接收一个验证语句数组。

for (i in 0..4) {
    foo.bar(i % 2)
}

Verify.ordered(
    @Called(foo.bar(0)),
    @Called(foo.bar(1)),
    @Called(foo.bar(0)),
    @Called(foo.bar(1))
)

允许检查多个对象的调用顺序。

for (i in 0..4) {
    if (i % 2 == 0) {
        fooEven.bar(i)
    }
    else {
        forOdd.bar(i)
    }
}

Verify.ordered(
    @Called(fooEven.bar(0)),
    @Called(fooOdd.bar(1)),
    @Called(fooEven.bar(2)),
    @Called(fooOdd.bar(3)),
)

有序验证的默认基数说明符是 once() 。如有需要,可使用其他基数说明符。

for (i in 0..4) {
    foo1.bar(i)
}

for (i in 0..4) {
    foo2.bar(i)
}

Verify.ordered(
    @Called(foo1.bar(_).times(4)),
    @Called(foo2.bar(_).times(4))
)

对于有序验证,须列出对(块中提到的) mock/spy 对象的所有调用。任何未列出的调用都会导致验证失败。

foo.bar(0)
foo.bar(10)
foo.bar(1000)

Verify.ordered(
    @Called(foo.bar(0)),
    @Called(foo.bar(10))
)

输出:

验证失败
    以下调用未匹配到任何语句:
        foo.bar(...) at example_test.cj:6

无序

无序验证只检查其验证语句的调用次数。

对于无序验证,除非显式指定,否则使用 atLeastOnce() 基数,即检查至少进行了一次的调用。

for (i in 0..4) {
    foo.bar(i % 2)
}

//验证是否至少调用了一次使用参数0和参数1的bar
Verify.unordered(
    @Called(foo.bar(0)),
    @Called(foo.bar(1))
)

//验证是否调用了两次使用参数0和参数1的bar
Verify.unordered(
    @Called(foo.bar(0)).times(2),
    @Called(foo.bar(1)).times(2)
)

//验证是否总共调用了四次bar
Verify.unordered(
    @Called(foo.bar(_)).times(4)
)

无序验证包括 PartialExhaustive

默认为 Exhaustive ,需要列出验证语句所提到的 mock/spy 对象的所有调用。 Partial 只列出部分调用。

for (i in 0..4) {
    foo.bar(i)
}

//失败,foo.bar()的两次调用未在块中列出
Verify.unordered(
    @Called(foo.bar(0)).once(),
    @Called(foo.bar(1)).once()
)

//忽略无关调用
Verify.unordered(Partial,
    @Called(foo.bar(0)).once(),
    @Called(foo.bar(1)).once()
)

动态构建验证块

orderedunordered 函数为接受 lambda 的重载函数。可使用 checkThat(statement: VerifyStatement) 函数动态添加语句。

示例:

let totalTimes = 40
for (i in 0..totalTimes) {
    foo.bar(i % 2)
}

Verify.ordered { v =>
    for (j in 0..totalTimes) {
        v.checkThat(@Called(foo.bar(eq(j % 2))))
    }
}

其他 API

另外,Verify 类还提供了以下工具。

  • that(statement: VerifyStatement) 为 Verify.unordered(Paritial, statement) 的别名,用于检查单个语句,不需要列出对应 mock/spy 对象的所有调用。
  • noInteractions(mocks: Array) 用于检查没有进行调用的 mock/spy 对象。
  • clearInvocationLog() 将日志重置为空状态。这会影响后面的所有验证块,但并不影响桩预期。
  • 示例:

    foo.bar()
    Verify.that(@Called(foo.bar())) // OK
    Verify.noInteractions(foo)      // 失败,foo.bar() 调用在日志中
    Verify.clearInvocationLog()     // 清除日志
    Verify.noInteractions(foo)      // 从日志中清除所有与 foo 的交互
    Verify.that(@Called(foo.bar())) // 失败
    

    Verify 类 API

    public static func that(statement: VerifyStatement): Unit
    
    public static func unordered(
        exhaustive: Exhaustiveness,
        collectStatements: (UnorderedVerifier) -> Unit
    ): Unit
    
    public static func unordered(
        collectStatements: (UnorderedVerifier) -> Unit
    ): Unit
    
    public static func unordered(statements: Array<VerifyStatement>): Unit
    
    public static func unordered(
        exhaustive: Exhaustiveness,
        statements: Array<VerifyStatement>
    ): Unit
    
    public static func ordered(
        collectStatements: (OrderedVerifier) -> Unit
    ): Unit
    
    public static func ordered(statements: Array<VerifyStatement>): Unit
    
    public static func clearInvocationLog(): Unit
    
    public static func noInteractions(mocks: Array<Object>): Unit
    

    验证错误

    验证失败时,会抛出 VerificationFailedException ,mock 框架会给出报告。不要捕获该异常。

    失败类型如下:

    • 调用次数太少调用次数太多:调用次数与块中的语句不匹配。
    • 语句不匹配:块中存在与日志中的调用不匹配的语句。
    • 调用不匹配:日志中存在与块中的语句不匹配的调用。
    • 意外调用有序验证块需要的是其他的调用。
    • 无用交互noInteractions 检测到意外调用。

    还有另一种失败类型不相交的语句,不一定是测试代码本身有问题。调用匹配到多个语句时,就会上报这种失败类型。在单个验证块中使用具有不相交参数匹配器的语句可能会导致此错误。不允许在语句和调用之间进行模糊匹配。

    示例和模式

    使用验证 API 的常见模式是验证测试代码(无论是函数、类还是整个包)与外部对象之间的交互。 如下所示:

    • 创建 spy 对象。
    • 将这些 spy 对象传递给测试代码。
    • 验证代码和 spy 对象之间的交互。

    验证调用数量

    func testDataCaching() {
        // 创建必要的spy或mock对象
        let uncachedRepo = spy(Repository())
        let invalidationTracker = mock<InvalidationTracker>()
        @On(invalidationTracker.getTimestamp()).returns(0)
    
        // 准备测试数据
        let cachedRepo = CachedRepistory(uncachedRepo, invalidationTracker)
    
        // 运行测试代码
        for (i in 0..10) {
            cachedRepo.get(TEST_ID)
        }
    
        // 验证得出只查询了一次基础repo,没有对未缓存repo的其他调用
        Verify.unordered(Exhaustive,
            @Called(uncachedRepo.get(TEST_ID)).once()
        )
    
        // 清除日志
        Verify.clearInvocationLog()
    
        // 设置其他行为
        @On(invalidationTracker.getTimestamp()).returns(1)
    
        for (i in 0..10) {
            cachedRepo.get(TEST_ID)
        }
    
        // 自上次清除后只进行了一次调用
        Verify.unordered(Exhaustive,
            @Called(uncachedRepo.get(TEST_ID)).once()
        )
    }
    

    验证带特定参数的调用

    func testDrawingTriangle() {
        // 创建必要的 spy 或 mock 对象
        let canvas = spy(Canvas())
    
        // 运行代码
        canvas.draw(Triangle())
    
        // 测试三角形由3条线和3个点组成
    
        // 使用 'that' 块
        Verify.that(
            @Called(canvas.draw(ofType<Dot>())).times(3)
        )
        Verify.that(
            @Called(canvas.draw(ofType<Line>())).times(3)
        )
    
        //或者使用部分无序验证块
    
        Verify.unordered(Partial, // 未知线条和点实际绘制的顺序
            @Called(canvas.draw(ofType<Dot>())).times(3),
            @Called(canvas.draw(ofType<Line>())).times(3)
        )
    
        // 使用枚举块时,必须枚举出所有调用
        Verify.unordered(Exhaustive,
            @Called(canvas.draw(ofType<Triangle>())).once(),
            @Called(canvas.draw(ofType<Dot>())).times(3),
            @Called(canvas.draw(ofType<Line>())).times(3)
        )
    
        // 验证用例从未调用入参为 Square 类型的 draw 函数
        Verify.that(
            @Called(canvas.draw(ofType<Square>)).never()
        )
    
        // 如果想通过更复杂的条件来区分参数
        // 可以使用下面的模式
        let isDot = { f: Figure =>
            f is Dot //此为更复杂的逻辑
        }
    
        Verify.that(
            @Called(canvas.draw(argThat(isDot))).times(3)
        )
    
        // 注意,属于同一个块的语句必须明确只匹配了一个调用
        // 以下为反例,有些调用匹配了两个语句
        Verify.unordered(
            @Called(canvas.draw(_)).times(7),
            @Called(canvas.draw(ofType<Dot>())).times(3)
        )
    }
    

    验证调用顺序

    func testBuildFlight() {
        let plane = spy(Plane())
    
        FlightBuilder(plane).planFlight(Shenzhen, Shanghai, Beijing).execute()
    
        Verify.ordered(
            @Called(plane.takeOffAt(Shenzhen)),
            @Called(plane.landAt(Shanghai)),
            @Called(plane.takeOffAt(Shanghai)),
            @Called(plane.landAt(Beijing))
        )
    }
    

    预期与验证 API

    配置桩时,可以设置预期和验证API覆盖测试代码的一些断言。这种情况别无他法,只能选择更能反映测试意图的方法。

    一般情况下,建议避免重复验证块中的配置步骤。

    let foo = mock<Foo>()
    @On(foo.bar(_)).returns() //如果从未使用此桩,测试失败
    
    foo.bar(1)
    foo.bar(2)
    
    Verify.that(
        //不需要,自动验证
        @Called(foo.bar(_)).atLeastOnce()
    )
    
    //但可以检查调用的数量和具体的参数
    Verify.unordered(
        @Called(foo.bar(1)).once(),
        @Called(foo.bar(2)).once()
    )
    

    上面的示例可以使用预期重写:

    let foo = mock<Foo>()
    @On(foo.bar(1)).returns().once() //预期只被调用一次,参数为`1`
    @On(foo.bar(2)).returns().once() //预期只被调用一次,参数为`2`
    
    foo.bar(1)
    foo.bar(2)
    
    //如果没有桩被触发,则测试失败
    

    std.unittest.mock.mockmacro 包

    功能介绍

    unittest.mock.mockmacro 为 mock 框架提供了用户所需的宏。

    API 列表

    宏名功能
    Called创建一个验证语句
    On使用配置 API定义 mock/spy 对象成员的行为(或重新定义 spy 对象)。

    @Called

    功能:创建一个验证语句

    @On

    功能:使用配置 API定义 mock/spy 对象成员的行为(或重新定义 spy 对象)。

    std.unittest.testmacro 包

    功能介绍

    unittest.testmacro 为单元测试框架提供了用户所需的宏。

    API 列表

    宏名功能
    AfterAll声明测试类中的函数为测试生命周期函数。被该宏修饰的函数在所有测试用例之后运行一次。
    AfterEach声明测试类中的函数为测试生命周期函数。被该宏修饰的函数在每个测试用例之后运行一次。
    Assert声明 Assert 断言,测试函数内部使用,断言失败停止用例。
    AssertThrows声明预期异常的断言,测试函数内部使用,断言失败停止用例。
    BeforeAll声明测试类中的函数为测试生命周期函数。被该宏修饰的函数在所有测试用例之前运行一次。
    BeforeEach声明测试类中的函数为测试生命周期函数。被该宏修饰的函数在每个测试用例之前运行一次。
    Bench宏用于标记要执行多次的函数并计算该函数的预期执行时间。
    Configure为测试类或测试函数提供配置参数。它可以放置在测试类或测试函数上。
    CustomAssertion@CustomAssertions 将函数指定为用户自定义断言。
    Expect声明 Expect 断言,测试函数内部使用,断言失败继续执行用例。
    ExpectThrows声明预期异常的断言,测试函数内部使用,断言失败继续执行用例。
    Fail声明预期失败的断言,测试函数内部使用,断言失败停止用例。
    FailExpect声明预期失败的断言,测试函数内部使用,断言失败继续执行用例。
    Measurement用于为性能测试指定 Measurement 实例。只能应用于标有 @Test 宏的类或顶级函数的范围内。
    Parallel可以修饰测试类。被 @Parallel 修饰的测试类中的测试用例可并行执行。
    PowerAssert检查传递的表达式是否为真,并显示包含传递表达式的中间值和异常的详细图表。
    Skip修饰已经被 @TestCase / @Bench 修饰的函数,使该测试用例被跳过。
    Strategy用于组合、映射和重用各种数据策略。
    Tag@Tag 宏可以应用于 @Test 类和 @Test@TestCase 函数,提供测试实体的元信息。
    Test宏应用于顶级函数或顶级类,使该函数或类转换为单元测试类。
    TestBuilder声明一个动态测试套。
    TestCase宏用于标记单元测试类内的函数,使这些函数成为单元测试的测试用例。
    Timeout指示测试应在指定时间后终止。它有助于测试可能运行很长时间或陷入无限循环的复杂算法。
    Types宏为测试类或测试函数提供类型参数。它可以放置在测试类或测试函数上。

    @AfterAll

    功能:声明测试类中的函数为测试生命周期函数。被该宏修饰的函数在所有测试用例之后运行一次。

    @AfterEach

    功能:声明测试类中的函数为测试生命周期函数。被该宏修饰的函数在每个测试用例之后运行一次。

    @Assert

    功能:@Assert 声明 Assert 断言,测试函数内部使用,断言失败停止用例。

    1. @Assert(leftExpr, rightExpr) ,比较 leftExprrightExpr 值是否相同。
    2. @Assert(condition: Bool) ,比较 condition 是否为 true ,即 @Assert(condition: Bool) 等同于 @Assert(condition: Bool, true)
    3. @Assert[customAssertion](arguments...), 使用指定的参数 arguments 调用 customAssertion 函数,详见 @CustomAssertion

    @AssertThrows

    功能:声明预期异常的断言,测试函数内部使用,断言失败停止用例。

    @BeforeAll

    功能:声明测试类中的函数为测试生命周期函数。被该宏修饰的函数在所有测试用例之前运行一次。

    @BeforeEach

    功能:声明测试类中的函数为测试生命周期函数。被该宏修饰的函数在每个测试用例之前运行一次。

    @Bench

    功能:@Bench 宏用于标记要执行多次的函数并计算该函数的预期执行时间。

    此类函数将分批执行,并针对整个批次测量执行时间。这种测量将重复多次以获得结果的统计分布,并将计算该分布的各种统计参数。 当前支持的参数如下:

    • 中位数
    • 用作误差估计的中位数 99% 置信区间的绝对值
    • 中位数 99% 置信区间的相对值
    • 平均值

    参数化的 DSL 与 @Bench 结合的示例如下,具体语法与规则详见@TestCase章节:

    func sortArray<T>(arr: Array<T>): Unit 
            where T <: Comparable<T> {
        if (arr.size < 2) { return }
        var minIndex = 0
        for (i in 1..arr.size) {
            if (arr[i] < arr[minIndex]) { 
                minIndex = i   
            }
        }
        (arr[0], arr[minIndex]) = (arr[minIndex], arr[0])
        sortArray(arr[1..])
    }
    
    @Test 
    @Configure[baseline: "test1"]
    class ArrayBenchmarks{
        @Bench
        func test1(): Unit 
        {
            let arr = Array(10) { i: Int64 => i }
            sortArray(arr)
        }
    
        @Bench[x in 10..20]
        func test2(x:Int64): Unit 
        {
            let arr = Array(x) { i: Int64 => i.toString() }
            sortArray(arr)
        }
    }
    

    输出如下, 增加 Args 列,列举不同参数下的测试数据,每个参数值将作为一个性能测试用例输出测试结果,多个参数时将列举全组合场景:

    --------------------------------------------------------------------------------------------------
    TP: default, time elapsed: 68610430659 ns, Result:
        TCS: ArrayBenchmarks, time elapsed: 68610230100 ns, RESULT:
        | Case   | Args   |   Median |       Err |   Err% |     Mean |
        |:-------|:-------|---------:|----------:|-------:|---------:|
        | test1  | -      | 4.274 us | ±2.916 ns |  ±0.1% | 4.507 us |
        |        |        |          |           |        |          |
        | test2  | 10     | 6.622 us | ±5.900 ns |  ±0.1% | 6.670 us |
        | test2  | 11     | 7.863 us | ±5.966 ns |  ±0.1% | 8.184 us |
        | test2  | 12     | 9.087 us | ±10.74 ns |  ±0.1% | 9.918 us |
        | test2  | 13     | 10.34 us | ±6.363 ns |  ±0.1% | 10.28 us |
        | test2  | 14     | 11.63 us | ±9.219 ns |  ±0.1% | 11.67 us |
        | test2  | 15     | 13.05 us | ±7.520 ns |  ±0.1% | 13.24 us |
        | test2  | 16     | 14.66 us | ±11.59 ns |  ±0.1% | 15.53 us |
        | test2  | 17     | 16.21 us | ±8.972 ns |  ±0.1% | 16.35 us |
        | test2  | 18     | 17.73 us | ±6.288 ns |  ±0.0% | 17.88 us |
        | test2  | 19     | 19.47 us | ±5.819 ns |  ±0.0% | 19.49 us |
        Summary: TOTAL: 11
        PASSED: 11, SKIPPED: 0, ERROR: 0
        FAILED: 0
    --------------------------------------------------------------------------------------------------
    

    @Configure

    功能:@Configure 宏为测试类或测试函数提供配置参数。它可以放置在测试类或测试函数上。

    语法规则为 @Configure[parameter1: <value1>,parameter2: <value2>] 其中 parameter1 是仓颉标识符,value 是任何有效的仓颉表达式。均大小写敏感。 value 可以是常量或在标有 @Configure 的声明范围内有效的任何仓颉表达式。 如果多个参数具有不同的类型,则它们可以有相同的名称。如果指定了多个具有相同名称和类型的参数,则使用最新的一个。

    目前支持的配置参数有:

    • randomSeed: 类型为 Int64, 为所有使用随机生成的函数设置起始随机种子。
    • generationSteps: 类型为 Int64 :参数化测试算法中的生成值的最大步数。
    • reductionSteps :类型为 Int64: 参数化测试算法中的缩减值的最大步数。

    以下参数一般用于被 @Bench 修饰的 Benchmark 测试函数:

    • explicitGC :类型为 ExplicitGcType: Benchmark 函数测试期间如何调用 GC。默认值为 ExplicitGcType.Light 。
    • baseline :类型为 String : 参数值为 Benchmark 函数的名称,作为比较 Benchmark 函数执行结果的基线。该结果值将作为附加列添加到输出中,其中将包含比较结果。
    • batchSize :类型为 Int64 或者 Range<Int64> : 为 Benchmark 函数配置批次大小。默认值是由框架在预热期间计算得到。
    • minBatches :类型为 Int64 : 配置 Benchmark 函数测试执行期间将执行多少个批次。默认值为 10
    • minDuration :类型为 Duration : 配置重复执行 Benchmark 函数以获得更好结果的时间。默认值为 Duration.second * 5 。
    • warmup :类型为 Duration 或者 Int64 : 配置在收集结果之前重复执行 Benchmark 函数的时间或次数。默认值为 Duration.second 。当值为 0 时,表示没有 warmup , 此时执行次数按用户输入的 batchSizeminBatches 计算得到,当 batchSize 未指定时将抛出异常。

    用户可以在 @Configure 宏中指定其他配置参数,这些参数将来可能会用到。 如果测试类使用 @Configure 宏指定配置,则该类中的所有测试函数都会继承此配置参数。 如果此类中的测试函数也标有 @Configure 宏,则配置参数将从类和函数合并,其中函数级宏优先。

    @CustomAssertion

    功能: @CustomAssertions 将函数指定为用户自定义断言。

    该宏修饰的函数应满足两个要求:

    1. 顶层函数
    2. 首个入参为 AssertionCtx 类型。

    示例如下:

    @CustomAssertion
    public func checkNotNone<T>(ctx: AssertionCtx, value: ?T): T {
        if (let Some(res) <- value) {
            return res
        }
        ctx.fail("Expected ${ctx.arg("value")} to be Some(_) but got None")
    }
    

    @CustomAssertion 的输出为树状结构,以提高 嵌套断言 的可读性。

    例如:

    @Test
    func customTest() {
        @Assert[checkNotNone](Option<Bool>.None)
    }
    
    [ FAILED ] CASE: customTest (120812 ns)
    Assert Failed: @Assert[checkNotNone](Option < Bool >.None)
    └── Assert Failed: `('Option < Bool >.None' was expected to be Some(_) but got None)`
    

    返回值

    @CustomAssertion 修饰的函数存在返回值时,它将被 @Assert 宏返回。

    示例如下:

    @Test
    func testfunc() {
        let maybeValue: Option<SomeObject> = maybeReturnsSomeObject()
        let value = @Assert[checkNotNone](maybeValue)
    
        @Assert[otherAssertion](value)
    }
    

    注意: 自定义 @Expect 将总是返回 Unit ,不论 @CustomAssertion 修饰的函数返回值为什么类型。

    嵌套断言

    @CustomAssertion 定义中, @Assert/@Expect (包括自定义断言), @AssertThrows/@ExpectThrows, @Fail/@FailExpect宏均可被调用,形成嵌套。

    例如:

    @CustomAssertion
    func iterableWithoutNone<T>(ctx: AssertionCtx, iter: Interable<?T>): Array<T> {
        iter |> map { it: ?T => @Assert[checkNotNone](it)} |> collectArray
    }
    
    @Test
    func customTest() {
        @Assert[iterWithoutNone]([true, false, Option<Bool>.None])
    }
    
    [ FAILED ] CASE: customTest
    Assert Failed: @Assert[iterWithoutNone]([true, false, Option < Bool >.None])
    └── @Assert[checkNotNone](it):
        └── Assert Failed: `('it' was expected to be Some(_) but got None)`
    

    如果用户自定义的断言在被 @Expect 宏调用时抛出 AssertException 。它会被捕获,不会往外传递。 同样,如果用户自定义的断言失败在被 @Assert 宏调用时不引发异常,异常将被创建并抛出。

    指定泛型类型

    当指定泛型类型参数时,可使用与常规语法来完成。

    例如:

    @CustomAssertion
    public func doesThrow<E>(ctx: AssertionCtx, codeblock: () -> Any): E where E <: Excepiton {
        ...
    }
    
    @Test
    func customTest() {
        let e = @Assert[doesThrow<NoneValueException>]({ => Option<Bool>.None.getOrThrow()})
    }
    

    @Expect

    功能: @Expect 声明 Expect 断言,测试函数内部使用,断言失败继续执行用例。

    1. @Expect(leftExpr, rightExpr) ,比较 leftExprrightExpr 是否相同。
    2. @Expect(condition: Bool) ,比较 condition 是否为 true ,即 @Expect(condition: Bool) 等同于 @Expect(condition: Bool, true)
    3. @Expect[customAssertion](arguments...), 使用指定的参数 arguments 调用 customAssertion 函数。详见 @CustomAssertion

    @ExpectThrows

    功能:声明预期异常的断言,测试函数内部使用,断言失败继续执行用例。

    @Fail

    功能:声明预期失败的断言,测试函数内部使用,断言失败停止用例。

    @FailExpect

    功能:声明预期失败的断言,测试函数内部使用,断言失败继续执行用例。

    @Measure

    功能:用于为性能测试指定 Measurement 实例。只能应用于标有 @Test 宏的类或顶级函数的范围内。 对于每个 Measurement,都会进行不同的测量。因此,指定更多 Measurement 实例,将花费更多时间进行性能测试。 默认值为 TimeNow() ,它在内部使用 DateTime.now() 进行测量。

    例如:

    @Test
    @Measure[TimeNow(), TimeNow(Nanos)]
    class BenchClass {
        @Bench
        func someBench() {
            for (i in 0..1000) {
                1e3 * Float64(i)
            }
        }
    }
    

    输出的测试报告如下:

    | Case      | Measurement  |   Median |         Err |   Err% |     Mean |
    |:----------|:-------------|---------:|------------:|-------:|---------:|
    | someBench | Duration     | 6.319 us | ±0.00019 us |  ±0.0% | 6.319 us |
    |           |              |          |             |        |          |
    | someBench | Duration(ns) |  6308 ns |   ±0.147 ns |  ±0.0% |  6308 ns |
    

    CSV 报告如下:

    Case,Args,Median,Err,Err%,Mean,Unit,Measurement
    "someBench",,"6319","0.185632","0.0","6319","ns","Duration"
    "someBench",,"6308","0.146873","0.0","6308","ns","Duration(ns)"
    

    @Parallel

    功能: @Parallel 宏可以修饰测试类。被 @Parallel 修饰的测试类中的测试用例可并行执行。该配置仅在 --parallel 运行模式下生效。

    1. 所有相关的测试用例应该各自独立,不依赖于任何可变的共享的状态值。
    2. beforeAll()afterAll() 应该是可重入的,以便可以在不同的进程中多次运行。
    3. 需要并行化的测试用例本身应耗时较长。否则并行化引入的多次 beforeAll()afterAll() 可能会超过并行化的收益。
    4. 不允许与 @Bench 同时使用。由于性能用例对底层资源敏感,用例是否并行执行,将影响性能用例的结果,因此禁止与 @Bench 同时使用。

    @PowerAssert

    1. @PowerAssert(leftExpr, rightExpr) ,比较 leftExprrightExpr 值是否相同。
    2. @PowerAssert(condition: Bool) ,比较 condition 是否为 true ,即 @PowerAssert(condition: Bool) 等同于 @PowerAssert(condition: Bool, true)

    @PowerAssert 宏对比 @Assert ,可显示表达式各个可被计算的子表达式的值的详细图表,包括步骤中的异常。

    其打印的详细信息如下:

    Assert Failed: `(foo(10, y: "test" + s) == foo(s.size, y: s) + bar(a))`
                    |          |        |_||  |   |_|    |   |_|| |   |_||
                    |          |       "123"  |  "123"   |  "123" |    1 |
                    |          |__________||  |   |______|      | |______|
                    |            "test123" |  |       3         |    33  |
                    |______________________|  |_________________|        |
                                0             |        1                 |
                                              |__________________________|
                                                            34
    --------------------------------------------------------------------------------------------------
    

    请注意,返回的 Tokens 是初始表达式,但包装到一些内部包装器中,这些包装器允许进一步打印中间值和异常。

    @Skip

    功能:@Skip 修饰已经被 @TestCase / @Bench 修饰的函数,使该测试用例被跳过。

    语法规则为 @Skip[expr]

    1. expr 暂只支持 true ,表达式为 true 时,跳过该测试,其他均为 false
    2. 默认 exprtrue@Skip[true] == @Skip

    @Strategy

    功能:在函数上使用 @Strategy 可从该函数创建新的 DataStrategy 。它是一个用于组合、映射和重用策略的便捷 API。

    标记为 @Strategy 的函数必须满足以下条件:

    1. 必须显式指定返回类型。
    2. 参数必须与宏参数中指定的 DSL 相对应。
    3. 可以在 @Test 标记的类的外部和内部使用。

    实现说明:宏展开的结果是一个具有函数名称和 DataStrategyProcessor 类型的变量。 该变量可以在任何可以使用 DataStrategy 的地方使用。

    @Tag

    @Tag 宏可以应用于 @Test 类和 @Test@TestCase@Bench 函数,提供测试实体的元信息。后续可以通过 --include-tags--exclude-tags 运行选项过滤带有这些标签的测试实体。

    支持的语法

    1. 单个 @Tag 在测试函数上。
    @Tag[Unittest]
    func test() {}
    
    1. 单个 @Tag 包含多个标签名,用逗号分隔。
    @Tag[Unittest, TestAuthor]
    func test() {}
    
    1. 多个 @Tag 在测试函数上。
    @Tag[Smoke]
    @Tag[Backend, JiraTask3271]
    func test() {}
    

    规则与约束

    • 标签应为有效的仓颉语言标识符。
    • @Tag 内的标签列表不应为空。
    • 如果 @Tag 放在 @Test 类的顶部,它会将其标签传播到其中的 @TestCase 函数上。

    例如:

    @Test
    @Tag[Unittest]
    public class UnittestClass {
        @TestCase[x in [1, 2, 3, 4, 5]]
        @Tag[JiraTask3271]
        func caseA(x: Int64) {}
     
        @TestCase
        func caseB() {}
    }
    

    等同于:

    @Test
    @Tag[Unittest]
    public class UnittestClass {
        @TestCase[x in [1, 2, 3, 4, 5]]
        @Tag[Unittest]
        @Tag[JiraTask3271]
        func caseA(x: Int64) {}
     
        @TestCase
        @Tag[Unittest]
        func caseB() {}
    }
    

    @Test

    功能:@Test 宏应用于顶级函数或顶级类,使该函数或类转换为单元测试类。

    如果是顶级函数,则该函数新增一个具有单个测试用例的类提供给框架使用,同时该函数仍旧可被作为普通函数调用。

    标有 @Test 的类必须满足以下条件:

    1. 它必须有一个无参构造函数。
    2. 不能从其他类继承。

    实现说明:@Test 宏为任何用它标记的类引入了一个新的基类:unittest.TestCasesunittest.TestCases 的所有公共和受保护成员(请参阅下面的 API 概述)将在标有 @Test 的类或函数中变得可用,包括两个字段: 1. 包含此测试的 TestContext 实例的 ctx。 2. 包含类的名称的 name 。 单元测试框架的用户不应修改这些字段,因为这可能会导致不可预期的错误。

    @TestBuilder

    功能:声明一个动态测试套。

    @TestCase

    功能:@TestCase 宏用于标记单元测试类内的函数,使这些函数成为单元测试的测试用例。

    标有 @TestCase 的函数必须满足以下条件:

    1. 该类必须用 @Test 标记。
    2. 该函数返回类型必须是 Unit
    @Test
    class Tests {
        @TestCase
        func fooTest(): Unit {...}
    }
    

    测试用例可能有参数,在这种情况下,开发人员必须使用参数化测试 DSL 指定这些参数的值:

    @Test[x in source1, y in source2, z in source3]
    func test(x: Int64, y: String, z: Float64): Unit {}
    

    此 DSL 可用于 @Test@Strategy@Bench@TestCase 宏,其中 @Test 仅在顶级函数上时才可用。如果测试函数中同时存在 @Bench@TestCase ,则只有 @Bench 可以包含 DSL 。 在 DSL 语法中,in 之前的标识符(在上面的示例中为 xyz )必须直接对应于函数的参数,参数源(在上面的示例中为source1source2source3)是任何有效的仓颉表达式(该表达式类型必须实现接口 DataStrategy<T> 或 DataStrategyProcessor<T>,详见下文)。 参数源的元素类型(此类型作为泛型参数 T 提供给接口 DataStrategy<T> )必须与相应函数参数的类型严格相同。

    支持的参数源类型如下:

    • Arrays: x in [1,2,3,4]
    • Ranges: x in 0..14
    • 随机生成的值: x in random()
    • 从 json 文件中读取到的值: x in json("filename.json")
    • 从 csv 文件中读取到的值: x in csv("filename.csv")
    • @Strategy 修饰的函数: x in nameOfStrategyAnnotatedFunction
    • 使用 DataStrategyProcessor 组合数据策略的结果。

    高级用户可以通过定义自己的类型并且实现 DataStrategy<T> 接口来引入自己的参数源类型。

    使用 random() 的随机生成函数默认支持以下类型:

    • Unit
    • Bool
    • 所有内置的 integer 类型(包含有符号和无符号)
    • 所有内置的 float 类型
    • Ordering
    • 所有已支持类型的数组类型
    • 所有已支持类型的 Option 类型

    若需要新增其他的类型支持 random() ,可以让该类型扩展 Arbitrary 。 在参数有多个值时,beforeEach / afterEach 不会在不同值下重复执行而仅会执行一次。若确实需要在每个值下做初始化和去初始化,需要在测试主体中写。对于性能测试方案, @Strategy 应该用于需要从基准中排除的设置代码。没有为这种情况提供特殊的API,因为在大多数情况下,这样的代码依赖于特定的参数值。

    @Timeout

    功能: @Timeout 指示测试应在指定时间后终止。它有助于测试可能运行很长时间或陷入无限循环的复杂算法。

    语法规则为 @Timeout[expr]

    expr 的类型应为 std.time.Duration 。 其修饰测试类时为每个相应的测试用例提供超时时间。

    @Types

    功能:@Types 宏为测试类或测试函数提供类型参数。它可以放置在测试类或测试函数上。

    语法规则为 @Types[Id1 in <Type1, Type2, Type3>, Id2 in <Type4, Type5> ...] 其中 Id1Id2... 是有效类型参数标识符,Type1Type2Type3...是有效的仓颉类型。

    @Types 宏有以下限制:

    • 必须与 @Test@TestCase@Bench 宏共同使用。
    • 一个声明只能有一个 @Types 宏修饰。
    • 该声明必须是具有与 @Types 宏中列出的相同类型参数的泛型类或函数。
    • 类型列表中列出的类型不能相互依赖,例如 @Types[A in <Int64, String>, B in <List<A>>] 将无法正确编译。但是,在为该类内的测试函数提供类型时,可以使用为测试类提供的类型。例如:
    @Test
    @Types[T in <...>]
    class TestClass<T> {
        @TestCase
        @Types[U in <Array<T>>]
        func testfunc<U>() {}
    }
    

    该机制可以与其他测试框架功能一起使用,例如 @Configure 等。

    @UnittestOption

    该宏可用于注册自定义配置项。只有已注册的配置项才能与单元测试框架一起使用。宏的参数是类型选项名称、可选的验证器回调可选的描述。 对所有单元测试配置项的严格检查保证了控制台输入和源代码的正确性。它可以防止笔误和使用错误类型的值。

    示例:

    @UnittestOption[String, Int](optionName)
    @UnittestOption[String](opt, /*validator*/ { str: String => str.size < 5 })
    @UnittestOption[A, B](option3, { x: Any => ... })
    @UnittestOption[Bool](needLog, /*description*/ "The option do ...")
    @UnittestOption[Int](public myOpt)
    

    具体规则如下:

    • @UnittestOption 对同一个配置项不能重复使用。
    • @UnittestOption 必须在顶层。
    • 如果配置项有多种类型,则验证器回调参数应为 Any,如果只有一种类型对该选项有效,则验证器回调参数应为该具体类型。
    • 验证器回调返回类型为 Bool 或 ?String。
    • true 表示选项有效,false 表示选项值无效。
    • ·Some<String> 包含选项无效原因的描述,None<String> 表示选项值有效。

    @Configuration 配合使用的示例如下:

    配置项的键名称是通过首字母大写并以 Key 字符串开头构建的成员。例如,对于名为 zxc 的配置项,有效键名称将为 KeyZxc.zxc

    @UnittestOption[String](opt)
    
    @Test
    func test_that_derived_type_overwrite_parent_type_value_in_configuration() {
        let conf = Configuration()
    
        conf.set(KeyOpt.opt, "a")
        let value = conf.get(KeyOpt.opt).getOrThrow()
        @PowerAssert(value == "a")
    }
    

    Configuration 类正确处理继承的情况。示例如下:

    open class Base {
        public open func str() {
            "Base"
        }
    }
    
    class Derived <: Base {
        public func str() {
            "Derived"
        }
    }
    
    @UnittestOption[Base](opt)
    
    @Test
    func test_that_derived_type_overwrite_parent_type_value_in_configuration() {
        let conf = Configuration()
    
        conf.set(KeyOpt.opt, Base())
        let first = conf.get(KeyOpt.opt).getOrThrow()
        @PowerAssert(first.str() == "Base")
    
        conf.set(KeyOpt.opt, Derived())
        let second = conf.get(KeyOpt.opt).getOrThrow()
        @PowerAssert(second.str() == "Derived")
    }
    

    std.unittest.common 包

    功能介绍

    unittest.common 为单元测试框架提供了打印所需的类型和一些通用方法。

    API 列表

    函数

    函数名功能
    toStringOrPlaceholder<T>(T)将实现 ToString 的参数转换为字符串表达。

    接口

    接口名功能
    DataProviderDataStrategy 的组件,用于提供测试数据, T 指定提供者提供的数据类型。
    DataShrinkerDataStrategy 的组件,用于在测试期间缩减数据,T 指定该收缩器处理的数据类型。
    DataStrategy为参数化测试提供数据的策略,T 指定该策略操作的数据类型。
    PrettyPrintable类型实现该接口表示可以较好得进行颜色及缩进格式的打印。
    KeyForConfiguration 中配置型的键的类型。

    类名功能
    Configuration存储 @Configure 宏生成的 unittest 配置数据的对象。Configuration 是一个类似 HashMap 的类,但它的键不是键和值类型,而是 String 类型,和任何给定类型的值。
    ConfigurationKey配置项的键值对象。提供判等及 hashCode 方法。
    PrettyPrinter拥有颜色和对齐、缩进控制的打印器。
    PrettyText类似构造器的类,用于存储打印的输出。

    枚举

    枚举名功能
    Color指定颜色。

    函数

    func toStringOrPlaceholder<T>(T)

    public func toStringOrPlaceholder<T>(value: T)
    

    功能:将实现 ToString 的参数转换为字符串表达。不支持 ToString 的转换为默认字符串。

    返回值:

    • String - 参数的字符串表达。

    接口

    interface DataProvider

    public interface DataProvider<T> {
        func provide(): Iterable<T>
        func positions(): Array<Int64>
        prop isInfinite: Bool
    }
    

    功能:DataStrategy 的组件,用于提供测试数据,T 指定提供者提供的数据类型。

    prop isInfinite

    prop isInfinite: Bool
    

    功能:是否无法穷尽。

    类型:Bool

    func provide()

    func provide(): Iterable<T>
    

    功能:获取数据迭代器。

    返回值:

    func positions()

    func positions(): Array<Int64>
    

    功能:获取位置信息。

    返回值:

    • Array<Int64> - 位置信息。

    extend<T> Array<T> <: DataProvider<T>

    extend<T> Array<T> <: DataProvider<T>
    

    功能:为 Array 实现了 DataProvider<T> 接口。使如下配置形式可用:

    @Test[x in [1,2,3]]
    func test(x: Int64) {}
    

    父类型:

    extend<T> Range<T> <: DataProvider<T>

    extend<T> Range<T> <: DataProvider<T>
    

    功能:为 Range 实现了 DataProvider<T> 接口。使如下配置形式可用:

    @Test[x in (0..5)]
    func test(x: Int64) {}
    

    父类型:

    interface DataShrinker<T>

    public interface DataShrinker<T> {
        func shrink(value: T): Iterable<T>
    }
    

    功能:DataStrategy 的组件,用于在测试期间缩减数据,T 指定该收缩器处理的数据类型。

    func shrink(T)

    func shrink(value: T): Iterable<T>
    

    功能:获取类型 T 的值并生成较小值的集合。什么被认为是“较小”取决于数据的类型。

    参数:

    • value: T - 被缩减的值。

    返回值:

    • Iterable<T> - 较小值的集合,当数据无法再被缩减时返回空集合。

    interface DataStrategy

    public interface DataStrategy<T> {
        func provider(configuration: Configuration): DataProvider<T>
        func shrinker(configuration: Configuration): DataShrinker<T>
    }
    

    功能:为参数化测试提供数据的策略,T 指定该策略操作的数据类型。

    func provider(Configuration)

    func provider(configuration: Configuration): DataProvider<T>
    

    功能:获取提供测试数据组件。

    参数:

    返回值:

    func shrinker(Configuration)

    open func shrinker(configuration: Configuration): DataShrinker<T>
    

    功能:获取缩减测试数据的组件。

    参数:

    返回值:

    extend<T> Array<T> <: DataStrategy<T>

    extend<T> Array<T> <: DataStrategy<T>
    

    功能:为 Array 实现了 DataStrategy<T> 接口。使如下配置形式可用:

    @Test[x in [1,2,3]]
    func test(x: Int64) {}
    

    父类型:

    extend<T> Range<T> <: DataStrategy<T>

    extend<T> Range<T> <: DataStrategy<T>
    

    功能:为 Range 实现了 DataStrategy<T> 接口。使如下配置形式可用:

    @Test[x in (0..5)]
    func test(x: Int64) {}
    

    父类型:

    interface PrettyPrintable

    public interface PrettyPrintable {
        func pprint(to: PrettyPrinter): PrettyPrinter
    }
    

    功能:类型实现该接口表示可以较好得进行颜色及缩进格式的打印。

    func pprint(PrettyPrinter)

    func pprint(to: PrettyPrinter): PrettyPrinter
    

    功能:将类型值打印到指定的打印器中。

    参数:

    返回值:

    extend<T> Array<T> <: PrettyPrintable where T <: PrettyPrintable

    extend<T> Array<T> <: PrettyPrintable where T <: PrettyPrintable {
    }
    

    功能:为 Array 类型扩展了 PrettyPrintable 接口。

    父类型:

    func pprint(PrettyPrinter)

    public func pprint(to: PrettyPrinter): PrettyPrinter
    

    功能:将 Array<T> 打印到指定的打印器中。

    参数:

    返回值:

    extend<T> ArrayList<T> <: PrettyPrintable where T <: PrettyPrintable

    extend<T> ArrayList<T> <: PrettyPrintable where T <: PrettyPrintable {
    }
    

    功能:为 ArrayList 类型扩展了 PrettyPrintable 接口。

    父类型:

    func pprint(PrettyPrinter)

    public func pprint(to: PrettyPrinter): PrettyPrinter
    

    功能:将 ArrayList<T> 打印到指定的打印器中。

    参数:

    返回值:

    interface KeyFor

    public interface KeyFor<T> {
        prop name: String
    }
    

    功能: Configuration 中配置型的键的类型。

    可以通过 @UnitestOption 定义自定义配置项键值。内置的 unittest 配置项可以根据命名规则获取。例如,可以通过 KeyRandomSeed.randomSeed 键从 Configuration 中提取 randomSeed

    prop name

    prop name: String
    

    功能:Configuration 中使用的键名称的字符串表示形式。

    类型:String

    class Configuration

    public class Configuration <: ToString {
        public init()
    }
    

    功能:存储 @Configure 宏生成的 unittest 配置数据的对象。Configuration 是一个类似 HashMap 的类,但它的键不是键和值类型,而是 KeyFor> 类型,和任何给定类型的值。

    父类型:

    init()

    public init()
    

    功能:构造一个空的实例。

    func clone()

    public func clone(): Configuration
    

    功能:拷贝一份对象。

    返回值:

    func get<T>(KeyFor<T>)

    public func get<T>(key: KeyFor<T>): ?T
    

    功能:获取 key 对应的值。

    T 为 泛型参数,用于在对象中查找对应类型的值。

    参数:

    • key: KeyFor - 配置项的键值。

    返回值:

    • ?T - 未找到时返回 None,找到对应类型及名称的值时返回 Some<T>(v) 。

    func getByName<T>(name: String): ?T

    public func getByName<T>(name: String): ?T
    

    功能:获取 key 对应的值。

    T 为 泛型参数,用于在对象中查找对应类型的值。

    参数:

    func remove<T>(KeyFor<T>)

    public func remove<T>(key: KeyFor<T>): ?T
    

    功能:删除对应键名称和类型的值。

    参数:

    • key: KeyFor - 配置项的键值。

    返回值:

    • ?T - 当存在该值时返回该值,当不存在时返回 None。

    func removeByName<T>(String)

    public func removeByName<T>(name: String): ?T
    

    功能:删除对应键名称和类型的值。

    参数:

    返回值:

    • ?T - 当存在该值时返回该值,当不存在时返回 None。

    func set<T>(KeyFor<T>, T)

    public func set<T>(key: KeyFor<T>, value: T)
    

    功能:给对应键名称和类型设置值。

    参数:

    • key: KeyFor - 配置项的键值。
    • value: T - 键值。

    func setByName<T>(name: String, value: T)

    public func setByName<T>(name: String, value: T): Unit
    

    功能:给对应键名称和类型设置值。

    参数:

    • name: String - 键名称。
    • value: T - 键值。

    func toString()

    public func toString(): String
    

    功能:该对象的字符化对象,当内部对象未实现 ToString 接口时,输出 '<not printable>' 。

    返回值:

    static func merge(Configuration, Configuration)

    public static func merge(parent: Configuration, child: Configuration): Configuration
    

    功能:合并 child 到 parent 配置中。其中如有同名键值 child 覆盖 parent 。

    参数:

    返回值:

    extend Configuration <: BenchmarkConfig

    extend Configuration <: BenchmarkConfig {}
    

    功能:为 Configuration 扩展 BenchmarkConfig 接口。

    父类型:

    func batchSize(Int64)

    public func batchSize(b: Int64) 
    

    功能:配置性能测试时一个批次的执行次数。

    参数:

    • b: Int64 - 执行次数。

    func batchSize(Range<Int64>)

    public func batchSize(x: Range<Int64>)
    

    功能:配置性能测试时一个批次的执行次数范围。

    参数:

    • b: Range<Int64> - 执行次数范围。

    func explicitGC(ExplicitGcType)

    public func explicitGC(x: ExplicitGcType)
    

    功能:配置性能测试时执行 GC 的方式。

    参数:

    func minBatches(Int64)

    public func minBatches(x: Int64) 
    

    功能:配置性能测试时最少的批次数。

    参数:

    • x: Int64 - 最少的批次数。

    func minDuration(Duration)

    public func minDuration(x: Duration)
    

    功能:配置性能测试时最短的执行时长。

    参数:

    • x: Duration - 最短的执行时长。

    func warmup(Int64)

    public func warmup(x: Int64) 
    

    功能:配置性能测试时预热的秒数。

    参数:

    • x: Int64 - 预热的秒数。

    func warmup(Duration)

    public func warmup(x: Duration)
    

    功能:配置性能测试时预热的时长。

    参数:

    class ConfigurationKey

    abstract sealed class ConfigurationKey <: Equatable<ConfigurationKey> & Hashable {
        public override operator func !=(that: ConfigurationKey)
    }
    

    功能:配置项的键值对象。提供判等及 hashCode 方法。

    父类型:

    func equals(ConfigurationKey)

    protected func equals(that: ConfigurationKey): Bool
    

    功能:判断是否相等。

    参数:

    返回值:

    • Bool - 是否相等。

    func hashCode

    public override func hashCode(): Int64
    

    功能:获取 hashCode 值。

    返回值:

    • Int64 - hashCode 值。

    operator func ==(ConfigurationKey)

    public override operator func ==(that: ConfigurationKey)
    

    功能:判等。

    参数:

    返回值:

    • Bool - 是否相等。

    public override operator func !=(that: ConfigurationKey)

    public override operator func !=(that: ConfigurationKey)
    

    功能:判不等。

    参数:

    返回值:

    • Bool - 是否不相等。

    class PrettyPrinter

    public abstract class PrettyPrinter {
        public PrettyPrinter(let indentationSize!: UInt64 = 4, let startingIndent!: UInt64 = 0)
    }
    

    功能:拥有颜色和对齐、缩进控制的打印器。

    init(UInt64,UInt64)

    public PrettyPrinter(let indentationSize!: UInt64 = 4, let startingIndent!: UInt64 = 0)
    

    功能:构造器。

    参数:

    • indentationSize!: UInt64 - 一个缩进的空格数。
    • startingIndent!: UInt64 - 开头的缩进个数。

    prop isTopLevel

    public prop isTopLevel: Bool
    

    功能:获取是否在打印的缩进顶层。

    类型:Bool 。

    func append(String)

    public func append(text: String): PrettyPrinter
    

    功能:增加一个字符串到打印器中。不支持多行字符串,对多行字符串不支持缩进。

    参数:

    • text: String - 被增加的字符串。

    返回值:

    func append<PP>(PP)where PP <: PrettyPrintable

    public func append<PP>(value: PP): PrettyPrinter where PP <: PrettyPrintable
    

    功能:增加一个实现了 PrettyPrintable 的对象到打印器中。

    参数:

    返回值:

    func appendCentered(String, UInt64)

    public func appendCentered(text: String, space: UInt64): PrettyPrinter
    

    功能:增加一个字符串到打印器中。居中对齐至指定字符数,不足的字符由空格补齐。不支持多行字符串,对多行字符串不支持缩进。

    参数:

    • text: String - 被增加的字符串。
    • space: UInt64 - 对齐的字符数量。

    返回值:

    func appendLeftAligned(String, UInt64)

    public func appendLeftAligned(text: String, space: UInt64): PrettyPrinter
    

    功能:增加一个字符串到打印器中。左对齐至指定字符数,不足的字符由空格补齐。不支持多行字符串,对多行字符串不支持缩进。

    参数:

    • text: String - 被增加的字符串。
    • space: UInt64 - 对齐的字符数量。

    返回值:

    func appendLine(String): PrettyPrinter

    public func appendLine(text: String): PrettyPrinter
    

    功能:增加一个字符串到打印器中,跟着一个换行符。

    参数:

    • text: String - 被增加的字符串。

    返回值:

    func appendLine<PP>(PP) where PP <: PrettyPrintable

    public func appendLine<PP>(value: PP): PrettyPrinter where PP <: PrettyPrintable 
    

    功能:增加一个实现了 PrettyPrintable 的对象到打印器中,跟着一个换行符。

    参数:

    返回值:

    func appendRightAligned(String, UInt64)

    public func appendRightAligned(text: String, space: UInt64): PrettyPrinter
    

    功能:增加一个字符串到打印器中。右对齐至指定字符数。不支持多行字符串,对多行字符串不支持缩进。

    参数:

    • text: String - 被增加的字符串。
    • space: UInt64 - 对齐的字符数量。

    返回值:

    func colored(Color, body: () -> Unit)

    public func colored(color: Color, body: () -> Unit): PrettyPrinter 
    

    功能:对闭包中给打印器增加的字符串指定颜色。 常见的用法如下:

    pp.colored(RED) {
        pp.appendLine("1")
        pp.appendLine("2")
        pp.appendLine("3")
    }
    

    此时字符串 "1" "2" "3" 均被打印为红色。

    参数:

    • color: Color - 指定打印的颜色。
    • body: () -> Unit - 添加字符串的闭包。

    返回值:

    func colored(Color, String)

    public func colored(color: Color, text: String): PrettyPrinter
    

    功能:对给打印器增加的字符串指定颜色。

    参数:

    • color: Color - 指定打印的颜色。
    • text: String - 添加的字符串。

    返回值:

    func customOffset(UInt64, body: () -> Unit)

    public func customOffset(symbols: UInt64, body: () -> Unit): PrettyPrinter 
    

    功能:对闭包中给打印器增加的字符串指定额外缩进的个数。 常见的用法如下:

    pp.customOffset(5) {
        pp.appendLine("1")
        pp.appendLine("2")
        pp.appendLine("3")
    }
    

    此时字符串 "1" "2" "3" 均额外缩进5个字符。

    参数:

    • symbols: UInt64 - 指定缩进个数。
    • body: () -> Unit - 添加字符串的闭包。

    返回值:

    func indent(body: () -> Unit)

    public func indent(body: () -> Unit): PrettyPrinter
    

    功能:对闭包中给打印器增加的字符串指定额外缩进一次。 常见的用法如下:

    pp.indent {
        pp.appendLine("1")
        pp.appendLine("2")
        pp.appendLine("3")
    }
    

    此时字符串 "1" "2" "3" 均额外缩进一次。

    参数:

    • body: () -> Unit - 添加字符串的闭包。

    返回值:

    func indent(UInt64, body: () -> Unit)

    public func indent(indents: UInt64, body: () -> Unit): PrettyPrinter
    

    功能:对闭包中给打印器增加的字符串指定额外缩进指定次数。 常见的用法如下:

    pp.indent(2) {
        pp.appendLine("1")
        pp.appendLine("2")
        pp.appendLine("3")
    }
    

    此时字符串 "1" "2" "3" 均额外缩进2次。

    参数:

    • indents: UInt64 - 指定额外缩进的次数。
    • body: () -> Unit - 添加字符串的闭包。

    返回值:

    func newLine()

    public func newLine(): PrettyPrinter
    

    功能:增加新行。

    返回值:

    func put(String)

    protected func put(s: String): Unit
    

    功能:打印字符串。

    参数:

    • s: String - 需打印的字符串。

    func putNewLine()

    protected open func putNewLine(): Unit
    

    功能:打印新行。

    func setColor(Color)

    protected func setColor(color: Color): Unit
    

    功能:设置颜色。

    参数:

    • color: Color - 指定的颜色。

    class PrettyText

    public class PrettyText <: PrettyPrinter & PrettyPrintable & ToString {
        public init()
        public init(string: String)
    }
    

    功能:类似构造器的类,用于存储打印的输出。 主要用途是中间存储和传递这些值。 实现 PrettyPrinter(可以打印到)和 PrettyPrintable(可以从中打印)

    父类型:

    init()

    public init()
    

    功能:默认构造器,生成一个空的对象。

    init(String)

    public init(string: String)
    

    功能:构造器,生成一个以入参开头的文本构造器。

    参数:

    • string : String - 希望放入打印文本开头的字符串。

    func isEmpty()

    public func isEmpty(): Bool
    

    功能:返回当前构造器是否为空,即未有值传入给构造器。

    返回值:

    • Bool - 未有内容传入时返回 true ,否则返回 false

    func pprint(PrettyPrinter)

    public func pprint(to: PrettyPrinter): PrettyPrinter
    

    功能:打印信息到打印器上。

    参数:

    返回值:

    func toString()

    public func toString(): String
    

    功能:打印文本到字符串上。

    返回值:

    • String - 打印文本的字符串。

    static func of<PP>(PP) where PP <: PrettyPrintable

    public static func of<PP>(pp: PP) where PP <: PrettyPrintable
    

    功能:通过打印从 PrettyPrintable 创建 PrettyText

    参数:

    返回值:

    枚举

    enum Color

    public enum Color <: Equatable<Color> {
        | RED
        | GREEN
        | YELLOW
        | BLUE
        | CYAN
        | MAGENTA
        | GRAY
        | DEFAULT_COLOR;
    }
    

    功能:指定颜色。

    父类型:

    RED

    RED
    

    功能:红色。

    GREEN

    GREEN
    

    功能:绿色。

    YELLOW

    YELLOW
    

    功能:黄色。

    BLUE

    BLUE
    

    功能:蓝色。

    CYAN

    CYAN
    

    功能:青色。

    MAGENTA

    MAGENTA
    

    功能:品红色。

    GRAY

    GRAY
    

    功能:灰色。

    DEFAULT_COLOR

    DEFAULT_COLOR
    

    功能:默认色。

    operator func ==(Color)

    public operator func ==(that: Color): Bool
    

    功能:判断颜色是否相等。

    参数:

    • that: Color - 被对比的颜色。

    返回值:

    • Bool - 相等时返回 true ,否则返回 false

    operator func !=(Color)

    public operator func !=(that: Color): Bool
    

    功能:判断颜色是否不相等。

    参数:

    • that: Color - 被对比的颜色。

    返回值:

    • Bool - 不相等时返回 true ,否则返回 false

    std.unittest.diff 包

    功能介绍

    unittest.diff 为单元测试框架提供了打印差异对比信息所需的 API 。

    API 列表

    接口

    接口名功能
    AssertPrintable提供打印 @Assert/@Expect 的检查结果的方法。

    接口

    interface AssertPrintable

    public interface AssertPrintable<T> {
        prop hasNestedDiff: Bool
        func pprintForAssertion(
            pp: PrettyPrinter, that: T, thisPrefix: String, thatPrefix: String, level: Int64
        ): PrettyPrinter
    }
    

    功能:提供打印 @Assert/@Expect 的检查结果的方法。

    prop hasNestedDiff

    prop hasNestedDiff: Bool
    

    功能:获取是否有嵌套 diff 层级。

    类型:Bool 。

    func pprintForAssertion(PrettyPrinter, T, String, String, Int64)

    func pprintForAssertion(
        pp: PrettyPrinter, that: T, thisPrefix: String, thatPrefix: String, level: Int64
    ): PrettyPrinter
    

    功能:打印 @Assert/@Expect 的检查结果的方法。

    参数:

    • pp: PrettyPrinter - 打印器。
    • that: T - 待打印的信息。
    • thisPrefix: String - 预期内容的前缀。
    • thatPrefix: String - 实际内容的前缀。
    • level: Int64 - 嵌套层级。

    返回值:

    • PrettyPrinter - 打印器。

    std.unittest.prop_test 包

    功能介绍

    unittest.prop_test 为单元测试框架提供了参数化测试所需的类型和方法。

    API 列表

    函数

    函数名功能
    emptyIterable<T>()创建一个空的迭代器。
    random<T>()该函数生成 T 类型的随机数据,其中 T 必须实现接口 Arbitrary<T> 。该函数的返回值是参数化测试的一种参数源。

    接口

    接口名功能
    Arbitrary生成 T 类型随机值的接口。
    IndexAccess通过索引访问元组元素的实用程序接口。
    RandomSource提供 Arbitrary 所需的随机生成基础类型数据的能力。
    Shrink将 T 类型的值缩减到多个“更小”的值。

    类名功能
    Generators包含辅助函数的类,可帮助开发人员编写自己的生成器。
    LazySeq延迟计算的 T 类型值序列。用于在迭代时计算和记忆值。
    ShrinkHelpers提供对元组实现缩减迭代器的方法。

    结构体

    结构体名功能
    Function0Wrapper将闭包封装为结构体。
    TupleWrapper2将闭包封装为结构体。闭包带两个参数。
    TupleWrapper3将闭包封装为结构体。闭包带三个参数。
    TupleWrapper4将闭包封装为结构体。闭包带四个参数。
    TupleWrapper5将闭包封装为结构体。闭包带五个参数。

    函数

    func emptyIterable<T>()

    public func emptyIterable<T>(): Iterable<T>
    

    功能:创建一个空的迭代器。

    返回值:

    func random<T>() where T <: Arbitrary<T>

    public func random<T>(): RandomDataStrategy<T> where T <: Arbitrary<T>
    

    功能:该函数生成 T 类型的随机数据,其中 T 必须实现接口 Arbitrary<T> 。该函数的返回值是参数化测试的一种参数源。

    返回值:

    接口

    interface Arbitrary

    public interface Arbitrary<T> {
        static func arbitrary(random: RandomSource): Generator<T>
    }
    

    功能:生成 T 类型随机值的接口。

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<T>
    

    功能:获取生成 T 类型随机值生成器。

    参数:

    返回值:

    • Generator<T> - 生成 T 类型随机值生成器。

    extend Bool <: Arbitrary<Bool>

    extend Bool <: Arbitrary<Bool>
    

    功能:为 Bool 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Bool>
    

    功能:获取生成 T 类型随机值生成器。

    参数:

    返回值:

    • Generator<Bool> - 生成 Bool 类型随机值生成器。

    extend Float16 <: Arbitrary<Float16>

    extend Float16 <: Arbitrary<Float16>
    

    功能:为 Float16 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Float16>
    

    功能:获取生成 T 类型随机值生成器。

    参数:

    返回值:

    • Generator<Float16> - 生成 Float16 类型随机值生成器。

    extend Float32 <: Arbitrary<Float32>

    extend Float32 <: Arbitrary<Float32>
    

    功能:为 Float32 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Float32>
    

    功能:获取生成 T 类型随机值生成器。

    参数:

    返回值:

    • Generator<Float32> - 生成 Float32 类型随机值生成器。

    extend Float64 <: Arbitrary<Float64>

    extend Float64 <: Arbitrary<Float64>
    

    功能:为 Float64 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Float64>
    

    功能:获取生成 T 类型随机值生成器。

    参数:

    返回值:

    • Generator<Float64> - 生成 Float64 类型随机值生成器。

    extend Int16 <: Arbitrary<Int16>

    extend Int16 <: Arbitrary<Int16>
    

    功能:为 Int16 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Int16>
    

    功能:获取生成 T 类型随机值生成器。

    参数:

    返回值:

    • Generator<Int16> - 生成 Int16 类型随机值生成器。

    extend Int32 <: Arbitrary<Int32>

    extend Int32 <: Arbitrary<Int32>
    

    功能:为 Int32 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Int32>
    

    功能:获取生成 T 类型随机值生成器。

    参数:

    返回值:

    • Generator<Int32> - 生成 Int32 类型随机值生成器。

    extend Int64 <: Arbitrary<Int64>

    extend Int64 <: Arbitrary<Int64>
    

    功能:为 Int64 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Int64>
    

    功能:获取生成 Int64 类型随机值生成器。

    参数:

    返回值:

    • Generator<Int64> - 生成 Int64 类型随机值生成器。

    extend Int8 <: Arbitrary<Int8>

    extend Int8 <: Arbitrary<Int8>
    

    功能:为 Int8 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Int8>
    

    功能:获取生成 Int8 类型随机值生成器。

    参数:

    返回值:

    • Generator<Int8> - 生成 Int8 类型随机值生成器。

    extend IntNative <: Arbitrary<IntNative>

    extend IntNative <: Arbitrary<IntNative>
    

    功能:为 IntNative 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<IntNative>
    

    功能:获取生成 IntNative 类型随机值生成器。

    参数:

    返回值:

    • Generator<IntNative> - 生成 IntNative 类型随机值生成器。

    extend Ordering <: Arbitrary<Ordering>

    extend Ordering <: Arbitrary<Ordering>
    

    功能:为 Ordering 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Ordering>
    

    功能:获取生成 Ordering 类型随机值生成器。

    参数:

    返回值:

    • Generator<Ordering> - 生成 Ordering 类型随机值生成器。

    extend Rune <: Arbitrary<Rune>

    extend Rune <: Arbitrary<Rune>
    

    功能:为 Rune 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Rune>
    

    功能:获取生成 Rune 类型随机值生成器。

    参数:

    返回值:

    • Generator<Rune> - 生成 Rune 类型随机值生成器。

    extend String <: Arbitrary<String>

    extend String <: Arbitrary<String>
    

    功能:为 String 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<String>
    

    功能:获取生成 String 类型随机值生成器。

    参数:

    返回值:

    • Generator<String> - 生成 String 类型随机值生成器。

    extend UInt16 <: Arbitrary<UInt16>

    extend UInt16 <: Arbitrary<UInt16>
    

    功能:为 UInt16 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<UInt16>
    

    功能:获取生成 UInt16 类型随机值生成器。

    参数:

    返回值:

    • Generator<UInt16> - 生成 UInt16 类型随机值生成器。

    extend UInt32 <: Arbitrary<UInt32>

    extend UInt32 <: Arbitrary<UInt32>
    

    功能:为 UInt32 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<UInt32>
    

    功能:获取生成 UInt32 类型随机值生成器。

    参数:

    返回值:

    • Generator<UInt32> - 生成 UInt32 类型随机值生成器。

    extend UInt64 <: Arbitrary<UInt64>

    extend UInt64 <: Arbitrary<UInt64>
    

    功能:为 UInt64 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<UInt64>
    

    功能:获取生成 UInt64 类型随机值生成器。

    参数:

    返回值:

    • Generator<UInt64> - 生成 UInt64 类型随机值生成器。

    extend UInt8 <: Arbitrary<UInt8>

    extend UInt8 <: Arbitrary<UInt8>
    

    功能:为 UInt8 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<UInt8>
    

    功能:获取生成 UInt8 类型随机值生成器。

    参数:

    返回值:

    • Generator<UInt8> - 生成 UInt8 类型随机值生成器。

    extend UIntNative <: Arbitrary<UIntNative>

    extend UIntNative <: Arbitrary<UIntNative>
    

    功能:为 UIntNative 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<UIntNative>
    

    功能:获取生成 UIntNative 类型随机值生成器。

    参数:

    返回值:

    • Generator<UIntNative> - 生成 UIntNative 类型随机值生成器。

    extend Unit <: Arbitrary<Unit>

    extend Unit <: Arbitrary<Unit>
    

    功能:为 Unit 实现了 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Unit>
    

    功能:获取生成 Unit 类型随机值生成器。

    参数:

    返回值:

    • Generator<Unit> - 生成 Unit 类型随机值生成器。

    extend<T> Array<T> <: Arbitrary<Array<T>> where T <: Arbitrary<T>

    extend<T> Array<T> <: Arbitrary<Array<T>> where T <: Arbitrary<T>
    

    功能:为 Array<T> 实现了 Arbitrary<Array<T>> 接口,且 T 需实现 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<Array<T>>
    

    功能:获取生成 Array<T> 类型随机值生成器。

    参数:

    返回值:

    • Generator<Array<T>> - 生成 Array<T> 类型随机值生成器。

    extend<T> Option<T> <: Arbitrary<Option<T>> where T <: Arbitrary<T>

    extend<T> option<T> <: Arbitrary<Option<T>> where T <: Arbitrary<T>
    

    功能:为 Option<T> 实现了 Arbitrary<Option<T>> 接口,且 T 需实现 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<option<T>>
    

    功能:获取生成 option<T> 类型随机值生成器。

    参数:

    返回值:

    • Generator<option<T>> - 生成 option<T> 类型随机值生成器。

    extend<T> ArrayList<T> <: Arbitrary<ArrayList<T>> where T <: Arbitrary<T>

    extend<T> ArrayList<T> <: Arbitrary<ArrayList<T>> where T <: Arbitrary<T> 
    

    功能:为 ArrayList<T> 实现了 Arbitrary 接口,且 T 需实现 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<ArrayList<T>>
    

    功能:获取生成 ArrayList<T> 类型随机值生成器。

    参数:

    返回值:

    • Generator<ArrayList<T>> - 生成 ArrayList<T> 类型随机值生成器。

    extend<T> HashSet<T> <: Arbitrary<HashSet<T>> where T <: Arbitrary<T>

    extend<T> HashSet<T> <: Arbitrary<HashSet<T>> where T <: Arbitrary<T>
    

    功能:为 HashSet<T> 实现了 Arbitrary 接口,且 T 需实现 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<HashSet<T>>
    

    功能:获取生成 HashSet<T> 类型随机值生成器。

    参数:

    返回值:

    • Generator<HashSet<T>> - 生成 HashSet<T> 类型随机值生成器。

    extend<K, V> HashMap<K, V> <: Arbitrary<HashMap<K, V>> where K <: Arbitrary<K>, V <: Arbitrary<V>

    extend<K, V> HashMap<K, V> <: Arbitrary<HashMap<K, V>> where K <: Arbitrary<K>, V <: Arbitrary<V> 
    

    功能:为 HashMap<T> 实现了 Arbitrary 接口,且 T 需实现 Arbitrary<T> 接口。

    父类型:

    static func arbitrary(RandomSource)

    static func arbitrary(random: RandomSource): Generator<HashMap<K, V>>
    

    功能:获取生成 HashMap<K, V> 类型随机值生成器。

    参数:

    返回值:

    • Generator<HashMap<K, V>> - 生成 HashMap<K, V> 类型随机值生成器。

    interface IndexAccess

    public interface IndexAccess {
        func getElementAsAny(index: Int64): ?Any
    }
    

    功能:通过索引访问元组元素的实用程序接口。

    func getElementAsAny(Int64)

    func getElementAsAny(index: Int64): ?Any
    

    功能:通过索引访问元组元素。

    参数:

    • index: Int64 - 索引值。

    返回值:

    • ?Any - 元素值。若未获取到则为 None

    interface RandomSource

    public interface RandomSource {
        func nextBool(): Bool
        func nextInt8(): Int8
        func nextInt16(): Int16
        func nextInt32(): Int32
        func nextInt64(): Int64
        func nextInt8(max: Int8): Int8
        func nextInt16(max: Int16): Int16
        func nextInt32(max: Int32): Int32
        func nextInt64(max: Int64): Int64
        func nextUInt8(): UInt8
        func nextUInt16(): UInt16
        func nextUInt32(): UInt32
        func nextUInt64(): UInt64
        func nextUInt8(max: UInt8): UInt8
        func nextUInt16(max: UInt16): UInt16
        func nextUInt32(max: UInt32): UInt32
        func nextUInt64(max: UInt64): UInt64
        func nextFloat16(): Float16
        func nextFloat32(): Float32
        func nextFloat64(): Float64
        func nextGaussianFloat64(mean!: Float64, sigma!: Float64): Float64
        func nextIntNative(): IntNative
        func nextUIntNative(): UIntNative
    
        func suggestUInt8(): UInt8 
        func suggestUInt16(): UInt16
        func suggestUInt32(): UInt32
        func suggestUInt64(): UInt64
        func suggestUIntNative(): UIntNative
        func suggestInt8(): Int8 
        func suggestInt16(): Int16
        func suggestInt32(): Int32 
        func suggestInt64(): Int64 
        func suggestIntNative(): IntNative 
        func suggestFloat16(): Float16
        func suggestFloat32(): Float32 
        func suggestFloat64(): Float64 
        func suggestBool(): Bool
        func suggestRune(): Rune
    }
    

    功能:提供 Arbitrary 所需的随机生成基础类型数据的能力。

    func nextBool()

    public open func nextBool(): Bool
    

    功能:获取一个布尔类型的伪随机值。

    返回值:

    • Bool - 一个 Bool 类型的伪随机数。

    func nextFloat16()

    public open func nextFloat16(): Float16
    

    功能:获取一个 Float16 类型的伪随机数,其范围为 [0.0, 1.0)。

    返回值:

    func nextFloat32()

    public open func nextFloat32(): Float32
    

    功能:获取一个 Float32 类型的伪随机数,其范围为 [0.0, 1.0)。

    返回值:

    func nextFloat64()

    public open func nextFloat64(): Float64
    

    功能:获取一个 Float64 类型的伪随机数,其范围为 [0.0, 1.0)。

    返回值:

    func nextGaussianFloat64(Float64, Float64)

    public func nextGaussianFloat64(mean!: Float64 = 0.0, sigma!: Float64 = 1.0): Float64
    

    功能:获取一个 Float64 类型的符合指定均值与标准差的高斯分布的随机数。

    默认获取一个 Float64 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数。其中均值是期望值,可解释为位置参数,决定了分布的位置,标准差可解释为尺度参数,决定了分布的幅度。此函数调用了函数 nextGaussianFloat64Implement 得到返回值,所以当子类继承 Random 并覆写 nextGaussianFloat64Implement 函数时,调用子类的该函数将会返回覆写的函数的返回值。

    参数:

    • mean!: Float64 - 均值,默认值 0.0。
    • sigma!: Float64 - 标准差,默认值 1.0。

    返回值:

    func nextInt16()

    public open func nextInt16(): Int16
    

    功能:获取一个 Int16 类型的伪随机数。

    返回值:

    func nextInt16(Int16)

    public open func nextInt16(upper: Int16): Int16
    

    功能:获取一个范围在 [0, upper) 的 Int16 类型的伪随机数。

    参数:

    • upper: Int16 - 表示生成的伪随机数范围上界(不包括 upper),取值范围 (0, Int16.Max]。

    返回值:

    异常:

    func nextInt32()

    public open func nextInt32(): Int32
    

    功能:获取一个 Int32 类型的伪随机数。

    返回值:

    func nextInt32(Int32)

    public open func nextInt32(upper: Int32): Int32
    

    功能:获取一个范围在 [0, upper) 的 Int32 类型的伪随机数。

    参数:

    • upper: Int32 - 表示生成的伪随机数范围上界(不包括 upper),取值范围 (0, Int32.Max]。

    返回值:

    异常:

    func nextInt64()

    public open func nextInt64(): Int64
    

    功能:获取一个 Int64 类型的伪随机数。

    返回值:

    func nextInt64(Int64)

    public open func nextInt64(upper: Int64): Int64
    

    功能:获取一个范围在 [0, upper) 的 Int64 类型的伪随机数。

    参数:

    • upper: Int64 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, Int64.Max]。

    返回值:

    异常:

    func nextInt8()

    public open func nextInt8(): Int8
    

    功能:获取一个 Int8 类型的伪随机数。

    返回值:

    • Int8 - 一个 Int8 类型的伪随机数。

    func nextInt8(Int8): Int8

    public open func nextInt8(upper: Int8): Int8
    

    功能:获取一个范围在 [0, upper) 的 Int8 类型的伪随机数。

    参数:

    • upper: Int8 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, Int8.Max]。

    返回值:

    • Int8 - 一个 Int8 类型的伪随机数。

    异常:

    func nextIntNative():IntNative

    public func nextIntNative(): IntNative
    

    功能:获取一个 IntNative 类型的伪随机数。

    返回值:

    func nextUInt16()

    public open func nextUInt16(): UInt16
    

    功能:获取一个 UInt16 类型的伪随机数。

    返回值:

    func nextUInt16(UInt16)

    public open func nextUInt16(upper: UInt16): UInt16
    

    功能:获取一个范围在 [0, upper) 的 UInt16 类型的伪随机数。

    参数:

    • upper: UInt16 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, UInt16.Max]。

    返回值:

    异常:

    func nextUInt32()

    public open func nextUInt32(): UInt32
    

    功能:获取一个 UInt32 类型的伪随机数。

    返回值:

    func nextUInt32(UInt32)

    public open func nextUInt32(upper: UInt32): UInt32
    

    功能:获取一个范围在 [0, upper) 的 UInt32 类型的伪随机数。

    参数:

    • upper: UInt32 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, UInt32.Max]。

    返回值:

    异常:

    func nextUInt64()

    public open func nextUInt64(): UInt64
    

    功能:获取一个 UInt64 类型的伪随机数。

    返回值:

    func nextUInt64(UInt64)

    public open func nextUInt64(upper: UInt64): UInt64
    

    功能:获取一个范围在 [0, upper) 的 UInt64 类型的伪随机数。

    参数:

    • upper: UInt64 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, UInt64.Max]。

    返回值:

    异常:

    func nextUInt8()

    public open func nextUInt8(): UInt8
    

    功能:获取一个 UInt8 类型的伪随机数。

    返回值:

    func nextUInt8(UInt8)

    public open func nextUInt8(upper: UInt8): UInt8
    

    功能:获取一个范围在 [0, upper) 的 UInt8 类型的伪随机数。

    参数:

    • upper: UInt8 - 生成的伪随机数范围上界(不包括 upper),取值范围 (0, UInt8.Max]。

    返回值:

    异常:

    func nextUIntNative():UIntNative

    public func nextUIntNative(): UIntNative
    

    功能:获取一个 UIntNative 类型的伪随机数。

    返回值:

    func suggestBool()

    public open func suggestBool(): Bool
    

    功能:获取一个布尔类型的伪随机值。

    返回值:

    • Bool - 一个 Bool 类型的伪随机数。

    func suggestRune()

    public open func suggestRune(): Rune
    

    功能:获取一个 Rune 类型的伪随机值。

    返回值:

    • Rune - 一个 Rune 类型的伪随机数。

    func suggestFloat16()

    public open func suggestFloat16(): Float16
    

    功能:获取一个 Float16 类型的伪随机数,其范围为 [0.0, 1.0)。

    返回值:

    func suggestFloat32()

    public open func suggestFloat32(): Float32
    

    功能:获取一个 Float32 类型的伪随机数,其范围为 [0.0, 1.0)。

    返回值:

    func suggestFloat64()

    public open func suggestFloat64(): Float64
    

    功能:获取一个 Float64 类型的伪随机数,其范围为 [0.0, 1.0)。

    返回值:

    func suggestInt16()

    public open func suggestInt16(): Int16
    

    功能:获取一个 Int16 类型的伪随机数。

    返回值:

    func suggestInt32()

    public open func suggestInt32(): Int32
    

    功能:获取一个 Int32 类型的伪随机数。

    返回值:

    func suggestInt64()

    public open func suggestInt64(): Int64
    

    功能:获取一个 Int64 类型的伪随机数。

    返回值:

    func suggestInt8()

    public open func suggestInt8(): Int8
    

    功能:获取一个 Int8 类型的伪随机数。

    返回值:

    • Int8 - 一个 Int8 类型的伪随机数。

    func suggestIntNative():IntNative

    public func suggestIntNative(): IntNative
    

    功能:获取一个 IntNative 类型的伪随机数。

    返回值:

    func suggestUInt16()

    public open func suggestUInt16(): UInt16
    

    功能:获取一个 UInt16 类型的伪随机数。

    返回值:

    func suggestUInt32()

    public open func suggestUInt32(): UInt32
    

    功能:获取一个 UInt32 类型的伪随机数。

    返回值:

    func suggestUInt64()

    public open func suggestUInt64(): UInt64
    

    功能:获取一个 UInt64 类型的伪随机数。

    返回值:

    func suggestUInt8()

    public open func suggestUInt8(): UInt8
    

    功能:获取一个 UInt8 类型的伪随机数。

    返回值:

    func suggestUIntNative():UIntNative

    public func suggestUIntNative(): UIntNative
    

    功能:获取一个 UIntNative 类型的伪随机数。

    返回值:

    interface Shrink<T>

    public interface Shrink<T> {
        func shrink(): Iterable<T>
    }
    

    功能:将 T 类型的值缩减到多个“更小”的值。

    func shrink()

    func shrink(): Iterable<T>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<T> - 一组可能的“较小”值的迭代器。

    extend Bool <: Shrink<Bool>

    extend Bool <: Shrink<Bool>
    

    功能:为 Bool 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<Bool>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<Bool> - 一组可能的“较小”值的迭代器。

    extend Int16 <: Shrink<Int16>

    extend Int16 <: Shrink<Int16>
    

    功能:为 Int16 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<Int16>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<Int16> - 一组可能的“较小”值的迭代器。

    extend Int32 <: Shrink<Int32>

    extend Int32 <: Shrink<Int32>
    

    功能:为 Int32 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<Int32>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<Int32> - 一组可能的“较小”值的迭代器。

    extend Int64 <: Shrink<Int64>

    extend Int64 <: Shrink<Int64>
    

    功能:为 Int64 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<Int64>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<Int64> - 一组可能的“较小”值的迭代器。

    extend Int8 <: Shrink<Int8>

    extend Int8 <: Shrink<Int8>
    

    功能:为 Int8 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<Int8>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<Int8> - 一组可能的“较小”值的迭代器。

    extend IntNative <: Shrink<IntNative>

    extend IntNative <: Shrink<IntNative>
    

    功能:为 IntNative 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<IntNative>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<IntNative> - 一组可能的“较小”值的迭代器。

    extend Rune <: Shrink<Rune>

    extend Rune <: Shrink<Rune>
    

    功能:为 Rune 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<Rune>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<Rune> - 一组可能的“较小”值的迭代器。

    extend String <: Shrink<String>

    extend String <: Shrink<String>
    

    功能:为 String 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<String>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<String> - 一组可能的“较小”值的迭代器。

    extend UInt16 <: Shrink<UInt16>

    extend UInt16 <: Shrink<UInt16>
    

    功能:为 UInt16 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<UInt16>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<UInt16> - 一组可能的“较小”值的迭代器。

    extend UInt32 <: Shrink<UInt32>

    extend UInt32 <: Shrink<UInt32>
    

    功能:为 UInt32 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<UInt32>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<UInt32> - 一组可能的“较小”值的迭代器。

    extend UInt64 <: Shrink<UInt64>

    extend UInt64 <: Shrink<UInt64>
    

    功能:为 UInt64 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<UInt64>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<UInt64> - 一组可能的“较小”值的迭代器。

    extend UInt8 <: Shrink<UInt8>

    extend UInt8 <: Shrink<UInt8>
    

    功能:为 UInt8 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<UInt8>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<UInt8> - 一组可能的“较小”值的迭代器。

    extend UIntNative <: Shrink<UIntNative>

    extend UIntNative <: Shrink<UIntNative>
    

    功能:为 UIntNative 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<UIntNative>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<UIntNative> - 一组可能的“较小”值的迭代器。

    extend Unit <: Shrink<Unit>

    extend Unit <: Shrink<Unit>
    

    功能:为 Unit 实现了 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<Unit>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<Unit> - 一组可能的“较小”值的迭代器。

    extend<T> Array<T> <: Shrink<Array<T>> where T <: Shrink<T>

    extend<T> Array<T> <: Shrink<Array<T>> where T <: Shrink<T>
    

    功能:为 Array<T> 实现了 Shrink<Array<T>> 接口,且 T 需实现 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<Array<T>>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<Array<T>> - 一组可能的“较小”值的迭代器。

    extend<T> Option<T> <: Shrink<Option<T>> where T <: Shrink<T>

    extend<T> Option<T> <: Shrink<Option<T>> where T <: Shrink<T>
    

    功能:为 Option<T> 实现了 Shrink<Option<T>> 接口,且 T 需实现 Shrink<T> 接口。

    父类型:

    func shrink()

    func shrink(): Iterable<Option<T>>
    

    功能:将该值缩小为一组可能的“较小”值。

    返回值:

    • Iterable<Option<T>> - 一组可能的“较小”值的迭代器。

    class Generators

    public class Generators {}
    

    功能:包含辅助函数的类,可帮助开发人员编写自己的生成器。

    static func generate<T>(() -> T)

    public static func generate<T>(body: () -> T): Generator<T> 
    

    功能:通过重复调用函数生成值的生成器。

    参数:

    • body: () -> T - 被调用的生成器闭包。

    返回值:

    static func iterable<T>(RandomSource, Array<T>)

    public static func iterable<T>(random: RandomSource, collection: Array<T>): Generator<T>
    

    功能:通过从数组中随机选取来生成值的生成器。

    参数:

    • random: RandomSource - 随机数。
    • collection: Array<T> - 被选取数字的数组。

    返回值:

    static func lookup<T>(RandomSource) where T <: Arbitrary<T>

    public static func lookup<T>(random: RandomSource): Generator<T> where T <: Arbitrary<T>
    

    功能:通过 T 的 Arbitrary 实例提供的生成器。

    参数:

    返回值:

    static func mapped<T, R>(RandomSource,(T) -> R) where T <: Arbitrary<T>

    public static func mapped<T, R>(random: RandomSource, body: (T) -> R): Generator<R> where T <: Arbitrary<T>
    

    功能:获取 T 的 Arbitrary 实例提供的生成器,并使用函数体生成 R 类型的值。

    参数:

    • random: RandomSource - 随机数。
    • body: (T) -> R - 生成 R 类型的值。

    返回值:

    static func mapped<T1, T2, R>(RandomSource, (T1, T2) -> R) where T1 <: Arbitrary<T1>, T2 <: Arbitrary<T2>

     public static func mapped<T1, T2, R>(random: RandomSource, body: (T1, T2) -> R): Generator<R> where T1 <: Arbitrary<T1>, T2 <: Arbitrary<T2>
    

    功能:获取 T1,T2 的 Arbitrary 实例提供的生成器,并使用函数体生成 R 类型的值。

    参数:

    • random: RandomSource - 随机数。
    • body: (T1, T2) -> R - 生成 R 类型的值。

    返回值:

    static func mapped<T1, T2, T3, R>(RandomSource, (T1, T2, T3) -> R) where T1 <: Arbitrary<T1>, T2 <: Arbitrary<T2>, T3 <: Arbitrary<T3>

    public static func mapped<T1, T2, T3, R>(random: RandomSource, body: (T1, T2, T3) -> R): Generator<R>
                where T1 <: Arbitrary<T1>, T2 <: Arbitrary<T2>, T3 <: Arbitrary<T3> 
    

    功能:获取 T1,T2,T3 的 Arbitrary 实例提供的生成器,并使用函数体生成 R 类型的值。

    参数:

    • random: RandomSource - 随机数。
    • body: (T1, T2,T3) -> R - 生成 R 类型的值。

    返回值:

    static func mapped<T1, T2, T3, T4, R>(RandomSource, (T1, T2, T3, T4) -> R) where T1 <: Arbitrary<T1>, T2 <: Arbitrary<T2>, T3 <: Arbitrary<T3>, T4 <: Arbitrary<T4>

    public static func mapped<T1, T2, T3, T4, R>(random: RandomSource, body: (T1, T2, T3, T4) -> R): Generator<R>
                where T1 <: Arbitrary<T1>, T2 <: Arbitrary<T2>, T3 <: Arbitrary<T3>, T4 <: Arbitrary<T4>
    

    功能:获取 T1,T2,T3,T4 的 Arbitrary 实例提供的生成器,并使用函数体生成 R 类型的值。

    参数:

    • random: RandomSource - 随机数。
    • body: (T1, T2,T3,T4) -> R - 生成 R 类型的值。

    返回值:

    static func pick<T>(RandomSource, Array<Generator<T>>)

    public static func pick<T>(random: RandomSource, variants: Array<Generator<T>>): Generator<T> 
    

    功能:通过从生成器数组中随机选取来生成值的生成器。

    参数:

    返回值:

    static func single<T>(T)

    public static func single<T>(value: T): Generator<T>
    

    功能:生成器始终返回同一个值。

    参数:

    • value: T - 生成器返回的值。

    返回值:

    static func weighted<T>(RandomSource, Array<(UInt64, Generator<T>)>)

    public static func weighted<T>(random: RandomSource, variants: Array<(UInt64, Generator<T>)>): Generator<T>
    

    功能:通过从成对数组(权重、生成器)中随机选取来生成值的生成器。

    参数:

    • random: RandomSource - 随机数。
    • variants: Array<(UInt64, Generator<T>)> - 数组(权重、生成器)。

    返回值:

    class LazySeq

    public class LazySeq<T> <: Iterable<T> {
        public init()
        public init(element: T) 
    }
    

    功能:延迟计算的 T 类型值序列。用于在迭代时计算和记忆值。 这是完全不可变的,每次操作都会产生一个新的序列。

    父类型:

    init()

    public init()
    

    功能:构造器。

    init(T)

    public init(element: T) 
    

    功能:构造器。

    参数:

    • element: T - 初始元素。

    func append(T)

    public func append(element: T): LazySeq<T>
    

    功能:增加一个元素。

    参数:

    • element: T - 被增加的元素。

    返回值:

    • LazySeq<T> - 增加元素后的序列。

    func concat(LazySeq<T>)

    public func concat(other: LazySeq<T>): LazySeq<T>
    

    功能:增加一个序列到此序列中。复杂度为 O(1) 。

    参数:

    • other: LazySeq<T> - 被增加的序列。

    返回值:

    • LazySeq<T> - 增加元素后的序列。

    func iterator()

    public func iterator(): Iterator<T>
    

    功能:实现序列的迭代器。

    返回值:

    func map<U>((T) -> U)

    public func map<U>(body: (T) -> U): [LazySeq](#class-lazyseq)<U> 
    

    功能:对序列中的每个元素执行闭包处理。

    参数:

    • body: (T) -> U - 对每个元素执行的闭包。

    返回值:

    • LazySeq<U> - 处理后的序列。

    func mixWith(LazySeq<T>)

    public func mixWith(other: LazySeq<T>): LazySeq<T>
    

    功能:将新序列穿插进原序列中。 例如:{1,2,3,4}.mixWith({5,6,7}) -> {1,5,2,6,3,7,4}

    参数:

    • other: LazySeq<T> - 待插入的序列。

    返回值:

    • LazySeq<U> - 处理后的序列。

    func prepend(T)

    public func prepend(element: T): LazySeq<T>
    

    功能:将新序列插进原序列的开头。

    参数:

    • other: LazySeq<T> - 待插入的序列。

    返回值:

    • LazySeq<U> - 处理后的序列。

    static func mix(LazySeq<T>,LazySeq<T>)

    public static func mix(l1: LazySeq<T>, l2: LazySeq<T>) 
    

    功能:两个序列穿插混合成一个。 例如:mix({1,2,3,4}, {5,6,7}) -> {1,5,2,6,3,7,4}

    参数:

    • l1: LazySeq<T> - 待穿插的序列。
    • l2: LazySeq<T> - 待穿插的序列。

    返回值:

    • LazySeq<U> - 处理后的序列。

    static func mix(LazySeq<T>,LazySeq<T>,LazySeq<T>)

    public static func mix(l1: LazySeq<T>, l2: LazySeq<T>, l3: LazySeq<T>) 
    

    功能:三个序列穿插混合成一个。

    参数:

    • l1: LazySeq<T> - 待穿插的序列。
    • l2: LazySeq<T> - 待穿插的序列。
    • l3: LazySeq<T> - 待穿插的序列。

    返回值:

    • LazySeq<U> - 处理后的序列。

    static func mix(LazySeq<T>,LazySeq<T>,LazySeq<T>,LazySeq<T>)

    public static func mix(l1: LazySeq<T>, l2: LazySeq<T>, l3: LazySeq<T>, l4: LazySeq<T>) 
    

    功能:四个序列穿插混合成一个。

    参数:

    • l1: LazySeq<T> - 待穿插的序列。
    • l2: LazySeq<T> - 待穿插的序列。
    • l3: LazySeq<T> - 待穿插的序列。
    • l4: LazySeq<T> - 待穿插的序列。

    返回值:

    • LazySeq<U> - 处理后的序列。

    static func mix(LazySeq<T>,LazySeq<T>,LazySeq<T>,LazySeq<T>,LazySeq<T>)

    public static func mix(l1: LazySeq<T>, l2: LazySeq<T>, l3: LazySeq<T>, l4: LazySeq<T>, l5: LazySeq<T>) 
    

    功能:五个序列穿插混合成一个。

    参数:

    • l1: LazySeq<T> - 待穿插的序列。
    • l2: LazySeq<T> - 待穿插的序列。
    • l3: LazySeq<T> - 待穿插的序列。
    • l4: LazySeq<T> - 待穿插的序列。
    • l5: LazySeq<T> - 待穿插的序列。

    返回值:

    • LazySeq<U> - 处理后的序列。

    static func of(Iterable<T>)

    public static func of(iterable: Iterable<T>)
    

    功能:从迭代器构造一个序列。

    参数:

    • iterable: Iterable<T> - 待处理的迭代器。

    返回值:

    • LazySeq<U> - 处理后的序列。

    static func of(Array<T>)

    public static func of(array: Array<T>)
    

    功能:从数组构造一个序列。

    参数:

    • array: Array<T> - 待处理的数组。

    返回值:

    • LazySeq<U> - 处理后的序列。

    class ShrinkHelpers

    public class ShrinkHelpers {}
    

    功能:提供对元组实现缩减迭代器的方法。

    static func shrinkTuple<T0, T1>((T0, T1),Iterable<T0>,Iterable<T1>)

    public static func shrinkTuple<T0, T1>(
        tuple: (T0, T1),
        t0: Iterable<T0>,
        t1: Iterable<T1>
    ): Iterable<(T0, T1)>
    

    功能:实现元组的缩减迭代器。

    参数:

    • tuple: (T0, T1) - 被缩减的元组。
    • t0: Iterable<T0> - 第一个元组成员的缩减迭代器。
    • t1: Iterable<T1> - 第二个元组成员的缩减迭代器。

    返回值:

    • Iterable<(T0, T1)> - 元组缩减迭代器。

    static func shrinkTuple<T0, T1, T2>((T0, T1, T2),Iterable<T0>,Iterable<T1>,Iterable<T2>)

    public static func shrinkTuple<T0, T1, T2>(
        tuple: (T0, T1, T2),
        t0: Iterable<T0>,
        t1: Iterable<T1>,
        t2: Iterable<T2>
    ): Iterable<(T0, T1, T2)> 
    

    功能:实现元组的缩减迭代器。

    参数:

    • tuple: (T0, T1, T2) - 被缩减的元组。
    • t0: Iterable<T0> - 第一个元组成员的缩减迭代器。
    • t1: Iterable<T1> - 第二个元组成员的缩减迭代器。
    • t2: Iterable<T2> - 第三个元组成员的缩减迭代器。

    返回值:

    • Iterable<(T0, T1, T2)> - 元组缩减迭代器。

    static func shrinkTuple<T0, T1, T2, T3>((T0, T1, T2, T3),Iterable<T0>,Iterable<T1>,Iterable<T2>,Iterable<T3>)

    public static func shrinkTuple<T0, T1, T2, T3>(
        tuple: (T0, T1, T2, T3),
        t0: Iterable<T0>,
        t1: Iterable<T1>,
        t2: Iterable<T2>,
        t3: Iterable<T3>
    ): Iterable<(T0, T1, T2, T3)> 
    

    功能:实现元组的缩减迭代器。

    参数:

    • tuple: (T0, T1, T2, T3) - 被缩减的元组。
    • t0: Iterable<T0> - 第一个元组成员的缩减迭代器。
    • t1: Iterable<T1> - 第二个元组成员的缩减迭代器。
    • t2: Iterable<T2> - 第三个元组成员的缩减迭代器。
    • t3: Iterable<T3> - 第四个元组成员的缩减迭代器。

    返回值:

    • Iterable<(T0, T1, T2,T3)> - 元组缩减迭代器。

    static func shrinkTuple<T0, T1, T2, T3, T4>((T0, T1, T2, T3, T4),Iterable<T0>,Iterable<T1>,Iterable<T2>,Iterable<T3>,Iterable<T4>)

    public static func shrinkTuple<T0, T1, T2, T3, T4>(
        tuple: (T0, T1, T2, T3, T4),
        t0: Iterable<T0>,
        t1: Iterable<T1>,
        t2: Iterable<T2>,
        t3: Iterable<T3>,
        t4: Iterable<T4>
    ): Iterable<(T0, T1, T2, T3, T4)> 
    

    功能:实现元组的缩减迭代器。

    参数:

    • tuple: (T0, T1, T2, T3, T4) - 被缩减的元组。
    • t0: Iterable<T0> - 第一个元组成员的缩减迭代器。
    • t1: Iterable<T1> - 第二个元组成员的缩减迭代器。
    • t2: Iterable<T2> - 第三个元组成员的缩减迭代器。
    • t3: Iterable<T3> - 第四个元组成员的缩减迭代器。
    • t4: Iterable<T4> - 第五个元组成员的缩减迭代器。

    返回值:

    • Iterable<(T0, T1, T2,T3,T4)> - 元组缩减迭代器。

    结构体

    struct Function0Wrapper<R>

    public struct Function0Wrapper<R> {
        public Function0Wrapper(public let function: () -> R)
    }
    

    功能:将闭包封装为结构体。

    init(() -> R)

    public Function0Wrapper(public let function: () -> R)
    

    功能:构造器。

    参数:

    • function: () -> R - 被封装的闭包。

    operator func ()()

    public operator func () (): R
    

    功能:调用操作符函数。将闭包转换为结构体的调用操作符函数。

    返回值:

    • R - 同闭包的返回值。

    extend<R> Function0Wrapper<R> <: Arbitrary<Function0Wrapper<R>> where R <: Arbitrary<R>

    extend<R> Function0Wrapper<R> <: Arbitrary<Function0Wrapper\<R>> where R <: Arbitrary<R>
    

    功能:为 Function0Wrapper 扩展 Arbitrary 实现。

    父类型:

    static func arbitrary(RandomSource)

    public static func arbitrary(random: RandomSource): Generator<Function0Wrapper<R>>
    

    功能:获取生成 Function0Wrapper<R> 类型随机值生成器。

    struct TupleWrapper2<T0, T1>

    public struct TupleWrapper2<T0, T1> {
        public TupleWrapper2(public let tuple: (T0, T1))
    }
    

    功能:将闭包封装为结构体。闭包带两个参数。

    init((T0, T1))

    public TupleWrapper2(public let tuple: (T0, T1))
    

    功能:构造器。

    参数:

    • tuple: (T0, T1) - 闭包的两个入参。

    func apply<R>(f: (T0, T1) -> R)

    public func apply<R>(f: (T0, T1) -> R): R
    

    功能:执行闭包函数。

    参数:

    • f: (T0, T1) -> R - 待执行的闭包。

    返回值:

    • R - 闭包的执行结果。

    extend<T0, T1> TupleWrapper2<T0, T1> <: ToString

    extend<T0, T1> TupleWrapper2<T0, T1> <: ToString
    

    功能:为 TupleWrapper2 扩展 ToString 实现。

    父类型:

    func toString()

    public func toString()
    

    功能:TupleWrapper2 的字符串表达。

    extend<T0, T1> TupleWrapper2<T0, T1> <: Equatable<TupleWrapper2<T0, T1>>

    extend<T0, T1> TupleWrapper2<T0, T1> <: Equatable<TupleWrapper2<T0, T1>>
    

    功能:为 TupleWrapper2 扩展 Equatable 实现。

    父类型:

    operator func ==(TupleWrapper2<T0, T1>)

    public operator func ==(other: TupleWrapper2<T0, T1>)
    

    功能:比较两个二元元组。

    参数:

    返回值:

    • Bool - 相等时返回 true ,否则返回 false

    operator func !=(TupleWrapper2<T0, T1>)

    public operator func !=(other: TupleWrapper2<T0, T1>)
    

    功能:比较两个二元元组。

    参数:

    返回值:

    • Bool - 不相等时返回 true ,否则返回 false

    extend<T0, T1> TupleWrapper2<T0, T1> <: IndexAccess

    extend<T0, T1> TupleWrapper2<T0, T1> <: IndexAccess
    

    功能:为 TupleWrapper2 扩展 IndexAccess 实现。

    父类型:

    func getElementAsAny(Int64)

    public func getElementAsAny(index: Int64): ?Any
    

    功能:按索引获取元组内的值。

    参数:

    • index: Int64 - 索引值。

    返回值:

    • ?Any - 获取到的元组内的值。索引不合法时返回 None

    extend<T0, T1> TupleWrapper2<T0, T1> <: Arbitrary<TupleWrapper2<T0, T1>> where T0 <: Arbitrary<T0>,T1 <: Arbitrary<T1>

    extend<T0, T1> TupleWrapper2<T0, T1> <: Arbitrary<TupleWrapper2<T0, T1>> where T0 <: Arbitrary<T0>,T1 <: Arbitrary<T1>
    

    功能:为 TupleWrapper2 扩展 Arbitrary 实现。

    父类型:

    static func arbitrary(RandomSource)

    public static func arbitrary(random: RandomSource): Generator<TupleWrapper2<T0, T1>>
    

    功能:获取生成 TupleWrapper2<T0, T1> 类型随机值生成器。

    struct TupleWrapper3<T0, T1, T2>

    public struct TupleWrapper3<T0, T1, T2> {
        public TupleWrapper3(public let tuple: (T0, T1,T2))
    }
    

    功能:将闭包封装为结构体。闭包带两个参数。

    init((T0, T1,T2))

    public TupleWrapper3(public let tuple: (T0, T1,T2))
    

    功能:构造器。

    参数:

    • tuple: (T0, T1,T2) - 闭包的两个入参。

    func apply<R>(f: (T0, T1,T2) -> R)

    public func apply<R>(f: (T0, T1,T2) -> R): R
    

    功能:执行闭包函数。

    参数:

    • f: (T0, T1,T2) -> R - 待执行的闭包。

    返回值:

    • R - 闭包的执行结果。

    extend<T0, T1, T2> TupleWrapper3<T0, T1, T2> <: ToString

    extend<T0, T1, T2> TupleWrapper3<T0, T1, T2> <: ToString
    

    功能:为 TupleWrapper3 扩展 ToString 实现。

    父类型:

    func toString()

    public func toString()
    

    功能:TupleWrapper3 的字符串表达。

    extend<T0, T1, T2> TupleWrapper3<T0, T1, T2> <: Equatable<TupleWrapper3<T0, T1, T2>>

    extend<T0, T1, T2> TupleWrapper3<T0, T1, T2> <: Equatable<TupleWrapper3<T0, T1, T2>>
    

    功能:为 TupleWrapper3 扩展 Equatable 实现。

    父类型:

    operator func ==(TupleWrapper3<T0, T1, T2>)

    public operator func ==(other: TupleWrapper3<T0, T1, T2>)
    

    功能:比较两个元组。

    参数:

    返回值:

    • Bool - 相等时返回 true ,否则返回 false

    operator func !=(TupleWrapper3<T0, T1, T2>)

    public operator func !=(other: TupleWrapper3<T0, T1, T2>)
    

    功能:比较两个元组。

    参数:

    返回值:

    • Bool - 不相等时返回 true ,否则返回 false

    extend<T0, T1, T2> TupleWrapper3<T0, T1, T2> <: IndexAccess

    extend<T0, T1, T2> TupleWrapper3<T0, T1, T2> <: IndexAccess
    

    功能:为 TupleWrapper3 扩展 IndexAccess 实现。

    父类型:

    func getElementAsAny(Int64)

    public func getElementAsAny(index: Int64): ?Any
    

    功能:按索引获取元组内的值。

    参数:

    • index: Int64 - 索引值。

    返回值:

    • ?Any - 获取到的元组内的值。索引不合法时返回 None

    extend<T0, T1, T2> TupleWrapper3<T0, T1, T2> <: Arbitrary<TupleWrapper3<T0, T1, T2>> where T0 <: Arbitrary<T0>,T1 <: Arbitrary<T1>,T2 <: Arbitrary<T2>

    extend<T0, T1, T2> TupleWrapper3<T0, T1, T2> <: Arbitrary<TupleWrapper3<T0, T1, T2>>  where T0 <: Arbitrary<T0>,T1 <: Arbitrary<T1>,T2 <: Arbitrary<T2>
    

    功能:为 TupleWrapper3 扩展 Arbitrary 实现。

    父类型:

    static func arbitrary(RandomSource)

    public static func arbitrary(random: RandomSource): Generator<TupleWrapper3<T0, T1, T2>>
    

    功能:获取生成 TupleWrapper3<T0, T1, T2> 类型随机值生成器。

    struct TupleWrapper4<T0, T1, T2, T3>

    public struct TupleWrapper4<T0, T1, T2, T3> {
        public TupleWrapper4(public let tuple: (T0, T1, T2, T3))
    }
    

    功能:将闭包封装为结构体。闭包带两个参数。

    init((T0, T1, T2, T3))

    public TupleWrapper4(public let tuple: (T0, T1, T2, T3))
    

    功能:构造器。

    参数:

    • tuple: (T0, T1, T2, T3) - 闭包的4个入参。

    func apply<R>(f: (T0, T1, T2, T3) -> R)

    public func apply<R>(f: (T0, T1, T2, T3) -> R): R
    

    功能:执行闭包函数。

    参数:

    • f: (T0, T1, T2, T3) -> R - 待执行的闭包。

    返回值:

    • R - 闭包的执行结果。

    extend<T0, T1, T2, T3> TupleWrapper4<T0, T1, T2, T3> <: ToString

    extend<T0, T1, T2, T3> TupleWrapper4<T0, T1, T2, T3> <: ToString
    

    功能:为 TupleWrapper4 扩展 ToString 实现。

    父类型:

    func toString()

    public func toString()
    

    功能:TupleWrapper4 的字符串表达。

    extend<T0, T1, T2, T3> TupleWrapper4<T0, T1, T2, T3> <: Equatable<TupleWrapper4<T0, T1, T2, T3>>

    extend<T0, T1, T2> TupleWrapper3<T0, T1, T2> <: Equatable<TupleWrapper3<T0, T1, T2>>
    

    功能:为 TupleWrapper4 扩展 Equatable 实现。

    父类型:

    operator func ==(TupleWrapper4<T0, T1, T2, T3>)

    public operator func ==(other: TupleWrapper4<T0, T1, T2, T3>)
    

    功能:比较两个元组。

    参数:

    • other: TupleWrapper4<T0, T1, T2, T3> - 待比较的元组。

    返回值:

    • Bool - 相等时返回 true ,否则返回 false

    operator func !=(TupleWrapper4<T0, T1, T2, T3>)

    public operator func !=(other: TupleWrapper4<T0, T1, T2, T3>)
    

    功能:比较两个元组。

    参数:

    返回值:

    • Bool - 不相等时返回 true ,否则返回 false

    extend<T0, T1, T2, T3> TupleWrapper4<T0, T1, T2, T3> <: IndexAccess

    extend<T0, T1, T2, T3> TupleWrapper4<T0, T1, T2, T3> <: IndexAccess
    

    功能:为 TupleWrapper4 扩展 IndexAccess 实现。

    父类型:

    func getElementAsAny(Int64)

    public func getElementAsAny(index: Int64): ?Any
    

    功能:按索引获取元组内的值。

    参数:

    • index: Int64 - 索引值。

    返回值:

    • ?Any - 获取到的元组内的值。索引不合法时返回 None

    extend<T0, T1, T2, T3> TupleWrapper4<T0, T1, T2, T3><: Arbitrary<TupleWrapper4<T0, T1, T2, T3>> where where T0 <: Arbitrary<T0>,T1 <: Arbitrary<T1>,T2 <: Arbitrary<T2>,T3 <: Arbitrary<T3>

    extend<T0, T1, T2, T3> TupleWrapper4<T0, T1, T2, T3><: Arbitrary<TupleWrapper4<T0, T1, T2, T3>> where where T0 <: Arbitrary<T0>,T1 <: Arbitrary<T1>,T2 <: Arbitrary<T2>,T3 <: Arbitrary<T3>
    

    功能:为 TupleWrapper4 扩展 Arbitrary 实现。

    父类型:

    static func arbitrary(RandomSource)

    public static func arbitrary(random: RandomSource): Generator<TupleWrapper2<T0, T1, T2, T3>>
    

    功能:获取生成 TupleWrapper4<T0, T1, T2, T3> 类型随机值生成器。

    struct TupleWrapper5<T0, T1, T2, T3, T4>

    public struct TupleWrapper5<T0, T1, T2, T3, T4> {
        public TupleWrapper5(public let tuple: (T0, T1, T2, T3, T4))
    }
    

    功能:将闭包封装为结构体。闭包带两个参数。

    init((T0, T1, T2, T3, T4))

    public TupleWrapper5(public let tuple: (T0, T1, T2, T3, T4))
    

    功能:构造器。

    参数:

    • tuple: (T0, T1, T2, T3, T4) - 闭包的5个入参。

    func apply<R>(f: (T0, T1, T2, T3, T4) -> R)

    public func apply<R>(f: (T0, T1, T2, T3, T4) -> R): R
    

    功能:执行闭包函数。

    参数:

    • f: (T0, T1, T2, T3, T4) -> R - 待执行的闭包。

    返回值:

    • R - 闭包的执行结果。

    extend<T0, T1, T2, T3, T4> TupleWrapper5<T0, T1, T2, T3, T4> <: ToString

    extend<T0, T1, T2, T3, T4> TupleWrapper5<T0, T1, T2, T3, T4> <: ToString
    

    功能:为 TupleWrapper5 扩展 ToString 实现。

    父类型:

    func toString()

    public func toString()
    

    功能:TupleWrapper5 的字符串表达。

    extend<T0, T1, T2, T3, T4> TupleWrapper5<T0, T1, T2, T3, T4> <: Equatable<TupleWrapper5<T0, T1, T2, T3, T4>>

    extend<T0, T1, T2> TupleWrapper3<T0, T1, T2> <: Equatable<TupleWrapper3<T0, T1, T2>>
    

    功能:为 TupleWrapper5 扩展 Equatable 实现。

    父类型:

    operator func ==(TupleWrapper5<T0, T1, T2, T3, T4>)

    public operator func ==(other: TupleWrapper5<T0, T1, T2, T3, T4>)
    

    功能:比较两个二元元组。

    参数:

    返回值:

    • Bool - 相等时返回 true ,否则返回 false

    operator func !=(TupleWrapper5<T0, T1, T2, T3, T4>)

    public operator func !=(other: TupleWrapper2<T0, T1, T2, T3, T4>)
    

    功能:比较两个元组。

    参数:

    • other: TupleWrapper5<T0, T1, T2, T3, T4> - 待比较的元组。

    返回值:

    • Bool - 不相等时返回 true ,否则返回 false

    extend<T0, T1, T2, T3, T4> TupleWrapper5<T0, T1, T2, T3, T4> <: IndexAccess

    extend<T0, T1, T2, T3, T4> TupleWrapper5<T0, T1, T2, T3, T4> <: IndexAccess
    

    功能:为 TupleWrapper5 扩展 IndexAccess 实现。

    父类型:

    func getElementAsAny(Int64)

    public func getElementAsAny(index: Int64): ?Any
    

    功能:按索引获取元组内的值。

    参数:

    • index: Int64 - 索引值。

    返回值:

    • ?Any - 获取到的元组内的值。索引不合法时返回 None

    extend<T0, T1, T2, T3, T4> TupleWrapper5<T0, T1, T2, T3, T4> <: Arbitrary<TupleWrapper2<T0, T1, T2, T3, T4>> where T0 <: Arbitrary<T0>,T1 <: Arbitrary<T1>,T2 <: Arbitrary<T2>,T3 <: Arbitrary<T3>,T4 <: Arbitrary<T4>

    extend<T0, T1, T2, T3, T4> TupleWrapper5<T0, T1, T2, T3, T4> <: Arbitrary<TupleWrapper2<T0, T1, T2, T3, T4>> where T0 <: Arbitrary<T0>,T1 <: Arbitrary<T1>,T2 <: Arbitrary<T2>,T3 <: Arbitrary<T3>,T4 <: Arbitrary<T4>
    

    功能:为 TupleWrapper5 扩展 Arbitrary 实现。

    父类型:

    static func arbitrary(RandomSource)

    public static func arbitrary(random: RandomSource): Generator<TupleWrapper5<T0, T1, T2, T3, T4>>
    

    功能:获取生成 TupleWrapper5<T0, T1, T2, T3, T4> 类型随机值生成器。

    compress 模块

    compress 功能介绍

    compress 模块提供压缩解压功能。

    压缩是指用更少的比特表示数据,以便更高效地存储和传输数据。在实际应用中,压缩广泛应用于文件压缩、网页压缩、数据库备份等。

    压缩功能的实现依赖于压缩算法,主流的压缩算法有 deflate、lz77、lzw 等,这些算法可以将数据中的冗余信息去除或者替换成更紧凑的表示形式,从而实现数据压缩的目的。本模块目前使用自研的 deflate 算法。

    基于 deflate 压缩算法,给压缩后数据加上首部和尾部,可封装成不同格式的压缩文件,如 deflate-raw(无封装)、gzip、zip、png 等。其中 zip 可用于多个文件的压缩和打包,gzip 仅包含一个压缩文件。本模块目前支持的数据格式有 deflate-raw 和 gzip,暂不支持文件打包功能。

    此外,本模块支持设置压缩级别,更高的压缩级别对应着更高的压缩率和更慢的压缩速度,反之,更低的压缩级别对应着更低的压缩率和更快的压缩速度。

    特别地,zlib 指的是压缩功能的一个实现库,本模块的 zlib 包实现了 deflate 算法,并支持 deflate-raw 和 gzip 压缩格式。

    compress 模块的包列表

    compress 模块提供了如下包:

    包名功能
    zlibzlib 包提供压缩解压能力。

    compress.zlib 包

    功能介绍

    zlib 压缩解压库。

    本包使用自研 deflate 算法,支持 deflate-raw 和 gzip 数据格式,支持快速、默认、高压缩率三种压缩等级,压缩速度依次下降,压缩率依次提升。

    本包提供流式压缩和解压功能,即支持从输入流读取数据,将其压缩或解压,并写入字节数组,或从字节数组中读取数据,将其压缩或解压,并写入输出流。

    说明:

    本包暂不支持文件打包功能。

    API 列表

    类名功能
    CompressInputStream压缩输入流。
    CompressOutputStream压缩输出流。
    DecompressInputStream解压输入流。
    DecompressOutputStream解压输出流。

    枚举

    枚举名功能
    CompressLevel压缩等级。
    WrapType压缩数据格式。

    异常类

    异常类名功能
    ZlibExceptionzlib 包的异常类。

    class CompressInputStream

    public class CompressInputStream <: InputStream {
        public init(inputStream: InputStream, wrap!: WrapType = DeflateFormat, compressLevel!: CompressLevel = DefaultCompression, bufLen!: Int64 = 512)
    }
    

    功能:压缩输入流。

    可将 CompressInputStream 实例绑定到任意 InputStream 输入流,将该输入流中的数据压缩,并输出到字节数组。

    父类型:

    init(InputStream, WrapType, CompressLevel, Int64)

    public init(inputStream: InputStream, wrap!: WrapType = DeflateFormat, compressLevel!: CompressLevel = DefaultCompression, bufLen!: Int64 = 512)
    

    功能:构造一个压缩输入流。

    需绑定一个输入流,可设置压缩数据格式、压缩等级、内部缓冲区大小(每次从输入流中读取多少数据进行压缩)。

    参数:

    异常:

    • ZlibException - 当 bufLen 小于等于 0,输入流分配内存失败,或压缩资源初始化失败,抛出异常。

    func close()

    public func close(): Unit
    

    功能:关闭压缩输入流。

    当前 CompressInputStream 实例使用完毕后必须调用此函数来释放其所占内存资源,以免造成内存泄漏。调用该函数前需确保 read 函数已返回 0,否则可能导致绑定的 InputStream 并未被全部压缩。

    异常:

    • ZlibException - 如果释放压缩资源失败,抛出异常。

    func read(Array<Byte>)

    public func read(outBuf: Array<Byte>): Int64
    

    功能:从绑定的输入流中读取数据并压缩,压缩后数据放入指定的字节数组中。

    参数:

    • outBuf: Array<Byte> - 用来存放压缩后数据的缓冲区。

    返回值:

    • Int64 - 如果压缩成功,返回压缩后字节数,如果绑定的输入流中数据已经全部压缩完成,或者该压缩输入流被关闭,返回 0。

    异常:

    • ZlibException - 当 outBuf 为空,或压缩数据失败,抛出异常。

    class CompressOutputStream

    public class CompressOutputStream <: OutputStream {
        public init(outputStream: OutputStream, wrap!: WrapType = DeflateFormat, compressLevel!: CompressLevel = DefaultCompression, bufLen!: Int64 = 512)
    }
    

    功能:压缩输出流。

    可将 CompressOutputStream 实例绑定到任意 OutputStream 类型输出流,读取、压缩指定字节数组中的数据,并将压缩后数据输出到绑定的输出流。

    父类型:

    init(OutputStream, WrapType, CompressLevel, Int64)

    public init(outputStream: OutputStream, wrap!: WrapType = DeflateFormat, compressLevel!: CompressLevel = DefaultCompression, bufLen!: Int64 = 512)
    

    功能:构造一个压缩输出流,需绑定一个输出流,可设置压缩数据类型、压缩等级、内部缓冲区大小(每得到多少压缩后数据往输出流写出)。

    参数:

    异常:

    • ZlibException - 如果 bufLen 小于等于 0,输出流分配内存失败,或压缩资源初始化失败,抛出异常。

    func close()

    public func close(): Unit
    

    功能:关闭当前压缩输出流实例。

    关闭时,将写入剩余压缩数据(包括缓冲区中数据,以及压缩尾部信息),并释放其所占内存资源。当前压缩输出流使用完毕后必须调用此函数来释放其所占内存资源,以免造成内存泄漏。在调用 close 函数前,绑定的输出流里已写入的数据并不是一段完整的压缩数据,调用 close 函数后,才会把剩余压缩数据写入绑定的输出流,使其完整。

    异常:

    • ZlibException - 如果当前压缩输出流已经被关闭,或释放压缩资源失败,抛出异常。

    func flush()

    public func flush(): Unit
    

    功能:刷新压缩输出流。将内部缓冲区里已压缩的数据刷出并写入绑定的输出流,然后刷新绑定的输出流。

    异常:

    • ZlibException - 如果当前压缩输出流已经被关闭,抛出异常。

    func write(Array<Byte>)

    public func write(inBuf: Array<Byte>): Unit
    

    功能:将指定字节数组中的数据进行压缩,并写入输出流,当数据全部压缩完成并写入输出流,函数返回。

    参数:

    • inBuf: Array<Byte> - 待压缩的字节数组。

    异常:

    • ZlibException - 如果当前压缩输出流已经被关闭,或压缩数据失败,抛出异常。

    class DecompressInputStream

    public class DecompressInputStream <: InputStream {
        public init(inputStream: InputStream, wrap!: WrapType = DeflateFormat, bufLen!: Int64 = 512)
    }
    

    功能:解压输入流。

    可将 DecompressInputStream 实例绑定到任意 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,输入流分配内存失败,或待解压资源初始化失败,抛出异常。

    func close()

    public func close(): Unit
    

    功能:关闭解压输入流。

    当前 DecompressInputStream 实例使用完毕后必须调用此函数来释放其所占内存资源,以免造成内存泄漏。调用该函数前需确保 read 函数已返回 0,否则可能导致绑定的 InputStream 并未被全部解压。

    异常:

    • ZlibException - 如果释放解压资源失败,抛出异常。

    func read(Array<Byte>)

    public func read(outBuf: Array<Byte>): Int64
    

    功能:从绑定的输入流中读取数据并解压,解压后数据放入指定的字节数组中。

    参数:

    • outBuf: Array<Byte> - 用来存放解压后数据的缓冲区。

    返回值:

    • Int64 - 如果解压成功,返回解压后字节数,如果绑定的输入流中数据已经全部解压完成,或者该解压输入流被关闭,返回 0。

    异常:

    • ZlibException - 当 outBuf 为空,或解压数据失败,抛出异常。

    class DecompressOutputStream

    public class DecompressOutputStream <: OutputStream {
        public init(outputStream: OutputStream, wrap!: WrapType = DeflateFormat, bufLen!: Int64 = 512)
    }
    

    功能:解压输出流。

    可将 DecompressOutputStream 实例绑定到指定的 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,输出流分配内存失败,或解压资源初始化失败,抛出异常。

    func close()

    public func close(): Unit
    

    功能:关闭当前解压输出流实例。

    关闭时,将写入剩余解压后数据,并释放其所占内存资源。当前压缩输出流使用完毕后必须调用此函数来释放其所占内存资源,以免造成内存泄漏。如果之前 write 函数已处理的压缩数据不完整,调用 close 函数时会因为解压数据不全而抛出异常。

    异常:

    • ZlibException - 如果当前压缩输出流已经被关闭,通过 write 函数传入的待解压数据不完整,或释放压缩资源失败,抛出异常。

    func flush()

    public func flush(): Unit
    

    功能:刷新解压输出流。将内部缓冲区里已解压的数据写入绑定的输出流,然后刷新绑定的输出流。

    异常:

    • ZlibException - 如果当前解压输出流已经被关闭,抛出异常。

    func write(Array<Byte>)

    public func write(inBuf: Array<Byte>): Unit
    

    功能:将指定字节数组中的数据进行解压,并写入输出流,当数据全部解压完成并写入输出流,函数返回。

    参数:

    • inBuf: Array<Byte> - 待解压的字节数组。

    异常:

    • ZlibException - 如果当前解压输出流已经被关闭,或解压数据失败,抛出异常。

    枚举

    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 包的异常类。

    父类型:

    init(String)

    public init(message: String)
    

    功能:根据异常信息创建 ZlibException 实例。

    参数:

    • message: String - 异常提示信息。

    Deflate 格式数据的压缩和解压

    import compress.zlib.*
    import std.fs.*
    
    main() {
        var arr: Array<Byte> = Array<Byte>(1024 * 1024, {i => UInt8(i % 256)})
        File.writeTo("./zlib1.txt", arr, openOption: Create(false))
    
        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, OpenOption.Open(true, false))
        var destFile: File = File(destFileName, OpenOption.Create(false))
    
        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, OpenOption.Open(true, false))
        var destFile: File = File(destFileName, OpenOption.Create(false))
    
        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 compress.zlib.*
    import std.fs.*
    
    main() {
        var arr: Array<Byte> = Array<Byte>(1024 * 1024, {i => UInt8(i % 256)})
        File.writeTo("./zlib.txt", arr, openOption: Create(false))
    
        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, OpenOption.Open(true, false))
        var destFile: File = File(destFileName, OpenOption.Create(false))
    
        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, OpenOption.Open(true, false))
        var destFile: File = File(destFileName, OpenOption.Create(false))
    
        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
    

    crypto 模块

    crypto 功能介绍

    crypto 模块提供安全加密能力,包括生成安全随机数、生成消息摘要、数据加密和签名、创建和解析证书等。

    在实际应用中,crypto 模块常用于加密用户密码、保护敏感数据、生成数字签名等场景。

    crypto 模块的包列表

    crypto 模块提供了如下包:

    包名功能
    cryptocrypto 包提供安全随机数功能。
    digestdigest 包提供常用的消息摘要算法,包括 MD5、SHA1、SHA224、SHA256、SHA384、SHA512、HMAC、SM3等。
    keyskeys 包提供非对称加密和签名算法,包括 RSA 和 SM2 非对称加密算法以及 ECDSA 签名算法。
    x509x509 包提供处理数字证书功能,提供包括解析和序列化 X509 证书、验证证书、创建自签名证书、创建和验证证书链等主要功能。

    crypto.crypto 包

    功能介绍

    crypto 包提供安全随机数功能。

    使用本包需要外部依赖 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 中。

    说明:

    如果未安装 OpenSSL 3 软件包或者安装低版本的软件包,程序可能无法使用并抛出相关异常 SecureRandomException:Can not load openssl library or function xxx。

    API 列表

    类名功能
    SecureRandom安全随机数。
    SM4提供国密SM4对称加解密。

    结构体

    结构体名功能
    OperationMode对称加解密算法的工作模式。
    PaddingMode对称加解密算法的工填充模式。

    异常类

    异常类名功能
    SecureRandomException安全随机数异常类。

    class SecureRandom

    public class SecureRandom {
        public init(priv!: Bool = false)
    }
    

    功能:用于生成加密安全的伪随机数。

    Random 相比,主要有三个方面不同:

    • 随机数种子: Random 使用系统时钟作为默认的种子,时间戳一样,结果就相同;SecureRandom 使用操作系统或者硬件提供的随机数种子,生成的是真随机数。

    • 随机数生成: Random 使用了梅森旋转伪随机生成器;SecureRandom 则使用了 openssl 库提供的 MD5 等随机算法,使用熵源生成真随机数;如果硬件支持,还可以使用硬件随机数生成器来生成安全性更强的随机数。

    • 安全性: Random 不能用于加密安全的应用或者隐私数据的保护,可以使用 SecureRandom

    init(Bool)

    public init(priv!: Bool = false)
    

    功能:创建 SecureRandom 实例,可指定是否使用更加安全的加密安全伪随机生成器,加密安全伪随机生成器可用于会话密钥和证书私钥等加密场景。

    参数:

    • priv!: Bool - 设置为 true 表示使用加密安全伪随机生成器。

    func nextBool()

    public func nextBool(): Bool
    

    功能:获取一个随机的 Bool 类型实例。

    返回值:

    • Bool - 一个随机的 Bool 类型实例。

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextBytes(Int32)

    public func nextBytes(length: Int32): Array<Byte>
    

    功能:获取一个指定长度的随机字节的数组。

    参数:

    • length: Int32 - 要生成的随机字节数组的长度。

    返回值:

    异常:

    func nextFloat16()

    public func nextFloat16(): Float16
    

    功能:获取一个 Float16 类型且在区间 [0.0, 1.0) 内的随机数。

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextFloat32()

    public func nextFloat32(): Float32
    

    功能:获取一个 Float32 类型且在区间 [0.0, 1.0) 内的随机数。

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextFloat64()

    public func nextFloat64(): Float64
    

    功能:获取一个 Float64 类型且在区间 [0.0, 1.0) 内的随机数。

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextGaussianFloat16(Float16, Float16)

    public func nextGaussianFloat16(mean!: Float16 = 0.0, sigma!: Float16 = 1.0): Float16
    

    功能:默认获取一个 Float16 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数,其中均值是期望值,可解释为位置参数,决定了分布的位置,标准差可解释为尺度参数,决定了分布的幅度。

    参数:

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextGaussianFloat32(Float32, Float32)

    public func nextGaussianFloat32(mean!: Float32 = 0.0, sigma!: Float32 = 1.0): Float32
    

    功能:默认获取一个 Float32 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数,其中均值是期望值,可解释为位置参数,决定了分布的位置,标准差可解释为尺度参数,决定了分布的幅度。

    参数:

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextGaussianFloat64(Float64, Float64)

    public func nextGaussianFloat64(mean!: Float64 = 0.0, sigma!: Float64 = 1.0): Float64
    

    功能:默认获取一个 Float64 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数,其中均值是期望值,可解释为位置参数,决定了分布的位置,标准差可解释为尺度参数,决定了分布的幅度。

    参数:

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextInt16()

    public func nextInt16(): Int16
    

    功能:获取一个 Int16 类型的随机数。

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextInt32()

    public func nextInt32(): Int32
    

    功能:获取一个 Int32 类型的随机数。

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextInt16(Int16)

    public func nextInt16(max: Int16): Int16
    

    功能:获取一个 Int16 类型且在区间 [0, max) 内的随机数。

    参数:

    • max: Int16 - 区间最大值。

    返回值:

    异常:

    func nextInt32(Int32)

    public func nextInt32(max: Int32): Int32
    

    功能:获取一个 Int32 类型且在区间 [0, max) 内的随机数。

    参数:

    • max: Int32 - 区间最大值。

    返回值:

    异常:

    func nextInt64()

    public func nextInt64(): Int64
    

    功能:获取一个 Int64 类型的随机数。

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextInt64(Int64)

    public func nextInt64(max: Int64): Int64
    

    功能:获取一个 Int64 类型且在区间 [0, max) 内的随机数。

    参数:

    • max: Int64 - 区间最大值。

    返回值:

    异常:

    func nextInt8()

    public func nextInt8(): Int8
    

    功能:获取一个 Int8 类型的随机数。

    返回值:

    • Int8 - 一个 Int8 类型的随机数。

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextInt8(Int8)

    public func nextInt8(max: Int8): Int8
    

    功能:获取一个 Int8 类型且在区间 [0, max) 内的随机数。

    参数:

    • max: Int8 - 区间最大值。

    返回值:

    • Int8 - 一个 Int8 类型的随机数。

    异常:

    func nextUInt16()

    public func nextUInt16(): UInt16
    

    功能:获取一个 UInt16 类型的随机数。

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextUInt16(UInt16)

    public func nextUInt16(max: UInt16): UInt16
    

    功能:获取一个 UInt16 类型且在区间 [0, max) 内的随机数。

    参数:

    • max: UInt16 - 区间最大值。

    返回值:

    异常:

    func nextUInt32()

    public func nextUInt32(): UInt32
    

    功能:获取一个 UInt32 类型的随机数。

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextUInt32(UInt32)

    public func nextUInt32(max: UInt32): UInt32
    

    功能:获取一个 UInt32 类型且在区间 [0, max) 内的随机数。

    参数:

    • max: UInt32 - 区间最大值。

    返回值:

    异常:

    func nextUInt64()

    public func nextUInt64(): UInt64
    

    功能:获取一个 UInt64 类型的随机数。

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextUInt64(UInt64)

    public func nextUInt64(max: UInt64): UInt64
    

    功能:获取一个 UInt64 类型且在区间 [0, max) 内的随机数。

    参数:

    • max: UInt64 - 区间最大值。

    返回值:

    异常:

    func nextUInt8()

    public func nextUInt8(): UInt8
    

    功能:获取一个 UInt8 类型的随机数。

    返回值:

    异常:

    • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

    func nextUInt8(UInt8)

    public func nextUInt8(max: UInt8): UInt8
    

    功能:获取一个 UInt8 类型且在区间 [0, max) 内的随机数。

    参数:

    • max: UInt8 - 区间最大值。

    返回值:

    异常:

    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 = SM4_GCM_TAG_SIZE
        )
    }
    

    功能:提供国密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 字节是摘要数据。

    注意:

    GCM 模式需要 OpenSSL 3.2 或者以上版本。

    父类型:

    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 = SM4_GCM_TAG_SIZE
        )
    

    功能:创建 SM4 实例,可指定在不同工作模式下参数。

    参数:

    异常:

    prop aad

    public prop aad: Array<Byte> 
    

    功能:附加数据。

    类型:Array<Byte>

    prop blockSize

    public prop blockSize: Int64
    

    功能:分组长度,单位字节。

    类型:Int64

    prop keySize

    public prop keySize: Int64 
    

    功能:密钥长度。

    类型:Int64

    prop key

    public prop key: Array<Byte> 
    

    功能:密钥。

    类型:Array<Byte>

    prop optMode

    public prop optMode: OperationMode
    

    功能:工作模式。

    类型:OperationMode

    prop paddingMode

    public prop paddingMode: PaddingMode
    

    功能:填充模式。

    类型:PaddingMode

    prop iv

    public prop iv: Array<Byte>
    

    功能:初始化向量。

    类型:Array<Byte>

    prop ivSize

    public prop ivSize: Int64
    

    功能:初始化向量长度。

    类型:Int64

    prop tagSize

    public prop tagSize: Int64
    

    功能:摘要长度。

    类型:Int64

    func encrypt(Array<Byte>)

    public func encrypt(input: Array<Byte>): Array<Byte>
    

    功能:加密一段数据数据。

    参数:

    返回值:

    异常:

    func encrypt(InputStream, OutputStream)

    public func encrypt(input: InputStream, output: OutputStream)
    

    功能:对输入流进行加密,一般如果数据过大无法一次对其加密,可以对数据流进行加密。

    参数:

    异常:

    func decrypt(Array<Byte>)

    public func decrypt(input: Array<Byte>): Array<Byte>
    

    功能:解密一段数据数据。

    参数:

    返回值:

    异常:

    func decrypt(InputStream, OutputStream)

    public func decrypt(input: InputStream, output: OutputStream)
    

    功能:对输入流进行解密,一般如果数据过大无法一次对其解密,可以对数据流进行解密。

    参数:

    异常:

    结构体

    struct OperationMode

    public struct OperationMode <: ToString & Equatable<OperationMode>
    

    功能: 对称加解密算法的工作模式。

    父类型:

    static let ECB

    public static let ECB
    

    功能:Electronic CodeBook(单子密码本)工作模式。

    类型:OperationMode

    static let CBC

    public static let CBC
    

    功能:Cipher Block Chaining(密码分组链接)工作模式。

    类型:OperationMode

    static let OFB

    public static let OFB
    

    功能:Output FeedBack(输出反馈)工作模式。

    类型:OperationMode

    static let CFB

    public static let CFB
    

    功能:Output FeedBack(密文反馈)工作模式。

    类型:OperationMode

    static let CTR

    public static let CTR
    

    功能:CounTeR(计数器)工作模式。

    类型:OperationMode

    static let GCM

    public static let GCM
    

    功能:Galois Counter(伽罗瓦计数器)工作模式。

    类型:OperationMode

    let mode

    public let mode: String
    

    功能:operation 分组加解密的工作模式,目前支持 ECB、CBC CFB OFB CTR GCM。

    类型:String

    func toString()

    public override func toString(): String
    

    功能:获取工作模式字符串。

    返回值:

    • String - 工作模式字符串。

    func ==(OperationMode)

    public operator override func ==(other: OperationMode): Bool
    

    功能:工作模式比较是否相同。

    参数:

    返回值:

    • Bool - true 相同, false不相同。

    func !=(OperationMode)

    public operator override func !=(other: OperationMode): Bool
    

    功能:工作模式比较是否不相同。

    参数:

    返回值:

    • Bool - true 不相同, false相同。

    struct PaddingMode

    public struct PaddingMode <: Equatable<PaddingMode>
    

    功能: 对称加解密算法的工填充模式。

    父类型:

    static let NoPadding

    public static let NoPadding
    

    功能:不填充。

    类型:PaddingMode

    static let PKCS7Padding

    public static let PKCS7Padding
    

    功能:采用PKCS7协议填充。

    类型:PaddingMode

    let paddingType

    public let paddingType: Int64
    

    功能:分组加解密填充方式,目前支持非填充和 pkcs7 填充。

    类型:Int64

    func ==(PaddingMode)

    public operator override func ==(other: PaddingMode): Bool
    

    功能:填充模式比较是否相同。

    参数:

    返回值:

    • Bool - true 相同, false不相同。

    func !=(PaddingMode)

    public operator override func !=(other: PaddingMode): Bool
    

    功能:工作模式比较是否不相同。

    参数:

    返回值:

    • Bool - true 不相同, false相同。

    异常类

    class SecureRandomException

    public class SecureRandomException <: Exception {
        public init()
        public init(message: String)
    }
    

    功能:crypto 包安全随机数的异常类。

    父类型:

    init()

    public init()
    

    功能:创建默认的 SecureRandomException 实例,异常提示消息为空。

    init(String)

    public init(message: String)
    

    功能:根据异常信息创建 SecureRandomException 实例。

    参数:

    • message: String - 异常提示信息。

    SecureRandom 使用

    示例:Random 创建随机数对象。

    代码:

    import 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 crypto.crypto.*
    import encoding.hex.fromHexString
    main() {
    
        var plains ="hello cangjie!"
        var key = "1234567890123456"
        var iv = "1234567890123456"
        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!
    

    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 中。

    说明:

    如果未安装 OpenSSL 3 软件包或者安装低版本的软件包,程序可能无法使用并抛出相关异常 CryptoException:Can not load openssl library or function xxx。

    API 列表

    类名功能
    HMACHMAC摘要算法。
    MD5MD5摘要算法。
    SHA1SHA1摘要算法。
    SHA224SHA224摘要算法。
    SHA256SHA256摘要算法。
    SHA384SHA384摘要算法。
    SHA512SHA512摘要算法。
    SM3SM3摘要算法。

    结构体

    结构体名功能
    HashType摘要算法类型。

    异常类

    异常类名功能
    CryptoExceptioncrypto 包的异常类。

    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。

    父类型:

    prop blockSize

    public prop blockSize: Int64
    

    功能:HMAC 所选 Hash 算法信息块长度,单位字节。

    类型:Int64

    prop size

    public prop size: Int64
    

    功能:HMAC 所选 Hash 算法的摘要信息长度,单位字节。

    类型:Int64

    init(Array<Byte>, () -> Digest)

    public init(key: Array<Byte>, digest: () -> Digest)
    

    功能:构造函数,创建 HMAC 对象。

    参数:

    • key: Array<Byte> - 密钥,建议该参数不小于所选Hash算法摘要的长度。
    • digest: () -> Digest- hash 算法。

    异常:

    init(Array<Byte>, HashType)

    public init(key: Array<Byte>, algorithm: HashType)
    

    功能:构造函数,创建 HMAC 对象。

    参数:

    • key: Array<Byte> - 密钥,建议该参数不小于所选Hash算法摘要的长度。
    • algorithm: HashType - hash 算法。

    异常:

    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 不相同。

    func finish()

    public func finish(): Array<Byte>
    

    功能:返回生成的信息摘要值,注意调用 finish 后不可以再进行摘要计算,如重新计算需要 reset 重置上下文。

    返回值:

    • Array<Byte> - 生成的信息摘要字节序列。

    异常:

    • CryptoException - 未重置上下文再次调用 finish 进行摘要计算,抛此异常。

    func reset()

    public func reset(): Unit
    

    功能:重置 HMAC 对象到初始状态,清理 HMAC 上下文。

    异常:

    func write(Array<Byte>)

    public func write(buffer: Array<Byte>): Unit 
    

    功能:使用给定的 buffer 更新 HMAC 对象,在调用 finish 前可以多次更新。

    参数:

    • buffer: Array<Byte> - 需要追加的字节序列。

    异常:

    • CryptoException - 当 buffer 为空、finish 已经调用生成信息摘要场景,抛此异常。

    class MD5

    public class MD5 <: Digest {
        public init()
    }
    

    功能:提供 MD5 算法的实现接口。

    父类型:

    prop blockSize

    public prop blockSize: Int64
    

    功能:MD5 信息块长度,单位字节。

    类型:Int64

    prop size

    public prop size: Int64
    

    功能:MD5 摘要信息长度,单位字节。

    类型:Int64

    init()

    public init()
    

    功能:无参构造函数,创建 MD5 对象。

    func finish()

    public func finish(): Array<Byte>
    

    功能:返回生成的 MD5 值,注意调用 finish 后 MD5 上下文会发生改变,finish 后不可以再进行摘要计算,如重新计算需要 reset 重置上下文。

    返回值:

    异常:

    • CryptoException - 未重置上下文再次调用 finish 进行摘要计算,抛此异常。

    func reset()

    public func reset(): Unit
    

    功能:重置 MD5 对象到初始状态,清理 MD5 上下文。

    func write(Array<Byte>)

    public func write(buffer: Array<Byte>): Unit
    

    功能:使用给定的 buffer 更新 MD5 对象,在调用 finish 前可以多次更新。

    参数:

    • buffer: Array<Byte> - 输入字节序列。

    异常:

    • CryptoException - 已经调用 finish 进行摘要计算后未重置上下文,抛此异常。

    class SHA1

    public class SHA1 <: Digest {
        public init()
    }
    

    功能:提供 SHA1 算法的实现接口。

    父类型:

    prop blockSize

    public prop blockSize: Int64
    

    功能:SHA1 信息块长度,单位字节。

    类型:Int64

    prop size

    public prop size: Int64
    

    功能:SHA1 摘要信息长度,单位字节。

    类型:Int64

    init()

    public init()
    

    功能:无参构造函数,创建 SHA1 对象。

    func finish()

    public func finish(): Array<Byte>
    

    功能:返回生成的 SHA1 值,注意调用 finish 后 SHA1 上下文会发生改变,finish 后不可以再进行摘要计算,如重新计算需要 reset 重置上下文。

    返回值:

    异常:

    • CryptoException - 未重置上下文再次调用 finish 进行摘要计算,抛此异常。

    func reset()

    public func reset(): Unit
    

    功能:重置 SHA1 对象到初始状态,清理 SHA1 上下文。

    func write(Array<Byte>)

    public func write(buffer: Array<Byte>): Unit
    

    功能:使用给定的 buffer 更新 SHA1 对象,在调用 finish 前可以多次更新。

    参数:

    • buffer: Array<Byte> - 输入字节序列。

    异常:

    • CryptoException - 已经调用 finish 进行摘要计算后未重置上下文,抛此异常。

    class SHA224

    public class SHA224 <: Digest {
        public init()
    }
    

    功能:提供 SHA224 算法的实现接口。

    父类型:

    prop blockSize

    public prop blockSize: Int64
    

    功能:SHA224 信息块长度,单位字节。

    类型:Int64

    prop size

    public prop size: Int64
    

    功能:SHA224 摘要信息长度,单位字节。

    类型:Int64

    init()

    public init()
    

    功能:无参构造函数,创建 SHA224 对象。

    func finish()

    public func finish(): Array<Byte>
    

    功能:返回生成的 SHA224 值,注意调用 finish 后 SHA224 上下文会发生改变,finish 后不可以再进行摘要计算,如重新计算需要 reset 重置上下文。

    返回值:

    异常:

    • CryptoException - 未重置上下文再次调用 finish 进行摘要计算,抛此异常。

    func reset()

    public func reset(): Unit
    

    功能:重置 SHA224 对象到初始状态,清理 SHA224 上下文。

    func write(Array<Byte>)

    public func write(buffer: Array<Byte>): Unit
    

    功能:使用给定的 buffer 更新 SHA224 对象,在调用 finish 前可以多次更新。

    参数:

    • buffer: Array<Byte> - 输入字节序列。

    异常:

    • CryptoException - 已经调用 finish 进行摘要计算后未重置上下文,抛此异常。

    class SHA256

    public class SHA256 <: Digest {
        public init()
    }
    

    功能:提供 SHA256 算法的实现接口。

    父类型:

    prop blockSize

    public prop blockSize: Int64
    

    功能:SHA256 信息块长度,单位字节。

    类型:Int64

    prop size

    public prop size: Int64
    

    功能:SHA256 摘要信息长度,单位字节。

    类型:Int64

    init()

    public init()
    

    功能:无参构造函数,创建 SHA256 对象。

    func finish()

    public func finish(): Array<Byte>
    

    功能:返回生成的 SHA256 值,注意调用 finish 后 SHA256 上下文会发生改变,finish 后不可以再进行摘要计算,如重新计算需要 reset 重置上下文。

    返回值:

    异常:

    • CryptoException - 未重置上下文再次调用 finish 进行摘要计算,抛此异常。

    func reset()

    public func reset(): Unit
    

    功能:重置 SHA256 对象到初始状态,清理 SHA256 上下文。

    func write(Array<Byte>)

    public func write(buffer: Array<Byte>): Unit
    

    功能:使用给定的 buffer 更新 SHA256 对象,在调用 finish 前可以多次更新。

    参数:

    • buffer: Array<Byte> - 输入字节序列。

    异常:

    • CryptoException - 已经调用 finish 进行摘要计算后未重置上下文,抛此异常。

    class SHA384

    public class SHA384 <: Digest {
        public init()
    }
    

    功能:提供 SHA384 算法的实现接口。

    父类型:

    prop blockSize

    public prop blockSize: Int64
    

    功能:SHA384 信息块长度,单位字节。

    类型:Int64

    prop size

    public prop size: Int64
    

    功能:SHA384 摘要信息长度,单位字节。

    类型:Int64

    init()

    public init()
    

    功能:无参构造函数,创建 SHA384 对象。

    func finish()

    public func finish(): Array<Byte>
    

    功能:返回生成的 SHA384 值,注意调用 finish 后 SHA384 上下文会发生改变,finish 后不可以再进行摘要计算,如重新计算需要 reset 重置上下文。

    返回值:

    异常:

    • CryptoException - 未重置上下文再次调用 finish 进行摘要计算,抛此异常。

    func reset()

    public func reset(): Unit
    

    功能:重置 SHA384 对象到初始状态,清理 SHA384 上下文。

    func write(Array<Byte>)

    public func write(buffer: Array<Byte>): Unit
    

    功能:使用给定的 buffer 更新 SHA384 对象,在调用 finish 前可以多次更新。

    参数:

    • buffer: Array<Byte> - 输入字节序列。

    异常:

    • CryptoException - 已经调用 finish 进行摘要计算后未重置上下文,抛此异常。

    class SHA512

    public class SHA512 <: Digest {
        public init()
    }
    

    功能:提供 SHA512 算法的实现接口。

    父类型:

    prop blockSize

    public prop blockSize: Int64
    

    功能:SHA512 信息块长度,单位字节。

    类型:Int64

    prop size

    public prop size: Int64
    

    功能:SHA512 摘要信息长度,单位字节。

    类型:Int64

    init()

    public init()
    

    功能:无参构造函数,创建 SHA512 对象。

    func finish()

    public func finish(): Array<Byte>
    

    功能:返回生成的 SHA512 值,注意调用 finish 后 SHA512 上下文会发生改变,finish 后不可以再进行摘要计算,如重新计算需要 reset 重置上下文。

    返回值:

    异常:

    • CryptoException - 未重置上下文再次调用 finish 进行摘要计算,抛此异常。

    func reset()

    public func reset(): Unit
    

    功能:重置 SHA512 对象到初始状态,清理 SHA512 上下文。

    func write(Array<Byte>)

    public func write(buffer: Array<Byte>): Unit
    

    功能:使用给定的 buffer 更新 SHA512 对象,在调用 finish 前可以多次更新。

    参数:

    • buffer: Array<Byte> - 输入字节序列。

    异常:

    • CryptoException - 已经调用 finish 进行摘要计算后未重置上下文,抛此异常。

    class SM3

    public class SM3 <: Digest {
        public init()
    }
    

    功能:提供 SM3 算法的实现接口。

    父类型:

    prop blockSize

    public prop blockSize: Int64
    

    功能:SM3 信息块长度,单位字节。

    类型:Int64

    prop size

    public prop size: Int64
    

    功能:SM3 摘要信息长度,单位字节。

    类型:Int64

    init()

    public init()
    

    功能:无参构造函数,创建 SM3 对象。

    func finish()

    public func finish(): Array<Byte>
    

    功能:返回生成的 SM3 值,注意调用 finish 后 SM3 上下文会发生改变,finish 后不可以再进行摘要计算,如重新计算需要 reset 重置上下文。

    返回值:

    异常:

    • CryptoException - 未重置上下文再次调用 finish 进行摘要计算,抛此异常。

    func reset()

    public func reset(): Unit
    

    功能:重置 SM3 对象到初始状态,清理 SM3 上下文。

    func write(Array<Byte>)

    public func write(buffer: Array<Byte>): Unit
    

    功能:使用给定的 buffer 更新 SM3 对象,在调用 finish 前可以多次更新。

    参数:

    • buffer: Array<Byte> - 输入字节序列。

    异常:

    • CryptoException - 已经调用 finish 进行摘要计算后未重置上下文,抛此异常。

    结构体

    struct HashType

    public struct HashType <: ToString & Equatable<HashType>
    

    功能: 此类为 Hash 算法类别结构体,MD5SHA1SHA224SHA256SHA384SHA512均为常用摘要算法。

    父类型:

    prop MD5

    public static prop MD5: HashType
    

    功能:返回 MD5 类型。

    类型:HashType

    prop SHA1

    public static prop SHA1: HashType
    

    功能:返回 SHA1 类型。

    类型:HashType

    prop SHA224

    public static prop SHA224: HashType
    

    功能:返回 SHA224 类型。

    类型:HashType

    prop SHA256

    public static prop SHA256: HashType
    

    功能:返回 SHA256 类型。

    类型:HashType

    prop SHA384

    public static prop SHA384: HashType
    

    功能:返回 SHA384 类型。

    类型:HashType

    prop SHA512

    public static prop SHA512: HashType
    

    功能:返回 SHA512 类型。

    类型:HashType

    prop SM3

    public static prop SM3: HashType
    

    功能:返回 SM3 类型。

    类型:HashType

    func toString()

    public func toString(): String
    

    功能:获取 Hash 算法名称。

    返回值:

    • String - Hash 算法名称。

    operator func ==(HashType)

    public operator override func ==(other: HashType): Bool
    

    功能:判断两 HashType 是否引用同一实例。

    参数:

    • other: HashType - 对比的 HashType。

    返回值:

    • Bool - 相同返回 true;否则,返回 false

    operator func !=(HashType)

    public operator override func !=(other: HashType): Bool
    

    功能:判断两 HashType 是否引用不同实例。

    参数:

    • other: HashType - 对比的 HashType。

    返回值:

    • Bool - 不相同返回 true;否则,返回 false

    异常类

    class CryptoException

    public class CryptoException <: Exception {
        public init()
        public init(message: String)
    }
    

    功能:此类为摘要和加解密出现错误时抛出的异常。

    父类型:

    init()

    public init()
    

    功能:无参构造函数,构造CryptoException异常。

    init(String)

    public init(message: String)
    

    功能:根据异常信息构造 CryptoException 异常类对象。

    参数:

    • message: String - 异常信息。

    digest 使用

    MD5 算法示例

    调用仓颉标准库提供的通用 digest 函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import encoding.hex.*
    
    main() {
        var str: String = "helloworld"
        var md5Instance = MD5()
        var md: Array<Byte> = digest(md5Instance, str)
        var result: String = toHexString(md)
        println(result)
        return 0
    }
    

    调用 MD5 成员函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import 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 算法示例

    调用仓颉标准库提供的通用 digest 函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import encoding.hex.*
    
    main() {
        var str: String = "helloworld"
        var sha1Instance = SHA1()
        var md: Array<Byte> = digest(sha1Instance, str)
        var result: String = toHexString(md)
        println(result)
        return 0
    }
    

    调用 SHA1 成员函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import 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 算法示例

    调用仓颉标准库提供的通用 digest 函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import encoding.hex.*
    
    main() {
        var str: String = "helloworld"
        var sha224Instance = SHA224()
        var md: Array<Byte> = digest(sha224Instance, str)
        var result: String = toHexString(md)
        println(result)
        return 0
    }
    

    调用 SHA224 成员函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import 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 算法示例

    调用仓颉标准库提供的通用 digest 函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import encoding.hex.*
    
    main() {
        var str: String = "helloworld"
        var sha256Instance = SHA256()
        var md: Array<Byte> = digest(sha256Instance, str)
        var result: String = toHexString(md)
        println(result)
        return 0
    }
    

    调用 SHA256 成员函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import 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 算法示例

    调用仓颉标准库提供的通用 digest 函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import encoding.hex.*
    
    main() {
        var str: String = "helloworld"
        var sha384Instance = SHA384()
        var md: Array<Byte> = digest(sha384Instance, str)
        var result: String = toHexString(md)
        println(result)
        return 0
    }
    

    调用 SHA384 成员函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import 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 算法示例

    调用仓颉标准库提供的通用 digest 函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import encoding.hex.*
    
    main() {
        var str: String = "helloworld"
        var sha512Instance = SHA512()
        var md: Array<Byte> = digest(sha512Instance, str)
        var result: String = toHexString(md)
        println(result)
        return 0
    }
    

    调用 SHA512 成员函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import 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。

    调用仓颉标准库提供的通用 digest 函数

    import crypto.digest.*
    import encoding.hex.*
    import std.crypto.digest.*
    
    main() {
        var algorithm: HashType  =  HashType.SHA512
        var key: Array<UInt8> = "cangjie".toArray()
        var data: Array<UInt8> = "123456789".toArray()
        var hmac= HMAC(key,algorithm)
        var md: Array<Byte> = digest(hmac, data)
        var result: String = toHexString(md)
        println(result)
        return 0
    }
    

    运行结果:

    2bafeb53b60a119d38793a886c7744f5027d7eaa3702351e75e4ff9bf255e3ce296bf41f80adda2861e81bd8efc52219df821852d84a17fb625e3965ebf2fdd9
    

    调用 HMAC-SHA512 成员函数

    import crypto.digest.*
    import 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 算法示例

    调用仓颉标准库提供的通用 digest 函数

    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import encoding.hex.*
    
    main() {
        var str: String = "helloworld"
        var sm3Instance = SM3()
        var md: Array<Byte> = digest(sm3Instance, str)
        var result: String = toHexString(md)
        println(result)
        return 0
    }
    

    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 中。

    说明:

    如果未安装 OpenSSL 3 软件包或者安装低版本的软件包,程序可能无法使用并抛出相关异常 CryptoException:Can not load openssl library or function xxx。

    API 列表

    类名功能
    ECDSAPrivateKeyECDSA私钥类。
    ECDSAPublicKeyECDSA公钥类。
    RSAPrivateKeyRSA私钥类。
    RSAPublicKeyRSA公钥类。
    SM2PrivateKeySM2私钥类。
    SM2PublicKeySM2公钥类。

    枚举

    枚举名功能
    Curve枚举类型 Curve 用于选择生成 ECDSA 密钥时使用的椭圆曲线类型。
    PadOption用于设置 RSA 的填充模式。

    结构体

    结构体名功能
    OAEPOption最优非对称加密填充。
    PSSOption概率签名方案。

    class ECDSAPrivateKey

    public class ECDSAPrivateKey <: PrivateKey {
        public init(curve: Curve)
    }
    

    功能:ECDSA 私钥类,提供生成 ECDSA 私钥能力,ECDSA 的私钥支持签名操作,同时支持 PEM 和 DER 格式的编码解码。

    父类型:

    init()

    public init(curve: Curve)
    

    功能:init 初始化生成私钥。

    参数:

    • curve: Curve - 椭圆曲线类型。

    异常:

    func decodeDer(DerBlob)

    public static func decodeDer(blob: DerBlob): ECDSAPrivateKey
    

    功能:将私钥从 DER 格式解码。

    参数:

    • blob: DerBlob - 二进制格式的私钥对象。

    返回值:

    异常:

    func decodeDer(DerBlob, ?String)

    public static func decodeDer(blob: DerBlob, password!: ?String): ECDSAPrivateKey
    

    功能:将加密的私钥从 DER 格式解码。

    参数:

    • blob: DerBlob - 二进制格式的私钥对象。
    • password!: ?String - 解密私钥需要提供的密码,密码为 None 时则不解密。

    返回值:

    异常:

    • CryptoException - 解码失败、解密失败或者参数密码为空字符串,抛出异常。

    func decodeFromPem(String)

    public static func decodeFromPem(text: String): ECDSAPrivateKey
    

    功能:将私钥从 PEM 格式解码。

    参数:

    • text: String - PEM 格式的私钥字符流。

    返回值:

    异常:

    • CryptoException - 解码失败、字符流不符合 PEM 格式或文件头不符合私钥头标准时,抛出异常。

    func decodeFromPem(String, ?String)

    public static func decodeFromPem(text: String, password!: ?String): ECDSAPrivateKey
    

    功能:将私钥从PEM 格式解码。

    参数:

    • text: String - PEM 格式的私钥字符流。
    • password!: ?String - 解密私钥需要提供的密码,密码为 None 时则不解密。

    返回值:

    异常:

    • CryptoException - 解码失败、解密失败、参数密码为空字符串、字符流不符合 PEM 格式或文件头不符合私钥头标准时,抛出异常。

    func encodeToDer()

    public override func encodeToDer(): DerBlob
    

    功能:将私钥编码为 DER 格式。

    返回值:

    • DerBlob - 编码后的Der格式私钥。

    异常:

    func encodeToDer(?String)

    public func encodeToDer(password!: ?String): DerBlob
    

    功能:使用 AES-256-CBC 加密私钥,将私钥编码为 DER 格式。

    参数:

    • password!: ?String - 加密私钥需要提供的密码,密码为 None 时则不加密。

    返回值:

    • DerBlob - 编码后的DER格式私钥。

    异常:

    • CryptoException - 编码失败、加密失败或者参数密码为空字符串,抛出异常。

    func encodeToPem()

    public override func encodeToPem(): PemEntry
    

    功能:将私钥编码为 PEM 格式。

    返回值:

    • PemEntry - 私钥PEM 格式的对象。

    异常:

    func sign(Array<Byte>)

    public func sign(digest: Array<Byte>): Array<Byte>
    

    功能:sign 对数据的摘要结果进行签名。

    参数:

    • digest: Array<Byte> - 数据的摘要结果。

    返回值:

    异常:

    func toString

    public override func toString(): String
    

    功能:输出私钥种类。

    返回值:

    • String - 密钥类别描述。

    class ECDSAPublicKey

    public class ECDSAPublicKey <: PublicKey {
        public init(pri: ECDSAPrivateKey)
    }
    

    功能:ECDSA 公钥类,提供生成 ECDSA 公钥能力,ECDSA 公钥支持验证签名操作,支持 PEM 和 DER 格式的编码解码。

    父类型:

    init(ECDSAPrivateKey)

    public init(pri: ECDSAPrivateKey)
    

    功能:init 初始化公钥,从私钥中获取对应的公钥。

    参数:

    异常:

    func decodeDer(DerBlob)

    public static func decodeDer(blob: DerBlob): ECDSAPublicKey
    

    功能:将公钥从 DER 格式解码。

    参数:

    • blob: DerBlob - 二进制格式的公钥对象。

    返回值:

    异常:

    func decodeFromPem(String)

    public static func decodeFromPem(text: String): ECDSAPublicKey
    

    功能:将公钥从 PEM 格式解码。

    参数:

    • text: String - PEM 格式的公钥字符流。

    返回值:

    异常:

    • CryptoException - 解码失败、字符流不符合 PEM 格式或文件头不符合公钥头标准时,抛出异常。

    func encodeToDer()

    public override func encodeToDer(): DerBlob
    

    功能:将公钥编码为 DER 格式。

    返回值:

    • DerBlob - 编码后的Der格式公钥。

    异常:

    func encodeToPem()

    public override func encodeToPem(): PemEntry
    

    功能:将公钥编码为 PEM 格式。

    返回值:

    异常:

    func toString

    public override func toString(): String
    

    功能:输出公钥种类。

    返回值:

    • String - 密钥类别描述。

    func verify(Array<Byte>, Array<Byte>)

    public func verify(digest: Array<Byte>, sig: Array<Byte>): Bool
    

    功能:verify 验证签名结果。

    参数:

    • digest: Array<Byte> - 数据的摘要结果。
    • sig: Array<Byte> - 数据的签名结果。

    返回值:

    • Bool - 返回 true 表示验证成功,false 失败。

    class RSAPrivateKey

    public class RSAPrivateKey <: PrivateKey{
        public init(bits: Int32)
        public init(bits: Int32, e: BigInt)
    }
    

    功能:RSA 私钥类,提供生成 RSA 私钥能力,RSA 私钥支持签名和解密操作,支持 PEM 和 DER 格式的编码解码,符合 PKCS1 标准。

    父类型:

    init(Int32)

    public init(bits: Int32)
    

    功能:init 初始化生成私钥, 公钥指数默认值为 65537,业界推荐。公钥指数e的大小直接影响了RSA算法的安全性和加密效率。通常情况下,e的值越小,加密速度越快,但安全性越低。

    参数:

    • bits: Int32 - 密钥长度,需要大于等于 512 位,并且小于等于 16384 位。

    异常:

    • CryptoException - 密钥长度不符合要求或初始化失败,抛出异常。

    init(Int32, BigInt)

    public init(bits: Int32, e: BigInt)
    

    功能:init 初始化生成私钥,允许用户指定公共指数。

    参数:

    • bits: Int32 - 密钥长度,需要大于等于 512 位,并且小于等于 16384 位,推荐使用的密钥长度不小于 3072 位。
    • e: BigInt - 公钥公共指数,范围是 [3, 2^256-1] 的奇数。

    异常:

    • CryptoException - 密钥长度不符合要求、公钥公共指数值不符合要求或初始化失败,抛出异常。

    func decodeDer(DerBlob)

    public static func decodeDer(blob: DerBlob): RSAPrivateKey
    

    功能:将私钥从 DER 格式解码。

    参数:

    • blob: DerBlob - 二进制格式的私钥对象。

    返回值:

    异常:

    func decodeDer(DerBlob, ?String)

    public static func decodeDer(blob: DerBlob, password!: ?String): RSAPrivateKey
    

    功能:将加密的私钥从 DER 格式解码。

    参数:

    • blob: DerBlob - 二进制格式的私钥对象。
    • password!: ?String - 解密私钥需要提供的密码,密码为 None 时则不解密。

    返回值:

    异常:

    • CryptoException - 解码失败、解密失败或者参数密码为空字符串,抛出异常。

    func decodeFromPem(String)

    public static func decodeFromPem(text: String): RSAPrivateKey
    

    功能:将私钥从 PEM 格式解码。

    参数:

    • text: String - PEM 格式的私钥字符流。

    返回值:

    异常:

    • CryptoException - 解码失败、解密失败、字符流不符合 PEM 格式或文件头不符合私钥头标准时,抛出异常。

    func decodeFromPem(String, ?String)

    public static func decodeFromPem(text: String, password!: ?String): RSAPrivateKey
    

    功能:将私钥从 PEM 格式解码。

    参数:

    • text: String - PEM 格式的私钥字符流。
    • password!: ?String - 解密私钥需要提供的密码,密码为 None 时则不解密。

    返回值:

    异常:

    • CryptoException - 解码失败、解密失败、参数密码为空字符串、字符流不符合 PEM 格式或文件头不符合私钥头标准时,抛出异常。

    func decrypt(InputStream, OutputStream, PadOption)

    public func decrypt(input: InputStream, output: OutputStream, padType!: PadOption): Unit
    

    功能:decrypt 解密出原始数据。

    参数:

    • input: InputStream - 加密的数据。
    • output: OutputStream - 解密后的数据。
    • padType!: PadOption - 填充模式,可以选择 PKCS1 或 OAEP 模式,不支持 PSS 模式,在对安全场景要求较高的情况下,推荐使用 OAEP 填充模式。

    异常:

    • CryptoException - 设置填充模式失败或解密失败,抛出异常。

    func encodeToDer()

    public override func encodeToDer(): DerBlob
    

    功能:将私钥编码为 DER 格式。

    返回值:

    • DerBlob - 编码后的DER格式私钥。

    异常:

    func encodeToDer(?String)

    public func encodeToDer(password!: ?String): DerBlob
    

    功能:使用 AES-256-CBC 加密私钥,将私钥编码为 DER 格式。

    参数:

    • password!: ?String - 加密私钥需要提供的密码,密码为 None 时则不加密。

    返回值:

    • DerBlob - 编码后的DER格式私钥。

    异常:

    • CryptoException - 编码失败、加密失败或者参数密码为空字符串,抛出异常。

    func encodeToPem()

    public override func encodeToPem(): PemEntry
    

    功能:将私钥编码为 PEM 格式。

    返回值:

    • PemEntry - 私钥PEM 格式的对象。

    异常:

    func sign(Digest, Array<Byte>, PadOption)

    public func sign(hash: Digest, digest: Array<Byte>, padType!: PadOption): Array<Byte>
    

    功能:对数据的摘要结果进行签名。

    参数:

    • hash: Digest - 摘要方法,获取 digest 结果使用的摘要方法。
    • digest: Array<Byte> - 数据的摘要结果。
    • padType!: PadOption - 填充模式,可以选择 PKCS1 或 PSS 模式,不支持 OAEP 模式,在对安全场景要求较高的情况下,推荐使用 PSS 填充模式。

    返回值:

    异常:

    • CryptoException - 设置摘要方法失败、设置填充模式失败或签名失败,抛出异常。

    func toString()

    public override func toString(): String
    

    功能:输出私钥种类。

    返回值:

    • String - 密钥类别描述。

    class RSAPublicKey

    public class RSAPublicKey <: PublicKey {
        public init(pri: RSAPrivateKey)
    }
    

    功能:RSA 公钥类,提供生成 RSA 公钥能力,RSA 公钥支持验证签名和加密操作,支持 PEM 和 DER 格式的编码解码。

    父类型:

    init(RSAPrivateKey)

    public init(pri: RSAPrivateKey)
    

    功能:init 初始化公钥,从私钥中获取对应的公钥。

    参数:

    异常:

    func decodeDer(DerBlob)

    public static func decodeDer(blob: DerBlob): RSAPublicKey
    

    功能:将公钥从 DER 格式解码。

    参数:

    • blob: DerBlob - 二进制格式的公钥对象。

    返回值:

    异常:

    func decodeFromPem(String)

    public static func decodeFromPem(text: String): RSAPublicKey
    

    功能:将公钥从PEM 格式解码。

    参数:

    • text: String - PEM 格式的公钥字符流。

    返回值:

    异常:

    • CryptoException - 解码失败、字符流不符合 PEM 格式或文件头不符合公钥头标准时,抛出异常。

    func encodeToDer()

    public override func encodeToDer(): DerBlob
    

    功能:将公钥编码为 DER 格式。

    返回值:

    • DerBlob - 编码后的Der格式公钥。

    异常:

    func encodeToPem()

    public override func encodeToPem(): PemEntry
    

    功能:将公钥编码为 PEM 格式。

    返回值:

    异常:

    func encrypt(InputStream, OutputStream, PadOption)

    public func encrypt(input: InputStream, output: OutputStream, padType!: PadOption): Unit
    

    功能:encrypt 给一段数据进行加密。

    参数:

    • input: InputStream - 需要加密的数据。
    • output: OutputStream - 加密后的数据。
    • padType!: PadOption - 填充模式,可以选择 PKCS1 或 OAEP 模式,不支持 PSS 模式,在对安全场景要求较高的情况下,推荐使用 OAEP 填充模式。

    异常:

    • CryptoException - 设置填充模式失败或加密失败,抛出异常。

    func toString()

    public override func toString(): String
    

    功能:输出公钥种类。

    返回值:

    • String - 密钥类别描述。

    func verify(Digest, Array<Byte>, Array<Byte>, PadOption)

    public func verify(hash: Digest, digest: Array<Byte>, sig: Array<Byte>, padType!: PadOption): Bool
    

    功能:verify 验证签名结果。

    参数:

    • hash: Digest - 摘要方法,获取 digest 结果使用的摘要方法。
    • digest: Array<Byte> - 数据的摘要结果。
    • sig: Array<Byte> - 数据的签名结果。
    • padType!: PadOption - 填充模式,可以选择 PKCS1 或 PSS 模式,不支持 OAEP 模式,在对安全场景要求较高的情况下,推荐使用 PSS 填充模式。

    返回值:

    • Bool - 返回 true 表示验证成功,false 失败。

    异常:

    • CryptoException - 设置填充模式失败或验证失败,抛出异常。

    class SM2PrivateKey

    public class SM2PrivateKey <: PrivateKey {
        public init()
    }
    

    功能:SM2 私钥类,提供生成 SM2 私钥能力,SM2 私钥支持签名和解密操作,支持 PEM 和 DER 格式的编码解码,符合 PKCS1 标准。

    父类型:

    init()

    public init()
    

    功能:init 初始化生成私钥。

    异常:

    func decodeDer(DerBlob)

    public static func decodeDer(blob: DerBlob): SM2PrivateKey
    

    功能:将私钥从 DER 格式解码。

    参数:

    • blob: DerBlob - 二进制格式的私钥对象。

    返回值:

    异常:

    func decodeDer(DerBlob, ?String)

    public static func decodeDer(blob: DerBlob, password!: ?String): SM2PrivateKey
    

    功能:将加密的私钥从 DER 格式解码。

    参数:

    • blob: DerBlob - 二进制格式的私钥对象。
    • password!: ?String - 解密私钥需要提供的密码,密码为 None 时则不解密。

    返回值:

    异常:

    • CryptoException - 解码失败、解密失败或者参数密码为空字符串,抛出异常。

    func decodeFromPem(String)

    public static func decodeFromPem(text: String): SM2PrivateKey
    

    功能:将私钥从 PEM 格式解码。

    参数:

    • text: String - PEM 格式的私钥字符流。

    返回值:

    异常:

    • CryptoException - 解码失败、解密失败、字符流不符合 PEM 格式或文件头不符合私钥头标准时,抛出异常。

    func decodeFromPem(String, ?String)

    public static func decodeFromPem(text: String, password!: ?String): SM2PrivateKey
    

    功能:将私钥从 PEM 格式解码。

    参数:

    • text: String - PEM 格式的私钥字符流。
    • password!: ?String - 解密私钥需要提供的密码,密码为 None 时则不解密。

    返回值:

    异常:

    • CryptoException - 解码失败、解密失败、参数密码为空字符串、字符流不符合 PEM 格式或文件头不符合私钥头标准时,抛出异常。

    func decrypt(Array<Byte>)

    public func decrypt(input: Array<Byte>): Array<Byte>
    

    功能:decrypt 解密出原始数据。

    参数:

    返回值:

    异常:

    func encodeToDer()

    public func encodeToDer(): DerBlob
    

    功能:将私钥编码为 DER 格式。

    返回值:

    • DerBlob - 编码后的DER格式私钥。

    异常:

    func encodeToDer(?String)

    public func encodeToDer(password!: ?String): DerBlob
    

    功能:使用 AES-256-CBC 加密私钥,将私钥编码为 DER 格式。

    参数:

    • password!: ?String - 加密私钥需要提供的密码,密码为 None 时则不加密。

    返回值:

    • DerBlob - 编码后的DER格式公钥。

    异常:

    • CryptoException - 编码失败、加密失败或者参数密码为空字符串,抛出异常。

    func encodeToPem(?String)

    public func encodeToPem(password!: ?String): PemEntry 
    

    功能:将加密的私钥编码为 PEM 格式。

    参数:

    • password!: ?String - 加密私钥需要提供的密码,密码为 None 时则不加密。

    返回值:

    • PemEntry - 私钥PEM 格式的对象。

    异常:

    • CryptoException - 编码失败、加密失败或者参数密码为空字符串,抛出异常。

    func encodeToPem()

    public func encodeToPem(): PemEntry
    

    功能:将私钥编码为 PEM 格式。

    返回值:

    • PemEntry - 私钥PEM 格式的对象。

    异常:

    func sign(Array<Byte>)

    public func sign(data: Array<Byte>): Array<Byte>
    

    功能:sign 对数据进行签名, SM2采用SM3数据摘要算法。

    参数:

    返回值:

    异常:

    func toString

    public override func toString(): String
    

    功能:输出私钥种类。

    返回值:

    • String - 密钥类别描述。

    class SM2PublicKey

    public class SM2PublicKey <: PublicKey {
        public init(pri: SM2PrivateKey)
    }
    

    功能:SM2 公钥类,提供生成 SM2 公钥能力,SM2 公钥支持验证签名和加密操作,支持 PEM 和 DER 格式的编码解码。

    父类型:

    init(SM2PrivateKey)

    public init(pri: SM2PrivateKey)
    

    功能:init 初始化公钥,从私钥中获取对应的公钥。

    参数:

    异常:

    func decodeDer(DerBlob)

    public static func decodeDer(blob: DerBlob): SM2PublicKey
    

    功能:将公钥从 DER 格式解码。

    参数:

    • blob: DerBlob - 二进制格式的公钥对象。

    返回值:

    异常:

    func decodeFromPem(String)

    public static func decodeFromPem(text: String): SM2PublicKey
    

    功能:将公钥从PEM 格式解码。

    参数:

    • text: String - PEM 格式的公钥字符流。

    返回值:

    异常:

    • CryptoException - 解码失败、字符流不符合 PEM 格式或文件头不符合公钥头标准时,抛出异常。

    func encodeToDer()

    public func encodeToDer(): DerBlob
    

    功能:将公钥编码为 DER 格式。

    返回值:

    • DerBlob - 编码后的Der格式公钥。

    异常:

    func encodeToPem()

    public func encodeToPem(): PemEntry
    

    功能:将公钥编码为 PEM 格式。

    返回值:

    异常:

    func encrypt(Array<Byte>)

    public func encrypt(input: Array<Byte>): Array<Byte> 
    

    功能:encrypt 给一段数据进行加密。

    参数:

    • input: Array<Byte> - 需要加密的数据。

    返回值:

    异常:

    func toString()

    public override func toString(): String
    

    功能:输出公钥种类。

    返回值:

    • String - 密钥类别描述。

    func verify(Array<Byte>, Array<Byte>)

    public func verify(data: Array<Byte>, sig: Array<Byte>): Bool
    

    功能:verify 验证签名结果。

    参数:

    返回值:

    • Bool - 返回 true 表示验证成功,false 失败。

    异常:

    • CryptoException - 设置填充模式失败或验证失败,抛出异常。

    枚举

    enum Curve

    public enum Curve {
        | P224 | P256 | P384 | P521 | BP256 | BP320 | BP384 | BP512
    }
    

    功能:枚举类型 Curve 用于选择生成 ECDSA 密钥时使用的椭圆曲线类型。

    椭圆曲线是一种数学曲线,常用于加密算法中的密钥生成。在密码学中,椭圆曲线密码算法是一种基于椭圆曲线的公钥密码算法。它的基本思想是利用椭圆曲线上的点集构成一个计算困难性,来实现公钥密码的安全性。

    Curve 枚举类型支持 NIST P-224,NIST P-256,NIST P-384,NIST P-521,Brainpool P-256,Brainpool P-320,Brainpool P-384,Brainpool P-512 八种椭圆曲线。

    • NIST P-224:基于椭圆曲线的加密算法,使用224位的素数作为模数,安全性较高,适用于轻量级应用。

    • NIST P-256:基于椭圆曲线的加密算法,使用256位的素数作为模数,安全性较高,适用于中等级应用。

    • NIST P-384:基于椭圆曲线的加密算法,使用384位的素数作为模数,安全性非常高,适用于高级别应用。

    • NIST P-521:基于椭圆曲线的加密算法,使用521位的素数作为模数,安全性非常高,适用于极高级别应用。

    • Brainpool P-256:基于椭圆曲线的加密算法,使用256位的素数作为模数,安全性较高,但比NIST P-256更快。

    • Brainpool P-320:基于椭圆曲线的加密算法,使用320位的素数作为模数,安全性非常高,但比NIST P-384更快。

    • Brainpool P-384:基于椭圆曲线的加密算法,使用384位的素数作为模数,安全性非常高,但比NIST P-384更快。

    • Brainpool P-512:基于椭圆曲线的加密算法,使用512位的素数作为模数,安全性非常高,但比NIST P-521更快

    BP256

    BP256
    

    功能:使用 Brainpool P-256 椭圆曲线初始化 Curve 实例。

    BP320

    BP320
    

    功能:使用 Brainpool P-320 椭圆曲线初始化 Curve 实例。

    BP384

    BP384
    

    功能:使用 Brainpool P-384 椭圆曲线初始化 Curve 实例。

    BP512

    BP512
    

    功能:使用 Brainpool P-512 椭圆曲线初始化 Curve 实例。

    P224

    P224
    

    功能:使用 NIST P-224 椭圆曲线初始化 Curve 实例。

    P256

    P256
    

    功能:使用 NIST P-256 椭圆曲线初始化 Curve 实例。

    P384

    P384
    

    功能:使用 NIST P-384 椭圆曲线初始化 Curve 实例。

    P521

    P521
    

    功能:使用 NIST P-521 椭圆曲线初始化 Curve 实例。

    enum PadOption

    public enum PadOption {
        | OAEP(OAEPOption) | PSS(PSSOption) | PKCS1
    }
    

    功能:用于设置 RSA 的填充模式。

    RSA 有三种常用的填充模式:

    OAEP 为最优非对称加密填充,只能用于加密解密; PSS 为概率签名方案,只能用于签名和验证; PKCS1 是一种普通的填充模式,用于填充数据长度,可以用于加密、解密、签名和验证。 RSA 的 PKCS1 填充模式是在早期的 PKCS #1 v1.5 规范中定义的填充模式,当前对使用 PKCS1 填充模式的攻击较为成熟,容易被攻击者解密或伪造签名,建议采用 PKCS #1 v2 版本中更加安全的 PSS 或 OAEP 填充模式。

    OAEP(OAEPOption)

    OAEP(OAEPOption)
    

    功能:使用最优非对称加密初始化 PadOption 实例。

    PKCS1

    PKCS1
    

    功能:使用 PKCS #1 公钥密码学标准初始化 PadOption 实例。

    PSS(PSSOption)

    PSS(PSSOption)
    

    功能:使用概率签名方案初始化 PadOption 实例。

    结构体

    struct OAEPOption

    public struct OAEPOption {
        public init(hash: Digest, mgfHash: Digest, label!: String = "")
    }
    

    功能:此结构体为 OAEP 填充模式需要设置的参数。

    init(Digest, Digest, String)

    public init(hash: Digest, mgfHash: Digest, label!: String = "")
    

    功能:初始化 OAEP 填充参数。

    参数:

    • hash: Digest - 摘要方法,用于对 label 进行摘要。
    • mgfHash: Digest - 摘要方法,用于设置 MGF1 函数中的摘要方法。
    • label!: String - label 是可选参数,默认为空字符串,可以通过设置 label 来区分不同的加密操作。

    struct PSSOption

    public struct PSSOption {
        public init(saltLen: Int32)
    }
    

    此结构体为 PSS 填充模式需要设置的参数。

    init(Int32)

    public init(saltLen: Int32)
    

    功能:初始化 PSS 填充参数。

    参数:

    • saltLen: Int32 - 随机盐长度,长度应大于等于 0,小于等于(RSA 长度 - 摘要长度 - 2),长度单位为字节,长度过长会导致签名失败。

    异常:

    keys 使用

    RSA 密钥示例

    生成 rsa 公钥及私钥,并使用公钥的 OAEP 填充模式加密,用私钥的 OAEP 填充模式解密

    import crypto.keys.*
    import crypto.digest.*
    import std.io.*
    import std.crypto.digest.*
    
    main() {
        var rsaPri = RSAPrivateKey(2048)
        var rsaPub = RSAPublicKey(rsaPri)
    
        var str: String = "hello world, hello cangjie"
        var bas1 = ByteBuffer()
        var bas2 = ByteBuffer()
        var bas3 = ByteBuffer()
        bas1.write(str.toArray())
    
        var encOpt = OAEPOption(SHA1(), SHA256())
        rsaPub.encrypt(bas1, bas2, padType: OAEP(encOpt))
        var encOpt2 = OAEPOption(SHA1(), SHA256())
        rsaPri.decrypt(bas2, bas3, padType: OAEP(encOpt2))
    
        var buf = Array<Byte>(str.size, repeat:0)
        bas3.read(buf)
        if (str.toArray() == buf){
            println("success")
        } else {
            println("fail")
        }
    }
    

    运行结果:

    success
    

    从文件中读取 rsa 公钥和私钥,并使用私钥的 PKCS1 填充模式签名,用公钥的 PKCS1 填充模式验证签名结果

    说明: >

    • 需要自行准备公私钥文件。
    import crypto.keys.*
    import crypto.digest.*
    import std.crypto.digest.*
    import std.fs.*
    import std.io.*
    
    main() {
        var pemPri = String.fromUtf8(readToEnd(File("./files/rsaPri.pem", OpenOption.Open(true, false))))
        var rsaPri = RSAPrivateKey.decodeFromPem(pemPri)
    
        var pemPub = String.fromUtf8(readToEnd(File("./files/rsaPub.pem", OpenOption.Open(true, false))))
        var rsaPub = RSAPublicKey.decodeFromPem(pemPub)
    
        var str: String = "helloworld"
        var sha512Instance = SHA512()
        var md: Array<Byte> = digest(sha512Instance, str)
    
        var sig = rsaPri.sign(sha512Instance, md, padType: PKCS1)
        if (rsaPub.verify(sha512Instance, md, sig, padType: PKCS1)){
            println("verify successful")
        }
    }
    

    运行结果:

    verify successful
    

    ECDSA 密钥示例

    使用 ECDSA 密钥使用示例。

    生成 ECDSA 公钥及私钥,并使用私钥签名,公钥验证签名结果

    import crypto.keys.*
    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    
    main() {
        var ecPri = ECDSAPrivateKey(P224)
        var ecPub = ECDSAPublicKey(ecPri)
    
        var str: String = "helloworld"
        var sha512Instance = SHA512()
        var md: Array<Byte> = digest(sha512Instance, str)
    
        var sig = ecPri.sign(md)
        if (ecPub.verify(md, sig)){
            println("verify successful")
        }
    }
    

    运行结果:

    verify successful
    

    SM2 密钥示例

    生成 SM2 公钥及私钥,并使用私钥签名,公钥验证签名结果

    import crypto.keys.*
    import crypto.digest.*
    import std.convert.*
    import std.crypto.digest.*
    import std.fs.*
    import std.io.*
    
    main(): Unit {
        // 无参生成公钥私钥
        let sm2PrivateKey = SM2PrivateKey()
        let sm2PublicKey = SM2PublicKey(sm2PrivateKey)
    
        //公钥和私钥导出
        let priPem = sm2PrivateKey.encodeToPem()
        let file1: File = File("./sm2Pri.pem", OpenOption.CreateOrTruncate(true))
        file1.write(priPem.encode().toArray())
        file1.close()
    
        let pubPem = sm2PublicKey.encodeToPem()
        let file2: File = File("./sm2Pub.pem", OpenOption.CreateOrTruncate(true))
        file2.write(pubPem.encode().toArray())
        file2.close()
    
        //公钥加密 私钥解密
        let str: String = "helloworld"
        let encresult = sm2PublicKey.encrypt(str.toArray())
        let decresult = sm2PrivateKey.decrypt(encresult)
        println(String.fromUtf8(decresult))
    
        //私钥签名 公钥验证
        let strSig: String = "helloworld"
        let sigRe = sm2PrivateKey.sign(strSig.toArray())
        let verifyre  = sm2PublicKey.verify(strSig.toArray(), sigRe)
        println(verifyre)
    
        // 私钥公钥导入
        let pemPri = String.fromUtf8(readToEnd(File("./sm2Pri.pem", OpenOption.Open(true, false))))
        let sm2PrivateKeyNew = SM2PrivateKey.decodeFromPem(pemPri)
        let pemPub = String.fromUtf8(readToEnd(File("./sm2Pub.pem", OpenOption.Open(true, false))))
        let sm2PublicKeyNew = SM2PublicKey.decodeFromPem(pemPub)
    
        }
    

    运行结果:

    helloworld
    true
    

    crypto.x509 包

    功能介绍

    x509 包提供处理数字证书功能,提供包括解析和序列化 X509 证书、验证证书、创建自签名证书、创建和验证证书链等主要功能。

    使用本包需要外部依赖 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 中。

    说明:

    如果未安装 OpenSSL 3 软件包或者安装低版本的软件包,程序可能无法使用并抛出相关异常 X509Exception: Can not load openssl library or function xxx。

    API 列表

    类型别名

    类型别名功能
    IPx509 用 Array<Byte> 来记录 IP。

    接口

    接口名功能
    DHParamters提供 DH 密钥接口。
    Key提供密钥接口。
    PrivateKey提供私钥接口。
    PublicKey提供公钥接口。

    类名功能
    X509CertificateX509 数字证书是一种用于加密通信的数字证书。
    X509CertificateRequest数字证书签名请求。
    X509Name证书实体可辨识名称。

    枚举

    枚举名功能
    PublicKeyAlgorithm数字证书中包含的公钥信息。
    SignatureAlgorithm证书签名算法。

    结构体

    结构体名功能
    DerBlobCrypto 支持配置二进制证书流。
    ExtKeyUsage数字证书扩展字段。
    KeyUsage数字证书扩展字段中通常会包含携带公钥的用法说明。
    PemPem 结构体。
    PemEntryPEM 文本格式。
    SerialNumber数字证书的序列号。
    Signature数字证书的签名。
    VerifyOption校验选项。
    X509CertificateInfo证书信息。
    X509CertificateRequestInfo证书请求信息。

    异常类

    异常类名功能
    X509Exceptionx509 包的异常类。

    类型别名

    type IP

    public type IP = Array<Byte>
    

    功能:x509包用 Array<Byte> 来记录 IP

    接口

    interface DHParamters

    public interface DHParamters <: Key {
        override func encodeToPem(): PemEntry
        static func decodeDer(blob: DerBlob): DHParamters
        static func decodeFromPem(text: String): DHParamters
    }
    

    功能:提供 DH 参数接口。

    父类型:

    static func decodeDer(DerBlob)

    static func decodeDer(blob: DerBlob): DHParamters
    

    功能:将 DH 密钥参数从 DER 格式解码。

    说明:

    • DH(Diffie-Hellman)密钥交换协议是一种确保共享KEY安全穿越不安全网络的方法。
    • DER 和 PEM 是两种常见的编码格式。

    参数:

    • blob: DerBlob - DER 格式的 DH 密钥参数对象。

    返回值:

    • DHParamters - 由 DER 格式解码出的 DH 密钥参数。

    异常:

    • X509Exception - 当 DER 格式的 DH 密钥参数内容不正确,无法解析时抛出异常。

    static func decodeFromPem(String)

    static func decodeFromPem(text: String): DHParamters
    

    功能:将 DH 密钥参数从 PEM 格式解码。

    说明:

    PEM 是用 ASCLL(BASE64)编码的证书。

    参数:

    • text: String - PEM 格式的 DH 密钥参数字符流。

    返回值:

    • DHParamters - 由 PEM 格式解码出的 DH 密钥参数。

    异常:

    • X509Exception - 字符流不符合 PEM 格式时,或文件头不符合 DH 密钥参数头标准 ("-----BEGIN DH PARAMETERS-----")时抛出异常。

    func encodeToPem()

    override func encodeToPem(): PemEntry
    

    功能:将 DH 密钥参数编码为 PEM 格式。

    返回值:

    • PemEntry - DH 密钥参数数据 PEM 格式编码生成的对象。

    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 及用户扩展接口。

    父类型:

    static func decodeDer(DerBlob)

    static func decodeDer(encoded: DerBlob): Key
    

    功能:将密钥从 DER 格式解码。

    参数:

    • encoded: DerBlob - DER 格式的对象。

    返回值:

    • Key - 由 DER 格式解码出的密钥。

    异常:

    • X509Exception - 当 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 {
        static func decodeDer(blob: DerBlob): PrivateKey
        static func decodeFromPem(text: String): PrivateKey
        static func decodeDer(blob: DerBlob, password!: ?String): PrivateKey
        static func decodeFromPem(text: String, password!: ?String): PrivateKey
        func encodeToDer(password!: ?String): DerBlob
        override func encodeToPem(): PemEntry
        func encodeToPem(password!: ?String): PemEntry
    }
    

    功能:提供私钥接口。

    父类型:

    static func decodeDer(DerBlob)

    static func decodeDer(blob: DerBlob): PrivateKey
    

    功能:将私钥从 DER 格式解码。

    参数:

    • blob: DerBlob - DER 格式的私钥对象。

    返回值:

    • PrivateKey - 由 DER 格式解码出的私钥。

    异常:

    • X509Exception - 当 DER 格式的私钥内容不正确,无法解析时抛出异常。

    static func decodeDer(DerBlob, ?String)

    static func decodeDer(blob: DerBlob, password!: ?String): PrivateKey 
    

    功能:将 DER 格式的私钥解密解码成 PrivateKey 对象,密码为 None 时则不解密。

    参数:

    • blob: DerBlob - DER 格式的私钥。
    • password!: ?String - 解密密码。

    返回值:

    异常:

    • X509Exception - 解密解码失败,或者 password 为空字符串。

    static func decodeFromPem(String)

    static func decodeFromPem(text: String): PrivateKey
    

    功能:将私钥从 PEM 格式解码。

    参数:

    • text: String - PEM 格式的私钥字符流。

    返回值:

    • PrivateKey - 由 PEM 格式解码出的私钥。

    异常:

    • X509Exception - 字符流不符合 PEM 格式时,或文件头不符合公钥头标准时抛出异常。

    static func decodeFromPem(String, ?String)

    static func decodeFromPem(text: String, password!: ?String): PrivateKey 
    

    功能:将 PEM 格式的私钥解密解码成 PrivateKey 对象,密码为 None 时则不解密。

    参数:

    • text: String - PEM 格式的私钥。
    • password!: ?String - 解密密码。

    返回值:

    异常:

    • X509Exception - 解密解码失败,或者 password 为空字符串。

    func encodeToDer(?String)

    func encodeToDer(password!: ?String): DerBlob
    

    功能:将私钥加密编码成 DER 格式,密码为 None 时则不加密。

    参数:

    • password!: ?String - 加密密码。

    返回值:

    • DerBlob - 加密后的 DER 格式的私钥。

    异常:

    • X509Exception - 加密失败,或者 password 为空字符串。

    func encodeToPem()

    override func encodeToPem(): PemEntry
    

    功能:将私钥编码成 PEM 格式。

    返回值:

    • PemEntry - 编码后的 PEM 格式的私钥。

    异常:

    func encodeToPem(?String)

    func encodeToPem(password!: ?String): PemEntry
    

    功能:将私钥加密编码成 PEM 格式,密码为 None 时则不加密。

    参数:

    • password!: ?String - 加密密码。

    返回值:

    • PemEntry - 加密后的 PEM 格式的私钥。

    异常:

    • X509Exception - 加密失败,或者 password 为空字符串。

    interface PublicKey

    public interface PublicKey <: Key {
        override func encodeToPem(): PemEntry
        static func decodeDer(blob: DerBlob): PublicKey
        static func decodeFromPem(text: String): PublicKey
    }
    

    功能:公钥接口。

    父类型:

    static func decodeDer(DerBlob)

    static func decodeDer(blob: DerBlob): PublicKey
    

    功能:将公钥从 DER 格式解码。

    参数:

    • blob: DerBlob - DER 格式的公钥对象。

    返回值:

    • PublicKey - 由 DER 格式解码出的公钥。

    异常:

    • X509Exception - 当 DER 格式的公钥内容不正确,无法解析时抛出异常。

    static func decodeFromPem(String)

    static func decodeFromPem(text: String): PublicKey
    

    功能:将公钥从 PEM 格式解码。

    参数:

    • text: String - PEM 格式的公钥字符流。

    返回值:

    • PublicKey - 由 PEM 格式解码出的公钥。

    异常:

    • X509Exception - 字符流不符合 PEM 格式时,或文件头不符合公钥头标准时抛出异常。

    func encodeToPem()

    override func encodeToPem(): PemEntry
    

    功能:将公钥编码为 PEM 格式。

    返回值:

    • PemEntry - 公钥数据 PEM 格式编码生成的对象。

    x509 包

    class X509Certificate

    public class X509Certificate <: Equatable<X509Certificate> & Hashable & ToString {
        public init(
            certificateInfo: X509CertificateInfo,
            parent!: X509Certificate,
            publicKey!: PublicKey,
            privateKey!: PrivateKey,
            signatureAlgorithm!: ?SignatureAlgorithm = None
        )
    
        public func encodeToDer(): DerBlob
        public func encodeToPem(): PemEntry
        public static func decodeFromDer(der: DerBlob): X509Certificate
        public static func decodeFromPem(pem: String): Array<X509Certificate>
        public static func systemRootCerts(): Array<X509Certificate>
    
        public prop serialNumber: SerialNumber
        public prop signatureAlgorithm: SignatureAlgorithm
        public prop signature: Signature
        public prop issuer: X509Name
        public prop subject: X509Name
        public prop notBefore: DateTime
        public prop notAfter: DateTime
        public prop publicKeyAlgorithm: PublicKeyAlgorithm
        public prop publicKey: PublicKey
        public prop dnsNames: Array<String>
        public prop emailAddresses: Array<String>
        public prop IPAddresses: Array<IP>
        public prop keyUsage: KeyUsage
        public prop extKeyUsage: ExtKeyUsage
    
        public func verify(verifyOption: VerifyOption): Bool
    
        public override func toString(): String
        public override operator func ==(other: X509Certificate): Bool
        public override operator func !=(other: X509Certificate): Bool
        public override func hashCode(): Int64
    }
    

    功能:X509 数字证书是一种用于加密通信的数字证书,它是公钥基础设施(PKI)的核心组件之一。X509 数字证书包含了一个实体的公钥和身份信息,用于验证该实体的身份和确保通信的安全性。

    父类型:

    prop dnsNames

    public prop dnsNames: Array<String>
    

    功能:解析数字证书备选名称中的域名。

    类型:Array<String>

    prop emailAddresses

    public prop emailAddresses: Array<String>
    

    功能:解析数字证书备选名称中的 email 地址。

    类型:Array<String>

    prop extKeyUsage

    public prop extKeyUsage: ExtKeyUsage
    

    功能:解析数字证书中的扩展密钥用法。

    类型:ExtKeyUsage

    prop issuer

    public prop issuer: X509Name
    

    功能:解析数字证书的颁发者信息。

    类型:X509Name

    prop IPAddresses

    public prop IPAddresses: Array<IP>
    

    功能:解析数字证书备选名称中的 IP 地址。

    类型:Array<IP>

    prop keyUsage

    public prop keyUsage: KeyUsage
    

    功能:解析数字证书中的密钥用法。

    类型:KeyUsage

    prop notAfter

    public prop notAfter: DateTime
    

    功能:解析数字证书的有效期截止时间。

    类型:DateTime

    prop notBefore

    public prop notBefore: DateTime
    

    功能:解析数字证书的有效期开始时间。

    类型:DateTime

    prop publicKey

    public prop publicKey: PublicKey
    

    功能:解析数字证书的公钥。

    类型:PublicKey

    prop publicKeyAlgorithm

    public prop publicKeyAlgorithm: PublicKeyAlgorithm
    

    功能:解析数字证书的公钥算法。

    类型:PublicKeyAlgorithm

    prop serialNumber

    public prop serialNumber: SerialNumber
    

    功能:解析数字证书的序列号。

    类型:SerialNumber

    prop signature

    public prop signature: Signature
    

    功能:解析数字证书的签名。

    类型:Signature

    prop signatureAlgorithm

    public prop signatureAlgorithm: SignatureAlgorithm
    

    功能:解析数字证书的签名算法。

    类型:SignatureAlgorithm

    prop subject

    public prop subject: X509Name
    

    功能:解析数字证书的使用者信息。

    类型:X509Name

    init(X509CertificateInfo, X509Certificate, PublicKey, PrivateKey, ?SignatureAlgorithm)

    public init(
        certificateInfo: X509CertificateInfo,
        parent!: X509Certificate,
        publicKey!: PublicKey,
        privateKey!: PrivateKey,
        signatureAlgorithm!: ?SignatureAlgorithm = None
    )
    

    功能:创建数字证书对象。

    参数:

    • certificateInfo: X509CertificateInfo - 数字证书配置信息。
    • parent!: X509Certificate - 颁发者证书。
    • publicKey!: PublicKey - 申请人公钥,仅支持 RSA、ECDSA 和 DSA 公钥。
    • privateKey!: PrivateKey - 颁发者私钥,仅支持 RSA、ECDSA 和 DSA 私钥。
    • signatureAlgorithm!: ?SignatureAlgorithm - 证书签名算法,默认值为 None,使用默认值时默认的摘要类型是 SHA256

    异常:

    • X509Exception - 公钥或私钥类型不支持、私钥类型和证书签名算法中的私钥类型不匹配或数字证书信息设置失败时,抛出异常。

    static func decodeFromDer(DerBlob)

    public static func decodeFromDer(der: DerBlob): X509Certificate
    

    功能:将 DER 格式的数字证书解码。

    参数:

    • der: DerBlob - DER 格式的二进制数据。

    返回值:

    异常:

    • X509Exception - 数据为空时,或数据不是有效的数字证书 DER 格式时抛出异常。

    static func decodeFromPem(String)

    public static func decodeFromPem(pem: String): Array<X509Certificate>
    

    功能:将数字证书从 PEM 格式解码。

    参数:

    • pem: String - PEM 格式的数字证书字符流。

    返回值:

    异常:

    • X509Exception - 字符流不符合 PEM 格式时,或文件头不符合数字证书头标准时抛出异常。

    func encodeToDer()

    public func encodeToDer(): DerBlob
    

    功能:将数字证书编码成 Der 格式。

    返回值:

    • DerBlob - 编码后的 Der 格式的数字证书。

    func encodeToPem()

    public func encodeToPem(): PemEntry
    

    功能:将数字证书编码成 PEM 格式。

    返回值:

    • PemEntry - 编码后的 PEM 格式的数字证书。

    func hashCode()

    public override func hashCode(): Int64
    

    功能:返回证书哈希值。

    返回值:

    • Int64 - 对证书对象进行哈希计算后得到的结果。

    static func systemRootCerts()

    public static func systemRootCerts(): Array<X509Certificate>
    

    功能:返回操作系统的根证书,支持 Linux,MacOS 和 Windows 平台。

    返回值:

    func toString()

    public override func toString(): String
    

    功能:生成证书名称字符串,包含证书的使用者信息、有效期以及颁发者信息。

    返回值:

    • String - 证书名称字符串。

    func verify(VerifyOption)

    public func verify(verifyOption: VerifyOption): Bool
    

    功能:根据验证选项验证当前证书的有效性。

    验证优先级:

    1. 优先验证有效期;
    2. 可选验证DNS域名;
    3. 最后根据根证书和中间证书验证其有效性。

    参数:

    返回值:

    • Bool - 证书有效返回 true,否则返回 false。

    异常:

    • X509Exception - 检验过程中失败,比如内存分配异常等内部错误,则抛出异常。

    operator func !=(X509Certificate)

    public override operator func !=(other: X509Certificate): Bool
    

    功能:判不等。

    参数:

    返回值:

    • Bool - 若证书不同,返回 true;否则,返回 false。

    operator func ==(X509Certificate)

    public override operator func ==(other: X509Certificate): Bool
    

    功能:判等。

    参数:

    返回值:

    • Bool - 若证书相同,返回 true;否则,返回 false。

    class X509CertificateRequest

    public class X509CertificateRequest <: Hashable & ToString {
        public init(
            privateKey: PrivateKey,
            certificateRequestInfo!: ?X509CertificateRequestInfo = None,
            signatureAlgorithm!: ?SignatureAlgorithm = None
        )
        public func encodeToDer(): DerBlob
        public func encodeToPem(): PemEntry
        public static func decodeFromDer(der: DerBlob): X509CertificateRequest
        public static func decodeFromPem(pem: String): Array<X509CertificateRequest>
        public prop signatureAlgorithm: SignatureAlgorithm
        public prop signature: Signature
        public prop publicKeyAlgorithm: PublicKeyAlgorithm
        public prop publicKey: PublicKey
        public prop subject: X509Name
        public prop dnsNames: Array<String>
        public prop emailAddresses: Array<String>
        public prop IPAddresses: Array<IP>
        public override func toString(): String
        public override func hashCode(): Int64
    }
    

    功能:数字证书签名请求。

    父类型:

    prop IPAddresses

    public prop IPAddresses: Array<IP>
    

    功能:解析数字证书签名请求备选名称中的 IP 地址。

    类型:Array<IP>

    prop dnsNames

    public prop dnsNames: Array<String>
    

    功能:解析数字证书签名请求备选名称中的域名。

    类型:Array<String>

    prop emailAddresses

    public prop emailAddresses: Array<String>
    

    功能:解析数字证书签名请求备选名称中的 email 地址。

    类型:Array<String>

    prop publicKey

    public prop publicKey: PublicKey
    

    功能:解析数字证书签名请求的公钥。

    类型:PublicKey

    prop publicKeyAlgorithm

    public prop publicKeyAlgorithm: PublicKeyAlgorithm
    

    功能:解析数字证书签名请求的公钥算法。

    类型:PublicKeyAlgorithm

    prop signature

    public prop signature: Signature
    

    功能:解析数字证书签名请求的签名。

    类型:Signature

    prop signatureAlgorithm

    public prop signatureAlgorithm: SignatureAlgorithm
    

    功能:解析数字证书签名请求的签名算法。

    类型:SignatureAlgorithm

    prop subject

    public prop subject: X509Name
    

    功能:解析数字证书签名请求的使用者信息。

    类型:X509Name

    init(PrivateKey, ?X509CertificateRequestInfo, ?SignatureAlgorithm)

    public init(
        privateKey: PrivateKey,
        certificateRequestInfo!: ?X509CertificateRequestInfo = None,
        signatureAlgorithm!: ?SignatureAlgorithm = None
    )
    

    功能:创建数字证书签名请求对象。

    参数:

    • privateKey: PrivateKey - 私钥,仅支持 RSA、ECDSA 和 DSA 私钥。
    • certificateRequestInfo!: ?X509CertificateRequestInfo - 数字证书签名信息,默认值为 None。
    • signatureAlgorithm!: ?SignatureAlgorithm - 证书签名算法,默认值为 None,使用默认值时默认的摘要类型是 SHA256

    异常:

    • X509Exception - 私钥类型不支持、私钥类型和证书签名算法中的私钥类型不匹配或数字证书签名信息设置失败时,抛出异常。

    static func decodeFromDer(DerBlob)

    public static func decodeFromDer(der: DerBlob): X509CertificateRequest
    

    功能:将 DER 格式的数字证书签名请求解码。

    参数:

    • der: DerBlob - DER 格式的二进制数据。

    返回值:

    异常:

    • X509Exception - 数据为空时,或数据不是有效的数字证书签名请求 DER 格式时抛出异常。

    static func decodeFromPem(String)

    public static func decodeFromPem(pem: String): Array<X509CertificateRequest>
    

    功能:将数字证书签名请求从 PEM 格式解码。

    参数:

    • pem: String - PEM 格式的数字证书签名请求字符流。

    返回值:

    异常:

    • X509Exception - 字符流不符合 PEM 格式时,或文件头不符合数字证书签名请求头标准时抛出异常。

    func encodeToDer()

    public func encodeToDer(): DerBlob
    

    功能:将数字证书签名请求编码成 Der 格式。

    返回值:

    • DerBlob - 编码后的 Der 格式的数字证书签名请求。

    func encodeToPem()

    public func encodeToPem(): PemEntry
    

    功能:将数字证书签名请求编码成 PEM 格式。

    返回值:

    • PemEntry - 编码后的 PEM 格式的数字证书签名请求。

    func hashCode()

    public override func hashCode(): Int64
    

    功能:返回证书签名请求哈希值。

    返回值:

    • Int64 - 对证书签名请求对象进行哈希计算后得到的结果。

    func toString()

    public override func toString(): String
    

    功能:生成证书签名请求名称字符串,包含证书签名请求的使用者信息。

    返回值:

    • String - 证书签名请求名称字符串。

    class X509Name

    public class X509Name <: ToString {
        public init(
            countryName!: ?String = None,
            provinceName!: ?String = None,
            localityName!: ?String = None,
            organizationName!: ?String = None,
            organizationalUnitName!: ?String = None,
            commonName!: ?String = None,
            email!: ?String = None
        )
        public prop countryName: ?String
        public prop provinceName: ?String
        public prop localityName: ?String
        public prop organizationName: ?String
        public prop organizationalUnitName: ?String
        public prop commonName: ?String
        public prop email: ?String
        public override func toString(): String
    }
    

    功能:证书实体可辨识名称(Distinguished Name)是数字证书中的一个重要组成部分,作用是确保证书的持有者身份的真实性和可信度,同时也是数字证书验证的重要依据之一。

    X509Name 通常包含证书实体的国家或地区名称(Country Name)、州或省名称(State or Province Name)、城市名称(Locality Name)、组织名称(Organization Name)、组织单位名称(Organizational Unit Name)、通用名称(Common Name)。有时也会包含 email 地址。

    父类型:

    prop commonName

    public prop commonName: ?String
    

    功能:返回证书实体的通用名称。

    类型:?String

    prop countryName

    public prop countryName: ?String
    

    功能:返回证书实体的国家或地区名称。

    类型:?String

    prop email

    public prop email: ?String
    

    功能:返回证书实体的 email 地址。

    类型:?String

    prop localityName

    public prop localityName: ?String
    

    功能:返回证书实体的城市名称。

    类型:?String

    prop organizationName

    public prop organizationName: ?String
    

    功能:返回证书实体的组织名称。

    类型:?String

    prop organizationalUnitName

    public prop organizationalUnitName: ?String
    

    功能:返回证书实体的组织单位名称。

    类型:?String

    prop provinceName

    public prop provinceName: ?String
    

    功能:返回证书实体的州或省名称。

    类型:?String

    init(?String, ?String, ?String, ?String, ?String, ?String, ?String)

        public init(
            countryName!: ?String = None,
            provinceName!: ?String = None,
            localityName!: ?String = None,
            organizationName!: ?String = None,
            organizationalUnitName!: ?String = None,
            commonName!: ?String = None,
            email!: ?String = None
        )
    

    功能:构造 X509Name 对象。

    参数:

    • countryName!: ?String - 国家或地区名称,默认值为 None。
    • provinceName!: ?String - 州或省名称,默认值为 None。
    • localityName!: ?String - 城市名称,默认值为 None。
    • organizationName!: ?String - 组织名称,默认值为 None。
    • organizationalUnitName!: ?String - 组织单位名称,默认值为 None。
    • commonName!: ?String - 通用名称,默认值为 None。
    • email!: ?String - email 地址,默认值为 None。

    异常:

    • X509Exception - 设置证书实体可辨识名称时失败,比如内存分配异常等内部错误,则抛出异常。

    func toString()

    public override func toString(): String
    

    功能:生成证书实体名称字符串。

    返回值:

    • String - 证书实体名称字符串,包含实体名称中存在的字段信息。

    枚举

    enum PublicKeyAlgorithm

    public enum PublicKeyAlgorithm <: Equatable<PublicKeyAlgorithm> & ToString {
        RSA | DSA | ECDSA | UnknownPublicKeyAlgorithm
    }
    

    功能:数字证书中包含的公钥信息,目前支持的种类有:RSA、DSA、ECDSA。

    父类型:

    DSA

    DSA
    

    功能:DSA 公钥算法。

    ECDSA

    ECDSA
    

    功能:ECDSA 公钥算法。

    RSA

    RSA
    

    功能:RSA 公钥算法。

    UnknownPublicKeyAlgorithm

    UnknownPublicKeyAlgorithm
    

    功能:未知公钥算法。

    func toString()

    public override func toString(): String
    

    功能:生成证书携带的公钥算法名称字符串。

    返回值:

    • String - 证书携带的公钥算法名称字符串。

    operator func !=(PublicKeyAlgorithm)

    public override operator func !=(other: PublicKeyAlgorithm): Bool
    

    功能:判不等。

    参数:

    返回值:

    • Bool - 若公钥算法不同,返回 true;否则,返回 false。

    operator func ==(PublicKeyAlgorithm)

    public override operator func ==(other: PublicKeyAlgorithm): Bool
    

    功能:判等。

    参数:

    返回值:

    • Bool - 若公钥算法相同,返回 true;否则,返回 false。

    enum SignatureAlgorithm

    public enum SignatureAlgorithm <: Equatable<SignatureAlgorithm> & ToString {
        | MD2WithRSA | MD5WithRSA | SHA1WithRSA | SHA256WithRSA | SHA384WithRSA
        | SHA512WithRSA | DSAWithSHA1 | DSAWithSHA256 | ECDSAWithSHA1 | ECDSAWithSHA256
        | ECDSAWithSHA384 | ECDSAWithSHA512 | UnknownSignatureAlgorithm
    }
    

    功能:证书签名算法(Signature Algorithm)是用于数字证书签名的算法,它是一种将数字证书中的公钥和其他信息进行加密的算法,以确保数字证书的完整性和真实性。

    目前支持签名算法的种类包括:MD2WithRSA 、MD5WithRSA 、SHA1WithRSA 、SHA256WithRSA 、SHA384WithRSA、SHA512WithRSA、DSAWithSHA1、DSAWithSHA256、ECDSAWithSHA1、ECDSAWithSHA256、ECDSAWithSHA384 和 ECDSAWithSHA512。

    父类型:

    DSAWithSHA1

    DSAWithSHA1
    

    功能:DSAwithSHA1 签名算法。

    DSAWithSHA256

    DSAWithSHA256
    

    功能:DSAwithSHA256 签名算法。

    ECDSAWithSHA1

    ECDSAWithSHA1
    

    功能:ECDSAwithSHA1 签名算法。

    ECDSAWithSHA256

    ECDSAWithSHA256
    

    功能:ECDSAwithSHA256 签名算法。

    ECDSAWithSHA384

    ECDSAWithSHA384
    

    功能:ECDSAwithSHA384 签名算法。

    ECDSAWithSHA512

    ECDSAWithSHA512
    

    功能:ECDSAwithSHA512 签名算法。

    MD2WithRSA

    MD2WithRSA
    

    功能:MD2withRSA 签名算法。

    MD5WithRSA

    MD5WithRSA
    

    功能:MD5withRSA 签名算法。

    SHA1WithRSA

    SHA1WithRSA
    

    功能:SHA1withRSA签名算法。

    SHA256WithRSA

    SHA256WithRSA
    

    功能:SHA256withRSA 签名算法。

    SHA384WithRSA

    SHA384WithRSA
    

    功能:SHA384withRSA 签名算法。

    SHA512WithRSA

    SHA512WithRSA
    

    功能:SHA512withRSA 签名算法。

    UnknownSignatureAlgorithm

    UnknownSignatureAlgorithm
    

    功能:未知签名算法。

    func toString()

    public override func toString(): String
    

    功能:生成证书签名算法名称字符串。

    返回值:

    • String - 证书签名算法名称字符串。

    operator func !=

    public override operator func !=(other: SignatureAlgorithm): Bool
    

    功能:判不等。

    参数:

    返回值:

    • Bool - 若签名算法不同,返回 true;否则,返回 false。

    operator func ==

    public override operator func ==(other: SignatureAlgorithm): Bool
    

    功能:判等。

    参数:

    返回值:

    • Bool - 若签名算法相同,返回 true;否则,返回 false。

    结构体

    struct DerBlob

    public struct DerBlob <: Equatable<DerBlob> & Hashable {
        public init(content: Array<Byte>)
    }
    

    功能:Crypto 支持配置二进制证书流,用户读取二进制证书数据并创建 DerBlob 对象后可将其解析成 X509Certificate / X509CertificateRequest / PublicKey / PrivateKey 对象。

    父类型:

    prop body

    public prop body: Array<Byte>
    

    功能:DerBlob 对象中的字符序列。

    类型:Array<Byte>

    prop size

    public prop size: Int64
    

    功能:DerBlob 对象中字符序列的大小。

    类型:Int64

    init(Array)

    public init(content: Array<Byte>)
    

    功能:构造 DerBlob 对象。

    参数:

    • content: Array<Byte> - 二进制字符序列。

    func hashCode()

    public override func hashCode(): Int64
    

    功能:返回 DerBlob 对象哈希值。

    返回值:

    • Int64 - 对 DerBlob 对象进行哈希计算后得到的结果。

    operator func !=(DerBlob)

    public override operator func !=(other: DerBlob): Bool
    

    功能:判不等。

    参数:

    返回值:

    • Bool - 若对象不同,返回 true;否则,返回 false。

    operator func ==(DerBlob)

    public override operator func ==(other: DerBlob): Bool
    

    功能:判等。

    参数:

    返回值:

    • Bool - 若对象相同,返回 true;否则,返回 false。

    struct ExtKeyUsage

    public struct ExtKeyUsage <: ToString {
        public static let AnyKey = 0u16
        public static let ServerAuth = 1u16
        public static let ClientAuth = 2u16
        public static let EmailProtection = 3u16
        public static let CodeSigning = 4u16
        public static let OCSPSigning = 5u16
        public static let TimeStamping = 6u16
    
        public init(keys: Array<UInt16>)
    
        public override func toString(): String
    }
    

    功能:数字证书扩展字段中通常会包含携带扩展密钥用法说明,目前支持的用途有:ServerAuth、ClientAuth、EmailProtection、CodeSigning、OCSPSigning、TimeStamping。

    父类型:

    static let AnyKey

    public static let AnyKey = 0u16
    

    功能:表示应用于任意用途。

    类型:UInt16

    static let ClientAuth

    public static let ClientAuth = 2u16
    

    功能:表示用于 SSL 的客户端验证。

    类型:UInt16

    static let CodeSigning

    public static let CodeSigning = 4u16
    

    功能:表示用于代码签名。

    类型:UInt16

    static let EmailProtection

    public static let EmailProtection = 3u16
    

    功能:表示用于电子邮件的加解密、签名等。

    类型:UInt16

    static let OCSPSigning

    public static let OCSPSigning = 5u16
    

    功能:用于对 OCSP 响应包进行签名。

    类型:UInt16

    static let ServerAuth

    public static let ServerAuth = 1u16
    

    功能:表示用于 SSL 的服务端验证。

    类型:UInt16

    static let TimeStamping

    public static let TimeStamping = 6u16
    

    功能:用于将对象摘要值与时间绑定。

    类型:UInt16

    init(Array<UInt16>)

    public init(keys: Array<UInt16>)
    

    功能:构造指定用途的扩展密钥用法,需要注意同一个密钥可以有多种用途。

    参数:

    func toString()

    public override func toString(): String
    

    功能:生成扩展密钥用途字符串。

    返回值:

    • String - 证书扩展密钥用途字符串。

    struct KeyUsage

    public struct KeyUsage <: ToString {
        public static let DigitalSignature = 0x0080u16
        public static let NonRepudiation = 0x0040u16
        public static let KeyEncipherment = 0x0020u16
        public static let DataEncipherment = 0x0010u16
        public static let KeyAgreement = 0x0008u16
        public static let CertSign = 0x0004u16
        public static let CRLSign = 0x0002u16
        public static let EncipherOnly = 0x0001u16
        public static let DecipherOnly = 0x0100u16
    
        public init(keys: UInt16)
    
        public override func toString(): String
    }
    

    功能:数字证书扩展字段中通常会包含携带公钥的用法说明,目前支持的用途有:DigitalSignature、NonRepudiation、KeyEncipherment、DataEncipherment、KeyAgreement、CertSign、CRLSign、EncipherOnly、DecipherOnly。

    父类型:

    static let CRLSign

    public static let CRLSign = 0x0002u16
    

    功能:表示私钥可用于对 CRL 签名,而公钥可用于验证 CRL 签名。

    类型:UInt16

    static let CertSign

    public static let CertSign = 0x0004u16
    

    功能:表示私钥用于证书签名,而公钥用于验证证书签名,专用于 CA 证书。

    类型:UInt16

    static let DataEncipherment

    public static let DataEncipherment = 0x0010u16
    

    功能:表示公钥用于直接加密数据。

    类型:UInt16

    static let DecipherOnly

    public static let DecipherOnly = 0x0100u16
    

    功能:表示证书中的公钥在密钥协商过程中,仅仅用于解密计算,配合 key Agreement 使用才有意义。

    类型:UInt16

    static let DigitalSignature

    public static let DigitalSignature = 0x0080u16
    

    功能:表示私钥可以用于除了签发证书、签发 CRL 和非否认性服务的各种数字签名操作,而公钥用来验证这些签名。

    类型:UInt16

    static let EncipherOnly

    public static let EncipherOnly = 0x0001u16
    

    功能:表示证书中的公钥在密钥协商过程中,仅仅用于加密计算,配合 key Agreement 使用才有意义。

    类型:UInt16

    static let KeyAgreement

    public static let KeyAgreement = 0x0008u16
    

    功能:表示密钥用于密钥协商。

    类型:UInt16

    static let KeyEncipherment

    public static let KeyEncipherment = 0x0020u16
    

    功能:表示密钥用来加密传输其他的密钥。

    类型:UInt16

    static let NonRepudiation

    public static let NonRepudiation = 0x0040u16
    

    功能:表示私钥可以用于进行非否认性服务中的签名,而公钥用来验证签名。

    类型:UInt16

    init(UInt16)

    public init(keys: UInt16)
    

    功能:构造指定用途的扩展密钥用法,需要注意同一个密钥可以有多种用途。

    参数:

    • keys: UInt16 - 密钥的用法,建议使用本结构中所提供的密钥用法变量通过按位或的方式传入参数。

    func toString()

    public override func toString(): String
    

    功能:生成密钥用途字符串。

    返回值:

    • String - 证书密钥用途字符串。

    struct Pem

    public struct Pem <: Collection<PemEntry> & ToString {
        public Pem(private let items: Array<PemEntry>)
    }
    

    功能:结构体 Pem 为条目序列,可以包含多个 PemEntry

    父类型:

    prop size

    public override prop size: Int64
    

    功能:条目序列的数量。

    类型:Int64

    Pem(Array<PemEntry>)

    public Pem(private let items: Array<PemEntry>)
    

    功能:构造 Pem 对象。

    参数:

    static func decode(String)

    public static func decode(text: String): Pem
    

    功能:将 PEM 文本解码为条目序列。

    参数:

    • text: String - PEM 字符串。

    返回值:

    • Pem - PEM 条目序列。

    func encode()

    public func encode(): String
    

    功能:返回PEM格式的字符串。行结束符将根据当前操作系统生成。

    返回值:

    • String - PEM 格式的字符串。

    func isEmpty()

    public override func isEmpty(): Bool
    

    功能:判断 PEM 文本解码为条目序列是否为空。

    返回值:

    • Bool - PEM 文本解码为条目序列为空返回 true;否则,返回 false。

    func iterator()

    public override func iterator(): Iterator<PemEntry>
    

    功能:生成 PEM 文本解码为条目序列的迭代器。

    返回值:

    func toString()

    public override func toString(): String
    

    功能:返回一个字符串,字符串内容是包含每个条目序列的标签。

    返回值:

    • String - 包含每个条目序列的标签的字符串。

    struct PemEntry

    public struct PemEntry <: ToString {
        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 编码标准中在第一行和正文之间还包含条目头。

    为了支持不同的用户场景,我们提供了 PemEntryPem 类型,PemEntry 用于存储单个PEM 基础结构。

    父类型:

    static let LABEL_CERTIFICATE

    public static let LABEL_CERTIFICATE = "CERTIFICATE"
    

    功能:记录条目类型为证书。

    类型:String

    static let LABEL_CERTIFICATE_REQUEST

    public static let LABEL_CERTIFICATE_REQUEST = "CERTIFICATE REQUEST"
    

    功能:记录条目类型为证书签名请求。

    类型:String

    static let LABEL_DH_PARAMETERS

    public static let LABEL_DH_PARAMETERS = "DH PARAMETERS"
    

    功能:记录条目类型为 DH 密钥参数。

    类型:String

    static let LABEL_EC_PARAMETERS

    public static let LABEL_EC_PARAMETERS = "EC PARAMETERS"
    

    功能:记录条目类型为椭圆曲线参数。

    类型:String

    static let LABEL_EC_PRIVATE_KEY

    public static let LABEL_EC_PRIVATE_KEY = "EC PRIVATE KEY"
    

    功能:记录条目类型为椭圆曲线私钥。

    类型:String

    static let LABEL_ENCRYPTED_PRIVATE_KEY

    public static let LABEL_ENCRYPTED_PRIVATE_KEY = "ENCRYPTED PRIVATE KEY"
    

    功能:记录条目类型为 PKCS #8 标准加密的私钥。

    类型:String

    static let LABEL_PRIVATE_KEY

    public static let LABEL_PRIVATE_KEY = "PRIVATE KEY"
    

    功能:记录条目类型为 PKCS #8 标准未加密的私钥。

    类型:String

    static let LABEL_PUBLIC_KEY

    public static let LABEL_PUBLIC_KEY = "PUBLIC KEY"
    

    功能:记录条目类型为公钥。

    类型:String

    static let LABEL_RSA_PRIVATE_KEY

    public static let LABEL_RSA_PRIVATE_KEY = "RSA PRIVATE KEY"
    

    功能:记录条目类型为 RSA 私钥。

    类型:String

    static let LABEL_SM2_PRIVATE_KEY

    public static let LABEL_SM2_PRIVATE_KEY = "SM2 PRIVATE KEY"
    

    功能:记录条目类型为 SM2 私钥。

    类型:String

    static let LABEL_X509_CRL

    public static let LABEL_X509_CRL = "X509 CRL"
    

    功能:记录条目类型为证书吊销列表。

    类型:String

    PemEntry(String, Array<(String, String)>, ?DerBlob)

    public PemEntry(
        public let label: String,
        public let headers: Array<(String, String)>,
        public let body: ?DerBlob
    )
    

    功能:构造 PemEntry 对象。

    参数:

    body

    public let body: ?DerBlob
    

    功能:PemEntry 实例的二进制内容。

    类型:?DerBlob

    headers

    public let headers: Array<(String, String)>
    

    功能:PemEntry 实例的条目头。

    类型:Array<(String, String)>

    label

    public let label: String
    

    功能:PemEntry 实例的标签。

    类型:String

    init(String, DerBlob)

    public init(label: String, body: DerBlob)
    

    功能:构造 PemEntry 对象。

    参数:

    func encode()

    public func encode(): String
    

    功能:返回PEM格式的字符串。行结束符将根据当前操作系统生成。

    返回值:

    • String - PEM 格式的字符串。

    func header(String)

    public func header(name: String): Iterator<String>
    

    功能:通过条目头名称,找到对应条目内容。

    参数:

    • name: String - 条目头名称。

    返回值:

    func toString()

    public override func toString(): String
    

    功能:返回 PEM 对象的标签和二进制内容的长度。

    返回值:

    • String - PEM 对象的标签和二进制内容的长度。

    struct SerialNumber

    public struct SerialNumber <: Equatable<SerialNumber> & Hashable & ToString {
        public init(length!: UInt8 = 16)
    }
    

    功能: 结构体 SerialNumber 为数字证书的序列号,是数字证书中的一个唯一标识符,用于标识数字证书的唯一性。根据规范,证书序列号的长度不应超过 20 字节。详见rfc5280

    父类型:

    init(UInt8)

    public init(length!: UInt8 = 16)
    

    功能:生成指定长度的随机序列号。

    参数:

    • length!: UInt8 - 序列号长度,单位为字节,类型为 UInt8,默认值为 16。

    异常:

    • X509Exception - length 等于 0 或大于 20 时,抛出异常。

    func hashCode()

    public override func hashCode(): Int64
    

    功能:返回证书序列号哈希值。

    返回值:

    • Int64 - 对证书序列号对象进行哈希计算后得到的结果。

    func toString()

    public override func toString(): String
    

    功能:生成证书序列号字符串,格式为 16 进制。

    返回值:

    • String - 证书序列号字符串。

    operator func !=(SerialNumber)

    public override operator func !=(other: SerialNumber): Bool
    

    功能:判不等。

    参数:

    • other: SerialNumber - 被比较的证书序列号对象。

    返回值:

    • Bool - 若序列号不同,返回 true;否则,返回 false。

    operator func ==(SerialNumber)

    public override operator func ==(other: SerialNumber): Bool
    

    功能:判等。

    参数:

    • other: SerialNumber - 被比较的证书序列号对象。

    返回值:

    • Bool - 若序列号相同,返回 true;否则,返回 false。

    struct Signature

    public struct Signature <: Equatable<Signature> & Hashable {
    }
    

    功能:数字证书的签名,用来验证身份的正确性。

    父类型:

    prop signatureValue

    public prop signatureValue: DerBlob
    

    功能:返回证书签名的二进制。

    类型:DerBlob

    func hashCode()

    public override func hashCode(): Int64
    

    功能:返回证书签名哈希值。

    返回值:

    • Int64 - 对证书签名对象进行哈希计算后得到的结果。

    operator func !=(Signature)

    public override operator func !=(other: Signature): Bool
    

    功能:判不等。

    参数:

    • other: Signature - 被比较的证书签名。

    返回值:

    • Bool - 若证书签名不同,返回 true;否则,返回 false。

    operator func ==(Signature)

    public override operator func ==(other: Signature): Bool
    

    功能:判等。

    参数:

    • other: Signature - 被比较的证书签名。

    返回值:

    • Bool - 若证书签名相同,返回 true;否则,返回 false。

    struct VerifyOption

    public struct VerifyOption {
        public var time: DateTime = DateTime.now()
        public var dnsName: String = ""
        public var roots: Array<X509Certificate> = X509Certificate.systemRootCerts()
        public var intermediates: Array<X509Certificate> = Array<X509Certificate>()
    }
    

    dnsName

    public var dnsName: String = ""
    

    功能:校验域名,默认为空,只有设置域名时才会进行此处校验。

    类型:String

    intermediates

    public var intermediates: Array<X509Certificate> = Array<X509Certificate>()
    

    功能:中间证书链,默认为空。

    类型:Array<X509Certificate>

    roots

    public var roots: Array<X509Certificate> = X509Certificate.systemRootCerts()
    

    功能:根证书链,默认为系统根证书链。

    类型:Array<X509Certificate>

    time

    public var time: DateTime = DateTime.now()
    

    功能:校验时间,默认为创建选项的时间。

    类型:DateTime

    struct X509CertificateInfo

    public struct X509CertificateInfo {
        public var serialNumber: SerialNumber
        public var notBefore: DateTime
        public var notAfter: DateTime
        public var subject: ?X509Name
        public var dnsNames: Array<String>
        public var emailAddresses: Array<String>
        public var IPAddresses: Array<IP>
        public var keyUsage: ?KeyUsage
        public var extKeyUsage: ?ExtKeyUsage
    
        public init(
            serialNumber!: ?SerialNumber = None,
            notBefore!: ?DateTime = None,
            notAfter!: ?DateTime = None,
            subject!: ?X509Name = None,
            dnsNames!: Array<String> = Array<String>(),
            emailAddresses!: Array<String> = Array<String>(),
            IPAddresses!: Array<IP> = Array<IP>(),
            keyUsage!: ?KeyUsage = None,
            extKeyUsage!: ?ExtKeyUsage = None
        )
    }
    

    功能:X509CertificateInfo 结构包含了证书信息,包括证书序列号、有效期、实体可辨识名称、域名、email 地址、IP 地址、密钥用法和扩展密钥用法。

    IPAddresses

    public var IPAddresses: Array<IP>
    

    功能:记录证书的 IP 地址。

    类型:Array<IP>

    dnsNames

    public var dnsNames: Array<String>
    

    功能:记录证书的 DNS 域名。

    类型:Array<String>

    emailAddresses

    public var emailAddresses: Array<String>
    

    功能:记录证书的 email 地址。

    类型:Array<String>

    extKeyUsage

    public var extKeyUsage: ?ExtKeyUsage
    

    功能:记录证书的扩展密钥用法。

    类型:?ExtKeyUsage

    keyUsage

    public var keyUsage: ?KeyUsage
    

    功能:记录证书的密钥用法。

    类型:?KeyUsage

    notAfter

    public var notAfter: DateTime
    

    功能:记录证书有效期的结束日期。

    类型:DateTime

    notBefore

    public var notBefore: DateTime
    

    功能:记录证书有效期的起始日期。

    类型:DateTime

    serialNumber

    public var serialNumber: SerialNumber
    

    功能:记录证书的序列号。

    类型:SerialNumber

    subject

    public var subject: ?X509Name
    

    功能:记录证书实体可辨识名称。

    类型:?X509Name

    init(?SerialNumber, ?DateTime, ?DateTime, ?X509Name, Array<String>, Array<String>, Array<IP>, ?KeyUsage, ?ExtKeyUsage)

    public init(
        serialNumber!: ?SerialNumber = None,
        notBefore!: ?DateTime = None,
        notAfter!: ?DateTime = None,
        subject!: ?X509Name = None,
        dnsNames!: Array<String> = Array<String>(),
        emailAddresses!: Array<String> = Array<String>(),
        IPAddresses!: Array<IP> = Array<IP>(),
        keyUsage!: ?KeyUsage = None,
        extKeyUsage!: ?ExtKeyUsage = None
    )
    

    功能:构造 X509CertificateInfo 对象。

    参数:

    • serialNumber!: ?SerialNumber - 数字证书序列号,默认值为 None,使用默认值时默认的序列号长度为 128 比特。
    • notBefore!: ?DateTime - 数字证书有效期开始时间,默认值为 None,使用默认值时默认的时间为 X509CertificateInfo 创建的时间。
    • notAfter!: ?DateTime - 数字证书有效期截止时间,默认值为 None,使用默认值时默认的时间为 notBefore 往后 1 年的时间。
    • subject!: ?X509Name - 数字证书使用者信息,默认值为 None。
    • dnsNames!: Array<String> - 域名列表,需要用户保证输入域名的有效性,默认值为空的字符串数组。
    • emailAddresses!: Array<String> - email 地址列表,需要用户保证输入 email 的有效性,默认值为空的字符串数组。
    • IPAddresses!: Array<IP> - IP 地址列表,默认值为空的 IP 数组。
    • keyUsage!: ?KeyUsage - 密钥用法,默认值为 None。
    • extKeyUsage!: ?ExtKeyUsage - 扩展密钥用法,默认值为 None。

    异常:

    • X509Exception - 输入的 IP 地址列表中包含无效的 IP 地址,则抛出异常。

    struct X509CertificateRequestInfo

    public struct X509CertificateRequestInfo {
        public var subject: ?X509Name
        public var dnsNames: Array<String>
        public var emailAddresses: Array<String>
        public var IPAddresses: Array<IP>
     
        public init(
            subject!: ?X509Name = None,
            dnsNames!: Array<String> = Array<String>(),
            emailAddresses!: Array<String> = Array<String>(),
            IPAddresses!: Array<IP> = Array<IP>()
        )
    }
    

    X509CertificateRequestInfo 结构包含了证书请求信息,包括证书实体可辨识名称、域名、email 地址和 IP 地址。

    IPAddresses

    public var IPAddresses: Array<IP>
    

    功能:记录证书签名请求的 IP 地址。

    类型:Array<IP>

    dnsNames

    public var dnsNames: Array<String>
    

    功能:记录证书签名请求的 DNS 域名。

    类型:Array<String>

    emailAddresses

    public var emailAddresses: Array<String>
    

    功能:记录证书签名请求的 email 地址。

    类型:Array<String>

    subject

    public var subject: ?X509Name
    

    功能:记录证书签名请求的实体可辨识名称。

    init(?X509Name, Array<String>, Array<String>, Array<IP>)

    public init(
        subject!: ?X509Name = None,
        dnsNames!: Array<String> = Array<String>(),
        emailAddresses!: Array<String> = Array<String>(),
        IPAddresses!: Array<IP> = Array<IP>()
    )
    

    功能:构造 X509CertificateRequestInfo 对象。

    参数:

    • subject!: ?X509Name - 数字证书的使用者信息,默认值为 None。
    • dnsNames!: Array<String> - 域名列表,需要用户保证输入域名的有效性,默认值为空的字符串数组。
    • emailAddresses!: Array<String> - email 地址列表,需要用户保证输入 email 的有效性,默认值为空的字符串数组。
    • IPAddresses!: Array<IP> - IP 地址列表,默认值为空的 IP 数组。

    异常:

    • X509Exception - 输入的 IP 地址列表中包含无效的 IP 地址,则抛出异常。

    异常类

    class X509Exception

    public class X509Exception <: Exception {
        public init()
        public init(message: String)
    }
    

    功能:此异常为 X509 包抛出的异常类型。

    父类型:

    init()

    public init()
    

    功能:构造 X509Exception 对象。

    init(String)

    public init(message: String)
    

    功能:构造 X509Exception 对象。

    参数:

    • message: String - 异常的信息。

    x509 使用

    读取、解析证书

    说明:

    需要自行准备证书文件。

    import std.fs.File
    import crypto.x509.*
    
    let readPath = "./files/root_rsa.cer"
    main() {
        // 读取本地证书
        let pem = String.fromUtf8(File.readFrom(readPath))
        let certificates = X509Certificate.decodeFromPem(pem)
    
        // 解析证书中的必选字段
        let cert = certificates[0]
        println(cert)
        println("Serial Number: ${cert.serialNumber}")
        println("Issuer: ${cert.issuer}")
        println("NotBefore: ${cert.notBefore}")
        println("NotAfter: ${cert.notAfter}")
        println(cert.signatureAlgorithm)
        let signature = cert.signature
        println(signature.hashCode())
        println(cert.publicKeyAlgorithm)
        let pubKey = cert.publicKey
        println(pubKey.encodeToPem().encode())
    
        // 解析证书中的扩展字段
        println("DNSNames: ${cert.dnsNames}")
        println("EmailAddresses: ${cert.emailAddresses}")
        println("IPAddresses: ${cert.IPAddresses}")
        println("KeyUsage: ${cert.keyUsage}")
        println("ExtKeyUsage: ${cert.extKeyUsage}")
    
        // 解析证书使用者的可辨识名称
        println("Subject: ${cert.subject}")
    
        return 0
    }
    

    读取、验证证书

    说明:

    需要自行准备证书文件。

    import std.fs.File
    import crypto.x509.*
    import std.time.DateTime
    
    let prefixPath = "./files/"
    let certFile = "servers.crt"
    let rootFile = "roots.crt"
    let middleFile = "middles.crt"
    
    func getX509Cert(path: String)
    {
        let pem = String.fromUtf8(File.readFrom(path))
        X509Certificate.decodeFromPem(pem)
    }
    
    
    func testVerifyByTime(cert: X509Certificate, roots: Array<X509Certificate>, middles: Array<X509Certificate>)
    {
        var opt = VerifyOption()
        opt.roots = roots
        opt.intermediates = middles
        cert.verify(opt)
        println("Verify result: ${cert.verify(opt)}")
        opt.time = DateTime.of(year: 2023, month: 7, dayOfMonth: 1)
        println("Verify result:: ${cert.verify(opt)}")
    }
    
    func testVerifyByDNS(cert: X509Certificate)
    {
        var opt = VerifyOption()
        opt.dnsName = "www.example.com"
        println("cert DNS names: ${cert.dnsNames}")
        let res = cert.verify(opt)
        println("Verify result: ${res}")
    }
    
    
    /**
     * The relation of certs.
     *    root[0]         root[1]
     *    /      \            |
     *  mid[0]  mid[1]    mid[2]
     *   |                  |
     *  server[0]         server[1]
    */
    func testVerify(cert: X509Certificate, roots: Array<X509Certificate>, middles: Array<X509Certificate>)
    {
        var opt = VerifyOption()
        opt.roots = roots
        opt.intermediates = middles
        let res = cert.verify(opt)
        println("Verify result: ${res}")
    }
    
    main() {
        // 2 server certs
        let certs = getX509Cert(prefixPath + certFile)
        // 2 root certs
        let roots = getX509Cert(prefixPath + rootFile)
        // 3 middle certs
        let middles = getX509Cert(prefixPath + middleFile)
        // Verify by time: true, false
        testVerifyByTime(certs[0], [roots[0]], [middles[0]])
        // Verify by dns: false
        testVerifyByDNS(certs[0])
        // cert0 <- root0: false
        testVerify(certs[0], [roots[0]], [])
        // cert0 <- middle0 <- root0: true
        testVerify(certs[0], [roots[0]], [middles[0]])
        // cert0 <- (middle0, middle1, middle2) <- (root0, root1) : true
        testVerify(certs[0], roots, middles)
        // cert1 <- middle0 <- root0: false
        testVerify(certs[1], [roots[0]], [middles[0]])
        // cert1 <- middle2 <- root1: true
        testVerify(certs[1], [roots[1]], [middles[2]])
        // cert1 <- (middle0, middle1, middle2) <- (root0, root1) : true
        testVerify(certs[1], roots, middles)
        return 0
    }
    

    创建、解析证书

    说明:

    需要自行准备根证书文件。

    import std.fs.*
    import crypto.x509.*
    import std.time.*
    import std.io.*
    
    main() {
        let x509Name = X509Name(
            countryName: "CN",
            provinceName: "beijing",
            localityName: "haidian",
            organizationName: "organization",
            organizationalUnitName: "organization unit",
            commonName: "x509",
            email: "test@email.com"
        )
        let serialNumber = SerialNumber(length: 20)
        let startTime: DateTime = DateTime.now()
        let endTime: DateTime = startTime.addYears(1)
        let ip1: IP = [8, 8, 8, 8]
        let ip2: IP = [0, 1, 0, 1, 0, 1, 0, 1, 0, 8, 0, 8, 0, 8, 0, 8]
        let parentCertPem = String.fromUtf8(readToEnd(File("./certificate.pem", OpenOption.Open(true, false))))
        let parentCert = X509Certificate.decodeFromPem(parentCertPem)[0]
        let parentKeyPem = String.fromUtf8(readToEnd(File("./rsa_private_key.pem", OpenOption.Open(true, false))))
        let parentPrivateKey = PrivateKey.decodeFromPem(parentKeyPem)
        let usrKeyPem = String.fromUtf8(readToEnd(File("./ecdsa_public_key.pem", OpenOption.Open(true, false))))
        let usrPublicKey = PublicKey.decodeFromPem(usrKeyPem)
    
        let certInfo = X509CertificateInfo(serialNumber: serialNumber, notBefore: startTime, notAfter: endTime, subject: x509Name, dnsNames: ["b.com"], IPAddresses: [ip1, ip2]);
        let cert = X509Certificate(certInfo, parent: parentCert, publicKey: usrPublicKey, privateKey: parentPrivateKey)
    
        println(cert)
        println("Serial Number: ${cert.serialNumber}")
        println("Issuer: ${cert.issuer}")
        println("Subject: ${cert.subject}")
        println("NotBefore: ${cert.notBefore}")
        println("NotAfter: ${cert.notAfter}")
        println(cert.signatureAlgorithm)
        println("DNSNames: ${cert.dnsNames}")
        println("IPAddresses: ${cert.IPAddresses}")
    
        return 0
    }
    

    创建、解析证书签名请求

    说明:

    需要自行准备私钥等文件。

    import std.fs.*
    import std.io.*
    import crypto.x509.*
    
    main(){
        let x509Name = X509Name(
            countryName: "CN",
            provinceName: "beijing",
            localityName: "haidian",
            organizationName: "organization",
            organizationalUnitName: "organization unit",
            commonName: "x509",
            email: "test@email.com"
        )
        let ip1: IP = [8, 8, 8, 8]
        let ip2: IP = [0, 1, 0, 1, 0, 1, 0, 1, 0, 8, 0, 8, 0, 8, 0, 8]
        let rsaPem = String.fromUtf8(readToEnd(File("./rsa_private_key.pem", OpenOption.Open(true, false))))
        let rsa = PrivateKey.decodeFromPem(rsaPem)
    
        let csrInfo = X509CertificateRequestInfo(subject: x509Name, dnsNames: ["b.com"], IPAddresses: [ip1, ip2]);
        let csr = X509CertificateRequest(rsa, certificateRequestInfo:csrInfo, signatureAlgorithm: SHA256WithRSA)
    
        println("Subject: ${csr.subject.toString()}")
        println("IPAddresses: ${csr.IPAddresses}")
        println("dnsNames: ${csr.dnsNames}")
    
        return 0
    }
    

    encoding 模块

    encoding 功能介绍

    encoding 模块提供字符编解码功能。

    支持 Base64、Hex、JSON、URL 格式数据的编解码。

    encoding 模块的包列表

    encoding 模块提供了如下包:

    包名功能
    base64base 包提供字符串的 Base64 编码及解码。
    hexhex 包提供字符串的 Hex 编码及解码。
    jsonjson 包用于对 json 数据的处理,实现 String, JsonValue, DataModel 之间的相互转换。
    json.streamjson.stream 包主要用于仓颉对象和 JSON 数据流之间的互相转换。
    urlurl 包提供了 URL 相关的能力,包括解析 URL 的各个组件,对 URL 进行编解码,合并 URL 或路径等。

    encoding.base64 包

    功能介绍

    base 包提供字符串的 Base64 编码及解码。

    Base64 编码能够将二进制数据转换成仅由 64 个可打印的字符(A-Z、a-z、0-9、+、/)组成的文本格式,这使得二进制数据能够在文本环境中安全传输和存储。

    API 列表

    函数

    函数名功能
    fromBase64String(String)用于 Base64 编码的字符串的解码。
    toBase64String(Array<Byte>)用于将字符数组转换成 Base64 编码的字符串。

    函数

    func fromBase64String(String)

    public func fromBase64String(data: String): Option<Array<Byte>>
    

    功能:此函数用于 Base64 编码的字符串的解码。

    参数:

    • data: String - 要解码的 Base64 编码的字符串。

    返回值:

    func toBase64String(Array<Byte>)

    public func toBase64String(data: Array<Byte>): String
    

    功能:此函数用于将 Byte 数组转换成 Base64 编码的字符串。

    参数:

    返回值:

    • String - 返回编码后的字符串。

    Byte 数组和 Base64 互转

    import encoding.base64.*
    main(): Int64 {
        var arr: Array<Byte> = [77, 97, 110]
        var str = toBase64String(arr)
        print("${str},")
        var opArr: Option<Array<Byte>> = fromBase64String(str)
        var arr2: Array<Byte> = match (opArr) {
            case Some(s) => s
            case None => Array<Byte>()
        }
        for (i in 0..arr2.size) {
            print("${arr2[i]},")
        }
        return 0
    }
    

    运行结果如下:

    TWFu,77,97,110,
    

    encoding.hex 包

    功能介绍

    hex 包提供字符串的 Hex 编码及解码。

    Hex 编码(也称为十六进制编码)是一种将数据转换为十六进制表示形式的编码方法。Hex 编码使用 16 个字符来表示数据,这 16 个字符分别是 0-9 的数字和 A-F 的字母(不区分大小写,即 a-f 和 A-F 是等价的)。

    API 列表

    函数

    函数名功能
    fromHexString(String)用于 Hex 编码的字符串的解码。
    toHexString(Array<Byte>)用于将字符数组转换成 Hex 编码的字符串。

    函数

    func fromHexString(String)

    public func fromHexString(data: String): Option<Array<Byte>>
    

    功能:此函数用于 Hex 编码的字符串的解码。

    参数:

    • data: String - 要解码的 Hex 编码的字符串。

    返回值:

    func toHexString(Array<Byte>)

    public func toHexString(data: Array<Byte>): String
    

    功能:此函数用于将 Byte 数组转换成 Hex 编码的字符串。

    参数:

    返回值:

    • String - 返回编码后的字符串。

    Byte 数组和 Hex 互转

    import encoding.hex.*
    main(): Int64 {
        var arr: Array<Byte> = [65, 66, 94, 97]
        var str = toHexString(arr)
        print("${str},")
        var opArr: Option<Array<Byte>> = fromHexString(str)
        var arr2: Array<Byte> = match (opArr) {
            case Some(s) => s
            case None => Array<Byte>()
        }
        for (i in 0..arr2.size) {
            print("${arr2[i]},")
        }
        return 0
    }
    

    运行结果如下:

    41425e61,65,66,94,97,
    

    encoding.json 包

    功能介绍

    json 包用于对 JSON 数据的处理,实现 String, JsonValue, DataModel 之间的相互转换。

    JsonValue 是对 JSON 数据格式的封装,包括 object, array, string, number, true, false 和 null。

    DataModel 详细信息可参考:serialization 包文档

    JSON 语法规则可参考:介绍 JSON

    JSON 数据转换标准可参考:ECMA-404 The JSON Data Interchange Standard

    API 列表

    接口

    接口名功能
    ToJson用于实现 JsonValue 和 DataModel 的相互转换。

    类名功能
    JsonArray创建空 JsonArray。
    JsonBool将指定的 Bool 类型实例封装成 JsonBool 实例。
    JsonFloat将指定的 Float64 类型实例封装成 JsonFloat 实例。
    JsonInt将指定的 Int64 类型实例封装成 JsonInt 实例。
    JsonNull将 JsonNull 转换为字符串。
    JsonObject创建空 JsonObject。
    JsonString将指定的 String 类型实例封装成 JsonString 实例。
    JsonValue此类为 JSON 数据层, 主要用于 JsonValue 和 String 数据之间的互相转换。

    枚举

    枚举名功能
    JsonKind表示 JsonValue 的具体类型。

    异常类

    异常类名功能
    JsonException用于 JsonValue 类型使用时出现异常的场景。

    接口

    interface ToJson

    public interface ToJson {
        static func fromJson(jv: JsonValue): DataModel
        func toJson(): JsonValue
    }
    

    功能:用于实现 JsonValueDataModel 的相互转换。

    static func fromJson(JsonValue)

    static func fromJson(jv: JsonValue): DataModel
    

    功能:将 JsonValue 转化为对象 DataModel

    参数:

    返回值:

    func toJson()

    func toJson(): JsonValue
    

    功能:将自身转化为 JsonValue

    返回值:

    异常:

    extend DataModel <: ToJson

    extend DataModel <: ToJson
    

    功能:为 DataModel 类型实现 ToJson 接口。

    父类型:

    static func fromJson(JsonValue)

    public static func fromJson(jv: JsonValue): DataModel
    

    功能:将 JsonValue 转化为对象 DataModel

    参数:

    返回值:

    func toJson()

    public func toJson(): JsonValue
    

    功能:将自身转化为 JsonValue

    返回值:

    异常:

    class JsonArray

    public class JsonArray <: JsonValue {
        public init()
        public init(list: ArrayList<JsonValue>)
        public init(list: Array<JsonValue>)
    }
    

    功能:此类为 JsonValue 实现子类,主要用于封装数组类型的 JSON 数据。

    父类型:

    示例:

    使用示例见JsonArray 使用示例

    init()

    public init()
    

    功能:创建空 JsonArray

    init(ArrayList<JsonValue>)

    public init(list: ArrayList<JsonValue>)
    

    功能:将指定的 ArrayList 类型实例封装成 JsonArray 实例。

    参数:

    init(Array<JsonValue>)

    public init(list: Array<JsonValue>)
    

    功能:将指定的 Array 类型实例封装成 JsonArray 实例。

    参数:

    func add(JsonValue)

    public func add(jv: JsonValue): JsonArray
    

    功能:向 JsonArray 中加入 JsonValue 数据。

    参数:

    返回值:

    func get(Int64)

    public func get(index: Int64): Option<JsonValue>
    

    功能:获取 JsonArray 中指定索引的 JsonValue,并用 Option<JsonValue> 封装。

    参数:

    • index: Int64 - 指定的索引。

    返回值:

    func getItems()

    public func getItems(): ArrayList<JsonValue>
    

    功能:获取 JsonArray 中的 items 数据。

    返回值:

    func kind()

    public func kind(): JsonKind
    

    功能:返回当前 JsonArray 所属的 JsonKind 类型(JsArray)。

    返回值:

    func size()

    public func size(): Int64
    

    功能:获取 JsonArrayJsonValue 的数量。

    返回值:

    func toJsonString()

    public func toJsonString(): String
    

    功能:将 JsonArray 转换为 JSON 格式的 (带有空格换行符) 的字符串。

    返回值:

    • String - 转换后的 JSON 格式字符串。

    func toJsonString(Int64, Bool, String)

    public func toJsonString(depth: Int64, bracketInNewLine!: Bool = false, indent!: String = "  "): String
    

    功能:将 JsonArray 转换为 JSON 格式的字符串。该函数将指定初始的缩进深度、第一个括号后是否换行以及缩进字符串。

    参数:

    • depth: Int64 - 指定的缩进深度。
    • bracketInNewLine!: Bool - 第一个括号是否换行,如果为 true,第一个括号将另起一行并且按照指定的深度缩进。
    • indent!: String - 指定的缩进字符串,缩进字符串中只允许空格和制表符的组合,默认为两个空格。

    返回值:

    • String - 转换后的 JSON 格式字符串。

    异常:

    • IllegalArgumentException - 如果 depth 为负数,或 indent 中存在 ' ' 和 '\t' 以外的字符,则抛出异常。

    func toString()

    public func toString(): String
    

    功能:将 JsonString 转换为字符串。

    返回值:

    • String - 转换后的字符串。

    operator func [](Int64)

    public operator func [](index: Int64): JsonValue
    

    功能:获取 JsonArray 中指定索引的 JsonValue

    参数:

    • index: Int64 - 指定的索引。

    返回值:

    异常:

    class JsonBool

    public class JsonBool <: JsonValue {
        public init(bv: Bool)
    }
    

    功能:此类为 JsonValue 实现子类,主要用于封装 true 或者 false 的 JSON 数据。

    父类型:

    init(Bool)

    public init(bv: Bool)
    

    功能:将指定的 Bool 类型实例封装成 JsonBool 实例。

    func getValue()

    public func getValue(): Bool
    

    功能:获取 JsonBool 中 value 的实际值。

    返回值:

    • Bool - value 的实际值。

    func kind()

    public func kind(): JsonKind
    

    功能:返回当前 JsonBool 所属的 JsonKind 类型(JsBool)。

    返回值:

    func toJsonString()

    public func toJsonString(): String
    

    功能:将 JsonBool 转换为 JSON 格式的 (带有空格换行符) 字符串。

    返回值:

    • String - 转换后的 JSON 格式字符串。

    func toString()

    public func toString(): String
    

    功能:将 JsonBool 转换为字符串。

    返回值:

    • String - 转换后的字符串。

    class JsonFloat

    public class JsonFloat <: JsonValue {
        public init(fv: Float64)
        public init(v: Int64)
    }
    

    功能:此类为 JsonValue 实现子类,主要用于封装浮点类型的 JSON 数据。

    父类型:

    init(Float)

    public init(fv: Float64)
    

    功能:将指定的 Float64 类型实例封装成 JsonFloat 实例。

    参数:

    init(Int64)

    public init(v: Int64)
    

    功能:将指定的 Int64 类型实例封装成 JsonFloat 实例。

    参数:

    func getValue()

    public func getValue(): Float64
    

    功能:获取 JsonFloat 中 value 的实际值。

    返回值:

    func kind()

    public func kind(): JsonKind
    

    功能:返回当前 JsonFloat 所属的 JsonKind 类型(JsFloat)。

    返回值:

    func toJsonString()

    public func toJsonString(): String
    

    功能:将 JsonFloat 转换为 JSON 格式的 (带有空格换行符) 字符串。

    返回值:

    • String - 转换后的 JSON 格式字符串。

    func toString()

    public func toString(): String
    

    功能:将 JsonFloat 转换为字符串。

    返回值:

    • String - 转换后的字符串。

    class JsonInt

    public class JsonInt <: JsonValue {
        public init(iv: Int64)
    }
    

    功能:此类为 JsonValue 实现子类,主要用于封装整数类型的 JSON 数据。

    父类型:

    init(Int64)

    public init(iv: Int64)
    

    功能:将指定的 Int64 类型实例封装成 JsonInt 实例。

    参数:

    func getValue()

    public func getValue(): Int64
    

    功能:获取 JsonInt 中 value 的实际值。

    返回值:

    • Int64 - value 的实际值。

    func kind()

    public func kind(): JsonKind
    

    功能:返回当前 JsonInt 所属的 JsonKind 类型(JsInt)。

    返回值:

    func toJsonString()

    public func toJsonString(): String
    

    功能:将 JsonInt 转换为 JSON 格式的 (带有空格换行符) 字符串。

    返回值:

    • String - 转换后的 JSON 格式字符串。

    func toString()

    public func toString(): String
    

    功能:将 JsonInt 转换为字符串。

    返回值:

    • String - 转换后的字符串。

    class JsonNull

    public class JsonNull <: JsonValue
    

    功能:此类为 JsonValue 实现子类,主要用于封装 null 的 JSON 数据。

    父类型:

    func kind()

    public func kind(): JsonKind
    

    功能:返回当前 JsonNull 所属的 JsonKind 类型(JsNull)。

    返回值:

    func toJsonString()

    public func toJsonString(): String
    

    功能:将 JsonNull 转换为 JSON 格式的 (带有空格换行符) 字符串。

    返回值:

    • String - 转换后的 JSON 格式字符串。

    func toString()

    public func toString(): String
    

    功能:将 JsonNull 转换为字符串。

    返回值:

    • String - 转换后的字符串。

    class JsonObject

    public class JsonObject <: JsonValue {
        public init()
        public init(map: HashMap<String, JsonValue>)
    }
    

    功能:此类为 JsonValue 实现子类,主要用于封装 object 类型的 JSON 数据。

    父类型:

    init()

    public init()
    

    功能:创建空 JsonObject

    init()

    public init(map: HashMap<String, JsonValue>)
    

    功能:将指定的 HashMap 类型实例封装成 JsonObject 实例。

    func containsKey(String)

    public func containsKey(key: String): Bool
    

    功能:判断 JsonObject 中是否存在 key。

    参数:

    • key: String - 指定的 key。

    返回值:

    • Bool - 存在返回 true,不存在返回 false。

    func get(String)

    public func get(key: String): Option<JsonValue>
    

    功能:获取 JsonObject 中 key 对应的 JsonValue,并用 Option<JsonValue> 封装。

    参数:

    • key: String - 指定的 key。

    返回值:

    func getFields()

    public func getFields(): HashMap<String, JsonValue>
    

    功能:获取 JsonObject 中的 fields 数据。

    返回值:

    func kind()

    public func kind(): JsonKind
    

    功能:返回当前 JsonObject 所属的 JsonKind 类型(JsObject)。

    返回值:

    func put(String, JsonValue)

    public func put(key: String, v: JsonValue): Unit
    

    功能:向 JsonObject 中加入 key-JsonValue 数据。

    参数:

    func size()

    public func size(): Int64
    

    功能:获取 JsonObject 中 fields 存入 string-JsonValue 的数量。

    返回值:

    func toJsonString()

    public func toJsonString(): String
    

    功能:将 JsonObject 转换为 JSON 格式的 (带有空格换行符) 字符串。

    返回值:

    • String - 转换后的 JSON 格式字符串。

    func toJsonString(Int64, Bool, String)

    public func toJsonString(depth: Int64, bracketInNewLine!: Bool = false, indent!: String = "  "): String
    

    功能:将 JsonObject 转换为 Json格式的字符串。该函数将指定初始的缩进深度、第一个括号后是否换行以及缩进字符串。

    参数:

    • depth: Int64 - 缩进深度。
    • bracketInNewLine!: Bool - 第一个括号是否换行,如果为 true,第一个括号将另起一行并且按照指定的深度缩进。
    • indent!: String - 指定的缩进字符串,缩进字符串中只允许空格和制表符的组合,默认为两个空格。

    返回值:

    • String - 转换后的 JSON 格式字符串。

    异常:

    • IllegalArgumentException - 如果 depth 为负数,或 indent 中存在 ' ' 和 '\t' 以外的字符,则抛出异常。

    func toString()

    public func toString(): String
    

    功能:将 JsonObject 转换为字符串。

    返回值:

    • String - 转换后的字符串。

    operator func [](String)

    public operator func [](key: String): JsonValue
    

    功能:获取 JsonObject 中 key 对应的 JsonValue

    参数:

    • key: String - 指定的 key。

    返回值:

    异常:

    class JsonString

    public class JsonString <: JsonValue {
        public init(sv: String)
    }
    

    功能:此类为 JsonValue 实现子类,主要用于封装字符串类型的 JSON 数据。

    父类型:

    init(String)

    public init(sv: String)
    

    功能:将指定的 String 类型实例封装成 JsonString 实例。

    func getValue()

    public func getValue(): String
    

    功能:获取 JsonString 中 value 的实际值。

    返回值:

    • String - value 的实际值。

    func kind()

    public func kind(): JsonKind
    

    功能:返回当前 JsonString 所属的 JsonKind 类型(JsString)。

    返回值:

    func toJsonString()

    public func toJsonString(): String
    

    功能:将 JsonString 转换为 JSON 格式的 (带有空格换行符) 字符串。

    返回值:

    • String - 转换后的 JSON 格式字符串。

    func toString()

    public func toString(): String
    

    功能:将 JsonString 转换为字符串。

    返回值:

    • String - 转换后的字符串。

    class JsonValue

    sealed abstract class JsonValue <: ToString
    

    功能:此类为 JSON 数据层,主要用于 JsonValueString 数据之间的互相转换。

    抽象类 JsonValue 提供了 String 类型和具体的 JSON 类型相互转换的接口,以及具体的 JSON 类型判断功能。

    父类型:

    示例:

    使用示例见JsonValue 和 String 互相转换

    static func fromStr(String)

    public static func fromStr(s: String): JsonValue
    

    功能:将字符串数据解析为 JsonValue。对于整数,支持前导 '0b','0o','0x'(不区分大小写),分别表示二进制,八进制和十六进制。字符串解析失败时将打印错误字符及其行数和列数,其中列数从错误字符所在行的非空格字符起开始计算。

    JSON 在解析 String 转换为 JsonValue 时,转义字符 \ 之后只能对应 JSON 支持的转义字符(b、f、n、r、t、u、\、"、/),其中 \u 的格式为:\uXXXX,X 为十六进制数,例:\u0041 代表字符 'A'。

    参数:

    • s: String - 传入字符串,暂不支持 "?" 和特殊字符。

    返回值:

    异常:

    • JsonException - 如果内存分配失败,或解析字符串出错,抛出异常。

    示例:

    import encoding.json.*
    
    main() {
        println(JsonString("\b | \f | \n | \r | \t | A | \\ | \" | /").toString())
        println(JsonValue.fromStr("\"\\b\"").toString())
        println(JsonValue.fromStr("\"\\f\"").toString())
        println(JsonValue.fromStr("\"\\n\"").toString())
        println(JsonValue.fromStr("\"\\r\"").toString())
        println(JsonValue.fromStr("\"\\t\"").toString())
        println(JsonValue.fromStr("\"\\u0041\"").toString())
        println(JsonValue.fromStr("\"\\\\\"").toString())
        println(JsonValue.fromStr("\"\\\"\"").toString())
        println(JsonValue.fromStr("\"\\/\"").toString())
    }
    

    运行结果如下:

    "\b | \f | \n | \r | \t | A | \\ | \" | /"
    "\b"
    "\f"
    "\n"
    "\r"
    "\t"
    "A"
    "\\"
    "\""
    "/"
    

    func asArray()

    public func asArray(): JsonArray
    

    功能:将 JsonValue 转换为 JsonArray 格式。

    返回值:

    异常:

    func asBool()

    public func asBool(): JsonBool
    

    功能:将 JsonValue 转换为 JsonBool 格式。

    返回值:

    异常:

    func asFloat()

    public func asFloat(): JsonFloat
    

    功能:将 JsonValue 转换为 JsonFloat 格式。

    返回值:

    异常:

    func asInt()

    public func asInt(): JsonInt
    

    功能:将 JsonValue 转换为 JsonInt 格式。

    返回值:

    异常:

    func asNull()

    public func asNull(): JsonNull
    

    功能:将 JsonValue 转换为 JsonNull 格式。

    返回值:

    异常:

    func asObject()

    public func asObject(): JsonObject
    

    功能:将 JsonValue 转换为 JsonObject 格式。

    返回值:

    异常:

    func asString()

    public func asString(): JsonString
    

    功能:将 JsonValue 转换为 JsonString 格式。

    返回值:

    异常:

    func kind()

    public func kind(): JsonKind
    

    功能:返回当前 JsonValue 所属的 JsonKind 类型。

    返回值:

    func toJsonString()

    public func toJsonString(): String
    

    功能:将 JsonValue 转换为 JSON 格式的 (带有空格换行符) 字符串。

    返回值:

    • String - 转换后的 JSON 格式字符串。

    func toString()

    public func toString(): String
    

    功能:将 JsonValue 转换为字符串。

    返回值:

    • String - 转换后的字符串。

    枚举

    enum JsonKind

    public enum JsonKind {
        | JsNull
        | JsBool
        | JsInt
        | JsFloat
        | JsString
        | JsArray
        | JsObject
    }
    

    功能:表示 JsonValue 的具体类型。

    JsArray

    JsArray
    

    功能:表示 JSON 类型中的数组类型。

    JsBool

    JsBool
    

    功能:表示 true 或者 false 类型。

    JsFloat

    JsFloat
    

    功能:表示值为浮点数的 number 类型。

    JsInt

    JsInt
    

    功能:表示值为整数的 number 类型。

    JsNull

    JsNull
    

    功能:表示 null 类型。

    JsObject

    JsObject
    

    功能:表述 JSON 类型中的对象类型。

    JsString

    JsString
    

    功能:表示 string 类型。

    异常

    class JsonException

    public class JsonException <: Exception {
        public init()
        public init(message: String)
    }
    

    功能:JSON 包的异常类,用于 JsonValue 类型使用时出现异常的场景。

    父类型:

    init()

    public init()
    

    功能:构造一个不包含任何异常提示信息的 JsonException 实例。

    init(String)

    public init(message: String)
    

    功能:根据指定的异常提示信息构造 JsonException 实例。

    参数:

    • message: String - 指定的异常提示信息。

    JsonArray 使用示例

    下面是 JsonArray 使用示例,该示例构造了一个 JsonArray 对象,并往其中添加了一些 JsonValue,最后以两种格式打印了该 JsonArray 对象。

    import encoding.json.*
    import std.collection.*
    
    main() {
        var a: JsonValue = JsonNull()
        var b: JsonValue = JsonBool(true)
        var c: JsonValue = JsonBool(false)
        var d: JsonValue = JsonInt(7363)
        var e: JsonValue = JsonFloat(736423.546)
        var list: ArrayList<JsonValue> = ArrayList<JsonValue>()
        var list2: ArrayList<JsonValue> = ArrayList<JsonValue>()
        var map = JsonObject()
        var map1 = JsonObject()
        map1.put("a", JsonString("jjjjjj"))
        map1.put("b", b)
        map1.put("c", JsonString("hhhhh"))
        list2.append(b)
        list2.append(JsonInt(3333333))
        list2.append(map1)
        list2.append(JsonString("sdfghgfasd"))
        list.append(b)
        list.append(a)
        list.append(map)
        list.append(c)
        list.append(JsonArray(list2))
        list.append(d)
        list.append(JsonString("ddddddd"))
        list.append(e)
        var result: JsonValue = JsonArray(list)
        println("func toString result is:")
        println(result.toString())
        println("func toJsonString result is:")
        println(result.toJsonString())
        0
    }
    

    运行结果如下:

    func toString result is:
    [true,null,{},false,[true,3333333,{"a":"jjjjjj","b":true,"c":"hhhhh"},"sdfghgfasd"],7363,"ddddddd",736423.546]
    func toJsonString result is:
    [
      true,
      null,
      {},
      false,
      [
        true,
        3333333,
        {
          "a": "jjjjjj",
          "b": true,
          "c": "hhhhh"
        },
        "sdfghgfasd"
      ],
      7363,
      "ddddddd",
      736423.546
    ]
    
    

    JsonValue 和 String 互相转换

    下面是 JsonValue 和 String 互相转换的示例,该示例使用 JsonValue.fromStr 将一个 JSON 字符串转换为 JsonValue,随后以两种格式打印了该 JsonValue 对象。

    import encoding.json.*
    
    main() {
        var str = ##"[true,"kjjjke\"eed",{"sdfd":"ggggg","eeeee":[341,false,{"nnnn":55.87}]},3422,22.341,false,[22,22.22,true,"ddd"],43]"##
        var jv: JsonValue = JsonValue.fromStr(str)
        var res = jv.toString()
        var prettyres = jv.toJsonString()
        println(res)
        println(prettyres)
        0
    }
    

    运行结果如下:

    [true,"kjjjke\"eed",{"sdfd":"ggggg","eeeee":[341,false,{"nnnn":55.87}]},3422,22.341,false,[22,22.22,true,"ddd"],43]
    [
      true,
      "kjjjke\"eed",
      {
        "sdfd": "ggggg",
        "eeeee": [
          341,
          false,
          {
            "nnnn": 55.87
          }
        ]
      },
      3422,
      22.341,
      false,
      [
        22,
        22.22,
        true,
        "ddd"
      ],
      43
    ]
    

    JsonValue 与 DataModel 的转换

    下面是 JSON 字符串与自定义类型间的转换的示例,该用例为 Person 类型实现了 Serializable 接口,随后进行了从 JSON 字符串到自定义类型的转换和从自定义类型到 JSON 字符串的转换。

    import serialization.serialization.*
    import encoding.json.*
    
    class Person <: Serializable<Person> {
        var name: String = ""
        var age: Int64 = 0
        var loc: Option<Location> = Option<Location>.None
    
        public func serialize(): DataModel {
            return DataModelStruct().add(field<String>("name", name)).add(field<Int64>("age", age)).add(field<Option<Location>>("loc", loc))
        }
    
        public static func deserialize(dm: DataModel): Person {
            var dms = match (dm) {
                case data: DataModelStruct => data
                case _ => throw Exception("this data is not DataModelStruct")
            }
            var result = Person()
            result.name = String.deserialize(dms.get("name"))
            result.age = Int64.deserialize(dms.get("age"))
            result.loc = Option<Location>.deserialize(dms.get("loc"))
            return result
        }
    }
    
    class Location <: Serializable<Location>{
        var country: String = ""
        var province: String = ""
    
        public func serialize(): DataModel {
            return DataModelStruct().add(field<String>("country", country)).add(field<String>("province", province))
        }
    
        public static func deserialize(dm: DataModel): Location {
            var dms = match (dm) {
                case data: DataModelStruct => data
                case _ => throw Exception("this data is not DataModelStruct")
            }
            var result = Location()
            result.country = String.deserialize(dms.get("country"))
            result.province = String.deserialize(dms.get("province"))
            return result
        }
    }
    
    main() {
        var js = ##"{
        "name": "A",
        "age": 30,
        "loc": {
            "country": "China",
            "province": "Beijing"
        }
    }"##
        var jv = JsonValue.fromStr(js)
        var dm = DataModel.fromJson(jv)
        var A = Person.deserialize(dm)
        println("name == ${A.name}")
        println("age == ${A.age}")
        println("country == ${A.loc.getOrThrow().country}")
        println("province == ${A.loc.getOrThrow().province}")
        println("====================") // 上部分实现从 JSON 字符串到自定义类型的转换,下部分实现从自定义类型到 JSON 字符串的转换。
        dm = A.serialize()
        var jo = dm.toJson().asObject()
        println(jo.toJsonString())
        0
    }
    

    运行结果如下:

    name == A
    age == 30
    country == China
    province == Beijing
    ====================
    {
      "name": "A",
      "age": 30,
      "loc": {
        "country": "China",
        "province": "Beijing"
      }
    }
    

    encoding.json.stream 包

    功能介绍

    json.stream 包主要用于仓颉对象和 JSON 数据流之间的互相转换。

    本包提供了 JsonWriter 和 JsonReader 类,JsonWriter 用于提供仓颉对象转 JSON 数据流的序列化能力;JsonReader 用于提供 JSON 数据流转仓颉对象的反序列化能力。

    当前实现中支持和 JSON 数据流互转的类型有:

    • 基础数据类型:String、Int8、Int16、Int32、Int64、Float16、Float32、Float64、UInt8、UInt16、UInt32、UInt64。

    • 集合类型:Array<T>、ArrayList<T>、HashMap<String, T>。

    • 其它类型:Option<T>、BigInt、Decimal。

    API 列表

    接口

    接口名功能
    JsonDeserializable<T>此接口用于实现从 JsonReader 中读取一个仓颉对象。
    JsonSerializable为类型提供序列化到 JSON 数据流的接口。

    类名功能
    JsonReader此类提供 JSON 数据流转仓颉对象的反序列化能力。
    JsonWriter构造函数,构造一个将数据写入 out 的实例。

    枚举

    枚举名功能
    JsonToken表示 JSON 编码的字符串中的结构、名称或者值类型。

    结构体

    结构体名功能
    WriteConfig用于表示 JsonWriter 的序列化格式配置。

    接口

    interface JsonDeserializable<T>

    public interface JsonDeserializable<T> {
        static func fromJson(r: JsonReader): T
    }
    

    功能:此接口用于实现从 JsonReader 中读取一个仓颉对象。

    支持的对象类型包括:

    static func fromJson(JsonReader)

    static func fromJson(r: JsonReader): T
    

    功能:从参数 r 指定的 JsonReader 实例中读取一个 T 类型对象。

    参数:

    返回值:

    • T - T 类型的实例。

    异常:

    extend BigInt <: JsonDeserializable<BigInt>

    extend BigInt <: JsonDeserializable<BigInt>
    

    功能:为 BigInt 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): BigInt
    

    功能:从 JsonReader 中读取一个 BigInt

    参数:

    返回值:

    • BigInt - BigInt 类型的实例。

    extend Bool <: JsonDeserializable<Bool>

    extend Bool <: JsonDeserializable<Bool>
    

    功能:为 Bool 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): Bool
    

    功能:从 JsonReader 中读取一个 Bool

    参数:

    返回值:

    • Bool - Bool 类型的实例。

    extend DateTime <: JsonDeserializable<DateTime>

    extend DateTime <: JsonDeserializable<DateTime>
    

    功能:为 DateTime 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): DateTime
    

    功能:从 JsonReader 中读取一个 DateTime 实例。

    该函数将会把读取到的字符串按照 RFC3339 的规范解析,可包含小数秒格式,函数的行为参考DateTimefunc parse(String)

    参数:

    返回值:

    • DateTime - DateTime 类型的实例。

    异常:

    extend Decimal <: JsonDeserializable<Decimal>

    extend Decimal <: JsonDeserializable<Decimal>
    

    功能:为 Decimal 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): Decimal
    

    功能:从 JsonReader 中读取一个 Decimal

    参数:

    返回值:

    • Decimal - Decimal 类型的实例。

    extend Float16 <: JsonDeserializable<Float16>

    extend Float16 <: JsonDeserializable<Float16>
    

    功能:为 Float16 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): Float16
    

    功能:从 JsonReader 中读取一个 Float16

    参数:

    返回值:

    • Float16 - Float16 类型的实例。

    异常:

    extend Float32 <: JsonDeserializable<Float32>

    extend Float32 <: JsonDeserializable<Float32>
    

    功能:为 Float32 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): Float32
    

    功能:从 JsonReader 中读取一个 Float32

    参数:

    返回值:

    • Float32 - Float32 类型的实例。

    异常:

    extend Float64 <: JsonDeserializable<Float64>

    extend Float64 <: JsonDeserializable<Float64>
    

    功能:为 Float64 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): Float64
    

    功能:从 JsonReader 中读取一个 Float64

    参数:

    返回值:

    • Float64 - Float64 类型的实例。

    异常:

    extend String <: JsonDeserializable<String>

    extend String <: JsonDeserializable<String>
    

    功能:为 String 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): String
    

    功能:从 JsonReader 中读取一个 String

    根据下一个 JsonToken 的不同,String 的反序列化结果将会不同:

    • 当下一个 JsonTokenJsonString 时, 反序列化过程会按照标准ECMA-404 The JSON Data Interchange Standard对读到的 String 进行转义。
    • 当下一个 JsonTokenJsonNumber JsonBool JsonNull 其中一个时,将会读取下一个 value 字段的原始字符串并返回。
    • 当下一个 JsonToken 是其它类型时,调用此接口会抛异常。

    参数:

    返回值:

    • String - String 类型的实例。

    extend Int16 <: JsonDeserializable<Int16>

    extend Int16 <: JsonDeserializable<Int16>
    

    功能:为 Int16 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): Int16
    

    功能:从 JsonReader 中读取一个 Int16

    参数:

    返回值:

    • Int16 - Int16 类型的实例。

    异常:

    extend Int32 <: JsonDeserializable<Int32>

    extend Int32 <: JsonDeserializable<Int32>
    

    功能:为 Int32 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): Int32
    

    功能:从 JsonReader 中读取一个 Int32

    参数:

    返回值:

    • Int32 - Int32 类型的实例。

    异常:

    extend Int64 <: JsonDeserializable<Int64>

    extend Int64 <: JsonDeserializable<Int64>
    

    功能:为 Int64 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): Int64
    

    功能:从 JsonReader 中读取一个 Int64

    参数:

    返回值:

    • Int64 - Int64 类型的实例。

    异常:

    extend Int8 <: JsonDeserializable<Int8>

    extend Int8 <: JsonDeserializable<Int8>
    

    功能:为 Int8 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): Int8
    

    功能:从 JsonReader 中读取一个 Int8

    参数:

    返回值:

    • Int8 - Int8 类型的实例。

    异常:

    extend IntNative <: JsonDeserializable<IntNative>

    extend IntNative <: JsonDeserializable<IntNative>
    

    功能:为 IntNative 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): IntNative
    

    功能:从 JsonReader 中读取一个 IntNative

    参数:

    返回值:

    异常:

    extend UInt16 <: JsonDeserializable<UInt16>

    extend UInt16 <: JsonDeserializable<UInt16>
    

    功能:为 UInt16 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): UInt16
    

    功能:从 JsonReader 中读取一个 UInt16

    参数:

    返回值:

    • UInt16 - UInt16 类型的实例。

    异常:

    extend UInt32 <: JsonDeserializable<UInt32>

    extend UInt32 <: JsonDeserializable<UInt32>
    

    功能:为 UInt32 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): UInt32
    

    功能:从 JsonReader 中读取一个 UInt32

    参数:

    返回值:

    • UInt32 - UInt32 类型的实例。

    异常:

    extend UInt64 <: JsonDeserializable<UInt64 >

    extend UInt64 <: JsonDeserializable<UInt64>
    

    功能:为 UInt64 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): UInt64
    

    功能:从 JsonReader 中读取一个 UInt64

    参数:

    返回值:

    • UInt64 - UInt64 类型的实例。

    异常:

    extend UInt8 <: JsonDeserializable<UInt8>

    extend UInt8 <: JsonDeserializable<UInt8>
    

    功能:为 UInt8 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): UInt8
    

    功能:从 JsonReader 中读取一个 UInt8

    参数:

    返回值:

    • UInt8 - UInt8 类型的实例。

    异常:

    extend UIntNative <: JsonDeserializable<UIntNative>

    extend UIntNative <: JsonDeserializable<UIntNative>
    

    功能:为 UIntNative 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): UIntNative
    

    功能:从 JsonReader 中读取一个 UIntNative

    参数:

    返回值:

    异常:

    extend<T> Array<T> <: JsonDeserializable<Array<T>> where T <: JsonSerializable

    extend<T> Array<T> <: JsonDeserializable<Array<T>> where T <: JsonDeserializable<T>
    

    功能:为 Array<T> 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): Array<T>
    

    功能:从 JsonReader 中读取一个 Array

    参数:

    返回值:

    • Array<T> - Array 类型的实例。

    extend<T> ArrayList<T> <: JsonDeserializable<ArrayList<T>> where T <: JsonSerializable

    extend<T> ArrayList<T> <: JsonDeserializable<ArrayList<T>> where T <: JsonDeserializable<T>
    

    功能:为 ArrayList 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): ArrayList<T>
    

    功能:从 JsonReader 中读取一个 ArrayList

    参数:

    返回值:

    • ArrayList <T> - ArrayList 类型的实例。

    extend<T> Option <T> <: JsonDeserializable<Option<T>> where T <: JsonSerializable

    extend<T> Option<T> <: JsonDeserializable<Option<T>> where T <: JsonDeserializable<T>
    

    功能:为 Option 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): Option<T>
    

    功能:从 JsonReader 中读取一个Option

    参数:

    返回值:

    • Option<T> - Option 类型的实例。

    extend<T> HashMap<String, T> <: JsonDeserializable<HashMap<String, T>> where T <: JsonDeserializable<T>

    extend<T> HashMap<String, T> <: JsonDeserializable<HashMap<String, T>> where T <: JsonDeserializable<T>
    

    功能:为 HashMap 类型实现 JsonDeserializable 接口。

    父类型:

    static func fromJson(JsonReader)

    public static func fromJson(r: JsonReader): HashMap<K, V>
    

    功能:从 JsonReader 中读取一个 HashMap

    参数:

    返回值:

    • HashMap<K, V> - HashMap<K, V> 类型的实例。

    interface JsonSerializable

    public interface JsonSerializable {
        func toJson(w: JsonWriter): Unit
    }
    

    功能:为类型提供序列化到 JSON 数据流的接口。

    JsonWriter 搭配使用,JsonWriter 可以将实现了 JsonSerializable 接口的类型写入到 Stream 中。

    func toJson(JsonWriter)

    func toJson(w: JsonWriter): Unit
    

    功能:将实现了 JsonSerializable 接口的类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend BigInt <: JsonSerializable

    extend BigInt <: JsonSerializable
    

    功能:为BigInt类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将BigInt类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend Bool <: JsonSerializable

    extend Bool <: JsonSerializable
    

    功能:为Bool类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将Bool类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend DateTime <: JsonSerializable

    extend DateTime <: JsonSerializable
    

    功能:为 DateTime 类型实现 JsonSerializable 接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:提供 DateTime 类型序列化到流的功能。

    该接口的功能与 JsonWriterwriteConfig中的属性 dateTimeFormat有关联,将会把 DateTime 按照dateTimeFormat中的格式输出到目标流中,可以通过修改dateTimeFormat实现不同的格式控制。

    参数:

    extend Decimal <: JsonSerializable

    extend Decimal <: JsonSerializable
    

    功能:为Decimal类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将Decimal类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend Float16 <: JsonSerializable

    extend Float16 <: JsonSerializable
    

    功能:为Float16类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将Float16类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend Float32 <: JsonSerializable

    extend Float32 <: JsonSerializable
    

    功能:为Float32类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将Float32类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend Float64 <: JsonSerializable

    extend Float64 <: JsonSerializable
    

    功能:为Float64类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将Float64类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend String <: JsonSerializable

    extend String <: JsonSerializable
    

    功能:为String类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将String类型写入参数 w 指定的 JsonWriter 实例中。写入的String

    参数:

    extend Int16 <: JsonSerializable

    extend Int16 <: JsonSerializable
    

    功能:为Int16类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将Int16类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend Int32 <: JsonSerializable

    extend Int32 <: JsonSerializable
    

    功能:为Int32类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将Int32类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend Int64 <: JsonSerializable

    extend Int64 <: JsonSerializable
    

    功能:为Int64类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将Int64类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend Int8 <: JsonSerializable

    extend Int8 <: JsonSerializable
    

    功能:为Int8类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将Int8类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend IntNative <: JsonSerializable

    extend IntNative <: JsonSerializable
    

    功能:为IntNative类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将IntNative类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend UInt16 <: JsonSerializable

    extend UInt16 <: JsonSerializable
    

    功能:为UInt16类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将UInt16类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend UInt32 <: JsonSerializable

    extend UInt32 <: JsonSerializable
    

    功能:为UInt32类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将UInt32类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend UInt64 <: JsonSerializable

    extend UInt64 <: JsonSerializable
    

    功能:为UInt64类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将UInt64类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend UInt8 <: JsonSerializable

    extend UInt8 <: JsonSerializable
    

    功能:为UInt8类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将UInt8类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend UIntNative <: JsonSerializable

    extend UIntNative <: JsonSerializable
    

    功能:为UIntNative类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将UIntNative类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend<T> Array<T> <: JsonSerializable where T <: JsonSerializable

    extend<T> Array<T> <: JsonSerializable where T <: JsonSerializable
    

    功能:为Array<T>类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将Array<T>类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend<T> ArrayList<T> <: JsonSerializable where T <: JsonSerializable

    extend<T> ArrayList<T> <: JsonSerializable where T <: JsonSerializable
    

    功能:为ArrayList<T>类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将ArrayList<T>类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend<T> Option<T> <: JsonSerializable where T <: JsonSerializable

    extend<T> Option<T> <: JsonSerializable where T <: JsonSerializable
    

    功能:为Option<T>类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将Option<T>类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    extend<V> HashMap<String, V> <: JsonSerializable where V <: JsonSerializable

    extend<V> HashMap<String, V> <: JsonSerializable where V <: JsonSerializable
    

    功能:为HashMap<K, V>类型提供序列化到 JSON 数据流的接口。

    父类型:

    func toJson(JsonWriter)

    public func toJson(w: JsonWriter): Unit
    

    功能:将HashMap<K, V>类型写入参数 w 指定的 JsonWriter 实例中。

    参数:

    class JsonReader

    public class JsonReader {
        public init(inputStream: InputStream)
    }
    

    功能:此类提供 JSON 数据流转仓颉对象的反序列化能力。

    示例:

    使用示例见使用 Json Stream 进行反序列化

    init(InputStream)

    public init(inputStream: InputStream)
    

    功能:根据输入流创建一个 JsonReaderJsonReader 从输入流中读取数据时,将跳过非 JsonString 中的空字符('\0', '\t', '\n', '\r')。

    参数:

    • inputStream: InputStream - 输入的 JSON 数据流。

    func endArray()

    public func endArray(): Unit
    

    功能:从输入流的当前位置跳过空白字符后消耗一个 ']' 字符,endArray 必须有一个 startArray 与之对应。

    异常:

    func endObject()

    public func endObject(): Unit
    

    功能:从输入流的当前位置跳过空白字符后消耗一个 '}' 字符,endObject 必须有一个 startObject 与之对应。

    异常:

    func peek()

    public func peek(): Option<JsonToken>
    

    功能:获取输入流的下一个 JsonToken 的类型,不保证下一个 JsonToken 的格式一定正确。

    例:如果输入流中的下一个字符为 't',获取的 JsonToken 将为 JsonToken.Bool,但调用 readValue<Bool>() 不一定成功。

    返回值:

    异常:

    • IllegalStateException - 如果输入流的下一个字符不在以下范围内:(n, t, f, ", 0~9, -, {, }, [, ])。

    func readName()

    public func readName(): String
    

    功能:从输入流的当前位置读取一个 name。

    返回值:

    • String - 读取出的 name 值。

    异常:

    func readValue<T>() where T <: JsonDeserializable<T>

    public func readValue<T>(): T where T <: JsonDeserializable<T>
    

    功能:从输入流的当前位置读取一个 value。

    注意:

    当泛型 T 是 String 类型时,根据下一个 JsonToken 的不同,该函数的返回值将会不同:

    返回值:

    • T - 读取出的 value 值。

    异常:

    func skip()

    public func skip(): Unit
    

    功能:从输入流的当前位置跳过一组数据。

    说明:

    Skip 的规则如下:

    • 如果 next token 是 value,跳过这个 value, 跳过 value 时不检查该 value 格式是否正确。

    • 如果 next token 是 Name,跳过 (name + value) 这一个组合。

    • 如果 next token 是 BeginArray,跳过这个 array。

    • 如果 next token 是 BeginObject,跳过这个 object。

    • 如果 next token 是 EndArray 或者 EndObject 或者 None,不做任何操作,peek 仍返回 EndArray 或者 EndObject 或者 None。

    异常:

    func startArray()

    public func startArray(): Unit
    

    功能:从输入流的当前位置跳过空白字符后消耗一个 '[' 字符。

    异常:

    func startObject()

    public func startObject(): Unit
    

    功能:从输入流的当前位置跳过空白字符后消耗一个 '{' 字符。

    异常:

    class JsonWriter

    public class JsonWriter {
        public init(out: OutputStream)
    }
    

    JsonWriter 提供了将仓颉对象序列化到 OutputStream 的能力。

    JsonWriter 需要和 interface JsonSerializable 搭配使用,JsonWriter 可以通过 writeValue 来将实现了 JsonSerializable 接口的类型写入到 Stream 中。

    注意:

    JsonWriter 中使用缓存来减少写入 Stream 时的 IO 次数,在结束使用 JsonWriter 之前需要调用 flush 函数来确保缓存中的数据全部写入 Stream。

    示例:

    使用示例见使用 Json Stream 进行序列化

    init(OutputStream)

    public init(out: OutputStream)
    

    功能:构造函数,构造一个将数据写入 out 的实例。

    参数:

    var writeConfig

    public var writeConfig = WriteConfig.compact
    

    功能:序列化格式配置。详见 WriteConfig

    func endArray()

    public func endArray(): Unit
    

    功能:结束序列化当前的 JSON 数组。

    异常:

    func endObject()

    public func endObject(): Unit
    

    功能:结束序列化当前的 JSON object。

    异常:

    func flush()

    public func flush(): Unit
    

    功能:将缓存中的数据写入 out,并且调用 out 的 flush 方法。

    func jsonValue()

    public func jsonValue(value: String): JsonWriter
    

    功能: 将符合JSON value规范的原始字符串写入stream。

    注意:

    此函数不会对值 value 进行转义,也不会为入参添加双引号。如果使用者能够保证输入的值 value 符合数据转换标准ECMA-404 The JSON Data Interchange Standard, 建议使用该函数。

    返回值:

    异常:

    func startArray()

    public func startArray(): Unit
    

    功能:开始序列化一个新的 JSON 数组,每一个 startArray 都必须有一个 endArray 对应。

    异常:

    func startObject()

    public func startObject(): Unit
    

    功能:开始序列化一个新的 JSON object,每一个 startObject 都必须有一个 endObject 对应。

    异常:

    func writeName(String)

    public func writeName(name: String): JsonWriter
    

    功能:在 object 结构中写入 name。

    返回值:

    异常:

    func writeNullValue()

    public func writeNullValue(): JsonWriter
    

    功能:向流中写入 JSON value null。

    返回值:

    异常:

    func writeValue<T>(T) where T <: JsonSerializable

    public func writeValue<T>(v: T): JsonWriter where T <: JsonSerializable
    

    功能:将实现了 JsonSerializable 接口的类型写入到 Stream 中。该接口会调用泛型 T 的 toJson 方法向输出流中写入数据。

    json.stream 包已经为基础类型 Int64UInt64Float64BoolString类型扩展实现了 JsonSerializable, 并且为 Collection 类型 ArrayArrayListHashMap 扩展实现了 JsonSerializable

    返回值:

    异常:

    枚举

    enum JsonToken

    public enum JsonToken <: Equatable<JsonToken> & Hashable{
        | JsonNull
        | JsonBool
        | JsonNumber
        | JsonString
        | BeginArray
        | EndArray
        | BeginObject
        | EndObject
        | Name
    }
    

    功能:表示 JSON 编码的字符串中的结构、名称或者值类型。

    JsonToken 通常和 JsonReader.peek()搭配使用,通过对返回值的判断来决定具体的处理方式。

    父类型:

    BeginArray

    BeginArray
    

    功能:表示 JSON 中 array 的开始。如果 JsonReader.peek() 返回的是该类型,可以使用 JsonReader.startArray() 读取。

    BeginObject

    BeginObject
    

    功能:表示 JSON 中 object 的开始。如果 JsonReader.peek() 返回的是该类型,可以使用 JsonReader.startObject() 读取。

    EndArray

    EndArray
    

    功能:表示 JSON 中 array 的结束。如果 JsonReader.peek() 返回的是该类型,可以使用 JsonReader.endArray() 读取。

    EndObject

    EndObject
    

    功能:表示 JSON 中 object 的结束。如果 JsonReader.peek() 返回的是该类型,可以使用 JsonReader.endObject() 读取。

    JsonBool

    JsonBool
    

    功能:表示 JSON 的 bool 类型。如果 JsonReader.peek() 返回的是该类型,可以使用 JsonReader.readValue<Bool>() 读取。

    JsonNull

    JsonNull
    

    功能:表示 JSON 的 null 类型。如果 JsonReader.peek() 返回的是该类型,可以使用 JsonReader.readValue<Option<T>>() 读取。

    JsonNumber

    JsonNumber
    

    功能:表示 JSON 的 number 类型。如果 JsonReader.peek() 返回的是该类型,可以使用 JsonReader.readValue<Float64>() 读取。

    JsonString

    JsonString
    

    功能:表示 JSON 的 string 类型。如果 JsonReader.peek() 返回的是该类型,可以使用 JsonReader.readValue<String>() 读取。

    Name

    Name
    

    功能:表示 object 中的 name。如果 JsonReader.peek() 返回的是该类型,可以使用 JsonReader.readName() 读取。

    func hashCode()

    public func hashCode(): Int64
    

    功能:获取 JsonToken 对象的 hashCode 值。

    返回值:

    • Int64 - hashCode 值。

    operator func !=(JsonToken)

    public operator func !=(that: JsonToken): Bool
    

    功能:判不等。

    参数:

    返回值:

    • Bool - 当前实例与 that 不相等返回 true,否则返回 false

    operator func ==(JsonToken)

    public operator func ==(that: JsonToken): Bool
    

    功能:判等。

    参数:

    返回值:

    • Bool - 当前实例与 that 相等返回 true,否则返回 false

    结构体

    struct WriteConfig

    public struct WriteConfig {
        public static let compact: WriteConfig
        public static let pretty: WriteConfig
    
        public mut prop htmlSafe: Bool
        public mut prop indent: String
        public mut prop newline: String
        public mut prop useSpaceAfterSeparators: Bool
        public mut prop dateTimeFormat: DateTimeFormat
    }
    

    功能:用于表示 JsonWriter 的序列化格式配置。

    示例:

    使用示例见 WriteConfig 使用示例

    static let compact

    public static let compact: WriteConfig
    

    功能:提供紧凑的序列化格式。

    说明:

    compact 的各属性值为:

    • newline: "",空字符串。
    • indent: "",空字符串。
    • useSpaceAfterSeparators: false。
    • htmlSafe: false。
    • dateTimeFormat: DateTimeFormat.RFC3339。

    类型:WriteConfig

    示例:

    {"Name":"zhangsan","Age":18,"Scores":[88.8,99.9],"Class":{"Name":"Class A","Students Number":33}}
    

    static let pretty

    public static let pretty: WriteConfig
    

    功能:提供整洁的序列化格式。

    说明:

    pretty 的各属性值为:

    • newline: "\n"。
    • indent: "    ",包含4个空格的字符串。
    • useSpaceAfterSeparators: true。
    • htmlSafe: false。
    • dateTimeFormat: DateTimeFormat.RFC3339。

    类型:WriteConfig

    示例:

    {
        "Name": "zhangsan",
        "Age": 18,
        "Scores": [
            88.8,
            99.9
        ],
        "Class": {
            "Name": "Class A",
            "Students Number": 33
        }
    }
    

    prop dateTimeFormat

    public mut prop dateTimeFormat: DateTimeFormat
    

    功能:用于序列化 DateTime 类型时的格式控制,功能与 DateTimefunc toString(DateTimeFormat)一致。

    类型:DateTimeFormat

    prop htmlSafe

    public mut prop htmlSafe: Bool
    

    功能:用于表示是否转义 HTML 字符 <>&='

    该值为 true 时,会将 HTML 字符转义为对应的 Unicode 编码的字符串。

    该选项只对 json value 中的字符串字面量有效。

    类型:Bool

    prop indent

    public mut prop indent: String
    

    功能:用于表示序列化时每个缩进级别填入的缩进字符串。取值应匹配正则 ^[ \t]*$

    当上述的换行起作用时,该值会作为换行后的填充符。

    类型:String

    异常:

    prop newline

    public mut prop newline: String
    

    功能:用于表示序列化时填入的换行符。取值应匹配正则 ^[\r\n]*$

    当该值不为空字符串且合法时,JsonWriter 调用 startObject 和 startArray 操作、插入元素、以及它们的结束操作会产生新的换行。

    当该值为空字符串时,不会触发换行。

    类型:String

    异常:

    prop useSpaceAfterSeparators

    public mut prop useSpaceAfterSeparators: Bool
    

    功能:用于表示序列化时在 ':' 和 ',' 后是否加一个空格。

    该值为 true 时,每插入一个 field name 或者 array 元素后会自动写入一个空格。

    该选项只对 json Object 中的 field 以及 json Array 中的元素有效。

    类型:Bool

    使用 Json Stream 进行反序列化

    代码如下:

    import encoding.json.stream.*
    import std.io.*
    import std.collection.*
    
    class A <: JsonDeserializable<A> {
        var key1: Option<String> = None
        var key2: Bool = false
        var key3: Float64 = 0.0
        var key4: String = ""
        var key5: Array<Int64> = Array<Int64>()
        var key6: HashMap<String, String> = HashMap<String, String>()
    
        public static func fromJson(r: JsonReader): A {
            var res = A()
            while (let Some(v) <- r.peek()) {
                match(v) {
                    case BeginObject =>
                        r.startObject()
                        while(r.peek() != EndObject) {
                            let n = r.readName()
                            match (n) {
                                case "key1" => res.key1 = r.readValue<Option<String>>()
                                case "key2" => res.key2 = r.readValue<Bool>()
                                case "key3" => res.key3 = r.readValue<Float64>()
                                case "key4" => res.key4 = r.readValue<String>()
                                case "key5" => res.key5 = r.readValue<Array<Int64>>()
                                case "key6" => res.key6 = r.readValue<HashMap<String, String>>()
                                case _ => ()
                            }
                        }
                        r.endObject()
                        break
                    case _ => throw Exception()
                }
            }
            return res
        }
    
        func toString(): String {
            return "${key1}\n${key2}\n${key3}\n${key4}\n${key5}\n${key6}"
        }
    }
    
    main() {
        let jsonStr = ##"{"key1": null, "key2": true, "key3": 123.456, "key4": "string", "key5": [123, 456], "key6": {"key7": " ", "key8": "\\a"}}"##
        var bas = ByteBuffer()
        unsafe { bas.write(jsonStr.rawData()) }
        var reader = JsonReader(bas)
        var obj = A.fromJson(reader)
        println(obj.toString())
    }
    

    运行结果如下:

    None
    true
    123.456000
    string
    [123, 456]
    [(key7,  ), (key8, \a)]
    

    使用 Json Stream 进行序列化

    代码如下:

    import encoding.json.stream.*
    import std.io.{ByteBuffer, readToEnd}
    
    class Image <: JsonSerializable {
        var width: Int64
        var height: Int64
        var title: String
        var ids: Array<Int64>
    
        public init() {
            width = 0
            height = 0
            title = ""
            ids = Array<Int64>()
        }
    
        public func toJson(w: JsonWriter): Unit {
            w.startObject() // start encoding an object
            w.writeName("Width").writeValue(width) // write name and value pair in current object
            w.writeName("Height").writeValue(height)
            w.writeName("Title").writeValue(title)
            w.writeName("Ids").writeValue<Array<Int64>>(ids) //use class Array's func toJson
            w.endObject()// end current object
        }
    }
    
    
    main(){
        let image = Image()
        image.width = 800
        image.height = 600
        image.title = "View from 15th Floor"
        image.ids = [116, 943, 234, 38793]
    
        let stream = ByteBuffer() // output
        let writer = JsonWriter(stream) // init a JsonWriter
        writer.writeValue(image) // serialize image to JSON
        writer.flush()
        println(String.fromUtf8(readToEnd(stream)))
    }
    

    运行结果如下:

    {"Width":800,"Height":600,"Title":"View from 15th Floor","Ids":[116,943,234,38793]}
    

    WriteConfig 使用示例

    代码如下:

    import encoding.json.stream.{JsonWriter, WriteConfig, JsonSerializable}
    import std.io.ByteBuffer
    
    main() {
        // 构造 JsonWriter
        let buffer = ByteBuffer()
        let writer = JsonWriter(buffer)
    
        // 设置 JSON 写格式配置
        let fmtCfg = WriteConfig.pretty
        writer.writeConfig = fmtCfg
    
        // 写 JSON 
        writer.writeValue(MyObj())
    
        // 打印 JSON 序列化字符串
        println(String.fromUtf8(buffer.bytes()))
    
        0
    }
    
    // 支持 JSON 序列化的类
    class MyObj <: JsonSerializable {
        public func toJson(w: JsonWriter): Unit {
            w.startObject()
            w.writeName("Name").writeValue("zhangsan")
            w.writeName("Age").writeValue(18)
            w.writeName("Scores").writeValue([88.8, 99.9])
            w.writeName("Class")
            w.startObject()
            w.writeName("Name").writeValue("Class A")
            w.writeName("Students Number").writeValue(33)
            w.endObject()
            w.endObject()
            w.flush()
        }
    }
    

    运行结果:

    {
        "Name": "zhangsan",
        "Age": 18,
        "Scores": [
            88.8,
            99.9
        ],
        "Class": {
            "Name": "Class A",
            "Students Number": 33
        }
    }
    

    encoding.url 包

    功能介绍

    url 包提供了 URL 相关的能力,包括解析 URL 的各个组件,对 URL 进行编解码,合并 URL 或路径等。

    URL(Uniform Resource Locator)是统一资源定位符的缩写,它是用来标识互联网上资源位置的一种地址。通常包含协议、主机名、路径和查询参数等信息,其中协议是指访问资源所使用的协议(如 HTTP、FTP 等),主机名是指资源所在的服务器的域名或 IP 地址,路径是指资源所在的具体位置,查询参数是指用于传递参数的字符串。URL 是互联网上标识资源的唯一方式,通过 URL 可以访问网页、图片、视频等各种类型的资源。

    URL 一般是以下格式:

    scheme://host[:port]/path[?query][#fragment]
    

    其中:

    • scheme:协议,例如 httphttpsftp 等;
    • host:主机名或 IP 地址;
    • port:端口号,可选,默认为协议默认端口;
    • path:资源路径,例如 /index.html/blog/post/123 等;
    • query:查询参数,例如 ?page=2&sort=desc 等,可选;
    • fragment:文档片段标识符,例如 #section-1,可选。

    例如,网址 https://www.example.com/blog/post/123?page=2&sort=desc#section-1 的 URL 格式为:

    • scheme: https
    • host: www.example.com
    • path: /blog/post/123
    • query: ?page=2&sort=desc
    • fragment: #section-1

    URL 编码的原因和基本过程:

    URL 编码是将 URL 中的非 ASCII 字符转换为一种可读性更好的 ASCII 字符的过程。这是因为 URL 中只允许包含 ASCII 字符,而非 ASCII 字符可能会导致 URL 解析错误或传输失败。

    URL 编码的基本过程如下:

    1. 将 URL 字符串转换为字节数组。
    2. 对于每个非 ASCII 字符,将其转换为 UTF-8 编码的字节序列。
    3. 对于每个字节,将其转换为两个十六进制数字。
    4. 在每个十六进制数字前添加一个百分号(%)。
    5. 将所有编码后的字符连接起来形成编码后的 URL 字符串。

    例如,将字符串“你好,世界!”进行 URL 编码,结果为“%E4%BD%A0%E5%A5%BD%EF%BC%8C%E4%B8%96%E7%95%8C%EF%BC%81”。

    API 列表

    类名功能
    FormForm 以 key-value 键值对形式存储 http 请求的参数,同一个 key 可以对应多个 value,value 以数组形式存储。
    URL该类提供解析 URL 的函数以及其他相关函数。
    UserInfoUserInfo 表示 URL 中用户名和密码信息。

    异常类

    异常类名功能
    UrlSyntaxExceptionurl 解析异常类。

    class Form

    public class Form {
        public init()
        public init(queryComponent: String)
    }
    

    功能:Form 以 key-value 键值对形式存储 http 请求的表单信息,通常为请求 URL 中的 query 部分。

    同一个 key 可以对应多个 value,value 以数组形式存储。& 符号分隔多个键值对;= 分隔的左侧作为 key 值,右侧作为 value 值(没有 = 或者 value 为空,均是允许的)。

    init()

    public init()
    

    功能:构造一个默认的 Form 实例。

    init(String)

    public init(queryComponent: String)
    

    功能:根据 URL 编码的查询字符串,即 URL 实例的 query 部分构造 Form 实例。

    解析 URL 编码的查询字符串,得到若干键值对,并将其添加到新构造的 Form 实例中。

    参数:

    • queryComponent: String - URL 的 query 组件部分的字符串,但是不包括组件前面的 ? 符号。

    异常:

    func add(String, String)

    public func add(key: String, value: String): Unit
    

    功能:新增 key-value 映射,如果 key 已存在,则将 value 添加到原来 value 数组的最后面。

    参数:

    • key: String - 指定键,可以是新增的。
    • value: String - 将该值添加到指定键对应的值数组中。

    func clone()

    public func clone(): Form
    

    功能:克隆 Form

    返回值:

    • Form - 克隆得到的新 Form 实例。

    func get(String)

    public func get(key: String): Option<String>
    

    功能:根据 key 获取第一个对应的 value 值。

    举例:

    • 当 query 组件部分是 a=b 时,form.get("a")获得 Some(b)
    • 当 query 组件部分是 a= 时,form.get("a")获得 Some()
    • 当 query 组件部分是 a 时,form.get("a")获得 Some()
    • 当 query 组件部分是 a 时,form.get("c")获得 None

    参数:

    返回值:

    func getAll(String)

    public func getAll(key: String): ArrayList<String>
    

    功能:根据指定的键(key)获取该键(key)对应的所有 value 值。

    参数:

    • key: String - 用户指定的键(key),用于获取对应的 value 值。

    返回值:

    • ArrayList<String> - 根据指定键(key)获取的全部 value 值对应的数组。当指定键(key)不存在时,返回空数组。

    func isEmpty()

    public func isEmpty(): Bool
    

    功能:判断 Form 是否为空。

    返回值:

    • Bool - 如果为空,则返回 true;否则,返回 false。

    func remove(String)

    public func remove(key: String): Unit
    

    功能:删除 key 及其对应 value。

    参数:

    • key: String - 需要删除的键。

    func set(String, String)

    public func set(key: String, value: String): Unit
    

    功能:重置指定 key 对应的 value。

    参数:

    • key: String - 指定键。
    • value: String - 将指定键的值设置为 value。

    func toEncodeString()

    public func toEncodeString(): String
    

    功能:对表单中的键值对进行编码,编码采用百分号编码。

    未保留字符不会被编码,空格将编码为 '+'。

    说明:

    RFC 3986 协议中对未保留字符定义如下: unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"

    返回值:

    • String - 编码后的字符串。

    class URL

    public class URL <: ToString {
        public init(scheme!: String, hostName!: String, path!: String)
    }
    

    功能:该类提供解析 URL 的函数以及其他相关函数。

    字符串中被百分号%编码的内容会被解码,保存在相应的组件之中,而初始值保存在相应的 raw 属性之中。URL 中的用户名和密码部分(如果存在的话)也会按照 RFC 3986 协议的说明被解析。

    注意:

    RFC 3986 明确说明在任何场景下,明文保存用户信息存在被泄露风险,所以建议不要在 URL 中明文保存用户信息。

    父类型:

    prop fragment

    public prop fragment: ?String
    

    功能:获取解码后的锚点组件,用字符串表示。

    类型:?String

    prop host

    public prop host: String
    

    功能:获取解码后的主机名和端口部分,用字符串表示。

    类型:String

    prop hostName

    public prop hostName: String
    

    功能:获取解码后的主机名,用字符串表示。

    类型:String

    prop opaque

    public prop opaque: String
    

    功能:获取 URL 中不透明部分,用字符串表示。

    类型:String

    prop path

    public prop path: String
    

    功能:获取解码后的路径,用字符串表示。

    类型:String

    prop port

    public prop port: String
    

    功能:获取端口号,用字符串表示,空字符串表示无端口号。

    类型:String

    prop query

    public prop query: ?String
    

    功能:获取解码后的查询组件,用字符串表示。

    类型:?String

    prop queryForm

    public prop queryForm: Form
    

    功能:获取解码后的查询组件,用 Form 实例表示。

    类型:Form

    prop rawFragment

    public prop rawFragment: ?String
    

    功能:获取解码前的锚点组件,用字符串表示。

    类型:?String

    prop rawPath

    public prop rawPath: String
    

    功能:获取解码前的路径,用字符串表示。

    类型:String

    prop rawQuery

    public prop rawQuery: ?String
    

    功能:获取解码前的查询组件,用字符串表示。

    类型:?String

    prop rawUserInfo

    public prop rawUserInfo: UserInfo
    

    功能:获取解码前的用户名和密码信息,用 UserInfo 实例表示。

    类型:UserInfo

    prop scheme

    public prop scheme: String
    

    功能:获取 URL 中协议部分,用字符串表示。

    类型:String

    prop userInfo

    public prop userInfo: UserInfo
    

    功能:获取解码后的用户名和密码信息,用 UserInfo 实例表示。

    类型:UserInfo

    init(String, String, String)

    public init(scheme!: String, hostName!: String, path!: String)
    

    功能:构造一个 URL 实例。

    构造实例时需要满足要求:

    • 拥有主机名 hostName 时,需要有协议 scheme。
    • 不能只存在协议 scheme。
    • 存在协议和路径的情况下,路径 path 必须是绝对路径。

    参数:

    • scheme!: String - 协议类型。
    • hostName!: String - 不包含端口号的主机名。
    • path!: String - 请求资源的路径。

    异常:

    static func mergePaths(String, String)

    public static func mergePaths(basePath: String, refPath: String): String
    

    功能:合并两个路径。

    合并规则:将引用路径 refPath 追加到基础路径 basePath 的最后一段。如果 refPath 是绝对路径,结果就是 refPath 原本的值。如果 refPath 不是绝对路径,则将自身拼接至 basePath 最后一个 / 后,所有结果最终都会进行标准化(路径中的.字符,..字符,以及多个连续的 / 字符都会被优化)。具体行为可以参照下面示例。更详细行为参考 RFC 3986 协议。

    如需合并 URL 请使用 resolveURL

    例如:

    • /a/b/c 合并 /d 输出 /d
    • /a/b/c 合并 d 输出 /a/b/d
    • /a/b/ 合并 d/e/../f 输出 /a/b/d/f
    • /a/b/c/ 合并 ./../../g 输出 /a/g

    参数:

    • basePath: String - 基础路径。
    • refPath: String - 引用路径。

    返回值:

    • String - 合并且标准化后的路径。

    static func parse(String)

    public static func parse(rawUrl: String): URL
    

    功能:将原始 URL 字符串解析成 URL 对象。

    这个函数会将 URL 按照组件分解,然后分别进行解码并存储在相应的组件属性中,而 rawXXX (此处泛指前缀是 raw 的 URL 属性)属性部分存储的是原始值,不做编解码处理。

    使用示例请参见URL 解析函数 parse 的使用

    注意:

    该函数可以解析 URL 中的用户名和密码(如果存在),这是符合 RFC 3986 协议的解析功能的,但是 RFC 3986 也明确指出,任何场景下,明文保存用户信息存在被泄露风险,所以建议不要在 URL 中明文保存用户信息。

    参数:

    返回值:

    • URL - 解析字符串得到的 URL 实例。

    异常:

    func isAbsoluteURL()

    public func isAbsoluteURL(): Bool
    

    功能:判断 URL 是否为绝对 URL(scheme 存在时,URL 是绝对 URL)。

    返回值:

    • Bool - scheme 存在时返回 true,不存在时返回 false。

    func replace(Option<String>, Option<String>, Option<String>, Option<String>, Option<String>, Option<String>, Option<String>)

    public func replace(scheme!: Option<String> = None, userInfo!: Option<String> = None,
     hostName!: Option<String> = None, port!: Option<String> = None, path!: Option<String> = None, 
     query!: Option<String> = None, fragment!: Option<String> = None): URL
    

    功能:替换 URL 对象的各组件,并且返回一个新的 URL 对象。

    替换时需要满足以下要求:

    • 方案 scheme 为空时,主机名必须为空。
    • 主机名为空时,用户信息或端口号必须为空。
    • 方案 scheme 不为空时,主机名和路径不能同时为空。
    • 方案 scheme 不为空时,路径必须是绝对路径。
    • 任意组件均为合法字符。

    参数:

    返回值:

    异常:

    func resolveURL(URL)

    public func resolveURL(ref: URL): URL
    

    功能:以当前 URL 实例为基础 URL,以传入的 URL 为参考 URL,根据 RFC 3986 协议生成一个新的 URL 实例。

    例如:http://a/b/c/d;p?q 为基础 URL,以下 = 左边为参考 URL,右边为生成的新 URL

    更多详细的 URL 生成规则,请参见 RFC 3968 协议。

    参数:

    • ref: URL - 参考 URL 对象。

    返回值:

    func toString()

    public func toString(): String
    

    功能:获取当前 URL 实例的字符串值。

    会把 hostName 编码,其余部分取 rawXXX (此处泛指前缀是 raw 的 URL 属性)属性值,按照 URL 组件构成顺序进行拼接而获得该函数返回值。

    返回值:

    • String - 当前 URL 实例的字符串值。

    class UserInfo

    public class UserInfo <: ToString {
        public init()
        public init(userName: String)
        public init(userName: String, passWord: String)
        public init(userName: String, passWord: Option<String>)
    }
    

    功能:UserInfo 表示 URL 中用户名和密码信息。

    注意:

    RFC 3986 明确指出,任何场景下,明文保存用户信息存在被泄露风险,所以建议不要在 URL 中明文保存用户信息。

    父类型:

    init()

    public init()
    

    功能:创建 UserInfo 实例。

    init(String)

    public init(userName: String)
    

    功能:根据用户名创建 UserInfo 实例。

    参数:

    • userName: String - 用户名。

    init(String, Option<String>)

    public init(userName: String, passWord: Option<String>)
    

    功能:根据用户名和密码创建 UserInfo 实例。 参数:

    init(String, String)

    public init(userName: String, passWord: String)
    

    功能:根据用户名和密码创建 UserInfo 实例。 参数:

    • userName: String - 用户名。
    • passWord: String - 密码。

    func password()

    public func password(): Option<String>
    

    功能:获取密码信息。

    注意:

    RFC 3986 明确指出,任何场景下,明文保存用户信息存在被泄露风险,所以建议不要在 URL 中明文保存用户信息。

    返回值:

    func toString()

    public func toString(): String
    

    功能:将当前 UserInfo 实例转换为字符串。

    返回值:

    func username()

    public func username(): String
    

    功能:获取用户名信息。

    返回值:

    • String - 字符串类型的用户名。

    异常类

    class UrlSyntaxException

    public class UrlSyntaxException <: Exception {
        public init(reason: String)
        public init(input: String, reason: String)
    }
    

    功能:URL 解析异常类。

    父类型:

    init(String)

    public init(reason: String)
    

    功能:根据错误原因构造 UrlSyntaxException 实例。

    参数:

    • reason: String - 解析错误的原因。

    init(String, String)

    public init(input: String, reason: String)
    

    功能:根据 URL 及错误原因构造 UrlSyntaxException 实例。

    参数:

    • input: String - 原生 URL 或其片段。
    • reason: String - 解析错误的原因。

    init(String, String, String)

    public init(input: String, reason: String, pos: String)
    

    功能:根据 URL 字符串,错误原因以及解析失败的部分,构造 UrlSyntaxException 实例。

    参数:

    • input: String - 原生 URL 或其片段。
    • reason: String - 解析错误的原因。
    • pos: String - 给定 URL 字符串中解析失败的部分。

    Form 的构造使用

    Form 的构造与其函数 get 的使用

    创建 Form 类,并通过 get 获取 key 对应映射的 value。

    代码如下:

    示例中使用 Form 类的函数 get 获取指定 key = 1 的 value 值 2 。

    import encoding.url.*
    
    main(): Int64 {
        var s = Form("1=2&2=3&1=2&&")
        print(s.get("1").getOrThrow())
        return 0
    }
    

    运行结果如下:

    2
    

    Form 的构造与重复 key 情况下函数 get 的使用

    创建 Form 类,并通过 get 获取 key 对应映射的 value。

    代码如下:

    示例中使用 Form 类的函数 get 获取指定 key = 1 的第一个 value 值 %6AD。value 中的 %6A 被解码为 j,因此得到 value 值 jD 。

    import encoding.url.*
    
    main(): Int64 {
       var s = Form("2=3&1=%6AD&1=2")
       // 对于 %6A 解码成 j,重复的 key 调用 get 获取第一个 value 值 jD
       print(s.get("1").getOrThrow())
       return 0
    }
    

    运行结果如下:

    jD
    

    Form 的构造与其他函数使用

    分别调用 add,set,clone,打印输出前后变化。

    代码如下:

    import encoding.url.*
    
    main(): Int64 {
        var f = Form()
        // 给键 k 增加值 v1 和 v2。
        f.add("k", "v1")
        f.add("k", "v2")
        // 调用 get 方法时,获取的是第一个值。
        println(f.get("k").getOrThrow())
        // 设定键 k 的值为 v
        f.set("k", "v")
        println(f.get("k").getOrThrow())
        let clone_f = f.clone()
        // 给克隆出来的 clone_f 增加键值对。
        clone_f.add("k1", "v1")
        // 通过 get 获得值 v1。
        println(clone_f.get("k1").getOrThrow())
        // 原来的 f 并没有键 k1,所以值是给的默认值 kkk。
        println(f.get("k1") ?? "kkk")
        0
    }
    

    运行结果如下:

    v1
    v
    v1
    kkk
    

    URL 解析函数 parse 的使用

    使用 parse 函数解析 URL 字符串,生成 URL 对象。

    代码如下:

    示例中对一个地址进行了解析并获得了 URL 对象,并且打印该对象的各个属性。

    import encoding.url.*
    
    main(): Int64 {
        // 调用 URL 静态函数 parse 解析网址获得名为 url 的对象。
        var url = URL.parse("http://www.example.com:80/path%E4%BB%93%E9%A2%89?key=value%E4%BB%93%E9%A2%89#%E4%BD%A0%E5%A5%BD")
        // 打印 url 的组件属性。
        println("url.scheme = ${url.scheme}")
        println("url.opaque = ${url.opaque}")
        println("url.userInfo = ${url.userInfo}")
        println("url.rawUserInfo = ${url.rawUserInfo}")
        println("url.host = ${url.host}")
        println("url.hostName = ${url.hostName}")
        println("url.port = ${url.port}")
        println("url.path = ${url.path}")
        println("url.rawPath = ${url.rawPath}")
        println("url.query = ${url.query.getOrThrow()}")
        println("url.rawQuery = ${url.rawQuery.getOrThrow()}")
        println("url.fragment = ${url.fragment.getOrThrow()}")
        println("url.rawfragment = ${url.rawFragment.getOrThrow()}")
        println("url = ${url}")
        return 0
    }
    

    运行结果如下:

    url.scheme = http
    url.opaque =
    url.userInfo =
    url.rawUserInfo =
    url.host = www.example.com:80
    url.hostName = www.example.com
    url.port = 80
    url.path = /path仓颉
    url.rawPath = /path%E4%BB%93%E9%A2%89
    url.query = key=value仓颉
    url.rawQuery = key=value%E4%BB%93%E9%A2%89
    url.fragment = 你好
    url.rawfragment = %E4%BD%A0%E5%A5%BD
    url = http://www.example.com:80/path%E4%BB%93%E9%A2%89?key=value%E4%BB%93%E9%A2%89#%E4%BD%A0%E5%A5%BD
    

    fuzz 模块

    fuzz 功能介绍

    fuzz 模块提供基于覆盖率反馈的模糊测试能力。其主要功能是自动生成大量随机的输入数据,以检测目标软件在各种异常情况下的稳定性和安全性。

    fuzz 模块的包列表

    fuzz 模块提供了如下包:

    包名功能
    fuzzfuzz 包为开发者提供基于覆盖率反馈的仓颉 fuzz 引擎及对应的接口,开发者可以编写代码对 API 进行测试。

    fuzz.fuzz 包

    功能介绍

    Fuzz 技术是一种自动化软件测试方法,旨在发现软件中的漏洞和错误。它通过持续输入随机或经过变异的测试用例来执行软件程序,并根据程序的覆盖率信息来指导测试的方向。

    fuzz 包为开发者提供基于覆盖率反馈的仓颉 fuzz 引擎及对应的接口,开发者可以编写代码对 API 进行测试。当前支持通过传入 fuzz 引擎变异的字节流 (Array<UInt8>) 或符合仓颉的标准数据类型(FuzzDataProvider)进行 fuzz 测试。

    使用此包需要配合需覆盖率反馈插桩(SanitizerCoverage)功能使用,需要开发者对 fuzz 测试有一定的了解,初学者建议先学习 C 语言的 Fuzz 工具 libFuzzer

    使用本包需要外部依赖 LLVM 套件 compiler-rt 提供的 libclang_rt.fuzzer_no_main.a 静态库,当前支持 Linux 以及 macOS,不支持 Windows。

    通常使用包管理工具即可完成安装,例如 Ubuntu 22.04 系统上可使用 sudo apt install clang 进行安装,安装后可以在 clang -print-runtime-dir 指向的目录下找到对应的 libclang_rt.fuzzer_no_main.a 文件,例如 /usr/lib/llvm-14/lib/clang/14.0.0/lib/linux/libclang_rt.fuzzer_no_main-x86_64.a,将来在链接时会用到它。

    API 列表

    类名功能
    FuzzerFuzzer 类提供了 fuzz 工具的创建。
    FuzzerBuilder此类用于 Fuzzer 类的构建。
    FuzzDataProviderFuzzDataProvider 是一个工具类,目的是将变异数据的字节流转化为标准的仓颉基本数据。
    DebugDataProvider此类继承了 FuzzDataProvider 类型,额外增加了调试信息。

    异常类

    异常类名功能
    ExhaustedException此异常为转换数据时,剩余数据不足以转换时抛出的异常。

    常量&变量

    let FUZZ_VERSION

    public let FUZZ_VERSION = "1.0.0"
    

    功能:Fuzz 版本。

    类型:String

    class DebugDataProvider

    public class DebugDataProvider <: FuzzDataProvider
    

    功能:此类继承了 FuzzDataProvider 类型,额外增加了调试信息。

    父类型:

    func consumeAll()

    public override func consumeAll(): Array<UInt8>
    

    功能:将所有数据转换成 UInt8 类型数组。

    返回值:

    func consumeAllAsAscii()

    public override func consumeAllAsAscii(): String
    

    功能:将所有数据转换成 Ascii String 类型。

    返回值:

    func consumeAllAsString()

    public override func consumeAllAsString(): String
    

    功能:将所有数据转换成 utf8 String 类型。

    返回值:

    func consumeAsciiString(Int64)

    public override func consumeAsciiString(maxLength: Int64): String
    

    功能:将数据转换成 Ascii String 类型实例。

    参数:

    返回值:

    func consumeBool()

    public override func consumeBool(): Bool
    

    功能:将数据转换成 Bool 类型实例。

    返回值:

    func consumeBools(Int64)

    public override func consumeBools(count: Int64): Array<Bool>
    

    功能:将指定数量的数据转换成 Bool 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeByte()

    public override func consumeByte(): Byte
    

    功能:将数据转换成 Byte 类型实例。

    返回值:

    func consumeBytes(Int64)

    public override func consumeBytes(count: Int64): Array<Byte>
    

    功能:将指定数量的数据转换成 Byte 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeFloat32()

    public override func consumeFloat32(): Float32
    

    功能:将数据转换成 Float32 类型实例。

    返回值:

    func consumeFloat64()

    public override func consumeFloat64(): Float64
    

    功能:将数据转换成 Float64 类型实例。

    返回值:

    func consumeInt16()

    public override func consumeInt16(): Int16
    

    功能:将数据转换成 Int16 类型实例。

    返回值:

    func consumeInt16s(Int64)

    public override func consumeInt16s(count: Int64): Array<Int16>
    

    功能:将指定数量的数据转换成 Int16 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeInt32()

    public override func consumeInt32(): Int32
    

    功能:将数据转换成 Int32 类型实例。

    返回值:

    func consumeInt32s(Int64)

    public override func consumeInt32s(count: Int64): Array<Int32>
    

    功能:将指定数量的数据转换成 Int32 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeInt64()

    public override func consumeInt64(): Int64
    

    功能:将数据转换成 Int64 类型实例。

    返回值:

    func consumeInt64s(Int64)

    public override func consumeInt64s(count: Int64): Array<Int64>
    

    功能:将指定数量的数据转换成 Int64 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeInt8()

    public override func consumeInt8(): Int8
    

    功能:将数据转换成 Int8 类型实例。

    返回值:

    func consumeInt8s(Int64)

    public override func consumeInt8s(count: Int64): Array<Int8>
    

    功能:将指定数量的数据转换成 Int8 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeRune()

    public override func consumeRune(): Rune
    

    功能:将数据转换成 Rune 类型实例。

    返回值:

    func consumeString(Int64)

    public override func consumeString(maxLength: Int64): String
    

    功能:将数据转换成 utf8 String 类型实例。

    参数:

    返回值:

    func consumeUInt16()

    public override func consumeUInt16(): UInt16
    

    功能:将数据转换成 UInt16 类型实例。

    返回值:

    func consumeUInt16s(Int64)

    public override func consumeUInt16s(count: Int64): Array<UInt16>
    

    功能:将指定数量的数据转换成 UInt16 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeUInt32()

    public override func consumeUInt32(): UInt32
    

    功能:将数据转换成 UInt32 类型实例。

    返回值:

    func consumeUInt32s(Int64)

    public override func consumeUInt32s(count: Int64): Array<UInt32>
    

    功能:将指定数量的数据转换成 UInt32 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeUInt64()

    public override func consumeUInt64(): UInt64
    

    功能:将数据转换成 UInt64 类型实例。

    返回值:

    func consumeUInt64s(Int64)

    public override func consumeUInt64s(count: Int64): Array<UInt64>
    

    功能:将指定数量的数据转换成 UInt64 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeUInt8()

    public override func consumeUInt8(): UInt8
    

    功能:将数据转换成 UInt8 类型实例。

    返回值:

    func consumeUInt8s(Int64)

    public override func consumeUInt8s(count: Int64): Array<UInt8>
    

    功能:将指定数量的数据转换成 UInt8 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func wrap(FuzzDataProvider)

    public static func wrap(dp: FuzzDataProvider): DebugDataProvider
    

    功能:根据 FuzzDataProvider 实例创建 DebugDataProvider 实例。

    参数:

    返回值:

    class Fuzzer

    public class Fuzzer {
        public init(targetFunction: (Array<UInt8>) -> Int32)
        public init(targetFunction: (Array<UInt8>) -> Int32, args: Array<String>)
        public init(targetFunction: (FuzzDataProvider) -> Int32)
        public init(targetFunction: (FuzzDataProvider) -> Int32, args: Array<String>)
    }
    

    功能:Fuzzer 类提供了 fuzz 工具的创建。用户提供需要进行 fuzz 测试的函数 targetFunction,以及设置特定的 fuzz 运行参数 args 比如 fuzz 执行次数、初始种子、生成数据最大长度等,可创建相应类型的 Fuzzer

    init((Array<UInt8>) -> Int32)

    public init(targetFunction: (Array<UInt8>) -> Int32)
    

    功能:根据以 UInt8 数组为参数,以 Int32 为返回值的目标函数,创建 Fuzzer 实例。

    参数:

    init((Array<UInt8>) -> Int32, Array<String>)

    public init(targetFunction: (Array<UInt8>) -> Int32, args: Array<String>)
    

    功能:根据以 UInt8 数组为参数,以 Int32 为返回值的目标函数,以及 Fuzz 运行参数,创建 Fuzzer 实例。

    参数:

    init((FuzzDataProvider) -> Int32)

    public init(targetFunction: (FuzzDataProvider) -> Int32)
    

    功能:根据以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数,创建 Fuzzer 实例。

    参数:

    init((FuzzDataProvider) -> Int32, Array<String>)

    public init(targetFunction: (FuzzDataProvider) -> Int32, args: Array<String>)
    

    功能:根据以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数,以及 Fuzz 运行参数,创建 Fuzzer 实例。

    参数:

    func disableDebugDataProvider()

    public func disableDebugDataProvider(): Unit
    

    功能:关闭调试信息打印功能,当 FuzzDataProvider.consumeXXX 被调用时,返回值将不被打印到 stdout

    func disableFakeCoverage()

    public func disableFakeCoverage(): Unit
    

    功能:关闭调用 enableFakeCoverage 对 Fuzz 的影响。

    func enableDebugDataProvider()

    public func enableDebugDataProvider(): Unit
    

    功能:启用调试信息打印功能,当 FuzzDataProvider.consumeXXX 被调用时,返回值将被打印到 stdout。该功能默认为关闭。

    func enableFakeCoverage()

    public func enableFakeCoverage(): Unit
    

    功能:创建一块虚假的覆盖率反馈区域,保持 Fuzz 持续进行。在 FuzzDataProvider 模式下,前几轮运行时可能由于数据不足而导致没有覆盖率,libfuzzer 会退出。该功能默认为关闭。

    func getArgs()

    public func getArgs(): Array<String>
    

    功能:获取 Fuzz 运行参数。

    返回值:

    func setArgs(Array<String>)

    public func setArgs(args: Array<String>): Unit
    

    功能:设置 Fuzz 运行参数。

    参数:

    func setTargetFunction((Array<UInt8>) -> Int32)

    public func setTargetFunction(targetFunction: (Array<UInt8>) -> Int32): Unit
    

    功能:设置 Fuzz 目标函数。

    参数:

    func setTargetFunction((FuzzDataProvider) -> Int32)

    public func setTargetFunction(targetFunction: (FuzzDataProvider) -> Int32): Unit
    

    功能:设置 Fuzz 目标函数。

    参数:

    func startFuzz()

    public func startFuzz(): Unit
    

    功能:执行 Fuzz。

    class FuzzerBuilder

    public class FuzzerBuilder {
        public init(targetFunction: (Array<UInt8>) -> Int32)
        public init(targetFunction: (FuzzDataProvider) -> Int32)
    }
    

    功能:此类用于 Fuzzer 类的构建。

    init((Array<UInt8>) -> Int32)

    public init(targetFunction: (Array<UInt8>) -> Int32)
    

    功能:根据以 UInt8 数组为参数,以 Int32 为返回值的目标函数,创建 FuzzerBuilder 实例。

    参数:

    init((FuzzDataProvider) -> Int32)

    public init(targetFunction: (FuzzDataProvider) -> Int32)
    

    功能:根据以 FuzzDataProvider 为参数,以 Int32 为返回值的目标函数,创建 FuzzerBuilder 实例。

    参数:

    func build()

    public func build(): Fuzzer
    

    功能:生成一个 Fuzzer 实例。

    返回值:

    func setArgs(Array<String>)

    public func setArgs(args: Array<String>): FuzzerBuilder
    

    功能:设置 Fuzz 运行参数。

    参数:

    返回值:

    func setTargetFunction((Array<UInt8>) -> Int32)

    public func setTargetFunction(targetFunction: (Array<UInt8>) -> Int32): FuzzerBuilder
    

    功能:设置 Fuzz 目标函数。

    参数:

    返回值:

    func setTargetFunction((FuzzDataProvider) -> Int32)

    public func setTargetFunction(targetFunction: (FuzzDataProvider) -> Int32): FuzzerBuilder
    

    功能:设置 Fuzz 目标函数。

    参数:

    返回值:

    class FuzzDataProvider

    public open class FuzzDataProvider {
        public let data: Array<UInt8>
        public var remainingBytes: Int64
        public var offset: Int64
    }
    

    功能:FuzzDataProvider 是一个工具类,目的是将变异数据的字节流转化为标准的仓颉基本数据。

    当前支持的数据结构如下:

    目标类型API说明
    BoolconsumeBool()获取 1 个 Bool,变异数据长度不足时,抛出 ExhaustedException
    Array<Bool>consumeBools(count: Int64)获取 N 个 Bool,变异数据长度不足时,抛出 ExhaustedException
    ByteconsumeByte()获取 1 个 Byte,变异数据长度不足时,抛出 ExhaustedException
    Array<Byte>consumeBytes(count: Int64)获取 N 个 Byte,变异数据长度不足时,抛出 ExhaustedException
    UInt8consumeUInt8()获取 1 个 UInt8,变异数据长度不足时,抛出 ExhaustedException
    UInt16consumeUInt16()获取 1 个 UInt16,变异数据长度不足时,抛出 ExhaustedException
    UInt32consumeUInt32()获取 1 个 UInt32,变异数据长度不足时,抛出 ExhaustedException
    UInt64consumeUInt64()获取 1 个 UInt64,变异数据长度不足时,抛出 ExhaustedException
    Int8consumeInt8()获取 1 个 Int8,变异数据长度不足时,抛出 ExhaustedException
    Int16consumeInt16()获取 1 个 Int16,变异数据长度不足时,抛出 ExhaustedException
    Int32consumeInt32()获取 1 个 Int32,变异数据长度不足时,抛出 ExhaustedException
    Int32consumeInt32()获取 1 个 Int32,变异数据长度不足时,抛出 ExhaustedException
    Float32consumeFloat32()获取 1 个 Float32,变异数据长度不足时,抛出 ExhaustedException
    Float64consumeFloat64()获取 1 个 Float64,变异数据长度不足时,抛出 ExhaustedException
    Array<UInt8>consumeUInt8s(count: Int64)获取 N 个 UInt8,变异数据长度不足时,抛出 ExhaustedException
    Array<UInt16>consumeUInt16s(count: Int64)获取 N 个 UInt16,变异数据长度不足时,抛出 ExhaustedException
    Array<UInt32>consumeUInt32s(count: Int64)获取 N 个 UInt32,变异数据长度不足时,抛出 ExhaustedException
    Array<UInt64>consumeUInt64s(count: Int64)获取 N 个 UInt64,变异数据长度不足时,抛出 ExhaustedException
    Array<Int8>consumeInt8s(count: Int64)获取 N 个 Int8,变异数据长度不足时,抛出 ExhaustedException
    Array<Int16>consumeInt16s(count: Int64)获取 N 个 Int16,变异数据长度不足时,抛出 ExhaustedException
    Array<Int32>consumeInt32s(count: Int64)获取 N 个 Int32,变异数据长度不足时,抛出 ExhaustedException
    Array<Int32>consumeInt32s(count: Int64)获取 N 个 Int32,变异数据长度不足时,抛出 ExhaustedException
    RuneconsumeRune()获取 1 个 Rune,变异数据长度不足时,抛出 ExhaustedException
    StringconsumeAsciiString(maxLength: Int64)获取 1 个纯 ASCII 的 String,长度为 0 到 maxLength,可以为 0。
    StringconsumeString(maxLength: Int64)获取 1 个 UTF8 String,长度为 0 到 maxLength,可以为 0。
    Array<UInt8>consumeAll()FuzzDataProvider 中的剩余内容全部转化为字节数组。
    StringconsumeAllAsAscii()FuzzDataProvider 中的剩余内容全部转化为纯 ASCII 的 String
    StringconsumeAllAsString()FuzzDataProvider 中的剩余内容全部转化为 UTF8 String,末尾多余的字符不会被消耗。

    在数据长度不足时,调用上述大部分虽然会抛出 ExhaustedException,但编写 fuzz 函数时通常并不需要对它进行处理,ExhaustedException 默认会被 fuzz 框架捕获,告诉 libfuzzer 该次运行无效,请继续下一轮变异。随着执行时间的变长,变异数据也会逐渐变长,直到满足 FuzzDataProvider 的需求。

    如果达到了 max_len 仍无法满足 FuzzDataProvider 的需求,则进程退出,请修改 fuzz 测试用例(推荐) 或 增大 max_len(不推荐)。

    let data

    public let data: Array<UInt8>
    

    功能:变异数据。

    类型:Array<UInt8>

    var offset

    public var offset: Int64
    

    功能:已转化的字节数。

    类型:Int64

    var remainingBytes

    public var remainingBytes: Int64
    

    功能:剩余字节数。

    类型:Int64

    func consumeAll()

    public open func consumeAll(): Array<UInt8>
    

    功能:将所有数据转换成 UInt8 类型数组。

    返回值:

    func consumeAllAsAscii()

    public open func consumeAllAsAscii(): String
    

    功能:将所有数据转换成 Ascii String 类型。

    返回值:

    func consumeAllAsString()

    public open func consumeAllAsString(): String
    

    功能:将所有数据转换成 utf8 String 类型。

    返回值:

    func consumeAsciiString(Int64)

    public open func consumeAsciiString(maxLength: Int64): String
    

    功能:将数据转换成 Ascii String 类型实例。

    参数:

    返回值:

    func consumeBool()

    public open func consumeBool(): Bool
    

    功能:将数据转换成 Bool 类型实例。

    返回值:

    func consumeBools(Int64)

    public open func consumeBools(count: Int64): Array<Bool>
    

    功能:将指定数量的数据转换成 Bool 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeByte()

    public open func consumeByte(): Byte
    

    功能:将数据转换成 Byte 类型实例。

    返回值:

    func consumeBytes(Int64)

    public open func consumeBytes(count: Int64): Array<Byte>
    

    功能:将指定数量的数据转换成 Byte 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeFloat32()

    public open func consumeFloat32(): Float32
    

    功能:将数据转换成 Float32 类型实例。

    返回值:

    func consumeFloat64()

    public open func consumeFloat64(): Float64
    

    功能:将数据转换成 Float64 类型实例。

    返回值:

    func consumeInt16()

    public open func consumeInt16(): Int16
    

    功能:将数据转换成 Int16 类型实例。

    返回值:

    func consumeInt16s(Int64)

    public open func consumeInt16s(count: Int64): Array<Int16>
    

    功能:将指定数量的数据转换成 Int16 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeInt32()

    public open func consumeInt32(): Int32
    

    功能:将数据转换成 Int32 类型实例。

    返回值:

    func consumeInt32s(Int64)

    public open func consumeInt32s(count: Int64): Array<Int32>
    

    功能:将指定数量的数据转换成 Int32 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeInt64()

    public open func consumeInt64(): Int64
    

    功能:将数据转换成 Int64 类型实例。

    返回值:

    func consumeInt64s(Int64)

    public open func consumeInt64s(count: Int64): Array<Int64>
    

    功能:将指定数量的数据转换成 Int64 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeInt8()

    public open func consumeInt8(): Int8
    

    功能:将数据转换成 Int8 类型实例。

    返回值:

    func consumeInt8s(Int64)

    public open func consumeInt8s(count: Int64): Array<Int8>
    

    功能:将指定数量的数据转换成 Int8 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeRune()

    public open func consumeRune(): Rune
    

    功能:将数据转换成 Rune 类型实例。

    返回值:

    func consumeString(Int64)

    public open func consumeString(maxLength: Int64): String
    

    功能:将数据转换成 utf8 String 类型实例。

    参数:

    返回值:

    func consumeUInt16()

    public open func consumeUInt16(): UInt16
    

    功能:将数据转换成 UInt16 类型实例。

    返回值:

    func consumeUInt16s(Int64)

    public open func consumeUInt16s(count: Int64): Array<UInt16>
    

    功能:将指定数量的数据转换成 UInt16 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeUInt32()

    public open func consumeUInt32(): UInt32
    

    功能:将数据转换成 UInt32 类型实例。

    返回值:

    func consumeUInt32s(Int64)

    public open func consumeUInt32s(count: Int64): Array<UInt32>
    

    功能:将指定数量的数据转换成 UInt32 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeUInt64()

    public open func consumeUInt64(): UInt64
    

    功能:将数据转换成 UInt64 类型实例。

    返回值:

    func consumeUInt64s(Int64)

    public open func consumeUInt64s(count: Int64): Array<UInt64>
    

    功能:将指定数量的数据转换成 UInt64 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    func consumeUInt8()

    public open func consumeUInt8(): UInt8
    

    功能:将数据转换成 UInt8 类型实例。

    返回值:

    func consumeUInt8s(Int64)

    public open func consumeUInt8s(count: Int64): Array<UInt8>
    

    功能:将指定数量的数据转换成 UInt8 类型数组。

    参数:

    • count: Int64 - 指定转换的数据量。

    返回值:

    static func withCangjieData(Array<UInt8>)

    public static func withCangjieData(data: Array<UInt8>): FuzzDataProvider
    

    功能:使用 Array<UInt8> 类型的数据生成 FuzzDataProvider 类型实例。

    参数:

    返回值:

    static func withNativeData(CPointer<UInt8>, Int64)

    public static unsafe func withNativeData(data: CPointer<UInt8>, length: Int64): FuzzDataProvider
    

    功能:使用 C 指针数据生成 FuzzDataProvider 类型实例。

    参数:

    返回值:

    异常类

    class ExhaustedException

    public class ExhaustedException <: Exception {
        public init()
        public init(message: String)
    }
    

    功能:此异常为转换数据时,剩余数据不足以转换时抛出的异常。

    父类型:

    init()

    public init()
    

    功能:创建 ExhaustedException 实例。

    init(String)

    public init(message: String)
    

    功能:创建 ExhaustedException 实例。

    参数:

    • message: String - 异常提示信息。

    测试猜测字符功能

    • 编写被测 API,当且仅当输入数组长度是 8、内容是 "Cangjie!" 对应的 ASCII 时抛出异常,纯随机的情况下最差需要 264 次猜测才会触发异常。
    • 创建 Fuzzer 并且调用待测 API,进入主流程。
    // 导入依赖的类
    import fuzz.fuzz.Fuzzer
    
    main() {
        // 创建Fuzzer并启动fuzz流程
        Fuzzer(api).startFuzz()
        return 0
    }
    
    
    // 被测函数,在满足特定条件会抛出异常,该异常会被 Fuzzer 捕获
    public func api(data: Array<UInt8>): Int32 {
        if (data.size == 8 && data[0] == b'C' && data[1] == b'a' && data[2] == b'n' && data[3] == b'g' && data[4] == b'j' &&
            data[5] == b'i' && data[6] == b'e' && data[7] == b'!') {
            throw Exception("TRAP")
        }
        return 0
    }
    

    Linux 的编译命令是:cjc fuzz_main.cj --link-options="--whole-archive $CANGJIE_HOME/lib/linux_x86_64_llvm/libclang_rt.fuzzer_no_main.a -no-whole-archive -lstdc++" --sanitizer-coverage-inline-8bit-counters

    macOS 的编译命令是:cjc fuzz_main.cj --link-options="$CANGJIE_HOME/lib/linux_x86_64_llvm/libclang_rt.fuzzer_no_main.a -lc++" --sanitizer-coverage-inline-8bit-counters

    释义:

    • link-options 是链接时选项,fuzz 库本身依赖符号 LLVMFuzzerRunDriver,该符号需要开发者自行解决。
      • 仓颉语言在 $CANGJIE_HOME/lib/linux_x86_64_llvm/libclang_rt.fuzzer_no_main.a 存放一份 修改过 的 libfuzzer,对标准的 libfuzzer 进行了增强,见 实验性特性-覆盖率信息打印
      • 可以使用 find $(clang -print-runtime-dir) -name "libclang_rt.fuzzer_no_main*.a" 寻找本地安装好的静态库文件。
    • 向 Linux 编译需要使用 whole-archive libfuzzer.a 是因为 cjc 调用 ld 后端时,从左到右顺序是 libfuzzer.alibcangjie-fuzz-fuzz.a、 libc 等基础库,该顺序会导致 libcangjie-fuzz-fuzz.a 依赖的 LLVMFuzzerRunDriver 符号未被找到。解决方案有:
      • libfuzzer.a 放到 libcangjie-fuzz-fuzz.a 后面;
      • 使用 whole-archive libfuzzer.a 来规避符号找不到的问题。
    • -lstdc++ (Linux) / -lc++ (macOS) 用于链接 libfuzzer 依赖的 std 库。
    • --sanitizer-coverage-inline-8bit-counterscjc 的编译选项,它会对当前 package 执行覆盖率反馈插桩,详见 cjc 编译器使用手册。
      • 其他高级的参数有:--sanitizer-coverage-trace-compares(提高Fuzz变异的效率)、--sanitizer-coverage-pc-table(Fuzz结束后打印覆盖率信息)。

    libfuzzer 体验类似,可以直接运行,数秒后(取决于 CPU 性能)可获得 crash,且输入的数据是 "Cangjie!"

    运行结果

    $ ./main
    INFO: Seed: 246468919
    INFO: Loaded 1 modules   (15 inline 8-bit counters): 15 [0x55bb7c76dcb0, 0x55bb7c76dcbf),
    INFO: -max_len is not provided; libFuzzer will not generate inputs larger than 4096 bytes
    INFO: A corpus is not provided, starting from an empty corpus
    #2      INITED ft: 4 corp: 1/1b exec/s: 0 rss: 28Mb
    #420    NEW    ft: 5 corp: 2/9b lim: 8 exec/s: 0 rss: 28Mb L: 8/8 MS: 3 CrossOver-InsertByte-InsertRepeatedBytes-
    #1323   NEW    ft: 6 corp: 3/17b lim: 14 exec/s: 0 rss: 28Mb L: 8/8 MS: 3 InsertByte-InsertByte-CrossOver-
    #131072 pulse  ft: 6 corp: 3/17b lim: 1300 exec/s: 65536 rss: 35Mb
    #262144 pulse  ft: 6 corp: 3/17b lim: 2600 exec/s: 65536 rss: 41Mb
    #295225 NEW    ft: 7 corp: 4/25b lim: 2930 exec/s: 73806 rss: 43Mb L: 8/8 MS: 2 ShuffleBytes-ChangeByte-
    #514006 NEW    ft: 8 corp: 5/33b lim: 4096 exec/s: 73429 rss: 53Mb L: 8/8 MS: 1 ChangeByte-
    #524288 pulse  ft: 8 corp: 5/33b lim: 4096 exec/s: 74898 rss: 53Mb
    #1048576        pulse  ft: 8 corp: 5/33b lim: 4096 exec/s: 61680 rss: 78Mb
    #1064377        NEW    ft: 9 corp: 6/41b lim: 4096 exec/s: 62610 rss: 79Mb L: 8/8 MS: 1 ChangeByte-
    #1287268        NEW    ft: 10 corp: 7/49b lim: 4096 exec/s: 61298 rss: 90Mb L: 8/8 MS: 1 ChangeByte-
    #2097152        pulse  ft: 10 corp: 7/49b lim: 4096 exec/s: 59918 rss: 128Mb
    #2875430        NEW    ft: 11 corp: 8/57b lim: 4096 exec/s: 61179 rss: 165Mb L: 8/8 MS: 2 ChangeBinInt-ChangeByte-
    #4194304        pulse  ft: 11 corp: 8/57b lim: 4096 exec/s: 59918 rss: 227Mb
    #4208258        NEW    ft: 12 corp: 9/65b lim: 4096 exec/s: 60117 rss: 228Mb L: 8/8 MS: 3 CrossOver-CrossOver-ChangeBit-
    [WARNING]: Detect uncatched exception, maybe caused by bugs, exit now
    An exception has occurred:
    Exception: TRAP
             at default.api(std/core::Array<...>)(/data/Cangjie/fuzz_main.cj:14)
             at _ZN7default3apiER_ZN8std$core5ArrayIhE_cc_wrapper(/data/Cangjie/fuzz_main.cj:0)
             at libfuzzerCallback(fuzz/fuzz/callback.cj:20)
    [INFO]: data is: [67, 97, 110, 103, 106, 105, 101, 33]
    [INFO]: data base64: Q2FuZ2ppZSE=
    crash file will stored with libfuzzer
    ==899957== ERROR: libFuzzer: fuzz target exited
    SUMMARY: libFuzzer: fuzz target exited
    MS: 1 ChangeByte-; base unit: 7d8b0108ce76a937161065eafcde95bbf3d47dbf
    0x43,0x61,0x6e,0x67,0x6a,0x69,0x65,0x21,
    Cangjie!
    artifact_prefix='./'; Test unit written to ./crash-555e7af32a2ceb585cdd9ce810c4804e65d41cea
    Base64: Q2FuZ2ppZSE=
    

    使用 DataProvider 功能进行测试

    除了使用字节流对 API 进行测试的方法之外,fuzz 包提供了 FuzzDataProvider 类,用于更友好地从变异的数据源产生仓颉的标准数据类型,方便对 API 进行测试。

    public func api2(dp: FuzzDataProvider): Int32 {
        if(dp.consumeBool() && dp.consumeByte() == b'A' && dp.consumeuint32() == 0xdeadbeef){
            throw Exception("TRAP")
        }
        return 0
    }
    

    此案例中,开启 --sanitizer-coverage-trace-compares 可有效提高 fuzz 效率。

    DataProvider 模式下,无法直观地判断各个 API 返回值分别是什么,因此提供了 Fuzzer.enableDebugDataProvider() 和 DebugDataProvider,在 startFuzz 前调用 enableDebugDataProvider() 即可令本次 fuzz 每次调用 consumeXXX 时打印日志。

    例如,上文代码触发异常后,添加 enableDebugDataProvider 重新编译,效果如下。

    import fuzz.fuzz.*
    
    main() {
        let fuzzer = Fuzzer(api2)
        fuzzer.enableDebugDataProvider()
        fuzzer.startFuzz()
        return 0
    }
    

    运行结果

    ./main crash-d7ece8e77ff25769a5d55eb8d3093d4bace78e1b
    Running: crash-d7ece8e77ff25769a5d55eb8d3093d4bace78e1b
    [DEBUG] consumeBool return true
    [DEBUG] consumeByte return 65
    [DEBUG] consumeUInt32 return 3735928559
    [WARNING]: Detect uncatched exception, maybe caused by bugs, exit now
    An exception has occurred:
    Exception: TRAP
             at default.api2(fuzz/fuzz::FuzzDataProvider)(/tmp/test.cj:12)
             at _ZN7default4api2EC_ZN9fuzz$fuzz16FuzzDataProviderE_cc_wrapper(/tmp/test.cj:0)
             at libfuzzerCallback(fuzz/fuzz/callback.cj:0)
    [INFO]: data is: [191, 65, 239, 190, 173, 222]
    

    使用 FakeCoverage 避免 DataProvider 模式下 Fuzz 异常终止

    在链接了 libfuzzer <= 14 的情况下,且处于 DataProvider 模式下,遇到了类似如下的错误,可能需要阅读此章节:

    ERROR: no interesting inputs were found. Is the code instrumented for coverage? Exiting.
    

    libfuzzer 15 起,修复了该 feature,即使初始化时拒绝了输入,也不会停止执行。

    注意:请确认被测试的库确实被插入了覆盖率反馈,因为在没有覆盖率反馈插桩的情况下,也会出现该错误!

    当前 fuzz 后端对接到了 libfuzzer,而 libfuzzer 在启动时会先输入空字节流、再输入仅包含一个 '\n' 的字节流对待测函数进行试探,在两轮结束后检测覆盖率是否新增。在 DataProvider 模式下,如果先消耗数据,再调用待测库的 API,会导致消耗数据时长度不足而提前返回,从而 libfuzzer 认为覆盖率信息为零。

    例如下方代码,会触发该错误

    触发的代码:

    // main.cj
    import fuzz.fuzz.*
    
    main() {
        let f = Fuzzer(api)
        f.disableFakeCoverage()
        f.startFuzz()
        return 0
    }
    
    // fuzz_target.cj, with sancov
    public func api(dp: FuzzDataProvider): Int32 {
        if (dp.consumeBool() && dp.consumeBool()) {
            throw Exception("TRAP!")
        }
        return 0
    }
    

    运行结果:

    ...
    ERROR: no interesting inputs were found. Is the code instrumented for coverage? Exiting.
    ...
    

    因此,需要使用 Fake Coverage 创建虚假的覆盖率信息,让 libfuzzer 在初始化期间认为待测模块确实被插桩,等到 DataProvider 收集到足够数据后,再进行有效的 fuzz 测试。该模式被称为 Fake Coverage 模式。

    将上文的 disableFakeCoverage() 替换为 enableFakeCoverage() 即可继续运行,最终触发 TRAP。

    此外,除了使用 Fake Coverage 模式,还可以在测试用例中主动调用待测函数的某些不重要的API来将覆盖率信息传递给 libfuzzer,也能起到让 fuzz 继续下去的作用。

    // main.cj
    import fuzz.fuzz.*
    
    main() {
        let f = Fuzzer(api)
        f.enableFakeCoverage()
        f.startFuzz()
        return 0
    }
    
    // fuzz_target.cj, with sancov
    public func api(dp: FuzzDataProvider): Int32 {
        if (dp.consumeBool() && dp.consumeBool()) {
            throw Exception("TRAP!")
        }
        return 0
    }
    

    运行结果:

    INFO: Running with entropic power schedule (0xFF, 100).
    INFO: Seed: 3187548846
    INFO: Loaded 2 modules   (8 inline 8-bit counters): 7 [0x55bf83ea8790, 0x55bf83ea8797), 1 [0x55bf83e97b00, 0x55bf83e97b01),
    INFO: -max_len is not provided; libFuzzer will not generate inputs larger than 4096 bytes
    INFO: A corpus is not provided, starting from an empty corpus
    #2      INITED ft: 5 corp: 1/1b exec/s: 0 rss: 33Mb
    #9      NEW    ft: 6 corp: 2/2b lim: 4 exec/s: 0 rss: 33Mb L: 1/1 MS: 2 CopyPart-ChangeByte-
    [WARNING]: Detect uncatched exception, maybe caused by bugs, exit now
    An exception has occurred:
    Exception: TRAP!
    ...
    ...
    

    打印 fuzz 使用方法

    可以使用 -help=1 打印帮助,-seed=246468919 指定随机数的种子。

    运行结果

    $ ./main -help=1                                                                                                                                                                                        exit 130
    Usage:
    To run fuzzing pass 0 or more directories.
    program_name [-flag1=val1 [-flag2=val2 ...] ] [dir1 [dir2 ...] ]
    To run individual tests without fuzzing pass 1 or more files:
    program_name [-flag1=val1 [-flag2=val2 ...] ] file1 [file2 ...]
    

    实验性特性-覆盖率信息打印

    仓颉 fuzzer 支持使用 -print_coverage=1 作为启动参数运行 fuzzer,用于统计各函数的测试情况,该特性在持续完善中,只与输出覆盖率报告有关,不影响 fuzz 过程。

    由于该功能需要对 libfuzzer 进行侵入式修改,使用该功能需要链接仓颉自带的 libfuzzer,路径是:$CANGJIE_HOME/lib/{linux_x86_64_llvm, linux_aarch64_llvm}/libclang_rt-fuzzer_no_main.a。

    编译时需要同时启用--sanitizer-coverage-inline-8bit-counters--sanitizer-coverage-pc-table

    C 语言 libfuzzer 输出举例

    ./a.out -print_coverage=1
    COVERAGE:
    COVERED_FUNC: hits: 5 edges: 6/8 LLVMFuzzerTestOneInput /tmp/test.cpp:5
      UNCOVERED_PC: /tmp/test.cpp:6
      UNCOVERED_PC: /tmp/test.cpp:9
    

    仓颉语言 cj-fuzz 输出举例

    ./main -print_coverage=1 -runs=100
    Done 100 runs in 0 second(s)
    COVERAGE:
    COVERED_FUNC: hits: 1 edges: 3/12 ttt <unknown cj filename>:<unknown cj line number>
      UNCOVERED_PC: <unknown cj filename>:<unknown cj line number>
      UNCOVERED_PC: <unknown cj filename>:<unknown cj line number>
      UNCOVERED_PC: <unknown cj filename>:<unknown cj line number>
      UNCOVERED_PC: <unknown cj filename>:<unknown cj line number>
      UNCOVERED_PC: <unknown cj filename>:<unknown cj line number>
      UNCOVERED_PC: <unknown cj filename>:<unknown cj line number>
      UNCOVERED_PC: <unknown cj filename>:<unknown cj line number>
      UNCOVERED_PC: <unknown cj filename>:<unknown cj line number>
      UNCOVERED_PC: <unknown cj filename>:<unknown cj line number>
    UNCOVERED_FUNC: hits: 0 edges: 0/2 main <unknown cj filename>:<unknown cj line number>
    COVERED_FUNC: hits: 1 edges: 1/1 ttt_cc_wrapper <unknown cj filename>:<unknown cj line number>
    

    栈回溯缺失的处理方案

    当前在启动 fuzz 时默认会有这三条 WARNING,因为当前 cj-fuzz 没有对它们进行实现。

    WARNING: Failed to find function "__sanitizer_acquire_crash_state".
    WARNING: Failed to find function "__sanitizer_print_stack_trace".
    WARNING: Failed to find function "__sanitizer_set_death_callback".
    

    在 fuzz 过程中,可能会因为以下 3 种情况而结束 fuzz 流程:

    1. 抛出异常
    2. 超时
    3. 在 C 代码中 crash

    其中“抛出异常”的情况,fuzz 框架对异常进行捕获后会打印栈回溯,不会造成栈回溯缺失的现象。

    “超时”和“在 C 代码中 crash”实际是在 native 代码中触发了 SIGNAL,不属于仓颉异常,因此会造成栈回溯的缺失。

    libfuzzer 会尝试使用 __sanitizer_acquire_crash_state__sanitizer_print_stack_trace__sanitizer_set_death_callback 等函数处理异常情况,其中 __sanitizer_print_stack_trace 会打印栈回溯,目前成熟的实现在 llvm compiler-rt 中的 asan 等模块中。

    因此,建议的解决方案是在链接时额外加入如下的静态库文件和链接选项,释义如下:

    /usr/lib/llvm-14/lib/clang/14.0.0/lib/linux/libclang_rt.asan-x86_64.a -lgcc_s --eh-frame-hdr

    • /usr/lib/llvm-14/lib/clang/14.0.0/lib/linux/libclang_rt.asan-x86_64.a 因为该 .a 文件实现了 __sanitizer_print_stack_trace,出于方便就直接用它;
    • -lgcc_s 栈回溯依赖 gcc_s;
    • --eh-frame-hdr ld 链接时生成 eh_frame_hdr 节,帮助完成栈回溯。

    可选的环境变量:ASAN_SYMBOLIZER_PATH=$CANGJIE_HOME/third_party/llvm/bin/llvm-symbolizer,可能在某些情况下有用。

    最终会得到两套栈回溯,一套是 Exception.printStackTrace,一套是 __sanitizer_print_stack_trace,内容如下:

    [WARNING]: Detect uncatched exception, maybe caused by bugs, exit now
    An exception has occurred:
    Exception: TRAP!
             at default.ttt(std/core::Array<...>)(/data/cangjie/libs/fuzz/ci_fuzzer0.cj:11)
             at _ZN7default3tttER_ZN8std$core5ArrayIhE_cc_wrapper(/data/cangjie/libs/fuzz/ci_fuzzer0.cj:0)
             at libfuzzerCallback(/data/cangjie/libs/fuzz/fuzz/callback.cj:34)
    [INFO]: data is: [0, 202, 0, 0, 0, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255]
    [INFO]: crash file will stored with libfuzzer
    ==425243== ERROR: libFuzzer: fuzz target exited
        #0 0x563a233fadf1 in __sanitizer_print_stack_trace (/data/cangjie/libs/fuzz/main+0x280df1)
        #1 0x563a2337c0b8 in fuzzer::PrintStackTrace() (/data/cangjie/libs/fuzz/main+0x2020b8)
        #2 0x563a2338726c in fuzzer::Fuzzer::ExitCallback() (/data/cangjie/libs/fuzz/main+0x20d26c)
        #3 0x7f485cf36494 in __run_exit_handlers stdlib/exit.c:113:8
        #4 0x7f485cf3660f in exit stdlib/exit.c:143:3
        #5 0x563a23224e68 in libfuzzerCallback$real /data/cangjie/libs/fuzz/fuzz/callback.cj:62:18
        #6 0x7f485d22718b in CJ_MCC_N2CStub (/data/cangjie/output/runtime/lib/linux_x86_64_llvm/libcangjie-runtime.so+0x2718b)
        #7 0x563a2322fc26 in libfuzzerCallback /data/cangjie/libs/fuzz/fuzz/callback.cj:20
        #8 0x563a23387883 in fuzzer::Fuzzer::ExecuteCallback(unsigned char const*, unsigned long) (/data/cangjie/libs/fuzz/main+0x20d883)
        #9 0x563a2338a3f9 in fuzzer::Fuzzer::RunOne(unsigned char const*, unsigned long, bool, fuzzer::InputInfo*, bool, bool*) (/data/cangjie/libs/fuzz/main+0x2103f9)
        #10 0x563a23387e49 in fuzzer::Fuzzer::MutateAndTestOne() (/data/cangjie/libs/fuzz/main+0x20de49)
        #11 0x563a2338a2b5 in fuzzer::Fuzzer::Loop(std::vector<fuzzer::SizedFile, std::allocator<fuzzer::SizedFile>>&) (/data/cangjie/libs/fuzz/main+0x2102b5)
        #12 0x563a23377a12 in fuzzer::FuzzerDriver(int*, char***, int (*)(unsigned char const*, unsigned long)) (/data/cangjie/libs/fuzz/main+0x1fda12)
        #13 0x563a231ad2b6 in fuzz_fake$fuzz::Fuzzer::startFuzz() /data/cangjie/libs/fuzz/fuzz/fuzzer.cj:200:13
        #14 0x563a23405fad in default::main() /data/cangjie/libs/fuzz/ci_fuzzer0.cj:5:5
        #15 0x563a23405fe7 in user.main /data/cangjie/libs/fuzz/<stdin>
        #16 0x563a234060e1 in cj_entry$ (/data/cangjie/libs/fuzz/main+0x28c0e1)
        #17 0x7f485d227220  (/data/cangjie/output/runtime/lib/linux_x86_64_llvm/libcangjie-runtime.so+0x27220)
        #18 0x7f485d223898  (/data/cangjie/output/runtime/lib/linux_x86_64_llvm/libcangjie-runtime.so+0x23898)
        #19 0x7f485d2607b9 in CJ_CJThreadEntry (/data/cangjie/output/runtime/lib/linux_x86_64_llvm/libcangjie-runtime.so+0x607b9)
    

    log 模块

    log 功能介绍

    log 模块提供日志管理和日志打印接口。

    log 模块的包列表

    log 模块提供了如下包:

    包名功能
    loglog 包提供了一个单一的日志API,它抽象了实际的日志实现。

    log 包

    功能介绍

    log 包提供了一个单一的日志API,它抽象了实际的日志实现。

    API 列表

    函数

    函数名功能
    getGlobalLogger(Array<Attr>)获取全局Logger对象。
    setGlobalLogger(Logger)设置全局Logger对象。

    类型别名

    类型别名功能
    Attr日志消息的键值对类型,是 (String, LogValue) 的类型别名。

    接口

    接口名功能
    LogValue为仓颉数据类型提供序列化到日志输出目标的接口。

    类名功能
    Logger此抽象类提供基础的日志打印和管理功能。
    LogRecord日志消息的“负载”。
    LogWriterLogWriter 提供了将仓颉数据类型序列化到日志输出目标的能力。
    NoopLoggerLogger 的 NO-OP(无操作)实现。

    结构体

    结构体名功能
    LogLevelLogLevel 为日志级别结构体。

    异常类

    异常类名功能
    LogException用于处理 log 相关的异常。

    类型别名

    type Attr

    public type Attr = (String, LogValue)
    

    功能:日志消息的键值对类型,是 (String, LogValue) 的类型别名。

    函数

    func getGlobalLogger(Array<Attr>)

    public func getGlobalLogger(attrs: Array<Attr>): Logger
    

    功能:获取 Logger 对象。

    如果未传入 attrs 参数,那么获取的是同一个 Logger 对象,传入了 attrs 参数,则创建一个包含指定的属性的 Logger 对象副本。

    参数:

    • attrs: Array<Attr> - 日志数据键值对属性,获取的 Logger 对象会包含这些属性。

    返回值:

    func setGlobalLogger(Logger)

    public func setGlobalLogger(logger: Logger): Unit
    

    功能:设置全局 Logger 对象。

    注意,这个函数在程序的生命周期中只应该被调用一次。对 setGlobalLogger 的调用完成之前发生的任何日志事件都将被忽略。

    此函数通常不需要手动调用。日志实现提供者应提供包含了调用本方法的的初始化方法。

    参数:

    接口

    interface LogValue

    public interface LogValue {
        func writeTo(w: LogWriter): Unit
    }
    

    功能:为类型提供序列化到日志输出目标的接口。

    LogWriter 搭配使用, LogWriter 可以通过 writeValue 来将实现了 LogValue 接口的类型写入到日志输出目标中。

    func writeTo(LogWriter)

    func writeTo(w: LogWriter): Unit
    

    功能:将实现了 LogValue 接口的类型写入参数 w 指定的 LogWriter 实例中。

    参数:

    extend Bool <: LogValue

    extend Bool <: LogValue
    

    功能:为 Bool 类型实现 LogValue 接口。

    父类型:

    func writeTo(LogWriter)

    public func writeTo(w: LogWriter): Unit
    

    功能:提供 Bool 类型序列化到流的功能。

    参数:

    extend Exception <: LogValue

    extend Exception <: LogValue
    

    功能:为 Exception 类型实现 LogValue 接口。

    父类型:

    func writeTo(LogWriter)

    public func writeTo(w: LogWriter): Unit
    

    功能:提供 Exception 类型序列化到流的功能。

    参数:

    extend Int64 <: LogValue

    extend Int64 <: LogValue
    

    功能:为 Int64 类型实现 LogValue 接口。

    父类型:

    func writeTo(LogWriter)

    public func writeTo(w: LogWriter): Unit
    

    功能:提供 Int64 类型序列化到流的功能。

    参数:

    extend Float64 <: LogValue

    extend Float64 <: LogValue
    

    功能:为 Float64 类型实现 LogValue 接口。

    父类型:

    func writeTo(LogWriter)

    public func writeTo(w: LogWriter): Unit
    

    功能:提供 Float64 类型序列化到流的功能。

    参数:

    extend String <: LogValue

    extend String <: LogValue
    

    功能:为 String 类型实现 LogValue 接口。

    父类型:

    func writeTo(LogWriter)

    public func writeTo(w: LogWriter): Unit
    

    功能:提供 String 类型序列化到流的功能。

    参数:

    extend DateTime <: LogValue

    extend DateTime <: LogValue
    

    功能:为 DateTime 类型实现 LogValue 接口。

    父类型:

    func writeTo(LogWriter)

    public func writeTo(w: LogWriter): Unit
    

    功能:提供 DateTime 类型序列化到流的功能。

    参数:

    extend Duration <: LogValue

    extend Duration <: LogValue
    

    功能:为 Duration 类型实现 LogValue 接口。

    父类型:

    func writeTo(LogWriter)

    public func writeTo(w: LogWriter): Unit
    

    功能:提供 Duration 类型序列化到流的功能。

    参数:

    extend Array <: LogValue

    extend<T> Array<T> <: LogValue where T <: LogValue
    

    功能:为 Array<T> 类型实现 LogValue 接口。

    父类型:

    func writeTo(LogWriter)

    public func writeTo(w: LogWriter): Unit
    

    功能:提供 Array<T> 类型序列化到流的功能。

    参数:

    extend<V> HashMap<String, V> <: LogValue where V <: LogValue

    extend<V> HashMap<String, V> <: LogValue where V <: LogValue
    

    功能:为 HashMap<K, V> 类型实现 LogValue 接口。

    父类型:

    func writeTo(LogWriter)

    public func writeTo(w: LogWriter): Unit
    

    功能:提供 HashMap<K, V> 类型序列化到流的功能。

    参数:

    extend<V> TreeMap<String, V> <: LogValue where V <: LogValue

    extend<V> TreeMap<String, V> <: LogValue where V <: LogValue
    

    功能:为 TreeMap<K, V> 类型实现 LogValue 接口。

    父类型:

    func writeTo(LogWriter)

    public func writeTo(w: LogWriter): Unit
    

    功能:提供 TreeMap<K, V> 类型序列化到流的功能。

    参数:

    extend<T> Option<T> <: LogValue where T <: LogValue

    extend<T> Option<T> <: LogValue where T <: LogValue
    

    功能:为 Option<T> 类型实现 LogValue 接口。

    父类型:

    func writeTo(LogWriter)

    public func writeTo(w: LogWriter): Unit
    

    功能:提供 Option<T> 类型序列化到流的功能。

    参数:

    class Logger

    public abstract class Logger <: Resource {
        public mut open prop level: LogLevel
        public open func withAttrs(attrs: Array<Attr>): Logger
        public open func log(record: LogRecord): Unit
        public func enabled(level: LogLevel): Bool
        public open func log(level: LogLevel, message: String, attrs: Array<Attr>): Unit
        public open func log(level: LogLevel, message: () -> String, attrs: Array<Attr>): Unit
        public func fatal(message: String, attrs: Array<Attr>): Unit
        public func fatal(message: () -> String, attrs: Array<Attr>): Unit
        public func error(message: String, attrs: Array<Attr>): Unit
        public func error(message: () -> String, attrs: Array<Attr>): Unit
        public func warn(message: String, attrs: Array<Attr>): Unit
        public func warn(message: () -> String, attrs: Array<Attr>): Unit
        public func info(message: String, attrs: Array<Attr>): Unit
        public func info(message: () -> String, attrs: Array<Attr>): Unit
        public func debug(message: String, attrs: Array<Attr>): Unit
        public func debug(message: () -> String, attrs: Array<Attr>): Unit
        public func trace(message: String, attrs: Array<Attr>): Unit
        public func trace(message: () -> String, attrs: Array<Attr>): Unit
    }
    

    功能:此抽象类提供基础的日志打印和管理功能。

    父类型:

    prop level

    public mut open prop level: LogLevel
    

    功能:获取和修改日志打印级别。

    类型:LogLevel

    func debug(String, Array<Attr>)

    public func debug(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 DEBUG 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func debug(() -> String, Array<Attr>)

    public func debug(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 DEBUG 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func enabled(LogLevel)

    public func enabled(level: LogLevel): Bool
    

    功能:确定是否记录指定日志级别的日志消息。

    这个函数允许调用者提前判断日志是否会被丢弃,以避免耗时的日志消息参数计算。

    参数:

    返回值:

    • Bool - 如果指定的日志级别处于使能状态,则返回 true;否则,返回 false

    func error(String, Array<Attr>)

    public func error(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 ERROR 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func error(() -> String, Array<Attr>)

    public func error(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 ERROR 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func fatal(String, Array<Attr>)

    public func fatal(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 FATAL 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func fatal(() -> String, Array<Attr>)

    public func fatal(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 FATAL 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func info(String, Array<Attr>)

    public func info(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 INFO 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func info(() -> String, Array<Attr>)

    public func info(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 INFO 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogLevel, String, Array<Attr>)

    public open func log(level: LogLevel, message: String, attrs: Array<Attr>): Unit
    

    功能:打印日志的通用函数,需指定日志级别。

    参数:

    • level: LogLevel - 日志级别。
    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogLevel, () -> String, Array<Attr>)

    public open func log(level: LogLevel, message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印日志的通用函数,需指定日志级别。

    参数:

    • level: LogLevel - 日志级别。
    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogRecord)

    public open func log(record: LogRecord): Unit
    

    功能:打印日志的通用函数。

    参数:

    func trace(String, Array<Attr>)

    public func trace(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 TRACE 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func trace(() -> String, Array<Attr>)

    public func trace(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 TRACE 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func warn(String, Array<Attr>)

    public func warn(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 WARN 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func warn(() -> String, Array<Attr>)

    public func warn(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 WARN 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func withAttrs(Array<Attr>)

    public open func withAttrs(attrs: Array<Attr>): Logger
    

    功能:创建当前对象的副本,新的副本会包含指定的属性。

    参数:

    • attrs: Array<Attr> - 日志数据键值对属性。

    返回值:

    class LogRecord

    public class LogRecord {
        public init(time: DateTime, level: LogLevel, msg: String, attrs: Array<Attr>)
        public prop time: DateTime
        public prop level: LogLevel
        public mut prop message: String
        public mut prop attrs: Array<Attr>
        public func clone(): LogRecord
    }
    

    功能:日志消息的“负载”。

    记录结构作为参数传递给 Logger 类的 log方法。日志提供者处理这些结构以显示日志消息。记录是由日志对象自动创建,因此日志用户看不到。

    init(DateTime, LogLevel, String, Array<Attr>)

    public init(time: DateTime, level: LogLevel, msg: String, attrs: Array<Attr>)
    

    功能:创建一个 LogRecord 实例,指定时间戳,日志打印级别,日志消息和日志数据键值对。

    参数:

    • time: DateTime - 记录日志时的时间戳
    • level: LogLevel - 日志级别。
    • msg: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    prop attrs

    public mut prop attrs: Array<Attr>
    

    功能:获取或设置日志数据键值对。

    类型:Array<Attr>

    prop level

    public prop level: LogLevel
    

    功能:获取日志打印级别,只有级别小于等于该值的日志会被打印。

    类型:LogLevel

    prop message

    public mut prop message: String
    

    功能:获取或设置日志消息。

    类型:String

    prop time

    public prop time: DateTime
    

    功能:获取日志打印时的时间戳。

    类型:DateTime

    func clone()

    public func clone(): LogRecord
    

    功能:创建当前对象的副本。

    返回值:

    class LogWriter

    public abstract class LogWriter {
        public func writeNone(): Unit
        public func writeInt(v: Int64): Unit
        public func writeUInt(v: UInt64): Unit
        public func writeBool(v: Bool): Unit
        public func writeFloat(v: Float64): Unit
        public func writeString(v: String): Unit
        public func writeDateTime(v: DateTime): Unit
        public func writeDuration(v: Duration): Unit
        public func writeKey(v: String): Unit
        public func writeValue(v: LogValue): Unit
        public func startArray(): Unit
        public func endArray(): Unit
        public func startObject(): Unit
        public func endObject(): Unit
    }
    

    功能:LogWriter 提供了将仓颉对象序列化成日志输出目标的能力。

    LogWriter 需要和 interface LogValue 搭配使用,LogWriter 可以通过 writeValue 系列方法来将实现了 LogValue 接口的类型写入到日志输出目标中。

    func endArray()

    public func endArray(): Unit
    

    功能:结束序列化当前的 LogValue 数组。

    异常:

    func endObject()

    public func endObject(): Unit
    

    功能:结束序列化当前的 LogValue object。

    异常:

    func startArray()

    public func startArray(): Unit
    

    功能:开始序列化一个新的 LogValue 数组,每一个 startArray 都必须有一个 endArray 对应。

    异常:

    func startObject()

    public func startObject(): Unit
    

    功能:开始序列化一个新的 LogValue object,每一个 startObject 都必须有一个 endObject 对应。

    异常:

    func writeBool(Bool)

    public func writeBool(v: Bool): Unit
    

    功能:向日志输出目标中写入 Bool 值。

    参数:

    异常:

    func writeFloat(Float64)

    public func writeFloat(v: Float64): Unit
    

    功能:向日志输出目标中写入 Float64 值。

    参数:

    异常:

    func writeDateTime(DateTime)

    public func writeDateTime(v: DateTime): Unit
    

    功能:向日志输出目标中写入 DateTime 值。

    参数:

    异常:

    func writeDuration(Duration)

    public func writeDuration(v: Duration): Unit
    

    功能:向日志输出目标中写入 Duration 值。

    参数:

    异常:

    func writeException(Exception)

    public func writeException(v: Exception): Unit
    

    功能:向日志输出目标中写入 Exception 值。

    参数:

    异常:

    func writeInt(Int64)

    public func writeInt(v: Int64): Unit
    

    功能:向日志输出目标中写入 Int64 值。

    参数:

    异常:

    func writeKey(String)

    public func writeKey(v: String): Unit
    

    功能:向日志输出目标中写入 name。

    参数:

    • v: String - 待写入的 Key 值。

    异常:

    func writeNone()

    public func writeNone(): Unit
    

    功能:向日志输出目标中写入 None,具体写成什么格式由 Logger 的提供者自行决定。

    异常:

    func writeString(String)

    public func writeString(v: String): Unit
    

    功能:向日志输出目标中写入 String 值。

    参数:

    异常:

    func writeValue(LogValue)

    public func writeValue(v: LogValue): Unit
    

    功能:将实现了 LogValue 接口的类型写入到日志输出目标中。该接口会调用 LogValuewriteTo 方法向日志输出目标中写入数据。

    log 包已经为基础类型 Int64Float64BoolString 类型扩展实现了 LogValue,并且为 DateTimeDurationCollection 类型 ArrayHashMapTreeMap 以及 Option<T> 扩展实现了 LogValue

    参数:

    异常:

    class NoopLogger

    public class NoopLogger <: Logger {
        public init()
        public prop level: LogLevel
        public func log(record: LogRecord): Unit
        public func log(level: LogLevel, message: String, attrs: Array<Attr>): Unit
        public func log(level: LogLevel, message: () -> String, attrs: Array<Attr>): Unit
        public func withAttrs(attrs: Array<Attr>): Logger
        public func isClosed(): Bool
        public func close(): Unit
    }
    

    功能:Logger 的 NO-OP(无操作)实现,会丢弃所有的日志。

    父类型:

    init()

    public init()
    

    功能:创建一个 NoopLogger 实例。

    prop level

    public mut prop level: LogLevel
    

    功能:永远只能获取到 OFF 日志打印级别,设置日志打印级别不会生效。

    类型:LogLevel

    func close()

    public func close(): Unit
    

    功能:NOOP 实现。

    func isClosed()

    public func isClosed(): Bool
    

    功能:NOOP 实现。

    返回值:

    func log(LogLevel, String, Array<Attr>)

    public func log(level: LogLevel, message: String, attrs: Array<Attr>): Unit
    

    功能:NOOP 实现。

    参数:

    • level: LogLevel - 日志级别。
    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogLevel, () -> String, Array<Attr>)

    public func log(level: LogLevel, message: () -> String, attrs: Array<Attr>): Unit
    

    功能:NOOP 实现。

    参数:

    • level: LogLevel - 日志级别。
    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogRecord)

    public func log(record: LogRecord): Unit
    

    功能:NOOP 实现。

    参数:

    func withAttrs(Array<Attr>)

    public func withAttrs(attrs: Array<Attr>): Logger
    

    功能:NOOP 实现。

    参数:

    • attrs: Array<Attr> - 日志数据键值对。

    结构体

    struct LogLevel

    public struct LogLevel <: ToString & Comparable<LogLevel>
    

    功能:LogLevel 为日志级别结构体。

    定义了日志打印的七个级别,级别从低到高分别为 OFFFATALERRORWARNINFODEBUGTRACEALL

    我们期望只有级别小于等于指定打印级别的日志条目会被打印到输出流中。

    父类型:

    let name: String

    public let name: String
    

    功能:日志级别名。

    let value: Int32

    public let value: Int32
    

    功能:日志级别值。

    init(String, Int32)

    public const init(name: String, value: Int32)
    

    功能:常量构造函数,创建 LogLevel 对象。

    参数:

    • name: String - 日志级别名。
    • value: Int32 - 日志级别值。

    static const ALL

    public static const ALL = LogLevel("ALL", -0x8000_0000)
    

    功能:获取一个日志打印级别的静态常量实例,等级为所有。

    static const DEBUG

    public static const DEBUG = LogLevel("DEBUG", 2000)
    

    功能:获取一个日志打印级别的静态常量实例,等级为调试。

    static const ERROR

    public static const ERROR = LogLevel("ERROR", 5000)
    

    功能:获取一个日志打印级别的静态常量实例,等级为错误。

    static const FATAL

    public static const FATAL = LogLevel("FATAL", 6000)
    

    功能:获取一个日志打印级别的静态常量实例,等级为严重错误。

    static const INFO

    public static const INFO = LogLevel("INFO", 3000)
    

    功能:获取一个日志打印级别的静态常量实例,等级为通知。

    static const OFF

    public static const OFF = LogLevel("OFF", 0x7FFF_FFFF)
    

    功能:获取一个日志打印级别的静态常量实例,等级为禁用。

    static const TRACE

    public static const TRACE = LogLevel("TRACE", 1000)
    

    功能:获取一个日志打印级别的静态常量实例,等级为跟踪。

    static const WARN

    public static const WARN = LogLevel("WARN", 4000)
    

    功能:获取一个日志打印级别的静态常量实例,等级为警告。

    func compare(LogLevel)

    public func compare(rhs: LogLevel): Ordering
    

    功能:判断当前 LogLevel 类型实例与参数指向的 LogLevel 类型实例的大小关系。

    参数:

    • that: LogLevel - 待与当前实例比较的另一个实例。

    返回值:

    func toString()

    public func toString(): String
    

    功能:获取日志级别对应的名称。

    返回值:

    • String - 当前的日志级别的名称。

    operator func ==(LogLevel)

    public operator func ==(rhs: LogLevel): Bool
    

    功能:比较日志级别高低。

    参数:

    • rhs: LogLevel - 将当前日志级别和 target 进行比较。

    返回值:

    • Bool - 如果当前日志级别等于 target,返回 true,否则返回 false

    operator func !=(LogLevel)

    public operator func !=(rhs: LogLevel): Bool
    

    功能:比较日志级别高低。

    参数:

    • rhs: LogLevel - 将当前日志级别和 target 进行比较。

    返回值:

    • Bool - 如果当前日志级别不等于 target,返回 true,否则返回 false

    operator func >=(LogLevel)

    public operator func >=(rhs: LogLevel): Bool
    

    功能:比较日志级别高低。

    参数:

    • rhs: LogLevel - 将当前日志级别和 target 进行比较。

    返回值:

    • Bool - 如果当前日志级别大于等于 target,返回 true,否则返回 false

    operator func <=(LogLevel)

    public operator func <=(rhs: LogLevel): Bool
    

    功能:比较日志级别高低。

    参数:

    • rhs: LogLevel - 将当前日志级别和 target 进行比较。

    返回值:

    • Bool - 如果当前日志级别小于等于 target,返回 true,否则返回 false

    operator func >(LogLevel)

    public operator func >(rhs: LogLevel): Bool
    

    功能:比较日志级别高低。

    参数:

    • rhs: LogLevel - 将当前日志级别和 target 进行比较。

    返回值:

    • Bool - 如果当前日志级别大于 target,返回 true,否则返回 false

    operator func <(LogLevel)

    public operator func <(rhs: LogLevel): Bool
    

    功能:比较日志级别高低。

    参数:

    • rhs: LogLevel - 将当前日志级别和 target 进行比较。

    返回值:

    • Bool - 如果当前日志级别小于 target,返回 true,否则返回 false

    异常类

    class LogException

    public open class LogException <: Exception
    

    功能:用于处理 log 相关的异常。

    父类型:

    init()

    public init()
    

    功能:无参构造函数。

    init(String)

    public init(message: String)
    

    功能:根据异常信息创建 LogException 实例。

    参数:

    • message: String - 异常信息。

    日志打印示例

    库开发场景记录日志

    下面是开发仓颉库时,打印日志的示例。

    代码如下:

    import log.*
    
    public class PGConnection {
        let objId: Int64 = 1
        let logger = getGlobalLogger(("name", "PGConnection"))
    
        public func close(): Unit {
            logger.trace("driver conn closed", ("id", objId))
        }
    }
    

    运行结果如下:

    2021/08/05 08:20:42.696645 TRACE msg="driver conn closed" id=1 name="PGConnection"
    

    应用程序开发场景日志打印

    下面是 自定义 PasswordFilter 和 TextLogger 日志打印示例。

    代码如下:

    import std.time.*
    import std.io.{OutputStream, ByteBuffer, BufferedOutputStream}
    import std.console.Console
    import std.fs.*
    import std.collection.{ArrayList, Map, HashMap}
    import std.collection.concurrent.NonBlockingQueue
    import std.sync.AtomicBool
    import std.time.DateTime
    import log.{LogValue, LogWriter, Logger, Attr, LogRecord, LogLevel}
    import log
    
    
    public class PasswordFilter <: Logger {
        var _level = LogLevel.INFO
        let processor: Logger
        public init(logger: Logger) {
            processor = logger
        }
        public mut prop level: LogLevel {
            get() {
                _level
            }
            set(v) {
                _level = v
            }
        }
        public func withAttrs(attrs: Array<Attr>): Logger {
            this
        }
        // log
        public func log(level: LogLevel, message: String, attrs: Array<Attr>): Unit {
            let record: LogRecord = LogRecord(DateTime.now(), level, message, attrs)
            log(record)
        }
        // lazy
        public func log(level: LogLevel, message: () -> String, attrs: Array<Attr>): Unit {
            let record: LogRecord = LogRecord(DateTime.now(), level, message(), attrs)
            log(record)
        }
        // 根据键值对的名字过滤,将密码值换成 "***"
        public func log(record: LogRecord): Unit {
            var attrs = record.attrs.clone()
            for (i in 0..attrs.size) {
                var attr = attrs[i]
                if (attr[0] == "password") {
                    attrs[i] = (attr[0], "***")
                }
            }
            let r = LogRecord(record.time, record.level, record.message, attrs)
            processor.log(r)
        }
        public func isClosed(): Bool {
            false
        }
        public func close(): Unit {
        }
    }
    
    main() {
        let o = ByteBuffer()
        let tl = TextLogger(Console.stdOut)
        tl.level = LogLevel.TRACE
        let l = PasswordFilter(tl)
        log.setGlobalLogger(l)
        let logger = log.getGlobalLogger([("name", "main")])
        let user = User()
        // 普通记录信息日志
        logger.info("Hello, World!", ("k1", [[1, 4], [2, 5], [3]]), ("password", "v22222"))
        // 记录诊断日志,如果 DEBUG 级别未开启,直接返回,几乎无cost
        logger.debug("Logging in user ${user.name} with birthday ${user.birthdayCalendar}")
    
        // lazy 方式记录耗时日志数据
        logger.log(LogLevel.ERROR, "long-running operation msg", ("k1", 100), ("k2", user.birthdayCalendar),
            ("oper", ToStringWrapper({=> "Some long-running operation returned"})))
    
        logger.log(LogLevel.ERROR, "long-running operation msg", ("sourcePackage", @sourcePackage()),
            ("sourceFile", @sourceFile()), ("sourceLine", @sourceLine()), ("birthdayCalendar", user.birthdayCalendar),
            ("oper", ToStringWrapper({=> "Some long-running operation returned"})))
    
        let m = HashMap<String, String>()
        m.put("k1", "1")
        m.put("k2", "2")
        m.put("k3", "3")
        logger.trace({=> "Some long-running operation returned"}, ("k1", m))
        let m2 = HashMap<String, LogValue>()
        m2.put("g1", m)
    
        // 如果TRACE 级别没有开启,那么lambda表达式不会被执行
        logger.trace({=> "Some long-running operation returned"}, ("k2", m2))
    
        // Console.stdOut.write(o.bytes())
        // Console.stdOut.flush()
    }
    
    public class User {
        public prop name: String {
            get() {
                "foo"
            }
        }
        public prop birthdayCalendar: DateTime {
            get() {
                DateTime.now()
            }
        }
    }
    
    public class ToStringWrapper <: ToString & LogValue {
        let _fn: () -> String
        public init(fn: () -> String) {
            _fn = fn
        }
        public func toString(): String {
            return _fn()
        }
        public func writeTo(w: LogWriter): Unit {
            w.writeValue(_fn())
        }
    }
    
    func expensiveOperation(): String {
        for (_ in 0..1000000) {
            unsafe {
                let b = LibC.malloc<Byte>(count: 1000)
                LibC.free(b)
            }
        }
        "Some long-running operation returned"
    }
    
    public class TextLogger <: Logger {
        let w: TextLogWriter
        let opts = HashMap<String, String>()
        let _closed = AtomicBool(false)
        let queue = NonBlockingQueue<LogRecord>()
        let bo: BufferedOutputStream<OutputStream>
        let _attrs = ArrayList<Attr>()
        var _level = LogLevel.INFO
        public init(output: OutputStream) {
            bo = BufferedOutputStream<OutputStream>(output)
            w = TextLogWriter(bo)
        }
    
        public mut prop level: LogLevel {
            get() {
                _level
            }
            set(v) {
                _level = v
            }
        }
        public func withAttrs(attrs: Array<Attr>): Logger {
            if (attrs.size > 0) {
                let nl = TextLogger(w.out)
                nl._attrs.appendAll(attrs)
                return nl
            }
            return this
        }
        // log
        public func log(level: LogLevel, message: String, attrs: Array<Attr>): Unit {
            if (this.enabled(level)) {
                let record: LogRecord = LogRecord(DateTime.now(), level, message, attrs)
                log(record)
            }
        }
        // lazy
        public func log(level: LogLevel, message: () -> String, attrs: Array<Attr>): Unit {
            if (this.enabled(level)) {
                let record: LogRecord = LogRecord(DateTime.now(), level, message(), attrs)
                log(record)
            }
        }
        public func log(record: LogRecord): Unit {
            // write time
            w.writeKey("time")
            w.writeValue(record.time)
            w.writeString(" ")
            // write level
            w.writeKey("level")
            w.writeString(record.level.toString())
            w.writeString(" ")
            // write message
            w.writeKey("msg")
            w.writeValue(record.message)
            w.writeString(" ")
            // write source
    
            // write attrs
            for (i in 0..record.attrs.size) {
                let attr = record.attrs[i]
                w.writeKey(attr[0])
                w.writeValue(attr[1])
                if (i < record.attrs.size - 1) {
                    w.writeString(" ")
                }
            }
            w.writeString("\n")
            bo.flush()
        }
        public func isClosed(): Bool {
            _closed.load()
        }
        public func close(): Unit {
            if (isClosed()) {
                return
            }
            _closed.store(true)
        }
    }
    
    class TextLogWriter <: LogWriter {
        var out: OutputStream
        init(out: OutputStream) {
            this.out = out
        }
        public func writeNone(): Unit {
            out.write("None".toArray())
        }
        public func writeInt(v: Int64): Unit {
            out.write(v.toString().toArray())
        }
        public func writeUInt(v: UInt64): Unit {
            out.write(v.toString().toArray())
        }
        public func writeBool(v: Bool): Unit {
            out.write(v.toString().toArray())
        }
        public func writeFloat(v: Float64): Unit {
            out.write(v.toString().toArray())
        }
        public func writeString(v: String): Unit {
            out.write(v.toArray())
        }
        public func writeDateTime(v: DateTime): Unit {
            out.write(v.toString().toArray())
        }
        public func writeDuration(v: Duration): Unit {
            out.write(v.toString().toArray())
        }
        public func writeException(v: Exception): Unit {
            out.write(v.toString().toArray())
        }
        public func writeKey(v: String): Unit {
            out.write(v.toString().toArray())
            out.write("=".toArray())
        }
        public func writeValue(v: LogValue): Unit {
            match (v) {
                case vv: String =>
                    out.write("\"".toArray())
                    out.write(vv.toArray())
                    out.write("\"".toArray())
                case vv: ToString =>
                    out.write("\"".toArray())
                    out.write(vv.toString().toArray())
                    out.write("\"".toArray())
                case _ =>
                    out.write("\"".toArray())
                    v.writeTo(this)
                    out.write("\"".toArray())
            }
        }
        public func startArray(): Unit {
            out.write("[".toArray())
        }
        public func endArray(): Unit {
            out.write("]".toArray())
        }
        public func startObject(): Unit {
            out.write("{".toArray())
        }
        public func endObject(): Unit {
            out.write("}".toArray())
        }
    }
    
    

    运行结果如下:

    time="2024-06-17T14:10:07.1861349Z" level=INFO msg="Hello, World!" k1="[[1, 4], [2, 5], [3]]" password="***"
    time="2024-06-17T14:10:07.1864929Z" level=DEBUG msg="Logging in user foo with birthday 2024-06-17T14:10:07.1864802Z"
    time="2024-06-17T14:10:07.1869579Z" level=ERROR msg="long-running operation msg" k1="100" k2="2024-06-17T14:10:07.186957Z" oper="Some long-running operation returned"
    time="2024-06-17T14:10:07.18742Z" level=ERROR msg="long-running operation msg" sourcePackage="log" sourceFile="main.cj" sourceLine="77" birthdayCalendar="2024-06-17T14:10:07.1874188Z" oper="Some long-running operation returned"
    time="2024-06-17T14:10:07.1879195Z" level=TRACE msg="Some long-running operation returned" k1="[(k1, 1), (k2, 2), (k3, 3)]"
    time="2024-06-17T14:10:07.1881599Z" level=TRACE msg="Some long-running operation returned" k2="{g1="[(k1, 1), (k2, 2), (k3, 3)]"}"
    

    logger 模块概述

    logger 功能介绍

    logger 模块提供文本格式和 JSON 格式日志打印功能。

    logger 模块的包列表

    logger 模块提供了如下包:

    包名功能
    loggerlogger 包提供文本格式和 JSON 格式日志打印功能。

    logger 包

    功能介绍

    logger 包提供文本格式和 JSON 格式日志打印功能。

    API 列表

    类名功能
    JsonLogger输出 JSON 格式的 Logger 类实现。
    SimpleLogger输出传统文本格式的 Logger 类实现。
    TextLogger输出文本 KV 格式的 Logger 类实现。

    class JsonLogger

    public class JsonLogger <: Logger {
        public init(output: OutputStream)
    }
    

    功能:此类实现了输出 JSON 格式的日志打印功能,形如 {"time":"2024-07-27T11:51:59+08:00","level":"INFO","msg":"foo","name":"bar"}

    父类型:

    init(OutputStream)

    public init(output: OutputStream)
    

    功能:创建 JsonLogger 对象。

    参数:

    • output: OutputStream - 绑定的输出流,日志格式化后将写入该输出流。

    prop level

    public open mut prop level: LogLevel
    

    功能:获取和修改日志打印级别。

    类型:LogLevel

    func debug(String, Array<Attr>)

    public func debug(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 DEBUG 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func debug(() -> String, Array<Attr>)

    public func debug(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 DEBUG 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func enabled(LogLevel)

    public func enabled(level: LogLevel): Bool
    

    功能:确定是否记录指定日志级别的日志消息。

    这个函数允许调用者提前判断日志是否会被丢弃,以避免耗时的日志消息参数计算。

    参数:

    返回值:

    • Bool - 如果指定的日志级别处于使能状态,则返回 true;否则,返回 false

    func error(String, Array<Attr>)

    public func error(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 ERROR 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func error(() -> String, Array<Attr>)

    public func error(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 ERROR 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func fatal(String, Array<Attr>)

    public func fatal(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 FATAL 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func fatal(() -> String, Array<Attr>)

    public func fatal(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 FATAL 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func info(String, Array<Attr>)

    public func info(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 INFO 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func info(() -> String, Array<Attr>)

    public func info(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 INFO 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogLevel, String, Array<Attr>)

    public open func log(level: LogLevel, message: String, attrs: Array<Attr>): Unit
    

    功能:打印日志的通用函数,需指定日志级别。

    参数:

    • level: LogLevel - 日志级别。
    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogLevel, () -> String, Array<Attr>)

    public open func log(level: LogLevel, message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印日志的通用函数,需指定日志级别。

    参数:

    • level: LogLevel - 日志级别。
    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogRecord)

    public open func log(record: LogRecord): Unit
    

    功能:打印日志的通用函数。

    参数:

    func trace(String, Array<Attr>)

    public func trace(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 TRACE 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func trace(() -> String, Array<Attr>)

    public func trace(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 TRACE 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func warn(String, Array<Attr>)

    public func warn(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 WARN 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func warn(() -> String, Array<Attr>)

    public func warn(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 WARN 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func withAttrs(Array<Attr>)

    public open func withAttrs(attrs: Array<Attr>): Logger
    

    功能:创建当前对象的副本,新的副本会包含指定的属性。

    参数:

    • attrs: Array<Attr> - 日志数据键值对属性。

    返回值:

    class SimpleLogger

    public class SimpleLogger <: Logger {
        public init(output: OutputStream)
    }
    

    功能:此类实现了输出文本格式的日志打印功能,形如 2024-07-27T11:50:47.6616733+08:00 INFO foo name="bar"

    父类型:

    init(OutputStream)

    public init(output: OutputStream)
    

    功能:创建 SimpleLogger 对象。

    参数:

    • output: OutputStream - 绑定的输出流,日志格式化后将写入该输出流。

    prop level

    public open mut prop level: LogLevel
    

    功能:获取和修改日志打印级别。

    类型:LogLevel

    func debug(String, Array<Attr>)

    public func debug(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 DEBUG 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func debug(() -> String, Array<Attr>)

    public func debug(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 DEBUG 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func enabled(LogLevel)

    public func enabled(level: LogLevel): Bool
    

    功能:确定是否记录指定日志级别的日志消息。

    这个函数允许调用者提前判断日志是否会被丢弃,以避免耗时的日志消息参数计算。

    参数:

    返回值:

    • Bool - 如果指定的日志级别处于使能状态,则返回 true;否则,返回 false

    func error(String, Array<Attr>)

    public func error(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 ERROR 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func error(() -> String, Array<Attr>)

    public func error(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 ERROR 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func fatal(String, Array<Attr>)

    public func fatal(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 FATAL 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func fatal(() -> String, Array<Attr>)

    public func fatal(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 FATAL 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func info(String, Array<Attr>)

    public func info(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 INFO 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func info(() -> String, Array<Attr>)

    public func info(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 INFO 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogLevel, String, Array<Attr>)

    public open func log(level: LogLevel, message: String, attrs: Array<Attr>): Unit
    

    功能:打印日志的通用函数,需指定日志级别。

    参数:

    • level: LogLevel - 日志级别。
    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogLevel, () -> String, Array<Attr>)

    public open func log(level: LogLevel, message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印日志的通用函数,需指定日志级别。

    参数:

    • level: LogLevel - 日志级别。
    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogRecord)

    public open func log(record: LogRecord): Unit
    

    功能:打印日志的通用函数。

    参数:

    func trace(String, Array<Attr>)

    public func trace(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 TRACE 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func trace(() -> String, Array<Attr>)

    public func trace(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 TRACE 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func warn(String, Array<Attr>)

    public func warn(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 WARN 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func warn(() -> String, Array<Attr>)

    public func warn(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 WARN 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func withAttrs(Array<Attr>)

    public open func withAttrs(attrs: Array<Attr>): Logger
    

    功能:创建当前对象的副本,新的副本会包含指定的属性。

    参数:

    • attrs: Array<Attr> - 日志数据键值对属性。

    返回值:

    class TextLogger

    public class TextLogger <: Logger {
        public init(output: OutputStream)
    }
    

    功能:此类实现了输出文本格式的日志打印功能,形如 time=2024-07-27T11:52:40.3226881+08:00 level="INFO" msg="foo" name="bar"

    父类型:

    init(OutputStream)

    public init(output: OutputStream)
    

    功能:创建 TextLogger 对象。

    参数:

    • output: OutputStream - 绑定的输出流,日志格式化后将写入该输出流。

    prop level

    public open mut prop level: LogLevel
    

    功能:获取和修改日志打印级别。

    类型:LogLevel

    func debug(String, Array<Attr>)

    public func debug(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 DEBUG 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func debug(() -> String, Array<Attr>)

    public func debug(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 DEBUG 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func enabled(LogLevel)

    public func enabled(level: LogLevel): Bool
    

    功能:确定是否记录指定日志级别的日志消息。

    这个函数允许调用者提前判断日志是否会被丢弃,以避免耗时的日志消息参数计算。

    参数:

    返回值:

    • Bool - 如果指定的日志级别处于使能状态,则返回 true;否则,返回 false

    func error(String, Array<Attr>)

    public func error(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 ERROR 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func error(() -> String, Array<Attr>)

    public func error(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 ERROR 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func fatal(String, Array<Attr>)

    public func fatal(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 FATAL 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func fatal(() -> String, Array<Attr>)

    public func fatal(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 FATAL 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func info(String, Array<Attr>)

    public func info(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 INFO 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func info(() -> String, Array<Attr>)

    public func info(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 INFO 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogLevel, String, Array<Attr>)

    public open func log(level: LogLevel, message: String, attrs: Array<Attr>): Unit
    

    功能:打印日志的通用函数,需指定日志级别。

    参数:

    • level: LogLevel - 日志级别。
    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogLevel, () -> String, Array<Attr>)

    public open func log(level: LogLevel, message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印日志的通用函数,需指定日志级别。

    参数:

    • level: LogLevel - 日志级别。
    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func log(LogRecord)

    public open func log(record: LogRecord): Unit
    

    功能:打印日志的通用函数。

    参数:

    func trace(String, Array<Attr>)

    public func trace(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 TRACE 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func trace(() -> String, Array<Attr>)

    public func trace(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 TRACE 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func warn(String, Array<Attr>)

    public func warn(message: String, attrs: Array<Attr>): Unit
    

    功能:打印 WARN 级别的日志的便捷函数。

    参数:

    • message: String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func warn(() -> String, Array<Attr>)

    public func warn(message: () -> String, attrs: Array<Attr>): Unit
    

    功能:打印 WARN 级别的日志的便捷函数。

    参数:

    • message: () -> String - 日志消息。
    • attrs: Array<Attr> - 日志数据键值对。

    func withAttrs(Array<Attr>)

    public open func withAttrs(attrs: Array<Attr>): Logger
    

    功能:创建当前对象的副本,新的副本会包含指定的属性。

    参数:

    • attrs: Array<Attr> - 日志数据键值对属性。

    返回值:

    日志打印示例

    下面是使用 JsonLogger 日志打印示例代码:

    import std.time.*
    import std.io.{OutputStream, ByteBuffer, BufferedOutputStream}
    import std.console.Console
    import std.fs.*
    import std.collection.{HashMap, ArrayList}
    import encoding.json.stream.*
    import log.*
    import logger.*
    
    main() {
        let o = ByteBuffer()
        let bo = BufferedOutputStream<OutputStream>(Console.stdOut)
        let tl = JsonLogger(bo)
        tl.level = LogLevel.TRACE
        setGlobalLogger(tl)
        let logger = getGlobalLogger([("name", "main")])
        let futs = ArrayList<Future<Unit>>()
    
        // let f = File("log/a.log", OpenOption.CreateOrAppend)
        // let h = TextHandler(f)
        for (_ in 0..1) {
            let f = spawn {
                =>
                logger.info("abc", ("age", 2))
                let user = User()
                // 记录诊断日志,如果 DEBUG 级别未开启,直接返回,几乎无cost
                logger.debug("Logging in user ${user.name} with birthday ${user.birthdayCalendar}")
                // 普通记录信息日志
                logger.info("Hello, World!", ("k1", [[1, 4], [2, 5], [3]]), ("password", "v22222"))
    
                // lazy 方式记录耗时日志数据
                logger.log(LogLevel.ERROR, "long-running operation msg", ("k1", 100), ("k2", user.birthdayCalendar),
                    ("oper", ToStringWrapper({=> "Some long-running operation returned"})))
    
                logger.log(LogLevel.ERROR, "long-running operation msg", ("sourcePackage", @sourcePackage()),
                    ("sourceFile", @sourceFile()), ("sourceLine", @sourceLine()), ("birthdayCalendar", user.birthdayCalendar),
                    ("oper", ToStringWrapper({=> "Some long-running operation returned"})))
    
                let m = HashMap<String, String>()
                m.put("k1", "1\n")
                m.put("k2", "2")
                m.put("k3", "3")
                logger.trace({=> "Some long-running operation returned"}, ("m1", m))
                let m2 = HashMap<String, LogValue>()
                m2.put("g1", m)
                m2.put("k1", [["1", "4 s"], ["2", "5"], ["3"]])
    
                // 如果TRACE 级别没有开启,那么lambda表达式不会被执行
                logger.trace({=> "Some long-running operation returned"}, ("m2", m2))
            }
            futs.append(f)
        }
    
        for (f in futs) {
            f.get()
        }
    
        logger.close()
    }
    
    public class User {
        public prop name: String {
            get() {
                "foo"
            }
        }
        public prop birthdayCalendar: DateTime {
            get() {
                DateTime.now()
            }
        }
    }
    
    public class ToStringWrapper <: ToString & LogValue {
        let _fn: () -> String
        public init(fn: () -> String) {
            _fn = fn
        }
        public func toString(): String {
            return _fn()
        }
        public func writeTo(w: LogWriter): Unit {
            w.writeValue(_fn())
        }
    }
    
    func expensiveOperation(): String {
        for (_ in 0..1000000) {
            unsafe {
                let b = LibC.malloc<Byte>(count: 1000)
                LibC.free(b)
            }
        }
        "Some long-running operation returned"
    }
    
    

    运行结果如下:

    {"time":"2024-07-18T07:57:45Z","level":"INFO","msg":"abc","name":"main","age":2}
    {"time":"2024-07-18T07:57:45Z","level":"DEBUG","msg":"Logging in user foo with birthday 2024-07-18T07:57:45.9912185Z","name":"main"}
    {"time":"2024-07-18T07:57:45Z","level":"INFO","msg":"Hello, World!","name":"main","k1":[[1,4],[2,5],[3]],"password":"v22222"}
    {"time":"2024-07-18T07:57:45Z","level":"ERROR","msg":"long-running operation msg","name":"main","k1":100,"k2":"2024-07-18T07:57:45Z","oper":"Some long-running operation returned"}
    {"time":"2024-07-18T07:57:45Z","level":"ERROR","msg":"long-running operation msg","name":"main","sourcePackage":"mylog","sourceFile":"main.cj","sourceLine":52,"birthdayCalendar":"2024-07-18T07:57:45Z","oper":"Some long-running operation returned"}
    {"time":"2024-07-18T07:57:45Z","level":"TRACE","msg":"Some long-running operation returned","name":"main","m1":{"k1":"1\n","k2":"2","k3":"3"}}
    {"time":"2024-07-18T07:57:45Z","level":"TRACE","msg":"Some long-running operation returned","name":"main","m2":{"g1":{"k1":"1\n","k2":"2","k3":"3"},"k1":[["1","4 s"],["2","5"],["3"]]}}
    

    net 模块

    net 功能介绍

    net 模块提供了网络通信相关的能力。

    在 http 应用层,支持基于 http 相关协议的 http/1.1,http/2,websocket 客户端和服务端的开发。

    在 tls 传输层,支持基于 TLS 1.2 和 TLS 1.3 协议的加密网络通信。

    net 模块的包列表

    net 模块提供了如下包:

    包名功能
    httphttp 包提供 HTTP/1.1,HTTP/2,WebSocket 协议的 server、client 端实现。
    tlstls 包用于进行安全加密的网络通信,提供创建 TLS 服务器、基于协议进行 TLS 握手、收发加密数据、恢复 TLS 会话等能力。

    net.http 包

    功能介绍

    http 包提供 HTTP/1.1、HTTP/2 和 WebSocket 协议的 server、client 端实现。

    关于协议的详细内容可参考 RFC 91109112911392187541 等。

    使用本包需要外部依赖 OpenSSL 3sslcrypto 动态库文件,故使用前需安装相关工具:

    • 对于 Linux 操作系统,可参考以下方式:
      • 如果系统的包管理工具支持安装 OpenSSL 3 开发工具包,可通过这个方式安装,并确保系统安装目录下含有 libssl.solibssl.so.3libcrypto.solibcrypto.so.3 这些动态库文件,例如 Ubuntu 22.04 系统上可使用 sudo apt install libssl-dev 命令安装 libssl-dev 工具包;
      • 如果无法通过上面的方式安装,可自行下载 OpenSSL 3.x.x 源码编译安装软件包,并确保安装目录下含有 libssl.solibssl.so.3libcrypto.solibcrypto.so.3 这些动态库文件,然后可选择下面任意一种方式来保证系统链接器可以找到这些文件:
        • 在系统未安装 OpenSSL 的场景,安装时选择直接安装到系统路径下;
        • 安装在自定义目录的场景,将这些文件所在目录设置到环境变量 LD_LIBRARY_PATH 以及 LIBRARY_PATH 中。
    • 对于 Windows 操作系统,可按照以下步骤:
      • 自行下载 OpenSSL 3.x.x 源码编译安装 x64 架构软件包或者自行下载安装第三方预编译的供开发人员使用的 OpenSSL 3.x.x 软件包;
      • 确保安装目录下含有 libssl.dll.a(或 libssl.lib)、libssl-3-x64.dlllibcrypto.dll.a(或 libcrypto.lib)、libcrypto-3-x64.dll 这些库文件;
      • libssl.dll.a(或 libssl.lib)、libcrypto.dll.a(或 libcrypto.lib) 所在的目录路径设置到环境变量 LIBRARY_PATH 中,将 libssl-3-x64.dlllibcrypto-3-x64.dll 所在的目录路径设置到环境变量 PATH 中。
    • 对于 macOS 操作系统,可参考以下方式:
      • 使用 brew install openssl@3 安装,并确保系统安装目录下含有 libcrypto.dyliblibcrypto.3.dylib 这两个动态库文件;
      • 如果无法通过上面的方式安装,可自行下载 OpenSSL 3.x.x 源码编译安装软件包,并确保安装目录下含有 libcrypto.dyliblibcrypto.3.dylib 这两个动态库文件,然后可选择下面任意一种方式来保证系统链接器可以找到这些文件:
        • 在系统未安装 OpenSSL 的场景,安装时选择直接安装到系统路径下;
        • 安装在自定义目录的场景,将这些文件所在目录设置到环境变量 DYLD_LIBRARY_PATH 以及 LIBRARY_PATH 中。

    如果未安装 OpenSSL 3软件包或者安装低版本的软件包,程序可能无法使用并抛出 TLS 相关异常。

    http

    用户可以选择 http 协议的版本,如 HTTP/1.1、HTTP/2。http 包的多数 API 并不区分这两种协议版本,只有当用户用到某个版本的特有功能时,才需要做这种区分,如 HTTP/1.1 中的 chunked 的 transfer-encoding,HTTP/2 中的 server push。

    http 库默认使用 HTTP/1.1 版本。当开发者需要使用 HTTP/2 协议时,需要为 Client/Server 配置 tls,并且设置 alpn 的值为 h2;不支持 HTTP/1.1 通过 Upgrade: h2c 协议升级的方式升级到 HTTP/2。

    如果创建 HTTP/2 连接握手失败,Client/Server 会自动将协议退回 HTTP/1.1。

    • 用户通过 ClientBuilder 构建一个 Client 实例,构建过程可以指定多个参数,如 httpProxy、logger、cookieJar、是否自动 redirect、连接池大小等。

    • 用户通过 ServerBuilder 构建一个 Server 实例,构建过程可以指定多个参数,如 addr、port、logger、distributor 等。

    用户如果需要自己设置 Logger,需要保证它是线程安全的。

    Client、Server 的大多数参数在构建后便不允许修改,如果想要更改,用户需要重新构建一个新的 Client 或 Server 实例;如果该参数支持动态修改,本实现会提供显式的功能,如 Server 端 cert、CA 的热更新。

    • 通过 Client 实例,用户可以发送 http request、接收 http response。

    • 通过 Server 实例,用户可以配置 request 转发处理器,启动 http server。在 server handler 中,用户可以通过 HttpContext 获取 client 发来的 request 的详细信息,构造发送给 client 的 response。 Server 端根据 Client 端请求,创建对应的 ProtocolService 实例,同一个 Server 实例可同时支持两种协议:HTTP/1.1、HTTP/2。

    • 在 client 端,用户通过 HttpRequestBuilder 构造 request,构建过程可以指定多个参数,如 method、url、version、headers、body、trailers 等等;构建之后的request 不允许再进行修改。

    • 在 server 端,用户通过 HttpResponseBuilder 构造 response,构建过程可以指定多个参数,如 status、headers、body、trailers 等等;构建之后的 response 不允许再进行修改。

    另外,本实现提供一些工具类,方便用户构造一些常用 response,如 RedirectHandler 构造 redirect response,NotFoundHandler 构造 404 response。

    WebSocket

    本实现为 WebSocket 提供 sub-protocol 协商,包括基础的 frame 解码、读取、消息发送、frame 编码、ping、pong、关闭等功能。

    用户通过 WebSocket.upgradeFromClient 从一个 HTTP/1.1 或 HTTP/2 Client 实例升级到 WebSocket 协议,之后通过返回的 WebSocket 实例进行 WebSocket 通讯。

    用户在一个 server 端的 handler 中,通过 WebSocket.upgradeFromServer 从 HTTP/1.1 或 HTTP/2 协议升级到 WebSocket 协议,之后通过返回的 WebSocket 实例进行 WebSocket 通讯。

    按照协议,HTTP/1.1 中,升级后的 WebSocket 连接是建立在 tcp/tls 连接之上;HTTP/2 中,升级后的 WebSocket 连接是建立在 HTTP/2 connection 的一个 stream 之上。HTTP/1.1 中,close 最终会直接关闭 tcp/tls 连接;HTTP/2 中,close 只会关闭 connection 上的一个 stream。

    API 列表

    函数

    函数名功能
    handleError(HttpContext, UInt16)便捷的 Http 请求处理函数,用于回复错误请求。
    notFound(HttpContext)便捷的 Http 请求处理函数,用于回复 404 响应。
    upgrade(HttpContext)在 handler 内获取 StreamingSocket,可用于支持协议升级和处理 CONNECT 请求。

    接口

    接口名功能
    CookieJarClient 用来管理 Cookie 的工具。
    HttpRequestDistributorHttp request 分发器接口,将一个 request 按照 url 中的 path 分发给对应的 HttpRequestHandler 处理。
    HttpRequestHandlerHttp request 处理器。
    ProtocolServiceFactoryHttp 服务实例工厂,用于生成 ProtocolService 实例。

    类名功能
    ClientClient 类,用户可以通过 Client 实例发送 HTTP/1.1 或 HTTP/2 请求。
    ClientBuilder用于 Client 实例的构建,Client 没有公开的构造函数,用户只能通过 ClientBuilder 得到 Client 实例。ClientBuilder 文档中未明确说明支持版本的配置,在 HTTP/1.1 与 HTTP/2 都会生效。
    CookieHTTP 本身是无状态的,server 为了知道 client 的状态,提供个性化的服务,便可以通过 Cookie 来维护一个有状态的会话。
    FileHandler用于处理文件下载或者文件上传。
    FuncHandlerHttpRequestHandler 接口包装类,把单个函数包装成 HttpRequestHandler。
    HttpContextHttp 请求上下文,作为 HttpRequestHandler.handle 函数的参数在服务端使用。
    HttpHeaders用于表示 Http 报文中的 header 和 trailer,定义了相关增、删、改、查操作。
    HttpRequestHttp 请求类。
    HttpRequestBuilderHttpRequestBuilder 类用于构造 HttpRequest 实例。
    HttpResponseHttp 响应类。
    HttpResponseBuilder用于构造 HttpResponse 实例。
    HttpResponsePusherHTTP/2 服务器推送。
    HttpResponseWriterHTTP response消息体 Writer,支持用户控制消息体的发送过程。
    NotFoundHandler便捷的 Http 请求处理器,404 Not Found 处理器。
    OptionsHandler便捷的 Http 处理器,用于处理 OPTIONS 请求。固定返回 "Allow: OPTIONS,GET,HEAD,POST,PUT,DELETE" 响应头。
    ProtocolServiceHttp协议服务实例,为单个客户端连接提供 Http 服务,包括对客户端 request 报文的解析、 request 的分发处理、 response 的发送等。
    RedirectHandler便捷的 Http 处理器,用于回复重定向响应。
    Server提供 HTTP 服务的 Server 类。
    ServerBuilder提供 Server 实例构建器。
    WebSocket提供 WebSocket 服务的相关类,提供 WebSocket 连接的读、写、关闭等函数。用户通过 upgradeFrom 函数以获取 WebSocket 连接。
    WebSocketFrameWebSocket 用于读的基本单元。

    枚举

    枚举名功能
    FileHandlerType用于设置 FileHandler 是上传还是下载模式。
    Protocol定义 HTTP 协议类型枚举。
    WebSocketFrameType定义 WebSocketFrame 的枚举类型。

    结构体

    结构体名功能
    HttpStatusCode用来表示网页服务器超文本传输协议响应状态的 3 位数字代码。
    ServicePoolConfigHttp Server 协程池配置。
    TransportConfig传输层配置类,服务器建立连接使用的传输层配置。

    异常类

    异常类名功能
    ConnectionExceptionHttp 的tcp连接异常类。
    CoroutinePoolRejectExceptionHttp 的协程池拒绝请求处理异常类。
    HttpExceptionHttp 的通用异常类。
    HttpStatusExceptionHttp 的响应状态异常类。
    HttpTimeoutExceptionHttp 的超时异常类。
    WebSocketExceptionWebSocket 的通用异常类。

    函数

    func handleError(HttpContext, UInt16)

    public func handleError(ctx: HttpContext, code: UInt16): Unit
    

    功能:便捷的 Http 请求处理函数,用于回复错误请求。

    参数:

    func notFound(HttpContext)

    public func notFound(ctx: HttpContext): Unit
    

    功能:便捷的 Http 请求处理函数,用于回复 404 响应。

    参数:

    func upgrade(HttpContext)

    public func upgrade(ctx: HttpContext): StreamingSocket
    

    功能:在 handler 内获取 StreamingSocket,可用于支持协议升级和处理 CONNECT 请求。

    • 调用该函数时,将首先根据 ctx.responseBuilder 发送响应,仅发送状态码和响应头。
    • 调用该函数时,将把 ctx.request.body 置空,后续无法通过 body.read(...) 读数据,未读完的 body 数据将留存在返回的 StreamingSocket 中。

    参数:

    返回值:

    • StreamingSocket - 底层连接(对于 HTTP/2 是一个 stream),可用于后续读写。

    异常:

    • HttpException - 获取底层连接(对于 HTTP/2 是一个 stream)失败。

    接口

    interface CookieJar

    public interface CookieJar {
        prop isHttp: Bool
        prop rejectPublicSuffixes: ArrayList<String>
        static func createDefaultCookieJar(rejectPublicSuffixes: ArrayList<String>, isHttp: Bool): CookieJar
        static func parseSetCookieHeader(response: HttpResponse): ArrayList<Cookie>
        static func toCookieString(cookies: ArrayList<Cookie>): String
        func clear(): Unit
        func getCookies(url: URL): ArrayList<Cookie>
        func removeCookies(domain: String): Unit
        func storeCookies(url: URL, cookies: ArrayList<Cookie>): Unit
    }
    

    功能:CookieJarClient 用来管理 Cookie 的工具。

    其有两个静态函数:

    如果 Client 配置了 CookieJar,那么 Cookie 的解析收发都是自动的。

    说明

    prop isHttp

    prop isHttp: Bool
    

    功能:该 CookieJar 是否用于 HTTP 协议。

    • 若 isHttp 为 true, 则只会存储来自于 HTTP 协议的 Cookie
    • 若 isHttp 为 false, 则只会存储来自非 HTTP 协议的 Cookie,且不会存储发送设置了 httpOnly 的 Cookie

    类型:Bool

    prop rejectPublicSuffixes

    prop rejectPublicSuffixes: ArrayList<String>
    

    功能:获取 public suffixes 配置,该配置是一个 domain 黑名单,会拒绝 domain 值为 public suffixes 的 Cookie

    说明:

    如果该 Cookie 来自于与 domain 相同的 host,黑名单就不会生效。

    类型:ArrayList<String>

    static func createDefaultCookieJar(ArrayList<String>, Bool)

    static func createDefaultCookieJar(rejectPublicSuffixes: ArrayList<String>, isHttp: Bool): CookieJar
    

    功能:构建默认的管理 CookieCookieJar 实例。

    默认的 CookieJar 的管理要求参考 RFC 6265 5.3.

    参数:

    • rejectPublicSuffixes: ArrayList<String> - 用户配置的 public suffixes,Cookie 管理为了安全会拒绝 domain 值为 public suffixes 的 cookie(除非该 Cookie 来自于与 domain 相同的 host),public suffixes 见 PUBLIC SUFFIX LIST
    • isHttp: Bool - 该 CookieJar 是否用于 HTTP 协议,isHttp 为 true 则只会存储来自于 HTTP 协议的 Cookie

    返回值:

    static func parseSetCookieHeader(HttpResponse)

    static func parseSetCookieHeader(response: HttpResponse): ArrayList<Cookie>
    

    功能:解析 response 中的 Set-Cookie header。

    该函数解析 response 中的 Set-Cookie header,并返回解析出的 ArrayList<Cookie>,解析 Set-Cookie header 的具体规则见 RFC 6265 5.2.

    参数:

    返回值:

    static func toCookieString(ArrayList<Cookie>)

    static func toCookieString(cookies: ArrayList<Cookie>): String
    

    功能:将 ArrayList<Cookie> 转成字符串,用于 Cookie header。

    该函数会将传入的 ArrayList<Cookie> 数组转成协议规定的 Cookie header 的字符串形式,见 RFC 6265 5.4.4.

    参数:

    返回值:

    func clear()

    func clear(): Unit
    

    功能:清除全部 Cookie

    默认实现 CookieJarImpl 会清除 CookieJar 中的所有 Cookie

    func getCookies(URL)

    func getCookies(url: URL): ArrayList<Cookie>
    

    功能:从 CookieJar 中取出 ArrayList<Cookie>。

    默认实现 cookieJarImpl 的取 ArrayList<Cookie> 函数的具体要求见 RFC 6265 5.4.,对取出的 ArrayList<Cookie> 调用 toCookieString 可以将取出的 ArrayList<Cookie> 转成 Cookie header 的 value 字符串。

    参数:

    返回值:

    func removeCookies(String)

    func removeCookies(domain: String): Unit
    

    功能:从 CookieJar 中移除某个 domain 的 Cookie

    说明:

    默认实现 CookieJarImpl 的移除某个 domain 的 Cookie 只会移除特定 domain 的 Cookie,domain 的 subdomain 的 Cookie 并不会移除。

    参数:

    异常:

    • IllegalArgumentException - 如果传入的 domain 为空字符串或者非法,则抛出该异常,合法的 domain 规则见 Cookie 的参数文档。

    func storeCookies(URL, ArrayList<Cookie>)

    func storeCookies(url: URL, cookies: ArrayList<Cookie>): Unit
    

    功能:将 ArrayList<Cookie> 存进 CookieJar

    如果往 CookieJar 中存 Cookie 时超过了上限(3000 条),那么至少清除 CookieJar 中 1000 条 Cookie 再往里存储。清除 CookieJarCookie 的优先级见 RFC 6265 5.3.12.

    Cookie按如下顺序清除:

    • 过期的 Cookie
    • 相同 domain 中超过 50 条以上的部分;
    • 所有 Cookie具有相同优先级的 Cookie 则优先删除 last-access 属性更早的。

    参数:

    interface HttpRequestDistributor

    public interface HttpRequestDistributor
    

    功能:Http request 分发器接口,将一个 request 按照 url 中的 path 分发给对应的 HttpRequestHandler 处理。

    说明:

    本实现提供一个默认的 HttpRequestDistributor,该 distributor 非线程安全。 默认实现提供仓颉标准库中 HTTP/1.1、HTTP/2 的 ProtocolService 实例。 且只能在启动 server 前 register,启动后再次 register,结果未定义。 如果用户希望在启动 server 后还能够 register,需要自己提供一个线程安全的 HttpRequestDistributor 实现。

    func distribute(String)

    func distribute(path: String): HttpRequestHandler
    

    功能:分发请求处理器,未找到对应请求处理器时,将返回 NotFoundHandler 以返回 404 状态码。

    参数:

    • path: String - 请求路径。

    返回值:

    func register(String, (HttpContext) -> Unit)

    func register(path: String, handler: (HttpContext) -> Unit): Unit
    

    功能:注册请求处理器。

    参数:

    异常:

    func register(String, HttpRequestHandler)

    func register(path: String, handler: HttpRequestHandler): Unit
    

    功能:注册请求处理器。

    参数:

    异常:

    interface HttpRequestHandler

    public interface HttpRequestHandler {
        func handle(ctx: HttpContext): Unit
    }
    

    功能:Http request 处理器。

    http server 端通过 handler 处理来自客户端的 http request;在 handler 中用户可以获取 http request 的详细信息,包括 header、body;在 handler 中,用户可以构造 http response,包括 header、body,并且可以直接发送 response 给客户端,也可交由 server 发送。

    用户在构建 http server 时,需手动通过 server 的 HttpRequestDistributor 注册一个或多个 handler,当一个客户端 http request 被接收,distributor 按照 request 中 url 的 path 分发给对应的 handler 处理。

    注意:

    应用程序应注意 DNS 重绑定攻击,即在 handler 的处理逻辑中对 request 中的 Host 请求头的值进行合法性校验,校验该值是否为此应用程序所认可的权威主机名。

    func handle(HttpContext)

    func handle(ctx: HttpContext): Unit
    

    功能:处理 Http 请求。

    参数:

    interface ProtocolServiceFactory

    public interface ProtocolServiceFactory {
        func create(protocol: Protocol, socket: StreamingSocket): ProtocolService
    }
    

    功能:Http 服务实例工厂,用于生成 ProtocolService 实例。

    ServerBuilder 提供默认的实现。默认实现提供仓颉标准库中 HTTP/1.1、HTTP/2 的 ProtocolService 实例。

    func create()

    func create(protocol: Protocol, socket: StreamingSocket): ProtocolService
    

    功能:根据协议创建协议服务实例。

    参数:

    • protocol: Protocol - 协议版本,如 HTTP1_0、HTTP1_1、HTTP2_0。
    • socket: StreamingSocket - 来自客户端的套接字。

    返回值:

    • ProtocolService - 协议服务实例。

    class Client

    public class Client
    

    功能:发送 Http request、随时关闭等。用户可以通过 Client 实例发送 HTTP/1.1 或 HTTP/2 请求。

    说明:

    Client 文档中未明确说明支持版本的配置,在 HTTP/1.1 与 HTTP/2 都会生效。

    prop autoRedirect

    public prop autoRedirect: Bool
    

    功能:客户端是否会自动进行重定向,304 状态码默认不重定向。

    类型:Bool

    prop connector

    public prop connector: (SocketAddress) -> StreamingSocket
    

    功能:客户端调用此函数获取到服务器的连接。

    类型:(SocketAddress) -> StreamingSocket

    prop cookieJar

    public prop cookieJar: ?CookieJar
    

    功能:用于存储客户端所有 Cookie,如果配置为 None,则不会启用 Cookie

    类型:?CookieJar

    prop enablePush

    public prop enablePush: Bool
    

    功能:客户端 HTTP/2 是否支持服务器推送,默认值为 true。

    类型:Bool

    prop headerTableSize

    public prop headerTableSize: UInt32
    

    功能:获取客户端 HTTP/2 Hpack 动态表的初始值,默认值为 4096。

    类型:UInt32

    prop httpProxy

    public prop httpProxy: String
    

    功能:获取客户端 http 代理,默认使用系统环境变量 http_proxy 的值,用字符串表示,格式为:"http://host:port",例如:"http://192.168.1.1:80"

    类型:String

    prop httpsProxy

    public prop httpsProxy: String
    

    功能:获取客户端 https 代理,默认使用系统环境变量 https_proxy 的值,用字符串表示,格式为:"http://host:port",例如:"http://192.168.1.1:443"

    类型:String

    prop initialWindowSize

    public prop initialWindowSize: UInt32
    

    功能:获取客户端 HTTP/2 流控窗口初始值,默认值为 65535 ,取值范围为 0 至 2^31 - 1。

    类型:UInt32

    prop logger

    public prop logger: Logger
    

    功能:获取客户端日志记录器,设置 logger.level 将立即生效,记录器应该是线程安全的。

    类型:Logger

    prop maxConcurrentStreams

    public prop maxConcurrentStreams: UInt32
    

    功能:获取客户端 HTTP/2 初始最大并发流数量,默认值为 2^31 - 1。

    类型:UInt32

    prop maxFrameSize

    public prop maxFrameSize: UInt32
    

    功能:获取客户端 HTTP/2 初始最大帧大小。默认值为 16384. 取值范围为 2^14 至 2^24 - 1。

    类型:UInt32

    prop maxHeaderListSize

    public prop maxHeaderListSize: UInt32
    

    功能:获取客户端支持的 HTTP/2 最大头部(Header)大小。这个大小指的是响应头部中所有头部字段(Header Field)的最大允许长度之和,其中包括所有字段名称(name)的长度、字段值(value)的长度以及每个字段自动添加的伪头开销(通常每个字段会有32字节的开销,这包括了HTTP/2协议本身为头部字段添加的伪头部信息)。默认情况下,这个最大长度被设置为 UInt32.Max。

    类型:UInt32

    prop poolSize

    public prop poolSize: Int64
    

    功能:配置 HTTP/1.1 客户端使用的连接池的大小,亦可表示对同一个主机(host:port)同时存在的连接数的最大值。

    类型:Int64

    prop readTimeout

    public prop readTimeout: Duration
    

    功能:获取客户端设定的读取整个响应的超时时间,默认值为 15s。

    类型:Duration

    prop writeTimeout

    public prop writeTimeout: Duration
    

    功能:获取客户端设定的写请求的超时时间,默认值为 15s。

    类型:Duration

    func close()

    public func close(): Unit
    

    功能:关闭客户端建立的所有连接,调用后不能继续发送请求。

    func connect(String, HttpHeaders, Protocol)

    public func connect(url: String, header!: HttpHeaders = HttpHeaders(), version!: Protocol = HTTP1_1): (HttpResponse, ?StreamingSocket)
    

    功能:发送 CONNECT 请求与服务器建立隧道,返回建连成功后的连接,连接由用户负责关闭。服务器返回 2xx 表示建连成功,否则建连失败(不支持自动重定向,3xx 也视为失败)。

    参数:

    • url: String - 请求的 url。
    • header!: HttpHeaders - 请求头,默认为空请求头。
    • version!: Protocol - 请求的协议,默认为 HTTP1_1。

    返回值:

    异常:

    func delete(String)

    public func delete(url: String): HttpResponse
    

    功能:请求方法为 DELETE 的便捷请求函数。

    参数:

    • url: String - 请求的 url。

    返回值:

    异常:

    func get(String)

    public func get(url: String): HttpResponse
    

    功能:请求方法为 GET 的便捷请求函数。

    参数:

    • url: String - 请求的 url。

    返回值:

    异常:

    func getTlsConfig()

    public func getTlsConfig(): ?TlsClientConfig
    

    功能:获取客户端设定的 TLS 层配置。

    返回值:

    • ?TlsClientConfig - 客户端设定的 TLS 层配置,如果没有设置则返回 None。

    func head(String)

    public func head(url: String): HttpResponse
    

    功能:请求方法为 HEAD 的便捷请求函数。

    参数:

    • url: String - 请求的 url。

    返回值:

    异常:

    func options(String)

    public func options(url: String): HttpResponse
    

    功能:请求方法为 OPTIONS 的便捷请求函数。

    参数:

    • url: String - 请求的 url。

    返回值:

    异常:

    func post(String, Array<UInt8>)

    public func post(url: String, body: Array<UInt8>): HttpResponse
    

    功能:请求方法为 POST 的便捷请求函数。

    参数:

    返回值:

    异常:

    func post(String, InputStream)

    public func post(url: String, body: InputStream): HttpResponse
    

    功能:请求方法为 POST 的便捷请求函数。

    参数:

    返回值:

    异常:

    func post(String, String)

    public func post(url: String, body: String): HttpResponse
    

    功能:请求方法为 POST 的便捷请求函数。

    参数:

    • url: String - 请求的 url。
    • body: String - 请求体。

    返回值:

    异常:

    func put(String, Array<UInt8>)

    public func put(url: String, body: Array<UInt8>): HttpResponse
    

    功能:请求方法为 PUT 的便捷请求函数。

    参数:

    返回值:

    异常:

    func put(String, InputStream)

    public func put(url: String, body: InputStream): HttpResponse
    

    功能:请求方法为 PUT 的便捷请求函数。

    参数:

    返回值:

    异常:

    func put(String, String)

    public func put(url: String, body: String): HttpResponse
    

    功能:请求方法为 PUT 的便捷请求函数。

    参数:

    • url: String - 请求的 url。
    • body: String - 请求体。

    返回值:

    异常:

    func send(HttpRequest)

    public func send(req: HttpRequest): HttpResponse
    

    功能:通用请求函数,发送 HttpRequest 到 url 中的服务器,接收 HttpResponse

    注意:

    • 对于 HTTP/1.1,如果请求中有 body 要发,那么需要保证 Content-Length 和 Transfer-Encoding: chunked必有且只有一个,以 chunked 形式发时,每段 chunk 最大为 8192 字节;如果用户发送的 body 为自己实现的 InputStream 类,则需要自己保证 Content-Length和 Transfer-Encoding: chunked 设置且只设置了一个;如果用户采用默认的 body 发送,Content-Length 和 Transfer-Encoding: chunked都缺失时,我们会为其补上 Content-Length header,值为 body.size;
    • 用户如果设置了 Content-Length,则需要保证其正确性:如果所发 body 的内容大于等于 Content-Length 的值,我们会发送长度为 Content-Length 值的数据;如果所发 body 的内容小于 Content-Length 的值,此时如果 body 是默认的 body,则会抛出 HttpException,如果 body是用户自己实现的 InputStream 类,其行为便无法保证(可能会造成服务器端的读 request 超时或者客户端的收 response 超时);
    • 升级函数通过 WebSocket 的 upgradeFromClient 或 Clientupgrade 接口发出,调用 client 的其他函数发送 upgrade 请求会抛出异常;
    • 协议规定 TRACE 请求无法携带内容,故用户发送带有 body 的 TRACE 请求时会抛出异常;
    • HTTP/1.1 默认对同一个服务器的连接数不超过 10 个。response 的 body 需要用户调用 body.read(buf: Array<Byte>) 函数去读。body 被读完后,连接才能被客户端对象复用,否则请求相同的服务器也会新建连接。新建连接时如果连接数超出限制则会抛出 HttpException
    • body.read 函数将 body 读完之后返回 0,如果读的时候连接断开会抛出 ConnectionException
    • HTTP/1.1 的升级请求如果收到 101 响应,则表示切换协议,此连接便不归 client 管理;
    • 下文的快捷请求函数的注意点与 send 相同。

    参数:

    返回值:

    异常:

    func upgrade(HttpRequest)

    public func upgrade(req: HttpRequest): (HttpResponse, ?StreamingSocket)
    

    功能:发送请求并升级协议,用户设置请求头,返回升级后的连接(如果升级成功),连接由用户负责关闭。

    说明:

    • 服务器返回 101 表示升级成功,获取到了 StreamingSocket
    • 必选请求头:
      • Upgrade: protocol-name ["/" protocol-version];
      • Connection: Upgrade (在请求头包含 Upgrade 字段时会自动添加);
    • 不支持 HTTP/1.0、HTTP/2;
    • 不支持 HTTP/1.1 CONNECT 方法的 HttpRequest

    参数:

    返回值:

    异常:

    class ClientBuilder

    public class ClientBuilder {
        public init()
    }
    

    功能:用于 Client 实例的构建,Client 没有公开的构造函数,用户只能通过 ClientBuilder 得到 Client 实例。ClientBuilder 文档中未明确说明支持版本的配置,在 HTTP/1.1 与 HTTP/2 都会生效。

    init()

    public init()
    

    功能:创建新的 ClientBuilder 实例。

    func autoRedirect(Bool)

    public func autoRedirect(auto: Bool): ClientBuilder
    

    功能:配置客户端是否会自动进行重定向。重定向会请求 Location 头的资源,协议规定,Location 只能包含一个 URI 引用Location = URI-reference,详见 RFC 9110 10.2.2.。304 状态码默认不重定向。

    参数:

    • auto: Bool - 默认值为 true,即开启自动重定向。

    返回值:

    func build()

    public func build(): Client
    

    功能:构造 Client 实例。

    返回值:

    异常:

    func connector((SocketAddress)->StreamingSocket)

    public func connector(connector: (SocketAddress)->StreamingSocket): ClientBuilder
    

    功能:客户端调用此函数获取到服务器的连接。

    参数:

    返回值:

    func cookieJar(?CookieJar)

    public func cookieJar(cookieJar: ?CookieJar): ClientBuilder
    

    功能:用于存储客户端所有 Cookie

    参数:

    返回值:

    func enablePush(Bool)

    public func enablePush(enable: Bool): ClientBuilder
    

    功能:配置客户端 HTTP/2 是否支持服务器推送。

    参数:

    • enable: Bool - 默认值 true。

    返回值:

    func headerTableSize(UInt32)

    public func headerTableSize(size: UInt32): ClientBuilder
    

    功能:配置客户端 HTTP/2 Hpack 动态表初始值。

    参数:

    • size: UInt32 - 默认值 4096。

    返回值:

    func httpProxy(String)

    public func httpProxy(addr: String): ClientBuilder
    

    功能:设置客户端 http 代理,默认使用系统环境变量 http_proxy 的值。

    参数:

    • addr: String - 格式为:"http://host:port",例如:"http://192.168.1.1:80"

    返回值:

    func httpsProxy(String)

    public func httpsProxy(addr: String): ClientBuilder
    

    功能:设置客户端 https 代理,默认使用系统环境变量 https_proxy 的值。

    参数:

    • addr: String - 格式为:"http://host:port",例如:"http://192.168.1.1:443"

    返回值:

    func initialWindowSize(UInt32)

    public func initialWindowSize(size: UInt32): ClientBuilder
    

    功能:配置客户端 HTTP/2 流控窗口初始值。

    参数:

    • size: UInt32 - 默认值 65535 , 取值范围为 0 至 2^31 - 1。

    返回值:

    func logger(Logger)

    public func logger(logger: Logger): ClientBuilder
    

    功能:设定客户端的 logger,默认 logger 级别为 INFO,logger 内容将写入 Console.stdout。

    参数:

    • logger: Logger - 需要是线程安全的,默认使用内置线程安全 logger。

    返回值:

    func maxConcurrentStreams(UInt32)

    public func maxConcurrentStreams(size: UInt32): ClientBuilder
    

    功能:配置客户端 HTTP/2 初始最大并发流数量。

    参数:

    • size: UInt32 - 默认值为 2^31 - 1。

    返回值:

    func maxFrameSize(UInt32)

    public func maxFrameSize(size: UInt32): ClientBuilder
    

    功能:配置客户端 HTTP/2 初始最大帧大小。

    参数:

    • size: UInt32 - 默认值为 16384. 取值范围为 2^14 至 2^24 - 1。

    返回值:

    func maxHeaderListSize(UInt32)

    public func maxHeaderListSize(size: UInt32): ClientBuilder
    

    功能:获取客户端支持的 HTTP/2 最大头部(Header)大小。这个大小指的是响应头部中所有头部字段(Header Field)的最大允许长度之和,其中包括所有字段名称(name)的长度、字段值(value)的长度以及每个字段自动添加的伪头开销(通常每个字段会有32字节的开销,这包括了HTTP/2协议本身为头部字段添加的伪头部信息)。默认情况下,这个最大长度被设置为 UInt32.Max。

    参数:

    • size: UInt32 - 客户端接收的 HTTP/2 响应 headers 最大长度。

    返回值:

    func noProxy()

    public func noProxy(): ClientBuilder
    

    功能:调用此函数后,客户端不使用任何代理。

    返回值:

    func poolSize(Int64)

    public func poolSize(size: Int64): ClientBuilder
    

    功能:配置 HTTP/1.1 客户端使用的连接池的大小,亦可表示对同一个主机(host:port)同时存在的连接数的最大值。

    参数:

    • size: Int64 - 默认 10,poolSize 需要大于 0。

    返回值:

    异常:

    • HttpException - 如果传参小于等于 0,则会抛出该异常。

    func readTimeout(Duration)

    public func readTimeout(timeout: Duration): ClientBuilder
    

    功能:设定客户端读取一个响应的最大时长。

    参数:

    返回值:

    func tlsConfig(TlsClientConfig)

    public func tlsConfig(config: TlsClientConfig): ClientBuilder
    

    功能:设置 TLS 层配置,默认不对其进行设置。

    参数:

    • config: TlsClientConfig - 设定支持 tls 客户端需要的配置信息。

    返回值:

    func writeTimeout(Duration)

    public func writeTimeout(timeout: Duration): ClientBuilder
    

    功能:设定客户端发送一个请求的最大时长。

    参数:

    返回值:

    public class Cookie {
        public init(name: String, value: String, expires!: ?DateTime = None, maxAge!: ?Int64 = None,
            domain!: String = "", path!: String = "", secure!: Bool = false, httpOnly!: Bool = false)
    }
    

    功能:HTTP 本身是无状态的,server 为了知道 client 的状态,提供个性化的服务,便可以通过 Cookie 来维护一个有状态的会话。

    说明:

    • 用户首次访问某站点时,server 通过 Set-Cookie header 将 name/value 对,以及 attribute-value 传给用户代理;用户代理随后对该站点的请求中便可以将 name/value 加入到 Cookie header 中。
    • Cookie 类提供了构建 Cookie 对象,并将 Cookie 对象转成 Set-Cookie header 值的函数,提供了获取 Cookie 对象各属性值的函数。
    • Cookie 的各个属性的要求和作用见 RFC 6265
    • 下文中 cookie-name,cookie-value,expires-av 等名字采用 RFC 6265 中的术语,详情请见协议。

    prop cookieName

    public prop cookieName: String
    

    功能:获取 Cookie 对象的 cookie-name 值。

    类型:String

    prop cookieValue

    public prop cookieValue: String
    

    功能:获取 Cookie 对象的 cookie-value 值。

    类型:String

    prop domain

    public prop domain: String
    

    功能:获取 Cookie 对象的 domain-av 值。

    类型:String

    prop expires

    public prop expires: ?DateTime
    

    功能:获取 Cookie 对象的 expires-av 值。

    类型:?DateTime

    prop httpOnly

    public prop httpOnly: Bool
    

    功能:获取 Cookie 对象的 httpOnly-av 值。

    类型:Bool

    prop maxAge

    public prop maxAge: ?Int64
    

    功能:获取 Cookie 对象的 max-age-av 值。

    类型:?Int64

    prop others

    public prop others: ArrayList<String>
    

    功能:获取未被解析的属性。

    类型:ArrayList<String>

    prop path

    public prop path: String
    

    功能:获取 Cookie 对象的 path-av 值。

    类型:String

    prop secure

    public prop secure: Bool
    

    功能:获取 Cookie 对象的 secure-av 值。

    类型:Bool

    init(String, String, ?DateTime, ?Int64, String, String, Bool, Bool)

    public init(name: String, value: String, expires!: ?DateTime = None, maxAge!: ?Int64 = None,
        domain!: String = "", path!: String = "", secure!: Bool = false, httpOnly!: Bool = false)
    

    功能:提供 Cookie 对象的公开构造器说明:该构造器会检查传入的各项属性是否满足协议要求,如果不满足则会产生 IllegalArgumentException。具体要求见 RFC 6265 4.1.1.

    注意:

    Cookie 各属性中只有 cookie-name,cookie-value 是必需的,必须传入 name,value 参数,但 value 参数可以传入空字符串。

    参数:

    • name: String - cookie-name 属性。

      name         = token 
      token        = 1*tchar
      tchar        = "!" / "#" / "$" / "%" / "&" / "'" / "*"
                     / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~"
                     / DIGIT / ALPHA
      
    • value: String - cookie-value 属性。

      value        = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )
      cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
                  ; US-ASCII characters excluding CTLs,
                  ; whitespace DQUOTE, comma, semicolon,
                  ; and backslash
      
    • expires!: ?DateTime - 设置 Cookie 的过期时间,默认为 None,时间必须在 1601 年之后。

    • maxAge!: ?Int64 - Cookie 的最大生命周期,默认为 None,如果 Cookie 既有 expires 属性,也有 maxAge,则表示该 Cookie 只维护到会话结束(维护到 Client 关闭之前,Client 关闭之后设置了过期的 Cookie 也不再维护)。

      max-age-av     = "Max-Age=" non-zero-digit *DIGIT
      non-zero-digit = %x31-39
                      ; digits 1 through 9
      DIGIT          = %x30-39
                      ; digits 0 through 9
      
    • domain!: String - 默认为空字符串,表示该收到该 Cookie 的客户端只会发送该 Cookie 给原始服务器。如果设置了合法的 domain,则收到该 Cookie 的客户端只会发送该 Cookie 给所有该 domain 的子域(且满足其他属性条件要求才会发)。

      domain          = <subdomain> | " "
      <subdomain>   ::= <label> | <subdomain> "." <label>
      <label>       ::= <letter> [ [ <ldh-str> ] <let-dig> ]
      <ldh-str>     ::= <let-dig-hyp> | <let-dig-hyp> <ldh-str>
      <let-dig-hyp> ::= <let-dig> | "-"
      <let-dig>     ::= <letter> | <digit>
      <letter>      ::= any one of the 52 alphabetic characters A through Z in upper case and a through z in lower case
      <digit>       ::= any one of the ten digits 0 through 9
      RFC 1035 2.3.1.
      而 RFC 1123 2.1. 放松了对 label 首字符必须是 letter 的限制
      因此,对 domain 的要求为:
      1、总长度小于等于 255,由若干个 label 组成
      2、label 与 label 之间通过 "." 分隔,每个 label 长度小于等于 63
      3、label 的开头和结尾必须是数字或者字母,label 的中间字符必须是数字、字母或者 "-"
      
    • path!: String - 默认为空字符串,客户端会根据 url 计算出默认的 path 属性,见 RFC 6265 5.1.4.。 收到该 Cookie 的客户端只会发送该 Cookie 给所有该 path 的子目录(且满足其他属性条件要求才会发)。

      path            = <any RUNE except CTLs or ";">
      RUNE            = <any [USASCII] character>
      CTLs            = <controls>
      
    • secure!: Bool - 默认为 false,如果设置为 true,该 Cookie 只会在安全协议请求中发送。

    • httpOnly!: Bool - 默认为 false,如果设置为 true,该 Cookie 只会在 HTTP 协议请求中发送。

    异常:

    func toSetCookieString()

    public func toSetCookieString(): String
    

    功能:提供将 Cookie 转成字符串形式的函数,方便 server 设置 Set-Cookie header。

    注意:

    • Cookie 各属性(包含 name,value)在对象创建时就被检查了,因此 toSetCookieString() 函数不会产生异常;
    • Cookie 必需的属性是 cookie-pair 即 cookie-name "=" cookie-value,cookie-value 可以为空字符串,toSetCookieString() 函数只会将设置过的属性写入字符串,即只有 "cookie-name=" 是必有的,其余部分是否存在取决于是否设置。

    返回值:

    • String - 字符串对象,用于设置 Set-Cookie header。

    class FileHandler

    public class FileHandler <: HttpRequestHandler {
        public init(path: String, handlerType!: FileHandlerType = DownLoad, bufferSize!: Int64 = 64 * 1024)
    }
    

    功能:用于处理文件下载或者文件上传。

    文件下载:

    • 构造 FileHandler 时需要传入待下载文件的路径,目前一个 FileHandler 只能处理一个文件的下载;
    • 下载文件只能使用 GET 请求,其他请求返回 400 状态码;
    • 文件如果不存在,将返回 404 状态码。

    文件上传:

    • 构造 FileHandler 时需要传入一个存在的目录路径,上传到服务端的文件将保存在这个目录中;
    • 上传文件时只能使用 POST 请求,其他请求返回 400 状态码;
    • 上传数据的 http 报文必须是 multipart/form-data 格式的,Content-Type 头字段的值为 multipart/form-data; boundary=----XXXXX
    • 上传文件的文件名存放在 form-data 数据报文中,报文数据格式为 Content-Disposition: form-data; name="xxx"; filename="xxxx",文件名是 filename 字段的值;
    • 目前 form-data 中必须包含 filename 字段;
    • 如果请求报文不正确,将返回 400 状态码;
    • 如果出现其他异常,例如文件处理异常,将返回 500 状态码。

    父类型:

    init(String, FileHandlerType, Int64)

    public init(path: String, handlerType!: FileHandlerType = DownLoad, bufferSize!: Int64 = 64 * 1024)
    

    功能:FileHandler 的构造函数。

    参数:

    • path: String - FileHandler 构造时需要传入的文件或者目录路径字符串,上传模式中只能传入存在的目录路径;路径中存在../时,用户需要确认标准化后的绝对路径是期望传入的路径。
    • handlerType!: FileHandlerType - 构造 FileHandler 时指定当前 FileHandler 的工作模式,默认为 DownLoad 下载模式。
    • bufferSize!: Int64 - 内部从网络读取或者写入的缓冲区大小,默认值为 64*1024(64k),若小于 4096,则使用 4096 作为缓冲区大小。

    异常:

    func handle(HttpContext)

    public func handle(ctx: HttpContext): Unit
    

    功能:根据请求对响应数据进行处理。

    参数:

    class FuncHandler

    public class FuncHandler <: HttpRequestHandler {
        public FuncHandler((HttpContext) -> Unit)
    }
    

    功能:HttpRequestHandler 接口包装类,把单个函数包装成 HttpRequestHandler

    父类型:

    FuncHandler((HttpContext) -> Unit)

    public FuncHandler(let handler: (HttpContext) -> Unit)
    

    功能:FuncHandler 的构造函数。

    参数:

    func handle(HttpContext)

    public func handle(ctx: HttpContext): Unit
    

    功能:处理 Http 请求。

    参数:

    class HttpContext

    public class HttpContext
    

    功能:Http 请求上下文,作为 HttpRequestHandler.handle 函数的参数在服务端使用。

    prop clientCertificate

    public prop clientCertificate: ?Array<X509Certificate>
    

    功能:获取 Http 客户端证书。

    类型:?Array<X509Certificate>

    prop request

    public prop request: HttpRequest
    

    功能:获取 Http 请求。

    类型:HttpRequest

    prop responseBuilder

    public prop responseBuilder: HttpResponseBuilder
    

    功能:获取 Http 响应构建器。

    类型:HttpResponseBuilder

    class HttpHeaders

    public class HttpHeaders <: Iterable<(String, Collection<String>)> {
        public init()
    }
    

    功能:此类用于表示 Http 报文中的 header 和 trailer,定义了相关增、删、改、查操作。

    说明:

    • header 和 trailer 为键值映射集,由若干 field-line 组成,每一个 field-line 包含一个键 (field -name) 和若干值 (field-value)。
    • field-name 由 token 字符组成,不区分大小写,在该类中将转为小写保存。
    • field-value 由 vchar,SP 和 HTAB 组成,vchar 表示可见的 US-ASCII 字符,不得包含前后空格,不得为空值。
    • 详见 rfc 9110

    示例:

    Example-Field: Foo, Bar
    key: Example-Field, value: Foo, Bar
    field-name = token
    token = 1*tchar
    tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*"
    / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~"
    / DIGIT / ALPHA
    ; any VCHAR, except delimiters
    

    父类型:

    init()

    public init()
    

    功能:创建新的 HttpHeaders 实例。

    func add(String, String)

    public func add(name: String, value: String): Unit
    

    功能:添加指定键值对。如果 name 已经存在,将在其对应的值列表中添加 value;如果 name 不存在,则添加 name 字段及其值 value。

    参数:

    异常:

    • HttpException - 如果传入的 name/value 包含不合法元素,将抛出此异常。

    func del(String)

    public func del(name: String): Unit
    

    功能:删除指定 name 对应的键值对。

    参数:

    • name: String - 删除的字段名称。

    func get(String)

    public func get(name: String): Collection<String>
    

    功能:获取指定 name 对应的 value 值。

    参数:

    • name: String - 字段名称,不区分大小写。

    返回值:

    • Collection<String> - name 对应的 value 集合,如果指定 name 不存在,返回空集合。

    func getFirst(String)

    public func getFirst(name: String): ?String
    

    功能:获取指定 name 对应的第一个 value 值。

    参数:

    • name: String - 字段名称,不区分大小写。

    返回值:

    • ?String - name 对应的第一个 value 值,如果指定 name 不存在,返回 None。

    func isEmpty()

    public func isEmpty(): Bool
    

    功能:判断当前实例是否为空,即没有任何键值对。

    返回值:

    • Bool - 如果当前实例为空,返回 true,否则返回 false。

    func iterator()

    public func iterator(): Iterator<(String, Collection<String>)>
    

    功能:获取迭代器,可用于遍历所有键值对。

    返回值:

    func set(String, String)

    public func set(name: String, value: String): Unit
    

    功能:设置指定键值对。如果 name 已经存在,传入的 value 将会覆盖之前的值。

    参数:

    异常:

    • HttpException - 如果传入的 name/values 包含不合法元素,将抛出此异常。

    class HttpRequest

    public class HttpRequest <: ToString
    

    功能:此类为 Http 请求类。

    客户端发送请求时,需要构造一个 HttpRequest 实例,再编码成字节报文发出。

    服务端处理请求时,需要把收到的请求解析成 HttpRequest 实例,并传给 handler 处理函数。

    父类型:

    prop body

    public prop body: InputStream
    

    功能:获取 body。

    注意:

    • body 不支持并发读取;
    • 默认 InputStream 实现类的 read 函数不支持多次读取。

    类型:InputStream

    prop bodySize

    public prop bodySize: Option<Int64>
    

    功能:获取请求 body 长度。

    • 如果未设置 body,则 bodySize 为 Some(0);
    • 如果 body 长度已知,即通过 Array<UInt8> 或 String 传入 body,或传入的 InputStream 有确定的 length (length >= 0),则 bodySize 为 Some(Int64);
    • 如果 body 长度未知,即通过用户自定义的 InputStream 实例传入 body 且 InputStream 实例没有确定的 length (length < 0),则 bodySize 为 None。

    类型:Option<Int64>

    prop close

    public prop close: Bool
    

    功能:表示该请求 header 是否包含 Connection: close

    • 对于服务端,close 为 true 表示处理完该请求应该关闭连接。
    • 对于客户端,close 为 true 表示如果收到响应后服务端未关闭连接,客户端应主动关闭连接。

    类型:Bool

    prop form

    public prop form: Form
    

    功能:获取请求中的表单信息。

    • 如果请求方法为 POST,PUT,PATCH,且 content-type 包含 application/x-www-form-urlencoded,获取请求 body 部分,用 form 格式解析;
    • 如果请求方法不为 POST,PUT,PATCH,获取请求 url 中 query 部分。

    注意:

    • 如果用该接口读取了 body,body 已被消费完,后续将无法通过 body.read 读取 body;
    • 如果 form 不符合 Form 格式,抛 UrlSyntaxException 异常。

    类型:Form

    prop headers

    public prop headers: HttpHeaders
    

    功能:获取 headers,headers 详述见 HttpHeaders 类,获取后,可通过调用 HttpHeaders 实例成员函数,修改该请求的 headers。

    类型:HttpHeaders

    prop method

    public prop method: String
    

    功能:获取 method,如 "GET", "POST",request 实例的 method 无法修改。

    类型:String

    prop readTimeout

    public prop readTimeout: ?Duration
    

    功能:表示该请求的请求级读超时时间。None 表示没有设置;Some(Duration) 表示设置了读超时时间。

    类型:?Duration

    prop remoteAddr

    public prop remoteAddr: String
    

    功能:用于服务端,获取对端地址,即客户端地址,格式为 ip: port,用户无法设置,自定义的 request 对象调用该属性返回 "",服务端 handler 中调用该属性返回客户端地址。

    类型:String

    prop trailers

    public prop trailers: HttpHeaders
    

    功能:获取 trailers,trailers 详述见 HttpHeaders 类,获取后,可通过调用 HttpHeaders 实例成员函数,修改该请求的 trailers。

    类型:HttpHeaders

    prop url

    public prop url: URL
    

    功能:获取 url,表示客户端访问的 url。

    类型:URL

    prop version

    public prop version: Protocol
    

    功能:获取 http 版本,如 HTTP1_1 和 HTTP2_0,request 实例的 version 无法修改。

    类型:Protocol

    prop writeTimeout

    public prop writeTimeout: ?Duration
    

    功能:表示该请求的请求级写超时时间,None 表示没有设置;Some(Duration) 表示设置了写超时时间。

    类型:?Duration

    func toString()

    public override func toString(): String
    

    功能:把请求转换为字符串,包括 start line,headers,body size,trailers。 例如:"GET /path HTTP/1.1\r\nhost: www.example.com\r\n\r\nbody size: 5\r\nbar: foo\r\n"

    返回值:

    • String - 请求的字符串表示。

    class HttpRequestBuilder

    public class HttpRequestBuilder {
        public init()
    }
    

    功能:HttpRequestBuilder 类用于构造 HttpRequest 实例。

    init()

    public init()
    

    功能:构造一个新 HttpRequestBuilder

    init(HttpRequest)

    public init(request: HttpRequest)
    

    功能: 通过 request 构造一个具有 request 属性的 HttpRequestBuilder。由于 body 成员是一个 InputStream,对原始的 request 的 body 的操作会影响到复制得到的 HttpRequest 的 body。HttpRequestBuilder 的 headers 和 trailers 是入参 request 的深拷贝。其余元素都是入参 request 的浅拷贝(因为是不可变对象,无需深拷贝)。

    参数:

    func addHeaders(HttpHeaders)

    public func addHeaders(headers: HttpHeaders): HttpRequestBuilder
    

    功能:向请求 header 添加参数 HttpHeaders 中的键值对。

    参数:

    返回值:

    func addTrailers(HttpHeaders)

    public func addTrailers(trailers: HttpHeaders): HttpRequestBuilder
    

    功能:向请求 trailer 添加参数 HttpHeaders 中的键值对。

    参数:

    返回值:

    func body(Array<UInt8>)

    public func body(body: Array<UInt8>): HttpRequestBuilder
    

    功能:设置请求 body。如果已经设置过,调用该函数将替换原 body。

    参数:

    • body: Array<UInt8> - 字节数组形式的请求体。

    返回值:

    func body(InputStream)

    public func body(body: InputStream): HttpRequestBuilder
    

    功能:设置请求 body。如果已经设置过,调用该函数将替换原 body。

    参数:

    返回值:

    func body(String)

    public func body(body: String): HttpRequestBuilder
    

    功能:设置请求 body,如果已经设置过,调用该函数将替换原 body调用该函数设置请求 body,则 body 将以内置的 InputStream 实现类表示,其大小已知。

    参数:

    • body: String - 字符串形式的请求体。

    返回值:

    func build()

    public func build(): HttpRequest
    

    功能:根据 HttpRequestBuilder 实例生成一个 HttpRequest 实例。

    返回值:

    func connect()

    public func connect(): HttpRequestBuilder
    

    功能:构造 method 为 "CONNECT" 的请求的便捷函数。

    返回值:

    func delete()

    public func delete(): HttpRequestBuilder
    

    功能:构造 method 为 "DELETE" 的请求的便捷函数。

    返回值:

    func get()

    public func get(): HttpRequestBuilder
    

    功能:构造 method 为 "GET" 的请求的便捷函数。

    返回值:

    func head()

    public func head(): HttpRequestBuilder
    

    功能:构造 method 为 "HEAD" 的请求的便捷函数。

    返回值:

    func header(String, String)

    public func header(name: String, value: String): HttpRequestBuilder
    

    功能:向请求 header 添加指定键值对,规则同 HttpHeaders 类的 add 函数。

    参数:

    • name: String - 请求头的 key。
    • value: String - 请求头的 value。

    返回值:

    异常:

    • HttpException - 如果传入的 name 或 value 包含不合法元素,将抛出此异常。

    func method(String)

    public func method(method: String): HttpRequestBuilder
    

    功能:设置请求 method,默认请求 method 为 "GET"。

    参数:

    • method: String - 请求方法,必须由 token 字符组成,如果传入空字符串,method 值将自动设置为 "GET"。

    返回值:

    异常:

    func options()

    public func options(): HttpRequestBuilder
    

    功能:构造 method 为 "OPTIONS" 的请求的便捷函数。

    返回值:

    func post()

    public func post(): HttpRequestBuilder
    

    功能:构造 method 为 "POST" 的请求的便捷函数。

    返回值:

    func priority(Int64, Bool)

    public func priority(urg: Int64, inc: Bool): HttpRequestBuilder
    

    功能:设置 priority 头的便捷函数,调用此函数后,将生成 priority 头,形如:"priority: urgency=x, i"。如果通过设置请求头的函数设置了 priority 字段,调用此函数无效。如果多次调用此函数,以最后一次为准。

    参数:

    • urg: Int64 - 表示请求优先级,取值范围为 0~7,0 表示最高优先级。
    • inc: Bool - 表示请求是否需要增量处理,为 true 表示希望服务器并发处理与之同 urg 同 inc 的请求,为 false 表示不希望服务器并发处理。

    返回值:

    func put()

    public func put(): HttpRequestBuilder
    

    功能:构造 method 为 "PUT" 的请求的便捷函数。

    返回值:

    func readTimeout(Duration)

    public func readTimeout(timeout: Duration): HttpRequestBuilder
    

    功能:设置此请求的读超时时间。如果传入的 Duration 为负,则会自动转为 0。如果用户设置了此读超时时间,那么该请求的读超时以此为准;如果用户没有设置,那么该请求的读超时以 Client 为准。

    参数:

    • timeout: Duration - 用户设置的此请求的读超时时间。

    返回值:

    func setHeaders(HttpHeaders)

    public func setHeaders(headers: HttpHeaders): HttpRequestBuilder
    

    功能:设置请求 header,如果已经设置过,调用该函数将替换原 header。

    参数:

    返回值:

    func setTrailers(HttpHeaders)

    public func setTrailers(trailers: HttpHeaders): HttpRequestBuilder
    

    功能:设置请求 trailer,如果已经设置过,调用该函数将替换原 trailer。

    参数:

    返回值:

    func trace()

    public func trace(): HttpRequestBuilder
    

    功能:构造 method 为 "TRACE" 的请求的便捷函数。

    返回值:

    func trailer(String, String)

    public func trailer(name: String, value: String): HttpRequestBuilder
    

    功能:向请求 trailer 添加指定键值对,规则同 HttpHeaders 类的 add 函数。

    参数:

    • name: String - 请求头的 key。
    • value: String - 请求头的 value。

    返回值:

    异常:

    • HttpException - 如果传入的 name 或 value 包含不合法元素,将抛出此异常。

    func url(String)

    public func url(rawUrl: String): HttpRequestBuilder
    

    功能:设置请求 url,默认 url 为空的 URL 对象。

    参数:

    • rawUrl: String - 待解析成 url 对象的字符串,该字符串格式详见 URL.parse 函数。

    返回值:

    异常:

    func url(URL)

    public func url(url: URL): HttpRequestBuilder
    

    功能:设置请求 url,默认 url 为空的 URL 对象,即 URL.parse("")。

    参数:

    • url: URL - URL 对象。

    返回值:

    func version(Protocol)

    public func version(version: Protocol): HttpRequestBuilder
    

    功能:设置请求的 http 协议版本,默认为 UnknownProtocol(""),客户端会根据 tls 配置自动选择协议。

    参数:

    返回值:

    func writeTimeout(Duration)

    public func writeTimeout(timeout: Duration): HttpRequestBuilder
    

    功能:设置此请求的写超时时间。如果传入的 Duration 为负,则会自动转为 0。如果用户设置了此写超时时间,那么该请求的写超时以此为准;如果用户没有设置,那么该请求的写超时以 Client 为准。

    参数:

    • timeout: Duration - 用户设置的此请求的写超时时间。

    返回值:

    class HttpResponse

    public class HttpResponse <: ToString
    

    功能:Http 响应类。

    此类定义了 http 中响应 Response 的相关接口,客户端用该类读取服务端返回的响应。

    父类型:

    prop body

    public prop body: InputStream
    

    功能:获取 body。

    注意:

    • body 不支持并发读取;
    • 默认 InputStream 实现类的 read 函数不支持多次读取。

    类型:InputStream

    prop bodySize

    public prop bodySize: Option<Int64>
    

    功能:获取响应 body 长度。

    • 如果未设置 body,则 bodySize 为 Some(0);
    • 如果 body 长度已知,即通过 Array<UInt8> 或 String 传入 body,或传入的 InputStream 有确定的 length (length >= 0),则 bodySize 为 Some(Int64);
    • 如果 body 长度未知,即通过用户自定义的 InputStream 实例传入 body 且 InputStream 实例没有确定的 length (length < 0),则 bodySize 为 None。

    类型:Option<Int64>

    prop close

    public prop close: Bool
    

    功能:表示该响应 header 是否包含 Connection: close。

    对于服务端,close 为 true 表示处理完该请求应该关闭连接;

    对于客户端,close 为 true 表示如果收到响应后服务端未关闭连接,客户端应主动关闭连接。

    类型:Bool

    prop headers

    public prop headers: HttpHeaders
    

    功能:获取 headers,headers 详述见 HttpHeaders 类,获取后,可通过调用 HttpHeaders 实例成员函数,修改该请求的 headers。

    类型:HttpHeaders

    prop request

    public prop request: Option<HttpRequest>
    

    功能:获取该响应对应的请求,默认为 None。

    类型:Option<HttpRequest>

    prop status

    public prop status: UInt16
    

    功能:获取响应的状态码,默认值为 200。状态码由 100~599 的三位数字组成,状态码所反映的具体信息可参考 RFC 9110

    类型:UInt16

    prop trailers

    public prop trailers: HttpHeaders
    

    功能:获取 trailers,trailers 详述见 HttpHeaders 类,获取后,可通过调用 HttpHeaders 实例成员函数,修改该请求的 trailers。

    类型:HttpHeaders

    prop version

    public prop version: Protocol
    

    功能:获取响应的协议版本,默认值为Http1_1。

    类型:Protocol

    func getPush()

    public func getPush(): ?ArrayList<HttpResponse>
    

    功能:获取服务器推送的响应,返回 None 代表未开启服务器推送功能,返回空 ArrayList 代表无服务器推送的响应。

    返回值:

    func toString()

    public override func toString(): String
    

    功能:把响应转换为字符串,包括 status-line,headers,body size, trailers。

    例如:HTTP/1.1 200 OK\r\ncontent-length: 5\r\n\r\nbody size: 5\r\nbar: foo\r\n。

    返回值:

    • String - 响应的字符串表示。

    class HttpResponseBuilder

    public class HttpResponseBuilder {
        public init()
    }
    

    功能:用于构造 HttpResponse 实例。

    init()

    public init()
    

    功能:构造一个新 HttpResponseBuilder

    func addHeaders(HttpHeaders)

    public func addHeaders(headers: HttpHeaders): HttpResponseBuilder
    

    功能:向响应 header 添加参数 HttpHeaders 中的键值对。

    参数:

    返回值:

    func addTrailers(HttpHeaders)

    public func addTrailers(trailers: HttpHeaders): HttpResponseBuilder
    

    功能:向响应 trailer 添加参数 HttpHeaders 中的键值对。

    参数:

    返回值:

    func body(Array<UInt8>)

    public func body(body: Array<UInt8>): HttpResponseBuilder
    

    功能:设置响应 body,如果已经设置过,调用该函数将替换原 body。

    参数:

    • body: Array<UInt8> - 字节数组形式的响应体。

    返回值:

    func body(InputStream)

    public func body(body: InputStream): HttpResponseBuilder
    

    功能:设置响应 body,如果已经设置过,调用该函数将替换原 body调用该函数设置请求 body。

    参数:

    返回值:

    func body(String)

    public func body(body: String): HttpResponseBuilder
    

    功能:设置响应 body,如果已经设置过,调用该函数将替换原 body调用该函数设置请求 body。

    参数:

    • body: String - 字符串形式的响应体。

    返回值:

    func build()

    public func build(): HttpResponse
    

    功能:根据 HttpResponseBuilder 实例生成一个 HttpResponse 实例。

    返回值:

    func header(String, String)

    public func header(name: String, value: String): HttpResponseBuilder
    

    功能:向响应 header 添加指定键值对,规则同 HttpHeaders 类的 add 函数。

    参数:

    • name: String - 响应头的 key。
    • value: String - 响应头的 value。

    返回值:

    异常:

    • HttpException - 如果传入的 name 或 value 包含不合法元素,将抛出此异常。

    func request(HttpRequest)

    public func request(request: HttpRequest): HttpResponseBuilder
    

    功能:设置响应对应的请求。

    参数:

    返回值:

    func setHeaders(HttpHeaders)

    public func setHeaders(headers: HttpHeaders): HttpResponseBuilder
    

    功能:设置响应 header,如果已经设置过,调用该函数将替换原 header。

    参数:

    返回值:

    func setTrailers(HttpHeaders)

    public func setTrailers(trailers: HttpHeaders): HttpResponseBuilder
    

    功能:设置响应 trailer,如果已经设置过,调用该函数将替换原 trailer。

    参数:

    返回值:

    func status(UInt16)

    public func status(status: UInt16): HttpResponseBuilder
    

    功能:设置 http 响应状态码。

    参数:

    • status: UInt16 - 传入的状态码的值。

    返回值:

    异常:

    • HttpException - 如果设置响应状态码不在 100~599 这个区间内,则抛出此异常。

    func trailer(String, String)

    public func trailer(name: String, value: String): HttpResponseBuilder
    

    功能:向响应 trailer 添加指定键值对,规则同 HttpHeaders 类的 add 函数。

    参数:

    • name: String - 响应头的 key。
    • value: String - 响应头的 value。

    返回值:

    异常:

    • HttpException - 如果传入的 name 或 value 包含不合法元素,将抛出此异常。

    func version(Protocol)

    public func version(version: Protocol): HttpResponseBuilder
    

    功能:设置 http 响应协议版本。

    参数:

    返回值:

    class HttpResponsePusher

    public class HttpResponsePusher
    

    功能:HTTP/2 服务器推送。

    说明:

    如果服务器收到请求后,认为客户端后续还需要某些关联资源,可以将其提前推送到客户端; 服务端推送包括推送请求和推送响应; 启用服务端推送需要先调用 push 函数发送推送请求,并向服务器注册该请求对应的 handler,用以生成推送响应; 客户端可设置拒绝服务端推送; 不允许嵌套推送,即不允许在推送请求对应的 handler 中再次推送。嵌套推送情况下,服务端将不执行推送,并打印日志进行提示。

    static func getPusher(HttpContext)

    public static func getPusher(ctx: HttpContext): ?HttpResponsePusher
    

    功能:获取 HttpResponsePusher 实例,如果客户端拒绝推送,将返回 None。

    参数:

    返回值:

    func push(String, String, HttpHeaders)

    public func push(path: String, method: String, header: HttpHeaders): Unit
    

    功能:向客户端发送推送请求,path 为请求地址,method 为请求方法,header 为请求头。

    参数:

    • path: String - 推送的请求地址。
    • method: String - 推送的请求方法。
    • header: HttpHeaders - 推送的请求头。

    class HttpResponseWriter

    public class HttpResponseWriter {
        public HttpResponseWriter(let ctx: HttpContext)
    }
    

    功能:HTTP response 消息体 Writer,支持用户控制消息体的发送过程。

    说明:

    第一次调用 write 函数时,将立即发送 header 和通过参数传入的 body,此后每次调用 write,发送通过参数传入的 body。 对于 HTTP/1.1,如果设置了 transfer-encoding: chunked,用户每调用一次 write,将发送一个 chunk。 对于 HTTP/2,用户每调用一次 write,将把指定数据封装并发出。

    HttpResponseWriter(HttpContext)

    public HttpResponseWriter(let ctx: HttpContext)
    

    功能:构造一个 HttpResponseWriter 实例。

    参数:

    func write(Array<Byte>)

    public func write(buf: Array<Byte>): Unit
    

    功能:发送 buf 中数据到客户端。

    参数:

    异常:

    class NotFoundHandler

    public class NotFoundHandler <: HttpRequestHandler {
        public init()
    }
    

    功能:便捷的 Http 请求处理器,404 Not Found 处理器。

    父类型:

    init()

    public init()
    

    功能:构造一个 NotFoundHandler 对象。

    func handle(HttpContext)

    public func handle(ctx: HttpContext): Unit
    

    功能:处理 Http 请求,回复 404 响应。

    参数:

    class OptionsHandler

    public class OptionsHandler <: HttpRequestHandler {
        public init()
    }
    

    功能:便捷的 Http 处理器,用于处理 OPTIONS 请求。固定返回 "Allow: OPTIONS,GET,HEAD,POST,PUT,DELETE" 响应头。

    父类型:

    init()

    public init()
    

    功能:构造一个 NotFoundHandler 对象。

    func handle(HttpContext)

    public func handle(ctx: HttpContext): Unit
    

    功能:处理 Http OPTIONS 请求。

    参数:

    class ProtocolService

    public abstract class ProtocolService
    

    功能:Http 协议服务实例,为单个客户端连接提供 Http 服务,包括对客户端 request 报文的解析、 request 的分发处理、 response 的发送等。

    prop server

    open protected mut prop server: Server
    

    功能:返回 Server 实例,提供默认实现,设置为绑定的 Server 实例

    func serve

    protected func serve(): Unit
    

    功能:处理来自客户端连接的请求,不提供默认实现。

    func closeGracefully

    open protected func closeGracefully(): Unit
    

    功能:优雅关闭连接,提供默认实现,无任何行为。

    func close

    open protected func close(): Unit
    

    功能:强制关闭连接,提供默认实现,无任何行为。

    class RedirectHandler

    public class RedirectHandler <: HttpRequestHandler
    

    功能:便捷的 Http 处理器,用于回复重定向响应。

    父类型:

    init(String, UInt16)

    public init(url: String, code: UInt16)
    

    功能:RedirectHandler 的构造函数。

    参数:

    • url: String - 重定向响应中 Location 头部的 url。
    • code: UInt16 - 重定向响应的响应码。

    异常:

    • HttpException - url 为空或响应码不是除 304 以外的 3XX 状态码时抛出异常。

    func handle(HttpContext)

    public func handle(ctx: HttpContext): Unit
    

    功能:处理 Http 请求,回复重定向响应。

    参数:

    class Server

    public class Server
    

    功能:提供 HTTP 服务的 Server 类。

    说明:

    • 启动服务,在指定地址及端口等待用户连接、服务用户的 http request;
    • 关闭服务,包括关闭所有已有连接;
    • 提供注册处理 http request 的 handler 的机制,根据注册信息分发 request 到相应的 handler;
    • 提供 tls 证书热机制;
    • 提供 shutdown 回调机制;
    • 通过 Logger.level 开启、关闭日志打印,包括按照用户要求打印相应级别的日志;
    • Server 文档中未明确说明支持版本的配置,在 HTTP/1.1 与 HTTP/2 都会生效。

    prop addr

    public prop addr: String
    

    功能:获取服务端监听地址,格式为 IP 或者 域名。

    类型:String

    prop distributor

    public prop distributor: HttpRequestDistributor
    

    功能:获取请求分发器,请求分发器会根据 url 将请求分发给对应的 handler。

    类型:HttpRequestDistributor

    prop enableConnectProtocol

    public prop enableConnectProtocol: Bool
    

    功能:HTTP/2 专用,用来限制对端发送的报文是否支持通过 connect 方法升级协议,true 表示支持。

    类型:Bool

    prop headerTableSize

    public prop headerTableSize: UInt32
    

    功能:获取服务端 HTTP/2 Hpack 动态表的初始值,默认值为 4096。

    类型:UInt32

    prop httpKeepAliveTimeout

    public prop httpKeepAliveTimeout: Duration
    

    功能:HTTP/1.1 专用,获取服务器设定的保持长连接的超时时间。

    类型:Duration

    prop initialWindowSize

    public prop initialWindowSize: UInt32
    

    功能:HTTP/2 专用,用来限制对端发送的报文stream 初始流量窗口大小。默认值为 65535 ,取值范围为 0 至 2^31 - 1。

    类型:UInt32

    prop listener

    public prop listener: ServerSocket
    

    功能:获取服务器绑定 socket。

    类型:ServerSocket

    prop logger

    public prop logger: Logger
    

    功能:获取服务器日志记录器,设置 logger.level 将立即生效,记录器应该是线程安全的。

    类型:Logger

    prop maxConcurrentStreams

    public prop maxConcurrentStreams: UInt32
    

    功能:HTTP/2 专用,用来限制连接同时处理的最大请求数量。

    类型:UInt32

    prop maxFrameSize

    public prop maxFrameSize: UInt32
    

    功能:HTTP/2 专用,用来限制对端发送的报文一个帧的最大长度。默认值为 16384. 取值范围为 2^14 至 2^24 - 1。

    类型:UInt32

    prop maxHeaderListSize

    public prop maxHeaderListSize: UInt32
    

    功能:获取客户端支持的 HTTP/2 最大头部(Header)大小。这个大小指的是响应头部中所有头部字段(Header Field)的最大允许长度之和,其中包括所有字段名称(name)的长度、字段值(value)的长度以及每个字段自动添加的伪头开销(通常每个字段会有32字节的开销,这包括了HTTP/2协议本身为头部字段添加的伪头部信息)。默认情况下,这个最大长度被设置为 UInt32.Max。

    类型:UInt32

    prop maxRequestBodySize

    public prop maxRequestBodySize: Int64
    

    功能:获取服务器设定的读取请求的请求体最大值,仅对于 HTTP/1.1 且未设置 "Transfer-Encoding: chunked" 的请求生效。

    类型:Int64

    prop maxRequestHeaderSize

    public prop maxRequestHeaderSize: Int64
    

    功能:获取服务器设定的读取请求的请求头最大值。仅对 HTTP/1.1 生效,HTTP/2 中有专门的配置 maxHeaderListSize。

    类型:Int64

    prop port

    public prop port: UInt16
    

    功能:获取服务端监听端口。

    类型:UInt16

    prop protocolServiceFactory

    public prop protocolServiceFactory: ProtocolServiceFactory
    

    功能:获取协议服务工厂,服务协议工厂会生成每个协议所需的服务实例。

    类型:ProtocolServiceFactory

    prop readHeaderTimeout

    public prop readHeaderTimeout: Duration
    

    功能:获取服务器设定的读取请求头的超时时间。

    类型:Duration

    prop readTimeout

    public prop readTimeout: Duration
    

    功能:获取服务器设定的读取整个请求的超时时间。

    类型:Duration

    prop servicePoolConfig

    public prop servicePoolConfig: ServicePoolConfig
    

    功能:获取协程池配置实例。

    类型:ServicePoolConfig

    prop transportConfig

    public prop transportConfig: TransportConfig
    

    功能:获取服务器设定的传输层配置。

    类型:TransportConfig

    prop writeTimeout

    public prop writeTimeout: Duration
    

    功能:获取服务器设定的写响应的超时时间。

    类型:Duration

    func afterBind(()->Unit)

    public func afterBind(f: ()->Unit): Unit
    

    功能:注册服务器启动时的回调函数,服务内部 ServerSocket 实例 bind 之后,accept 之前将调用该函数。重复调用将覆盖之前注册的函数。

    参数:

    • f: () ->Unit - 回调函数,入参为空,返回值为 Unit 类型。

    func close()

    public func close(): Unit
    

    功能:关闭服务器,服务器关闭后将不再对请求进行读取与处理,重复关闭将只有第一次生效(包括 close 和 closeGracefully)。

    func closeGracefully()

    public func closeGracefully(): Unit
    

    功能:关闭服务器,服务器关闭后将不再对请求进行读取,当前正在进行处理的服务器待处理结束后进行关闭。

    func getTlsConfig()

    public func getTlsConfig(): ?TlsServerConfig
    

    功能:获取服务器设定的 TLS 层配置。

    返回值:

    • ?TlsClientConfig - 客户端设定的 TLS 层配置,如果没有设置则返回 None。

    func onShutdown(()->Unit)

    public func onShutdown(f: ()->Unit): Unit
    

    功能:注册服务器关闭时的回调函数,服务器关闭时将调用该回调函数,重复调用将覆盖之前注册的函数。

    参数:

    • f: () ->Unit - 回调函数,入参为空,返回值为 Unit 类型。

    func serve()

    public func serve(): Unit
    

    功能:启动服务端进程,不支持重复启动。

    h1 request 检查和处理:

    • request-line 不符合 rfc9112 中 request-line = method SP request-target SP HTTP-version 的规则,将会返回 400 响应;
    • method 由 tokens 组成,且大小写敏感;request-target 为能够被解析的 url;HTTP-version 为 HTTP/1.0 或 HTTP/1.1 ,否则将会返回 400 响应;
    • headers name 和 value 需符合特定规则,详见 HttpHeaders 类说明,否则返回 400 响应;
    • 当 headers 的大小超出 server 设定的 maxRequestHeaderSize 时将自动返回 431 响应;
    • headers 中必须包含 "host" 请求头,且值唯一,否则返回 400 响应headers 中不允许同时存在 "content-length" 与 "transfer-encoding" 请求头,否则返回 400 响应;
    • 请求头 "transfer-encoding" 的 value 经过 "," 分割后最后一个 value 必须为 "chunked",且之前的 value 不允许存在 "chunked",否则返回 400 响应;
    • 请求头 "content-length" 其 value 必须能解析为 Int64 类型,且不能为负值,否则返回 400 响应,当其 value 值超出 server 设定maxRequestBodySize,将返回 413 响应;
    • headers 中若不存在 "content-length" 和 "transfer-encoding: chunked" 时默认不存在 body;
    • 请求头 "trailer" 中,value 不允许存在 "transfer-encoding","trailer","content-length";
    • 请求头 "expect" 中,value 中存在非 "100-continue" 的值,将会返回 417 响应;
    • HTTP/1.0 默认短连接,若想保持长连接需要包含请求头 "connection: keep-alive" 与 "keep-alive: timeout = XX, max = XX",将会自动保持 timeout 时长的连接。HTTP/1.1 默认长连接,当解析 request 失败则关闭连接;
    • 仅允许在 chunked 模式下存在 trailer,且 trailer 中条目的 name 必须被包含在 "trailer" 请求头中,否则将自动删除。

    h1 response 检查和处理:

    • 若用户不对 response 进行配置,将会自动返回 200 响应;
    • 若接收到的 request 包含请求头 "connection: close" 而配置 response 未添加响应头 "connection" 或响应头 "connection" 的 value 不包含 "close",将自动添加 "connection: close",若接收到的 request 不包含请求头 "connection: close" 且响应头不存在 "connection: keep-alive",将会自动添加;
    • 如果 headers 包含逐跳响应头:"proxy-connection","keep-alive","te","transfer-encoding","upgrade",将会在响应头 "connection" 自动添加这些头作为 value;
    • 将自动添加 "date" 响应头,用户提供的 "date" 将被忽略;
    • 若请求方法为 "HEAD" 或响应状态码为 "1XX\204\304",body将配置为空;
    • 若已知提供 body 的长度时,将会与响应头 "content-length" 进行比较,若不存在响应头 "content-length",将自动添加此响应头,其 value 值为 body 长度。若响应头 "content-length" 长度大于 body 长度,将会在 handler 中抛出 HttpException,若小于 body 长度,将对 body 进行截断处理,发送的 body 长度将为 "content-length" 的值;
    • response 中 "set-cookie" header 将分条发送,其他 headers 同名条目将合成一条发送;
    • 在处理包含请求头:"expect: 100-continue" 的 request 时,在调用 request 的 body.read() 时将会自动发送状态码为 100 的响应给客户端。不允许用户主动发送状态码为 100 的 response,若进行发送则被认定为服务器异常。

    启用 h2 服务:tlsConfig 中 supportedAlpnProtocols 需包含 "h2",此后如果 tls 层 alpn 协商结果为 h2,则启用 h2 服务。

    h2 request 检查和处理:

    • headers name 和 value 需符合特定规则,详见 HttpHeaders 类说明,此外 name 不能包含大写字符,否则发送 RST 帧关闭流,即无法保证返回响应;
    • trailers name 和 value 需符合同样规则,否则关闭流;
    • headers 不能包含 "connection","transfer-encoding","keep-alive","upgrade","proxy-connection",否则关闭流;
    • 如果有 "te" header,其值只能为 "trailers",否则关闭流;
    • 如果有 "host" header 和 ":authority" pseudo header,"host" 值必须与 ":authority" 一致,否则关闭流;
    • 如果有 "content-length" header,需符合 "content-length" 每个值都能解析为 Int64 类型,且如果有多个值,必须相等,否则关闭流;
    • 如果有 "content-length" header,且有 body 大小,则 content-length 值与 body 大小必须相等,否则关闭流;
    • 如果有 "trailer" header,其值不能包含 "transfer-encoding","trailer","content-length",否则关闭流;
    • 仅在升级 WebSocket 场景下支持 CONNECT 方法,否则关闭流;
    • pseudo headers 中,必须包含 ":method"、":scheme"、":path",其中 ":method" 值必须由 tokens 字符组成,":scheme" 值必须为 "https",":path" 不能为空,否则关闭流;
    • trailer 中条目的 name 必须被包含在 "trailer" 头中,否则将自动删除;
    • request headers 大小不能超过 maxHeaderListSize,否则关闭连接。

    h2 response 检查和处理:

    • 如果 HEAD 请求的响应包含 body,将自动删除;
    • 将自动添加 "date" field,用户提供的 "date" 将被忽略;
    • 如果 headers 包含 "connection","transfer-encoding","keep-alive","upgrade","proxy-connection",将自动删除;
    • response 中 "set-cookie" header 将分条发送,其他 headers 同名条目将合成一条发送;
    • 如果 headers 包含 "content-length",且 method 不为 "HEAD","content-length" 将被删除;
    • 如果 method 为 "HEAD",则:
      • headers 包含 "content-length",但 "content-length" 不合法(无法被解析为 Int64 值,或包含多个不同值),如果用户调用 HttpResponseWriter 类的 write 函数,将抛出 HttpException,如果用户 handler 已经结束,将打印日志;
      • headers 包含 "content-length",同时 response.body.length 不为 -1,"content-length" 值与 body.length 不符,同 6.1 处理;
      • headers 包含 "content-length",同时 response.body.length 为 -1,或 body.length 与 "content-length" 值一致,则保留 "content-length" header;
    • trailer 中条目必须被包含在 "trailer" 头中,否则将自动删除;
    • 如果 handler 中抛出异常,且用户未调用 write 发送部分响应,将返回 500 响应。如果用户已经调用 write 发送部分响应,将发送 RST 帧关闭 stream。

    h2 server 发完 response 之后,如果 stream 状态不是 CLOSED,会发送带 NO_ERROR 错误码的 RST 帧关闭 stream,避免已经处理完毕的 stream 继续占用服务器资源。

    h2 流量控制:

    • connection 流量窗口初始值为 65535,每次收到 DATA 帧将返回一个 connection 层面的 WINDOW-UPDATE,发送 DATA 时,如果 connection 流量窗口值为负数,将阻塞至其变为正数;
    • stream 流量窗口初始值可由用户设置,默认值为 65535,每次收到 DATA 帧将返回一个 stream 层面的 WINDOW-UPDATE,发送 DATA 时,如果 stream 流量窗口值为负数,将阻塞至其变为正数。

    h2 请求优先级:

    • 支持按 urgency 处理请求,h2 服务默认并发处理请求,当并发资源不足时,请求将按 urgency 处理,优先级高的请求优先处理。

    默认 ProtocolServiceFactory 协议选择:

    • 如果连接是 tcp,使用 HTTP/1.1 server;
    • 如果连接是 tls,根据 alpn 协商结果确定 http 协议版本,如果协商结果为 "http/1.0","http/1.1" 或 "",使用 HTTP/1.1 server,如果协商结果为 "h2",使用 HTTP/2 server,否则不处理此次请求,打印日志关连接。

    异常:

    func updateCA(Array<X509Certificate>)

    public func updateCA(newCa: Array<X509Certificate>): Unit
    

    功能:对 CA 证书进行热更新。

    参数:

    异常:

    func updateCA(String)

    public func updateCA(newCaFile: String): Unit
    

    功能:对 CA 证书进行热更新。

    参数:

    • newCaFile: String - CA证书文件。

    异常:

    func updateCert(Array<X509Certificate>, PrivateKey)

    public func updateCert(certChain: Array<X509Certificate>, certKey: PrivateKey): Unit
    

    功能:对 TLS 证书进行热更新。

    参数:

    异常:

    func updateCert(String, String)

    public func updateCert(certificateChainFile: String, privateKeyFile: String): Unit
    

    功能:对 TLS 证书进行热更新。

    参数:

    • certificateChainFile: String - 证书链文件。
    • privateKeyFile: String - 证书匹配的私钥文件。

    异常:

    class ServerBuilder

    public class ServerBuilder {
        public init()
    }
    

    功能:提供 Server 实例构建器。

    支持通过如下参数构造一个 Http Server

    • 地址、端口;
    • 线程安全的 logger;
    • HttpRequestDistributor,用于注册 handler、分发 request;
    • HTTP/2 的 settings;
    • shutdown 回调;
    • transport:listener、连接及其配置;
    • protocol service:http 协议解析服务;

    除地址端口、shutdown 回调外,均提供默认实现,用户在构造 server 过程中可不指定其他构建参数。 ServerBuilder 文档中未明确说明支持版本的配置,在 HTTP/1.1 与 HTTP/2 都会生效。

    init()

    public init()
    

    功能:创建 ServerBuilder 实例。

    func addr(String)

    public func addr(addr: String): ServerBuilder
    

    功能:设置服务端监听地址,若 listener 被设定,此值被忽略。

    参数:

    • addr: String - 地址值,格式为 IP 或者 域名。

    返回值:

    func afterBind(()->Unit)

    public func afterBind(f: ()->Unit): ServerBuilder
    

    功能:注册服务器启动时的回调函数,服务内部 ServerSocket 实例 bind 之后,accept 之前将调用该函数。重复调用将覆盖之前注册的函数。

    参数:

    • f: () ->Unit - 回调函数,入参为空,返回值为 Unit 类型。

    返回值:

    func build()

    public func build(): Server
    

    功能:根据设置的属性构建 Server 实例。

    返回值:

    异常:

    func distributor(HttpRequestDistributor)

    public func distributor(distributor: HttpRequestDistributor): ServerBuilder
    

    功能:设置请求分发器,请求分发器会根据 url 将请求分发给对应的 handler。不设置时使用默认请求分发器。

    参数:

    返回值:

    func enableConnectProtocol(Bool)

    public func enableConnectProtocol(flag: Bool): ServerBuilder
    

    功能:HTTP/2 专用,设置本端是否接收 CONNECT 请求,默认 false。

    参数:

    • flag: Bool - 本端是否接收 CONNECT 请求。

    返回值:

    func headerTableSize(UInt32)

    public func headerTableSize(size: UInt32): ServerBuilder
    

    功能:设置服务端 HTTP/2 Hpack 动态表的初始值,默认值为 4096。

    参数:

    • size: UInt32 - 本端对响应头编码时使用的最大 table size

    返回值:

    func httpKeepAliveTimeout(Duration)

    public func httpKeepAliveTimeout(timeout: Duration): ServerBuilder
    

    功能:HTTP/1.1 专用,设定服务端连接保活时长,该时长内客户端未再次发送请求,服务端将关闭长连接,默认不进行限制。

    参数:

    • timeout: Duration - 设定保持长连接的超时时间,如果传入负的 Duration 将被替换为 Duration.Zero。

    返回值:

    func initialWindowSize(UInt32)

    public func initialWindowSize(size: UInt32): ServerBuilder
    

    功能:HTTP/2 专用,设置当前服务器上每个流的接收报文的初始流量窗口大小,默认值为 65535。取值范围为 0 至 2^31 - 1。

    参数:

    • size: UInt32 - 本端一个 stream 上接收报文的初始流量窗口大小。

    返回值:

    func listener(ServerSocket)

    public func listener(listener: ServerSocket): ServerBuilder
    

    功能:服务端调用此函数对指定 socket 进行绑定监听。

    参数:

    返回值:

    func logger(Logger)

    public func logger(logger: Logger): ServerBuilder
    

    功能:设定服务器的 logger,默认 logger 级别为 INFO,logger 内容将写入 Console.stdout。

    参数:

    • logger: Logger - 需要是线程安全的,默认使用内置线程安全 logger。

    返回值:

    func maxConcurrentStreams(UInt32)

    public func maxConcurrentStreams(size: UInt32): ServerBuilder
    

    功能:HTTP/2 专用,设置本端同时处理的最大请求数量,限制对端并发发送请求的数量,默认值为 100。

    参数:

    • size: UInt32 - 本端同时处理的最大请求数量。

    返回值:

    func maxFrameSize(UInt32)

    public func maxFrameSize(size: UInt32): ServerBuilder
    

    功能:HTTP/2 专用,设置本端接收的一个帧的最大长度,用来限制对端发送帧的长度,默认值为 16384. 取值范围为 2^14 至 2^24 - 1。

    参数:

    • size: UInt32 - 本端接收的一个帧的最大长度。

    返回值:

    func maxHeaderListSize(UInt32)

    public func maxHeaderListSize(size: UInt32): ServerBuilder
    

    功能:获取客户端支持的 HTTP/2 最大头部(Header)大小。这个大小指的是响应头部中所有头部字段(Header Field)的最大允许长度之和,其中包括所有字段名称(name)的长度、字段值(value)的长度以及每个字段自动添加的伪头开销(通常每个字段会有32字节的开销,这包括了HTTP/2协议本身为头部字段添加的伪头部信息)。默认情况下,这个最大长度被设置为 UInt32.Max。

    参数:

    • size: UInt32 - 本端接收的报文头最大长度。

    返回值:

    func maxRequestBodySize(Int64)

    public func maxRequestBodySize(size: Int64): ServerBuilder
    

    功能:设置服务端允许客户端发送单个请求的请求体最大长度,请求体长度超过该值时,将返回状态码为 413 的响应。默认值为 2M。仅对于 HTTP/1.1 且未设置 "Transfer-Encoding: chunked" 的请求生效。

    参数:

    • size: Int64 - 设定允许接收请求的请求体大小最大值,值为 0 代表不作限制。

    返回值:

    异常:

    func maxRequestHeaderSize(Int64)

    public func maxRequestHeaderSize(size: Int64): ServerBuilder
    

    功能:设定服务端允许客户端发送单个请求的请求头最大长度,请求头长度超过该值时,将返回状态码为 431 的响应;仅对 HTTP/1.1 生效,HTTP/2 中有专门的配置 maxHeaderListSize。

    参数:

    • size: Int64 - 设定允许接收请求的请求头大小最大值,值为 0 代表不作限制。

    返回值:

    异常:

    func onShutdown(()->Unit)

    public func onShutdown(f: ()->Unit): ServerBuilder
    

    功能:注册服务器关闭时的回调函数,服务器关闭时将调用该回调函数,重复调用将覆盖之前注册的函数。

    参数:

    • f: () ->Unit - 回调函数,入参为空,返回值为 Unit 类型。

    返回值:

    func port(UInt16)

    public func port(port: UInt16): ServerBuilder
    

    功能:设置服务端监听端口,若 listener 被设定,此值被忽略。

    参数:

    返回值:

    func protocolServiceFactory(ProtocolServiceFactory)

    public func protocolServiceFactory(factory: ProtocolServiceFactory): ServerBuilder
    

    功能:设置协议服务工厂,服务协议工厂会生成每个协议所需的服务实例,不设置时使用默认工厂。

    参数:

    返回值:

    func readHeaderTimeout(Duration)

    public func readHeaderTimeout(timeout: Duration): ServerBuilder
    

    功能:设定服务端读取客户端发送一个请求的请求头最大时长,超过该时长将不再进行读取并关闭连接,默认不进行限制。

    参数:

    返回值:

    func readTimeout(Duration)

    public func readTimeout(timeout: Duration): ServerBuilder
    

    功能:设定服务端读取一个请求的最大时长,超过该时长将不再进行读取并关闭连接,默认不进行限制。

    参数:

    • timeout: Duration - 设定读请求的超时时间,如果传入时间为负值将被替换为 Duration.Zero。

    返回值:

    func servicePoolConfig(ServicePoolConfig)

    public func servicePoolConfig(cfg: ServicePoolConfig): ServerBuilder
    

    功能:服务过程中使用的协程池相关设置,具体说明见 ServicePoolConfig 结构体。

    参数:

    返回值:

    func tlsConfig(TlsServerConfig)

    public func tlsConfig(config: TlsServerConfig): ServerBuilder
    

    功能:设置 TLS 层配置,默认不对其进行设置。

    参数:

    • config: TlsServerConfig - 设定支持 tls 服务所需要的配置信息。

    返回值:

    func transportConfig(TransportConfig)

    public func transportConfig(config: TransportConfig): ServerBuilder
    

    功能:设置传输层配置,默认配置详见 TransportConfig 结构体说明。

    参数:

    返回值:

    func writeTimeout(Duration)

    public func writeTimeout(timeout: Duration): ServerBuilder
    

    功能:设定服务端发送一个响应的最大时长,超过该时长将不再进行写入并关闭连接,默认不进行限制。

    参数:

    • timeout: Duration - 设定写响应的超时时间,如果传入时间为负值将被替换为 Duration.Zero。

    返回值:

    class WebSocket

    public class WebSocket
    

    功能:提供 WebSocket 服务的相关类,提供 WebSocket 连接的读、写、关闭等函数。用户通过 upgradeFrom 函数以获取 WebSocket 连接。

    • 调用 read() 读取一个 WebSocketFrame,用户可通过 WebSocketFrame.frameType 来知晓帧的类型,通过 WebSocketFrame.fin 来知晓是否是分段帧。
    • 调用 write(frameType: WebSocketFrameType, byteArray: Array<UInt8>),传入 message 的类型和 message 的 byte 来发送 WebSocket 信息,如果写的是控制帧,则不会分段发送,如果写的是数据帧(Text、Binary),则会将 message 按底层 buffer 的大小分段(分成多个 fragment)发送。

    详细说明见下文接口说明,接口行为以 RFC 6455 为准。

    prop logger

    public prop logger: Logger
    

    功能:日志记录器。

    类型:Logger

    prop subProtocol

    public prop subProtocol: String
    

    功能:获取与对端协商到的 subProtocol,协商时,客户端提供一个按偏好排名的 subProtocols 列表,服务器从中选取一个或零个子协议。

    类型:String

    static func upgradeFromClient(Client, URL, Protocol, ArrayList<String>, HttpHeaders)

    public static func upgradeFromClient(client: Client, url: URL,
     version!: Protocol = HTTP1_1,
     subProtocols!: ArrayList<String> = ArrayList<String>(), 
     headers!: HttpHeaders = HttpHeaders()): (WebSocket, HttpHeaders)
    

    功能:提供客户端升级到 WebSocket 协议的函数。

    说明:

    客户端的升级流程为:传入 client 对象,url 对象,构建升级请求,请求服务器后验证其响应,如果握手成功,则返回 WebSocket 对象用于 WebSocket 通讯,并返回 101 响应头的 HttpHeaders 对象给用户。暂不支持 extensions如果子协议协商成功,用户可通过调用返回的 WebSocket 的 subProtocol 查看子协议。

    参数:

    • client: Client - 用于请求的 client 对象。
    • version!: Protocol - 创建 socket 使用的 HTTP 版本,只支持 HTTP1_1 和 HTTP2_0 向 WebSocket 升级。
    • url: URL - 用于请求的 url 对象,WebSocket 升级时要注意 url 的 scheme 为 ws 或 wss。
    • subProtocols!: ArrayList<String> - 用户配置的子协议列表,按偏好排名,默认为空。若用户配置了,则会随着升级请求发送给服务器。
    • headers!: HttpHeaders - 需要随着升级请求一同发送的非升级必要头,如 cookie 等。

    返回值:

    • (WebSocket, HttpHeaders) - 升级成功,则返回 WebSocket 对象用于通讯和 101 响应的头。

    异常:

    static func upgradeFromServer(HttpContext, ArrayList<String>, ArrayList<String>, (HttpRequest) -> HttpHeaders)

    public static func upgradeFromServer(ctx: HttpContext, subProtocols!: ArrayList<String> = ArrayList<String>(), 
                                            origins!: ArrayList<String> = ArrayList<String>(), 
                                            userFunc!:(HttpRequest) -> HttpHeaders = {_: HttpRequest => HttpHeaders()}): WebSocket
    

    功能:提供服务端升级到 WebSocket 协议的函数,通常在 handler 中使用。

    服务端升级的流程为:收到客户端发来的升级请求,验证请求,如果验证通过,则回复 101 响应并返回 WebSocket 对象用于 WebSocket 通讯。

    • 用户通过 subProtocols,origins 参数来配置其支持的 subprotocol 和 origin 白名单,subProtocols如果不设置,则表示不支持子协议,origins 如果不设置,则表示接受所有 origin 的握手请求;
    • 用户通过 userFunc 来自定义处理升级请求的行为,如处理 cookie 等,传入的 userFunc 要求返回一个 HttpHeaders 对象,其会通过 101 响应回给客户端(升级失败的请求则不会);
    • 暂不支持 WebSocket 的 extensions,因此如果握手过程中出现 extensions 协商则会抛 WebSocketException
    • 只支持 HTTP1_1 和 HTTP2_0 向 WebSocket 升级。

    参数:

    • ctx: HttpContext - Http 请求上下文,将传入给 handler 的直接传给 upgradeFromServer 即可。
    • subProtocols!: ArrayList<String> - 用户配置的子协议列表,默认值为空,表示不支持。如果用户配置了,则会选取升级请求中最靠前的作为升级后的 WebSocket 的子协议,用户可通过调用返回的 WebSocket 的 subProtocol 查看子协议。
    • origins!: ArrayList<String> - 用户配置的同意握手的 origin 的白名单,如果不配置,则同意来自所有 origin 的握手,如果配置了,则只接受来自配置 origin 的握手。
    • userFunc!: (HttpRequest) ->HttpHeaders - 用户配置的自定义处理升级请求的函数,该函数返回一个 HttpHeaders

    返回值:

    func closeConn()

    public func closeConn(): Unit
    

    功能:提供关闭底层 WebSocket 连接的函数。

    说明:

    直接关闭底层连接。正常的关闭流程需要遵循协议规定的握手流程,即先发送 Close 帧给对端,并等待对端回应的 Close 帧。握手流程结束后方可关闭底层连接。

    func read()

    public func read(): WebSocketFrame
    

    功能:从连接中读取一个帧,如果连接上数据未就绪会阻塞,非线程安全(即对同一个 WebSocket 对象不支持多线程读)。

    read 函数返回一个 WebSocketFrame 对象,用户可以调用 WebSocketFrame 的 frameType,fin 属性确定其帧类型和是否是分段帧调用。通过 WebSocketFrame 的 payload 函数得到原始二进制数据数组:Array<UInt8>

    • 分段帧的首帧为 fin == false,frameType == TextWebFrame 或 BinaryWebFrame中间帧 fin == false,frameType == ContinuationWebFrame尾帧 fin == true, frameType == ContinuationWebFrame;
    • 非分段帧为 fin == true, frameType != ContinuationWebFrame。

    注意:

    • 数据帧(Text,Binary)可以分段,用户需要多次调用 read 将所有分段帧读完(以下称为接收到完整的 message),再将分段帧的 payload 按接收序拼接Text 帧的 payload 为 UTF-8 编码,用户在接收到完整的 message 后,调用 String.fromUtf8函数将拼接后的 payload 转成字符串Binary 帧的 payload 的意义由使用其的应用确定,用户在接收到完整的 message 后,将拼接后的 payload 传给上层应用;
    • 控制帧(Close,Ping,Pong)不可分段;
    • 控制帧本身不可分段,但其可以穿插在分段的数据帧之间。分段的数据帧之间不可出现其他数据帧,如果用户收到穿插的分段数据帧,则需要当作错误处理;
    • 客户端收到 masked 帧,服务器收到 unmasked 帧,断开底层连接并抛出异常;
    • rsv1、rsv2、rsv3 位被设置(暂不支持 extensions,因此 rsv 位必须为 0),断开底层连接并抛出异常;
    • 收到无法理解的帧类型(只支持 Continuation,Text,Binary,Close,Ping,Pong),断开底层连接并抛出异常;
    • 收到分段或 payload 长度大于 125 bytes 的控制帧(Close,Ping,Pong),断开底层连接并抛出异常;
    • 收到 payload 长度大于 20M 的帧,断开底层连接并抛出异常;
    • closeConn 关闭连接后继续调用读,抛出异常。

    返回值:

    异常:

    • SocketException - 底层连接错误。
    • WebSocketException - 收到不符合协议规定的帧,此时会给对端发送 Close 帧说明错误信息,并断开底层连接。
    • ConnectionException - 从连接中读数据时对端已关闭连接抛此异常。

    func write(WebSocketFrameType, Array<UInt8>, Int64)

    public func write(frameType: WebSocketFrameType, byteArray: Array<UInt8>, frameSize!: Int64 = FRAMESIZE): Unit
    

    功能:发送数据,非线程安全(即对同一个 WebSocket 对象不支持多线程写)。

    注意:

    write 函数将数据以 WebSocket 帧的形式发送给对端;

    • 如果发送数据帧(Text,Binary),传入的 byteArray 如果大于 frameSize (默认 4 * 1024 bytes),我们会将其分成小于等于 frameSize 的 payload 以分段帧的形式发送,否则不分段;
    • 如果发送控制帧(Close,Ping,Pong),传入的 byteArray 的大小需要小于等于 125 bytes,Close 帧的前两个字节为状态码,可用的状态码见 RFC 6455 7.4. Status Codes协议规定,Close 帧发送之后,禁止再发送数据帧,如果发送则会抛出异常;
    • 用户需要自己保证其传入的 byteArray 符合协议,如 Text 帧的 payload 需要是 UTF-8 编码,如果数据帧设置了 frameSize,那么需要大于 0,否则抛出异常;
    • 发送数据帧时,frameSize 小于等于 0,抛出异常;
    • 用户发送控制帧时,传入的数据大于 125 bytes,抛出异常;
    • 用户传入非 Text,Binary,Close,Ping,Pong 类型的帧类型,抛出异常;
    • 发送 Close 帧时传入非法的状态码,或 reason 数据超过 123 bytes,抛出异常;
    • 发送完 Close 帧后继续发送数据帧,抛出异常;
    • closeConn 关闭连接后调用写,抛出异常。

    参数:

    • frameType: WebSocketFrameType - 所需发送的帧的类型。
    • byteArray: Array<UInt8> - 所需发送的帧的 payload(二进制形式)。
    • frameSize!: Int64 - 分段帧的大小,默认为 4 * 1024 bytes,frameSize 不会对控制帧生效(控制帧设置了无效)。

    异常:

    func writeCloseFrame(?UInt16, String)

    public func writeCloseFrame(status!: ?UInt16 = None, reason!: String = ""): Unit
    

    功能:发送 Close 帧。

    注意:

    协议规定,Close 帧发送之后,禁止再发送数据帧。如果用户不设置 status,那么 reason 不会被发送(即有 reason 必有 status);控制帧的 payload 不超过 125 bytes,Close 帧的前两个 bytes 为 status,因此 reason 不能超过 123 bytes,closeConn 关闭连接后调用写,抛出异常。

    参数:

    • status!: ?UInt16 - 发送的 Close 帧的状态码,默认为 None,表示不发送状态码和 reason。
    • reason!: String - 关闭连接的说明,默认为空字符串,发送时会转成 UTF-8,不保证可读,debug 用。

    异常:

    • WebSocketException - 传入非法的状态码,或 reason 数据超过 123 bytes时抛出异常。

    func writePingFrame(Array<UInt8>)

    public func writePingFrame(byteArray: Array<UInt8>): Unit
    

    功能:提供发送 Ping 帧的快捷函数,closeConn 关闭连接后调用写,抛出异常。

    参数:

    • byteArray: Array<UInt8> - 所需发送的帧的 payload(二进制形式)。

    异常:

    func writePongFrame(Array<UInt8>)

    public func writePongFrame(byteArray: Array<UInt8>): Unit
    

    功能:提供发送 Pong 帧的快捷函数,closeConn 关闭连接后调用写,抛出异常。

    参数:

    • byteArray: Array<UInt8> - 所需发送的帧的 payload(二进制形式)。

    异常:

    class WebSocketFrame

    public class WebSocketFrame
    

    功能:WebSocket 用于读的基本单元。

    WebSocketFrame 提供了三个属性,其中 fin 和 frameType 共同说明了帧是否分段和帧的类型。payload 为帧的载荷。

    • 分段帧的首帧为 fin == false,frameType == TextWebFrame 或 BinaryWebFrame;
    • 中间帧 fin == false,frameType == ContinuationWebFrame;
    • 尾帧 fin == true, frameType == ContinuationWebFrame;
    • 非分段帧为 fin == true, frameType != ContinuationWebFrame;
    • 用户仅能通过 WebSocket 对象的 read 函数得到 WebSocketFrame。数据帧可分段,如果用户收到分段帧,则需要多次调用 read 函数直到收到完整的 message,并将所有分段的 payload 按接收顺序拼接。

    注意:

    由于控制帧可以穿插在分段帧之间,用户在拼接分段帧的 payload 时需要单独处理控制帧。分段帧之间仅可穿插控制帧,如果用户在分段帧之间接收到其他数据帧,则需要当作错误处理。

    prop fin

    public prop fin: Bool
    

    功能:获取 WebSocketFrame 的 fin 属性,fin 与 frameType 共同说明了帧是否分段和帧的类型。

    类型:Bool

    prop frameType

    public prop frameType: WebSocketFrameType
    

    功能:获取 WebSocketFrame 的帧类型,fin 与 frameType 共同说明了帧是否分段和帧的类型。

    类型:WebSocketFrameType

    prop payload

    public prop payload: Array<UInt8>
    

    功能:获取 WebSocketFrame 的帧载荷。如果是分段数据帧,用户需要在接收到完整的 message 后,将所有分段的 payload 按接收序拼接。

    类型:Array<UInt8>

    枚举

    enum FileHandlerType

    public enum FileHandlerType {
        | DownLoad
        | UpLoad
    }
    

    功能:用于设置 FileHandler 是上传还是下载模式。

    DownLoad

    DownLoad
    

    功能:设置 FileHandler 为下载模式。

    UpLoad

    UpLoad
    

    功能:设置 FileHandler 为上传模式。

    enum Protocol

    public enum Protocol <: Equatable<Protocol> & ToString {
        | HTTP1_0
        | HTTP1_1
        | HTTP2_0
        | UnknownProtocol(String)
    }
    

    功能:定义 HTTP 协议类型枚举。

    父类型:

    HTTP1_0

    HTTP1_0
    

    功能:定义 1.0 版本 HTTP 协议。

    HTTP1_1

    HTTP1_1
    

    功能:定义 1.1 版本 HTTP 协议。

    HTTP2_0

    HTTP2_0
    

    功能:定义 2.0 版本 HTTP 协议。

    UnknownProtocol(String)

    UnknownProtocol(String)
    

    功能:定义未知 HTTP 协议。

    func toString()

    public override func toString(): String
    

    功能:获取 Http 协议版本字符串。

    返回值:

    • String - Http 协议版本字符串。

    operator func != (Protocol)

    public override operator func != (that: Protocol): Bool
    

    功能:判断枚举值是否不相等。

    参数:

    • that: Protocol - 被比较的枚举值。

    返回值:

    • Bool - 当前实例与 that 不等,返回 true;否则返回 false

    operator func == (Protocol)

    public override operator func == (that: Protocol): Bool
    

    功能:判断枚举值是否相等。

    参数:

    • that: Protocol - 被比较的枚举值。

    返回值:

    • Bool - 当前实例与 that 相等,返回 true;否则返回 false

    enum WebSocketFrameType

    public enum WebSocketFrameType <: Equatable<WebSocketFrameType> & ToString {
        | ContinuationWebFrame
        | TextWebFrame
        | BinaryWebFrame
        | CloseWebFrame
        | PingWebFrame
        | PongWebFrame
        | UnknownWebFrame
    }
    

    功能:定义 WebSocketFrame 的枚举类型。

    父类型:

    ContinuationWebFrame

    ContinuationWebFrame
    

    功能:定义 websocket 协议中的未结束的分片帧。

    TextWebFrame

    TextWebFrame
    

    功能:定义 websocket 协议中的文本帧。

    BinaryWebFrame

    BinaryWebFrame
    

    功能:定义 websocket 协议中的数据帧。

    CloseWebFrame

    CloseWebFrame
    

    功能:定义 websocket 协议中的关闭帧。

    PingWebFrame

    PingWebFrame
    

    功能:定义 websocket 协议中的心跳帧。

    PongWebFrame

    PongWebFrame
    

    功能:定义 websocket 协议中的心跳帧。

    UnknownWebFrame

    UnknownWebFrame
    

    功能:定义 websocket 协议中的未知类型帧。

    func toString()

    public override func toString(): String
    

    功能:获取 WebSocket 帧类型字符串。

    返回值:

    operator func != (WebSocketFrameType)

    public override operator func != (that: WebSocketFrameType): Bool
    

    功能:判断枚举值是否不相等。

    参数:

    返回值:

    • Bool - 当前实例与 that 不等返回 true,否则返回 false

    operator func == (WebSocketFrameType)

    public override operator func == (that: WebSocketFrameType): Bool
    

    功能:判断枚举值是否相等。

    参数:

    返回值:

    • Bool - 当前实例与 that 相等返回 true,否则返回 false

    结构体

    struct HttpStatusCode

    public struct HttpStatusCode
    

    功能:用来表示网页服务器超文本传输协议响应状态的 3 位数字代码。

    状态码由 RFC 9110 规范定义,并得到 RFC2518、RFC 3229、RFC 4918、RFC 5842、RFC 7168 与 RFC 8297 等规范扩展。

    所有状态码的第一个数字代表了响应的五种状态之一:

    • 状态代码的 1xx(信息)指示在完成请求的操作并发送最终响应之前通信连接状态或请求进度的临时响应。
    • 状态代码的 2xx(成功)指示客户端的请求已成功接收、理解和接受。
    • 状态代码的 3xx(重定向)指示用户代理需要采取进一步的操作才能完成请求。
    • 状态代码的 4xx(客户端错误)指示客户端似乎出错。
    • 状态代码的 5xx(服务器错误)指示服务器意识到它出错或无法执行请求的方法。

    static const STATUS_ACCEPTED

    public static const STATUS_ACCEPTED: UInt16 = 202
    

    功能:服务器已接受请求,但尚未处理。

    类型:Int64

    static const STATUS_ALREADY_REPORTED

    public static const STATUS_ALREADY_REPORTED: UInt16 = 208
    

    功能:消息体将是一个 XML 消息。

    类型:Int64

    static const STATUS_BAD_GATEWAY

    public static const STATUS_BAD_GATEWAY: UInt16 = 502
    

    功能:作为网关或者代理工作的服务器尝试执行请求时,从上游服务器接收到无效的响应。

    类型:Int64

    static const STATUS_BAD_REQUEST

    public static const STATUS_BAD_REQUEST: UInt16 = 400
    

    功能:语义有误,当前请求无法被服务器理解;或请求参数有误。

    类型:Int64

    static const STATUS_CONFLICT

    public static const STATUS_CONFLICT: UInt16 = 409
    

    功能:由于和被请求的资源的当前状态之间存在冲突,请求无法完成。

    类型:Int64

    static const STATUS_CONTINUE

    public static const STATUS_CONTINUE: UInt16 = 100
    

    功能:这个临时响应是用来通知客户端它的部分请求已经被服务器接收,且仍未被拒绝。

    类型:Int64

    说明:

    客户端应当继续发送请求的剩余部分,或者如果请求已经完成,忽略这个响应。 服务器必须在请求完成后向客户端发送一个最终响应。

    static const STATUS_CREATED

    public static const STATUS_CREATED: UInt16 = 201
    

    功能:请求已经被实现,而且有一个新的资源已经依据请求的需要而建立,且其 URI 已经随 Location 头信息返回。

    类型:Int64

    static const STATUS_EARLY_HINTS

    public static const STATUS_EARLY_HINTS: UInt16 = 103
    

    功能:提前预加载 (css、js) 文档。

    类型:Int64

    static const STATUS_EXPECTATION_FAILED

    public static const STATUS_EXPECTATION_FAILED: UInt16 = 417
    

    功能:服务器无法满足 Expect 的请求头信息。

    类型:Int64

    static const STATUS_FAILED_DEPENDENCY

    public static const STATUS_FAILED_DEPENDENCY: UInt16 = 424
    

    功能:由于之前的某个请求发生的错误,导致当前请求失败。

    类型:Int64

    static const STATUS_FORBIDDEN

    public static const STATUS_FORBIDDEN: UInt16 = 403
    

    功能:服务器已经理解请求,但是拒绝执行。

    类型:Int64

    static const STATUS_FOUND

    public static const STATUS_FOUND: UInt16 = 302
    

    功能:临时移动。

    类型:Int64

    说明:

    请求的资源已被临时的移动到新 URI,客户端应当继续向原有地址发送以后的请求。

    static const STATUS_GATEWAY_TIMEOUT

    public static const STATUS_GATEWAY_TIMEOUT: UInt16 = 504
    

    功能:从上游服务器(URI 标识出的服务器,例如 HTTP、FTP、LDAP)或者辅助服务器(例如 DNS)收到响应超时。

    类型:Int64

    static const STATUS_GONE

    public static const STATUS_GONE: UInt16 = 410
    

    功能:被请求的资源在服务器上已经不再可用,而且没有任何已知的转发地址。

    类型:Int64

    static const STATUS_HTTP_VERSION_NOT_SUPPORTED

    public static const STATUS_HTTP_VERSION_NOT_SUPPORTED: UInt16 = 505
    

    功能:服务器不支持,或者拒绝支持在请求中使用的 HTTP 版本。

    类型:Int64

    static const STATUS_IM_USED

    public static const STATUS_IM_USED: UInt16 = 226
    

    功能:服务器已完成对资源的请求,并且响应是应用于当前实例的一个或多个实例操作的结果的表示。

    类型:Int64

    static const STATUS_INSUFFICIENT_STORAGE

    public static const STATUS_INSUFFICIENT_STORAGE: UInt16 = 507
    

    功能:服务器无法存储完成请求所必须的内容。

    类型:Int64

    static const STATUS_INTERNAL_SERVER_ERROR

    public static const STATUS_INTERNAL_SERVER_ERROR: UInt16 = 500
    

    功能:服务器遇到了一个未曾预料的状况,导致了它无法完成对请求的处理。

    类型:Int64

    static const STATUS_LENGTH_REQUIRED

    public static const STATUS_LENGTH_REQUIRED: UInt16 = 411
    

    功能:服务器拒绝在没有定义 Content-Length 头的情况下接受请求。

    类型:Int64

    static const STATUS_LOCKED

    public static const STATUS_LOCKED: UInt16 = 423
    

    功能:当前资源被锁定。

    类型:Int64

    static const STATUS_LOOP_DETECTED

    public static const STATUS_LOOP_DETECTED: UInt16 = 508
    

    功能:服务器在处理请求时检测到无限递归。

    类型:Int64

    static const STATUS_METHOD_NOT_ALLOWED

    public static const STATUS_METHOD_NOT_ALLOWED: UInt16 = 405
    

    功能:请求行中指定的请求函数不能被用于请求响应的资源。

    类型:Int64

    static const STATUS_MISDIRECTED_REQUEST

    public static const STATUS_MISDIRECTED_REQUEST: UInt16 = 421
    

    功能:请求被指向到无法生成响应的服务器。

    类型:Int64

    static const STATUS_MOVED_PERMANENTLY

    public static const STATUS_MOVED_PERMANENTLY: UInt16 = 301
    

    功能:永久移动。

    类型:Int64

    说明:

    请求的资源已被永久的移动到新 URI,返回信息会包括新的 URI,浏览器会自动定向到新 URI。

    static const STATUS_MULTIPLE_CHOICES

    public static const STATUS_MULTIPLE_CHOICES: UInt16 = 300
    

    功能:被请求的资源有一系列可供选择的回馈信息,每个都有自己特定的地址和浏览器驱动的商议信息。

    类型:Int64

    说明:

    用户或浏览器能够自行选择一个首选的地址进行重定向。

    static const STATUS_MULTI_STATUS

    public static const STATUS_MULTI_STATUS: UInt16 = 207
    

    功能:DAV 绑定的成员已经在(多状态)响应之前的部分被列举,且未被再次包含。

    类型:Int64

    static const STATUS_NETWORK_AUTHENTICATION_REQUIRED

    public static const STATUS_NETWORK_AUTHENTICATION_REQUIRED: UInt16 = 511
    

    功能:要求网络认证。

    类型:Int64

    static const STATUS_NON_AUTHORITATIVE_INFO

    public static const STATUS_NON_AUTHORITATIVE_INFO: UInt16 = 203
    

    功能:服务器已成功处理了请求。

    类型:Int64

    说明:

    返回的实体头部元信息不是在原始服务器上有效的确定集合,而是来自本地或者第三方的拷贝。

    static const STATUS_NOT_ACCEPTABLE

    public static const STATUS_NOT_ACCEPTABLE: UInt16 = 406
    

    功能:请求的资源的内容特性无法满足请求头中的条件,因而无法生成响应实体。

    类型:Int64

    static const STATUS_NOT_EXTENDED

    public static const STATUS_NOT_EXTENDED: UInt16 = 510
    

    功能:获取资源所需要的策略并没有被满足。

    类型:Int64

    static const STATUS_NOT_FOUND

    public static const STATUS_NOT_FOUND: UInt16 = 404
    

    功能:请求失败,请求所希望得到的资源未被在服务器上发现。

    类型:Int64

    static const STATUS_NOT_IMPLEMENTED

    public static const STATUS_NOT_IMPLEMENTED: UInt16 = 501
    

    功能:服务器不支持当前请求所需要的某个功能。

    类型:Int64

    static const STATUS_NOT_MODIFIED

    public static const STATUS_NOT_MODIFIED: UInt16 = 304
    

    功能:请求的资源未修改,服务器返回此状态码时,不会返回任何资源。

    类型:Int64

    说明:

    客户端通常会缓存访问过的资源,通过提供一个头信息指出客户端希望只返回在指定日期之后修改的资源。

    static const STATUS_NO_CONTENT

    public static const STATUS_NO_CONTENT: UInt16 = 204
    

    功能:服务器成功处理,但未返回内容。

    类型:Int64

    static const STATUS_OK

    public static const STATUS_OK: UInt16 = 200
    

    功能:请求已经成功,请求所希望的响应头或数据体将随此响应返回。

    类型:Int64

    static const STATUS_PARTIAL_CONTENT

    public static const STATUS_PARTIAL_CONTENT: UInt16 = 206
    

    功能:服务器已经成功处理了部分 GET 请求。

    类型:Int64

    static const STATUS_PAYMENT_REQUIRED

    public static const STATUS_PAYMENT_REQUIRED: UInt16 = 402
    

    功能:为了将来可能的需求而预留的状态码。

    类型:Int64

    static const STATUS_PERMANENT_REDIRECT

    public static const STATUS_PERMANENT_REDIRECT: UInt16 = 308
    

    功能:请求和所有将来的请求应该使用另一个 URI。

    类型:Int64

    static const STATUS_PRECONDITION_FAILED

    public static const STATUS_PRECONDITION_FAILED: UInt16 = 412
    

    功能:服务器在验证在请求的头字段中给出先决条件时,没能满足其中的一个或多个。

    类型:Int64

    static const STATUS_PRECONDITION_REQUIRED

    public static const STATUS_PRECONDITION_REQUIRED: UInt16 = 428
    

    功能:客户端发送 HTTP 请求时,必须要满足的一些预设条件。

    类型:Int64

    static const STATUS_PROCESSING

    public static const STATUS_PROCESSING: UInt16 = 102
    

    功能:处理将被继续执行。

    类型:Int64

    static const STATUS_PROXY_AUTH_REQUIRED

    public static const STATUS_PROXY_AUTH_REQUIRED: UInt16 = 407
    

    功能:必须在代理服务器上进行身份验证。

    类型:Int64

    static const STATUS_REQUESTED_RANGE_NOT_SATISFIABLE

    public static const STATUS_REQUESTED_RANGE_NOT_SATISFIABLE: UInt16 = 416
    

    功能:客户端请求的范围无效。

    类型:Int64

    说明:

    请求中包含了 Range 请求头,并且 Range 中指定的任何数据范围都与当前资源的可用范围不重合; 同时请求中又没有定义 If-Range 请求头。

    static const STATUS_REQUEST_CONTENT_TOO_LARGE

    public static const STATUS_REQUEST_CONTENT_TOO_LARGE: UInt16 = 413
    

    功能:请求提交的实体数据大小超过了服务器愿意或者能够处理的范围。

    类型:Int64

    static const STATUS_REQUEST_HEADER_FIELDS_TOO_LARGE

    public static const STATUS_REQUEST_HEADER_FIELDS_TOO_LARGE: UInt16 = 431
    

    功能:请求头字段太大。

    类型:Int64

    static const STATUS_REQUEST_TIMEOUT

    public static const STATUS_REQUEST_TIMEOUT: UInt16 = 408
    

    功能:请求超时。客户端没有在服务器预备等待的时间内完成一个请求的发送。

    类型:Int64

    static const STATUS_REQUEST_URI_TOO_LONG

    public static const STATUS_REQUEST_URI_TOO_LONG: UInt16 = 414
    

    功能:求的 URI 长度超过了服务器能够解释的长度。

    类型:Int64

    static const STATUS_RESET_CONTENT

    public static const STATUS_RESET_CONTENT: UInt16 = 205
    

    功能:服务器成功处理了请求,且没有返回任何内容,希望请求者重置文档视图。

    类型:Int64

    static const STATUS_SEE_OTHER

    public static const STATUS_SEE_OTHER: UInt16 = 303
    

    功能:对应当前请求的响应可以在另一个 URL 上被找到,而且客户端应当采用 GET 的方式访问那个资源。

    类型:Int64

    static const STATUS_SERVICE_UNAVAILABLE

    public static const STATUS_SERVICE_UNAVAILABLE: UInt16 = 503
    

    功能:临时的服务器维护或者过载。

    类型:Int64

    static const STATUS_SWITCHING_PROTOCOLS

    public static const STATUS_SWITCHING_PROTOCOLS: UInt16 = 101
    

    功能:服务器已经理解了客户端的请求,并将通过 Upgrade 消息头通知客户端采用不同的协议来完成这个请求。

    类型:Int64

    说明:

    在发送完这个响应最后的空行后,服务器将会切换到在 Upgrade 消息头中定义的那些协议。

    static const STATUS_TEAPOT

    public static const STATUS_TEAPOT: UInt16 = 418
    

    功能:服务端无法处理请求,一个愚弄客户端的状态码,被称为“我是茶壶”错误码,不应被认真对待。

    类型:Int64

    static const STATUS_TEMPORARY_REDIRECT

    public static const STATUS_TEMPORARY_REDIRECT: UInt16 = 307
    

    功能:临时重定向。

    类型:Int64

    static const STATUS_TOO_EARLY

    public static const STATUS_TOO_EARLY: UInt16 = 425
    

    功能:服务器不愿意冒风险来处理该请求。

    类型:Int64

    static const STATUS_TOO_MANY_REQUESTS

    public static const STATUS_TOO_MANY_REQUESTS: UInt16 = 429
    

    功能:请求过多。

    类型:Int64

    static const STATUS_UNAUTHORIZED

    public static const STATUS_UNAUTHORIZED: UInt16 = 401
    

    功能:当前请求需要用户验证。

    类型:Int64

    public static const STATUS_UNAVAILABLE_FOR_LEGAL_REASONS: UInt16 = 451
    

    功能:该请求因法律原因不可用。

    类型:Int64

    static const STATUS_UNPROCESSABLE_ENTITY

    public static const STATUS_UNPROCESSABLE_ENTITY: UInt16 = 422
    

    功能:请求格式正确,但是由于含有语义错误,无法响应。

    类型:Int64

    static const STATUS_UNSUPPORTED_MEDIA_TYPE

    public static const STATUS_UNSUPPORTED_MEDIA_TYPE: UInt16 = 415
    

    功能:服务器无法处理请求附带的媒体格式。

    类型:Int64

    说明:

    对于当前请求的函数和所请求的资源,请求中提交的实体并不是服务器中所支持的格式。

    static const STATUS_UPGRADE_REQUIRED

    public static const STATUS_UPGRADE_REQUIRED: UInt16 = 426
    

    功能:服务器拒绝处理客户端使用当前协议发送的请求,但是可以接受其使用升级后的协议发送的请求。

    类型:Int64

    static const STATUS_USE_PROXY

    public static const STATUS_USE_PROXY: UInt16 = 305
    

    功能:使用代理,所请求的资源必须通过代理访问。

    类型:Int64

    static const STATUS_VARIANT_ALSO_NEGOTIATES

    public static const STATUS_VARIANT_ALSO_NEGOTIATES: UInt16 = 506
    

    功能:服务器存在内部配置错误。

    类型:Int64

    struct ServicePoolConfig

    public struct ServicePoolConfig
    

    功能:Http Server 协程池配置。

    说明:

    HTTP/1.1 Server 每次收到一个请求,将从协程池取出一个协程进行处理,如果任务等待队列已满,将拒绝服务该次请求,并断开连接。 HTTP/2 Server 处理过程中会从协程池取出若干协程进行处理,如果任务等待队列已满,将阻塞直至有协程空闲。

    let capacity

    public let capacity: Int64
    

    功能:获取协程池容量。

    类型:Int64

    let preheat

    public let preheat: Int64
    

    功能:获取服务启动时预先启动的协程数量。

    类型:Int64

    let queueCapacity

    public let queueCapacity: Int64
    

    功能:获取缓冲区等待任务的最大数量。

    类型:Int64

    init(Int64, Int64, Int64)

    public init(
        capacity!: Int64 = 10 ** 4,
        queueCapacity!: Int64 = 10 ** 4,
        preheat!: Int64 = 0
    )
    

    功能:构造一个 ServicePoolConfig 实例。

    参数:

    • capacity!: Int64 - 协程池容量,默认值为 10000。
    • queueCapacity!: Int64 - 缓冲区等待任务的最大数量,默认值为 10000。
    • preheat!: Int64 - 服务启动时预先启动的协程数量,默认值为 0。

    异常:

    struct TransportConfig

    public struct TransportConfig
    

    功能:传输层配置类,服务器建立连接使用的传输层配置。

    prop keepAliveConfig

    public mut prop keepAliveConfig: SocketKeepAliveConfig
    

    功能:设定和读取传输层连接的消息保活配置,默认配置空闲时间为 45s,发送探测报文的时间间隔为 5s,在连接被认为无效之前发送的探测报文数 5 次,实际时间粒度可能因操作系统而异。

    类型:SocketKeepAliveConfig

    prop readBufferSize

    public mut prop readBufferSize: ?Int64
    

    功能:设定和读取传输层连接的读缓冲区大小,默认值为 None ,若设置的值小于 0,将在服务器进行服务建立连接后抛出 IllegalArgumentException

    说明:

    使用默认值时,实际的缓冲区大小将由操作系统决定。

    类型:?Int64

    prop readTimeout

    public mut prop readTimeout: Duration
    

    功能:设定和读取传输层连接的读超时时间,如果设置的时间小于 0 将置为 0,默认值为 Duration.Max。

    类型:Duration

    prop writeBufferSize

    public mut prop writeBufferSize: ?Int64
    

    功能:设定和读取传输层连接的写缓冲区大小,默认值为 None ,若设置的值小于 0,将在服务器进行服务建立连接后抛出 IllegalArgumentException

    说明:

    使用默认值时,实际的缓冲区大小将由操作系统决定。

    类型:?Int64

    prop writeTimeout

    public mut prop writeTimeout: Duration
    

    功能:设定和读取传输层连接的写超时时间,如果设置的时间小于 0 将置为 0,默认值为 Duration.Max。

    类型:Duration

    异常类

    class ConnectionException

    public class ConnectionException <: IOException {
        public init(message: String)
    }
    

    功能:Http 的tcp连接异常类。

    父类型:

    init(String)

    public init(message: String)
    

    功能:创建 ConnectionException 实例。

    参数:

    • message: String - 异常提示信息。

    class CoroutinePoolRejectException

    public class CoroutinePoolRejectException <: Exception {
        public init(message: String)
    }
    

    功能:Http 的协程池拒绝请求处理异常类。

    父类型:

    init(String)

    public init(message: String)
    

    功能:创建 CoroutinePoolRejectException 实例。

    参数:

    • message: String - 异常提示信息。

    class HttpException

    public class HttpException <: Exception {
        public init(message: String)
    }
    

    功能:Http 的通用异常类。

    父类型:

    init(String)

    public init(message: String)
    

    功能:创建 HttpException 实例。

    参数:

    • message: String - 异常提示信息。

    class HttpStatusException

    public class HttpStatusException <: Exception {
        public init(message: String)
    }
    

    功能:Http 的响应状态异常类。

    父类型:

    init(String)

    public init(message: String)
    

    功能:创建 HttpStatusException 实例。

    参数:

    • message: String - 异常提示信息。

    class HttpTimeoutException

    public class HttpTimeoutException <: Exception {
        public init(message: String)
    }
    

    功能:Http 的超时异常类。

    父类型:

    init(String)

    public init(message: String)
    

    功能:创建 HttpTimeoutException 实例。

    参数:

    • message: String - 异常提示信息。

    class WebSocketException

    public class WebSocketException <: Exception {
        public init(message: String)
    }
    

    功能:WebSocket 的通用异常类。

    父类型:

    init(String)

    public init(message: String)
    

    功能:创建 WebSocketException 实例。

    参数:

    • message: String - 异常提示信息。

    client

    Hello World

    import net.http.*
    
    main () {
        // 1. 构建 client 实例
        let client = ClientBuilder().build()
        // 2. 发送 request
        let rsp = client.get("http://example.com/hello")
        // 3. 读取response
        println(rsp)
        // 4. 关闭连接
        client.close()
    }
    

    运行结果如下:

    HTTP/1.1 200 OK
    accept-ranges: bytes
    age: 258597
    cache-control: max-age=604800
    content-type: text/html
    date: Wed, 05 Jun 2024 02:19:26 GMT
    etag: "3147526947"
    expires: Wed, 12 Jun 2024 02:19:26 GMT
    last-modified: Thu, 17 Oct 2019 07:18:26 GMT
    server: ECAcc (lac/55A4)
    vary: Accept-Encoding
    x-cache: HIT
    content-length: 1256
    connection: close
    
    body size: 1256
    

    自定义 client 网络配置

    import std.net.{TcpSocket, SocketAddress}
    import std.convert.Parsable
    import std.fs.*
    import net.tls.*
    import crypto.x509.X509Certificate
    import net.http.*
    import std.io.*
    
    //该程序需要用户配置存在且合法的文件路径才能执行
    main () {
        // 1. 自定义配置
        // tls 配置
        var tlsConfig = TlsClientConfig()
        let pem = String.fromUtf8(readToEnd(File("/rootCerPath", OpenOption.Open(true, false))))
        tlsConfig.verifyMode = CustomCA(X509Certificate.decodeFromPem(pem))
        tlsConfig.alpnProtocolsList = ["h2"]
        // connector
        let TcpSocketConnector = { sa: SocketAddress =>
            let socket = TcpSocket(sa)
            socket.connect()
            return socket
        }
        // 2. 构建 client 实例
        let client = ClientBuilder()
                          .tlsConfig(tlsConfig)
                          .enablePush(false)
                          .connector(TcpSocketConnector)
                          .build()
        // 3. 发送 request
        let rsp = client.get("https://example.com/hello")
        // 4. 读取response
        let buf = Array<UInt8>(1024, repeat: 0)
        let len = rsp.body.read(buf)
        println(String.fromUtf8(buf.slice(0, len)))
        // 5. 关闭连接
        client.close()
    }
    

    request中的 chunked 与 trailer

    import std.io.*
    import std.fs.*
    import net.http.*
    
    func checksum(chunk: Array<UInt8>): Int64 {
        var sum = 0
        for (i in chunk) {
            if (i == b'\n') {
                sum += 1
            }
        }
        return sum / 2
    }
    
    //该程序需要用户配置存在且合法的文件路径才能执行
    main () {
        // 1. 构建 client 实例
        let client = ClientBuilder().build()
        var requestBuilder = HttpRequestBuilder()
        let file = File("./res.jpg", OpenOption.Open(true, false))
        let sum = checksum(readToEnd(file))
        let req = requestBuilder
                       .method("PUT")
                       .url("https://example.com/src/")
                       .header("Transfer-Encoding","chunked")
                       .header("Trailer","checksum")
                       .body(FileBody("./res.jpg"))
                       .trailer("checksum", sum.toString())
                       .build()
        let rsp = client.send(req)
        println(rsp)
        client.close()
    }
    
    class FileBody <: InputStream {
        var file: File
        init(path: String) { file = File(path, OpenOption.Open(true, false))}
        public func read(buf: Array<UInt8>): Int64 {
            file.read(buf)
        }
    }
    

    配置代理

    import net.http.*
    
    main () {
        // 1. 构建 client 实例
        let client = ClientBuilder()
                          .httpProxy("http://192.168.0.1:8080")
                          .build()
        // 2. 发送 request,所有 request都会被发送至192.168.0.1地址的8080端口,而不是example.com
        let rsp = client.get("http://example.com/hello")
        // 3. 读取response
        println(rsp)
        // 4. 关闭连接
        client.close()
    }
    

    cookie

    Client

    import net.http.*
    import encoding.url.*
    import std.net.*
    import std.time.*
    import std.sync.*
    
    main() {
        // 1、启动socket服务器
        let serverSocket = TcpServerSocket(bindAt: 0)
        serverSocket.bind()
        let fut = spawn {
            serverPacketCapture(serverSocket)
        }
        sleep(Duration.millisecond * 10)
        // 客户端一般从 response 中的 Set-Cookie header 中读取 cookie,并将其存入 cookieJar 中,
        // 下次发起 request时,将其放在 request 的 Cookie header 中发送
        // 2、启动客户端
        let client = ClientBuilder().build()
        let port = (serverSocket.localAddress as IPSocketAddress)?.port ?? throw Exception("Port not found.")
        var u = URL.parse("http://127.0.0.1:${port}/a/b/c")
        var r = HttpRequestBuilder()
                            .url(u)
                            .build()
        // 3、发送request
        client.send(r)
        sleep(Duration.second * 2)
        r = HttpRequestBuilder()
                            .url(u)
                            .build()
        // 4、发送新 request,从 CookieJar 中取出 cookie,并转成 Cookie header 中的值
        // 此时 cookie 2=2 已经过期,因此只发送 1=1 cookie
        client.send(r)
        // 5、关闭客户端
        client.close()
        fut.get()
        serverSocket.close()
    }
    
    func serverPacketCapture(serverSocket: TcpServerSocket) {
        let buf = Array<UInt8>(500, repeat: 0)
        let server = serverSocket.accept()
        var i = server.read(buf)
        println(String.fromUtf8(buf[..i]))
        // GET /a/b/c HTTP/1.1
        // host: 127.0.0.1:44649
        // user-agent: CANGJIEUSERAGENT_1_1
        // connection: keep-alive
        // content-length: 0
        //
        // 过期时间为 4 秒的 cookie1
        let cookie1 = Cookie("1", "1", maxAge: 4, domain: "127.0.0.1", path: "/a/b/")
        let setCookie1 = cookie1.toSetCookieString()
        // 过期时间为 2 秒的 cookie2
        let cookie2 = Cookie("2", "2", maxAge: 2, path: "/a/")
        let setCookie2 = cookie2.toSetCookieString()
        // 服务器发送 Set-Cookie 头,客户端解析并将其存进 CookieJar 中
        server.write("HTTP/1.1 204 ok\r\nSet-Cookie: ${setCookie1}\r\nSet-Cookie: ${setCookie2}\r\nConnection: close\r\n\r\n".toArray())
    
        let server2 = serverSocket.accept()
        i = server2.read(buf)
        // 接收客户端的带 cookie 的请求
        println(String.fromUtf8(buf[..i]))
        // GET /a/b/c HTTP/1.1
        // host: 127.0.0.1:34857
        // cookie: 1=1
        // user-agent: CANGJIEUSERAGENT_1_1
        // connection: keep-alive
        // content-length: 0
        //
        server2.write("HTTP/1.1 204 ok\r\nConnection: close\r\n\r\n".toArray())
        server2.close()
    }
    

    运行结果参考如下(port 会随机分配):

    GET /a/b/c HTTP/1.1
    host: 127.0.0.1:37359
    user-agent: CANGJIEUSERAGENT_1_1
    connection: keep-alive
    content-length: 0
    
    
    GET /a/b/c HTTP/1.1
    host: 127.0.0.1:37359
    cookie: 1=1
    user-agent: CANGJIEUSERAGENT_1_1
    connection: keep-alive
    content-length: 0
    

    Server

    import net.http.*
    
    main () {
       // 服务器设置 cookie 时将 cookie 放在 Set-Cookie header 中发给客户端
        // 1. 构建 Server 实例
        let server = ServerBuilder()
                           .addr("127.0.0.1")
                           .port(8080)
                           .build()
        // 2. 注册 HttpRequestHandler
        server.distributor.register("/index", {httpContext =>
            let cookie = Cookie("name", "value")
            httpContext.responseBuilder.header("Set-Cookie", cookie.toSetCookieString()).body("Hello 仓颉!")
        })
        // 3. 启动服务
        server.serve()
    }
    

    log

    import log.*
    import net.http.*
    
    main () {
        // 1. 构建 Server 实例
        let server = ServerBuilder()
                           .addr("127.0.0.1")
                           .port(8080)
                           .build()
        // 2. 注册 HttpRequestHandler
        server.distributor.register("/index", {httpContext =>
            httpContext.responseBuilder.body("Hello 仓颉!")
        })
        // 3. 开启日志
        server.logger.level = LogLevel.DEBUG
        // client端通过client.logger.level = DEBUG 开启
        // 4. 启动服务
        server.serve()
    }
    

    运行结果如下所示:

    2024/01/25 17:23:54.344205 DEBUG Logger [Server#serve] bindAndListen(127.0.0.1, 8080)
    

    server

    Hello 仓颉

    import net.http.ServerBuilder
    
    main () {
        // 1. 构建 Server 实例
        let server = ServerBuilder()
                            .addr("127.0.0.1")
                            .port(8080)
                            .build()
        // 2. 注册 HttpRequestHandler
        server.distributor.register("/index", {httpContext =>
            httpContext.responseBuilder.body("Hello 仓颉!")
        })
        // 3. 启动服务
        server.serve()
    }
    

    通过 request distributor注册处理器

    import net.http.{ServerBuilder, HttpRequestHandler, FuncHandler}
    
    main () {
        // 1. 构建 Server 实例
        let server = ServerBuilder()
                            .addr("127.0.0.1")
                            .port(8080)
                            .build()
        var a: HttpRequestHandler = FuncHandler({ httpContext =>
            httpContext.responseBuilder.body("index")
        })
        var b: HttpRequestHandler = FuncHandler({ httpContext =>
            httpContext.responseBuilder.body("id")
        })
        var c: HttpRequestHandler = FuncHandler({ httpContext =>
            httpContext.responseBuilder.body("help")
        })
        server.distributor.register("/index", a)
        server.distributor.register("/id", b)
        server.distributor.register("/help", c)
        // 2. 启动服务
        server.serve()
    }
    

    自定义 request distributor与处理器

    import net.http.*
    import std.collection.HashMap
    
    class NaiveDistributor <: HttpRequestDistributor {
        let map = HashMap<String, HttpRequestHandler>()
        public func register(path: String, handler: HttpRequestHandler): Unit {
            map.put(path, handler)
        }
    
        public func distribute(path: String): HttpRequestHandler {
            if (path == "/index") {
                return PageHandler()
            }
            return NotFoundHandler()
        }
    }
    
    // 返回一个简单的 HTML 页面
    class PageHandler <: HttpRequestHandler {
        public func handle(httpContext: HttpContext): Unit {
            httpContext.responseBuilder.body("<html></html>")
        }
    }
    
    main () {
        // 1. 构建 Server 实例
        let server = ServerBuilder()
                            .addr("127.0.0.1")
                            .port(8080)
                            .distributor(NaiveDistributor()) // 自定义分发器
                            .build()
        // 2. 启动服务
        server.serve()
    }
    

    自定义 server 网络配置

    import std.io.*
    import std.fs.*
    import net.tls.*
    import crypto.x509.{X509Certificate, PrivateKey}
    import net.http.*
    
    //该程序需要用户配置存在且合法的文件路径才能执行
    main () {
        // 1. 自定义配置
        // tcp 配置
        var transportCfg = TransportConfig()
        transportCfg.readBufferSize = 8192
        // tls 配置 需要传入配套的证书与私钥文件路径
        let pem0 = String.fromUtf8(readToEnd(File("/certPath", OpenOption.Open(true, false))))
        let pem02 = String.fromUtf8(readToEnd(File("/keyPath", OpenOption.Open(true, false))))
        var tlsConfig = TlsServerConfig(X509Certificate.decodeFromPem(pem0), PrivateKey.decodeFromPem(pem02))
        tlsConfig.supportedAlpnProtocols = ["h2"]
        // 2. 构建 Server 实例
        let server = ServerBuilder()
                           .addr("127.0.0.1")
                           .port(8080)
                           .transportConfig(transportCfg)
                           .tlsConfig(tlsConfig)
                           .headerTableSize(10 * 1024)
                           .maxRequestHeaderSize(1024 * 1024)
                           .build()
        // 3. 注册 HttpRequestHandler
        server.distributor.register("/index", {httpContext =>
            httpContext.responseBuilder.body("Hello 仓颉!")
        })
        // 4. 启动服务
        server.serve()
    }
    

    response中的 chunked与trailer

    import net.http.*
    import std.io.*
    import std.collection.HashMap
    
    func checksum(chunk: Array<UInt8>): Int64 {
        var sum = 0
        for (i in chunk) {
            if (i == UInt8(UInt32(r'\n'))) {
                sum += 1
            }
        }
        return sum / 2
    }
    
    main () {
        // 1. 构建 Server 实例
        let server = ServerBuilder()
                            .addr("127.0.0.1")
                            .port(8080)
                            .build()
        // 2. 注册 HttpRequestHandler
        server.distributor.register("/index", {httpContext =>
            let responseBuilder = httpContext.responseBuilder
            responseBuilder.header("transfer-encoding", "chunked") // 设置response头
            responseBuilder.header("trailer", "checkSum")
            let writer = HttpResponseWriter(httpContext)
            var sum = 0
            for (_ in 0..10) {
                let chunk = Array<UInt8>(10, repeat: 0)
                sum += checksum(chunk)
                writer.write(chunk) // 立即发送
            }
            responseBuilder.trailer("checkSum", "${sum}") // handler结束后发送
        })
        // 3. 启动服务
        server.serve()
    }
    

    处理重定向 request

    import net.http.*
    
    main () {
        // 1. 构建 Server 实例
        let server = ServerBuilder()
                            .addr("127.0.0.1")
                            .port(8080)
                            .build()
        // 2. 注册 HttpRequestHandler
        server.distributor.register("/redirecta",RedirectHandler("/movedsource", 308))
        server.distributor.register("/redirectb",RedirectHandler("http://www.example.com", 308))
        // 3. 启动服务
        server.serve()
    }
    

    tls 证书热加载

    import std.io.*
    import std.fs.*
    import net.tls.*
    import crypto.x509.{X509Certificate, PrivateKey}
    import net.http.*
    
    //该程序需要用户配置存在且合法的文件路径才能执行
    main() {
        // 1. tls 配置
        let pem0 = String.fromUtf8(readToEnd(File("/certPath", OpenOption.Open(true, false))))
        let pem02 = String.fromUtf8(readToEnd(File("/keyPath", OpenOption.Open(true, false))))
        var tlsConfig = TlsServerConfig(X509Certificate.decodeFromPem(pem0), PrivateKey.decodeFromPem(pem02))
        tlsConfig.supportedAlpnProtocols = ["http/1.1"]
        let pem = String.fromUtf8(readToEnd(File("/rootCerPath", OpenOption.Open(true, false))))
        tlsConfig.verifyMode = CustomCA(X509Certificate.decodeFromPem(pem))
        // 2. 构建 Server 实例,并启动服务
        let server = ServerBuilder()
                            .addr("127.0.0.1")
                            .port(8080)
                            .tlsConfig(tlsConfig)
                            .build()
        spawn {
            server.serve()
        }
        // 3. 更新 tls 证书和私钥,之后收到的 request将使用新的证书和私钥
        server.updateCert("/newCerPath", "/newKeyPath")
        // 4. 更新 CA, 双向认证时使用,之后收到的 request将使用新的CA
        server.updateCA("/newRootCerPath")
    }
    

    server push

    仅用于 HTTP/2

    client:

    import std.io.*
    import std.fs.*
    import std.collection.ArrayList
    import net.tls.*
    import crypto.x509.X509Certificate
    import net.http.*
    
    //该程序需要用户配置存在且合法的文件路径才能执行
    // client:
    main() {
        // 1. tls 配置
        var tlsConfig = TlsClientConfig()
        let pem = String.fromUtf8(readToEnd(File("/rootCerPath", OpenOption.Open(true, false))))
        tlsConfig.verifyMode = CustomCA(X509Certificate.decodeFromPem(pem))
        tlsConfig.alpnProtocolsList = ["h2"]
        // 2. 构建 Client 实例
        let client = ClientBuilder()
                        .tlsConfig(tlsConfig)
                        .build()
        // 3. 发送 request,收response
        let response = client.get("https://example.com/index.html")
        // 4. 收 pushResponse,此例中相当于 client.get("http://example.com/picture.png") 的response
        let pushResponses: Option<ArrayList<HttpResponse>> = response.getPush()
        client.close()
    }
    

    server:

    import std.io.*
    import std.fs.*
    import net.tls.*
    import crypto.x509.{X509Certificate, PrivateKey}
    import net.http.*
    
    //该程序需要用户配置存在且合法的文件路径才能执行
    main() {
        // 1. tls 配置
        let pem0 = String.fromUtf8(readToEnd(File("/certPath", OpenOption.Open(true, false))))
        let pem02 = String.fromUtf8(readToEnd(File("/keyPath", OpenOption.Open(true, false))))
        var tlsConfig = TlsServerConfig(X509Certificate.decodeFromPem(pem0), PrivateKey.decodeFromPem(pem02))
        tlsConfig.supportedAlpnProtocols = ["h2"]
        // 2. 构建 Server 实例
        let server = ServerBuilder()
                        .addr("127.0.0.1")
                        .port(8080)
                        .tlsConfig(tlsConfig)
                        .build()
        // 3. 注册原 request 的 handler
        server.distributor.register("/index.html", {httpContext =>
            let pusher = HttpResponsePusher.getPusher(httpContext)
            match (pusher) {
                case Some(pusher) =>
                    pusher.push("/picture.png", "GET", httpContext.request.headers)
                case None =>
                    ()
            }
    
        })
        // 4. 注册 pushRequest 的 handler
        server.distributor.register("/picture.png", {httpContext =>
            httpContext.responseBuilder.body("picture.png")
        })
        // 4. 启动服务
        server.serve()
    }
    

    webSocket

    import net.http.*
    import encoding.url.*
    import std.time.*
    import std.sync.*
    import std.collection.*
    import log.*
    
    let server = ServerBuilder()
                            .addr("127.0.0.1")
                            .port(0)
                            .build()
    
    // client:
    main() {
        // 1 启动服务器
        spawn { startServer() }
        sleep(Duration.millisecond * 200)
    
        let client = ClientBuilder().build()
        let u = URL.parse("ws://127.0.0.1:${server.port}/webSocket")
    
        let subProtocol = ArrayList<String>(["foo1", "bar1"])
        let headers = HttpHeaders()
        headers.add("test", "echo")
    
        // 2 完成 WebSocket 握手,获取 WebSocket 实例
        let websocket: WebSocket
        let respHeaders: HttpHeaders
        (websocket, respHeaders) = WebSocket.upgradeFromClient(client, u, subProtocols: subProtocol, headers: headers)
        client.close()
    
        println("subProtocol: ${websocket.subProtocol}")      // fool1
        println(respHeaders.getFirst("rsp") ?? "") // echo
    
        // 3 消息收发
        // 发送 hello
        websocket.write(TextWebFrame, "hello".toArray())
        // 收
        let data = ArrayList<UInt8>()
        var frame = websocket.read()
        while(true) {
            match(frame.frameType) {
                case ContinuationWebFrame =>
                    data.appendAll(frame.payload)
                    if (frame.fin) {
                        break
                    }
                case TextWebFrame | BinaryWebFrame =>
                    if (!data.isEmpty()) {
                        throw Exception("invalid frame")
                    }
                    data.appendAll(frame.payload)
                    if (frame.fin) {
                        break
                    }
                case CloseWebFrame =>
                    websocket.write(CloseWebFrame, frame.payload)
                    break
                case PingWebFrame =>
                    websocket.writePongFrame(frame.payload)
                case _ => ()
            }
            frame = websocket.read()
        }
        println("data size: ${data.size}")      // 4097
        println("last item: ${String.fromUtf8(data.toArray()[4096])}")        // a
    
    
        // 4 关闭 websocket,
        // 收发 CloseFrame
        websocket.writeCloseFrame(status: 1000)
        let websocketFrame = websocket.read()
        println("close frame type: ${websocketFrame.frameType}")      // CloseWebFrame
        println("close frame payload: ${websocketFrame.payload}")     // 3, 232
        // 关闭底层连接
        websocket.closeConn()
    
        server.close()
    }
    
    func startServer() {
        // 1 注册 handler
        server.distributor.register("/webSocket", handler1)
        server.logger.level = LogLevel.OFF
        server.serve()
    }
    
    // server:
    func handler1(ctx: HttpContext): Unit {
        // 2 完成 websocket 握手,获取 websocket 实例
        let websocketServer = WebSocket.upgradeFromServer(ctx, subProtocols: ArrayList<String>(["foo", "bar", "foo1"]),
            userFunc: {request: HttpRequest =>
                let value = request.headers.getFirst("test") ?? ""
                let headers = HttpHeaders()
                headers.add("rsp", value)
                headers
            })
        // 3 消息收发
        // 收 hello
        let data = ArrayList<UInt8>()
        var frame = websocketServer.read()
        while(true) {
            match(frame.frameType) {
                case ContinuationWebFrame =>
                    data.appendAll(frame.payload)
                    if (frame.fin) {
                        break
                    }
                case TextWebFrame | BinaryWebFrame =>
                    if (!data.isEmpty()) {
                        throw Exception("invalid frame")
                    }
                    data.appendAll(frame.payload)
                    if (frame.fin) {
                        break
                    }
                case CloseWebFrame =>
                    websocketServer.write(CloseWebFrame, frame.payload)
                    break
                case PingWebFrame =>
                    websocketServer.writePongFrame(frame.payload)
                case _ => ()
            }
            frame = websocketServer.read()
        }
        println("data: ${String.fromUtf8(data.toArray())}")    // hello
        // 发 4097 个 a
        websocketServer.write(TextWebFrame, Array<UInt8>(4097, repeat: 97))
    
        // 4 关闭 websocket,
        // 收发 CloseFrame
        let websocketFrame = websocketServer.read()
        println("close frame type: ${websocketFrame.frameType}")   // CloseWebFrame
        println("close frame payload: ${websocketFrame.payload}")     // 3, 232
        websocketServer.write(CloseWebFrame, websocketFrame.payload)
        // 关闭底层连接
        websocketServer.closeConn()
    }
    

    运行结果如下:

    subProtocol: foo1
    echo
    data: hello
    data size: 4097
    last item: a
    close frame type: CloseWebFrame
    close frame payload: [3, 232]
    close frame type: CloseWebFrame
    close frame payload: [3, 232]
    

    net.tls 包

    功能介绍

    tls 包用于进行安全加密的网络通信,提供创建 TLS 服务器、基于协议进行 TLS 握手、收发加密数据、恢复 TLS 会话等能力。

    本包支持TLS 1.2 及 TLS 1.3 传输层安全协议通信。

    使用本包需要外部依赖 OpenSSL 3sslcrypto 动态库文件,故使用前需安装相关工具:

    • 对于 Linux 操作系统,可参考以下方式:
      • 如果系统的包管理工具支持安装 OpenSSL 3 开发工具包,可通过这个方式安装,并确保系统安装目录下含有 libssl.solibssl.so.3libcrypto.solibcrypto.so.3 这些动态库文件,例如 Ubuntu 22.04 系统上可使用 sudo apt install libssl-dev 命令安装 libssl-dev 工具包;
      • 如果无法通过上面的方式安装,可自行下载 OpenSSL 3.x.x 源码编译安装软件包,并确保安装目录下含有 libssl.solibssl.so.3libcrypto.solibcrypto.so.3 这些动态库文件,然后可选择下面任意一种方式来保证系统链接器可以找到这些文件:
        • 在系统未安装 OpenSSL 的场景,安装时选择直接安装到系统路径下;
        • 安装在自定义目录的场景,将这些文件所在目录设置到环境变量 LD_LIBRARY_PATH 以及 LIBRARY_PATH 中。
    • 对于 Windows 操作系统,可按照以下步骤:
      • 自行下载 OpenSSL 3.x.x 源码编译安装 x64 架构软件包或者自行下载安装第三方预编译的供开发人员使用的 OpenSSL 3.x.x 软件包;
      • 确保安装目录下含有 libssl.dll.a(或 libssl.lib)、libssl-3-x64.dlllibcrypto.dll.a(或 libcrypto.lib)、libcrypto-3-x64.dll 这些库文件;
      • libssl.dll.a(或 libssl.lib)、libcrypto.dll.a(或 libcrypto.lib) 所在的目录路径设置到环境变量 LIBRARY_PATH 中,将 libssl-3-x64.dlllibcrypto-3-x64.dll 所在的目录路径设置到环境变量 PATH 中。
    • 对于 macOS 操作系统,可参考以下方式:
      • 使用 brew install openssl@3 安装,并确保系统安装目录下含有 libcrypto.dyliblibcrypto.3.dylib 这两个动态库文件;
      • 如果无法通过上面的方式安装,可自行下载 OpenSSL 3.x.x 源码编译安装软件包,并确保安装目录下含有 libcrypto.dyliblibcrypto.3.dylib 这两个动态库文件,然后可选择下面任意一种方式来保证系统链接器可以找到这些文件:
        • 在系统未安装 OpenSSL 的场景,安装时选择直接安装到系统路径下;
        • 安装在自定义目录的场景,将这些文件所在目录设置到环境变量 DYLD_LIBRARY_PATH 以及 LIBRARY_PATH 中。

    注意:

    如果未安装OpenSSL 3软件包或者安装低版本的软件包,程序可能无法使用并抛出相关异常 TlsException: Can not load openssl library or function xxx.。

    API 列表

    类名功能
    TlsSessionContext服务端启用 session 特性恢复会话,存储 session 用于对客户端进行验证类型。
    TlsSocket用于在客户端及服务端间创建加密传输通道。

    枚举

    枚举名功能
    CertificateVerifyMode证书认证模式。
    SignatureAlgorithm签名算法类型,签名算法用于确保传输数据的身份验证、完整性和真实性。
    SignatureSchemeType加密算法类型,用于保护网络通信的安全性和隐私性。
    SignatureType签名算法类型,用于认证真实性。
    TlsClientIdentificationMode服务端对客户端证书的认证模式。
    TlsVersionTLS 协议版本。

    结构体

    结构体名功能
    CipherSuiteTLS 中的密码套件。
    TlsClientConfig客户端配置。
    TlsServerConfig服务端配置。
    TlsSession当客户端 TLS 握手成功后,将会生成一个会话,当连接因一些原因丢失后,客户端可以通过这个会话 id 复用此次会话,省略握手流程。

    异常类

    类名功能
    TlsExceptionTLS 处理出现错误时抛出的异常类型。

    class TlsSessionContext

    public class TlsSessionContext <: Equatable<TlsSessionContext> & ToString
    

    功能:该类表示 TLS 会话上下文,给客户端提供信息,确保客户端所连接的服务端仍为相同实例,用于连接复用时,验证客户端合法性。

    说明:

    当客户端尝试恢复会话时,双方都必须确保他们正在恢复与合法对端的会话。

    父类型:

    static func fromName(String)

    public static func fromName(name: String): TlsSessionContext
    

    功能:通过名称创建 TlsSessionContext 实例。

    通过 TlsSessionContext 保存的名称获取 TlsSessionContext 对象。该名称用于区分 TLS 服务器,因此客户端依赖此名称来避免意外,尝试恢复与错误的服务器的连接。这里不一定使用加密安全名称,因为底层实现可以完成这项工作。从此函数返回的具有相同名称的两个 TlsSessionContext 可能不相等,并且不保证可替换。尽管它们是从相同的名称创建的,因此服务器实例应该在整个生命周期内创建一个 TlsSessionContext ,并且在每次 TlsSocket.server() 调用中使用它。

    参数:

    • name: String - 会话上下文名称。

    返回值:

    func toString()

    public override func toString(): String
    

    功能:生成会话上下文名称字符串。

    返回值:

    operator func !=(TlsSessionContext)

    public override operator func !=(other: TlsSessionContext)
    

    功能:判断两 TlsSessionContext 实例名称是否不同。

    参数:

    返回值:

    operator func ==(TlsSessionContext)

    public override operator func ==(other: TlsSessionContext)
    

    功能:判断两 TlsSessionContext 实例名称是否相同。

    参数:

    返回值:

    class TlsSocket

    public class TlsSocket <: StreamingSocket & ToString & Equatable<TlsSocket> & Hashable
    

    功能:TlsSocket 用于在客户端及服务端间创建加密传输通道。

    父类型:

    prop alpnProtocolName

    public prop alpnProtocolName: ?String
    

    功能:读取协商到的应用层协议名称。

    类型:?String

    异常:

    • TlsException - 当套接字未完成 TLS 握手或本端 TLS 套接字已关闭时,抛出异常。
    • IllegalMemoryException - 当内存申请失败时,抛出异常。

    prop cipherSuite

    public prop cipherSuite: CipherSuite
    

    功能:握手后协商到的加密套。

    说明:

    密码套件包含加密算法、用于消息认证的散列函数、密钥交换算法。

    类型:CipherSuite

    异常:

    • TlsException - 当套接字未完成 TLS 握手或本端 TLS 套接字已关闭时,抛出异常。

    prop clientCertificate

    public prop clientCertificate: ?Array<X509Certificate>
    

    功能:客户端提供的客户端证书。在客户端获取时为本端证书,在服务端获取时为对端证书。

    注意:

    获取对端证书时,如果对端没有发送证书,该接口可能获取失败,返回 None。详见 peerCertificate

    类型:?Array<X509Certificate>

    异常:

    • TlsException - 当套接字未完成 TLS 握手或本端 TLS 套接字已关闭时,抛出异常。

    prop domain

    public prop domain: ?String
    

    功能:读取协商到的服务端主机名称。

    • TlsException - 当套接字未完成 TLS 握手或本端 TLS 套接字已关闭时,抛出异常。

    类型:?String

    prop localAddress

    public override prop localAddress: SocketAddress
    

    功能:读取 TlsSocket 的本地地址。

    类型:SocketAddress

    异常:

    • SocketException - 本端建连的底层 TCP 套接字关闭,抛出异常。
    • TlsException - 本端配置为 TLS 的套接字已关闭时,抛出异常。

    prop peerCertificate

    public prop peerCertificate: ?Array<X509Certificate>
    

    功能:获取对端证书。在客户端获取时同 serverCertificate,在服务端获取时同 clientCertificate

    注意:

    • 如果握手时没有要求对端发送证书,此处将无法获取对端证书,返回 None。

    • 通过 session 机制恢复连接时,双方都不发送证书,该接口行为如下:

      • 在服务端,如果被恢复的原始连接建立时获取了对端证书,服务端将缓存对端证书,并在此处获取到缓存的证书;
      • 在客户端,不缓存原始连接的对端证书,此处将无法获取对端证书,返回 None。

    类型:?Array<X509Certificate>

    异常:

    • TlsException - 当套接字未完成 TLS 握手或本端 TLS 套接字已关闭时,抛出异常。

    prop readTimeout

    public override mut prop readTimeout: ?Duration
    

    功能:读写 TlsSocket 的读超时时间。

    类型:?Duration

    异常:

    prop remoteAddress

    public override prop remoteAddress: SocketAddress
    

    功能:读取 TlsSocket 的远端地址。

    类型:SocketAddress

    异常:

    • SocketException - 本端建连的底层 TCP 套接字关闭,抛出异常。
    • TlsException - 本端配置为 TLS 的套接字已关闭时,抛出异常。

    prop serverCertificate

    public prop serverCertificate: Array<X509Certificate>
    

    功能:服务器证书链由服务器提供或在服务器配置中预先配置。在服务端获取时为本端证书,在客户端获取时为对端证书。

    注意:

    获取对端证书时,如果对端没有发送证书,该接口可能获取失败,返回 None。详见 peerCertificate

    类型:Array<X509Certificate>

    异常:

    • TlsException - 当套接字未完成 TLS 握手或本端 TLS 套接字已关闭时,抛出异常。

    prop session

    public prop session: ?TlsSession
    

    功能:读取 TLS 会话 id , 客户端会在握手成功后捕获当前会话的 id ,可使用该 id 重用该会话,省去 TLS 建立连接时间。连接建立未成功时,返回 None

    说明:

    服务端不做捕获因此始终为 None。

    类型:?TlsSession

    异常:

    • TlsException - 当套接字未完成 TLS 握手,抛出异常。

    prop socket

    public prop socket: StreamingSocket
    

    功能:TlsSocket 创建所使用的 StreamingSocket

    类型:StreamingSocket

    异常:

    • TlsException - 本端配置为 TLS 套接字已关闭时,抛出异常。

    prop tlsVersion

    public prop tlsVersion: TlsVersion
    

    功能:读取协商到的 TLS 版本。

    类型:TlsVersion

    异常:

    • TlsException - 当套接字未完成 TLS 握手或本端 TLS 套接字已关闭时,抛出异常。

    prop writeTimeout

    public override mut prop writeTimeout: ?Duration
    

    功能:读写 TlsSocket 的写超时时间。

    类型:?Duration

    异常:

    static func client(StreamingSocket, ?TlsSession, TlsClientConfig)

    public static func client(
        socket: StreamingSocket,
        session!: ?TlsSession = None,
        clientConfig!: TlsClientConfig = TlsClientConfig()
    ): TlsSocket
    

    功能:根据传入的 StreamingSocket 实例创建指定地址的客户端 TLS 套接字,该套接字可用于客户端 TLS 握手及会话。

    参数:

    • socket: StreamingSocket - 已连接到服务端的客户端 TCP 套接字。
    • session!: ?TlsSession - TLS 会话 id,若存在可用的 TLS 会话, 则可通过该 id 恢复历史 TLS 会话,省去 TLS 建立连接时间,但使用该会话依然可能协商失败。默认为 None
    • clientConfig!: TlsClientConfig - 客户端配置,默认为 TlsClientConfig()。

    返回值:

    static func server(StreamingSocket, ?TlsSessionContext, TlsServerConfig)

    public static func server(
        socket: StreamingSocket,
        sessionContext!: ?TlsSessionContext = None,
        serverConfig!: TlsServerConfig
    ): TlsSocket
    

    功能:根据传入的 StreamingSocket 实例创建指定地址的服务端 TLS 套接字,该套接字可用于服务端 TLS 握手及会话。

    参数:

    • socket: StreamingSocket - TCP 连接建立完成后接受到套接字。
    • sessionContext!: ?TlsSessionContext - TLS 会话 id, 若存在可用的 TLS 会话, 则可通过该 id 恢复历史 TLS 会话,省去 TLS 建立连接时间,但使用该会话依然可能协商失败。默认为 None。
    • serverConfig!: TlsServerConfig - 服务端配置,默认为 TlsServerConfig()。

    返回值:

    func close()

    public func close(): Unit
    

    功能:关闭套接字。

    异常:

    func handshake(?Duration)

    public func handshake(timeout!: ?Duration = None): Unit
    

    功能:TLS 握手。不支持重新协商握手,因此只能被调用一次。调用对象可以为客户端或者服务端的 TlsSocket

    参数:

    • timeout!: ?Duration - 握手超时时间,默认为 None 不对超时时间进行设置,此时采用默认 30s 的超时时间。

    异常:

    • SocketException - 本端建连的底层 TCP 套接字关闭,抛出异常。
    • SocketTimeoutException - 底层 TCP 套接字连接超时时,抛出异常。
    • TlsException - 当握手已经开始或者已经结束,抛出异常或当握手阶段出现系统错误时,抛出异常。
    • IllegalArgumentException - 设定的握手超时时间为负值时,抛出异常。

    func hashCode()

    public override func hashCode(): Int64
    

    功能:返回 TLS 套接字对象的哈希值。

    返回值:

    • Int64 - 对 TLS 套接字对象进行哈希计算后得到的结果。

    func isClosed()

    public func isClosed(): Bool
    

    功能:返回套接字是否关闭的状态。

    返回值:

    • Bool - 连接断开返回 true;否则,返回 false。

    func read(Array<Byte>)

    public override func read(buffer: Array<Byte>): Int64
    

    功能:TlsSocket 读取数据。

    参数:

    • buffer: Array<Byte> - 存储读取到的数据内容的数组。

    返回值:

    • Int64 - 读取到的数据内容字节数。

    异常:

    • SocketException - 本端建连的底层 TCP 套接字关闭,抛出异常。
    • TlsException - 当 buffer 为空,或者 TlsSocket 未连接,或读取数据出现系统错误等。

    func toString()

    public func toString(): String
    

    功能:套接字的字符串表示,字符串内容为当前套接字状态。

    说明:

    例如:当前套接字处于可开始进行握手状态时,该接口将返回字符串 "TlsSocket(TcpSocket(${本端地址} -> ${对端地址}), ready for handshake)"

    返回值:

    • String - 该 TLS 连接字符串。

    func write(Array<Byte>)

    public func write(buffer: Array<Byte>): Unit
    

    功能:TlsSocket 发送数据。

    参数:

    • buffer: Array<Byte> - 存储将要发送的数据内容数组。

    异常:

    • SocketException - 本端建连的底层 TCP 套接字关闭,抛出异常。
    • TlsException - 当套接字已关闭,或者 TlsSocket 未连接,或写入数据出现系统错误等。

    operator func !=(TlsSocket)

    public override operator func !=(other: TlsSocket)
    

    功能:判断两 TlsSocket 是否引用不同实例。

    参数:

    • other: TlsSocket - 对比的 TLS 套接字。

    返回值:

    • Unit - 对比的套接字不同返回 true;否则,返回 false

    operator func ==(TlsSocket)

    public override operator func ==(other: TlsSocket)
    

    功能:判断两 TlsSocket 是否引用同一实例。

    参数:

    • other: TlsSocket - 对比的 TLS 套接字。

    返回值:

    • Unit - 对比的套接字相同返回 true;否则,返回 false

    枚举

    enum CertificateVerifyMode

    public enum CertificateVerifyMode {
        | CustomCA(Array<X509Certificate>)
        | Default
        | TrustAll
    }
    

    功能:对证书验证的处理模式。

    说明:

    CustomCA 模式可使用用户配置的证书地址,适用于用户证书无法设置为系统证书的场景。
    证书认证模式,TCP 连接建立成功后,客户端和服务端可交换证书,Default 模式使用系统证书。
    在开发测试阶段,可使用 TrustAll 模式,该模式表示本端不作对对端证书的校验。此模式本端信任任意建立连接对象,一般仅在开发测试阶段使用。

    CustomCA(Array<X509Certificate>)

    CustomCA(Array<X509Certificate>)
    

    功能:表示根据提供的 CA 列表进行验证。

    Default

    Default
    

    功能:表示默认验证模式,根据系统 CA 验证证书。

    TrustAll

    TrustAll
    

    功能:表示信任所有证书。

    enum SignatureAlgorithm

    public enum SignatureAlgorithm <: ToString & Equatable<SignatureAlgorithm> {
        | SignatureAndHashAlgorithm(SignatureType, HashType)
        | SignatureScheme(SignatureSchemeType)
    }
    

    功能:签名算法类型,签名算法用于确保传输数据的身份验证、完整性和真实性。

    父类型:

    SignatureAndHashAlgorithm(SignatureType, HashType)

    SignatureAndHashAlgorithm(SignatureType, HashType)
    

    功能:表明哪个签名和哈希算法对会被用于数字签名,自 TLS 1.2 及以后版本,包含签名和哈希算法类型。

    SignatureScheme(SignatureSchemeType)

    SignatureScheme(SignatureSchemeType)
    

    功能:签名方案,自 TLS 1.3 及以后版本,业界更为推荐的指定签名算法的方式。

    func toString()

    public func toString():String
    

    功能:转换签名算法的字符串表示。

    返回值:

    • String - 签名算法名称。

    operator func !=(SignatureAlgorithm)

    public operator func !=(other: SignatureAlgorithm) : Bool
    

    功能:判断签名算法类型是否不同。

    参数:

    返回值:

    • Bool - 不相同返回 true;否则,返回 false

    operator func ==(SignatureAlgorithm)

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

    功能:判断签名算法类型是否相同。

    参数:

    返回值:

    • Bool - 相同返回 true;否则,返回 false

    enum SignatureSchemeType

    public enum SignatureSchemeType <: ToString & Equatable<SignatureSchemeType> {
        | RSA_PKCS1_SHA256
        | RSA_PKCS1_SHA384
        | RSA_PKCS1_SHA512
        | ECDSA_SECP256R1_SHA256
        | ECDSA_SECP384R1_SHA384
        | ECDSA_SECP521R1_SHA512
        | RSA_PSS_RSAE_SHA256
        | RSA_PSS_RSAE_SHA384
        | RSA_PSS_RSAE_SHA512
        | ED25519
        | ED448
        | RSA_PSS_PSS_SHA256
        | RSA_PSS_PSS_SHA384
        | RSA_PSS_PSS_SHA512
    }
    

    功能:加密算法类型,用于保护网络通信的安全性和隐私性。

    父类型:

    ECDSA_SECP256R1_SHA256

    ECDSA_SECP256R1_SHA256
    

    功能:创建一个 ECDSA_SECP256R1_SHA256 类型的枚举实例,表示加密算法类型使用 ECDSA_SECP256R1_SHA256

    ECDSA_SECP384R1_SHA384

    ECDSA_SECP384R1_SHA384
    

    功能:创建一个 ECDSA_SECP384R1_SHA384 类型的枚举实例,表示加密算法类型使用 ECDSA_SECP384R1_SHA384

    ECDSA_SECP521R1_SHA512

    ECDSA_SECP521R1_SHA512
    

    功能:创建一个 ECDSA_SECP521R1_SHA512 类型的枚举实例,表示加密算法类型使用 ECDSA_SECP521R1_SHA512

    ED25519

    ED25519
    

    功能:创建一个 ED25519 类型的枚举实例,表示加密算法类型使用 ED25519。

    ED448

    ED448
    

    功能:创建一个 ED448 类型的枚举实例,表示加密算法类型使用 ED448。

    RSA_PKCS1_SHA256

    RSA_PKCS1_SHA256
    

    功能:创建一个 RSA_PKCS1_SHA256 类型的枚举实例,表示加密算法类型使用 RSA_PKCS1_SHA256

    RSA_PKCS1_SHA384

    RSA_PKCS1_SHA384
    

    功能:创建一个 RSA_PKCS1_SHA384 类型的枚举实例,表示加密算法类型使用 RSA_PKCS1_SHA384

    RSA_PKCS1_SHA512

    RSA_PKCS1_SHA512
    

    功能:创建一个 RSA_PKCS1_SHA512 类型的枚举实例,表示加密算法类型使用 RSA_PKCS1_SHA512

    RSA_PSS_PSS_SHA256

    RSA_PSS_PSS_SHA256
    

    功能:创建一个 RSA_PSS_PSS_SHA256 类型的枚举实例,表示加密算法类型使用 RSA_PSS_PSS_SHA256

    RSA_PSS_PSS_SHA384

    RSA_PSS_PSS_SHA384
    

    功能:创建一个 RSA_PSS_PSS_SHA384 类型的枚举实例,表示加密算法类型使用 RSA_PSS_PSS_SHA384

    RSA_PSS_PSS_SHA512

    RSA_PSS_PSS_SHA512
    

    功能:创建一个 RSA_PSS_PSS_SHA512 类型的枚举实例,表示加密算法类型使用 RSA_PSS_PSS_SHA512

    RSA_PSS_RSAE_SHA256

    RSA_PSS_RSAE_SHA256
    

    功能:创建一个 RSA_PSS_RSAE_SHA256 类型的枚举实例,表示加密算法类型使用 RSA_PSS_RSAE_SHA256

    RSA_PSS_RSAE_SHA384

    RSA_PSS_RSAE_SHA384
    

    功能:创建一个 RSA_PSS_RSAE_SHA384 类型的枚举实例,表示加密算法类型使用 RSA_PSS_RSAE_SHA384

    RSA_PSS_RSAE_SHA512

    RSA_PSS_RSAE_SHA512
    

    功能:创建一个 RSA_PSS_RSAE_SHA512 类型的枚举实例,表示加密算法类型使用 RSA_PSS_RSAE_SHA384

    func toString()

    public func toString(): String
    

    功能:加密算法类型的字符串表示。

    RSA_PKCS1_SHA256 的字符串表示为 "rsa_pkcs1_sha256"。

    返回值:

    • String - 加密算法类型的字符串表示。

    operator func !=(SignatureSchemeType)

    public operator func !=(other: SignatureSchemeType): Bool
    

    功能:判断两者是否为不同加密算法类型。

    参数:

    返回值:

    • Bool - 不相同返回 true;否则,返回 false。

    operator func ==(SignatureSchemeType)

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

    功能:判断两者是否为同一加密算法类型。

    参数:

    返回值:

    • Bool - 相同返回 true;否则,返回 false。

    enum SignatureType

    public enum SignatureType <: ToString & Equatable<SignatureType> {
        | DSA
        | ECDSA
        | RSA
    }
    

    功能:签名算法类型,用于认证真实性。参见 RFC5246 7.4.1.4.1 章节。

    父类型:

    DSA

    DSA
    

    功能:创建一个 DSA 类型的枚举实例,表示采用数字签名算法。

    ECDSA

    ECDSA
    

    功能:创建一个 ECDSA 类型的枚举实例,表示采用椭圆曲线数字签名算法。

    RSA

    RSA
    

    功能:创建一个 RSA 类型的枚举实例,表示采用 RSA 加密算法。

    func toString()

    public func toString(): String
    

    功能:转换为签名算法的字符串表示。

    返回值:

    • String - 签名算法的名称。

    operator func !=(SignatureType)

    public operator func !=(other: SignatureType) : Bool
    

    功能:判断两者是否为不同的签名算法。

    参数:

    返回值:

    • Bool - 不相同返回 true;否则,返回 false

    operator func ==(SignatureType)

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

    功能:判断两者是否为相同的签名算法。

    参数:

    返回值:

    • Bool - 相同返回 true;否则,返回 false

    enum TlsClientIdentificationMode

    public enum TlsClientIdentificationMode {
        | Disabled
        | Optional
        | Required
    }
    

    功能:服务端对客户端证书的认证模式。

    Disabled

    Disabled
    

    功能:表示服务端不校验客户端证书,客户端可以不发送证书和公钥,即单向认证。

    Optional

    Optional
    

    功能:表示服务端校验客户端证书,但客户端可以不提供证书及公钥,不提供时则单向认证,提供时则为双向认证。

    Required

    Required
    

    功能:表示服务端校验客户端证书,并且要求客户端必须提供证书和公钥,即双向认证。

    enum TlsVersion

    public enum TlsVersion <: ToString {
        | V1_2
        | V1_3
        | Unknown
    }
    

    功能:TLS 协议版本

    父类型:

    Unknown

    Unknown
    

    功能:表示未知协议版本。

    V1_2

    V1_2
    

    功能:表示 TLS 1.2。

    V1_3

    V1_3
    

    功能:表示 TLS 1.3。

    func toString()

    public override func toString(): String
    

    功能:返回当前 TlsVersion 的字符串表示。

    返回值:

    结构体

    struct CipherSuite

    public struct CipherSuite <: ToString & Equatable<CipherSuite>
    

    功能:TLS 中的密码套件。

    父类型:

    static prop allSupported

    public static prop allSupported: Array<CipherSuite>
    

    功能:返回所有支持的密码套件。

    返回值:存放密码套件的数组。

    类型:Array<CipherSuite>

    func toString()

    public func toString(): String
    

    功能:返回密码套件名称。

    返回值:

    • String - 密码套件名称。

    operator func !=(CipherSuite)

    public operator func !=(that: CipherSuite): Bool
    

    功能:判断两个密码套件是否不等。

    参数:

    • that: CipherSuite - 被比较的密码套件对象。

    返回值:

    • Bool - 若不等,则返回 true;反之,返回 false

    operator func ==(CipherSuite)

    public operator func ==(that: CipherSuite): Bool
    

    功能:判断两个密码套件是否相等。

    参数:

    • that: CipherSuite - 被比较的密码套件对象。

    返回值:

    • Bool - 若相等,则返回 true;反之,返回 false

    struct TlsClientConfig

    public struct TlsClientConfig
    

    功能:客户端配置。

    var keylogCallback

    public var keylogCallback: ?(TlsSocket, String) -> Unit = None
    

    功能:握手过程的回调函数,提供 TLS 初始秘钥数据,用于调试和解密记录使用。

    类型:?(TlsSocket, String) -> Unit

    var verifyMode

    public var verifyMode: CertificateVerifyMode = CertificateVerifyMode.Default
    

    功能:设置或获取证书认证模式,默认为 Default

    类型:CertificateVerifyMode

    prop alpnProtocolsList

    public mut prop alpnProtocolsList: Array<String>
    

    功能:要求的应用层协议名称。若列表为空,则客户将不协商应用层协议。

    类型:Array<String>

    异常:

    prop cipherSuitesV1_2

    public mut prop cipherSuitesV1_2: ?Array<String>
    

    功能:基于 TLS 1.2 协议下的加密套。

    类型:?Array<String>

    异常:

    prop cipherSuitesV1_3

    public mut prop cipherSuitesV1_3: ?Array<String>
    

    功能:基于 TLS 1.3 协议下的加密套。

    类型:?Array<String>

    异常:

    prop clientCertificate

    public mut prop clientCertificate: ?(Array<X509Certificate>, PrivateKey)
    

    功能:客户端证书和私钥。

    类型:?(Array<X509Certificate>, PrivateKey)

    prop domain

    public mut prop domain: ?String
    

    功能:读写要求的服务端主机地址 (SNI), None 表示不要求。

    类型:?String

    异常:

    prop maxVersion

    public mut prop maxVersion: TlsVersion
    

    功能:支持的 TLS 最大的版本。

    注意:

    当仅设置 maxVersion 而未设置 minVersion ,或设置的 maxVersion 低于 minVersion ,将会在握手阶段抛出 TlsException

    类型:TlsVersion

    prop minVersion

    public mut prop minVersion: TlsVersion
    

    功能:支持的 TLS 最小的版本。

    注意:

    当仅设置 minVersion 而未设置 maxVersion ,或设置的 minVersion 高于 maxVersion ,将会在握手阶段抛出 TlsException

    类型:TlsVersion

    prop securityLevel

    public mut prop securityLevel: Int32
    

    功能:指定客户端的安全级别,默认值为2,可选参数值在 0-5 内,参数值含义参见 openssl-SSL_CTX_set_security_level 说明。

    类型:Int32

    prop signatureAlgorithms

    public mut prop signatureAlgorithms: ?Array<SignatureAlgorithm>
    

    功能:指定保序的签名和哈希算法。在值为 None 或者列表为空时,客户端会使用默认的列表。指定列表后,客户端可能不会发送不合适的签名算法。 参见 RFC5246 7.4.1.4.1 (TLS 1.2) 章节, RFC8446 4.2.3. (TLS 1.3) 章节。

    类型:?Array<SignatureAlgorithm>

    init()

    public init()
    

    功能:构造 TlsClientConfig

    struct TlsServerConfig

    public struct TlsServerConfig
    

    功能:服务端配置。

    var clientIdentityRequired

    public var clientIdentityRequired: TlsClientIdentificationMode = Disabled
    

    功能:设置或获取服务端要求客户端的认证模式,默认不要求客户端认证服务端证书,也不要求客户端发送本端证书。

    类型:TlsClientIdentificationMode

    var keylogCallback

    public var keylogCallback: ?(TlsSocket, String) -> Unit = None
    

    功能:握手过程的回调函数,提供 TLS 初始秘钥数据,用于调试和解密记录使用。

    类型:?(TlsSocket, String) -> Unit

    var verifyMode

    public var verifyMode: CertificateVerifyMode = CertificateVerifyMode.Default
    

    功能:设置或获取认证模式,默认认证系统证书。

    类型:CertificateVerifyMode

    prop cipherSuitesV1_2

    public mut prop cipherSuitesV1_2: Array<String>
    

    功能:基于 TLS 1.2 协议下的加密套。

    类型:Array<String>

    异常:

    prop cipherSuitesV1_3

    public mut prop cipherSuitesV1_3: Array<String>
    

    功能:基于 TLS 1.3 协议下的加密套。

    类型:Array<String>

    异常:

    prop dhParameters

    public mut prop dhParameters: ?DHParamters
    

    功能:指定服务端的 DH 密钥参数,默认为 None, 默认情况下使用 openssl 自动生成的参数值。

    类型:?DHParamters

    prop maxVersion

    public mut prop maxVersion: TlsVersion
    

    功能:支持的最大 TLS 版本。

    注意:

    当仅设置 maxVersion 而未设置 minVersion ,或设置的 maxVersion 低于 minVersion ,将会在握手阶段抛出 TlsException

    类型:TlsVersion

    prop minVersion

    public mut prop minVersion: TlsVersion
    

    功能:支持的最小 TLS 版本。

    注意:

    当仅设置 minVersion 而未设置 maxVersion ,或设置的 minVersion 高于 maxVersion ,将会在握手阶段抛出 TlsException

    类型:TlsVersion

    prop securityLevel

    public mut prop securityLevel: Int32
    

    功能:指定服务端的安全级别,默认值为2,可选参数值在 [0,5] 内,参数值含义参见 openssl-SSL_CTX_set_security_level 说明。 功能:指定服务端的安全级别,默认值为2,可选参数值在 0-5 内,参数值含义参见 openssl-SSL_CTX_set_security_level 说明。

    类型:Int32

    异常:

    prop serverCertificate(Array<X509Certificate>, PrivateKey)

    public mut prop serverCertificate: (Array<X509Certificate>, PrivateKey)
    

    功能:服务端证书和对应的私钥文件。

    类型:(Array<X509Certificate>, PrivateKey)

    prop supportedAlpnProtocols

    public mut prop supportedAlpnProtocols: Array<String>
    

    功能:应用层协商协议,若客户端尝试协商该协议,服务端将与选取其中相交的协议名称。若客户端未尝试协商协议,则该配置将被忽略。

    类型:Array<String>

    异常:

    init(Array<X509Certificate>, PrivateKey)

    public init(certChain: Array<X509Certificate>, certKey: PrivateKey)
    

    功能:构造 TlsServerConfig 对象。

    参数:

    struct TlsSession

    public struct TlsSession <: Equatable<TlsSession> & ToString & Hashable
    

    功能:此结构体表示已建立的客户端会话。此结构体实例用户不可创建,其内部结构对用户不可见。

    当客户端 TLS 握手成功后,将会生成一个会话,当连接因一些原因丢失后,客户端可以通过这个会话 id 复用此次会话,省略握手流程。

    父类型:

    func hashCode()

    public override func hashCode(): Int64
    

    功能:生成会话 id 哈希值。

    返回值:

    • Int64 - 会话 id 哈希值。

    func toString()

    public override func toString(): String
    

    功能:生成会话 id 字符串。

    返回值:

    operator func !=(TlsSession)

    public override operator func !=(other: TlsSession)
    

    功能:判断会话 id 是否不同。

    参数:

    返回值:

    • Unit - 若会话对象不同,返回 true;否则,返回 false

    operator func ==(TlsSession)

    public override operator func ==(other: TlsSession)
    

    功能:判断会话 id 是否相同。

    参数:

    返回值:

    • Unit - 若会话对象相同,返回 true;否则,返回 false

    异常类

    class TlsException

    public class TlsException <: Exception
    

    功能:TLS 处理出现错误时抛出的异常。

    父类型:

    init()

    public init()
    

    功能:创建 TlsException 实例,异常提示消息为空。

    init(String)

    public init(message: String)
    

    功能:根据异常信息创建 TlsException 实例。

    参数:

    • message: String - 异常信息。

    服务端证书及公钥在一份文件中

    说明:

    需要自行准备证书文件。

    import std.io.*
    import std.{fs.*, collection.*}
    import net.tls.*
    import crypto.x509.{X509Certificate,PrivateKey, Pem, PemEntry,DerBlob}
    
    let certificatePath = "/etc/myserver/cert-and-key.pem"
    
    
    func parsePem(text: String): (Array<X509Certificate>, PrivateKey) {
        let pem = Pem.decode(text)
        let chain = pem |>
            filter<PemEntry> { entry => entry.label == PemEntry.LABEL_CERTIFICATE } |>
            map<PemEntry, X509Certificate> { entry => X509Certificate.decodeFromDer(entry.body ?? DerBlob()) } |>
            collectArray
    
        let key = (pem |>
            filter<PemEntry> { entry => entry.label == PemEntry.LABEL_PRIVATE_KEY} |>
            map<PemEntry, PrivateKey> { entry => PrivateKey.decodeDer(entry.body ?? DerBlob()) } |>
            first) ?? throw Exception("No private key found in the PEM file")
    
        if (chain.isEmpty()) {
            throw Exception("No certificates found in the PEM file")
        }
    
        return (chain, key)
    }
    
    func readTextFromFile(path: String): String {
        var fileString = ""
        try (file = File(path, OpenOption.Open(true, false))) {
            fileString = String.fromUtf8(readToEnd(file))
            ()
        }
        fileString
    }
    
    main() {
        // 对证书及私钥进行解析
        let pem = readTextFromFile(certificatePath)
    
        let (certificate, privateKey) = parsePem(pem)
    
        var _ = TlsServerConfig(certificate, privateKey)
    
        // 进行https服务,请参阅其他服务器示例
    }
    

    客户端示例

    import std.net.TcpSocket
    import crypto.x509.{X509Certificate,PrivateKey}
    import net.tls.*
    
    main() {
        var config = TlsClientConfig()
        config.verifyMode = TrustAll
        config.alpnProtocolsList = ["h2"]
    
        // 用于恢复会话
        var lastSession: ?TlsSession = None
    
        while (true) { // 重新连接环路
            try (socket = TcpSocket("127.0.0.1", 8443)) {
                socket.connect() // 首先进行 TCP 连接
                try (tls = TlsSocket.client(socket, clientConfig: config, session: lastSession)) {
                    try {
                        tls.handshake()  // then we are negotiating TLS
                        lastSession = tls.session // 如果成功协商下一次重新连接,将记住会话
                    } catch (e: Exception) {
                        lastSession = None   // 如果协商失败,将删除会话
                        throw e
                    }
    
                   // tls实例已完成
                   tls.write("Hello, peer! Let's discuss our personal secrets.\n".toArray())
                }
            } catch (e: Exception) {
                println("client connection failed ${e}, retrying...")
            }
        }
    }
    

    证书热更新

    import std.net.StreamingSocket
    import crypto.x509.{X509Certificate,PrivateKey}
    import net.tls.*
    
    class MyServer {
        private var currentConfig: TlsServerConfig
    
        init(initialConfig: TlsServerConfig) { currentConfig = initialConfig }
    
        /**
          * 更改带有密钥的证书只会影响新的连接
          */
        public mut prop certificate: (Array<X509Certificate>, PrivateKey) {
            get() { currentConfig.serverCertificate }
            set(newCertificate) { currentConfig.serverCertificate = newCertificate }
        }
    
        public func onAcceptedConnection(client: StreamingSocket) {
            try (tls = TlsSocket.server(client, serverConfig: currentConfig)) {
                tls.handshake()
            }
        }
    }
    

    服务端示例

    说明:

    需要自行准备证书文件。

    import std.io.*
    import std.fs.{File, OpenOption}
    import std.net.{TcpServerSocket, TcpSocket}
    import crypto.x509.{X509Certificate, PrivateKey}
    import net.tls.*
    
    //证书及私钥路径,用户需自备
    let certificatePath = "./files/apiserver.crt"
    let certificateKeyPath = "./files/apiserver.key"
    
    main() {
        // 对证书以及私钥进行解析
        let pem = readTextFromFile(certificatePath)
        let keyText = readTextFromFile(certificateKeyPath)
    
        let certificate = X509Certificate.decodeFromPem(pem)
        let privateKey = PrivateKey.decodeFromPem(keyText)
    
        let config = TlsServerConfig(certificate, privateKey)
    
        //可选:允许恢复TLS会话
        let sessions= TlsSessionContext.fromName("my-server")
    
        try (server = TcpServerSocket(bindAt:8443)) {
            server.bind()
    
            server.acceptLoop { clientSocket =>
                try (tls = TlsSocket.server(clientSocket, serverConfig: config, sessionContext: sessions)) {
                    tls.handshake()
                    let buffer = Array<Byte>(100, repeat: 0)
                    tls.read(buffer)
                    println(buffer) // operate received data.
                }
            }
        }
    }
    
    // 简化示例代码的辅助函数
    extend TcpServerSocket {
        func acceptLoop(handler: (TcpSocket) -> Unit) {
            while (true) {
                let client = accept()
                spawn {
                    try {
                        handler(client)
                    } finally {
                        client.close()
                    }
                }
            }
        }
    }
    
    func readTextFromFile(path: String): String {
        var str = ""
        try (file = File(path, OpenOption.Open(true, false))) {
            str = String.fromUtf8(readToEnd(file))
        }
        str
    }
    

    serialization 模块

    serialization 功能介绍

    serialization 模块提供了序列化和反序列化能力。

    serialization 模块的包列表

    serialization 模块提供了如下包:

    包名功能
    serializationserialization 包提供了序列化和反序列化的能力。

    serialization.serialization 包

    功能介绍

    serialization 包提供了序列化和反序列化的能力。

    序列化(serialization)是指将数据结构或对象状态转换成可取用格式(例如存成文件,存于缓冲,或经由网络中发送),以留待后续在相同或另一台计算机环境中,能恢复原先状态的过程。相对地,从一系列字节提取数据结构的反向操作,即反序列化(deserialization)。

    用户定义的类型,可以通过实现 Serializable 接口,来支持序列化和反序列化。

    API列表

    函数

    函数名功能
    field<T>(String, T)用于将一组数据 namedata 封装到 Field 对象中。

    接口

    接口名功能
    Serializable用于规范序列化。

    类名功能
    DataModel中间数据层。
    DataModelBool此类为 DataModel 的子类,实现对 Bool 类型数据的封装。
    DataModelFloat此类为 DataModel 的子类,实现对 Float64 类型数据的封装。
    DataModelInt此类为 DataModel 的子类,实现对 Int64 类型数据的封装。
    DataModelNull此类为 DataModel 的子类,实现对 Null 类型数据的封装。
    DataModelSeq此类为 DataModel 的子类,实现对 ArrayList<DataModel> 类型数据的封装。
    DataModelString此类为 DataModel 的子类,实现对 String 类型数据的封装。
    DataModelStruct此类为 DataModel 的子类,用来实现 class 对象到 DataModel 的转换。
    Field用于存储 DataModelStruct 的元素。

    异常类

    异常类名功能
    DataModelExceptionDataModel 的异常类。

    函数

    func field<T>(String, T) where T <: Serializable<T>

    public func field<T>(name: String, data: T) : Field where T <: Serializable<T>
    

    功能:此函数用于将一组数据 namedata 封装到 Field 对象中。处理一组数据 namedata,将 data 序列化为 DataModel 类型,并将二者封装到 Field 对象中。

    参数:

    • name: String - String 类型,name 字段为 "" 时行为与为其它字符串时一致。
    • data: T - T 类型,T 类型必须实现 Serializable<T> 接口。

    返回值:

    • Field - 封装了 namedataField 对象。

    接口

    interface Serializable

    public interface Serializable<T> {
        func serialize(): DataModel
        static func deserialize(dm: DataModel): T
    }
    

    功能:用于规范序列化。

    func deserialize(DataModel)

    static func deserialize(dm: DataModel): T
    

    功能:将 DataModel 反序列化为对象。

    说明:

    支持实现 Serializable 的类型包括:

    返回值:

    • T - 反序列化的对象。

    func serialize()

    func serialize(): DataModel
    

    功能:将自身序列化为 DataModel

    返回值:

    extend<T> Array<T> <: Serializable<Array<T>> where T <: Serializable<T>

    extend<T> Array<T> <: Serializable<Array<T>> where T <: Serializable<T>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): Array<T>
    

    功能:将 DataModel 反序列化为 Array<T>。

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 Array<T> 序列化为 DataModelSeq

    返回值:

    extend<T> ArrayList<T> <: Serializable<ArrayLis<T>> where T <: Serializable<T>

    extend<T> ArrayList<T> <: Serializable<ArrayList<T>> where T <: Serializable<T>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): ArrayList<T>
    

    功能:将 DataModel 反序列化为 ArrayList<T>。

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 ArrayList<T> 序列化为 DataModelSeq

    返回值:

    extend Bool <: Serializable

    extend Bool <: Serializable<Bool>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): Bool
    

    功能:将 DataModel 反序列化为 Bool

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 Bool 序列化为 DataModelBool

    返回值:

    extend Float16 <: Serializable

    extend Float16 <: Serializable<Float16>
    

    拓展 Float16 以实现 Serializable

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): Float16
    

    功能:将 DataModel 反序列化为 Float16

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 Float16 序列化为 DataModelFloat

    返回值:

    extend Float32 <: Serializable

    extend Float32 <: Serializable<Float32>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): Float32
    

    功能:将 DataModel 反序列化为 Float32

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 Float32 序列化为 DataModelFloat

    返回值:

    extend Float64 <: Serializable

    extend Float64 <: Serializable<Float64>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): Float64
    

    功能:将 DataModel 反序列化为 Float64

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 Float64 序列化为 DataModelFloat

    返回值:

    extend HashMap <: Serializable

    extend<K, V> HashMap<K, V> <: Serializable<HashMap<K, V>> where K <: Serializable<K> & Hashable & Equatable<K>, V <: Serializable<V>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): HashMap<K, V>
    

    功能:将 DataModel 反序列化为 HashMap<K, V>。

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 HashMap<K, V> 序列化为 DataModelSeq

    返回值:

    异常:

    extend<T> HashSet<T> <: Serializable<HashSet<T>> where T <: Serializable<T> & Hashable & Equatable<T>

    extend<T> HashSet<T> <: Serializable<HashSet<T>> where T <: Serializable<T> & Hashable & Equatable<T>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): HashSet<T>
    

    功能:将 DataModel 反序列化为 HashSet<T>。

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 HashSet<T> 序列化为 DataModelSeq

    返回值:

    extend Int16 <: Serializable

    extend Int16 <: Serializable<Int16>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): Int16
    

    功能:将 DataModel 反序列化为 Int16

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 Int16 序列化为 DataModelInt

    返回值:

    extend Int32 <: Serializable

    extend Int32 <: Serializable<Int32>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): Int32
    

    功能:将 DataModel 反序列化为 Int32

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 Int32 序列化为 DataModelInt

    返回值:

    extend Int64 <: Serializable

    extend Int64 <: Serializable<Int64>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): Int64
    

    功能:将 DataModel 反序列化为 Int64

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 Int64 序列化为 DataModelInt

    返回值:

    extend Int8 <: Serializable

    extend Int8 <: Serializable<Int8>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): Int8
    

    功能:将 DataModel 反序列化为 Int8

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 Int8 序列化为 DataModelInt

    返回值:

    extend<T> Option<T> <: Serializable<Option<T>> where T <: Serializable<T>

    extend<T> Option<T> <: Serializable<Option<T>> where T <: Serializable<T>
    

    父类型:

    func deserialize()

    static public func deserialize(dm: DataModel): Option<T>
    

    功能:将 DataModel 反序列化为 Option<T>。

    参数:

    返回值:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 Option<T> 中的 T 序列化为 DataModel

    返回值:

    extend Rune <: Serializable

    extend Rune <: Serializable<Rune>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): Rune
    

    功能:将 DataModel 反序列化为 Rune

    参数:

    返回值:

    • Rune - 反序列化后的字符。

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 Rune 序列化为 DataModelString

    返回值:

    extend String <: Serializable

    extend String <: Serializable<String>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): String
    

    功能:将 DataModel 反序列化为 String

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 String 序列化为 DataModelString

    返回值:

    extend UInt16 <: Serializable

    extend UInt16 <: Serializable<UInt16>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): UInt16
    

    功能:将 DataModel 反序列化为 UInt16

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 UInt16 序列化为 DataModelInt

    返回值:

    extend UInt32 <: Serializable

    extend UInt32 <: Serializable<UInt32>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): UInt32
    

    功能:将 DataModel 反序列化为 UInt32

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 UInt32 序列化为 DataModelInt

    返回值:

    extend UInt64 <: Serializable

    extend UInt64 <: Serializable<UInt64>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): UInt64
    

    功能:将 DataModel 反序列化为 UInt64

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 UInt64 序列化为 DataModelInt

    返回值:

    extend UInt8 <: Serializable

    extend UInt8 <: Serializable<UInt8>
    

    父类型:

    func deserialize(DataModel)

    static public func deserialize(dm: DataModel): UInt8
    

    功能:将 DataModel 反序列化为 UInt8

    参数:

    返回值:

    异常:

    func serialize()

    public func serialize(): DataModel
    

    功能:将 UInt8 序列化为 DataModelInt

    返回值:

    class DataModel

    public abstract class DataModel
    

    功能:此类为中间数据层。

    class DataModelBool

    public class DataModelBool <: DataModel {
        public init(bv: Bool)
    }
    

    功能:此类为 DataModel 的子类,实现对 Bool 类型数据的封装。

    父类型:

    init(Bool)

    public init(bv: Bool)
    

    功能:构造一个具有初始数据的 DataModelBool 实例。

    参数:

    • bv: Bool - 传入的 Bool 类型的数据。

    func getValue()

    public func getValue(): Bool
    

    功能:获取 DataModelBool 中的数据。

    返回值:

    class DataModelFloat

    public class DataModelFloat <: DataModel {
        public init(fv: Float64)
        public init(v: Int64)
    }
    

    功能:此类为 DataModel 的子类,实现对 Float64 类型数据的封装。

    父类型:

    init(Float64)

    public init(fv: Float64)
    

    功能:构造一个具有初始数据的 DataModelFloat 实例。

    参数:

    init(Int64)

    public init(v: Int64)
    

    功能:构造一个具有初始数据的 DataModelFloat 实例。

    参数:

    func getValue()

    public func getValue(): Float64
    

    功能:获取 DataModelFloat 中的数据。

    返回值:

    class DataModelInt

    public class DataModelInt <: DataModel {
        public init(iv: Int64)
    }
    

    功能:此类为 DataModel 的子类,实现对 Int64 类型数据的封装。

    父类型:

    init(Int64)

    public init(iv: Int64)
    

    功能:构造一个具有初始数据的 DataModelInt 实例。

    参数:

    func getValue()

    public func getValue(): Int64
    

    功能:获取 DataModelInt 中的数据。

    返回值:

    class DataModelNull

    public class DataModelNull <: DataModel
    

    功能:此类为 DataModel 的子类,实现对 Null 类型数据的封装。

    父类型:

    class DataModelSeq

    public class DataModelSeq <: DataModel {
        public init()
        public init(list: ArrayList<DataModel>)
    }
    

    功能:此类为 DataModel 的子类,实现对 ArrayList<DataModel> 类型数据的封装。

    父类型:

    init()

    public init()
    

    功能:构造一个参数为空的 DataModelSeq 实例。其中的数据默认为空的 ArrayList<DataModel>。

    init(ArrayList<DataModel>)

    public init(list: ArrayList<DataModel>)
    

    功能:构造一个具有初始数据的 DataModelSeq 实例。

    参数:

    func add(DataModel)

    public func add(dm: DataModel)
    

    功能:在 DataModelSeq 末尾增加一个 DataModel 数据。

    参数:

    func getItems()

    public func getItems(): ArrayList<DataModel>
    

    功能:获取 DataModelSeq 中的数据。

    返回值:

    class DataModelString

    public class DataModelString <: DataModel {
        public init(sv: String)
    }
    

    功能:此类为 DataModel 的子类,实现对 String 类型数据的封装。

    父类型:

    init(String)

    public init(sv: String)
    

    功能:构造一个具有初始数据的 DataModelString

    参数:

    func getValue()

    public func getValue(): String
    

    功能:获取 DataModelString 中的数据。

    返回值:

    class DataModelStruct

    public class DataModelStruct <: DataModel {
        public init()
        public init(list: ArrayList<Field>)
    }
    

    功能:此类为 DataModel 的子类,用来实现 class 对象到 DataModel 的转换。

    父类型:

    init()

    public init()
    

    功能:构造一个空参的 DataModelStructfields 默认为空的 ArrayList<Field>。

    init(ArratList<Field>)

    public init(list: ArrayList<Field>)
    

    功能:构造一个具有初始数据的 DataModelStruct

    参数:

    func add(Field)

    public func add(fie: Field): DataModelStruct
    

    功能:添加数据 fieDataModelStruct 中。

    参数:

    返回值:

    func get(String)

    public func get(key: String): DataModel
    

    功能:获取 key 对应的数据。

    参数:

    返回值:

    func getFields()

    public func getFields(): ArrayList<Field>
    

    功能:获取 DataModelStruct 的数据集合。

    返回值:

    class Field

    public class Field {
        public init(name: String, data: DataModel)
    }
    

    功能:用于存储 DataModelStruct 的元素。

    init(String, DataModel)

    public init(name: String, data: DataModel)
    

    功能:Field 的构造函数。

    参数:

    • name: String - name 字段值,name 字段为 "" 时行为与为其它字符串时一致。
    • data: DataModel - data 字段值。

    func getData()

    public func getData(): DataModel
    

    功能:获取 data 字段。

    返回值:

    func getName()

    public func getName(): String
    

    功能:获取 name 字段。

    返回值:

    异常类

    class DataModelException

    public class DataModelException <: Exception
    

    功能:DataModel 的异常类。

    父类型:

    init()

    public init()
    

    功能:创建 DataModelException 实例。

    init(String)

    public init(message: String)
    

    功能:根据异常信息创建 DataModelException 实例。

    参数:

    • message: String - 异常信息提示字符串。

    class 序列化和反序列化

    import serialization.serialization.*
    import std.math.*
    import encoding.json.*
    
    /* 通过实现 Serializable 接口,来实现对自定义类型的序列化和反序列化功能 */
    class Abc <: Serializable<Abc> {
        var name: String = "Abcde"
        var age: Int64 = 555
        var loc: Option<Location> = Option<Location>.None
    
        /* 实现 Serializable 接口的序列化方法 */
        public func serialize(): DataModel {
            return DataModelStruct().add(field<String>("name", name)).add(field<Int64>("age", age)).add(field<Option<Location>>("loc", loc))
        }
    
        /* 实现反序列化方法 */
        public static func deserialize(dm: DataModel): Abc {
            let dms = match (dm) {
                case data: DataModelStruct => data
                case _ => throw Exception("this data is not DataModelStruct")
            }
            let result = Abc()
            result.name = String.deserialize(dms.get("name"))
            result.age = Int64.deserialize(dms.get("age"))
            result.loc = Option<Location>.deserialize(dms.get("loc"))
            return result
        }
    }
    
    class Location <: Serializable<Location> {
        var time: Int64 = 666
        var heheh: Rune = 'T'
    
        /* 实现 Serializable 接口的序列化方法 */
        public func serialize(): DataModel {
            return DataModelStruct().add(field<Int64>("time", time)).add(field<Rune>("heheh", heheh))
        }
    
        /* 实现反序列化方法 */
        public static func deserialize(dm: DataModel): Location {
            let dms = match (dm) {
                case data: DataModelStruct => data
                case _ => throw Exception("this data is not DataModelStruct")
            }
            let result = Location()
            result.time = Int64.deserialize(dms.get("time"))
            result.heheh = Rune.deserialize(dms.get("heheh"))
            return result
        }
    }
    
    main(): Unit {
        let dd = Abc()
        let aa: JsonValue = dd.serialize().toJson()
        let bb: JsonObject = (aa as JsonObject).getOrThrow()
        let v1 = (bb.get("name").getOrThrow() as JsonString).getOrThrow()
        let v2 = (bb.get("age").getOrThrow() as JsonInt).getOrThrow()
        let v3 = bb.get("loc").getOrThrow()
        println(v1.getValue())
        println(v2.getValue())
        println(v3.toString())
        println("===========")
        let aaa = ##"{"age": 123, "loc": { "heheh": "H", "time": 45 }, "name": "zhangsan"}"##
        let bbb = JsonValue.fromStr(aaa)
        let ccc = (bbb as JsonObject).getOrThrow()
        let v4 = (ccc.get("name").getOrThrow() as JsonString).getOrThrow()
        let v5 = (ccc.get("age").getOrThrow() as JsonInt).getOrThrow()
        let v6 = (ccc.get("loc").getOrThrow() as JsonObject).getOrThrow()
        let v7 = (v6.get("time").getOrThrow() as JsonInt).getOrThrow()
        let v8 = (v6.get("heheh").getOrThrow() as JsonString).getOrThrow()
        println(v4.getValue())
        println(v5.getValue())
        println(v7.getValue())
        println(v8.getValue())
    }
    

    运行结果如下:

    Abcde
    555
    null
    ===========
    zhangsan
    123
    45
    H
    

    HashSet 和 HashMap 序列化

    import std.collection.*
    import serialization.serialization.*
    import encoding.json.*
    
    main(): Unit {
        let s: HashSet<Values> = HashSet<Values>([Values(3), Values(5), Values(7)])
        let seris: DataModel = s.serialize()
        println(seris.toJson().toJsonString())
        println("===========")
        let m: HashMap<String, Values> = HashMap<String, Values>([("1", Values(3)), ("2", Values(6)), ("3", Values(9))])
        let serim: DataModel = m.serialize()
        print(serim.toJson().toJsonString())
    }
    
    class Values <: Hashable & Equatable<Values> & Serializable<Values> {
        var m_data: Int64
    
        init(m_data: Int64) {
            this.m_data = m_data
        }
    
        public func hashCode(): Int64 {
            return this.m_data
        }
    
        public operator func ==(right: Values): Bool {
            let a = (this.m_data == right.m_data)
            if (a) { return true } else { return false }
        }
    
        public operator func !=(right: Values): Bool {
            let a = (this.m_data != right.m_data)
            if (a) { return true } else { return false }
        }
    
        /* 实现 Serializable 接口的序列化方法 */
        public func serialize(): DataModel {
            return DataModelStruct().add(field<Int64>("m_data", m_data))
        }
    
        /* 实现反序列化方法 */
        public static func deserialize(dm: DataModel): Values {
            let dms: DataModelStruct = match (dm) {
                case data: DataModelStruct => data
                case _ => throw Exception("this data is not DataModelStruct")
            }
            let result = Values(0)
            result.m_data = Int64.deserialize(dms.get("m_data"))
            return result
        }
    }
    

    运行结果如下:

    [
      {
        "m_data": 3
      },
      {
        "m_data": 5
      },
      {
        "m_data": 7
      }
    ]
    ===========
    {
      "1": {
        "m_data": 3
      },
      "2": {
        "m_data": 6
      },
      "3": {
        "m_data": 9
      }
    }