仓颉编程语言库 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.*`。
```

模块列表

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

模块名	功能
std	std 模块意指标准库，标准库是指在编程语言中预先定义的一组函数、类、结构体等，旨在提供常用的功能和工具，以便开发者能够更快速、更高效地编写程序。
compress	compress 模块提供压缩解压功能。
crypto	crypto 模块提供安全加密能力。
encoding	encoding 模块提供字符编解码功能。
fuzz	fuzz 模块提供基于覆盖率反馈的模糊测试能力。
log	log 模块提供了日志记录相关的能力。
net	net 模块提供了网络通信相关的能力。
serialization	serialization 模块提供了序列化和反序列化能力。

std 模块

std 功能介绍

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

仓颉标准库提供的能力包括（不限于）：

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

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

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

std 模块的包列表

std 模块提供了如下包：

包名	功能
core	core 包是标准库的核心包，提供了适用仓颉语言编程最基本的一些 API 能力。
argopt	argopt 包提供从命令行参数字符串解析出参数名和参数值的相关能力。
ast	ast 包主要包含了仓颉源码的语法解析器和仓颉语法树节点，提供语法解析函数。
binary	binary 包提供了基础数据类型和二进制字节数组的不同端序转换接口，以及端序反转接口。
collection	collection 包提供了常见数据结构的高效实现、相关抽象的接口的定义以及在集合类型中常用的函数功能。
collection.concurrent	collection.concurrent 包提供了并发安全的集合类型实现。
console	console 包提供和标准输入、标准输出、标准错误进行交互的方法。
convert	convert 包提供从字符串转到特定类型的 Convert 系列函数。
crypto.digest	crypto.digest 包提供常用摘要算法的通用接口，包括 MD5、SHA1、SHA224、SHA256、SHA384、SHA512、HMAC、SM3。
database.sql	database.sql 包提供仓颉访问数据库的接口。
ffi.python	ffi.python 包提供仓颉与 Python 语言互操作调用的能力，以兼容强大的计算和 AI 生态。
format	format 包提供格式化能力，主要为将仓颉类型实例转换为格式化字符串。
fs	fs（file system）包提供对文件、文件夹、路径、文件元数据信息的一些操作函数。
io	io 包提供程序与外部设备进行数据交换的能力。
log	log 包提供日志管理和打印功能。
math	math 包提供常见的数学运算，常数定义，浮点数处理等功能。
math.numeric	math.numeric 包对基础类型可表达范围之外提供扩展能力。
objectpool	objectpool 包提供了对象缓存和复用的功能。
os	os 包提供了包括获取或操作当前进程相关信息(如进程参数、环境变量、目录信息等)，注册回调函数及退出当前进程等能力。
os.posix	os.posix 包主要适配 POSIX 系统接口。
os.process	os.process 包主要提供 Process 进程操作接口，主要包括进程创建，标准流获取，进程等待，进程信息查询等。
overflow	overflow 包提供了溢出处理相关能力。
random	random 包提供生成伪随机数的能力。
reflect	reflect 包提供了反射功能，使得程序在运行时能够获取到各种实例的类型信息，并进行各种读写和调用操作。
regex	regex 包使用正则表达式分析处理文本的能力（仅支持 Ascii 编码字符串），支持查找、分割、替换、验证等功能。
runtime	runtime 包的作用是与程序的运行时环境进行交互，提供了一系列函数和变量，用于控制、管理和监视程序的执行。
socket	socket 包用于进行网络通信，提供启动 Socket 服务器、连接 Socket 服务器、发送数据、接收数据等功能。
sort	sort 包提供数组类型的排序函数。
sync	sync 包提供并发编程相关的能力。
time	time 包提供了与时间相关的类型，包括日期时间，时间间隔，单调时间和时区等，并提供了计算和比较的功能。
unicode	unicode 包提供了按 unicode 编码标准处理字符的能力。
unittest	unittest 包用于编写仓颉项目单元测试代码，提供包括代码编写、运行和调测在内的基本功能。
unittest.mock	unittest.mock 包提供仓颉单元测试的mock 框架，提供 API 用于创建和配置mock 对象，这些 mock 对象与真实对象拥有签名一致的 API 。
unittest.testmacro	unittest.testmacro 为单元测试框架提供了用户所需的宏。

std.core 包

功能介绍

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

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

说明：

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

API 列表

函数

函数名	功能
CJ_CORE_AddAtexitCallback(() -> Unit)	注册退出函数，当前进程退出时执行该函数。
CJ_CORE_ExecAtexitCallbacks()	执行注册的退出函数，执行到此函数直接结束当前进程。
acquireArrayRawData(Array<T>) where T <: CType	获取 Array<T> 中数据的原始指针实例，T 需要满足 CType 约束。
alignOf<T>() where T <: CType	获取类型 T 的内存对齐值。
eprint(String, Bool)	用于打印错误消息。
eprintln(String)	用于打印错误消息，末尾添加换行。
ifNone(Option<T>, () -> Unit)	如果输入是 Option.None 类型数据，则执行 action 函数。
ifSome(Option<T>, (T) -> Unit)	如果输入是 Option.Some 类型数据，则执行 action 函数。
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 所占用的内存空间大小。
zeroValue<T>()	获取一个已全零初始化的 T 类型实例。

类型别名

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

接口

接口名	功能
Any	`Any` 是所有类型的父类型，所有 `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 语言互操作的接口。

类

类名	功能
ArrayIterator<T>	数组迭代器，迭代功能详述见 `Iterable` 和 `Iterator` 接口说明。
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` 类型的迭代器，迭代功能详述见 `Iterable` 和 `Iterator` 接口说明。
StackTraceElement	表示一个异常堆栈的具体信息，包括异常发生的类名、函数名、文件名、行号。
StringBuilder	该类主要用于字符串的构建。
Thread	`Thread` 类代表一个仓颉类，可用于获取线程 ID 及名字、查询线程是否存在取消请求、注册线程未处理异常的处理函数等。
ThreadLocal<T>	该类表示仓颉线程局部变量。

枚举

枚举名	功能
AnnotationKind	表示自定义注解希望支持的位置。
Endian	枚举类型 Endian 表示运行平台的端序，分为大端序和小端序。
Ordering	Ordering 表示比较大小的结果，它包含三种情况：小于，大于和等于。
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	该结构体表示仓颉字符串，提供了构造、查找、拼接等一系列字符串操作。

异常类

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

函数

func CJ_CORE_AddAtexitCallback(() -> Unit)

public func CJ_CORE_AddAtexitCallback(callback: () -> Unit): Unit

功能：注册退出函数，当前进程退出时执行该函数。

说明：

此处建议使用 os 库内 Process.atexit 函数，除非有制作进程管理框架的需要，否则不建议使用。

参数：

callback: () ->Unit - 注册的退出函数。

func CJ_CORE_ExecAtexitCallbacks()

public func CJ_CORE_ExecAtexitCallbacks(): Unit

功能：执行注册的退出函数，执行到此函数直接结束当前进程。

说明：

此处建议使用 os 库内 Process.exit 函数，除非有制作进程管理框架的需要，否则不建议使用。

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 等的仓颉对象，否则可能造成不可预期现象。

返回值：

CPointerHandle<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 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> 类型实例，同时其封装的 T 类型实例将作为 action 函数的输入。
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 print(Bool, Bool)

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

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

注意：

下列 print、 println、 eprint、 eprintln 函数默认为 UTF-8 编码。 windows 环境需手动执行命令 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(Bool)

public func println(b: Bool): Unit

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

参数：

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

func println(Float16)

public func println(f: Float16): Unit

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

参数：

f: Float16 - 待输出的 Float16 类型数据。

func println(Float32)

public func println(f: Float32): Unit

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

参数：

f: Float32 - 待输出的 Float32 类型数据。

func println(Float64)

public func println(f: Float64): Unit

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

参数：

f: Float64 - 待输出的 Float64 类型数据。

func println(Int16)

public func println(i: Int16): Unit

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

参数：

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

func println(Int32)

public func println(i: Int32): Unit

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

参数：

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

func println(Int64)

public func println(i: Int64): Unit

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

参数：

i: Int64 - 待输出的 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 类型数据的字符串表达，末尾添加换行。

参数：

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

func println(UInt32)

public func println(i: UInt32): Unit

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

参数：

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

func println(UInt64)

public func println(i: UInt64): Unit

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

参数：

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

func println(UInt8)

public func println(i: UInt8): Unit

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

参数：

i: UInt8 - 待输出的 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 实例的内存地址是否相同。

参数：

a: Object - 一个 Object 实例。
b: Object - 另一个 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 获取。

参数：

handle: CPointerHandle<T> - 待释放的指针实例。

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

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

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

返回值：

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

func zeroValue<T>()

public unsafe func zeroValue<T>(): T

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

注意：

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

返回值：

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

类型别名

内置类型

Bool

功能：表示布尔类型，有 true 和 false 两种取值。

extend Bool <: Equatable<Bool>

extend Bool <: Equatable<Bool>

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

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 语法上下文中实现内容自动释放。

返回值：

CPointerResource<T> - 当前指针对应的 CPointerResource 实例。

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 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 的构造函数或 LibC 的 mallocCString 创建 C 风格字符串，如需在仓颉端释放，则调用 LibC 的 free 方法。

extend CString <: ToString

extend CString <: ToString

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

func asResource()

public func asResource(): CStringResource

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

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

返回值：

CStringResource - 对应的 CStringResource C 字符串资源类型实例。

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

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

注意：

该接口返回为字符串的副本，返回的子串使用完后需要手动 free。

如果 beginIndex 与字符串长度相等，将返回空指针。

参数：

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

返回值：

CString - 截取的子串。

异常：

IndexOutOfBoundsException - 如果 beginIndex 大于字符串长度，抛出异常。
IllegalMemoryException - 如果内存申请失败或内存拷贝失败时，抛出异常。

func subCString(UIntNative, UIntNative)

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

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

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

注意：

该接口返回为字符串的副本，返回的子串使用完后需要手动 free。

如果 beginIndex 等于于字符串长度，或 subLen 等于 0，返回空指针。

参数：

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

返回值：

CString - 截取的子串。

异常：

IndexOutOfBoundsException - 如果 beginIndex 大于字符串长度，抛出异常。
IllegalMemoryException - 如果内存申请失败或内存拷贝失败时，抛出异常。

func toString()

public func toString(): String

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

返回值：

String - 转换后的字符串。

Float16

功能：表示 16 位浮点数，符合 IEEE 754 中的半精度格式（binary16）。

extend Float16 <: Comparable<Float16>

extend Float16 <: Comparable<Float16>

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

func compare(Float16)

public func compare(rhs: Float16): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 <: 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 <: Comparable<Float32>

extend Float32 <: Comparable<Float32>

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

func compare(Float32)

public func compare(rhs: Float32): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 <: 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 <: Comparable<Float64>

extend Float64 <: Comparable<Float64>

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

func compare(Float64)

public func compare(rhs: Float64): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 <: 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 <: Comparable<Int16>

extend Int16 <: Comparable<Int16>

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

func compare(Int16)

public func compare(rhs: Int16): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 值。

返回值：

Int64 - 当前 Int16 值的位置信息。

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 <: Comparable<Int32>

extend Int32 <: Comparable<Int32>

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

func compare(Int32)

public func compare(rhs: Int32): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 值。

返回值：

Int64 - 当前 Int32 值的位置信息。

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 <: Comparable<Int64>

extend Int64 <: Comparable<Int64>

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

func compare(Int64)

public func compare(rhs: Int64): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ 如果小于，返回 Ordering.LT。

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 值本身。

返回值：

Int64 - 当前 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 <: Comparable<Int8>

extend Int8 <: Comparable<Int8>

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

func compare(Int8)

public func compare(rhs: Int8): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 值。

返回值：

Int64 - 当前 Int8 值的位置信息。

extend Int8 <: ToString

extend Int8 <: ToString

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

func toString()

public func toString(): String

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

返回值：

String - 转化后的字符串。

IntNative

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

extend IntNative <: Comparable<IntNative>

extend IntNative <: Comparable<IntNative>

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

func compare(IntNative)

public func compare(rhs: IntNative): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 - 往右数的个数。

返回值：

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

func position()

public func position(): Int64

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

返回值：

Int64 - 当前 IntNative 值的位置信息。

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 - 字符的字节码长度，例如中文是三个字节码长度。

异常：

IllegalArgumentException - 如果索引位置的字节码不符合首位字节码规则，会抛出异常。

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 实例。

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 值。

异常：

OverflowException - 如果与 Int64 数进行加法运算后为不合法的 Unicode 值，抛出异常。

func position()

public func position(): Int64

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

返回值：

Int64 - 当前 Rune 值的位置信息。

extend Rune <: ToString

extend Rune <: ToString

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

func toString()

public func toString(): String

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

返回值：

String - 转化后的字符串。

UInt16

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

extend UInt16 <: Comparable<UInt16>

extend UInt16 <: Comparable<UInt16>

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

func compare(UInt16)

public func compare(rhs: UInt16): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 - 往右数的个数。

返回值：

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

func position()

public func position(): Int64

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

返回值：

Int64 - 当前 UInt16 值的位置信息。

extend UInt16 <: ToString

extend UInt16 <: ToString

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

func toString()

public func toString(): String

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

返回值：

String - 转化后的字符串。

UInt32

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

extend UInt32 <: Comparable<UInt32>

extend UInt32 <: Comparable<UInt32>

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

func compare(UInt32)

public func compare(rhs: UInt32): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 - 往右数的个数。

返回值：

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

func position()

public func position(): Int64

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

返回值：

Int64 - 当前 UInt32 值的位置信息。

extend UInt32 <: ToString

extend UInt32 <: ToString

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

func toString()

public func toString(): String

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

返回值：

String - 转化后的字符串。

UInt64

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

extend UInt64 <: Comparable<UInt64>

extend UInt64 <: Comparable<UInt64>

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

func compare(UInt64)

public func compare(rhs: UInt64): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 - 往右数的个数。

返回值：

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

func position()

public func position(): Int64

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

返回值：

Int64 - 当前 UInt64 值的位置信息。

extend UInt64 <: ToString

extend UInt64 <: ToString

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

func toString()

public func toString(): String

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

返回值：

String - 转化后的字符串。

UInt8

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

extend UInt8 <: Comparable<UInt8>

extend UInt8 <: Comparable<UInt8>

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

func compare(UInt8)

public func compare(rhs: UInt8): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 值。

返回值：

Int64 - 当前 UInt8 值的位置信息。

extend UInt8 <: ToString

extend UInt8 <: ToString

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

func toString()

public func toString(): String

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

返回值：

String - 转化后的字符串。

UIntNative

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

extend UIntNative <: Comparable<UIntNative>

extend UIntNative <: Comparable<UIntNative>

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

func compare(UIntNative)

public func compare(rhs: UIntNative): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

extend UIntNative <: Countable

extend UIntNative <: Countable<UIntNative>

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

func next(Int64)

public func next(right: Int64): UIntNative

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

参数：

right: Int64 - 往右数的个数。

返回值：

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

func position()

public func position(): Int64

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

返回值：

Int64 - 当前 UIntNative 值的位置信息。

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 <: 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 Comparable<T>

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

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

func compare(T)

func compare(that: T): Ordering

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

参数：

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

返回值：

Ordering - 如果大于，返回 Ordering.GT，如果等于，返回 Ordering.EQ，如果小于，返回 Ordering.LT。

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 类型。

返回值：

Int64 - 转换后的 Int64 值。

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>

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

已为部分仓颉类型实现该接口，包括：Unit、Bool 、Rune、Int64、Int32、Int16、Int8、UIntNative、UInt64、UInt32、UInt16、UInt8、Float64、Float32、Float16、String、Array、Box、ArrayList、HashSet。

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 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 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 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 ThreadContext

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

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

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

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

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>)
}

功能：数组迭代器，迭代功能详述见 Iterable 和 Iterator 说明。

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> 类型将可被引用。

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 对象。

返回值：

Ordering - 如果当前 Box 实例大于 that，返回 Ordering.GT，等于返回 Ordering.EQ，小于返回 Ordering.LT。

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 表达式中的闭包的返回值类型。

func cancel()

public func cancel(): Unit

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

func get()

public func get(): T

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

返回值：

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

func get(Int64)

public func get(ns: Int64): Option<T>

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

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

参数：

ns: Int64 - 等待时间，单位为纳秒。

返回值：

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

func tryGet()

public func tryGet(): Option<T>

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

返回值：

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

class Iterator<T>

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

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

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)>

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

返回值：

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> - 给定的映射函数。

返回值：

Iterator<R> - 返回一个带 flatten 功能的映射。

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 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 - 给定的映射函数。

返回值：

Iterator<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>

功能：使用第一个元素作为初始值，从左向右计算。

参数：

initial: R - 给定的 R 类型的初始值。

返回值：

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> - 返回一个跳过指定数量元素的迭代器。

异常：

IllegalArgumentException - 当 count < 0 时，抛出异常。

func step(Int64)

public func step(count: Int64): Iterator<T>

功能：迭代器每次调用 next() 跳过特定个数。

当 count 小于等于 0 时，抛异常。当 count 大于 0 时，每次调用 next() 跳过 count 次，直到迭代器为空。

参数：

count: Int64 - 每次调用 next() 要跳过的个数。

返回值：

Iterator<T> - 返回一个新迭代器，这个迭代器每次调用 next() 会跳过特定个数。

异常：

IllegalArgumentException - 当 count <= 0 时，抛出异常。

func take(Int64)

public func take(count: Int64): Iterator<T>

功能：从当前迭代器取出特定个数。

从后往前取出当前迭代器特定个数的元素。当 count 小于 0 时，抛异常。当 count 等于 0 时，不取元素，返回空迭代器。当 count 大于 0 小于迭代器的大小时，取前 count 个元素，返回新迭代器。当 count 大于等于迭代器的大小时，取所有元素，返回原迭代器。

参数：

count: Int64 - 要取出的个数。

返回值：

Iterator<T> - 返回一个取出指定数量元素的迭代器。

异常：

IllegalArgumentException - 当 count < 0 时，抛出异常。

func zip<R>(Iterator<R>)

public func zip<R>(it: Iterator<R>): Iterator<(T, R)>

功能：将两个迭代器合并成一个（长度取决于短的那个迭代器）。

参数：

other: 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 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 类型的迭代器，迭代功能详述见 Iterable 和 Iterator 接口说明。

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)
}

功能：表示一个异常堆栈的具体信息，包括异常发生的类名、函数名、文件名、行号。

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

init(Array<Rune>)

public init(value: Array<Rune>)

功能：使用参数 value 指定的字符数组初始化一个 StringBuilder 实例，该实例的初始容量为 value 大小，初始内容为 value 包含的字符内容。

参数：

value: Array<Rune> - 初始化 StringBuilder 实例的字符数组。

init(Int64)

public init(capacity: Int64)

功能：使用参数 capacity 指定的容量初始化一个空 StringBuilder 实例，该实例的初始容量为 value 大小，初始内容为若干 \0 字符。

参数：

capacity: Int64 - 初始化 StringBuilder 的字节容量，取值范围为 (0, Int64.Max]。

异常：

IllegalArgumentException - 当参数 capacity 的值小于等于 0 时，抛出异常。

init(Rune, Int64)

public init(r: Rune, n: Int64)

功能：使用 n 个 r 字符初始化 StringBuilder 实例，该实例的初始容量为 n，初始内容为 n 个 r 字符。

参数：

r: Rune - 初始化 StringBuilder 实例的字符。
n: Int64 - 字符 r 的数量，取值范围为 [0, Int64.Max]。

异常：

IllegalArgumentException - 当参数 n 小于 0 时，抛出异常。

init(String)

public init(str: String)

功能：根据指定初始字符串构造 StringBuilder 实例，该实例的初始容量为指定字符串的大小，初始内容为指定字符串。

参数：

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 中的内容。

参数：

cstr: CString - 插入的 CString。

func append(Float16)

public func append(n: Float16): Unit

功能：在 StringBuilder 末尾插入参数 n 的字符串表示。

参数：

n: Float16 - 插入的 Float16 类型的值。

func append(Float32)

public func append(n: Float32): Unit

功能：在 StringBuilder 末尾插入参数 n 的字符串表示。

参数：

n: Float32 - 插入的 Float32 类型的值。

func append(Float64)

public func append(n: Float64): Unit

功能：在 StringBuilder 末尾插入参数 n 的字符串表示。

参数：

n: Float64 - 插入的 Float64 类型的值。

func append(Int16)

public func append(n: Int16): Unit

功能：在 StringBuilder 末尾插入参数 n 的字符串表示。

参数：

n: Int16 - 插入的 Int16 类型的值。

func append(Int32)

public func append(n: Int32): Unit

功能：在 StringBuilder 末尾插入参数 n 的字符串表示。

参数：

n: Int32 - 插入的 Int32 类型的值。

func append(Int64)

public func append(n: Int64): Unit

功能：在 StringBuilder 末尾插入参数 n 的字符串表示。

参数：

n: Int64 - 插入的 Int64 类型的值。

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 中的内容。

参数：

sb: StringBuilder - 插入的 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 的字符串表示。

参数：

n: UInt16 - 插入的 UInt16 类型的值。

func append(UInt32)

public func append(n: UInt32): Unit

功能：在 StringBuilder 末尾插入参数 n 的字符串表示。

参数：

n: UInt32 - 插入的 UInt32 类型的值。

func append(UInt64)

public func append(n: UInt64): Unit

功能：在 StringBuilder 末尾插入参数 n 的字符串表示。

参数：

n: UInt64 - 插入的 UInt64 类型的值。

func append(UInt8)

public func append(n: UInt8): Unit

功能：在 StringBuilder 末尾插入参数 n 的字符串表示。

参数：

n: UInt8 - 插入的 UInt8 类型的值。

func appendFromUtf8(Array<Byte>)

public func appendFromUtf8(arr: Array<Byte>): Unit

功能：在 StringBuilder 末尾插入参数 arr 指向的字节数组。

该函数要求参数 arr 符合 UTF-8 编码，如果不符合，将抛出异常。

参数：

arr: Array<Byte> - 插入的字节数组。

异常：

IllegalArgumentException - 当字节数组不符合 utf8 编码规则时，抛出异常。

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 的最大值。

参数：

additional: Int64 - 指定 StringBuilder 的扩容大小。

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）。

异常：

IllegalArgumentException - 当参数 capacity 的值小于等于 0 时，抛出异常。

func toString()

public func toString(): String

功能：获取 StringBuilder 实例中的字符串。

注意：

该函数不会将字符串数据进行拷贝。

返回值：

String - StringBuilder 实例中的字符串。

class Thread

public class Thread

功能：Thread 类代表一个仓颉类，可用于获取线程 ID 及名字、查询线程是否存在取消请求、注册线程未处理异常的处理函数等。

该类型实例无法通过构造得到，仅能通过 Future 对象的 thread 属性或是 Thread 类的 currentThread 静态属性获取。

prop hasPendingCancellation

public prop hasPendingCancellation: Bool

功能：线程是否存在取消请求，即是否通过 future.cancel() 发送过取消请求，常见使用方为 Thread.currentThread.hasPendingCancellation。

类型：Bool

prop id

public prop id: Int64

功能：获取当前执行线程的标识，以 Int64 表示，所有存活的线程都有不同标识，但不保证当线程执行结束后复用它的标识。

类型：Int64

func handleUncaughtExceptionBy((Thread, Exception) -> Unit)

public static func handleUncaughtExceptionBy(exHandler: (Thread, Exception) -> Unit): Unit

功能：注册线程未处理异常的处理函数。

当某一线程因异常而提前终止后，如果全局的未处理异常函数被注册，那么将调用该函数并结束线程，在该函数内抛出异常时，将向终端打印提示信息并结束线程，但不会打印异常调用栈信息；如果没有注册全局异常处理函数，那么默认会向终端打印异常调用栈信息。

多次注册处理函数时，后续的注册函数将覆盖之前的处理函数。

当有多个线程同时因异常而终止时，处理函数将被并发执行，因而开发者需要在处理函数中确保并发正确性。

处理函数的参数第一个参数类型为 Thread，是发生异常的线程，第二个参数类型为 Exception，是线程未处理的异常。

参数：

exHandler: (Thread, Exception) -> Unit - 注册的处理函数。

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 Endian

public enum Endian {
    | Big
    | Little    
}

功能：枚举类型 Endian 表示运行平台的端序，分为大端序和小端序。

static prop Platform

public static prop Platform: Endian

功能：获取所在运行平台的端序。

类型：Endian

异常：

UnsupportedException - 当所运行平台返回的端序无法识别时，抛出异常。

示例：

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 类型的封装，表示可能有值也可能无值。

它包含两个构造器：Some 和 None。其中，Some 会携带一个参数，表示有值，None 不带参数，表示无值。当需要表示某个类型可能有值，也可能没有值的时候，可选择使用 Option 类型。

Option 类型的另一种写法是在类型名前加 ?，即对于任意类型 Type，?Type 等价于 Option<Type>。

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 的实例。

异常：

NoneValueException - 如果当前实例是 None，抛出异常。

func isNone()

public func isNone(): Bool

功能：判断当前实例值是否为 None。

返回值：

Bool - 如果当前实例值是 None，则返回 true，否则返回 false。

func isSome()

public func isSome(): Bool

功能：判断当前实例值是否为 Some。

返回值：

Bool - 如果当前实例值是 Some，则返回 true，否则返回 false。

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> 实例是否不等。

参数：

that: Option<T> - 待比较的 Option<T> 实例。

返回值：

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

operator func ==(?T)

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

功能：判断当前实例与参数指向的 Option<T> 实例是否相等。

如果两者同为 None，则相等；如果两者为 Some(v1) 和 Some(v2)，且 v1 和 v2 相等，则相等。

参数：

that: Option<T> - 待比较的 Option<T> 实例。

返回值：

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)。

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 - 转化后的字符串。

enum Ordering

public enum Ordering {
    | LT
    | GT
    | EQ
}

功能：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。

参数：

that: Ordering - 待比较的 Ordering 实例。

返回值：

Ordering - 如果大于，返回 GT，如果等于，返回 EQ，如果小于，返回 LT。

operator func !=(Ordering)

public operator func !=(that: Ordering): Bool

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

参数：

that: Ordering - 待比较的 Ordering 实例。

返回值：

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

operator func <(Ordering)

public operator func <(that: Ordering): Bool

功能：判断当前 Ordering 实例是否小于参数指向的 Ordering 实例。

参数：

that: Ordering - 待比较的 Ordering 实例。

返回值：

Bool - 如果当前 Ordering 实例小于参数指向的 Ordering 实例，则返回 true，否则返回 false。

operator func <=(Ordering)

public operator func <=(that: Ordering): Bool

功能：判断当前 Ordering 实例是否小于等于参数指向的 Ordering 实例。

参数：

that: Ordering - 待比较的 Ordering 实例。

返回值：

Bool - 如果当前 Ordering 实例小于等于参数指向的 Ordering 实例，则返回 true，否则返回 false。

operator func ==(Ordering)

public operator func ==(that: Ordering): Bool

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

参数：

that: Ordering - 待比较的 Ordering 实例。

返回值：

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

operator func >(Ordering)

public operator func >(that: Ordering): Bool

功能：判断当前 Ordering 实例是否大于参数指向的 Ordering 实例。

参数：

that: Ordering - 待比较的 Ordering 实例。

返回值：

Bool - 如果当前 Ordering 实例大于参数指向的 Ordering 实例，则返回 true，否则返回 false。

operator func >=(Ordering)

public operator func >=(that: Ordering): Bool

功能：判断当前 Ordering 实例是否大于等于参数指向的 Ordering 实例。

参数：

that: 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。

返回值：

Int64 - 哈希值。

extend Ordering <: ToString

extend Ordering <: ToString

功能：为 Ordering 类型其扩展 ToString 接口，支持转字符串操作。

func toString()

public func toString(): String

功能：将 Ordering 转换为可输出的字符串。

转换结果如下：

GT："Ordering.GT"。
LT："Ordering.ET"。
EQ："Ordering.EQ"。

返回值：

String - 转化后的字符串。

结构体

struct Array<T>

public struct Array<T> {
    public const init()
    public init(elements: Collection<T>)
    public init(size: Int64, item!: T)
    public init(size: Int64, initElement: (Int64) -> T)
}

功能：仓颉数组类型，用来表示单一类型的元素构成的有序序列。

T 表示数组的元素类型，T 可以是任意类型。

init(Collection<T>)

public init(elements: Collection<T>)

功能：根据 Collection 实例创建数组，把 Collection 实例中所有元素存入数组。

参数：

elements: Collection<T> - 根据该 Collection 实例创建数组。

init(Int64, (Int64) -> T)

public init(size: Int64, initElement: (Int64) -> T)

功能：创建指定长度的数组，其中元素根据初始化函数计算获取。

即：将 [0, size) 范围内的值分别传入初始化函数 initElement，执行得到数组对应下标的元素。

参数：

size: Int64 - 数组大小。
initElement: (Int64) ->T - 初始化函数。

异常：

NegativeArraySizeException - 当 size 小于 0，抛出异常。

init(Int64, T)

public init(size: Int64, item!: T)

功能：构造一个指定长度的数组，其中元素都用指定初始值进行初始化。

注意：

该构造函数不会拷贝 item，如果 item 是一个引用类型，构造后数组的每一个元素都将指向相同的引用。

参数：

size: Int64 - 数组大小，取值范围为 [0, Int64.Max]。
item!: T - 数组元素初始值。

异常：

NegativeArraySizeException - 当 size 小于 0，抛出异常。

func clone()

public func clone(): Array<T>

功能：克隆数组，将对数组数据进行深拷贝。

返回值：

Array<T> - 克隆得到的新数组。

func clone(Range<Int64>)

public func clone(range: Range<Int64>) : Array<T>

功能：克隆数组的指定区间。

注意：

如果参数 range 是使用 Range 构造函数构造的 Range 实例，有如下行为：

start 的值就是构造函数传入的值本身，不受构造时传入的 hasStart 的值的影响。

hasEnd 为 false 时，end 值不生效，且不受构造时传入的 isClosed 的值的影响，数组切片取到原数组最后一个元素。

range 的步长只能为 1。

参数：

range: Range<Int64> - 克隆的区间。

返回值：

Array<T> - 克隆得到的新数组。

异常：

IndexOutOfBoundsException - range 超出数组范围时，抛出异常。

示例：

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>, 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。

异常：

IllegalArgumentException - copyLen 小于 0 则抛出此异常。
IndexOutOfBoundsException - 如果参数不满足上述取值范围，抛出此异常。

示例：

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 get(Int64)

public func get(index: Int64): Option<T>

功能：获取数组中下标 index 对应的元素。

该函数结果将用 Option 封装，如果 index 越界，将返回 None。

也可以通过 [] 操作符获取数组指定下标的元素，该接口将在 index 越界时抛出异常。

参数：

index: Int64 - 要获取的值的下标。

返回值：

Option<T> - 当前数组中下标 index 对应的值。

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 set(Int64, T)

public func set(index: Int64, element: T): Unit

功能：修改数组中下标 index 对应的值。

也可以通过 [] 操作符完成对指定下标元素的修改，这两个函数的行为一致。

参数：

index: Int64 - 需要修改的值的下标，取值范围为 [0..this.size]。
element: T - 修改的目标值。

异常：

IndexOutOfBoundsException - 如果 index 小于 0 或者大于或等于 Array 的长度，抛出异常。

func slice(Int64, Int64)

public func slice(start: Int64, len: Int64): Array<T>

功能：获取数组切片。

注意：

切片不会对数组数据进行拷贝，是对原数据特定区间的引用。

参数：

start: Int64 - 切片的起始位置，取值需大于 0，且 start + len 小于等于当前 Array 实例的长度。
len: Int64 - 切片的长度，取值需大于 0。

返回值：

Array<T> - 返回切片后的数组。

异常：

IndexOutOfBoundsException - 如果参数不符合上述取值范围，抛出异常。

operator func [](Int64)

public operator func [](index: Int64): T

功能：获取数组下标 index 对应的值。

该函数中如果 index 越界，将抛出异常。

也可以通过 get 函数获取数组指定下标的元素，get 函数将在 index 越界时返回 None。

参数：

index: Int64 - 要获取的值的下标，取值范围为 [0, Int64.Max]。

返回值：

T - 数组中下标 index 对应的值。

异常：

IndexOutOfBoundsException - 如果 index 小于 0，或大于等于数组长度，抛出异常。

operator func [](Int64, T)

public operator func [](index: Int64, value!: T): Unit

功能：修改数组中下标 index 对应的值。

参数：

index: Int64 - 需要修改值的下标，取值范围为 [0, Int64.Max]。
value!: T - 修改的目标值。

异常：

IndexOutOfBoundsException - 如果 index 小于 0，或大于等于数组长度，抛出异常。

operator func [](Range<Int64>)

public operator func [](range: Range<Int64>): Array<T>

功能：根据给定区间获取数组切片。

注意：

如果参数 range 是使用 Range 构造函数构造的 Range 实例，有如下行为：

start 的值就是构造函数传入的值本身，不受构造时传入的 hasStart 的值的影响。

hasEnd 为 false 时，end 值不生效，且不受构造时传入的 isClosed 的值的影响，该数组切片取到原数组最后一个元素。

range 的步长只能为 1。

参数：

range: Range<Int64> - 切片的范围，range 表示的范围不能超过数组范围。

返回值：

Array<T> - 数组切片。

异常：

IllegalArgumentException - 如果 range 的步长不等于 1，抛出异常。
IndexOutOfBoundsException - 如果 range 表示的数组范围无效，抛出异常。

示例：

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 的大小需相等。

注意：

如果参数 range 是使用 Range 构造函数构造的 Range 实例，有如下行为：

start 的值就是构造函数传入的值本身，不受构造时传入的 hasStart 的值的影响。

hasEnd 为 false 时，end 值不生效，且不受构造时传入的 isClosed 的值的影响，该数组切片取到原数组最后一个元素。

range 的步长只能为 1。

参数：

range: Range<Int64> - 需要修改的数组范围，range 表示的范围不能超过数组范围。
value!: Array<T> - 修改的目标值。

异常：

IllegalArgumentException - 如果 range 的步长不等于 1，或 range 长度不等于 value 长度，抛出异常。
IndexOutOfBoundsException - 如果 range 表示的数组范围无效，抛出异常。

示例：

main() {
    let arr = [0, 1, 2, 3, 4, 5]
    arr[1..3] = [10, 11]
    println(arr)
}

运行结果：

[0, 10, 11, 3, 4, 5]

operator func [](Range<Int64>, T)

public operator func [](range: Range<Int64>, value!: T): Unit

功能：用指定的值对本数组一个连续范围的元素赋值。

注意：

如果参数 range 是使用 Range 构造函数构造的 Range 实例，有如下行为：

start 的值就是构造函数传入的值本身，不受构造时传入的 hasStart 的值的影响。

hasEnd 为 false 时，end 值不生效，且不受构造时传入的 isClosed 的值的影响，该数组切片取到原数组最后一个元素。

range 的步长只能为 1。

切片不会对数组数据进行拷贝，是对原数据特定区间的引用。

参数：

range: Range<Int64> - 需要修改的数组范围，range 表示的范围不能超过数组范围。
value!: T - 修改的目标值。

异常：

IllegalArgumentException - 如果 range 的步长不等于 1，抛出异常。
IndexOutOfBoundsException - 如果 range 表示的数组范围无效，抛出异常。

示例：

main() {
    let arr = [0, 1, 2, 3, 4, 5]
    arr[1..3] = 10
    println(arr)
}

运行结果：

[0, 10, 10, 3, 4, 5]

extend<T> Array<T> <: Collection<T>

extend<T> Array<T> <: Collection<T>

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 trimLeft(Array<T>)

public func trimLeft(prefix: Array<T>): Array<T>

功能：修剪当前数组，去除掉前缀为 prefix 的部分，并且返回当前数组的切片。

参数：

prefix: Array<T> - 要修剪的子串。

返回值：

Array<T> - 修剪后的数组切片。

func trimRight(Array<T>)

public func trimRight(suffix: Array<T>): Array<T>

功能：修剪当前数组，去除掉后缀为 suffix 的部分，并且返回当前数组的切片。

参数：

suffix: Array<T> - 要修剪的子串。

返回值：

Array<T> - 修剪后的数组切片。

operator func !=(Array<T>)

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

功能：判断当前实例与指定 Array<T> 实例是否不等。

参数：

that: Array<T> - 用于与当前实例比较的另一个 Array<T> 实例。

返回值：

Bool - 如果不相等，则返回 true；相等则返回 false。

operator func ==(Array<T>)

public const operator 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 - 转化后的字符串。

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 约束。

init()

public init()

功能：构造一个默认 CPointerHandle 实例，其中原始指针为空指针，仓颉数组为空数组。

init(CPointer<T>, Array<T>)

public init(ptr: CPointer<T>, arr: Array<T>)

功能：通过传入的 CPointer 和 Array 初始化一个 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 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 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 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 isClosed

public let isClosed: Bool

功能：表示区间开闭情况，为 true 表示左闭右闭，为 false 表示左闭右开。

类型：Bool

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 代表左闭右开。

异常：

IllegalArgumentException - 当 step 等于 0 时, 抛出异常。

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 是否不相等。

参数：

that: Range<T> - 待比较的 Range 实例。

返回值：

Bool - true 代表不相等，false 代表相等。

operator func ==(Range<T>)

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

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

两个 Range 实例相等指的是它们表示同一个区间，即 start、end、step、isClosed 值相等。

参数：

that: Range<T> - 待比较的 Range 实例。

返回值：

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

功能：获取哈希值，该值为 start、end、step、isClosed 的组合哈希运算结果。

返回值：

Int64 - 哈希值。

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 编码。

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 - 构造的字符串。

异常：

IllegalArgumentException - 入参不符合 utf-8 序列规则，抛出异常。

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 compare(String)

public func compare(str: String): Ordering

功能：按字典序比较当前字符串和参数指定的字符串。

参数：

str: String - 被比较的字符串。

返回值：

Ordering - 返回 enum 值 Ordering 表示结果，Ordering.GT 表示当前字符串字典序大于 str 字符串，Ordering.LT 表示当前字符串字典序小于 str 字符串，Ordering.EQ 表示两个字符串字典序相等。

异常：

IllegalArgumentException - 如果两个字符串的原始数据中存在无效的 UTF-8 编码，抛出异常。

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 getRaw()

public unsafe func getRaw(): CPointerHandle<UInt8>

功能：获取当前 String 的原始指针，用于和C语言交互，使用完后需要 releaseRaw 函数释放该指针。

注意：

getRaw 与 releaseRaw 之间仅可包含简单的 foreign C 函数调用等逻辑，不构造例如 CString 等的仓颉对象，否则可能造成不可预知的错误。

返回值：

CPointerHandle<UInt8> - 当前字符串的原始指针实例。

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。

返回值：

Iterator<String> - 分割后的字符串迭代器。

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。

返回值：

Iterator<String> - 分割后的字符串迭代器。

func lines()

public func lines(): Iterator<String>

功能：获取字符串的行迭代器，每行都由换行符进行分隔，换行符是 \n \r \r\n 之一，结果中每行不包括换行符。

返回值：

Iterator<String> - 字符串的行迭代器。

func padLeft(Int64, String)

public func padLeft(totalWidth: Int64, padding!: String = " "): String

功能：按指定长度右对齐原字符串，如果原字符串长度小于指定长度，在其左侧添加指定字符串。

当指定长度小于字符串长度时，返回字符串本身，不会发生截断；当指定长度大于字符串长度时，在左侧添加 padding 字符串，当 padding 长度大于 1 时，返回字符串的长度可能大于指定长度。

参数：

totalWidth: Int64 - 指定对齐后字符串长度，取值需大于等于 0。
padding!: String - 当长度不够时，在左侧用指定的字符串 padding 进行填充

返回值：

String - 填充后的字符串。

异常：

IllegalArgumentException - 如果 totalWidth 小于 0，抛出异常。

func padRight(Int64, String)

public func padRight(totalWidth: Int64, padding!: String = " "): String

功能：按指定长度左对齐原字符串，如果原字符串长度小于指定长度，在其右侧添加指定字符串。

当指定长度小于字符串长度时，返回字符串本身，不会发生截断；当指定长度大于字符串长度时，在右侧添加 padding 字符串，当 padding 长度大于 1 时，返回字符串的长度可能大于指定长度。

参数：

totalWidth: Int64 - 指定对齐后字符串长度，取值需大于等于 0。
padding!: String - 当长度不够时，在右侧用指定的字符串 padding 进行填充。

返回值：

String - 填充后的字符串。

异常：

IllegalArgumentException - 如果 totalWidth 小于 0，抛出异常。

func rawData()

public unsafe func rawData(): Array<Byte>

功能：获取字符串的 UTF-8 编码的原始字节数组。

注意：

用户不应该对获取的数组进行修改，这将破坏字符串的不可变性。

返回值：

Array<Byte> - 当前字符串对应的原始字节数组。

func releaseRaw(CPointerHandle<UInt8>)

public unsafe func releaseRaw(cp: CPointerHandle<UInt8>): Unit

功能：释放 getRaw 函数获取的指针。

注意：

释放时只能释放同一个 String 获取的指针，如果释放了其他 String 获取的指针，会出现不可预知的错误。

参数：

cp: CPointerHandle<UInt8> - 待释放的指针实例。

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。

返回值：

Array<String> - 分割后的字符串数组。

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。

返回值：

Array<String> - 分割后的字符串数组。

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 trimAscii()

public func trimAscii(): String

功能：去除原字符串开头结尾以 whitespace 字符组成的子字符串。

whitespace 的 unicode 码点范围为 [0009, 000D] 和 [0020]。

返回值：

String - 转换后的新字符串。

func trimAsciiLeft()

public func trimAsciiLeft(): String

功能：去除原字符串开头以 whitespace 字符组成的子字符串。

返回值：

String - 转换后的新字符串。

func trimAsciiRight()

public func trimAsciiRight(): String

功能：去除原字符串结尾以 whitespace 字符组成的子字符串。

返回值：

String - 转换后的新字符串。

func trimLeft(String)

public func trimLeft(prefix: String): String

功能：去除字符串的 prefix 前缀。

参数：

prefix: String - 待去除的前缀。

返回值：

String - 转换后的新字符串。

func trimRight(String)

public func trimRight(suffix: String): String

功能：去除字符串的 suffix 后缀。

参数：

suffix: String - 待去除的后缀。

返回值：

String - 转换后的新字符串。

func tryGet(Int64)

public func tryGet(index: Int64): Option<Byte>

功能：返回字符串下标 index 对应的 UTF-8 编码字节值。

参数：

index: Int64 - 要获取的字节值的下标。

返回值：

Option<Byte> - 获取得到下标对应的 UTF-8 编码字节值，当 index 小于 0 或者大于等于字符串长度，则返回 Option<Byte>.None。

operator func !=(String)

public const operator func !=(right: String): Bool

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

参数：

right: String - 待比较的 String 实例。

返回值：

Bool - 不相等返回 true，相等返回 false。

operator func *(Int64)

public const operator func *(count: Int64): String

功能：原字符串重复 count 次。

参数：

count: Int64 - 原字符串重复的次数。

返回值：

String - 返回重复 count 次后的新字符串。

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 编码字节。

异常：

IndexOutOfBoundsException - 如果 index 小于 0 或大于等于字符串长度，抛出异常。

operator func [](Range<Int64>)

public const operator func [](range: Range<Int64>): String

功能：根据给定区间获取当前字符串的切片。

注意：

如果参数 range 是使用 Range 构造函数构造的 Range 实例，有如下行为：

start 的值就是构造函数传入的值本身，不受构造时传入的 hasStart 的值的影响。

hasEnd 为 false 时，end 值不生效，且不受构造时传入的 isClosed 的值的影响，该字符串切片取到原字符串最后一个元素。

range 的步长只能为 1。

参数：

range: Range<Int64> - 切片的区间。

返回值：

String - 字符串切片。

异常：

IndexOutOfBoundsException - 如果切片范围超过原字符串边界，抛出异常。
IllegalArgumentException - 如果 range.step 不等于 1，抛出异常。
IllegalArgumentException - 如果范围起止点不是字符边界，抛出异常。

异常类

class Error

public open class Error <: ToString

功能：Error 是所有错误类的基类。该类不可被继承，不可初始化，但是可以被捕获到。

func getStackTrace()

public func getStackTrace(): Array<StackTraceElement>

功能：获取堆栈信息，每一条堆栈信息用一个 StackTraceElement 实例表示，最终返回一个 StackTraceElement 的数组。

返回值：

Array<StackTraceElement> - 堆栈信息数组。

func toString()

public open func toString(): String

功能：获取当前 Error 实例的字符串值，包括类名和错误信息。

返回值：

String - 错误信息字符串。

class Exception

public open class Exception <: ToString {
    public init()
    public init(message: String)
}

功能：Exception 是所有异常类的父类。

支持构造一个异常类，设置、获取异常信息，转换为字符串，获取、打印堆栈，设置异常名（用于字符串表示）。

init(String)

public init(message: String)

功能：根据异常信息构造一个 Exception 实例。

参数：

message: String - 异常提示信息。

func getClassName()

protected open func getClassName(): String

功能：获得类名，用字符串表示。

类名将在异常字符串中体现（toString 函数返回值），覆写该函数将改变异常信息字符串中类名信息。

返回值：

String - 类名。

func getStackTrace()

public func getStackTrace(): Array<StackTraceElement>

功能：获取堆栈信息，每一条堆栈信息用一个 StackTraceElement 实例表示，最终返回一个 StackTraceElement 的数组。

返回值：

Array<StackTraceElement> - 堆栈信息数组。

func toString()

public open func toString(): String

功能：获取当前 Exception 实例的字符串值，包括类名和异常信息。

返回值：

String - 异常字符串。

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"。

返回值：

String - 类名。

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 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 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(String)

public init(message: String)

功能：根据异常信息构造一个 SpawnException 实例。

参数：

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 的使用

主线程和新线程同时尝试打印一些文本。

代码如下：

import std.sync.sleep
import std.time.{Duration, DurationExtension}

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 的使用

主线程等待创建线程执行完再执行。

代码如下：

import std.sync.sleep
import std.time.{Duration, DurationExtension}

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

使用 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，编译过程如下：

使用 gcc 命令 gcc -fPIC -shared test.c -o libtest.so，编出 C 库 libtest.so。

使用 cjc 命令 cjc -L . -l test test.cj，编出可执行文件 main。

std.argopt 包

功能介绍

argopt 包提供从命令行参数字符串解析出参数名和参数值的相关能力。

命令行参数是在命令行中传递给程序的参数，它们用于指定程序的配置或行为。例如，一个命令行程序可能有一个参数来指定它要处理的文件的名称，或者一个参数来指定使用的数据库。这些参数通常会被解析并传递给程序的代码，以便程序可以根据这些参数正确地执行其功能。

命令行参数分为短命令行参数和长命令行参数，区别在于它们的长度和可读性。短命令行参数通常由单个字母组成，易于记忆；长命令行参数通常由一个或多个单词组成，易于理解。

API 列表

类

类名	功能
ArgOpt	`Argopt` 用于解析命令行参数，并提供了获取解析结果的功能。

类

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)

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 - 前缀和参数名组成的字符串（可省略前缀）。

返回值：

Option<String> - 参数解析值。

func getArgumentsMap()

public func getArgumentsMap(): HashMap<String, String>

功能：获取所有已解析的参数名和参数值，以哈希表的形式返回。

返回值：

HashMap < String, String > - 已解析的参数名为键，参数值为值的哈希表。

func getUnparseArgs()

public func getUnparseArgs(): Array<String>

功能：返回未被解析的命令行参数。

返回值：

Array<String> - 存放没有被解析的字符串的数组。

长命令行参数解析

import std.argopt.*

main() {
    let shortArgs: Array<String> = Array<String>(["--test1=abc", "--test2=123", "--test3 xyz"])
    let shortArgName: String = ""
    let longArgName: Array<String> = 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> = 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 列表

函数

函数名	功能
getTokenKind(UInt16)	将词法单元种类序号转化为 `TokenKind`。
compareTokens(Tokens, Tokens)	用于比较两个Tokens是否一致。
cangjieLex(String)	将字符串转换为 `Tokens` 类型。
cangjieLex(String, Bool)	将字符串转换为 `Tokens` 类型。
parseProgram(Tokens)	用于解析单个仓颉文件的源码，获取一个 Program 类型的节点。
parseDecl(Tokens, String)	用于解析一组词法单元，获取一个 Decl 类型的节点。
parseDeclFragment(Tokens, Int64)	用于解析一组词法单元，获取一个 Decl 类型的节点和继续解析节点的索引。
parseExpr(Tokens)	用于解析一组词法单元，获取一个 Expr 类型的节点。
parseExprFragment(Tokens, Int64)	用于解析一组词法单元，获取一个 Expr 类型的节点和继续解析节点的索引。
assertParentContext(String)	检查当前宏调用是否在特定的宏调用内;若检查不符合预期，编译器出现一个错误提示。
insideParentContext(String)	检查当前宏调用是否在特定的宏调用内，返回一个布尔值。
setItem(String, String)	内层宏通过该接口发送 string 类型的信息到外层宏。
setItem(String, Int64)	内层宏通过该接口发送 Int64 类型的信息到外层宏。
setItem(String, Bool)	内层宏通过该接口发送 Bool 类型的信息到外层宏。
getChildMessages(String)	获取特定内层宏发送的信息。
diagReport(DiagReportLevel, Tokens, String, String)	报错接口，在编译过程的宏展开阶段输出错误提示信息，支持 `WARNING` 和 `ERROR` 两个等级的报错。

接口

接口名	功能
ToTokens	实现对应类型的实例到 `Tokens` 类型转换的接口，作为支持quote插值操作必须实现的接口。
ToBytes	提供对应类型的序列化功能。

类

类名	功能
Annotation	表示编译器内置的注解节点。
Argument	表示函数调用的实参节点。
Body	表示 Class 类型、 Struct 类型、 Interface 类型以及扩展中由 `{}` 和内部的一组声明节点组成的结构。
Constructor	表示 `enum` 类型中的 `Constructor` 节点。
GenericConstraint	表示一个泛型约束节点。
GenericParam	表示一个类型形参节点.
ImportContent	表示包导入节点中的导入项。
ImportList	表示包导入节点。
MacroMessage	记录内层宏发送的信息。
MatchCase	表示一个 `MatchCase` 类型。
Modifier	表示该定义具备某些特性，通常放在定义处的最前端。
Node	所有仓颉语法树节点的父类。
PackageHeader	表示包声明节点。
Program	表示一个仓颉源码文件节点。
Tokens	对 `Token` 序列进行封装的类型。
TokensIterator	实现 `Tokens` 的迭代器功能。
Decl	所有声明节点的父类，继承自 `Node` 节点，提供了所有声明节点的通用接口。
ClassDecl	类定义节点。
EnumDecl	表示一个 `Enum` 定义节点。
ExtendDecl	表示一个扩展定义节点。
FuncParam	表示函数参数节点，包括非命名参数和命名参数。
MacroExpandParam	表示宏调用节点。
FuncDecl	表示一个函数定义节点。
InterfaceDecl	表示接口定义节点。
MacroDecl	表示一个宏定义节点。
MacroExpandDecl	表示宏调用节点。
MainDecl	表示一个 `main` 函数定义节点。
PrimaryCtorDecl	表示一个主构造函数节点。
PropDecl	表示一个属性定义节点。
StructDecl	表示一个 `Struct` 节点。
TypeAliasDecl	表示类型别名节点。
VarDecl	表示变量定义节点。
TypeNode	所有类型节点的父类，继承自 `Node`。
PrimitiveType	表示一个基本类型节点。
RefType	表示一个用户自定义类型节点。
QualifiedType	表示一个用户自定义成员类型。
ParenType	表示括号类型节点。
TupleType	表示元组类型节点。
ThisType	表示 `This` 类型节点。
PrefixType	表示带问号的前缀类型节点。
FuncType	表示函数类型节点。
VArrayType	表示 `VArray` 类型节点。
Pattern	所有模式匹配节点的父类，继承自 `Node` 节点。
ConstPattern	表示常量模式节点。
WildcardPattern	表示通配符模式节点。
VarPattern	表示绑定模式节点。
VarOrEnumPattern	表示当模式的标识符为 `Enum` 构造器时的节点。
TypePattern	表示当类型模式节点。
EnumPattern	表示 enum 模式节点。
TuplePattern	表示 Tuple 模式节点。
ExceptTypePattern	表示一个用于异常模式状态下的节点。
Expr	所有表达式节点的父类，继承自 `Node` 节点。
Block	表示块节点。
ArrayLiteral	表示 `Array` 字面量节点。
AsExpr	表示一个类型检查表达式。
AssignExpr	表示赋值表达式节点。
BinaryExpr	表示一个二元操作表达式节点。
CallExpr	表示函数调用节点节点。
DoWhileExpr	表示 `do-while` 表达式。
ForInExpr	表示 `for-in` 表达式。
UnaryExpr	表示一个一元操作表达式节点。
IsExpr	表示一个类型检查表达式。
ParenExpr	表示一个括号表达式节点，是指使用圆括号括起来的表达式。
LitConstExpr	表示一个常量表达式节点。
RefExpr	表示一个使用自定义类型节点相关的表达式节点。
ReturnExpr	表示 `return` 表达式节点。
ThrowExpr	表示 `throw` 表达式节点。
MemberAccess	表示成员访问表达式。
OptionalExpr	表示一个带有问号操作符的表达式节点。
IfExpr	表示条件表达式。
LetPatternExpr	表示 `let` 声明的解构匹配节点。
MatchExpr	表示模式匹配表达式实现模式匹配。
WhileExpr	表示 `while` 表达式。
LambdaExpr	表示 `Lambda` 表达式，是一个匿名的函数。
SpawnExpr	表示 `Spawn` 表达式。
SynchronizedExpr	表示 `synchronized` 表达式。
TrailingClosureExpr	表示尾随 `Lambda` 节点。
TypeConvExpr	表示类型转换表达式。
PrimitiveTypeExpr	表示基本类型表达式节点。
TupleLiteral	表示元组字面量节点。
RangeExpr	表示包含区间操作符的表达式。
SubscriptExpr	表示索引访问表达式。
JumpExpr	表示循环表达式的循环体中的 `break` 和 `continue`。
IncOrDecExpr	表示包含自增操作符（`++`）或自减操作符（`--`）的表达式。
TryExpr	表示 `try` 表达式节点。
QuoteExpr	表示 `quote` 表达式节点。
QuoteToken	表示 `quote` 表达式节点内任意合法的 `token`。
MacroExpandExpr	表示宏调用节点。
WildcardExpr	表示通配符表达式节点。
VArrayExpr	表示 `VArray` 的实例节点。
Visitor	一个抽象类，其内部默认定义了访问不同类型 AST 节点访问（visit）函数。

枚举

枚举名	功能
DiagReportLevel	表示报错接口的信息等级，支持 `ERROR` 和 `WARNING` 两种格式。
ImportKind	表示导入语句的类型，包括单导入、别名导入、全导入和多导入四种类型。
TokenKind	表示仓颉编译内部所有的词法结构，包括符号、关键字、标识符、换行等。

结构体

结构体名	功能
Position	表示位置信息的数据结构，包含文件ID，行号和列号。
Token	词法单元类型。

异常类

异常类名	功能
class ASTException	ast 库的异常类，在 ast 库调用过程中发生异常时使用。
class ParseASTException	ast 库的解析异常类，在节点解析过程中发生异常时使用。
class MacroContextException	ast 库的上下文宏异常类，在上下文宏的相关接口中发生异常时使用。

函数

func assertParentContext(String)

public func assertParentContext(parentMacroName: String): Unit

功能：检查当前宏调用是否在特定的宏调用内。若检查不符合预期，编译器出现一个错误提示。

注意：

该函数只能作为函数被直接调用，不能作为赋值给变量，不能作为实参或返回值使用。

参数：

parentMacroName: String - 待检查的外层宏调用的名字。

func cangjieLex(String)

public func cangjieLex(code: String): Tokens

功能：将字符串转换为 Tokens 对象。

参数：

code: String - 待词法解析的字符串。

返回值：

Tokens - 词法解析得到的 Tokens。

异常：

IllegalMemoryException - 当申请内存失败时，抛出异常。
IllegalArgumentException - 当输入的 code 无法被正确的解析为 Tokens 时，抛出异常。

func cangjieLex(String, Bool)

public func cangjieLex(code: String, truncated: Bool): Tokens

功能：将字符串转换为 Tokens 对象。

参数：

code: String - 待词法解析的字符串。
truncated: Bool - 是否删减解析后 Tokens 中的 Token(END)。

返回值：

Tokens - 词法解析得到的 Tokens。

异常：

IllegalMemoryException - 当申请内存失败，抛出异常时，抛出异常。
IllegalArgumentException - 当输入的 code 无法被正确的解析为 Tokens 时，抛出异常。

func compareTokens(Tokens, Tokens)

public func compareTokens(tokens1: Tokens, tokens2: Tokens): Bool

功能：用于比较两个Tokens是否一致。

参数：

tokens1: Tokens - 需要比较的第一个 Tokens。
tokens2: Tokens - 需要比较的第二个 Tokens。

返回值：

Bool - 如果两个 Tokens 内容相同（除了换行符、结束符和位置信息）则返回 true。

func diagReport(DiagReportLevel, Tokens, String, String)

public func diagReport(level: DiagReportLevel, tokens: Tokens, message: String, hint: String): Unit

功能：报错接口，在编译过程的宏展开阶段输出错误提示信息，支持 WARNING 和 ERROR 两个等级的报错。

注意：

该接口在错误等级为 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 - 待接收信息的内层宏名称。

返回值：

ArrayList<MacroMessage> - 返回一组 MacroMessage 的对象。

func getTokenKind(UInt16)

public func getTokenKind(no: UInt16): TokenKind

功能：将词法单元种类序号转化为 TokenKind。

参数：

no: UInt16 - 需要转换的序号。

返回值：

TokenKind - 词法单元种类序号对应的 TokenKind。

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 - 用于指定解析特定的节点类型，有效支持的值为：PrimaryCtorDecl 和 PropMemberDecl。
- PrimaryCtorDecl: 解析主构造函数。
- PropMemberDecl: 解析prop声明的getter和setter函数。

返回值：

Decl - 一个 Decl 类型的节点。

异常：

ParseASTException - 当输入的 Tokens 类型无法构造为 Decl 节点时，抛出异常。

示例：

以下代码展示 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
}

以下代码展示 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) - 语法树节点，继续解析的位置。

异常：

ParseASTException - 当输入的 Tokens 类型无法构造为 Decl 节点时，抛出异常。

func parseExpr(Tokens)

public func parseExpr(input: Tokens): Expr

功能：用于解析一组词法单元，获取一个 Expr 类型的节点。

参数：

input: Tokens - 待解析源码的词法单元。

返回值：

Expr - 一个 Expr 类型的节点。

异常：

ParseASTException - 当输入的 Tokens 类型无法构造为 Expr 节点时，抛出异常。

func parseExprFragment(Tokens, Int64)

public func parseExprFragment(input: Tokens, startFrom !: Int64 = 0): (Expr, Int64)

功能：用于解析一组词法单元，获取一个 Expr 类型的节点和继续解析节点的索引。

参数：

input: Tokens - 待解析源码的词法单元。
startFrom!: Int64 - 起始位置。

返回值：

(Expr, Int64) - 语法树节点，继续解析的位置。

异常：

ParseASTException - 当输入的 Tokens 类型无法构造为 Expr 节点时，抛出异常。

func parseProgram(Tokens)

public func parseProgram(input: Tokens): Program

功能：用于解析单个仓颉文件的源码，获取一个 Program 类型的节点。

参数：

input: Tokens - 待解析源码的词法单元。

返回值：

Program - 一个 Program 类型的节点。

异常：

ParseASTException - 当输入的 Tokens 类型无法构造为 Program 节点时，抛出异常。

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 类型的信息。

接口

interface ToBytes

public interface ToBytes {
    func toBytes(): Array<UInt8>
}

功能：提供对应类型的序列化功能。

func toBytes()

func toBytes(): Array<UInt8>

功能：提供对应类型的序列化功能。

返回值：

Array<UInt8> - 序列化后的字节序列。

extend Position <: ToBytes

extend Position <: ToBytes

功能：提供 Position 类型的序列化功能。

func toBytes()

func toBytes(): Array<UInt8>

功能：提供 Position 类型的序列化功能。

返回值：

Array<UInt8> - 序列化后的字节序列。

extend Token <: ToBytes

extend Token <: ToBytes

功能：提供 Token 类型的序列化功能。

func toBytes()

func toBytes(): Array<UInt8>

功能：提供 Token 类型的序列化功能。

返回值：

Array<UInt8> - 序列化后的字节序列。

extend Tokens <: ToBytes

extend Tokens <: ToBytes

功能：提供 Tokens 类型的序列化功能。

func toBytes()

func toBytes(): Array<UInt8>

功能：提供 Tokens 类型的序列化功能。

返回值：

Array<UInt8> - 序列化后的字节序列。

interface ToTokens

public interface ToTokens {
    func toTokens(): Tokens
}

功能：实现对应类型的实例到 Tokens 类型转换的接口，作为支持 quote 插值操作必须实现的接口。

func toTokens()

func toTokens(): Tokens

功能：实现对应类型的实例到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend Array <: ToTokens

extend<T> Array<T> <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Array 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Array 类型到 Tokens 类型的转换，仅支持数值类型、Rune 类型、Bool 类型、String 类型。

返回值：

Tokens - 转换后的 Tokens。

extend ArrayList <: ToTokens

extend<T> ArrayList<T> <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 ArrayList 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 ArrayList 类型到 Tokens 类型的转换，目前支持的类型有 Decl、Node、Constructor、Argument、FuncParam、MatchCase、Modifier、Annotation、ImportList、Pattern、TypeNode等。

返回值：

Tokens - 转换后的 Tokens。

extend Bool <: ToTokens

extend Bool <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Bool 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Bool 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend Float16 <: ToTokens

extend Float16 <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Float16 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Float16 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend Float32 <: ToTokens

extend Float32 <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Float32 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Float32 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend Float64 <: ToTokens

extend Float64 <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Float64 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Float64 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend Int16 <: ToTokens

extend Int16 <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Int16 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Int16 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend Int32 <: ToTokens

extend Int32 <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Int32 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Int32 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend Int64 <: ToTokens

extend Int64 <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Int64 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Int64 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend Int8 <: ToTokens

extend Int8 <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Int8 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Int8 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend Rune <: ToTokens

extend Rune <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Rune 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Rune 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend String <: ToTokens

extend String <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 String 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 String 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend Token <: ToTokens

extend Token <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Token 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Token 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend Tokens <: ToTokens

extend Tokens <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 Tokens 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 Tokens 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend UInt16 <: ToTokens

extend UInt16 <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 UInt16 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 UInt16 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend UInt32 <: ToTokens

extend UInt32 <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 UInt32 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 UInt32 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend UInt64 <: ToTokens

extend UInt64 <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 UInt64 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 UInt64 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

extend UInt8 <: ToTokens

extend UInt8 <: ToTokens {
    public func toTokens(): Tokens
}

功能：实现 UInt8 类型到 Tokens 类型的转换。

func toTokens()

func toTokens(): Tokens

功能：实现 UInt8 类型到 Tokens 类型的转换。

返回值：

Tokens - 转换后的 Tokens。

类

class Annotation

public class Annotation <: Node {
    public init()
    public init(input: Tokens)
}

功能：表示编译器内置的注解节点。

一个 Annotation 节点：@CallingConv[xxx], @Attribute[xxx], @When[condition]等。

类型：RefExpr

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

异常：

ASTException - 当 Annotation 节点中没有条件表达式时，抛出异常。

prop identifier

public mut prop identifier: Token

功能：获取或设置 Annotation 节点的标识符，如 @CallingConv[xxx] 中的 CallingConv。

类型：Token

init()

public init()

功能：构造一个默认的 Annotation 对象。

init(Token)

public init(input: Token)

功能：根据输入的词法单元，构造一个 Annotation 对象。

参数：

input: Token - 将要构造 Annotation 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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(input: 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(input: Tokens)

功能：构造一个 ArrayLiteral 对象。

参数：

input: Tokens - 将要构造 ArrayLiteral 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 ArrayLiteral 节点时，抛出异常。

class AsExpr

public class AsExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 AsExpr 对象。

参数：

input: Tokens - 将要构造 AsExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 AsExpr 节点时，抛出异常。

class AssignExpr

public class AssignExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 AssignExpr 对象。

参数：

input: Tokens - 将要构造 AssignExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 AssignExpr 节点时，抛出异常。

class BinaryExpr

public class BinaryExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 BinaryExpr 对象。

参数：

input: Tokens - 将要构造 BinaryExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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()
}

功能：表示 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 对象。

class CallExpr

public class CallExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 CallExpr 对象。

参数：

input: Tokens - 将要构造 CallExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 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 对象。

参数：

inputs: Tokens - 将要构造 ClassDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 ClassDecl 节点时，抛出异常。

class ConstPattern

public class ConstPattern <: Pattern {
    public init()
    public init(input: Tokens)
}

功能：表示常量模式节点。

常量模式可以是整数字面量、字符字节字面量、浮点数字面量、字符字面量、布尔字面量、字符串字面量等字面量，如 case 1 => 0 中的 1。

prop litConstExpr

public mut prop litConstExpr: LitConstExpr

功能：获取或设置 ConstPattern 节点中的字面量表达式。

类型：LitConstExpr

init()

public init()

功能：构造一个默认的 ConstPattern 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 ConstPattern 对象。

参数：

input: Tokens - 将要构造 ConstPattern 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 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 open mut prop identifier: Token

功能：获取或设置定义节点的标识符，如 class foo {} 中的 foo。

类型：Token

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(input: 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

功能：获取或设置 DoWhileExpr 中 while 关键字之后的左括号。

类型：Token

prop rParen

public mut prop rParen: Token

功能：获取或设置 DoWhileExpr 中 while 关键字之后的右括号。

类型：Token

init()

public init()

功能：构造一个默认的 DoWhileExpr 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 DoWhileExpr 对象。

参数：

input: Tokens - 将要构造 DoWhileExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 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 对象。

参数：

inputs: Tokens - 将要构造 EnumDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 EnumDecl 节点时，抛出异常。

class EnumPattern

public class EnumPattern <: Pattern {
    public init()
    public init(input: Tokens)
}

功能：表示 enum 模式节点。

用于匹配 enum 的 constructor，如 case Year(n) => 1 中的 Year(n)。

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(input: Tokens)

功能：构造一个 EnumPattern 对象。

参数：

input: Tokens - 将要构造 EnumPattern 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 EnumPattern 节点时，抛出异常。

class ExceptTypePattern

public class ExceptTypePattern <: Pattern {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 ExceptTypePattern 对象。

参数：

input: Tokens - 将要构造 ExceptTypePattern 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 override mut prop identifier: Token

功能：ExtendDecl 节点继承 Decl 节点，但是不支持 identifier 属性，使用时会抛出异常。

类型：Token

异常：

ASTException - 当使用 identifier 属性时，抛出异常。

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 对象。

参数：

inputs: Tokens - 将要构造 ExtendDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 ExtendDecl 节点时，抛出异常。

class ForInExpr

public class ForInExpr <: Expr {
    public init()
    public init(input: 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

异常：

ASTException - 当 ForInExpr 节点中不存在 patternGuard 表达式时，抛出异常。

prop rParen

public mut prop rParen: Token

功能：获取或设置 ForInExpr 中的右括号。

类型：Token

init()

public init()

功能：构造一个默认的 ForInExpr 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 ForInExpr 对象。

参数：

input: Tokens - 将要构造 ForInExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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

异常：

ASTException - 当 FuncDecl 节点的函数返回类型是一个缺省值时，抛出异常。

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 对象。

参数：

inputs: Tokens - 将要构造 FuncDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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: Int64 和 b: 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(input: Tokens)

功能：构造一个 FuncParam 对象。

参数：

input: Tokens - 将要构造 FuncParam 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 FuncParam 节点时，抛出异常。

func isMemberParam()

public func isMemberParam(): Bool

功能：当前的函数参数是否是主构造函数中的参数。

返回值：

Bool - 布尔类型，如果是主构造函数中的参数，返回 true。

class FuncType

public class FuncType <: TypeNode {
    public init()
    public init(input: Tokens)
}

功能：表示函数类型节点。

由函数的参数类型和返回类型组成，参数类型与返回类型之间用 -> 分隔，如：(Int32) -> Unit。

prop arrow

public mut prop arrow: Token

功能：获取或设置 FuncType 节点参数类型与返回类型之间的 ->的词法单元。

类型：Token

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(input: Tokens)

功能：构造一个 FuncType 对象。

参数：

input: Tokens - 将要构造 FuncType 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 FuncType 节点时，抛出异常。

class GenericConstraint

public class GenericConstraint <: Node {
    public init()
}

功能：表示一个泛型约束节点。

一个 GenericConstraint 节点：interface Enumerable where U <: Bounded {} 中的 where where U <: Bounded。

说明：

通过 where 之后的 <: 运算符来声明，由一个下界与一个上界来组成。其中 <: 左边称为约束的下界，下界只能为类型变元。<: 右边称为约束上界，约束上界可以为类型。

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 T2 和 T3。

类型：Tokens

prop rAngle

public mut prop rAngle: Token

功能：获取或设置 GenericParam 节点中的右尖括号词法单元。

类型：Token

init()

public init()

功能：构造一个默认的 GenericParam 对象。

init(Tokens)

public init(parameters: Tokens)

功能：构造一个 GenericParam 对象。

参数：

parameters: Tokens - 将要构造 GenericParam 的类型形参的词法单元集合 (Tokens)。

class IfExpr

public class IfExpr <: Expr {
    public init()
    public init(input: Tokens)
}

功能：表示条件表达式。

可以根据判定条件是否成立来决定执行哪条代码分支。一个 IfExpr 节点中 if 是关键字，if 之后是一个小括号，小括号内可以是一个表达式或者一个 let 声明的解构匹配，接着是一个 Block，Block 之后是可选的 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

异常：

ASTException - 当前 IfExpr 节点没有 else 分支节点。

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(input: Tokens)

功能：构造一个 IfExpr 对象。

参数：

input: Tokens - 将要构造 IfExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 IfExpr 节点时，抛出异常。

class ImportList

public class ImportList <: Node {
    public init()
    public init(input: Tokens)
}

功能：表示包导入节点。

一个 ImportList 节点: import module.package.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(input: Tokens)

功能：构造一个 ImportList 对象。

参数：

input: Tokens - 将要构造 ImportList 类型的词法单元集合 (Tokens) 序列。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 ImportList 节点时，抛出异常。

func isImportMulti()

public func isImportMulti(): Bool

功能：判断 ImportList 节点是否导入了多个顶级定义或声明。

返回值：

Bool - 如果 ImportList 节点导入了多个顶级定义或声明，返回 true；反之，返回 false。

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 中的 a 和 b。

类型：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 节点中导入的定义或声明的别名词法单元序列，只有 importKind 为 ImportKind.Alias 时非空。如：import packageName.xxx as yyy 中的 as yyy。

类型：Tokens

prop lBrace

public mut prop lBrace: Token

功能：获取或设置 ImportContent 节点中的 { 操作符词法单元，只有 importKind 为 ImportKind.Multi 时非空。

类型：Token

prop items

public mut prop items: ArrayList<ImportContent>

功能：获取或设置 ImportContent 节点中被导入的所有项，只有 importKind 为 ImportKind.Multi 时非空。

类型：ArrayList<ImportContent>

prop commas

public mut prop commas: Tokens

功能：获取或设置 ImportContent 节点中的 , 操作符词法单元序列，只有 importKind 为 ImportKind.Multi 时非空。

类型：Tokens

prop rBrace

public mut prop rBrace: Token

功能：获取或设置 ImportContent 节点中的 } 操作符词法单元，只有 importKind 为 ImportKind.Multi 时非空。

类型：Token

init()

public init()

功能：构造一个默认的 ImportContent 对象。

func isImportAlias()

public func isImportAlias(): Bool

功能：判断 ImportContent 节点是否对导入项取了别名。

返回值：

Bool - ImportContent 节点是否对导入项取了别名。

func isImportAll()

public func isImportAll(): Bool

功能：判断 ImportContent 节点是否为全导入。

返回值：

Bool - ImportContent 节点是否为全导入。

func isImportMulti()

public func isImportMulti(): Bool

功能：判断 ImportContent 节点是否导入了多个顶级定义或声明。

返回值：

Bool - ImportContent 节点是否导入了多个顶级定义或声明。

func isImportSingle()

public func isImportSingle(): Bool

功能：判断 ImportContent 节点是否为单导入。

返回值：

Bool - ImportContent 节点是否为单导入。

class IncOrDecExpr

public class IncOrDecExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 IncOrDecExpr 对象。

参数：

input: Tokens - 将要构造 IncOrDecExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 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 对象。

参数：

inputs: Tokens - 将要构造 InterfaceDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 InterfaceDecl 节点时，抛出异常。

class IsExpr

public class IsExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 IsExpr 对象。

参数：

input: Tokens - 将要构造 IsExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 IsExpr 节点时，抛出异常。

class JumpExpr

public class JumpExpr <: Expr {
    public init()
    public init(input: Tokens)
}

功能：表示循环表达式的循环体中的 break 和 continue。

prop keyword

public mut prop keyword: Token

功能：获取或设置关键字。

类型：Token

init()

public init()

功能：构造一个默认的 JumpExpr 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 JumpExpr 对象。

参数：

input: Tokens - 将要构造 JumpExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 JumpExpr 节点时，抛出异常。

class LambdaExpr

public class LambdaExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 LambdaExpr 对象。

参数：

input: Tokens - 将要构造 LambdaExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 LambdaExpr 节点时，抛出异常。

class LetPatternExpr

public class LetPatternExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 LetPatternExpr 对象。

参数：

input: Tokens - 将要构造 LetPatternExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 LetPatternExpr 节点时，抛出异常。

class LitConstExpr

public class LitConstExpr <: Expr {
    public init()
    public init(input: Tokens)
}

功能：表示一个常量表达式节点。

一个 LitConstExpr 表达式："abc"，123 等。

prop literal

public mut prop literal: Token

功能：获取或设置 LitConstExpr 节点中的字面量。

类型：Token

init()

public init()

功能：构造一个默认的 LitConstExpr 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 LitConstExpr 对象。

参数：

input: Tokens - 将要构造 LitConstExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 ParenExpr 节点时，抛出异常。

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

异常：

ASTException - 当 MacroDecl 节点的函数返回类型是一个缺省值时，抛出异常。

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 对象。

参数：

inputs: Tokens - 将要构造 MacroDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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

异常：

ASTException - 当 MacroDecl 节点中没有声明节点时，抛出异常。

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 对象。

参数：

inputs: Tokens - 将要构造 MacroExpandDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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

功能：获取或设置宏调用节点的关键字 at。

类型：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(input: Tokens)

功能：构造一个 MacroExpandExpr 对象。

参数：

input: Tokens - 将要构造 MacroExpandExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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

异常：

ASTException - 当 MacroExpandParam 节点中没有声明节点时，抛出异常。

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

异常：

ASTException - 当 MainDecl 节点的函数返回类型是一个缺省值时，抛出异常。

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 对象。

参数：

inputs: Tokens - 将要构造 MainDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 block

public mut prop block: Block

功能：获取或设置 MatchCase 中的一系列声明或表达式节点。

类型：Block

prop expr

public mut prop expr: Expr

功能：获取或设置 MatchCase 中位于 case 后的表达式节点。

类型：Expr

异常：

ASTException - 当 MatchCase 节点中不存在表达式节点时，抛出异常。

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

异常：

ASTException - 当 MatchCase 节点中不存在 pattern guard 表达式时，抛出异常。

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(input: 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 开头，后跟一个或者多个由 Pattern 或 Expr节点，具体见 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(input: Tokens)

功能：构造一个 MatchExpr 对象。

参数：

input: Tokens - 将要构造 MatchExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 MatchExpr 节点时，抛出异常。

class MemberAccess

public class MemberAccess <: Expr {
    public init()
    public init(input: Tokens)
}

功能：表示成员访问表达式。

可以用于访问 class、interface、struct 等类型的成员。一个 MemberAccess 节点的形式为 T.a，T 为成员访问表达式的主体，a 表示成员的名字。

prop baseExpr

public mut prop baseExpr: Expr

功能：获取或设置 MemberAccess 节点的成员访问表达式主体。

类型：Expr

prop dot

public mut prop dot: Token

功能：获取或设置 MemberAccess 节点中的 .。

类型：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(input: Tokens)

功能：构造一个 MemberAccess 对象。

参数：

input: Tokens - 将要构造 MemberAccess 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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

sealed abstract 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 类型。

返回值：

Tokens - 转化后的 Tokens 类型节点。

func traverse(Visitor)

public func traverse(v: Visitor): Unit

功能：遍历当前语法树节点及其子节点。若提前终止遍历子节点的行为，可重写 visit 函数并调用 breakTraverse 函数提前终止遍历行为，详细见示例代码中自定义访问函数遍历 AST 对象示例的内容。

参数：

v: Visitor - Visitor 类型的实例。

class OptionalExpr

public class OptionalExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 OptionalExpr 对象。

参数：

input: Tokens - 将要构造 OptionalExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 OptionalExpr 节点时，抛出异常。

class PackageHeader

public class PackageHeader <: Node {
    public init()
    public init(input: Tokens)
}

功能：表示包声明节点。

一个 PackageHeader 节点: package define 或者 macro package define。

说明：

包声明以关键字 package 或 macro 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 中的 a 和 b。

类型：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(input: Tokens)

功能：构造一个 PackageHeader 对象。

参数：

input: Tokens - 将要构造 PackageHeader 类型的词法单元集合 (Tokens) 序列。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 PackageHeader 节点时，抛出异常。

class ParenExpr

public class ParenExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 ParenExpr 对象。

参数：

input: Tokens - 将要构造 ParenExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 ParenExpr 节点时，抛出异常。

class ParenType

public class ParenType <: TypeNode {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 ParenType 对象。

参数：

input: Tokens - 将要构造 ParenType 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 ParenType 节点时，抛出异常。

class Pattern

public open class Pattern <: Node

功能：所有模式匹配节点的父类，继承自 Node 节点。

class PrefixType

public class PrefixType <: TypeNode {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 PrefixType 对象。

参数：

input: Tokens - 将要构造 PrefixType 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 对象。

参数：

inputs: Tokens - 将要构造 PrimaryCtorDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 PrimaryCtorDecl 节点时，抛出异常。

func isConst()

public func isConst(): Bool

功能：判断是否是一个 Const 类型的节点。

返回值：

Bool - 当前节点为 Const 类型的节点时，返回 true；反之，返回 false。

class PrimitiveType

public class PrimitiveType <: TypeNode {
    public init()
    public init(input: Tokens)
}

功能：表示一个基本类型节点。

例如数值类型，Rune 类型，布尔类型等。

prop keyword

public mut prop keyword: Token

功能：获取或设置构造 PrimitiveType 类型的关键字，如 Int8。

类型：Token

init()

public init()

功能：构造一个默认的 PrimitiveType 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 PrimitiveType 对象。

参数：

input: Tokens - 将要构造 PrimitiveType 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 PrimitiveType 节点时，抛出异常。

class PrimitiveTypeExpr

public class PrimitiveTypeExpr <: Expr {
    public init()
    public init(input: Tokens)
}

功能：表示基本类型表达式节点。

PrimitiveTypeExpr 节点：编译器内置的基本类型作为表达式出现在节点中。如 Int64.toSting() 中的 Int64。

prop keyword

public mut prop keyword: Token

功能：获取或设置 PrimitiveTypeExpr 中的基本类型关键字。

类型：Token

init()

public init()

功能：构造一个默认的 PrimitiveTypeExpr 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 PrimitiveTypeExpr 对象。

参数：

input: Tokens - 将要构造 PrimitiveTypeExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 PrimitiveTypeExpr 节点时，抛出异常。

class Program

public class Program <: Node {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 Program 对象。

参数：

input: Tokens - 将要构造 Program 类型的词法单元集合 (Tokens) 序列。

异常：

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 对象。

参数：

inputs: Tokens - 将要构造 PropDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 PropDecl 节点时，抛出异常。

class QualifiedType

public class QualifiedType <: TypeNode {
    public init()
    public init(input: Tokens)
}

功能：表示一个用户自定义成员类型。

例如 var a : T.a 中的 T.a, 其中 T 是包名，a 是从 T 包中导入的类型。

prop baseType

public mut prop baseType: Expr

功能：获取或设置 QualifiedType 节点的成员访问类型主体，如 var a : T.a 中的 T。

类型：Expr

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(input: Tokens)

功能：构造一个 QualifiedType 对象。

参数：

input: Tokens - 将要构造 QualifiedType 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 QualifiedType 节点时，抛出异常。

class QuoteExpr

public class QuoteExpr <: Expr {
    public init()
    public init(input: 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

功能：获取或设置 QuoteExpr 的通配符关键字。

类型：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(input: Tokens)

功能：构造一个 QuoteExpr 对象。

参数：

input: Tokens - 将要构造 QuoteExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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(input: Tokens)
}

功能：表示包含区间操作符的表达式。

RangeExpr 节点：存在两种 Range 操作符：.. 和 ..=，分别用于创建左闭右开和左闭右闭的 Range 实例。它们的使用方式分别为 start..end:step 和 start..=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

异常：

ASTException - 当 RangeExpr 中未设置序列前后两个元素之间的差值时，抛出异常。

init()

public init()

功能：构造一个默认的 RangeExpr 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 RangeExpr 对象。

参数：

input: Tokens - 将要构造 RangeExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 RangeExpr 节点时，抛出异常。

class RefExpr

public class RefExpr <: Expr {
    public init()
    public init(input: Tokens)
}

功能：表示一个使用自定义类型节点相关的表达式节点。

一个 RefExpr 节点：var ref = refNode + 1 中的 refNode 是一个 RefExpr。

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(input: Tokens)

功能：构造一个 RefExpr 对象。

参数：

input: Tokens - 将要构造 RefExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 RefExpr 节点时，抛出异常。

class RefType

public class RefType <: TypeNode {
    public init()
    public init(input: Tokens)
}

功能：表示一个用户自定义类型节点。

例如 var a : A = A() 中的 A。

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(input: Tokens)

功能：构造一个 RefType 对象。

参数：

input: Tokens - 将要构造 RefType 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 RefType 节点时，抛出异常。

class ReturnExpr

public class ReturnExpr <: Expr {
    public init()
    public init(input: Tokens)
}

功能：表示 return 表达式节点。

一个 ReturnExpr 节点：return 1。

prop expr

public mut prop expr: Expr

功能：获取或设置 ReturnExpr 节点中的表达式节点。

类型：Expr

异常：

ASTException - 当 ReturnExpr 节点没有表达式时，抛出异常。

prop keyword

public mut prop keyword: Token

功能：获取或设置 ReturnExpr 节点中的关键字。

类型：Token

init()

public init()

功能：构造一个默认的 ReturnExpr 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 ReturnExpr 对象。

参数：

input: Tokens - 将要构造 ReturnExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 ReturnExpr 节点时，抛出异常。

class SpawnExpr

public class SpawnExpr <: Expr {
    public init()
    public init(input: 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

异常：

ASTException - 当 SpawnExpr 中不含有上下文表达式时，抛出异常。

init()

public init()

功能：构造一个默认的 SpawnExpr 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 SpawnExpr 对象。

参数：

input: Tokens - 将要构造 SpawnExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 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 对象。

参数：

inputs: Tokens - 将要构造 StructDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 StructDecl 节点时，抛出异常。

class SubscriptExpr

public class SubscriptExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 SubscriptExpr 对象。

参数：

input: Tokens - 将要构造 SubscriptExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 SubscriptExpr 节点时，抛出异常。

class SynchronizedExpr

public class SynchronizedExpr <: Expr {
    public init()
    public init(input: 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

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(input: Tokens)

功能：构造一个 SynchronizedExpr 对象。

参数：

input: Tokens - 将要构造 SynchronizedExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 SynchronizedExpr 节点时，抛出异常。

class ThisType

public class ThisType <: TypeNode {
    public init()
    public init(input: Tokens)
}

功能：表示 This 类型节点。

prop keyword

public mut prop keyword: Token

功能：获取或设置 ThisType 节点关键字 This 的词法单元。

类型：Token

init()

public init()

功能：构造一个默认的 ThisType 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 ThisType 对象。

参数：

input: Tokens - 将要构造 ThisType 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 ThisType 节点时，抛出异常。

class ThrowExpr

public class ThrowExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 ThrowExpr 对象。

参数：

input: Tokens - 将要构造 ThrowExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 ThrowExpr 节点时，抛出异常。

class Tokens

public open class Tokens <: ToString & Iterable<Token> {
    public init()
    public init(tokArray: Array<Token>)
    public init(tokArrayList: ArrayList<Token>)
}

功能：对 Token 序列进行封装的类型。

prop size

public prop size: Int64

功能：获取 Tokens 对象中 Token 类型的数量。

类型：Int64

init()

public init()

功能：构造一个默认的 Tokens 对象。

init(Array<Token>)

public init(tokArray: Array<Token>)

功能：构造一个 Tokens 对象。

参数：

tokArray: Array<Token> - 一组包含 Token 的 Array 类型。

init(ArrayList<Token>)

public init(tokArrayList: ArrayList<Token>)

功能：构造一个 Tokens 对象。

参数：

tokArrayList: ArrayList<Token> - 一组包含 Token 的 ArrayList 类型。

func append(Node)

public func append(node: Node): Tokens

功能：将当前的 Tokens 与传入节点所转换得到的 Tokens 进行拼接。

参数：

node: Node - 待拼接的 Node 对象。

返回值：

Tokens - 拼接后的 Tokens 类型。

func append(Token)

public func append(token: Token): Tokens

功能：将当前的 Tokens 与传入的 Token 进行拼接。

参数：

token: Token - 待拼接的 Token 对象。

返回值：

Tokens - 拼接后的 Tokens 类型。

func append(Tokens)

public func append(tokens: Tokens): Tokens

功能：在当前的 Tokens 后追加传入的 Tokens 进行拼接（该接口性能较其他拼接函数表现更好）。

参数：

tokens: Tokens - 待拼接的 Tokens 对象。

返回值：

Tokens - 拼接后的 Tokens 类型。

func concat(Tokens)

public func concat(tokens: Tokens): Tokens

功能：将当前的 Tokens 与传入的 Tokens 进行拼接。

参数：

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 - 待索引的数值。

返回值：

Token - 指定索引的 Token。

func iterator()

public func iterator(): TokensIterator

功能：获取 Tokens 对象中的一个迭代器对象。

返回值：

TokensIterator - Tokens 对象的迭代器对象。

func remove(Int64)

public func remove(index: Int64): Tokens

功能：删除指定位置的 Token 对象。

参数：

index: Int64 - 被删除的 Token 的索引。

返回值：

Tokens - 删除指定位置的 Token 后的 Tokens 对象。

func toString()

public func toString(): String

功能：将 Tokens 转化为 String 类型。

operator func +(Token)

public operator func +(token: Token): Tokens

功能：使用当前 Token 与另一个 Token 相加以获取新的 Tokens。

参数：

token: Token - 待操作的另一个 Token 对象。

返回值：

Tokens - 新拼接 Tokens 后的词法单元集合。

operator func +(Tokens)

public operator func +(tokens: Tokens): Tokens

功能：使用当前 Token 与 Tokens 相加以获取新的 Tokens 类型。

参数：

tokens: Tokens - 待操作的一组 Tokens 对象。

返回值：

Tokens - 新拼接 Tokens 后的词法单元集合。

operator func [](Int64)

public operator func [](index: Int64): Token

功能：操作符重载，通过索引值获取对应 Token。

参数：

index: Int64 - 待索引的数值。

返回值：

Token - 返回索引对应的 Token。

operator func [](Range<Int64>)

public operator func [](range: Range<Int64>): Tokens

功能：操作符重载，通过 range 获取对应 Tokens 切片。

参数：

range: Range<Int64> - 待索引的切片范围。

返回值：

Tokens - 返回切片索引对应的 Tokens。

异常：

IllegalArgumentException - 当 range.step 不等于 1 时，抛出异常。
IndexOutOfBoundsException - 当 range 无效时，抛出异常。

class TokensIterator

public class TokensIterator <: Iterator<Token> {
    public init(tokens: Tokens)
}

功能：实现 Tokens 的迭代器功能。

init(Tokens)

public init(tokens: Tokens)

功能：构造一个 TokensIterator 对象。

参数：

tokens: Tokens - 传入 Tokens。

func iterator()

public func iterator(): Iterator<Token>

功能：获取当前迭代器实例。

返回值：

Iterator<Token> - 当前迭代器实例。

func next()

public func next(): Option<Token>

功能：获取迭代器中的下一个值。

返回值：

Option<Token> - 返回 Option<Token> 类型，当遍历结束后，返回 None。

func peek()

public func peek(): Option<Token>

功能：获取迭代器中的当前值。

返回值：

Option<Token> - 返回 Option<Token> 类型，当遍历结束后，返回 None。

func seeing(TokenKind)

public func seeing(kind: TokenKind): Bool

功能：判断当前节点的 Token 类型是否是传入的类型。

参数：

kind: TokenKind - 需要判断的 TokenKind 类型。

返回值：

Bool - 如果当前节点的 TokenKind 与传入类型相同，返回 true，否则返回 false。

class TrailingClosureExpr

public class TrailingClosureExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 TrailingClosureExpr 对象。

参数：

input: Tokens - 将要构造 TrailingClosureExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 TrailingClosureExpr 节点。

class TryExpr

public class TryExpr <: Expr {
    public init()
    public init(input: 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

异常：

ASTException - 当 TryExpr 节点无 Finally 块节点时，抛出异常。

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(input: Tokens)

功能：构造一个 TryExpr 对象。

参数：

input: Tokens - 将要构造 TryExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 TryExpr 节点时，抛出异常。

class TupleLiteral

public class TupleLiteral <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 TupleLiteral 对象。

参数：

input: Tokens - 将要构造 TupleLiteral 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 TupleLiteral 节点时，抛出异常。

class TuplePattern

public class TuplePattern <: Pattern {
    public init()
    public init(input: Tokens)
}

功能：表示 Tuple 模式节点。

用于 tuple 值的匹配，如 case ("Bob", age) => 1 中的 ("Bob", age)。

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(input: Tokens)

功能：构造一个 TuplePattern 对象。

参数：

input: Tokens - 将要构造 TuplePattern 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 TuplePattern 节点时，抛出异常。

class TupleType

public class TupleType <: TypeNode {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 TupleType 对象。

参数：

input: Tokens - 将要构造 TupleType 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 对象。

参数：

inputs: Tokens - 将要构造 TypeAliasDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 TypeAliasDecl 节点时，抛出异常。

class TypeConvExpr

public class TypeConvExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 TypeConvExpr 对象。

参数：

input: Tokens - 将要构造 TypeConvExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 TypeConvExpr 节点时，抛出异常。

class TypeNode

public open class TypeNode <: Node

功能：所有类型节点的父类，继承自 Node。

prop typeParameterName

public mut prop typeParameterName: Token

功能：获取或设置类型节点的参数，如：(p1:Int64, p2:Int64) 中的 p1 和 p2，可能为 ILLEGAL 的词法单元。

类型：Token

class TypePattern

public class TypePattern <: Pattern {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 TypePattern 对象。

参数：

input: Tokens - 将要构造 TypePattern 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 TypePattern 节点时，抛出异常。

class UnaryExpr

public class UnaryExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 UnaryExpr 对象。

参数：

input: Tokens - 将要构造 UnaryExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 UnaryExpr 节点时，抛出异常。

class VArrayExpr

public class VArrayExpr <: Expr {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 VArrayExpr 对象。

参数：

input: Tokens - 将要构造 VArrayExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 VArrayExpr 节点时，抛出异常。

class VArrayType

public class VArrayType <: TypeNode {
    public init()
    public init(input: 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(input: Tokens)

功能：构造一个 VArrayType 对象。

参数：

input: Tokens - 将要构造 VArrayType 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 VArrayType 节点时，抛出异常。

class VarDecl

public class VarDecl <: Decl {
    public init()
    public init(inputs: Tokens)
}

功能：表示变量定义节点。

一个 VarDecl 节点: var a: String，var 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

异常：

ASTException - 当 VarDecl 节点没有声明变量类型时，抛出异常。

prop expr

public mut prop expr: Expr

功能：获取或设置 VarDecl 节点的变量初始化节点。

类型：Expr

异常：

ASTException - 当 VarDecl 节点没有对变量进行初始化时，抛出异常。

prop pattern

public mut prop pattern: Pattern

功能：获取或设置 VarDecl 节点的 pattern 节点。

类型：Pattern

异常：

ASTException - 当 VarDecl 节点没有声明 pattern 节点时，抛出异常。

init()

public init()

功能：构造一个默认的 VarDecl 对象。

init(Tokens)

public init(inputs: Tokens)

功能：构造一个 VarDecl 对象。

参数：

inputs: Tokens - 将要构造 VarDecl 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 中的 RED 为 Enum 构造器。

prop identifier

public mut prop identifier: Token

功能：获取或设置 VarOrEnumPattern 节点中的标识符的词法单元。

类型：Token

init()

public init()

功能：构造一个默认的 VarOrEnumPattern 对象。

init(Tokens)

public init(identifier: Token)

功能：构造一个 VarOrEnumPattern 对象。

参数：

identifier: Token - 当将要构造 VarOrEnumPattern 类型的词法单元。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 VarOrEnumPattern 节点时，抛出异常。

class VarPattern

public class VarPattern <: Pattern {
    public init()
    public init(identifier: Token)
}

功能：表示绑定模式节点。

使用一个合法的标识符表示，一般适用于声明节点中，如 case n => 0 中的 n。

prop identifier

public mut prop identifier: Token

功能：获取或设置 VarPattern 节点中的标识符符的词法单元。

类型：Token

init()

public init()

功能：构造一个默认的 VarPattern 对象。

init(Tokens)

public init(identifier: Token)

功能：构造一个 VarPattern 对象。

参数：

identifier: Token - 将要构造 VarPattern 类型的词法单元。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 VarPattern 节点时，抛出异常。

class Visitor

public open 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(input: 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

功能：获取或设置 WhileExpr 中 while 关键字之后的左括号。

类型：Token

prop rParen

public mut prop rParen: Token

功能：获取或设置 WhileExpr 中 while 关键字之后的右括号。

类型：Token

init()

public init()

功能：构造一个默认的 WhileExpr 对象。

init(Tokens)

public init(input: Tokens)

功能：构造一个 WhileExpr 对象。

参数：

input: Tokens - 将要构造 WhileExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 对象。

参数：

keyword: Tokens - 将要构造 WildcardExpr 类型的词法单元集合 (Tokens)。

异常：

ASTException - 当输入的 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 对象。

参数：

keyword: Tokens - 将要构造 WildcardPattern 类型的词法单元集合（Tokens）。

异常：

ASTException - 当输入的 Tokens 类型无法构造为 WildcardPattern 节点时，抛出异常。

枚举

enum DiagReportLevel

public enum DiagReportLevel {
    ERROR|
    WARNING
}

功能：表示报错接口的信息等级，支持 ERROR 和 WARNING 两种等级。

ERROR

ERROR

功能：构造一个表示 ERROR 的枚举实例。

WARNING

WARNING

功能：构造一个表示 WARNING 的枚举实例。

func level()

public func level(): Int32

功能：返回枚举值对应的整型。

返回值：

Int32 - 枚举值对应的整型。ERROR 返回 0，WARNING 返回 1。

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. "`a.b`"  */
    INTEGER_LITERAL|          /*  e.g. "1"      */
    CHAR_BYTE_LITERAL|        /*  e.g. "b'x'"   */
    FLOAT_LITERAL|            /*  e.g. "'1.0'"  */
    COMMENT|                  /*  e.g. "/*xx*/" */
    NL|                       /*  newline         */
    END|                      /*  end of file     */
    SENTINEL|                 /*  ";"             */
    CHAR_LITERAL|             /*  e.g. "'x'"      */
    STRING_LITERAL|           /*  e.g. ""xx""     */
    JSTRING_LITERAL|          /*  e.g. "J"xx""     */
    BYTE_STRING_ARRAY_LITERAL /*  e.g. "b"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 的枚举实例。

BYTE_STRING_ARRAY_LITERAL

BYTE_STRING_ARRAY_LITERAL

功能：构造一个表示字节数组字面量的枚举实例。

CASE

CASE

功能：构造一个表示 case 的枚举实例。

CATCH

CATCH

功能：构造一个表示 catch 的枚举实例。

CFUNC

CFUNC

功能：构造一个表示 cfunc 的枚举实例。

CHAR_BYTE_LITERAL

CHAR_BYTE_LITERAL

功能：构造一个表示字符字节字面量的枚举实例。

CHAR_LITERAL

CHAR_LITERAL

功能：构造一个表示字符字面量的枚举实例。

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 的枚举实例。

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 类型转化为字符串类型表示。

返回值：

String - TokenKind 转换后的字符串值。

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 类型转化为字符串类型表示。

返回值：

String - ImportKind 转换后的字符串值。

结构体

struct Position

public struct Position {
    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: UInt32

功能：获取列号信息。

类型：UInt32

let fileID

public let fileID: UInt32

功能：获取文件 ID 信息。

类型：UInt32

let line

public let line: UInt32

功能：获取行号信息。

类型：UInt32

init()

public init()

功能：构造一个默认的 Position 实例，其中 fileID、line、column 成员变量均为 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。

operator func !=(Position)

public operator func !=(pos: Position): Bool

功能：比较两个 Position 实例是否不等。

参数：

pos: Position - 与当前位置比较的另一个位置实例。

返回值：

Bool - 当两个 Position 实例不完全相等时返回 true。

operator func ==(Position)

public operator func ==(pos: Position): Bool

功能：比较两个 Position 实例是否相等。

参数：

pos: Position - 与当前位置比较的另一个位置实例。

返回值：

Bool - 当两个 Position 实例完全相等时返回 true。

struct Token

public struct Token {
    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 类型为 ILLEGAL，value 为空字符串，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 值。

异常：

IllegalArgumentException - 当输入的 kind 与 value 不匹配时，抛出异常点。

func addPosition(UInt32, Int32, Int32)

public func addPosition(fileID: UInt32, line: Int32, colum: Int32)

功能：补充词法单元的位置信息。

参数：

fileID: UInt32 - Token 所在的 fileID。
line: Int32 - Token 所在的行号。
colum: Int32 - Token 所在的列号。

func dump()

public func dump(): Unit

功能：将 Token 的信息打印出来。

operator func !=(Token)

public operator func !=(token: Token): Bool

功能：判断两个 Token 对象是否不相等。

参数：

token: Token - 待比较的另一个 Token 对象。

返回值：

Bool - 两个词法单元的种类 ID、值、位置不相同时，返回 true。

operator func +(Token)

public operator func +(token: Token): Tokens

功能：使用当前 Token 添加一个 Token 以获取新的 Tokens。

参数：

token: Token - 待添加的另一个 Token 对象。

返回值：

Tokens - 添加新的 Tokens 后的词法单元集合。

operator func +(Tokens)

public operator func +(tokens: Tokens): Tokens

功能：使用当前 Token 添加一个 Tokens 以获取新的 Tokens。

参数：

tokens: Tokens - 待添加的另一组 Token 对象集合。

返回值：

Tokens - 添加新的 Tokens 后的词法单元集合。

operator func ==(Token)

public operator func ==(token: Token): Bool

功能：判断两个 Token 对象是否相等。

参数：

token: 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 宏中，在代码示例的宏调用场景下，由于 Outter 和 Inner 在调用时不存在这样的嵌套关系，因此编译器将报告一个错误。

宏定义如下：

// 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 内容进行自定义报错。

自定义报错接口提供同原生编译器报错一样的输出格式，允许用户报 warning 和 error 两类错误提示信息。

正确使用示例

宏定义如下：

// 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），又称字节顺序，又称尾序，在计算机科学领域中，指存储器中或在数字通信链路中，组成多字节的字的字节的排列顺序。

在几乎所有的机器上，多字节对象都被存储为连续的字节序列。

字节的排列方式有两个通用规则。例如，将一个多位数的低位放在较小的地址处，高位放在较大的地址处，则称小端序；反之则称大端序。在网络应用中，字节序是一个必须被考虑的因素，因为不同机器类型可能采用不同标准的字节序，所以均按照网络标准转化。

大端序

大端序（英：big-endian）或称大尾序。

数据以8位为单位:

地址增长方向：

... → 0x0A → 0x0B → 0x0C → 0x0D → ...

示例中，最高位字节是0x0A 存储在最低的内存地址处。下一个字节0x0B存在后面的地址处。正类似于十六进制字节从左到右的阅读顺序。
数据以16位为单位:

地址增长方向：... → 0x0A0B → 0x0C0D → ...

最高的16位单元0x0A0B存储在低位。

小端序

小端序（英：little-endian）或称小尾序。

数据以8位为单位:

地址增长方向：

... → 0x0D → 0x0C → 0x0B → 0x0A → ...

最低位字节是0x0D 存储在最低的内存地址处。后面字节依次存在后面的地址处。
数据以16位为单位:

地址增长方向：

... → 0x0C0D → 0x0A0B → ...

最低的16位单元0x0C0D存储在低位。
更改地址的增长方向:

地址增长方向：

... ← 0x0A ← 0x0B ← 0x0C ← 0x0D ← ...

最低有效位（LSB）是0x0D 存储在最低的内存地址处。后面字节依次存在后面的地址处。

地址增长方向：

... ← 0x0A0B ← 0x0C0D ← ...

最低的16位单元0x0C0D存储在低位。

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 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 T 值时，抛出异常。

func writeBigEndian(Array<Byte>)

func writeBigEndian(buffer: Array<Byte>): Int64

功能：将 T 值以大端序的方式写入字节数组中。

参数：

buffer: Array<Byte> - 缓冲区，用于存放待写入的数据。

返回值：

Int64 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 T 值时，抛出异常。

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> - 缓冲区，用于存放待读取的数据。

返回值：

Bool - Bool 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Bool 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Bool 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 0)
    let n = true.writeBigEndian(buffer)
    @Assert(n, 1)
    @Assert(buffer[..n], [0x01])
}

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> - 缓冲区，用于存放待读取的数据。

返回值：

Float16 - Float16 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Float16 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Float16 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Float32 - Float32 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Float32 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Float32 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Float64 - Float64 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Float64 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Float64 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Int16 - Int16 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Int16 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Int16 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Int32 - Int32 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Int32 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Int32 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Int64 - Int64 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Int64 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Int64 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Int8 - Int8 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Int8 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Int8 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

UInt16 - UInt16 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 UInt16 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 UInt16 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

UInt32 - UInt32 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 UInt32 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 UInt32 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

UInt64 - UInt64 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 UInt64 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 UInt64 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

UInt8 - UInt8 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 UInt8 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 UInt8 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 T 值时，抛出异常。

func writeLittleEndian(Array<Byte>)

func writeLittleEndian(buffer: Array<Byte>): Int64

功能：将 T 值以小端序的方式写入字节数组中。

参数：

buffer: Array<Byte> - 缓冲区，用于存放待写入的数据。

返回值：

Int64 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 T 值时，抛出异常。

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> - 缓冲区，用于存放待读取的数据。

返回值：

Bool - Bool 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Bool 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Bool 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Float16 - Float16 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Float16 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Float16 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Float32 - Float32 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Float32 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Float32 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Float64 - Float64 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Float64 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Float64 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Int16 - Int16 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Int16 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Int16 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Int32 - Int32 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Int32 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Int32 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Int64 - Int64 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Int64 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Int64 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

Int8 - Int8 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 Int8 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 Int8 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

UInt16 - UInt16 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 UInt16 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 UInt16 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

UInt32 - UInt32 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 UInt32 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 UInt32 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

UInt64 - UInt64 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 UInt64 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 UInt64 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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> - 缓冲区，用于存放待读取的数据。

返回值：

UInt8 - UInt8 值。

异常：

IllegalArgumentException - 当 buffer 太小，不足以读出 UInt8 值时，抛出异常。

示例：

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 - 写入的数据的字节数。

异常：

IllegalArgumentException - 当 buffer 太小，不足以存储 UInt8 值时，抛出异常。

示例：

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

main() {
    let buffer = Array<Byte>(8, item: 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 值的字节顺序。

返回值：

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 值的字节顺序。

返回值：

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 值的字节顺序。

返回值：

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 值的字节顺序。

返回值：

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 值的字节顺序。

返回值：

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 值的字节顺序。

返回值：

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 值的字节顺序。

返回值：

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 值的字节顺序。

返回值：

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>) where T <: Equatable<T>	统计迭代器包含元素数量。
enumerate<T>(Iterable<T>)	用于获取带索引的迭代器。
filter<T>((T) -> Bool)	筛选出满足条件的元素。
filterMap<T, R>((T) -> Option<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> 接口实例。

结构体

结构体名	功能
EntryView<K, V> where K <: Hashable & Equatable<K>	HashMap<K, V> where K <: Hashable & Equatable<K> 中某一个键的视图。
TreeMapNode<K, V> where K <: Comparable<K>	TreeMap<K, V> where K <: Comparable<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> - 给定的迭代器。

返回值：

ArrayList<T> - 返回一个 ArrayList。

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)> - 给定的迭代器。

返回值：

HashMap < K, V > - 返回一个 HashMap。

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> - 给定的迭代器。

返回值：

HashSet<T> - 返回一个 HashSet。

func collectString<T>(String) where T <: ToString

public func collectString<T>(delimiter!: String = ""): (Iterable<T>) -> String where T <: ToString

功能：将一个对应元素实现了 ToString 接口的迭代器转换成 String 类型。

参数：

delimiter!: String - 字符串拼接分隔符。

返回值：

(Iterable<T>) -> String - 返回一个转换函数。

func concat<T>(Iterable<T>)

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

功能：串联两个迭代器。

参数：

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

返回值：

(Iterable<T>) -> Iterator<T> - 返回一个串联函数。

func contains<T>(T) where T <: Equatable<T>

public func contains<T>(element: T): (Iterable<T>) -> Bool where T <: Equatable<T>

功能：遍历所有元素，判断是否包含指定元素并返回该元素。

参数：

element: T - 要查找的元素。

返回值：

(Iterable<T>) -> Bool - 返回一个查找函数。

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> - 给定的迭代器。

返回值：

Iterator <(Int64, T) > - 返回一个带索引的迭代器。

func filter<T>((T) -> Bool)

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

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

参数：

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

返回值：

(Iterable<T>) -> Iterator<T> - 返回一个筛选函数。

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

public func filterMap<T, R>(transform: (T)-> ?R): (Iterable<T>) ->Iterator<R>

功能：同时进行筛选操作和映射操作，返回一个新的迭代器。

参数：

transform: (T) -> Option<T> - 给定的映射函数。函数返回值为 Some 对应 filter 的 predicate 为 true，反之表示 false。

返回值：

(Iterable<T>) -> Iterator<T> - 返回一个筛选和映射的函数。

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> - 给定的映射函数。

返回值：

(Iterable<T>) -> Iterator<R> - 返回一个带 flatten 功能的映射函数。

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<R> - 返回一个能对迭代器每个元素执行额外操作的函数。

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 - 给定的映射函数。

返回值：

(Iterable<T>) -> Iterator<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 - 给定的操作函数。

返回值：

(Iterable<T>) -> Option<T> - 返回一个归并函数。

func skip<T>(Int64)

public func skip<T>(count: Int64): (Iterable<T>) -> Iterator<T>

功能：从迭代器跳过特定个数。

参数：

count: Int64 - 要跳过的个数。

返回值：

(Iterable<T>) -> Iterator<T> - 返回一个跳过指定数量元素的函数。

异常：

IllegalArgumentException - 当 count < 0 时，抛出异常。

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() 跳过特定个数的函数。

异常：

IllegalArgumentException - 当 count <= 0 时，抛出异常。

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> - 返回一个取出指定数量元素的函数。

异常：

IllegalArgumentException - 当 count < 0 时，抛出异常。

func zip<T, R>(Iterable<R>)

public func zip<T, R>(other: Iterable<R>): (Iterable<T>) -> Iterator<(T, R)>

功能：将两个迭代器合并成一个（长度取决于短的那个迭代器）。

参数：

other: Iterable<R> - 要合并的其中一个迭代器。

返回值：

(Iterable<T>) -> Iterator <(T, 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。

返回值：

Option<V> - Map 中与 Key 对应的值。

func isEmpty()

func isEmpty(): Bool

功能：检查 Map 是否为空。

返回值：

Bool - 如果 Map 为空，返回 true; 否则，返回 false。

func iterator()

func iterator(): Iterator<(K, V)>

功能：返回 Map 的迭代器。

返回值：

Iterator <(K, V) > - Map 的迭代器。

func keys()

func keys(): EquatableCollection<K>

功能：返回 Map 中所有的 key，并将所有 key 存储在一个 EquatableCollection<K> 容器中。

返回值：

EquatableCollection<K> - 保存所有返回的 key。

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。

返回值：

Option<V> - 从 Map 中移除的键对应的值。用 Option 封装。

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> 容器中。

返回值：

Collection<V> - 保存所有返回的 value。

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。

返回值：

Set<T> - 新的 Set<T>。

func contains(T)

func contains(element: T): Bool

功能：如果该集合包含指定元素，则返回 true。

参数：

element: T - 需要判断的元素。

返回值：

Bool - 如果包含，则返回 true；否则，返回 false。

func containsAll(Collection<T>)

func containsAll(elements: Collection<T>): Bool

功能：检查该集合是否包含其他集合。

参数：

elements: Collection<T> - 其他集合。

返回值：

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 中的所有元素。

参数：

elements: Collection<T> - 传入 Collection<T>。

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()

功能：构造一个初始容量大小为默认值16的ArrayList。

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。这些元素按照集合的迭代器返回的顺序排列。

参数：

elements: Collection<T> - 传入集合。

init(Int64)

public init(capacity: Int64)

功能：构造一个初始容量为指定大小的 ArrayList。

参数：

capacity: Int64 - 指定的初始容量大小。

异常：

IllegalArgumentException - 如果参数的大小小于 0 则抛出异常。

init(Int64, (Int64) -> T)

public init(size: Int64, initElement: (Int64) -> T)

功能：构造具有指定初始元素个数和指定规则函数的 ArrayList。该构造函数根据参数 size 设置 ArrayList 的容量。

参数：

size: Int64 - 初始化函数元素个数。
initElement: (Int64) ->T - 传入初始化函数。

异常：

IllegalArgumentException - 如果 size 小于 0 则抛出异常。

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 的容量大小。

返回值：

Int64 - 此 ArrayList 的容量大小。

func clear()

public func clear(): Unit

功能：从此 ArrayList 中删除所有元素。

示例：

使用示例见 ArrayList 的 remove/clear/slice 函数。

func clone()

public func clone(): ArrayList<T>

功能：返回此ArrayList实例的拷贝(浅拷贝)。

返回值：

ArrayList<T> - 返回新 ArrayList<T>。

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 大小的位置中可能包含有未初始化的元素，对其进行访问可能会产生未定义的行为。

返回值：

Array<T> - ArrayList 的底层原始数据。

func insert(Int64, T)

public func insert(index: Int64, element: T): Unit

功能：在此 ArrayList 中的指定位置插入指定元素。

参数：

index: Int64 - 插入元素的目标索引。
element: T - 要插入的 T 类型元素。

异常：

IndexOutOfBoundsException - 当 index 超出范围时，抛出异常。

示例：

使用示例见 ArrayList 的 append/insert 函数。

func insertAll(Int64, Collection<T>)

public func insertAll(index: Int64, elements: Collection<T>): Unit

功能：从指定位置开始，将指定集合中的所有元素插入此 ArrayList。

函数会按照迭代器顺序遍历入参中的集合，并且将所有元素插入到指定位置。

参数：

index: Int64 - 插入集合的目标索引。
elements: Collection<T> - 要插入的 T 类型元素集合。

异常：

IndexOutOfBoundsException - 当 index 超出范围时，抛出异常。

示例：

使用示例见 ArrayList 的 remove/clear/slice 函数。

func isEmpty()

public func isEmpty(): Bool

功能：判断 ArrayList 是否为空。

返回值：

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

func iterator()

public func iterator(): Iterator<T>

功能：返回此 ArrayList 中元素的迭代器。

返回值：

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 - 被移除的元素。

异常：

IndexOutOfBoundsException - 当 index 超出范围时，抛出异常。

示例：

使用示例见 ArrayList 的 remove/clear/slice 函数。

func remove(Range<Int64>)

public func remove(range: Range<Int64>): Unit

功能：删除此 ArrayList 中 Range 范围所包含的所有元素。

注意：

如果参数 range 是使用 Range 构造函数构造的 Range 实例，hasEnd 为 false 时，end 值不生效，且不受构造时传入的 isClosed 的值的影响，数组切片取到原数组最后一个元素。

参数：

range: Range<Int64> - 需要被删除的元素的范围。

异常：

IllegalArgumentException - 当 range 的 step 不等于 1 时抛出异常。
IndexOutOfBoundsException - 当 range 的 start 或 end 小于 0，或 end 大于 Array 的长度时抛出。

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 - 将要扩容的大小。

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 类型元素。

异常：

IndexOutOfBoundsException - 当 index 小于 0 或者大于等于 ArrayList 中的元素数量时，抛出异常。

示例：

使用示例见 ArrayList 的 get/set 函数。

func slice(Range<Int64>)

public func slice(range: Range<Int64>): ArrayList<T>

功能：以传入参数 range 作为索引，返回索引对应的 ArrayList<T>。

注意：

如果参数 range 是使用 Range 构造函数构造的 Range 实例，有如下行为：

start 的值就是构造函数传入的值本身，不受构造时传入的 hasStart 的值的影响。

hasEnd 为 false 时，end 值不生效，且不受构造时传入的 isClosed 的值的影响，该数组切片取到原数组最后一个元素。

参数：

range: Range<Int64> - 传递切片的范围。

异常：

IllegalArgumentException - 当 range.step 不等于 1 时，抛出异常。
IndexOutOfBoundsException - 当 range 无效时，抛出异常。

示例：

使用示例见 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 - 索引位置的元素的值。

异常：

IndexOutOfBoundsException - 当 index 超出范围时，抛出异常。

operator func [](Int64, T)

public operator func [](index: Int64, value!: T): Unit

功能：操作符重载 - set，通过下标运算符用指定的元素替换此列表中指定位置的元素。

参数：

index: Int64 - 要设置的索引值。
value!: T - 要设置的 T 类型的值。

异常：

IndexOutOfBoundsException - 当 index 超出范围时，抛出异常。

operator func [](Range<Int64>)

public operator func [](range: Range<Int64>): ArrayList<T>

功能：运算符重载 - 切片。

注意：

如果参数 range 是使用 Range 构造函数构造的 Range 实例，有如下行为：

start 的值就是构造函数传入的值本身，不受构造时传入的 hasStart 的值的影响。

hasEnd 为 false 时，end 值不生效，且不受构造时传入的 isClosed 的值的影响，数组切片取到原数组最后一个元素。

切片操作返回的 ArrayList 为全新的对象，与原 ArrayList 无引用关系。

参数：

range: Range<Int64> - 传递切片的范围。

异常：

IllegalArgumentException - 当 range.step 不等于 1 时，抛出异常。
IndexOutOfBoundsException - 当 range 无效时，抛出异常。

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 封装。

异常：

ConcurrentModificationException - 当函数检测到不同步的并发修改，抛出异常。

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> 实例。

参数：

map: HashMap<K, V> - 传入 HashMap<K, V>。

func iterator()

public func iterator(): Iterator<(K, V)>

功能：返回迭代器实例本身。

返回值：

Iterator <(K, V) > - 迭代器实例本身。

func next()

public func next(): ?(K, V)

功能：返回迭代器中的下一个元素。

返回值：

?(K, V) - 迭代器中的下一个元素，用 Option 封装。

异常：

ConcurrentModificationException - 当函数检测到不同步的并发修改，抛出异常。

func remove()

public func remove(): Option<(K, V)>

功能：删除此 HashMap 迭代器的 next 函数返回的元素，此函数只能在 next 函数调用时调用一次。

返回值：

Option <(K, V) > - 返回被删除的元素。

异常：

ConcurrentModificationException - 当函数检测到不同步的并发修改，抛出异常。

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 中存在重复的键时，按照迭代器顺序，出现在后面的键值对将会覆盖前面的键值对。

参数：

elements: Collection<(K, V)> - 初始化该 HashMap 的键值对集合。

init(Int64)

public init(capacity: Int64)

功能：构造一个带有传入容量大小的 HashMap。

参数：

capacity: Int64 - 初始化容量大小。

异常：

IllegalArgumentException - 如果 capacity 小于 0 则抛出异常。

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 的函数规则。

异常：

IllegalArgumentException - 如果 size 小于 0 则抛出异常。

func capacity()

public func capacity(): Int64

功能：返回 HashMap 的容量。

返回值：

Int64 - HashMap 的容量。

func clear()

public func clear(): Unit

功能：清除所有键值对。

示例：

使用示例见 HashMap 的 putAll/remove/clear 函数。

func clone()

public func clone(): HashMap<K, V>

功能：克隆 HashMap。

返回值：

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 - 要添加的键值对的键。

返回值：

EntryView < K, V > - 一个引用视图。

func get(K)

public func get(key: K): Option<V>

功能：返回指定键映射到的值，如果 HashMap 不包含指定键的映射，则返回 Option<V>.None。

参数：

key: K - 传入的键。

返回值：

Option<V> - 键对应的值。用 Option 封装。

示例：

使用示例见 Hashmap 的 get/put/contains 函数。

func isEmpty()

public func isEmpty(): Bool

功能：判断 HashMap 是否为空，如果是，则返回 true；否则，返回 false。

返回值：

Bool - HashMap 是否为空。

func iterator()

public func iterator(): HashMapIterator<K, V>

功能：返回 Hashmap 的迭代器。

返回值：

HashMapIterator < K, V > - 返回 HashMap 的迭代器。

func keys()

public func keys(): EquatableCollection<K>

功能：返回 HashMap 中所有的 key，并将所有 key 存储在一个 Keys 容器中。

返回值：

EquatableCollection<K> - 保存所有返回的 key。

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 中已有的键，该键的值将被新值替换。

参数：

elements: Collection<(K, V)> - 需要添加进 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。

返回值：

Option<V> - 被从 HashMap 中移除的键对应的值，用 Option 封装，如果 HashMap中不存该键，返回 None 。

示例：

使用示例见 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 - 将要扩容的大小。

func toArray()

public func toArray(): Array<(K, V)>

功能：构造一个包含 HashMap 内键值对的数组，并返回。

返回值：

Array <(K, V) > - 包含容器内所有键值对的数组。

func values()

public func values(): Collection<V>

功能：返回 HashMap 中包含的值，并将所有的 value 存储在一个 Values 容器中。

返回值：

Collection<V> - 保存所有返回的 value。

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 - 与键对应的值。

异常：

NoneValueException - 如果该 HashMap 不存在该键，抛此异常。

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 - 初始化函数规则。

异常：

IllegalArgumentException - 如果 size 小于 0，抛出异常。

init()

public init()

功能：构造一个空的 HashSet ，初始容量为 16 。

init(Array<T>)

public init(elements: Array<T>)

功能：使用传入的数组构造 HashSet。该构造函数根据传入数组 elements 的 size 设置 HashSet 的容量。

参数：

elements: Array<T> - 初始化 HashSet 的数组。

init(Collection<T>)

public init(elements: Collection<T>)

功能：使用传入的集合构造 HashSet。该构造函数根据传入集合 elements 的 size 设置 HashSet 的容量。

参数：

elements: Collection<T> - 初始化 HashSet 的集合。

init(Int64)

public init(capacity: Int64)

功能：使用传入的容量构造一个 HashSet。

参数：

capacity: Int64 - 初始化容量大小。

异常：

IllegalArgumentException - 如果 capacity 小于 0，抛出异常。

func capacity()

public func capacity(): Int64

功能：返回此 HashSet 的内部数组容量大小。

注意:

容量大小不一定等于 HashSet 的 size。

返回值：

Int64 - 返回此 HashSet 的内部数组容量大小。

func clear()

public func clear(): Unit

功能：从此 HashSet 中移除所有元素。

func clone()

public func clone(): HashSet<T>

功能：克隆 HashSet。

返回值：

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 的迭代器。

返回值：

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 中的所有元素。

参数：

elements: Collection<T> - 需要从此 HashSet 中移除的元素的集合。

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 - 将要扩容的大小。

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 类型数组。

class LinkedListNode<T>

public class LinkedListNode<T>

功能：LinkedListNode 是 LinkedList 上的节点。

可以通过 LinkedListNode 对 LinkedList 进行前向后向遍历操作，也可以访问和修改元素的值。

LinkedListNode 只能通过对应 LinkedList 的 'nodeAt'、'firstNode'、'lastNode' 获得，当 LinkedList 删除掉对应的节点时，会造成一个悬空的节点，对悬空的节点进行任何操作都会抛 'IllegalStateException' 异常。

prop next

public prop next: Option<LinkedListNode<T>>

功能：获取当前节点的下一个节点，如果没有则返回 None。

类型：Option<LinkedListNode<T>>

异常：

IllegalStateException - 如果该节点不属于任何链表实例，抛此异常。

prop prev

public prop prev: Option<LinkedListNode<T>>

功能：获取当前节点的前一个节点，如果没有则返回 None。

类型：Option<LinkedListNode<T>>

异常：

IllegalStateException - 如果该节点不属于任何链表实例，抛此异常。

prop value

public mut prop value: T

功能：获取或者修改元素的值。

类型：T

异常：

IllegalStateException - 如果该节点不属于任何链表实例，抛此异常。

func backward()

public func backward(): Iterator<T>

功能：获取一个从当前节点开始，到所对应链表的尾部节点的所有元素的迭代器。

返回值：

Iterator<T> - 对应元素的迭代器。

异常：

IllegalStateException - 如果该节点不属于任何链表实例，抛此异常。

func forward()

public func forward(): Iterator<T>

功能：获取一个从当前节点开始，到所对应链表的头部节点的所有元素的迭代器。

返回值：

Iterator<T> - 对应元素的迭代器。

异常：

IllegalStateException - 如果该节点不属于任何链表实例，抛此异常。

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 - 要添加到链表中的元素。

返回值：

LinkedListNode<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 - 要添加到链表中的元素。

返回值：

LinkedListNode<T> - 指向被插入元素的节点。

异常：

IllegalArgumentException - 如果指定的节点不属于该链表，则抛此异常。

func insertBefore(LinkedListNode<T>,T)

public func insertBefore(node: LinkedListNode<T>, element: T): LinkedListNode<T>

功能：在链表中指定节点的前面插入一个元素，并且返回该元素的节点。

参数：

node: LinkedListNode<T> - 指定的节点。
element: T - 要添加到链表中的元素。

返回值：

LinkedListNode<T> - 指向被插入元素的节点。

异常：

IllegalArgumentException - 如果指定的节点不属于该链表，则抛此异常。

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 个元素的节点。

返回值：

Option < LinkedListNode<T>> - 编号为 index 的节点，如果没有则返回 None。

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 - 要添加到链表中的元素。

返回值：

LinkedListNode<T> - 指向该元素的节点。

func remove(LinkedListNode<T>)

public func remove(node: LinkedListNode<T>): T

功能：删除链表中指定节点。

参数：

node: LinkedListNode<T> - 要被删除的节点。

返回值：

T - 被删除的节点的值。

异常：

IllegalArgumentException - 如果指定的节点不属于该链表，则抛此异常。

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 不在当前的链表内，而是作为首个节点存在于新的链表内部。

参数：

node: LinkedListNode<T> - 要分割的位置。

返回值：

LinkedList<T> - 原链表分割后新产生的链表。

异常：

IllegalArgumentException - 如果指定的节点不属于该链表，则抛此异常。

func toArray()

public func toArray(): Array<T>

功能：返回一个数组，数组包含该链表中的所有元素，并且顺序与链表的顺序相同。

返回值：

Array<T> - T 类型数组。

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 中有相同的键时，后出现(迭代器顺序)的键值对将会覆盖先出现的键值对。

参数：

elements: Collection<(K, V)> - 初始化该 TreeMap 的键值对集合。

init(Int64, (Int64) -> (K, V))

public init(size: Int64, initElement: (Int64) -> (K, V))

功能：通过传入的元素个数 size 和函数规则来构造 TreeMap。

参数：

size: Int64 - 传入的元素个数。
initElement: (Int64) ->(K, V) - 初始化该 TreeMap 的函数规则。

异常：

IllegalArgumentException - 如果 size 小于 0 则抛出异常。

func clear()

public func clear(): Unit

功能：清除所有键值对。

func clone()

public func clone(): TreeMap<K, V>

功能：克隆 TreeMap。

返回值：

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

功能：判断是否包含指定集合键的映射。

参数：

keys: Collection<K> - 键的集合 keys。

返回值：

Bool - 如果存在，则返回 true；否则，返回 false。

func findLower(K, Bool)

public func findLower(bound: K, inclusive!: Bool = false): Option<TreeMapNode<K, V>>

功能：返回比传入的键小的最大元素。

参数：

bound: K - 传入的键。
inclusive!: Bool - 是否包含传入的键本身，默认为 false ，即不包含。

返回值：

Option < TreeMapNode < K, V >> - 如果存在这样一个元素，用 Option<TreeMapNode<K, V>> 封装该元素并返回；否则，返回 Option<TreeMapNode<K, V>>.None。

func findUpper(K, Bool)

public func findUpper(bound: K, inclusive!: Bool = false): Option<TreeMapNode<K, V>>

功能：返回比传入的键大的最小元素。

参数：

bound: K - 传入的键。
inclusive!: Bool - 是否包含传入的键本身，默认为 false ，即不包含。

返回值：

Option < TreeMapNode < K, V >> - 如果存在这样一个元素，用 Option<TreeMapNode<K, V>> 封装该元素并返回；否则，返回 Option<TreeMapNode<K, V>>.None。

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 值从小到大的顺序迭代。

返回值：

Iterator <(K, V) > - TreeMap 的迭代器。

func keys()

public func keys(): EquatableCollection<K>

功能：返回 TreeMap 中所有的 key，并将所有 key 存储在一个容器中。

返回值：

EquatableCollection<K> - 包含所有键的集合。

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 中已有的键，该键的值将被新值替换。

参数：

elements: Collection<(K, V)> - 需要添加进 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 存储在一个容器中。

返回值：

Collection<V> - 包含所有值的集合。

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 - 与键对应的值。

异常：

NoneValueException - 如果该 HashMap 不存在该键，抛出异常。

结构体

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。

该结构体的实例只能通过对应 HashMap 的 func entryView(K) 方法获得。

func getKey()

public func getKey(): K

功能：获取视图中的键，时间复杂度为 O(1)。

返回值：

K - 视图的键。

异常：

ConcurrentModificationException - 当此视图在使用的过程中，对应的 HashMap 被其它操作修改时，抛此异常。

func getValue()

public func getValue(): ?V

功能：获取视图中的值，时间复杂度为 O(1)。

如果视图为空，返回 None；否则，返回键对应的值。

返回值：

?V - 视图的值。

异常：

ConcurrentModificationException - 当此视图在使用的过程中，对应的 HashMap 被其它操作修改时，抛此异常。

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 - 视图的值或者新插入的值。

异常：

ConcurrentModificationException - 当此视图在使用的过程中，对应的 HashMap 被其它操作修改时，抛此异常。

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

异常：

ConcurrentModificationException - 当此 TreeMapNode 失效时，抛出异常。

prop value

public mut prop value: V

功能：获取或设置当前节点的值。

类型：V

异常：

ConcurrentModificationException - 当此 TreeMapNode 失效时，抛出异常。

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 结束的一个正序的迭代器。

异常：

ConcurrentModificationException - 当此 TreeMapNode 失效时，抛出异常。

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 结束的一个逆序的迭代器。

异常：

ConcurrentModificationException - 当此 TreeMapNode 失效时，抛出异常

func next()

public func next(): Option<TreeMapNode<K, V>>

功能：访问后继节点。

返回值：

Option < TreeMapNode < K, V >> - 如果存在后继节点，用 Option<TreeMapNode<K, V>> 封装并返回；否则，返回 Option<TreeMapNode<K, V>>.None。

异常：

ConcurrentModificationException - 当此 TreeMapNode 失效时，抛出异常。

func prev()

public func prev(): Option<TreeMapNode<K, V>>

功能：访问前继节点。

返回值：

Option < TreeMapNode < K, V >> - 如果存在前继节点，用 Option<TreeMapNode<K, V>> 封装并返回；否则，返回 Option<TreeMapNode<K, V>>.None。

异常：

ConcurrentModificationException - 当此 TreeMapNode 失效时，抛出异常。

异常

class ConcurrentModificationException

public class ConcurrentModificationException <: Exception {
    public init()
    public init(message: String)
}

功能：并发修改异常类。当函数检测到不同步的并发修改，抛出异常。

由于 collection 包提供的容器类都不支持并发修改，因此在执行某些操作时，会抛出 ConcurrentModificationException。

典型的抛异常场景有：

使用 for-in 遍历一个容器过程中对容器进行修改时(HashMapIterator的remove() 方法除外)。
在使用声明周期较短的类型，如 EntryView、TreeMapNode 时，如果其所在的容器内容被修改，也会抛出异常。

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 - 初始化容量大小。

异常：

IllegalArgumentException - 如果 capacity 小于等于 0 则抛出异常。

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 为负，则会立即执行出队操作并且返回操作结果。

参数：

timeout: Duration - 等待时间。

返回值：

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 - 初始化容量大小。

异常：

IllegalArgumentException - 如果 capacity 小于等于 0 则抛出异常。

init(Int64, Array<E>)

public init(capacity: Int64, elements: Array<E>)

功能：构造一个带有传入容量大小，并带有传入数组元素的 BlockingQueue。

参数：

capacity: Int64 - 初始化容量大小。
elements: Array<E> - 初始化数组元素。

异常：

IllegalArgumentException - 如果 capacity 小于等于 0 或小于数组元素elements 的 size 则抛出异常。

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 为负，则会立即执行出队操作并且返回操作结果。

参数：

timeout: Duration - 等待时间。

返回值：

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>)
}

功能：此类主要实现 Concurrent HashMap 的迭代器功能。

注意：

这里定义的 Concurrent HashMap 迭代器：

不保证迭代结果为并发 HashMap 某一时刻的 “快照”，建议在环境中没有其它线程并发地修改 Concurrent HashMap 时调用；

迭代器在迭代过程中，不保证可以感知环境线程对目标 Concurrent HashMap 的修改。

init(ConcurrentHashMap<K, V>)

public init(cmap: ConcurrentHashMap<K, V>)

功能：创建 ConcurrentHashMapIterator<K, V> 实例。

参数：

cmap: ConcurrentHashMap<K, V> - 待获取其迭代器的 ConcurrentHashMap<K, V> 实例。

func iterator()

public func iterator(): Iterator<(K, V)>

功能：获取 ConcurrentHashMap<K, V> 迭代器自身。

返回值：

Iterator <(K, V) > - 迭代器自身。

func next()

public func next(): Option<(K, V)>

功能：返回迭代中的下一个元素。

返回值：

Option <(K, V) > - 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 - 用户指定并发度。

异常：

IllegalArgumentException - 如果 size 小于 0 则抛出异常。

init(Int64, Int64)

public init(capacity: Int64, concurrencyLevel!: Int64 = 16)

功能：构造一个带有传入容量大小和指定并发度（默认等于 16）的 ConcurrentHashMap。

参数：

capacity: Int64 - 初始化容量大小。
concurrencyLevel!: Int64 - 用户指定的并发度。

异常：

IllegalArgumentException - 如果 capacity 小于 0 则抛出异常。

func contains(K)

public func contains(key: K): Bool

功能：判断此映射中是否包含指定键 key 的映射。

参数：

key: K - 传递要判断的 key。

返回值：

Bool - 是否包含指定键 key 的映射。

func get(K)

public func get(key: K): ?V

功能：返回此映射中键 key 所关联的值。

参数：

key: K - 传递 key，获取 value。

返回值:

Option<V> - 此映射中键 key 所关联的值。

func isEmpty()

public func isEmpty(): Bool

功能：判断 ConcurrentHashMap 是否为空；如果是，则返回 true；否则，返回 false。

注意：

此方法不保证并发场景下的原子性，建议在环境中没有其它线程并发地修改 ConcurrentHashMap 时调用。

返回值：

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

func iterator()

public func iterator(): ConcurrentHashMapIterator<K, V>

功能：获取 ConcurrentHashMap 的迭代器。

返回值：

ConcurrentHashMapIterator < K, V > - Concurrent HashMap 的迭代器

func put(K, V)

public func put(key: K, value: V): ?V

参数：

key: K - 要放置的键。
value: V - 要关联的值。

返回值：

Option<V> - 如果赋值之前 key 存在，则返回旧的值 Some(v)；当赋值前 key 不存在时，返回 None。

func putIfAbsent(K, V)

public func putIfAbsent(key: K, value: V): ?V

功能：当此 Map 中不存在键 key 时，在 Map 中添加指定的值 value 与指定的键 key 的关联。如果 Map 已经包含键 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

功能：如果 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)

public func replace(key: K, eval: (V) -> V): ?V

参数：

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

功能：如果 Map 中存在 key，则将 Map 中键 key 关联的值替换为 value；如果 Map 中不存在 key，则不对 Map 做任何修改。

参数：

key: K - 传入要替换所关联值的键。
value: V - 传入要替换成的新值。

返回值：

Option<V> - 如果 key 存在，则返回 key 对应的旧值 Some(v)；当 key 不存在时，返回 None。

operator func [](K)

public operator func [](key: K): V

功能：运算符重载集合，如果键存在，返回键对应的值；如果不存在，抛出异常。

参数：

key: K - 传递值进行判断。

返回值：

V - 与键对应的值。

异常：

NoneValueException - 关联中不存在键 key。

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 实例。

参数：

elements: 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, item: 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, item: 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。

异常：

IllegalArgumentException：当输入不符合UTF-8编码的字符串时，抛此异常。

func read(Array<Byte>)

public func read(arr: Array<Byte>): Int64

功能：从标准输入中读取并放入 arr 中。

注意：

该函数存在风险，可能读取出来的结果恰好把 UTF-8 code point 从中截断，如果发生截断，将导致该 Array<Byte> 转换成字符串的结果不正确或抛出异常。

参数：

arr: Array<Byte> - 目标 Array。

返回值：

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。

返回值：

?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 位浮点数值的文本表示写入标准输出或标准错误流中。

参数：

v: Float16 - 要写入的值。

func write(Float32)

public func write(v: Float32): Unit

功能：将指定的 32 位浮点数值的文本表示写入标准输出或标准错误流中。

参数：

v: Float32 - 要写入的值。

func write(Float64)

public func write(v: Float64): Unit

功能：将指定的 64 位浮点数值的文本表示写入标准输出或标准错误流中。

参数：

v: Float64 - 要写入的值。

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): Unit 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 （后跟换行符）写入标准输出或标准错误流中。

参数：

buffer: Array<Byte> - 要写入的值。

func writeln(Bool)

public func writeln(v: Bool): Unit

功能：将指定的布尔值的文本表示形式（后跟换行符）写入标准输出或标准错误流中。

参数：

v: Bool - 要写入的值。

func writeln(Float16)

public func writeln(v: Float16): Unit

功能：将指定的 16 位浮点数值的文本表示（后跟换行符）写入标准输出或标准错误流中。

参数：

v: Float16 - 要写入的值。

func writeln(Float32)

public func writeln(v: Float32): Unit

功能：将指定的 32 位浮点数值的文本表示（后跟换行符）写入标准输出或标准错误流中。

参数：

v: Float32 - 要写入的值。

func writeln(Float64)

public func writeln(v: Float64): Unit

功能：将指定的 64 位浮点数值的文本表示（后跟换行符）写入标准输出或标准错误流中。

参数：

v: Float64 - 要写入的值。

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): Unit 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。本包内已经为 Bool，Rune，Float16，Int64 等基础类型实现该接口，可用于将字符串转换为这些类型。

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 - 要转换的字符串。

返回值：

Bool - 返回转换后 Bool 值。

异常：

IllegalArgumentException - 当字符串为空或转换失败时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Bool>

功能：将 Bool 类型字面量的字符串转换为 Option<Bool> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<Bool> - 返回转换后 Option<Bool> 值，转换失败返回 Option<Bool>.None。

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 - 要转换的字符串。

返回值：

Float16 - 返回转换后 Float16 值。

异常：

IllegalArgumentException - 当字符串不符合浮点数语法时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Float16>

功能：将 Float16 类型字面量的字符串转换为 Option<Float16> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<Float16> - 返回转换后 Option<Float16> 值，转换失败返回 Option<Float16>.None。

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 - 要转换的字符串。

返回值：

Float32 - 返回转换后 Float32 值。

异常：

IllegalArgumentException - 当字符串不符合浮点数语法时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Float32>

功能：将 Float32 类型字面量的字符串转换为 Option<Float32> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<Float32> - 返回转换后 Option<Float32> 值，转换失败返回 Option<Float32>.None。

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 - 要转换的字符串。

返回值：

Float64 - 返回转换后 Float64 值。

异常：

IllegalArgumentException - 当字符串不符合浮点数语法时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Float64>

功能：将 Float64 类型字面量的字符串转换为 Option<Float64> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<Float64> - 返回转换后 Option<Float64> 值，转换失败返回 Option<Float64>.None。

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 - 要转换的字符串。

返回值：

Int16 - 返回转换后 Int16 值。

异常：

IllegalArgumentException - 当字符串为空，首位为 + ，转换失败，或转换后超出 Int16 范围，或字符串中含有无效的 UTF-8 字符时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Int16>

功能：将 Int16 类型字面量的字符串转换为 Option<Int16> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<Int16> - 返回转换后 Option<Int16> 值，转换失败返回 Option<Int16>.None。

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 - 要转换的字符串。

返回值：

Int32 - 返回转换后 Int32 值。

异常：

IllegalArgumentException - 当字符串为空，首位为 + ，转换失败，或转换后超出 Int32 范围，或字符串中含有无效的 UTF-8 字符时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Int32>

功能：将 Int32 类型字面量的字符串转换为 Option<Int32> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<Int32> - 返回转换后 Option<Int32> 值，转换失败返回 Option<Int32>.None。

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 - 要转换的字符串。

返回值：

Int64 - 返回转换后 Int64 值。

异常：

IllegalArgumentException - 当字符串为空，首位为 + ，转换失败，或转换后超出 Int64 范围，或字符串中含有无效的 UTF-8 字符时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Int64>

功能：将 Int64 类型字面量的字符串转换为 Option<Int64> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<Int64> - 返回转换后 Option<Int64> 值，转换失败返回 Option<Int64>.None。

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 - 要转换的字符串。

返回值：

Int8 - 返回转换后 Int8 值。

异常：

IllegalArgumentException - 当字符串为空，首位为 + ，转换失败，或转换后超出 Int8 范围，或字符串中含有无效的 UTF-8 字符时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Int8>

功能：将 Int8 类型字面量的字符串转换为 Option<Int8> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<Int8> - 返回转换后 Option<Int8> 值，转换失败返回 Option<Int8>.None。

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 - 要转换的字符串。

返回值：

Rune - 返回转换后 Rune 值。

异常：

IllegalArgumentException - 当字符串为空，或转换失败时，或字符串中含有无效的 UTF-8 字符时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<Rune>

功能：将 Rune 类型字面量的字符串转换为 Option<Rune> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<Rune> - 返回转换后 Option<Rune> 值，转换失败返回 Option<Rune>.None。

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 - 要转换的字符串。

返回值：

UInt16 - 返回转换后 UInt16 值。

异常：

IllegalArgumentException - 当字符串为空，首位为 + 或 -，转换失败，或转换后超出 UInt16 范围，或字符串中含有无效的 UTF-8 字符时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<UInt16>

功能：将 UInt16 类型字面量的字符串转换为 Option<UInt16> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<UInt16> - 返回转换后 Option<UInt16> 值，转换失败返回 Option<UInt16>.None。

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 - 要转换的字符串。

返回值：

UInt32 - 返回转换后 UInt32 值。

异常：

IllegalArgumentException - 当字符串为空，首位为 + 或 -，转换失败，或转换后超出 UInt32 范围，或字符串中含有无效的 UTF-8 字符时，抛出异常常。

static func tryParse(String)

public static func tryParse(data: String): Option<UInt32>

功能：将 UInt32 类型字面量的字符串转换为 Option<UInt32> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<UInt32> - 返回转换后 Option<UInt32> 值，转换失败返回 Option<UInt32>.None。

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 - 要转换的字符串。

返回值：

UInt64 - 返回转换后 UInt64 值。

异常：

IllegalArgumentException - 当字符串为空，首位为 + 或 -，转换失败，或转换后超出 UInt64 范围，或字符串中含有无效的 UTF-8 字符时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<UInt64>

功能：将 UInt64 类型字面量的字符串转换为 Option<UInt64> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<UInt64> - 返回转换后 Option<UInt64> 值，转换失败返回 Option<UInt64>.None。

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 - 要转换的字符串。

返回值：

UInt8 - 返回转换后 UInt8 值。

异常：

IllegalArgumentException - 当字符串为空，首位为 + 或 -，转换失败，或转换后超出 UInt8 范围，或字符串中含有无效的 UTF-8 字符时，抛出异常。

static func tryParse(String)

public static func tryParse(data: String): Option<UInt8>

功能：将 UInt8 类型字面量的字符串转换为 Option<UInt8> 值。

参数：

data: String - 要转换的字符串。

返回值：

Option<UInt8> - 返回转换后 Option<UInt8> 值，转换失败返回 Option<UInt8>.None。

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.digest 包

功能介绍

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> - 待进行摘要运算的数据。

返回值：

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 - 待进行摘要运算的数据。

返回值：

Array<Byte> - 摘要运算结果。

接口

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 值。

返回值：

Array<Byte> - 返回生成摘要值。

func reset()

mut func reset(): Unit

功能：重置 digest 对象到初始状态。

func write(Array<Byte>)

mut func write(buffer: Array<Byte>): Unit

功能：使用给定的 buffer 更新 digest 对象。

std.cipher 包概述

功能介绍

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> - 待进行加密的数据。

返回值：

Array<Byte> - 加密后的结果。

func decrypt(Array<Byte>)

func decrypt(input: Array<Byte>): Array<Byte>

功能：提供解密函数。

参数：

input: Array<Byte> - 待进行解密的数据。

返回值：

Array<Byte> - 解密后的结果。

std.database.sql 包

功能介绍

database.sql 包提供仓颉访问数据库的接口。

本包提供 SQL/CLI 的通用接口，配合数据库驱动 Driver 完成对数据库的各项操作。

注意：

当前仅支持 SQL/CLI 接口。

SQL 数据类型和仓颉数据类型对应表如下：

SQL	CDBC/Cangjie	SqlDataType	说明
`RUNE`	`String`	`SqlChar`	-
`VARCHAR`	`String`	`SqlVarchar`	-
`CLOB`	`io.InputStream`	`SqlClob`	-
`BINARY`	`Array<Byte>`	`SqlBinary`	-
`VARBINARY`	`Array<Byte>`	`SqlVarBinary`	-
`BLOB`	`io.InputStream`	`SqlBlob`	-
`NUMERIC`	`Decimal`	`sqlDecimal`	-
`DECIMAL`	`Decimal`	`sqlDecimal`	-
`BOOLEAN`	`Bool`	`SqlBool`	-
`TINYINT`	`Int8`	`SqlByte`	-
`SMALLINT`	`Int16`	`SqlSmallInt`	-
`INTEGER`	`Int32`	`SqlInteger`	-
`BIGINT`	`Int64`	`SqlBigInt`	-
`REAL`	`Float32`	`SqlReal`	-
`DOUBLE`	`Float64`	`SqlDouble`	-
`DATE`	`time.DateTime`	`SqlDate`	值支持 `YEAR`，`MONTH`，`DAY`。
`TIME`	`time.DateTime`	`SqlTime`	值支持 `HOUR`，`MINUTE`，`SECOND`（不包括 `TIME ZONE`）。
`TIMETZ`	`time.DateTime`	`SqlTimeTz`	值支持 `HOUR`，`MINUTE`，`SECOND`（包括 `TIME ZONE`）。
`TIMESTAMP`	`time.DateTime`	`SqlTimestamp`	值支持 `YEAR`，`MONTH`，`DAY`，`HOUR`，`MINUTE`，`SECOND`，`TIME ZONE`。
`INTERVAL`	`time.Duration`	`SqlInterval`	年-月间隔或者日-时间隔。

API列表

接口

接口名	功能
ColumnInfo	执行 Select/Query 语句返回结果的列信息。
Connection	数据库连接接口。
Datasource	数据源接口。
Driver	数据库驱动接口。
QueryResult	执行 Select 语句产生的结果接口。
SqlDbType	所有 sql 数据类型的父类。
SqlNullableDbType	允许 `null` 值的 sql 数据类型父类。
Statement	sql 语句预执行接口。
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

功能：创建事务对象。

返回值：

Transaction - 事务对象。

异常：

SqlException - 当已经处于事务状态，不支持并行事务时，抛出异常。

func getMetaData()

func getMetaData(): Map<String, String>

功能：返回连接到的数据源元数据。

返回值：

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

功能：返回一个可用的连接。

返回值：

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 数组，打开数据源的选项。

返回值：

Datasource - 数据源实例。

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 的内容。

参数：

values: Array<SqlDbType> - sql 数据类型的数据列表。

返回值：

Bool - 下一行存在数据则返回 true，否则返回 false。

interface SqlDbType

public interface SqlDbType {
    prop name: String
}

功能：所有 sql 数据类型的父类。

要扩展用户定义的类型，请继承 SqlDbType 或 SqlNullableDbType。

说明：

SqlDbType 接口所有实现类型都必须具有公共 value 属性。每种 sql 数据类型实现类，同时满足以下条件：

只有一个参数的构造函数，参数类型为 T（T 为仓颉语言支持的类型）。

public 修饰的 value 属性，其类型必须上一条中使用的参数类型一致，其值为对应仓颉类型的值。

如果数据类型允许 null 值，继承 SqlNullableDbType，null 值时，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 语句中的 ? 占位符。

返回值：

QueryResult - 查询结果。

异常：

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 语句中的 ? 占位符。

返回值：

UpdateResult - 更新结果。

异常：

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>

功能：返回已注册数据库驱动名称的列表(名称已按照字典序排序)。本方法并发安全。

返回值：

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

异常：

ArithmeticException - 当该属性被设置为 Duration.Max 或 Duration.Min 时，抛此异常。
SqlException - 当超时后，抛出此异常。

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 对象。

参数：

datasource: Datasource - 数据源。

func close()

public func close(): Unit

功能：关闭连接池中的所有连接并阻止其它连接请求。调用该方法会阻塞至所有连接关闭并归还到连接池。

func connect()

public func connect(): Connection

功能：获取一个连接。

func isClosed()

public func isClosed(): 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 实例。

参数：

v: Array<Byte> - 传入的数据。

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 实例。

参数：

v: InputStream - 传入的数据。

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 实例。

参数：

v: InputStream - 传入的数据。

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 实例。

参数：

v: DateTime - 传入的数据。

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 实例。

参数：

v: Decimal - 传入的数据。

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 实例。

参数：

v: Float64 - 传入的数据。

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 实例。

参数：

v: Duration - 传入的数据。

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 实例。

参数：

v: ?Array<Byte> - 传入的数据。

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 实例。

参数：

v: ?InputStream - 传入的数据。

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 实例。

参数：

v: ?InputStream - 传入的数据。

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 实例。

参数：

v: ?DateTime - 传入的数据。

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 实例。

参数：

v: ?Decimal - 传入的数据。

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 实例。

参数：

v: ?Float64 - 传入的数据。

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 实例。

参数：

v: ?Duration - 传入的数据。

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 实例。

参数：

v: ?Float32 - 传入的数据。

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 实例。

参数：

v: ?DateTime - 传入的数据。

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 实例。

参数：

v: ?DateTime - 传入的数据。

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 实例。

参数：

v: ?DateTime - 传入的数据。

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 实例。

参数：

v: ?Array<Byte> - 传入的数据。

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 实例。

参数：

v: Float32 - 传入的数据。

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 实例。

参数：

v: DateTime - 传入的数据。

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 实例。

参数：

v: DateTime - 传入的数据。

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 实例。

参数：

v: DateTime - 传入的数据。

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 实例。

参数：

v: Array<Byte> - 传入的数据。

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

功能：判断数据源连接状态是否不同。

参数：

rhs: ConnectionState - 数据源连接状态。

返回值：

Bool - 传入数据源连接状态与当前状态相同则返回 false ，否则返回 true。

operator func ==(ConnectionState)

public operator func ==(rhs: ConnectionState): Bool

功能：判断数据源连接状态是否相同。

参数：

rhs: ConnectionState - 数据源连接状态。

返回值：

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 是否不相等。

参数：

rhs: TransactionAccessMode - 传入 TransactionAccessMode 的枚举值。

返回值：

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

operator func ==(TransactionAccessMode)

public operator func == (rhs: TransactionAccessMode): Bool

功能：判断两个 TransactionAccessMode 是否相等。

参数：

rhs: TransactionAccessMode - 传入 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 是否不相等。

参数：

rhs: TransactionDeferrableMode - 传入 TransactionDeferrableMode 的枚举值。

返回值：

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

operator func ==(TransactionDeferrableMode)

public operator func == (rhs: TransactionDeferrableMode): Bool

功能：判断两个 TransactionDeferrableMode 是否相等。

参数：

rhs: TransactionDeferrableMode - 传入 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 是否不相等。

参数：

rhs: TransactionIsoLevel - 传入的 TransactionIsoLevel。

返回值：

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

operator func ==(TransactionIsoLevel)

public operator func == (rhs: TransactionIsoLevel): Bool

功能：判断两个 TransactionIsoLevel 是否相等。

参数：

rhs: TransactionIsoLevel - 传入的 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>([10])), SqlTime(DateTime.now()))

            psInsert.update(SqlChar("kungfu"), SqlBinary(Array<Byte>([20])), SqlTime(DateTime.now()))

            // error, test rollback SQLException: No value specified for parameter 3.
            psInsert.update(SqlVarchar("mkyong"), SqlBinary(Array<Byte>([1, 2, 3, 4, 5])))

            // 提交事务
            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>([10])), SqlTime(DateTime.now())])

            // 创建保存点 2
            tx.save("save2")
            psInsert.update([SqlChar("kungfu"), SqlBinary(Array<Byte>([20])), SqlTime(DateTime.now())])

            // 创建保存点 3
            tx.save("save3")
            psInsert.update([SqlVarchar("mkyong"), SqlBinary(Array<Byte>([1, 2, 3, 4, 5]))])

            // 回滚到保存点 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.ffi.python 包

功能介绍

ffi.python 包提供仓颉与 Python 语言互操作调用的能力，以兼容强大的计算和 AI 生态。

本包为用户提供了以下能力：

Python 包为用户提供了全局解释器对象 Python ，其类型为 PythonBuiltins ，通过该解释器对象可以：
- 加载、卸载解释器资源；
- 获取当前使用的 Python 解释器版本；
- 导入及使用 Python 的三方模块。
详细介绍及使用请参见《仓颉语言用户指南》（跨语言互操作/与 Python 语言互操作/PythonBuiltins 内建函数类）。
Python 包提供了 Python 数据类型与仓颉类型之间的互相转换。如 PyBool/PyLong/PyFloat/PyString/PyTuple/PyList/PyDict/PySet, 它们均继承自 PyObject 类型，PyObject 类型提供了所有类型的通用接口，如成员变量访问、函数访问、到仓颉类型转换等。PyObject 类型的子类提供了每个类型独有的函数接口。

详细映射关系介绍及使用请参见《仓颉语言用户指南》（跨语言互操作/与 Python 语言互操作/类型映射）。
Python 包支持简单的函数注册及 Python 对仓颉函数调用。Python 回调仓颉代码需要通过 C 作为中间层进行调用，并且使用到了 Python 的三方库： ctypes 以及 _ctypes 。

详细映射关系介绍及使用请参见《仓颉语言用户指南》（跨语言互操作/与 Python 语言互操作/仓颉与 Python 的注册回调），该章节详细介绍了在回调过程中，两边参数和返回值的类型映射情况以及调用方式。

注意：

本包暂不支持 Windows 平台。

API 列表

常量&变量

变量/常量名	功能
PYLOG	`ffi.python` 日志对象，用于打印控制及输出。
Python	Python 解释器全局资源。

接口

接口名	功能
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 语言互操作/类型映射/PyBool 与 Bool 的映射）

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 语言互操作/类型映射/PyDict 与 HashMap 的映射）。

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 语言互操作/类型映射PyList 与 Array 的映射）。

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 语言互操作/类型映射PySet 与 HashSet 的映射）。

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，宽度前有负号则表示左对齐，没有负号则是右对齐，如果数值小于数值本身的长度，不会发生截断。如果前缀有 + 或 - 符号会占用一个字符位，如果前缀有 0x 或 0o 等会占用两个字符位。

代码如下:
```
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 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

extend Float32 <: Formatter

extend Float32 <: Formatter

功能：为 Float32 扩展 Formatter 接口，以实现将 Float32 实例转换为格式化字符串。

func format(String)

public func format(fmt: String): String

功能：根据格式化参数将当前 Float32 类型实例格式化为对应格式的字符串。

参数：

fmt: String - 格式化参数。

返回值：

String - 将当前 Float32 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

extend Float64 <: Formatter

extend Float64 <: Formatter

功能：为 Float64 扩展 Formatter 接口，以实现将 Float64 实例转换为格式化字符串。

func format(String)

public func format(fmt: String): String

功能：根据格式化参数将当前 Float64 类型实例格式化为对应格式的字符串。

参数：

fmt: String - 格式化参数。

返回值：

String - 将当前 Float64 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

extend Int16 <: Formatter

extend Int16 <: Formatter

功能：为 Int16 扩展 Formatter 接口，以实现将 Int16 实例转换为格式化字符串。

func format(String)

public func format(fmt: String): String

功能：根据格式化参数将当前 Int16 类型实例格式化为对应格式的字符串。

参数：

fmt: String - 格式化参数。

返回值：

String - 将当前 Int16 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

extend Int32 <: Formatter

extend Int32 <: Formatter

功能：为 Int32 扩展 Formatter 接口，以实现将 Int32 实例转换为格式化字符串。

func format(String)

public func format(fmt: String): String

功能：根据格式化参数将当前 Int32 类型实例格式化为对应格式的字符串。

参数：

fmt: String - 格式化参数。

返回值：

String - 将当前 Int32 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

extend Int64 <: Formatter

extend Int64 <: Formatter

功能：为 Int64 扩展 Formatter 接口，以实现将 Int64 实例转换为格式化字符串。

func format(String)

public func format(fmt: String): String

功能：根据格式化参数将当前 Int64 类型实例格式化为对应格式的字符串。

参数：

fmt: String - 格式化参数。

返回值：

String - 将当前 Int64 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

extend Int8 <: Formatter

extend Int8 <: Formatter

功能：为 Int8 扩展 Formatter 接口，以实现将 Int8 实例转换为格式化字符串。

func format(String)

public func format(fmt: String): String

功能：根据格式化参数将当前 Int8 类型实例格式化为对应格式的字符串。

参数：

fmt: String - 格式化参数。

返回值：

String - 将当前 Int8 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

extend Rune <: Formatter

extend Rune <: Formatter

功能：为 Rune 扩展 Formatter 接口，以实现将 Rune 实例转换为格式化字符串。

func format(String)

public func format(fmt: String): String

功能：根据格式化参数将当前 Rune 类型实例格式化为对应格式的字符串。

参数：

fmt: String - 格式化参数。

返回值：

String - 将当前 Rune 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

extend UInt16 <: Formatter

extend UInt16 <: Formatter

功能：为 UInt16 扩展 Formatter 接口，以实现将 UInt16 实例转换为格式化字符串。

func format(String)

public func format(fmt: String): String

功能：根据格式化参数将当前 UInt16 类型实例格式化为对应格式的字符串。

参数：

fmt: String - 格式化参数。

返回值：

String - 将当前 UInt16 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

extend UInt32 <: Formatter

extend UInt32 <: Formatter

功能：为 UInt32 扩展 Formatter 接口，以实现将 UInt32 实例转换为格式化字符串。

func format(String)

public func format(fmt: String): String

功能：根据格式化参数将当前 UInt32 类型实例格式化为对应格式的字符串。

参数：

fmt: String - 格式化参数。

返回值：

String - 将当前 UInt32 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

extend UInt64 <: Formatter

extend UInt64 <: Formatter

功能：为 UInt64 扩展 Formatter 接口，以实现将 UInt64 实例转换为格式化字符串。

func format(String)

public func format(fmt: String): String

功能：根据格式化参数将当前 UInt64 类型实例格式化为对应格式的字符串。

参数：

fmt: String - 格式化参数。

返回值：

String - 将当前 UInt64 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

extend UInt8 <: Formatter

extend UInt8 <: Formatter

功能：为 UInt8 扩展 Formatter 接口，以实现将 UInt8 实例转换为格式化字符串。

func format(String)

public func format(fmt: String): String

功能：根据格式化参数将当前 UInt8 类型实例格式化为对应格式的字符串。

参数：

fmt: String - 格式化参数。

返回值：

String - 将当前 UInt8 类型实例格式化后得到的字符串。

异常：

IllegalArgumentException - 当 fmt 不合法时抛出异常。

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 列表

类

类名	功能
Directory	对应文件系统中的目录，它提供创建、移动、复制、删除、查询属性以及遍历目录等能力。
File	提供一些对文件进行操作的函数，包括文件的打开、创建、关闭、移动、复制、删除，文件的流式读写操作，查询属性以及一些其他函数。

枚举

枚举名	功能
OpenOption	表示不同的文件打开选项。

结构体

结构体名	功能
FileDescriptor	用于获取文件句柄信息。
FileInfo	对应文件系统中的文件元数据，提供一些文件属性的查询和设置等函数。
Path	提供路径相关的函数。

异常类

异常类名	功能
FSException	文件流异常类，继承了异常类。

类

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 形式的目录路径。

异常：

FSException - 如果路径非法，则抛异常。

init(String)

public init(path: String)

功能：创建 Directory 实例，支持绝对路径和相对路径，路径非法抛异常。

参数：

path: String - 字符串形式的目录路径。

异常：

FSException - 当路径不存在时或路径为空时，抛出异常。

static func copy(Path, Path, Bool)

public static func copy(sourceDirPath: Path, destinationDirPath: Path, overwrite: Bool): Unit

功能：将该目录以及文件、子文件夹都拷贝到新的位置。

参数：

sourceDirPath: Path - Path 形式的源目录路径。
destinationDirPath: Path - Path 形式的目标目录路径。
overwrite: Bool - 是否覆盖, 为 true 时覆盖，为false 时不覆盖。

异常：

FSException - 源目录不存在，或 overwrite 为 false 时目标目录已存在，或目标目录在源目录中，或复制失败，抛出异常。
IllegalArgumentException - 源目录或目标目录名包含空字符则抛出异常。

static func copy(String, String, Bool)

public static func copy(sourceDirPath: String, destinationDirPath: String, overwrite: Bool): Unit

功能：将该目录以及文件、子文件夹都拷贝到新的位置，不成功则抛异常。

参数：

sourceDirPath: String - 字符串形式的源目录路径。
destinationDirPath: String - 字符串形式的目标目录路径。
overwrite: Bool - 是否覆盖, 为 true 时覆盖，为false 时不覆盖。

异常：

FSException - 源目录不存在，或 overwrite 为 false 时目标目录已存在，或目标目录在源目录中，或复制失败，抛出异常。
IllegalArgumentException - 源目录或目标目录名包含空字符则抛出异常。

static func create(Path, Bool)

public static func create(path: Path, recursive!: Bool = false): Directory

功能：创建目录。

可指定是否递归创建，如果需要递归创建，将逐级创建路径中不存在的目录。

参数：

path: Path - 待创建的目录路径。
recursive!: Bool - 是否递归创建目录，true 代表递归创建，false 代表不递归创建，默认 false。

返回值：

Directory - 新创建的 Directory 实例。

异常：

FSException - 目录已存在时，抛出异常；非递归时中间有不存在的目录时抛出异常。
IllegalArgumentException - 目录为空、目录为当前目录、目录为根目录，或目录中存在空字符时抛出异常。

static func create(String, Bool)

public static func create(path: String, recursive!: Bool = false): Directory

功能：创建目录。

可指定是否递归创建，如果需要递归创建，将逐级创建路径中不存在的目录。

参数：

path: String - 待创建的目录路径。
recursive!: Bool - 是否递归创建目录，true 代表递归创建，false 代表不递归创建，默认 false。

返回值：

Directory - 新创建的 Directory 实例。

异常：

FSException - 目录已存在时，抛出异常；非递归时中间有不存在的目录时抛出异常。
IllegalArgumentException - 目录为空、目录为当前目录、目录为根目录，或目录中存在空字符时抛出异常。

static func createTemp(Path)

public static func createTemp(directoryPath: Path): Directory

参数：

directoryPath: Path - Path 形式的目录路径。

返回值：

Directory - 临时目录的 Directory 实例。

异常：

FSException - 目录不存在或创建失败时抛出异常。
IllegalArgumentException - 目录为空或包含空字符时抛出异常。

static func createTemp(String)

public static func createTemp(directoryPath: String): Directory

参数：

directoryPath: String - 字符串形式的目录路径。

返回值：

Directory - 临时目录的 Directory 实例。

异常：

FSException - 目录不存在或创建失败时抛出异常。
IllegalArgumentException - 目录为空或包含空字符时抛出异常。

static func delete(Path, Bool)

public static func delete(path: Path, recursive!: Bool = false): Unit

功能：删除目录。

可指定是否递归删除，如果需要递归删除，将逐级删除目录。

参数：

path: Path - Path 形式的指定目录路径。
recursive!: Bool - 是否递归，true 代表递归，false 代表不递归，默认 false 不递归。

异常：

FSException - 如果目录不存在或递归删除失败，则抛出异常。
IllegalArgumentException - 如果 path 为空字符串或包含空字符或长度大于 4096 ，则出抛异常。

static func delete(String, Bool)

public static func delete(path: String, recursive!: Bool = false): Unit

功能：删除目录。

可指定是否递归删除，如果需要递归删除，将逐级删除目录。

参数：

path: String - 字符串形式的指定目录路径。
recursive!: Bool - 是否递归，true 代表递归，false 代表不递归，默认 false 不递归。

异常：

FSException - 如果目录不存在或递归删除失败，则抛出异常。
IllegalArgumentException - 如果 path 为空字符串或包含空字符或长度大于 4096 ，则出抛异常。

static func exists(Path)

public static func exists(path: Path): Bool

功能：判断路径对应的目录是否存在。

参数：

path: Path - Path 形式的目录路径。

返回值：

Bool - false 表示路径不存在或者路径对应的不是目录，true 表示路径对应的是目录或指向目录的软链接。

static func exists(String)

public static func exists(path: String): Bool

功能：判断路径对应的目录是否存在。

参数：

path: String - 字符串形式的目录路径。

返回值：

Bool - false 表示路径不存在，或者路径对应的不是目录，true 表示路径对应的是目录或指向目录的软链接。

static func move(Path, Path, Bool)

public static func move(sourceDirPath: Path, destinationDirPath: Path, overwrite: Bool): Unit

功能：将该目录以及文件、子文件夹都移动到指定路径。

参数：

sourceDirPath: Path - Path 形式的源目录路径。
destinationDirPath: Path - Path 形式的目标目录路径。
overwrite: Bool - 是否覆盖, 为 true 时将覆盖目标路径中的所有子文件夹和文件，为 false 时不覆盖。

异常：

IllegalArgumentException - 目标目录名为空，或目标目录名包含空字符。
FSException - 源目录不存在，或 overwrite 为 false 时目标目录已存在，或移动失败。

static func move(String, String, Bool)

public static func move(sourceDirPath: String, destinationDirPath: String, overwrite: Bool): Unit

功能：将该目录以及文件、子文件夹都移动到指定路径。

参数：

sourceDirPath: String - 字符串形式的源目录路径。
destinationDirPath: String - 字符串形式的目标目录路径。
overwrite: Bool - 是否覆盖, 为 true 时将覆盖目标路径中的所有子文件夹和文件，为 false 时不覆盖。

异常：

IllegalArgumentException - 目标目录名为空，或目标目录名包含空字符。
FSException - 源目录不存在，或 overwrite 为 false 时目标目录已存在，或移动失败。

func createFile(String)

public func createFile(name: String): File

功能：在当前 Directory 下创建指定名字的子文件。

参数：

name: String - 子文件名，参数只接受不带路径前缀的字符串。

返回值：

File - 子文件的 File 实例，该实例需要手动及时调用 close 函数关闭文件。

异常：

FSException - 当子文件名中含有路径信息或文件名已存在，抛出异常。
IllegalArgumentException - 当文件名包含空字符时抛出异常。

func createSubDirectory(String)

public func createSubDirectory(name: String): Directory

功能：在当前 Directory 下创建指定名字的子目录。

参数：

name: String - 子目录名，参数只接受不带路径前缀的字符串。

返回值：

Directory - 子目录的 Directory 实例。

异常：

FSException - 当子目录名中含有路径信息、路径已存在或创建目录失败时，抛出异常。
IllegalArgumentException - 当目录名中含有空字符时，抛出异常。

func directories()

public func directories(): Iterator<FileInfo>

返回值：

Iterator<FileInfo> - 当前目录的子目录迭代器。

返回值：目录是否为空，true 为空，false 不为空。

异常：

FSException - 获取目录的成员信息失败时，抛出异常。

func directoryList()

public func directoryList(): ArrayList<FileInfo>

返回值：

ArrayList<FileInfo> - 当前目录的所有子目录列表。

异常：

FSException - 获取目录的成员信息失败时，抛出异常。

func entryList()

public func entryList(): ArrayList<FileInfo>

返回值：

ArrayList<FileInfo> - 当前目录的文件或子目录列表。

异常：

FSException - 获取目录的成员信息失败时，抛出异常。

func fileList()

public func fileList(): ArrayList<FileInfo>

功能：返回当前目录的子文件列表。

返回值：

ArrayList<FileInfo> - 当前目录的子文件列表。

异常：

FSException - 获取目录的成员信息失败时，抛出异常。

func files()

public func files(): Iterator<FileInfo>

功能：返回当前目录的子文件迭代器。

返回值：

Iterator<FileInfo> - 当前目录的子文件迭代器。

异常：

FSException - 获取目录的成员信息失败时，抛出异常。

func isEmpty()

public func isEmpty(): Bool

功能：判断当前目录是否为空。

返回值：

Bool - 为 true 时目录为空，为 false 时不为空。

异常：

FSException - 如果判断过程中底层调用的系统接口发生错误，则抛异常。

func iterator()

public func iterator(): Iterator<FileInfo>

返回值：

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 copy(Path, Path, Bool)

public static func copy(sourcePath: Path, destinationPath: Path, overwrite: Bool): Unit

功能：将文件拷贝到新的位置，不成功则抛异常。

参数：

sourcePath: Path - 文件原路径。
destinationPath: Path - 文件目标路径。
overwrite: Bool - 是否覆盖, 为 true 时覆盖，为false 时不覆盖。

异常：

FSException - 文件路径为空，或源路径文件无读权限，或目标路径文件已存在且无写权限则抛出异常。
IllegalArgumentException - 文件路径包含空字符则抛出异常。

static func copy(String, String, Bool)

public static func copy(sourcePath: String, destinationPath: String, overwrite: Bool): Unit

功能：将文件拷贝到新的位置，不成功则抛异常。

参数：

sourcePath: String - 文件原路径。
destinationPath: String - 文件目标路径。
overwrite: Bool - 是否覆盖, 为 true 时覆盖，为false 时不覆盖。

异常：

FSException - 文件路径为空，或源路径文件无读权限，或目标路径文件已存在且无写权限则抛出异常。
IllegalArgumentException - 文件路径包含空字符则抛出异常。

static func create(Path)

public static func create(path: Path): File

功能：以只写模式创建指定路径的文件。

参数：

path: Path - 文件路径。

返回值：

File - File 实例。

异常：

FSException - 如果路径指向的文件的上级目录不存在或文件已存在，则抛出异常。
IllegalArgumentException - 如果文件路径为空或包含空字符，则抛出异常。

static func create(String)

public static func create(path: String): File

功能：以只写模式创建指定路径的文件。

参数：

path: String - 文件路径字符串。

返回值：

File - File 实例。

异常：

FSException - 如果路径指向的文件的上级目录不存在或文件已存在，则抛出异常。
IllegalArgumentException - 如果文件路径为空字符串或包含空字符，则抛出异常。

static func createTemp(Path)

public static func createTemp(directoryPath: Path): File

功能：在指定目录下创建临时文件。

创建的文件名称是 tmpFileXXXXXX 形式，不使用的临时文件应手动删除。

参数：

directoryPath: Path - 目录路径。

返回值：

File - 临时文件 File 实例。

异常：

FSException - 创建文件失败或路径不存在则抛出异常。
IllegalArgumentException - 如果文件路径为空或包含空字符，则抛出异常。

static func createTemp(String)

public static func createTemp(directoryPath: String): File

功能：在指定目录下创建临时文件。

创建的文件名称是 tmpFileXXXXXX 形式，不使用的临时文件应手动删除。

参数：

directoryPath: String - 目录路径字符串。

返回值：

File - 临时文件 File 实例。

异常：

FSException - 创建文件失败或路径不存在则抛出异常。
IllegalArgumentException - 如果文件路径为空字符串或包含空字符，则抛出异常。

static func delete(Path)

public static func delete(path: Path): Unit

功能：删除指定路径下的文件。

删除文件前需保证文件存在并且已关闭，否则可能删除失败。

参数：

path: Path - 文件路径。

异常：

FSException - 如果指定文件不存在，或删除失败，则抛异常。

static func delete(String)

public static func delete(path: String): Unit

功能：删除指定路径下的文件。

删除文件前需保证文件存在并且已关闭，否则可能删除失败。

参数：

path: String - 文件路径字符串。

异常：

FSException - 如果指定文件不存在，或删除失败，则抛异常。

static func exists(Path)

public static func exists(path: Path): Bool

功能：判断路径对应的文件是否存在。

参数：

path: Path - 文件路径。

返回值：

Bool - false 表示路径不存在或者路径对应的不是文件，true 表示路径对应的是文件或指向文件的软链接。

static func exists(String)

public static func exists(path: String): Bool

功能：判断路径对应的文件是否存在。

参数：

path: String - 文件路径字符串。

返回值：

Bool - false 表示路径不存在或者路径对应的不是文件，true 表示路径对应的是文件或指向文件的软链接。

static func move(Path, Path, Bool)

public static func move(sourcePath: Path, destinationPath: Path, overwrite: Bool): Unit

功能：移动文件。

当 overwrite 为 true，如果指定路径中已有同名的文件，则会覆盖已存在的文件，当 overwrite 为 false，不覆盖，如果目标目录已存在会抛出异常。

参数：

sourcePath: Path - 文件原路径。
destinationPath: Path - 文件目标路径。
overwrite: Bool - 是否覆盖, 为 true 时覆盖，为false 时不覆盖。

异常：

IllegalArgumentException - 目标目录名为空，或目标目录名包含空字符。
FSException - 源目录不存在，或 overwrite 为 false 时目标目录已存在，或移动失败。

static func move(String, String, Bool)

public static func move(sourcePath: String, destinationPath: String, overwrite: Bool): Unit

功能：移动文件。

当 overwrite 为 true，如果指定路径中已有同名的文件，则会覆盖已存在的文件，当 overwrite 为 false，不覆盖，如果目标目录已存在会抛出异常。

参数：

sourcePath: String - 文件原路径。
destinationPath: String - 文件目标路径。
overwrite: Bool - 是否覆盖, 为 true 时将覆盖目标路径中的文件，为 false 时不覆盖。

异常：

IllegalArgumentException - 目标目录名为空，或目标目录名包含空字符。
FSException - 源目录不存在，或 overwrite 为 false 时目标目录已存在，或移动失败。

static func openRead(Path)

public static func openRead(path: Path): File

功能：以只读模式打开指定路径的文件。

参数：

path: Path - 文件路径。

返回值：

File - File 实例，该实例需要手动及时调用 close 函数关闭文件。

异常：

FSException - 如果文件不存在，或文件不可读，则抛异常。
IllegalArgumentException - 文件路径包含空字符则抛出异常。

static func openRead(String)

public static func openRead(path: String): File

功能：以只读模式打开指定路径的文件。

参数：

path: String - 文件路径字符串。

返回值：

File - File 实例，该实例需要手动及时调用 close 函数关闭文件。

异常：

FSException - 如果文件不存在，或文件不可读，则抛异常。
IllegalArgumentException - 文件路径包含空字符则抛出异常。

static func readFrom(Path)

public static func readFrom(path: Path): Array<Byte>

功能：根据指定路径读取文件全部内容，以字节数组的形式返回其内容。

参数：

path: Path - 文件路径。

返回值：

Array<Byte> - 字节数组形式的文件全部内容。

异常：

FSException - 文件路径为空、文件不可读、文件读取失败，则抛出异常。
IllegalArgumentException - 文件路径包含空字符则抛出异常。

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。

异常：

FSException - 文件路径为空则抛出异常。
IllegalArgumentException - 如果文件路径为空或包含空字符，则抛出异常。

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。

异常：

FSException - 文件路径为空则抛出异常。
IllegalArgumentException - 如果文件路径为空字符串或包含空字符，则抛出异常。

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 对象。

异常：

FSException - 如果关闭失败，则抛异常。

func copyTo(OutputStream)

public func copyTo(out: OutputStream): Unit

功能：将当前 File 还没读取的数据全部写入到指定的 OutputStream 中。

参数：

out: OutputStream - 待写入的 OutputStream。

异常：

FSException - 文件读取时未被打开或文件没有读取权限，则抛出异常。

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。

异常：

IllegalArgumentException - 如果 buffer 为空，则抛出异常。
FSException - 读取失败、文件已关闭，或文件不可读，则抛出异常。

func readToEnd()

public func readToEnd(): Array<Byte>

功能：读取当前 File 所有剩余数据，以 Array<Byte> 形式返回剩余的 bytes。

返回值：

Array<Byte> - 文件内剩余的字节数组形式内容。

异常：

FSException - 如果读取失败，或文件不可读，则抛异常。

func seek(SeekPosition)

public func seek(sp: SeekPosition): Int64

功能：将光标跳转到指定位置。

指定的位置不能位于文件头部之前，指定位置可以超过文件末尾，但指定位置到文件头部的最大偏移量不能超过当前文件系统允许的最大值，这个最大值接近当前文件系统的所允许的最大文件大小，一般为最大文件大小减去 4096 个字节。

参数：

sp: SeekPosition - 指定光标跳转后的位置。

返回值：

Int64 - 返回文件头部到跳转后位置的偏移量（以字节为单位）。

异常：

FSException - 指定位置不满足以上情况时，或文件不能 seek 时均会抛异常。

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能：将 buffer 中的数据写入到文件中。

参数：

buffer: Array<Byte> - 待写入数据的缓冲区，若 buffer 为空则直接返回。

异常：

FSException - 如果写入失败、只写入了部分数据、文件已关闭或文件不可写则抛出异常。

枚举

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 length

public prop length: Int64

功能：返回当前文件大小。

当前是文件时，表示单个文件占用磁盘空间的大小。
当前是目录时，表示当前目录的所有文件占用磁盘空间的大小。

类型：Int64

异常：

FSException - 如果判断过程中底层调用的系统接口发生错误，则抛异常。

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 symbolicLinkTarget

public prop symbolicLinkTarget: Option<Path>

功能：获得链接目标路径，以 Option<Path> 形式返回，当前是符号链接返回 Option<Path>.Some(v)；否则返回 Option<Path>.None。

类型：Option<Path>

init(Path)

public init(path: Path)

功能：创建 FileInfo 实例。

参数：

path: Path - Path 形式的目录路径。

异常：

FSException - 当路径非法时，抛出异常。

init(String)

public init(path: String)

功能：创建 FileInfo 实例。

参数：

path: String - String 形式的目录路径。

异常：

FSException - 当路径非法时，抛出异常。

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 isFile()

public func isFile(): 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 - 如果判断过程中底层调用的系统接口发生错误，则抛异常。

func isSymbolicLink()

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 是否对应非同一文件。

参数：

that: FileInfo - 另一个 FileInfo。

返回值：

Bool - true，不是同一文件；false，是同一文件。

operator func ==(FileInfo)

public operator func ==(that: FileInfo): Bool

功能：判断当前 FileInfo 和另一个 FileInfo 是否对应同一文件。

参数：

that: FileInfo - 另一个 FileInfo。

返回值：

Bool - true，是同一文件；false，不是同一文件。

struct Path

public struct Path <: Equatable<Path> & Hashable & ToString {
    public init(rawPath: String)
}

功能：提供路径相关的函数。

Path 用来表示本地路径（Windows 平台已支持 DOS 设备路径和 UNC 路径，长度限制跟随系统）。路径的字符串最大支持 4096 个字节（包括结束符 \0）。

说明：

非法路径指的是以下情况之一：

路径中包含非法字符，例如空格、制表符、换行符等；

路径中包含不合法的字符，例如特殊字符、控制字符等；

路径中包含不存在的目录或文件；

路径中包含无法访问的目录或文件，例如权限不足或被锁定等。

在输入路径时，应该避免使用非法字符，确保路径的合法性，以便正确地访问目标文件或目录。

prop directoryName

public prop directoryName: Option<Path>

功能：获得 Path 的目录部分，以 Option<Path> 形式返回。

对于路径 "/a/b/c"，此属性返回 Some(Path("/a/b"))。
对于路径 "/a/b/"，此属性返回 Some(Path("/a/b"))。
对于路径 "/a"，此属性返回 Some(Path("/"))。
对于路径 "/"，此属性返回 Some(Path("/"))。
对于路径 "./a/b"，此属性返回 Some(Path("./a"))。
对于路径 "./"，此属性返回 Some(Path("."))。
对于路径 "."，此属性返回 None。
对于路径 ".gitignore"，此属性返回 None。
对于路径 "a.txt"，此属性返回 None。
对于路径 "C:\a\b\c"，此属性返回 Some(Path("C:\a\b"))。
对于路径 "C:\a\b"，此属性返回 Some(Path("C:\a\b"))。

返回值：返回构造时传入的路径中的目录部分，构造时传入的路径中无目录部分时返回 None。

类型：Option<Path>

异常：

IllegalArgumentException - 当路径为空，或包含字符串结束符则抛出异常。

prop extensionName

public prop extensionName: Option<String>

功能：获得 Path 的文件扩展名部分，以 Option<String> 形式返回。

对于路径 "./NewFile.txt"，此属性返回 Some("txt")。
对于路径 "./.gitignore"，此属性返回 Some("gitignore")。
对于路径 "./noextension"，此属性返回 None。
对于路径 "./a.b.c"，此属性返回 Some("c")。
对于路径 "./NewDir/"，此属性返回 None。
对于路径 "./NewDir/NewFile."，此属性返回 None。

返回值：返回构造时传入的路径中的文件扩展名部分，构造时传入的路径中无文件扩展名部分时返回 None。

类型：Option<String>

异常：

IllegalArgumentException - 当路径为空，或包含字符串结束符则抛出异常。

prop fileName

public prop fileName: Option<String>

功能：获得 Path 的文件名（含扩展名）部分，以 Option<String> 形式返回。

对于路径 "./NewFile.txt"，此属性返回 Some("NewFile.txt")。
对于路径 "./.gitignore"，此属性返回 Some(".gitignore")。
对于路径 "./noextension"，此属性返回 Some("noextension")。
对于路径 "./a.b.c"，此属性返回 Some("a.b.c")。
对于路径 "./NewDir/"，此属性返回 None。

返回值：返回构造时传入的路径中的文件名（含扩展名）部分，构造时传入的路径中无文件名（含扩展名）部分时返回 None。

类型：Option<String>

异常：

IllegalArgumentException - 当路径为空，或包含字符串结束符则抛出异常。

prop fileNameWithoutExtension

public prop fileNameWithoutExtension: Option<String>

功能：获得 Path 的文件名（不含扩展名）部分，以 Option<String> 形式返回。

对于路径 "./NewFile.txt"，此属性返回 Some("NewFile")。
对于路径 "./.gitignore"，此属性返回 None。
对于路径 "./noextension"，此属性返回 Some("noextension")。
对于路径 "./a.b.c"，此属性返回 Some("a.b")。
对于路径 "./NewDir/"，此属性返回 None。

返回值：返回构造时传入的路径中的文件名（不含扩展名）部分，构造时传入的路径中无文件名（不含扩展名）部分时返回 None。

类型：Option<String>

异常：

IllegalArgumentException - 当路径为空，或包含字符串结束符则抛出异常。

init(String)

public init(rawPath: String)

功能：创建 Path 实例时不检查路径字符串是否合法，支持绝对路径和相对路径。

参数：

rawPath: String - 路径的字符串。

func hashCode()

public func hashCode(): Int64

功能：获得 Path 的哈希值。

返回值：

Int64 - Path 的哈希值。

func isAbsolute()

public func isAbsolute(): Bool

功能：判断 Path 是否是绝对路径。在 Unix 中，以 / 开头的路径为绝对路径。

返回值：

Bool - true，是绝对路径；false，不是绝对路径。

异常：

IllegalArgumentException - 当路径为空，或包含字符串结束符则抛出异常。

func isDirectory()

public func isDirectory(): Bool

功能：判断 Path 是否是目录，与 isFile, isSymbolicLink 互斥。

返回值：

Bool - true，是目录；false，不是目录。

异常：

FSException - 如果路径不存在，或者判断过程中底层调用的系统接口发生错误，则抛异常。
IllegalArgumentException - 当路径为空，或包含字符串结束符则抛出异常。

func isFile()

public func isFile(): Bool

功能：判断 Path 是否是文件，与 isSymbolicLink, isDirectory 互斥。

返回值：

Bool - true，是文件；false，不是文件。

异常：

FSException - 如果路径不存在，或者判断过程中底层调用的系统接口发生错误，则抛异常。
IllegalArgumentException - 当路径为空，或包含字符串结束符则抛出异常。

func isRelative()

public func isRelative(): Bool

功能：判断 Path 是否是相对路径, 其结果与函数 isAbsolute 结果相反。

返回值：

Bool - true，是相对路径；false，不是相对路径。

异常：

IllegalArgumentException - 当路径为空，或包含字符串结束符则抛出异常。

func isSymbolicLink()

public func isSymbolicLink(): Bool

功能：判断 Path 是否是软链接，与 isFile, isDirectory 互斥。

返回值：

Bool - true，是软链接；false，不是软链接。

异常：

FSException - 如果路径不存在，或者判断过程中底层调用的系统接口发生错误，则抛异常。
IllegalArgumentException - 当路径为空，或包含字符串结束符则抛出异常。

func join(Path)

public func join(path: Path): Path

功能：在当前路径后拼接另一个路径字符串形成新路径。

对于路径 "a/b", "c"，返回 "a/b/c"。
对于路径 "a", "b/c"，返回 "a/b/c"。

返回值：

Path - 新路径的 Path 实例。

异常：

FSException - 如果参数 path 是绝对路径则抛异常。
IllegalArgumentException - 当前路径为空，或当前路径、入参路径非法时抛出异常。

func join(String)

public func join(path: String): Path

功能：在当前路径后拼接另一个路径字符串形成新路径。

对于路径 "a/b", "c"，返回 "a/b/c"。
对于路径 "a", "b/c"，返回 "a/b/c"。

返回值：

Path - 新路径的 Path 实例。

异常：

FSException - 如果参数 path 是绝对路径则抛异常。
IllegalArgumentException - 当前路径为空，或当前路径、入参路径非法时抛出异常。

func split()

public func split(): (Option<Path>, Option<String>)

功能：将 Path 分割成目录和文件名两部分以元组形式返回分割结果 (directoryName, fileName) 。

返回值：

(Option<Path>, Option<String>) - 返回值为元组类型，第一个元素表示路径，路径获取成功，返回 Option<Path>.Some(p)，失败，返回 Option<Path>.None；第二个元素表示文件名，文件名获取成功，返回 Option<String>.Some(s)，失败，返回 Option<String>.None。

异常：

IllegalArgumentException - 当路径为空，或包含字符串结束符则抛出异常。

func toCanonical()

public func toCanonical(): Path

功能：将 Path 规范化返回绝对路径形式的规范化路径。

所有的中间引用和软链接都会处理（UNC 路径下的软链接无法被规范化），例如，对于路径 "/foo/test/../test/bar.txt"，该函数会返回 "/foo/test/bar.txt"。

返回值：

Path - 规范化路径的 Path 实例。

异常：

FSException - 路径不存在或无法规范化时抛出异常。
IllegalArgumentException - 路径为空，或包含字符串结束符时抛出异常。

func toString()

public func toString(): String

功能：获得 Path 的路径字符串。

返回值：

String - Path 的路径字符串。

operator func !=(Path)

public operator func !=(that: Path): Bool

功能：判断 Path 是否不是同一路径。

参数：

that: Path - 另一个 Path。

返回值：

Bool - true，不是同一路径；false，是同一路径。

operator func ==(Path)

public operator func ==(that: Path): Bool

功能：判断 Path 是否是同一路径。

参数：

that: Path - 另一个 Path。

返回值：

Bool - true，是同一路径；false，不是同一路径。

异常类

class FSException

文件流异常类，继承了异常类。

public class FSException <: Exception {
    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 (Directory.exists(testDirPath)) {
        Directory.delete(testDirPath, recursive: true)
    }

    /* 递归创建目录 和 "./testDir/subDir" */
    let subDir: Directory = Directory.create(subDirPath, recursive: true)
    if (Directory.exists(subDirPath)) {
        println("The directory './testDir/subDir' is successfully created recursively in current directory.")
    }

    /* 在 "./testDir/subDir" 下创建子目录 "dir1" */
    subDir.createSubDirectory("dir1")
    if (Directory.exists("./testDir/subDir/dir1")) {
        println("The directory 'dir1' is created successfully in directory './testDir/subDir'.")
    }

    /* 在 "./testDir/subDir" 下创建子文件 "file1" */
    subDir.createFile("file1")
    if (File.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 (Directory.exists(tempDirPath)) {
        println("The temporary directory is created successfully in directory './testDir'.")
    }

    /* 将 "subDir" 移动到临时目录下并重命名为 "subDir_new" */
    let newSubDirPath: Path = tempDirPath.join("subDir_new")
    Directory.move(subDirPath, newSubDirPath, false)
    if (Directory.exists(newSubDirPath) && !Directory.exists(subDirPath)) {
        println("The directory './testDir/subDir' is moved successfully to the temporary directory and renamed 'subDir_new'.")
    }

    /* 将 "subDir_new" 拷贝到 "./testDir" 下并重命名为 "subDir" */
    Directory.copy(newSubDirPath, subDirPath, false)
    if (Directory.exists(subDirPath) && Directory.exists(newSubDirPath)) {
        println("The directory 'subDir_new' is copied successfully to directory './testDir' and renamed 'subDir'.")
    }

    Directory.delete(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.SeekPosition

main() {
    let filePath: Path = Path("./tempFile.txt")
    if (File.exists(filePath)) {
        File.delete(filePath)
    }

    /* 在当前目录以 只写模式 创建新文件 'tempFile.txt'，写入三遍 "123456789\n" 并关闭文件 */
    var file: File = File(filePath, OpenOption.Create(false))
    if (File.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, item: 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> = file.readToEnd()
    file.close()
    println("Data written newly: ${String.fromUtf8(allBytes)}")

    File.delete(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 (File.exists(filePath)) {
        File.delete(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))

    File.delete(filePath)
    return 0
}

运行结果如下：

123456789
abcdefghi

FileInfo 示例

FileInfo 一些基础操作演示

代码如下：

import std.fs.*
import std.time.DateTime

main() {
    // 在当前目录下创建个临时文件以便下面 FileInfo 的演示
    let curDirPath: Path = Path("./").toCanonical()
    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
    */

    /* 如果文件是软链接，获得其链接文件的 Path，这里的文件不是软链接故是 Option<Path>.None */
    let symbolicLinkTarget: Option<Path> = fileInfo.symbolicLinkTarget
    checkResult(symbolicLinkTarget == None, "It's not a symbolic link, there's no `symbolicLinkTarget`.")

    /* 获取这个文件的创建时间、最后访问时间、最后修改时间 */
    /*
    let creationTime: DateTime = fileInfo.creationTime
    let lastAccessTime: DateTime = fileInfo.lastAccessTime
    let lastModificationTime: DateTime = fileInfo.lastModificationTime
    */

    /*
     * 获取这个文件的 length
     * 如果是文件代表这个文件占用磁盘空间的大小
     * 如果是目录代表这个目录的所有文件占用磁盘空间的大小(不包含子目录)
     */
    /*
    let length: Int64 = fileInfo.length
    */

    /* 判断这个文件是否是软链接、普通文件、目录 */
    checkResult(fileInfo.isSymbolicLink(), "The file is a symbolic link.")
    checkResult(fileInfo.isFile(), "The file is a common 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.
It's not a symbolic link, there's no `symbolicLinkTarget`.
The file is a common 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.directoryName: ${path.directoryName}")
        // 打印 path 的文件全名（有扩展名）
        println("Path.fileName: ${path.fileName}")
        // 打印 path 的扩展名
        println("Path.extensionName: ${path.extensionName}")
        // 打印 path 的文件名（无扩展名）
        println("Path.fileNameWithoutExtension: ${path.fileNameWithoutExtension}")
        // 打印 path 的拆分成的目录路径和文件全名
        var (directoryName, fileName): (Option<Path>, Option<String>) = path.split()
        println("Path.split: (${directoryName}, ${fileName})")
        // 打印 path 的是否是符号链接、普通文件、目录
        println("Path.isAbsolute: ${path.isAbsolute()}; Path.isRelative: ${path.isRelative()}")
        println()
    }

    return 0
}

运行结果如下：

Path0: /a/b/c
Path.directoryName: Some(/a/b)
Path.fileName: Some(c)
Path.extensionName: None
Path.fileNameWithoutExtension: Some(c)
Path.split: (Some(/a/b), Some(c))
Path.isAbsolute: true; Path.isRelative: false

Path1: /a/b/
Path.directoryName: Some(/a/b)
Path.fileName: None
Path.extensionName: None
Path.fileNameWithoutExtension: None
Path.split: (Some(/a/b), None)
Path.isAbsolute: true; Path.isRelative: false

Path2: /a/b/c.cj
Path.directoryName: Some(/a/b)
Path.fileName: Some(c.cj)
Path.extensionName: Some(cj)
Path.fileNameWithoutExtension: Some(c)
Path.split: (Some(/a/b), Some(c.cj))
Path.isAbsolute: true; Path.isRelative: false

Path3: /a
Path.directoryName: Some(/)
Path.fileName: Some(a)
Path.extensionName: None
Path.fileNameWithoutExtension: Some(a)
Path.split: (Some(/), Some(a))
Path.isAbsolute: true; Path.isRelative: false

Path4: /
Path.directoryName: Some(/)
Path.fileName: None
Path.extensionName: None
Path.fileNameWithoutExtension: None
Path.split: (Some(/), None)
Path.isAbsolute: true; Path.isRelative: false

Path5: ./a/b/c
Path.directoryName: Some(./a/b)
Path.fileName: Some(c)
Path.extensionName: None
Path.fileNameWithoutExtension: Some(c)
Path.split: (Some(./a/b), Some(c))
Path.isAbsolute: false; Path.isRelative: true

Path6: ./a/b/
Path.directoryName: Some(./a/b)
Path.fileName: None
Path.extensionName: None
Path.fileNameWithoutExtension: None
Path.split: (Some(./a/b), None)
Path.isAbsolute: false; Path.isRelative: true

Path7: ./a/b/c.cj
Path.directoryName: Some(./a/b)
Path.fileName: Some(c.cj)
Path.extensionName: Some(cj)
Path.fileNameWithoutExtension: Some(c)
Path.split: (Some(./a/b), Some(c.cj))
Path.isAbsolute: false; Path.isRelative: true

Path8: ./
Path.directoryName: Some(.)
Path.fileName: None
Path.extensionName: None
Path.fileNameWithoutExtension: None
Path.split: (Some(.), None)
Path.isAbsolute: false; Path.isRelative: true

Path9: .
Path.directoryName: None
Path.fileName: Some(.)
Path.extensionName: None
Path.fileNameWithoutExtension: None
Path.split: (None, Some(.))
Path.isAbsolute: false; Path.isRelative: true

Path10: 123.
Path.directoryName: None
Path.fileName: Some(123.)
Path.extensionName: None
Path.fileNameWithoutExtension: Some(123)
Path.split: (None, Some(123.))
Path.isAbsolute: false; Path.isRelative: true

Path 的拼接、判等、转规范化路径等操作

代码如下：

import std.fs.*

main() {
    let dirPath: Path = Path("./a/b/c")
    if (!Directory.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 (!File.exists(filePath)) {
        File.create(filePath).close()
    }

    let curNormalizedPath: Path = Path(".").toCanonical()
    let fileNormalizedPath: Path = Path("././././a/./../a/b/../../a/b/c/.././../../a/b/c/d.cj").toCanonical()
    if (fileNormalizedPath == filePath &&
        fileNormalizedPath.toString() == curNormalizedPath.toString() + "/a/b/c/d.cj") {
        println("filePath.toCanonical: success")
    }

    Directory.delete(dirPath, recursive: true)
    return 0
}

运行结果如下：

filePath.join: success
filePath.toCanonical: success

通过 Path 创建文件和目录

代码如下：

import std.fs.*

main() {
    let curPath: Path = Path("./")
    let dirPath: Path = curPath.join("tempDir")
    let filePath: Path = dirPath.join("tempFile.txt")
    if (Directory.exists(dirPath)) {
        Directory.delete(dirPath, recursive: true)
    }

    Directory.create(dirPath)
    if (Directory.exists(dirPath)) {
        println("Directory 'tempDir' is created successfully.")
    }

    File.create(filePath).close()
    if (File.exists(filePath)) {
        println("File 'tempFile.txt' is created successfully in directory 'tempDir'.")
    }

    Directory.delete(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 列表

接口

接口名	功能
InputStream	输入流接口
IOStream	输入输出流接口
OutputStream	输出流接口
Seekable	移动光标接口

类

类名	功能
ByteArrayStream	输入流接口
BufferedInputStream<T> where T <: InputStream	提供带缓冲区的输入流
BufferedOutputStream<T> where T <: OutputStream	提供带缓冲区的输出流。
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	输入流接口

异常类

异常类名	功能
IOException	提供 io 流相关的异常处理
ContentFormatException	提供字符格式相关的异常处理

接口

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

功能：移动光标到指定的位置。

参数：

sp: SeekPosition - 指定光标移动后的位置。

返回值：

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 类型的输入流（如 ByteArrayStream）绑定到 BufferedInputStream 实例，从该实例读取数据时，先把数据从被绑定的流读入缓冲区暂存，再从缓冲区读取用户需要的数据。

init(T)

public init(input: T)

功能：创建 BufferedInputStream 实例，缓冲区容量取默认值 4096。

参数：

input: T - 绑定指定输入流。

init(T, Array<Byte>)

public init(input: T, buffer: Array<Byte>)

功能：创建 BufferedInputStream 实例。

其内部使用的缓存区由入参决定，在注重性能的场景下，通过复用传入的 buffer，可以减少内存分配次数，提高性能。

参数：

input: T - 绑定一个输入流。
buffer: Array<Byte> - BufferedInputStream 使用的内部缓存区。

异常：

IllegalArgumentException - 当 buffer 大小等于 0 时，抛出异常。

init(T, Int64)

public init(input: T, capacity: Int64)

功能：创建 BufferedInputStream 实例。

参数：

input: T - 绑定指定输入流。
capacity: Int64 - 内部缓冲区容量。

异常：

IllegalArgumentException - 当 capacity 小于等于 0 时，抛出异常。

func read(Array<Byte>)

public func read(buffer: Array<Byte>): Int64

功能：从绑定的输入流读出数据到 buffer 中。

参数：

buffer: Array<Byte> - 存放读取的数据的缓冲区。

返回值：

Int64 - 读取数据的字节数。

异常：

IllegalArgumentException - 当 buffer 为空时，抛出异常。

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

功能：移动光标到指定的位置。

说明：

指定的位置不能位于流中数据头部之前。

指定位置可以超过流中数据末尾。

调用该函数会先清空缓存区，再移动光标的位置。

参数：

sp: SeekPosition - 指定光标移动后的位置。

返回值：

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 类型的输入流（如 ByteArrayStream）绑定到 BufferedOutputStream 实例，从该实例写入数据时，先把数据写入缓冲区暂存，再从缓冲区写入数据到流中。

init(T)

public init(output: T)

功能：创建 BufferedOutputStream 实例，缓冲区容量取默认值 4096。

参数：

output: T - 绑定指定输出流。

init(T, Array<Byte>)

public init(output: T, buffer: Array<Byte>)

功能：创建 BufferedOutputStream 实例。

其内部使用的缓存区由入参决定，在注重性能的场景下，通过复用传入的 buffer，可以减少内存分配次数，提高性能。

参数：

output: T - 绑定一个输出流。
buffer: Array<Byte> - BufferedOutputStream 使用的内部缓存区。

异常：

IllegalArgumentException - 当 buffer 大小等于 0 时，抛出异常。

init(T, Int64)

public init(output: T, capacity: Int64)

功能：创建 BufferedOutputStream 实例。

参数：

output: T - 绑定指定输出流。
capacity: Int64 - 内部缓冲区容量。

异常：

IllegalArgumentException - 当 capacity 小于等于 0 时，抛出异常。

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> - 待写入数据的缓冲区。

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

功能：移动光标到指定的位置。

说明：

指定的位置不能位于流中数据头部之前。

指定位置可以超过流中数据末尾。

调用该函数会先将缓存区内的数据写到绑定的输出流里，再移动光标的位置。

参数：

sp: SeekPosition - 指定光标移动后的位置。

返回值：

Int64 - 返回流中数据的起点到移动后位置的偏移量（以字节为单位）。

class ByteArrayStream

public class ByteArrayStream <: IOStream & Seekable {
    public init()
    public init(capacity: Int64)
}

功能：基于 Array<Byte> 数据类型，提供对字节流的写入、读取等操作。

prop length

public prop length: Int64

功能：返回当前流中的总数据量。

类型：Int64

prop position

public prop position: Int64

功能：获取当前光标位置。

类型：Int64

prop remainLength

public prop remainLength: Int64

功能：获取当前流中未读的数据量。

类型：Int64

init()

public init()

功能：创建 ByteArrayStream 实例，默认的初始容量是 32。

init(Int64)

public init(capacity: Int64)

功能：创建 ByteArrayStream 实例。

参数：

capacity: Int64 - 指定的初始容量。

异常：

IllegalArgumentException - 当 capacity 小于 0 时，抛出异常。

static func fromString(String)

public static func fromString(data: String): ByteArrayStream

功能：通过 String 类型构造一个 ByteArrayStream。

参数：

data: String - 构造一个新 ByteArrayStream 的初始数据。

返回值：

ByteArrayStream - 由 data 构造的 ByteArrayStream。

func bytes()

public func bytes(): Array<Byte>

功能：获取当前 ByteArrayStream 中未被读取的数据的切片。

注意：

缓冲区进行读取，写入或重置等修改操作会导致这个切片失效。

对切片的修改会影响缓冲区的内容。

返回值：

Array<Byte> - 当前流中未被读取的数据的切片。

func capacity()

public func capacity(): Int64

功能：获取当前缓冲区容量。

返回值：

Int64 - 当前缓冲区容量。

func clear()

public func clear(): Unit

功能：清除当前 ByteArrayStream 中所有数据。

func clone()

public func clone(): ByteArrayStream

功能：用当前 ByteArrayStream 中的数据来构造一个新的 ByteArrayStream。

返回值：

ByteArrayStream - 新构造的 ByteArrayStream 对象。

func copyTo(OutputStream)

public func copyTo(output: OutputStream): Unit

功能：将当前 ByteArrayStream 中未被读取的所有数据拷贝到 output 流中。

参数：

output: OutputStream - 数据将要拷贝到的流。

func read(Array<Byte>)

public func read(buffer: Array<Byte>): Int64

功能：从输入流中读取数据放到 buffer 中。

参数：

buffer: Array<Byte> - 存放读取的数据的缓冲区。

返回值：

Int64 - 读取数据的字节数。

异常：

IllegalArgumentException - 当 buffer 为空时，抛出异常。

func readString()

public func readString(): String

功能：读取流中的剩余数据，并转换为 String 类型，做 UTF-8 编码检查。

返回值：

String - 流中剩余字节组成的 String。

异常：

ContentFormatException - 当剩余字节不符合 UTF-8 编码规则时，抛出异常。

func readStringUnchecked()

public unsafe func readStringUnchecked(): String

功能：读取流中的剩余数据，并转换为 String 类型，不做 UTF-8 编码检查。

返回值：

String - 流中剩余字节组成的 String。

func readToEnd()

public func readToEnd(): Array<Byte>

功能：获取当前 ByteArrayStream 中未被读取的数据。

返回值：

Array<Byte> - 未被读取的数据的拷贝。

func reserve(Int64)

public func reserve(additional: Int64): Unit

功能：将缓冲区扩容指定大小。

说明：

当缓冲区剩余字节数大于等于 additional 时不发生扩容。

当缓冲区剩余字节数量小于 additional 时，取（additional + capacity）与（capacity的1.5倍向下取整）两个值中的最大值进行扩容。

参数：

additional: Int64 - 将要扩容的大小。

异常：

IllegalArgumentException - 当 additional 小于 0 时，抛出异常。
OverflowException - 当扩容后的缓冲区大小超过 Int64 的最大值时，抛出异常。

func seek(SeekPosition)

public func seek(sp: SeekPosition): Int64

功能：将光标跳转到指定位置。

说明：

指定的位置不能位于流中数据头部之前。

指定位置可以超过流中数据末尾。

参数：

sp: SeekPosition - 指定光标跳转后的位置。

返回值：

Int64 - 流中数据的头部到跳转后位置的偏移量（以字节为单位）。

异常：

IOException - 当指定的位置位于流中数据头部之前时，抛出异常。

func write(Array<Byte>)

public func write(buffer: Array<Byte>): Unit

功能：将 buffer 中的数据写入到输出流中。

参数：

buffer: Array<Byte> - 待写入数据的缓冲区。

异常：

IllegalArgumentException - 当数据写入失败或者只写入了部分数据时，抛出异常。

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> - 绑定指定输入流数组。

异常：

IllegalArgumentException - 当 input 为空时，抛出异常。

func read(Array<Byte>)

public func read(buffer: Array<Byte>): Int64

功能：依次从绑定 InputStream 数组中读出数据到 buffer 中。

参数：

buffer: Array<Byte> - 存储读出数据的缓冲区。

返回值：

Int64 - 读取字节数。

异常：

IllegalArgumentException - 当 buffer 为空时，抛出异常。

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> - 绑定指定输出流数组。

异常：

IllegalArgumentException - 当 output 为空时，抛出异常。

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 之一。

每行不包括换行符。

返回值：

Iterator<String> - 字符串的行迭代器。

异常：

ContentFormatException - 当for-in或者调用next()方法时读取到非法字符，抛出异常。

func read()

public func read(): ?Rune

功能：按字符读取流中的数据。

返回值：

?Rune - 读取成功，返回 Option<Rune>.Some(c)，c 为该次读出的字符；否则返回 Option<Rune>.None。

异常：

ContentFormatException - 当读取到非法字符时，抛出异常。

func readToEnd()

public func readToEnd(): String

功能：读取流中所有剩余数据。

返回值：

String - 流中所有剩余数据。

异常：

ContentFormatException - 当读取到非法字符时，抛出异常。

func readUntil((Rune)->Bool)

public func readUntil(predicate: (Rune)->Bool): Option<String>

功能：从流内读取到使 predicate 返回 true 的字符位置（包含这个字符）或者流结束位置的数据。

参数：

predicate: (Rune)->Bool - 满足一定条件返回 true 的表达式。

返回值：

Option<String> - 读取成功，返回 Option<String>.Some(str)，str 为该次读出的字符串；否则返回 Option<String>.None。

异常：

ContentFormatException - 当读取到非法字符时，抛出异常。

func readUntil(Rune)

public func readUntil(v: Rune): Option<String>

功能：从流内读取到指定字符（包含指定字符）或者流结束位置的数据。

参数：

v: Rune - 指定字符。

返回值：

Option<String> - 读取成功，返回 Option<String>.Some(str)，str 为该次读出的字符串；否则返回 Option<String>.None。

异常：

ContentFormatException - 当读取到非法字符时，抛出异常。

func readln()

public func readln(): Option<String>

功能：按行读取流中的数据。

说明：

读取的数据会去掉原换行符。

返回值：

Option<String> - 读取成功，返回 Option<String>.Some(str)，str 为该次读出的字符串；否则返回 Option<String>.None。

异常：

ContentFormatException - 当读取到非法字符时，抛出异常。

func runes()

public func runes(): Iterator<Rune>

功能：获得 StringReader 的 Rune 迭代器。

返回值：

Iterator<Rune> - 字符串的 Rune 迭代器。

异常：

ContentFormatException：当for-in或者调用next()方法时读取到非法字符，抛出异常。

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

功能：移动光标到指定的位置。

说明：

指定的位置不能位于流中数据头部之前。

指定位置可以超过流中数据末尾。

参数：

sp: SeekPosition - 指定光标移动后的位置。

返回值：

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 类型。

参数：

v: Bool - Bool 类型的实例。

func write(Float16)

public func write(v: Float16): Unit

功能：写入 Float16 类型。

参数：

v: Float16 - Float16 类型的实例。

func write(Float32)

public func write(v: Float32): Unit

功能：写入 Float32 类型。

参数：

v: Float32 - Float32 类型的实例。

func write(Float64)

public func write(v: Float64): Unit

功能：写入 Float64 类型。

参数：

v: Float64 - Float64 类型的实例。

func write(Int16)

public func write(v: Int16): Unit

功能：写入 Int16 类型。

参数：

v: Int16 - Int16 类型的实例。

func write(Int32)

public func write(v: Int32): Unit

功能：写入 Int32 类型。

参数：

v: Int32 - Int32 类型的实例。

func write(Int64)

public func write(v: Int64): Unit

功能：写入 Int64 类型。

参数：

v: Int64 - Int64 类型的实例。

func write(Int8)

public func write(v: Int8): Unit

功能：写入 Int8 类型。

参数：

v: Int8 - Int8 类型的实例。

func write(Rune)

public func write(v: Rune): Unit

功能：写入 Rune 类型。

参数：

v: Rune - Rune 类型的实例。

func write(String)

public func write(v: String): Unit

功能：写入字符串。

参数：

v: String - 待写入的字符串。

func write(UInt16)

public func write(v: UInt16): Unit

功能：写入 UInt16 类型。

参数：

v: UInt16 - UInt16 类型的实例。

func write(UInt32)

public func write(v: UInt32): Unit

功能：写入 UInt32 类型。

参数：

v: UInt32 - UInt32 类型的实例。

func write(UInt64)

public func write(v: UInt64): Unit

功能：写入 UInt64 类型。

参数：

v: UInt64 - UInt64 类型的实例。

func write(UInt8)

public func write(v: UInt8): Unit

功能：写入 UInt8 类型。

参数：

v: UInt8 - UInt8 类型的实例。

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

public func write<T>(v: T): Unit where T <: ToString

功能：写入 ToString 类型。

参数：

v: T - ToString 类型的实例。

func writeln()

public func writeln(): Unit

功能：写入换行符。

func writeln(Bool)

public func writeln(v: Bool): Unit

功能：写入 Bool 类型 + 换行符。

参数：

v: Bool - Bool 类型的实例。

func writeln(Float16)

public func writeln(v: Float16): Unit

功能：写入 Float16 类型 + 换行符。

参数：

v: Float16 - Float16 类型的实例。

func writeln(Float32)

public func writeln(v: Float32): Unit

功能：写入 Float32 类型 + 换行符。

参数：

v: Float32 - Float32 类型的实例。

func writeln(Float64)

public func writeln(v: Float64): Unit

功能：写入 Float64 类型 + 换行符。

参数：

v: Float64 - Float64 类型的实例。

func writeln(Int16)

public func writeln(v: Int16): Unit

功能：写入 Int16 类型 + 换行符。

参数：

v: Int16 - Int16 类型的实例。

func writeln(Int32)

public func writeln(v: Int32): Unit

功能：写入 Int32 类型 + 换行符。

参数：

v: Int32 - Int32 类型的实例。

func writeln(Int64)

public func writeln(v: Int64): Unit

功能：写入 Int64 类型 + 换行符。

参数：

v: Int64 - Int64 类型的实例。

func writeln(Int8)

public func writeln(v: Int8): Unit

功能：写入 Int8 类型 + 换行符。

参数：

v: Int8 - Int8 类型的实例。

func writeln(Rune)

public func writeln(v: Rune): Unit

功能：写入 Rune 类型 + 换行符。

参数：

v: Rune - Rune 类型的实例。

func writeln(String)

public func writeln(v: String): Unit

功能：写入字符串 + 换行符。

参数：

v: String - 待写入的字符串。

func writeln(UInt16)

public func writeln(v: UInt16): Unit

功能：写入 UInt16 类型 + 换行符。

参数：

v: UInt16 - UInt16 类型的实例。

func writeln(UInt32)

public func writeln(v: UInt32): Unit

功能：写入 UInt32 类型 + 换行符。

参数：

v: UInt32 - UInt32 类型的实例。

func writeln(UInt64)

public func writeln(v: UInt64): Unit

功能：写入 UInt64 类型 + 换行符。

参数：

v: UInt64 - UInt64 类型的实例。

func writeln(UInt8)

public func writeln(v: UInt8): Unit

功能：写入 UInt8 类型 + 换行符。

参数：

v: UInt8 - UInt8 类型的实例。

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

public func writeln<T>(v: T): Unit where T <: ToString

功能：写入 ToString 类型 + 换行符。

参数：

v: T - ToString 类型的实例。

extend StringWriter <: 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 StringWriter <: 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

功能：移动光标到指定的位置。

说明：

指定的位置不能位于流中数据头部之前。

指定位置可以超过流中数据末尾。

参数：

sp: SeekPosition - 指定光标移动后的位置。

返回值：

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 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 byteArrayStream = ByteArrayStream()
    byteArrayStream.write(arr1)
    let bufferedInputStream = BufferedInputStream(byteArrayStream)
    let arr2 = Array<Byte>(20, item: 0)

    /* 读取流中数据，返回读取到的数据的长度 */
    let readLen = bufferedInputStream.read(arr2)
    println(String.fromUtf8(arr2[..readLen]))
}

运行结果

0123456789

BufferedOutputStream 示例

下面是 BufferedOutputStream 向流中写入数据示例。

import std.io.*

main(): Unit {
    let arr1 = "01234".toArray()
    let byteArrayStream = ByteArrayStream()
    byteArrayStream.write(arr1)
    let bufferedInputStream = BufferedOutputStream(byteArrayStream)
    let arr2 = "56789".toArray()

    /* 向流中写入数据，此时数据在外部流的缓冲区中 */
    bufferedInputStream.write(arr2)

    /* 调用 flush 函数，真正将数据写入内部流中 */
    bufferedInputStream.flush()
    println(String.fromUtf8(byteArrayStream.readToEnd()))
}

运行结果

0123456789

ByteArrayStream 示例

下面是 ByteArrayStream 对流进行写入数据，读取数据等操作的示例。

import std.io.*

main(): Unit {
    let arr1 = "test case".toArray()
    let byteArrayStream = ByteArrayStream()

    /* 将 arr1 中的数据写入到流中 */
    byteArrayStream.write(arr1)

    /* 读取 4 个字节的数据到 arr2 中 */
    let arr2 = Array<Byte>(4, item: 0)
    byteArrayStream.read(arr2)
    println(String.fromUtf8(arr2))

    /* 将流的索引指向起点 */
    byteArrayStream.seek(Begin(0))

    /* 读取流中全部数据 */
    let arr3 = byteArrayStream.readToEnd()
    println(String.fromUtf8(arr3))

    /* 将流的索引指向字母 c */
    byteArrayStream.seek(End(-4))

    /* 读取流中剩余数据 */
    let str = byteArrayStream.readString()
    println(str)
}

运行结果

test
test case
case

ChainedInputStream 示例

下面是 ChainedInputStream 从绑定的流中循环读取数据示例。

import std.io.*
import std.collection.ArrayList

main(): Unit {
    const size = 2

    /* 创建两个 ByteArrayStream 并写入数据 */
    let streamArr = Array<InputStream>(size, {_ => ByteArrayStream()})
    for (i in 0..size) {
        match (streamArr[i]) {
            case v: OutputStream =>
                let str = "now ${i}"
                v.write(str.toArray())
            case _ => throw Exception()
        }
    }

    /* 将两个 ByteArrayStream 绑定到 ChainedInputStream */
    let chainedInputStream = ChainedInputStream(streamArr)
    let res = ArrayList<Byte>()
    let buffer = Array<Byte>(20, item: 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

    /* 将两个 ByteArrayStream 绑定到 MultiOutputStream */
    let streamArr = Array<OutputStream>(size, {_ => ByteArrayStream()})
    let multiOutputStream = MultiOutputStream(streamArr)

    /* 往 MultiOutputStream 写入数据，会同时写入绑定的两个 ByteArrayStream */
    multiOutputStream.write("test".toArray())

    /* 读取 ByteArrayStream 中数据，验证结果 */
    for (i in 0..size) {
        match (streamArr[i]) {
            case v: ByteArrayStream =>
                println(String.fromUtf8(v.readToEnd()))
            case _ => throw Exception()
        }
    }
}

运行结果

test
test

StringReader 示例

下面是 StringReader 从流中读取数据示例。

import std.io.*

main(): Unit {
    let arr1 = "012\n346789".toArray()
    let byteArrayStream = ByteArrayStream()
    byteArrayStream.write(arr1)
    let stringReader = StringReader(byteArrayStream)

    /* 读取一个字节 */
    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)
}

运行结果

StringWriter 示例

下面是 StringWriter 向流中写入数据示例。

import std.io.*

main(): Unit {
    let byteArrayStream = ByteArrayStream()
    let stringWriter = StringWriter(byteArrayStream)

    /* 写入字符串 */
    stringWriter.write("number")

    /* 写入字符串并自动转行 */
    stringWriter.writeln(" is:")

    /* 写入数字 */
    stringWriter.write(100.0f32)

    stringWriter.flush()

    println(String.fromUtf8(byteArrayStream.readToEnd()))
}

运行结果

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

功能：打印日志的通用函数，需指定日志级别。

参数：

level: LogLevel - 日志级别。
msg: String - 日志内容。

func setOutput(OutputStream)

func setOutput(output: OutputStream): Unit

功能：设置日志输出流，日志将被打印到该输出流。

参数：

output: OutputStream - 输出流。

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 实例，指定日志名称，日志打印级别和输出流。

参数：

name: String - 日志名称。
level: LogLevel - 日志级别。
output: OutputStream - 输出流。

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

功能：打印日志的通用函数，需指定日志级别。

参数：

level: LogLevel - 日志级别。
msg: String - 日志内容。

func setOutput(OutputStream)

public func setOutput(output: OutputStream): Unit

功能：设置输出流，日志信息将打印到该输出流中。

参数：

output: OutputStream - 输出流。

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
}

功能：该枚举类表示打印级别。

定义了日志打印的七个级别，级别从低到高分别为 OFF、ERROR、WARN、INFO、DEBUG、TRACE、ALL。

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 包提供常见的数学运算，常数定义，浮点数处理等功能。

包括了以下能力：

科学常数与类型常数定义；
浮点数的判断，规整；
常用的位运算；
通用的数学函数，如绝对值，三角函数，指数，对数计算；
最大公约数与最小公倍数。

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` 的对数。
max(Float16, Float16)	求两个数的最大值。
max(Float32, Float32)	求两个数的最大值。
max(Float64, Float64)	求两个数的最大值。
max(Int8, Int8)	求两个数的最大值。
max(Int16, Int16)	求两个数的最大值。
max(Int32, Int32)	求两个数的最大值。
max(Int64, Int64)	求两个数的最大值。
max(UInt8, UInt8)	求两个数的最大值。
max(UInt16, UInt16)	求两个数的最大值。
max(UInt32, UInt32)	求两个数的最大值。
max(UInt64, UInt64)	求两个数的最大值。
maxNaN(Float16, Float16)	求两个数的最大值。
maxNaN(Float32, Float32)	求两个数的最大值。
maxNaN(Float64, Float64)	求两个数的最大值。
min(Float16, Float16)	求两个数的最小值。
min(Float32, Float32)	求两个数的最小值。
min(Float64, Float64)	求两个数的最小值。
min(Int8, Int8)	求两个数的最小值。
min(Int16, Int16)	求两个数的最小值。
min(Int32, Int32)	求两个数的最小值。
min(Int64, Int64)	求两个数的最小值。
min(UInt8, UInt8)	求两个数的最小值。
min(UInt16, UInt16)	求两个数的最小值。
min(UInt32, UInt32)	求两个数的最小值。
min(UInt64, UInt64)	求两个数的最小值。
minNaN(Float16, Float16)	求两个数的最小值。
minNaN(Float32, Float32)	求两个数的最小值。
minNaN(Float64, Float64)	求两个数的最小值。
pow(Float32, Float32)	求浮点数 `base` 的 `exponent` 次幂。
pow(Float32, Int32)	求浮点数 `base` 的 `exponent` 次幂。
pow(Float64, Float64)	求浮点数 `base` 的 `exponent` 次幂。
pow(Float64, Int64)	求浮点数 `base` 的 `exponent` 次幂。
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)	计算双精度浮点数的双曲正切函数值。
throwIllegalArgumentException()	此函数用于抛出非法参数异常。
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、Max等。
Float16	拓展半精度浮点数以支持一些数学常数。
Float32	拓展单精度浮点数以支持一些数学常数。
Float64	拓展双精度浮点数以支持一些数学常数。
Int8	拓展 8 位有符号整数以支持一些数学常数。
Int16	拓展 16 位有符号整数以支持一些数学常数。
Int32	拓展 32 位有符号整数以支持一些数学常数。
Int64	拓展 64 位有符号整数以支持一些数学常数。
UInt8	拓展 8 位无符号整数以支持一些数学常数。
UInt16	拓展 16 位无符号整数以支持一些数学常数。
UInt32	拓展 32 位无符号整数以支持一些数学常数。
UInt64	拓展 64 位无符号整数以支持一些数学常数。
IntNative	拓展平台相关有符号整数以支持一些数学常数。
UIntNative	拓展平台相关无符号整数以支持一些数学常数。

函数

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

func acos(Float16)

public func acos(x: Float16): Float16

功能：计算半精度浮点数的反余弦函数值。

参数：

x: Float16 - 传入的半精度浮点数。-1.0 <= x <= 1.0。

返回值：

Float16 - 返回传入参数的反余弦函数值，单位为弧度。

异常：

IllegalArgumentException - 当参数 x 大于 1.0 或小于 -1.0 时，抛出异常。

示例：

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 - 返回传入参数的反余弦函数值，单位为弧度。

异常：

IllegalArgumentException - 当参数 x 大于 1.0 或小于 -1.0 时，抛出异常。

示例：

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 - 返回传入参数的反余弦函数值，单位为弧度。

异常：

IllegalArgumentException - 当参数 x 大于 1.0 或小于 -1.0 时，抛出异常。

示例：

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。

异常：

IllegalArgumentException - 当参数 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 - 返回传入参数的反双曲余弦函数值。

异常：

IllegalArgumentException - 当参数 x 小于 1.0 时，抛出异常。

示例：

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 - 返回传入参数的反双曲余弦函数值。

异常：

IllegalArgumentException - 当参数 x 小于 1.0 时，抛出异常。

示例：

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 - 返回传入参数的反正弦函数值，单位为弧度。

异常：

IllegalArgumentException - 当参数 x 大于 1.0 或小于 -1.0 时，抛出异常。

示例：

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 - 返回传入参数的反正弦函数值，单位为弧度。

异常：

IllegalArgumentException - 当参数 x 大于 1.0 或小于 -1.0 时，抛出异常。

示例：

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 - 返回传入参数的反正弦函数值，单位为弧度。

异常：

IllegalArgumentException - 当参数 x 大于 1.0 或小于 -1.0 时，抛出异常。

示例：

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 - 返回传入参数的反双曲正切函数值。

异常：

IllegalArgumentException - 当参数 x 大于等于 1.0 或小于等于 -1.0 时，抛出异常。

示例：

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 - 返回传入参数的反双曲正切函数值。

异常：

IllegalArgumentException - 当参数 x 大于等于 1.0 或小于等于 -1.0 时，抛出异常。

示例：

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 - 返回传入参数的反双曲正切函数值。

异常：

IllegalArgumentException - 当参数 x 大于等于 1.0 或小于等于 -1.0 时，抛出异常。

示例：

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 位有符号整数。

返回值：

Option<Int16> - 返回传入参数的绝对值的 Option 类型。

示例：

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 位有符号整数。

返回值：

Option<Int32> - 返回传入参数的绝对值的 Option 类型。

示例：

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 位有符号整数。

返回值：

Option<Int64> - 返回传入参数的绝对值的 Option 类型。

示例：

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 位有符号整数。

返回值：

Option<Int8> - 返回传入参数的绝对值的 Option 类型。

示例：

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 - 如果 v 在 min 与 max 之间则返回 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

参数：

v: Float32 - 传入一个浮点数。
min: Float32 - 指定的最小值。
max: Float32 - 指定的最大值。

返回值：

Float32 - 如果 v 在 min 与 max 之间则返回 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

参数：

v: Float64 - 传入一个浮点数。
min: Float64 - 指定的最小值。
max: Float64 - 指定的最大值。

返回值：

Float64 - 如果 v 在 min 与 max 之间则返回 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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

func lcm(Int16, Int16)

public func lcm(x: Int16, y: Int16): Int16

功能：求两个 16 位有符号整数的最小的非负的公倍数，当入参有 0 时才返回 0。

参数：

x: Int16 - 传入的需要计算最小公倍数的第一个整数。
y: Int16 - 传入的需要计算最小公倍数的第二个整数。

返回值：

Int16 - 返回两个整数的最小的非负的公倍数，当入参有 0 时才返回 0。

异常：

IllegalArgumentException - 当返回值超出 16 位有符号整数的最大值时抛出异常。

示例：

import std.math.lcm

main() {
    let x: Int16 = -15
    let y: Int16 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

func lcm(Int32, Int32)

public func lcm(x: Int32, y: Int32): Int32

功能：求两个 32 位有符号整数的最小的非负的公倍数，当入参有 0 时才返回 0。

参数：

x: Int32 - 传入的需要计算最小公倍数的第一个整数。
y: Int32 - 传入的需要计算最小公倍数的第二个整数。

返回值：

Int32 - 返回两个整数的最小的非负的公倍数，当入参有 0 时才返回 0。

异常：

IllegalArgumentException - 当返回值超出 32 位有符号整数的最大值时抛出异常。

示例：

import std.math.lcm

main() {
    let x: Int32 = -15
    let y: Int32 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

func lcm(Int64, Int64)

public func lcm(x: Int64, y: Int64): Int64

功能：求两个 64 位有符号整数的最小的非负的公倍数，当入参有 0 时才返回 0。

参数：

x: Int64 - 传入的需要计算最小公倍数的第一个整数。
y: Int64 - 传入的需要计算最小公倍数的第二个整数。

返回值：

Int64 - 返回两个整数的最小的非负的公倍数，当入参有 0 时才返回 0。

异常：

IllegalArgumentException - 当返回值超出 64 位有符号整数的最大值时抛出异常。

示例：

import std.math.lcm

main() {
    let x: Int64 = 15
    let y: Int64 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

func lcm(Int8, Int8)

public func lcm(x: Int8, y: Int8): Int8

功能：求两个 8 位有符号整数的最小的非负的公倍数，当入参有 0 时才返回 0。

参数：

x: Int8 - 传入的需要计算最小公倍数的第一个整数。
y: Int8 - 传入的需要计算最小公倍数的第二个整数。

返回值：

Int8 - 返回两个整数的最小的非负的公倍数，当入参有 0 时才返回 0。

异常：

IllegalArgumentException - 当返回值超出 8 位有符号整数的最大值时抛出异常。

示例：

import std.math.lcm

main() {
    let x: Int8 = 15
    let y: Int8= 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

func lcm(UInt16, UInt16)

public func lcm(x: UInt16, y: UInt16): UInt16

功能：求两个 16 位无符号整数的最小的非负的公倍数，当入参有 0 时才返回 0。

参数：

x: UInt16 - 传入的需要计算最小公倍数的第一个整数。
y: UInt16 - 传入的需要计算最小公倍数的第二个整数。

返回值：

UInt16 - 返回两个整数的最小的非负的公倍数，当入参有 0 时才返回 0。

异常：

IllegalArgumentException - 当返回值超出 16 位无符号整数的最大值时抛出异常。

示例：

import std.math.lcm

main() {
    let x: UInt16 = 15
    let y: UInt16 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

func lcm(UInt32, UInt32)

public func lcm(x: UInt32, y: UInt32): UInt32

功能：求两个 32 位无符号整数的最小的非负的公倍数，当入参有 0 时才返回 0。

参数：

x: UInt32 - 传入的需要计算最小公倍数的第一个整数。
y: UInt32 - 传入的需要计算最小公倍数的第二个整数。

返回值：

UInt32 - 返回两个整数的最小的非负的公倍数，当入参有 0 时才返回 0。

异常：

IllegalArgumentException - 当返回值超出 32 位无符号整数的最大值时抛出异常。

示例：

import std.math.lcm

main() {
    let x: UInt32 = 15
    let y: UInt32 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

func lcm(UInt64, UInt64)

public func lcm(x: UInt64, y: UInt64): UInt64

功能：求两个 64 位无符号整数的最小的非负的公倍数，当入参有 0 时才返回 0。

参数：

x: UInt64 - 传入的需要计算最小公倍数的第一个整数。
y: UInt64 - 传入的需要计算最小公倍数的第二个整数。

返回值：

UInt64 - 返回两个整数的最小的非负的公倍数，当入参有 0 时才返回 0。

异常：

IllegalArgumentException - 当返回值超出 64 位无符号整数的最大值时抛出异常。

示例：

import std.math.lcm

main() {
    let x: UInt64 = 15
    let y: UInt64 = 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

func lcm(UInt8, UInt8)

public func lcm(x: UInt8, y: UInt8): UInt8

功能：求两个 8 位无符号整数的最小的非负的公倍数，当入参有 0 时才返回 0。

参数：

x: UInt8 - 传入的需要计算最小公倍数的第一个整数。
y: UInt8 - 传入的需要计算最小公倍数的第二个整数。

返回值：

UInt8 - 返回两个整数的最小的非负的公倍数，当入参有 0 时才返回 0。

异常：

IllegalArgumentException - 当返回值超出 8 位无符号整数的最大值时抛出异常。

示例：

import std.math.lcm

main() {
    let x: UInt8 = 15
    let y: UInt8= 9
    let lcm = lcm(x, y)
    println(lcm)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

func log(Float16)

public func log(x: Float16): Float16

功能：求以 e 为底 x 的对数。

参数：

x: Float16 - 真数。真数需要大于 0。

返回值：

Float16 - 返回以 e 为底 x 的对数。

异常：

IllegalArgumentException - 当输入值不为正时，抛出异常。

示例：

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 的对数。

参数：

x: Float32 - 真数。真数需要大于 0。

返回值：

Float32 - 返回以 e 为底 x 的对数。

异常：

IllegalArgumentException - 当输入值不为正时，抛出异常。

示例：

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 的对数。

参数：

x: Float64 - 真数。真数需要大于 0。

返回值：

Float64 - 返回以 e 为底 x 的对数。

异常：

IllegalArgumentException - 当输入值不为正时，抛出异常。

示例：

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 的对数。

参数：

x: Float16 - 真数。真数需要大于 0。

返回值：

Float16 - 返回以 10 为底 x 的对数。

异常：

IllegalArgumentException - 当输入值不为正时，抛出异常。

示例：

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 的对数。

参数：

x: Float32 - 真数。真数需要大于 0。

返回值：

Float32 - 返回以 10 为底 x 的对数。

异常：

IllegalArgumentException - 当输入值不为正时，抛出异常。

示例：

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 的对数。

参数：

x: Float64 - 真数。真数需要大于 0。

返回值：

Float64 - 返回以 10 为底 x 的对数。

异常：

IllegalArgumentException - 当输入值不为正时，抛出异常。

示例：

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 的对数。

参数：

x: Float16 - 真数。真数需要大于 0。

返回值：

Float16 - 返回以 2 为底 x 的对数。

异常：

IllegalArgumentException - 当输入值不为正时，抛出异常。

示例：

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 的对数。

参数：

x: Float32 - 真数。真数需要大于 0。

返回值：

Float32 - 返回以 2 为底 x 的对数。

异常：

IllegalArgumentException - 当输入值不为正时，抛出异常。

示例：

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 的对数。

参数：

x: Float64 - 真数。真数需要大于 0。

返回值：

Float64 - 返回以 2 为底 x 的对数。

异常：

IllegalArgumentException - 当输入值不为正时，抛出异常。

示例：

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 的对数。

异常：

IllegalArgumentException - 当真数或底数不为正，或底数为 1 时，抛出异常。

示例：

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 的对数。

异常：

IllegalArgumentException - 当真数或底数不为正，或底数为 1 时，抛出异常。

示例：

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 的对数。

异常：

IllegalArgumentException - 当真数或底数不为正，或底数为 1 时，抛出异常。

示例：

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 max(Float16, Float16)

public func max(a: Float16, b: Float16): Float16

功能：求两个数的最大值。若入参有 NaN，则返回 NaN。

参数：

a: Float16 - 需要比较大小的第一个数。
b: Float16 - 需要比较大小的第二个数。

返回值：

Float16 - 返回两个数的最大值。若入参有 NaN，则返回 NaN。

示例：

import std.math.max

main() {
    let a: Float16 = 1.0
    let b: Float16 = 2.0
    let max = max(a, b)
    println(max)
}

运行结果:

2.000000

func max(Float32, Float32)

public func max(a: Float32, b: Float32): Float32

功能：求两个数的最大值。若入参有 NaN，则返回 NaN。

参数：

a: Float32 - 需要比较大小的第一个数。
b: Float32 - 需要比较大小的第二个数。

返回值：

Float32 - 返回两个数的最大值。若入参有 NaN，则返回 NaN。

示例：

import std.math.max

main() {
    let a: Float32 = 1.0
    let b: Float32 = 2.0
    let max = max(a, b)
    println(max)
}

运行结果:

2.000000

func max(Float64, Float64)

public func max(a: Float64, b: Float64): Float64

功能：求两个数的最大值。若入参有 NaN，则返回 NaN。

参数：

a: Float64 - 需要比较大小的第一个数。
b: Float64 - 需要比较大小的第二个数。

返回值：

Float64 - 返回两个数的最大值。若入参有 NaN，则返回 NaN。

示例：

import std.math.max

main() {
    let a: Float64 = 1.0
    let b: Float64 = 2.0
    let max = max(a, b)
    println(max)
}

运行结果:

2.000000

func max(Int16, Int16)

public func max(a: Int16, b: Int16): Int16

功能：求两个数的最大值。

参数：

a: Int16 - 需要比较大小的第一个数。
b: Int16 - 需要比较大小的第二个数。

返回值：

Int16 - 返回两个数的最大值。

示例：

import std.math.max

main() {
    let a: Int16 = -1
    let b: Int16 = 2
    let max = max(a, b)
    println(max)
}

运行结果:

func max(Int32, Int32)

public func max(a: Int32, b: Int32): Int32

功能：求两个数的最大值。

参数：

a: Int32 - 需要比较大小的第一个数。
b: Int32 - 需要比较大小的第二个数。

返回值：

Int32 - 返回两个数的最大值。

示例：

import std.math.max

main() {
    let a: Int32 = -1
    let b: Int32 = 2
    let max = max(a, b)
    println(max)
}

运行结果:

func max(Int64, Int64)

public func max(a: Int64, b: Int64): Int64

功能：求两个数的最大值。

参数：

a: Int64 - 需要比较大小的第一个数。
b: Int64 - 需要比较大小的第二个数。

返回值：

Int64 - 返回两个数的最大值。

示例：

import std.math.max

main() {
    let a: Int64 = -1
    let b: Int64 = 2
    let max = max(a, b)
    println(max)
}

运行结果:

func max(Int8, Int8)

public func max(a: Int8, b: Int8): Int8

功能：求两个数的最大值。

参数：

a: Int8 - 需要比较大小的第一个数。
b: Int8 - 需要比较大小的第二个数。

返回值：

Int8 - 返回两个数的最大值。

示例：

import std.math.max

main() {
    let a: Int8 = -1
    let b: Int8 = 2
    let max = max(a, b)
    println(max)
}

运行结果:

func max(UInt16, UInt16)

public func max(a: UInt16, b: UInt16): UInt16

功能：求两个数的最大值。

参数：

a: UInt16 - 需要比较大小的第一个数。
b: UInt16 - 需要比较大小的第二个数。

返回值：

UInt16 - 返回两个数的最大值。

示例：

import std.math.max

main() {
    let a: UInt16 = 1
    let b: UInt16 = 2
    let max = max(a, b)
    println(max)
}

运行结果:

func max(UInt32, UInt32)

public func max(a: UInt32, b: UInt32): UInt32

功能：求两个数的最大值。

参数：

a: UInt32 - 需要比较大小的第一个数。
b: UInt32 - 需要比较大小的第二个数。

返回值：

UInt32 - 返回两个数的最大值。

示例：

import std.math.max

main() {
    let a: UInt32 = 1
    let b: UInt32 = 2
    let max = max(a, b)
    println(max)
}

运行结果:

func max(UInt64, UInt64)

public func max(a: UInt64, b: UInt64): UInt64

功能：求两个数的最大值。

参数：

a: UInt64 - 需要比较大小的第一个数。
b: UInt64 - 需要比较大小的第二个数。

返回值：

UInt64 - 返回两个数的最大值。

示例：

import std.math.max

main() {
    let a: UInt64 = 1
    let b: UInt64 = 2
    let max = max(a, b)
    println(max)
}

运行结果:

func max(UInt8, UInt8)

public func max(a: UInt8, b: UInt8): UInt8

功能：求两个数的最大值。

参数：

a: UInt8 - 需要比较大小的第一个数。
b: UInt8 - 需要比较大小的第二个数。

返回值：

UInt8 - 返回两个数的最大值。

示例：

import std.math.max

main() {
    let a: UInt8 = 1
    let b: UInt8 = 2
    let max = max(a, b)
    println(max)
}

运行结果:

func maxNaN(Float16, Float16)

public func maxNaN(a: Float16, b: Float16): Float16

功能：求两个数的最大值。maxNaN 仅支持浮点数，若入参有 NaN，则返回 NaN。

参数：

a: Float16 - 需要比较大小的第一个数。
b: Float16 - 需要比较大小的第二个数。

返回值：

Float16 - 返回两个数的最大值。若入参有 NaN，则返回 NaN。

示例：

import std.math.maxNaN

main() {
    let a: Float16 = 1.0
    let b: Float16 = 2.0
    let maxNaN = maxNaN(a, b)
    println(maxNaN)
}

运行结果:

2.000000

func maxNaN(Float32, Float32)

public func maxNaN(a: Float32, b: Float32): Float32

功能：求两个数的最大值。maxNaN 仅支持浮点数，若入参有 NaN，则返回 NaN。

参数：

a: Float32 - 需要比较大小的第一个数。
b: Float32 - 需要比较大小的第二个数。

返回值：

Float32 - 返回两个数的最大值。若入参有 NaN，则返回 NaN。

示例：

import std.math.maxNaN

main() {
    let a: Float32 = 1.0
    let b: Float32 = 2.0
    let maxNaN = maxNaN(a, b)
    println(maxNaN)
}

运行结果:

2.000000

func maxNaN(Float64, Float64)

public func maxNaN(a: Float64, b: Float64): Float64

功能：求两个数的最大值。maxNaN 仅支持浮点数，若入参有 NaN，则返回 NaN。

参数：

a: Float64 - 需要比较大小的第一个数。
b: Float64 - 需要比较大小的第二个数。

返回值：

Float64 - 返回两个数的最大值。若入参有 NaN，则返回 NaN。

示例：

import std.math.maxNaN

main() {
    let a: Float64 = 1.0
    let b: Float64 = 2.0
    let maxNaN = maxNaN(a, b)
    println(maxNaN)
}

运行结果:

2.000000

func min(Float16, Float16)

public func min(a: Float16, b: Float16): Float16

功能：求两个数的最小值。若入参有 NaN，则返回 NaN。

参数：

a: Float16 - 需要比较大小的第一个数。
b: Float16 - 需要比较大小的第二个数。

返回值：

Float16 - 返回两个数的最小值。若入参有 NaN，则返回 NaN。

示例：

import std.math.min

main() {
    let a: Float16 = 1.0
    let b: Float16 = 2.0
    let min = min(a, b)
    println(min)
}

运行结果:

1.000000

func min(Float32, Float32)

public func min(a: Float32, b: Float32): Float32

功能：求两个数的最小值。若入参有 NaN，则返回 NaN。

参数：

a: Float32 - 需要比较大小的第一个数。
b: Float32 - 需要比较大小的第二个数。

返回值：

Float32 - 返回两个数的最小值。若入参有 NaN，则返回 NaN。

示例：

import std.math.min

main() {
    let a: Float32 = 1.0
    let b: Float32 = 2.0
    let min = min(a, b)
    println(min)
}

运行结果:

1.000000

func min(Float64, Float64)

public func min(a: Float64, b: Float64): Float64

功能：求两个数的最小值。若入参有 NaN，则返回 NaN。

参数：

a: Float64 - 需要比较大小的第一个数。
b: Float64 - 需要比较大小的第二个数。

返回值：

Float64 - 返回两个数的最小值。若入参有 NaN，则返回 NaN。

示例：

import std.math.min

main() {
    let a: Float64 = 1.0
    let b: Float64 = 2.0
    let min = min(a, b)
    println(min)
}

运行结果:

1.000000

func min(Int16, Int16)

public func min(a: Int16, b: Int16): Int16

功能：求两个数的最小值。

参数：

a: Int16 - 需要比较大小的第一个数。
b: Int16 - 需要比较大小的第一个数。

返回值：

Int16 - 返回两个数的最小值。

示例：

import std.math.min

main() {
    let a: Int16 = -1
    let b: Int16 = 2
    let min = min(a, b)
    println(min)
}

运行结果:

-1

func min(Int32, Int32)

public func min(a: Int32, b: Int32): Int32

功能：求两个数的最小值。

参数：

a: Int32 - 需要比较大小的第一个数。
b: Int32 - 需要比较大小的第一个数。

返回值：

Int32 - 返回两个数的最小值。

示例：

import std.math.min

main() {
    let a: Int32 = -1
    let b: Int32 = 2
    let min = min(a, b)
    println(min)
}

运行结果:

-1

func min(Int64, Int64)

public func min(a: Int64, b: Int64): Int64

功能：求两个数的最小值。

参数：

a: Int64 - 需要比较大小的第一个数。
b: Int64 - 需要比较大小的第一个数。

返回值：

Int64 - 返回两个数的最小值。

示例：

import std.math.min

main() {
    let a: Int64 = -1
    let b: Int64 = 2
    let min = min(a, b)
    println(min)
}

运行结果:

-1

func min(Int8, Int8)

public func min(a: Int8, b: Int8): Int8

功能：求两个数的最小值。

参数：

a: Int8 - 需要比较大小的第一个数。
b: Int8 - 需要比较大小的第一个数。

返回值：

Int8 - 返回两个数的最小值。

示例：

import std.math.min

main() {
    let a: Int8 = -1
    let b: Int8 = 2
    let min = min(a, b)
    println(min)
}

运行结果:

-1

func min(UInt16, UInt16)

public func min(a: UInt16, b: UInt16): UInt16

功能：求两个数的最小值。

参数：

a: UInt16 - 需要比较大小的第一个数。
b: UInt16 - 需要比较大小的第一个数。

返回值：

UInt16 - 返回两个数的最小值。

示例：

import std.math.min

main() {
    let a: UInt16 = 1
    let b: UInt16 = 2
    let min = min(a, b)
    println(min)
}

运行结果:

func min(UInt32, UInt32)

public func min(a: UInt32, b: UInt32): UInt32

功能：求两个数的最小值。

参数：

a: UInt32 - 需要比较大小的第一个数。
b: UInt32 - 需要比较大小的第一个数。

返回值：

UInt32 - 返回两个数的最小值。

示例：

import std.math.min

main() {
    let a: UInt32 = 1
    let b: UInt32 = 2
    let min = min(a, b)
    println(min)
}

运行结果:

func min(UInt64, UInt64)

public func min(a: UInt64, b: UInt64): UInt64

功能：求两个数的最小值。

参数：

a: UInt64 - 需要比较大小的第一个数。
b: UInt64 - 需要比较大小的第一个数。

返回值：

UInt64 - 返回两个数的最小值。

示例：

import std.math.min

main() {
    let a: UInt64 = 1
    let b: UInt64 = 2
    let min = min(a, b)
    println(min)
}

运行结果:

func min(UInt8, UInt8)

public func min(a: UInt8, b: UInt8): UInt8

功能：求两个数的最小值。

参数：

a: UInt8 - 需要比较大小的第一个数。
b: UInt8 - 需要比较大小的第一个数。

返回值：

UInt8 - 返回两个数的最小值。

示例：

import std.math.min

main() {
    let a: UInt8 = 1
    let b: UInt8 = 2
    let min = min(a, b)
    println(min)
}

运行结果:

func minNaN(Float16, Float16)

public func minNaN(a: Float16, b: Float16): Float16

功能：求两个数的最小值。minNaN 仅支持浮点数，若入参有 NaN，则返回 NaN。

参数：

a: Float16 - 需要比较大小的第一个数。
b: Float16 - 需要比较大小的第二个数。

返回值：

Float16 - 返回两个数的最小值。若入参有 NaN，则返回 NaN。

示例：

import std.math.minNaN

main() {
    let a: Float16 = 1.0
    let b: Float16 = 2.0
    let minNaN = minNaN(a, b)
    println(minNaN)
}

运行结果:

1.000000

func minNaN(Float32, Float32)

public func minNaN(a: Float32, b: Float32): Float32

功能：求两个数的最小值。minNaN 仅支持浮点数，若入参有 NaN，则返回 NaN。

参数：

a: Float32 - 需要比较大小的第一个数。
b: Float32 - 需要比较大小的第二个数。

返回值：

Float32 - 返回两个数的最小值。若入参有 NaN，则返回 NaN。

示例：

import std.math.minNaN

main() {
    let a: Float32 = 1.0
    let b: Float32 = 2.0
    let minNaN = minNaN(a, b)
    println(minNaN)
}

运行结果:

1.000000

func minNaN(Float64, Float64)

public func minNaN(a: Float64, b: Float64): Float64

功能：求两个数的最小值。minNaN 仅支持浮点数，若入参有 NaN，则返回 NaN。

参数：

a: Float64 - 需要比较大小的第一个数。
b: Float64 - 需要比较大小的第二个数。

返回值：

Float64 - 返回两个数的最小值。若入参有 NaN，则返回 NaN。

示例：

import std.math.minNaN

main() {
    let a: Float64 = 1.0
    let b: Float64 = 2.0
    let minNaN = minNaN(a, b)
    println(minNaN)
}

运行结果:

1.000000

func pow(Float32, Float32)

public func pow(base: Float32, exponent: Float32): Float32

功能：求浮点数 base 的 exponent 次幂。

参数：

base: Float32 - 底数。
exponent: Float32 - 指数。

返回值：

Float32 - 返回传入浮点数 base 的 exponent 次幂。如果值不存在，则返回 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

功能：求浮点数 base 的 exponent 次幂。

参数：

base: Float32 - 底数。
exponent: Int32 - 指数。

返回值：

Float32 - 返回传入浮点数 base 的 exponent 次幂。

示例：

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

功能：求浮点数 base 的 exponent 次幂。

参数：

base: Float64 - 底数。
exponent: Float64 - 指数。

返回值：

Float64 - 返回传入浮点数 base 的 exponent 次幂。如果值不存在，则返回 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

功能：求浮点数 base 的 exponent 次幂。

参数：

base: Float64 - 底数。
exponent: Int64 - 指数。

返回值：

Float64 - 返回传入浮点数 base 的 exponent 次幂。

示例：

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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 - 返回传入的浮点数的算术平方根。

异常：

IllegalArgumentException - 当参数为负数时，抛出异常。

示例：

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 - 返回传入的浮点数的算术平方根。

异常：

IllegalArgumentException - 当参数为负数时，抛出异常。

示例：

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 - 返回传入的浮点数的算术平方根。

异常：

IllegalArgumentException - 当参数为负数时，抛出异常。

示例：

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 throwIllegalArgumentException()

public func throwIllegalArgumentException(): Int64

功能：此函数用于抛出非法参数异常。

返回值：

Int64 - 返回 0。

异常：

IllegalArgumentException - 当函数被调用时，抛出异常。

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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

接口

interface MathExtension

public interface MathExtension

功能：为了导出 prop 而作辅助接口，辅助导出 Max，Min 属性，浮点数额外导出 NaN，Inf，PI，E，MinDenormal，MinNormal 属性和 isInf，isNaN，isNormal 接口。该辅助接口内部为空。

extend Float16 <: MathExtension

extend Float16 <: MathExtension

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

static prop E

public static prop E: Float16

功能：获取半精度浮点数的自然常数。

类型：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 prop PI

public static prop PI: 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 Float32 <: MathExtension

extend Float32 <: MathExtension

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

static prop E

public static prop E: Float32

功能：获取单精度浮点数的自然常数。

类型：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 prop PI

public static prop PI: 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 Float64 <: MathExtension

extend Float64 <: MathExtension

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

static prop E

public static prop E: Float64

功能：获取双精度浮点数的自然常数。

类型：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 prop PI

public static prop PI: 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 Int16 <: MathExtension

extend Int16 <: MathExtension

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

static prop Max

public static prop Max: Int16

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

类型：Int16

static prop Min

public static prop Min: Int16

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

类型：Int16

extend Int32 <: MathExtension

extend Int32 <: MathExtension

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

static prop Max

public static prop Max: Int32

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

类型：Int32

static prop Min

public static prop Min: Int32

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

类型：Int32

extend Int64 <: MathExtension

extend Int64 <: MathExtension

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

static prop Max

public static prop Max: Int64

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

类型：Int64

static prop Min

public static prop Min: Int64

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

类型：Int64

extend Int8 <: MathExtension

extend Int8 <: MathExtension

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

static prop Max

public static prop Max: Int8

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

类型：Int8

static prop Min

public static prop Min: Int8

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

类型：Int8

extend IntNative <: MathExtension

extend IntNative <: MathExtension

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

static prop Max

public static prop Max: IntNative

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

类型：IntNative

static prop Min

public static prop Min: IntNative

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

类型：IntNative

extend UInt16 <: MathExtension

extend UInt16 <: MathExtension

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

static prop Max

public static prop Max: UInt16

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

类型：UInt16

static prop Min

public static prop Min: UInt16

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

类型：UInt16

extend UInt32 <: MathExtension

extend UInt32 <: MathExtension

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

static prop Max

public static prop Max: UInt32

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

类型：UInt32

static prop Min

public static prop Min: UInt32

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

类型：UInt32

extend UInt64 <: MathExtension

extend UInt64 <: MathExtension

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

static prop Max

public static prop Max: UInt64

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

类型：UInt64

static prop Min

public static prop Min: UInt64

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

类型：UInt64

extend UInt8 <: MathExtension

extend UInt8 <: MathExtension

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

static prop Max

public static prop Max: UInt8

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

类型：UInt8

static prop Min

public static prop Min: UInt8

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

类型：UInt8

extend UIntNative <: MathExtension

extend UIntNative <: MathExtension

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

static prop Max

public static prop Max: UIntNative

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

类型：类型：UIntNative

static prop Min

public static prop Min: UIntNative

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

类型：UIntNative

数学基础运算示例

import std.math.clamp
import std.math.gcd
import std.math.lcm
import std.math.rotate
import std.math.numeric.DecimalContext

// 范围截断示例
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 包对基础类型可表达范围之外提供扩展能力。

例如：

支持大整数(BigInt)；
支持高精度十进制数(Decimal)类型；
提供常见的数学运算能力包括高精度运算规则。

API 列表

函数

函数名	功能
abs(BigInt)	求一个 `BigInt` 的绝对值。
sqrt(BigInt)	求 `BigInt` 的算数平方根，向下取整。
gcd(BigInt, BigInt)	求两个 `BigInt` 的最大公约数。总是返回非负数（相当于绝对值的最大公约数）。
lcm(BigInt, BigInt)	求两个 `BigInt` 的的最小公倍数。除了入参有 0 时返回 0 外，总是返回正数（相当于绝对值的最小公倍数）。
max(BigInt, BigInt)	计算并返回两个 `BigInt` 中较大的那个。
min(BigInt, BigInt)	计算并返回两个 `BigInt` 中较小的那个。
countOne(BigInt)	计算并返回入参 `BigInt` 的二进制补码中 1 的个数。

枚举

枚举	功能
RoundingMode	舍入规则枚举类，共包含 6 中舍入规则。除包含 IEEE 754 浮点数规定约定的 5 种舍入规则外，提供使用较多的 “四舍五入” 舍入规则。
OverflowStrategy	溢出策略枚举类，共包含 3 种溢出策略。`BigInt` 类型、`Decimal` 类型转换为整数类型时，允许指定不同的溢出处理策略。

结构体

结构体	功能
BigInt	BigInt 定义为任意精度（二进制）的有符号整数。仓颉的 struct BigInt 用于任意精度有符号整数的计算，类型转换等。
DecimalContext	DecimalContext 对象作用于用户对 Decimal 操作过程中，对生成结果指定上下文，设定结果的精度与对应舍入规则。
Decimal	Decimal 用于表示任意精度的有符号的十进制数。允许操作过程指定上下文，指定结果精度及舍入规则。提供基础类型 (Int、UInt、String、Float等) 与 BigInt 类型互相转换能力，支持 Decimal 对象基本属性查询等能力，支持基础数学运算操作，提供对象比较、hash、字符串打印等基础能力。

函数

func abs(BigInt)

public func abs(i: BigInt): BigInt

功能：求一个 BigInt 的绝对值。

参数：

i: BigInt - 需要计算绝对值的 BigInt。

返回值：

BigInt - 返回入参 BigInt 的绝对值。

示例：

import std.math.numeric.*

main() {
    let n: BigInt = BigInt(-23)
    let abs = abs(n)
    println(abs)
}

运行结果:

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)
}

运行结果:

func gcd(BigInt, BigInt)

public func gcd(i1: BigInt, i2: BigInt): BigInt

功能：求两个 BigInt 的最大公约数。总是返回非负数（相当于绝对值的最大公约数）。

参数：

i1: BigInt - 需要计算最大公约数的第一个入参。
i2: BigInt - 需要计算最大公约数的第二个入参。

返回值：

BigInt - 返回 i1 和 i2 的最大公约数，总是返回非负数。

示例：

import std.math.numeric.*

main() {
    let i1: BigInt = BigInt(-36)
    let i2: BigInt = BigInt(48)
    let gcd = gcd(i1, i2)
    println(gcd)
}

运行结果:

func lcm(BigInt, BigInt)

public func lcm(i1: BigInt, i2: BigInt): BigInt

功能：求两个 BigInt 的的最小公倍数。除了入参有 0 时返回 0 外，总是返回正数（相当于绝对值的最小公倍数）。

参数：

i1: BigInt - 需要计算最小公倍数的第一个入参。
i2: BigInt - 需要计算最小公倍数的第二个入参。

返回值：

BigInt - 返回 i1 和 i2 的最小公倍数，当入参有 0 时返回 0，其余情况返回正数。

示例：

import std.math.numeric.*

main() {
    let i1: BigInt = BigInt(-36)
    let i2: BigInt = BigInt(48)
    let lcm = lcm(i1, i2)
    println(lcm)
}

运行结果:

func max(BigInt, BigInt)

public func max(i1: BigInt, i2: BigInt): BigInt

功能：计算并返回两个 BigInt 中较大的那个。

参数：

i1: BigInt - 需要比较的 BigInt。
i2: BigInt - 需要比较的 BigInt。

返回值：

BigInt - 返回 i1，i2 中较大的 BigInt。

示例：

import std.math.numeric.*

main() {
    let i1: BigInt = BigInt(-36)
    let i2: BigInt = BigInt(48)
    let max = max(i1, i2)
    println(max)
}

运行结果:

func min(BigInt, BigInt)

public func min(i1: BigInt, i2: BigInt): BigInt

功能：计算并返回两个 BigInt 中较小的那个。

参数：

i1: BigInt - 需要比较的 BigInt。
i2: BigInt - 需要比较的 BigInt。

返回值：

BigInt - 返回 i1，i2 中较小的 BigInt。

示例：

import std.math.numeric.*

main() {
    let i1: BigInt = BigInt(-36)
    let i2: BigInt = BigInt(48)
    let min = min(i1, i2)
    println(min)
}

运行结果:

-36

func sqrt(BigInt)

public func sqrt(i: BigInt): BigInt

功能：求 BigInt 的算数平方根，向下取整。

参数：

i: BigInt - 需要计算算数平方根的 BigInt，入参需要非负。

返回值：

BigInt - 返回入参 BigInt 的算数平方根，向下取整。

异常：

IllegalArgumentException - 如果入参为负数，则抛此异常。

示例：

import std.math.numeric.*

main() {
    let n: BigInt = BigInt(23)
    let sqrt = sqrt(n)
    println(sqrt)
}

运行结果:

枚举

enum OverflowStrategy

public enum OverflowStrategy {
    | saturating
    | throwing
    | wrapping
}

溢出策略枚举类，共包含 3 种溢出策略。BigInt 类型、Decimal 类型转换为整数类型时，允许指定不同的溢出处理策略。

saturating

saturating

功能：出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

throwing

throwing

功能：出现溢出，抛出异常。

wrapping

wrapping

功能：出现溢出，高位截断。

enum RoundingMode

public enum RoundingMode {
    | CEILING
    | DOWN
    | FLOOR
    | HALF_EVEN
    | HALF_UP
    | UP
}

舍入规则枚举类，共包含 6 中舍入规则。除包含 IEEE 754 浮点数规定约定的 5 种舍入规则外，提供使用较多的 “四舍五入” 舍入规则。

十进制数	UP	DOWN	CEILING	FLOOR	HALF_UP	HALF_EVEN
7.5	8	7	8	7	8	8
4.5	5	4	5	4	5	4
-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

功能：向远离零的方向舍入。

结构体

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> - 大端二进制补码数组，数组长度不能为空。

异常：

IllegalArgumentException - 当传入空数组时，抛此异常。

init(Bool, Array<Byte>)

public init(sign: Bool, magnitude: Array<Byte>)

功能：通过符号位和真值的绝对值构建一个 BigInt 结构体。视空数组为 0。

参数：

sign: Bool - 符号。true 表示非负数，false 表示负数。
magnitude: Array<Byte> - 真值绝对值的二进制原码。

异常：

IllegalArgumentException - 当 sign 为 false 且传入的数组为 0 时，抛此异常。

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 - 指定的随机数种子。

异常：

IllegalArgumentException - 如果指定的 bit 长度小于等于 0，则抛此异常。

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 结构体。

参数：

n: UIntNative - 平台相关无符号整数。

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 - 返回生成的随机素数。

异常：

IllegalArgumentException - 如果指定的 bit 长度小于等于 1，则抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let randomProbablePrime = BigInt.randomProbablePrime(6, 3)
    println(randomProbablePrime)
}

运行结果:

func clearBit(Int64)

public func clearBit(index: Int64): BigInt

功能：通过将指定索引位置的 bit 修改为 0 来构造一个新 BigInt。

参数：

index: Int64 - 需要设置的 bit 位置的索引。index 需要大于等于 0。

返回值：

BigInt - 一个新的 BigInt，它是将原 BigInt 的 index 处的 bit 改为 0 的产物。

异常：

IllegalArgumentException - 如果入参 index 小于 0，则抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1024)
    let clearBit = bigInt.clearBit(10)
    println(clearBit)
}

运行结果:

func compare(BigInt)

public func compare(that: BigInt): Ordering

功能：判断 BigInt 与另一个 BigInt 的关系。

参数：

that: BigInt - 另一个 BigInt。

返回值：

Ordering - 返回此 BigInt 与另一个 BigInt 的关系。如果等于，返回 Ordering.EQ；如果小于，返回 Ordering.LT；如果大于，返回 Ordering.GT。

func divAndMod(BigInt)

public func divAndMod(that: BigInt): (BigInt, BigInt)

功能：BigInt 的除法运算。

与另一个 BigInt 相除，返回商和模。此除法运算的行为与基础类型保持一致，即商向靠近 0 的方向取整，模的符号与被除数保持一致。

参数：

that: BigInt - 除数。除数不得为 0。

返回值：

(BigInt, BigInt) - 商和模。

异常：

ArithmeticException - 除数为 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 翻转后的产物。

异常：

IllegalArgumentException - 如果入参 index 小于 0，则抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1024)
    let flipBit = bigInt.flipBit(10)
    println(flipBit)
}

运行结果:

func hashCode()

public func hashCode(): Int64

功能：计算并返回此 BigInt 的哈希值。

返回值：

Int64 - 返回此 BigInt 的哈希值。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1024)
    let hashCode = bigInt.hashCode()
    println(hashCode)
}

运行结果:

func isProbablePrime(UInt64)

public func isProbablePrime(certainty: UInt64): Bool

功能：判断一个数是不是素数。

说明：

该函数使用了 Miller-Rabin 测试算法，此算法的准确率会随着 certainty 参数的增加而增加。如果该数是素数，那么 Miller-Rabin 测试必定返回 true；如果该数是合数（期待返回 false），那么会有低于 1/4^certainty 概率返回 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)
}

运行结果:

func modInverse(BigInt)

public func modInverse(that: BigInt): BigInt

功能：求模逆元。

模逆元 r 满足 $(this * r) % that == 1$。显然，this 和 that 必须互质。当 that 为正负 1 时，结果总是 0。

参数：

that: BigInt - 另外一个 BigInt。入参不得为 0，且需要与 this 互质。

返回值：

BigInt - 返回模逆元。

异常：

IllegalArgumentException - 当 this 和 that 不互质或 that 为 0 时，抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let modInverse = bigInt.modInverse(that)
    println(modInverse)
}

运行结果:

func modPow

public func modPow(n: BigInt, m!: ?BigInt = None): BigInt

功能：计算此 BigInt 的 n 次幂模 m 的结果，并返回。

模的规则与基础类型一致，即模的符号与被除数保持一致。

参数：

n: BigInt - 指数，必须为非负数。
m!: ?BigInt - 除数，此入参不得为 0。

返回值：

BigInt - 乘方后取模的运算结果。

异常：

ArithmeticException - 除数为 0 抛此异常。
IllegalArgumentException - 指数为负数时抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(2)
    let n = BigInt(10)
    let modPow = bigInt.modPow(n)
    println(modPow)
}

运行结果:

func quo(BigInt)

public func quo(that: BigInt): BigInt

功能：BigInt 的除法运算。

与另一个 BigInt 相除，返回结果。此除法运算的行为与运算符重载函数区别于，如果被除数为负数，此函数的结果向着远离 0 的方向取整，保证余数大于等于 0。

参数：

that: BigInt - 除数。除数不得为 0。

返回值：

BigInt - 一个新 BigInt，它是此 BigInt 与另外一个 BigInt 相除后的结果

异常：

ArithmeticException - 除数为 0 抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let quo = bigInt.quo(that)
    println(quo)
}

运行结果:

func quoAndRem(BigInt)

public func quoAndRem(that: BigInt): (BigInt, BigInt)

功能：BigInt 的除法运算。

与另一个 BigInt 相除，返回商和余数。此除法运算的行为与 divAndMod 函数区别于，如果被除数为负数，此函数的结果向着远离 0 的方向取整，保证余数总是大于等于 0。

参数：

that: BigInt - 除数。除数不得为 0。

返回值：

(BigInt, BigInt) - 商和余数。

异常：

ArithmeticException - 除数为 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。

返回值：

BigInt - 一个新 BigInt，它是此 BigInt 与另外一个 BigInt 相除后的余数。

异常：

ArithmeticException - 除数为 0 抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let rem = bigInt.rem(that)
    println(rem)
}

运行结果:

func setBit(Int64)

public func setBit(index: Int64): BigInt

功能：通过将指定索引位置的 bit 修改为 1 来构造一个新 BigInt。

参数：

index: Int64 - 需要设置的 bit 位置的索引。index 需要大于等于 0。

返回值：

BigInt - 一个新的 BigInt，它是将原 BigInt index 处的 bit 改为 1 的产物。

异常：

IllegalArgumentException - 如果入参 index 小于 0，则抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(0)
    let setBit = bigInt.setBit(10)
    println(setBit)
}

运行结果:

func testBit(Int64)

public func testBit(index: Int64): Bool

功能：判断指定位置的 bit 信息，如果指定位置的 bit 为 0，则返回 false；为 1，则返回 true。

参数：

index: Int64 - 需要知道的 bit 的索引。index 需要大于等于 0。

返回值：

Bool - 指定位置的 bit 信息。

异常：

IllegalArgumentException - 如果入参 index 小于 0，则抛此异常。

示例：

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）。

返回值：

Array<Byte> - 返回此 BigInt 的大端补码字节数组。

示例：

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 值。

返回值：

Int16 - 返回转换后的 Int16 值。

异常：

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)
}

运行结果:

func toInt32(OverflowStrategy)

public func toInt32(overflowHandling!: OverflowStrategy = throwing): Int32

功能：将当前 BigInt 对象转化为 Int32 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

Int32 - 返回转换后的 Int32 值。

异常：

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)
}

运行结果:

func toInt64(OverflowStrategy)

public func toInt64(overflowHandling!: OverflowStrategy = throwing): Int64

功能：将当前 BigInt 对象转化为 Int64 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

Int64 - 返回转换后的 Int64 值。

异常：

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)
}

运行结果:

func toInt8(OverflowStrategy)

public func toInt8(overflowHandling!: OverflowStrategy = throwing): Int8

功能：将当前 BigInt 对象转化为 Int8 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

Int8 - 返回转换后的 Int8 值。

异常：

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)
}

运行结果:

func toIntNative(OverflowStrategy)

public func toIntNative(overflowHandling!: OverflowStrategy = throwing): IntNative

功能：将当前 BigInt 对象转化为 IntNative 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

IntNative - 返回转换后的 IntNative 值。

异常：

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)
}

运行结果:

func toString()

public func toString(): String

功能：计算并返回此 BigInt 的十进制字符串表示。

返回值：

String - 返回此 BigInt 的十进制字符串。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(0x400)
    let toString = bigInt.toString()
    println(toString)
}

运行结果:

func toString(Int64)

public func toString(base: Int64): String

功能：计算并返回此 BigInt 的任意进制字符串表示。

参数：

base: Int64 - 进制。字符串所表示的进制，范围为 [2, 36]。

返回值：

String - 返回此 BigInt 的 base 进制字符串。

示例：

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 值。

返回值：

UInt16 - 返回转换后的 UInt16 值。

异常：

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)
}

运行结果:

func toUInt32(OverflowStrategy)

public func toUInt32(overflowHandling!: OverflowStrategy = throwing): UInt32

功能：将当前 BigInt 对象转化为 UInt32 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

UInt32 - 返回转换后的 UInt32 值。

异常：

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)
}

运行结果:

func toUInt64(OverflowStrategy)

public func toUInt64(overflowHandling!: OverflowStrategy = throwing): UInt64

功能：将当前 BigInt 对象转化为 UInt64 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

UInt64 - 返回转换后的 UInt64 值。

异常：

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)
}

运行结果:

func toUInt8(OverflowStrategy)

public func toUInt8(overflowHandling!: OverflowStrategy = throwing): UInt8

功能：将当前 BigInt 对象转化为 UInt8 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

UInt8 - 返回转换后的 UInt8 值。

异常：

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 值。

返回值：

UIntNative - 返回转换后的 UInt64 值。

异常：

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)
}

运行结果:

operator func !()

public operator func !(): BigInt

功能：按位非。将操作数中的二进制位 0 变 1，1 变 0。

返回值：

BigInt - 返回此 BigInt 按位非的结果。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let no = !bigInt
    println(no)
}

运行结果:

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 %(BigInt)

public operator func %(that: BigInt): BigInt

功能：BigInt 的模运算。

取模运算的行为与基础类型保持一致，即符号与被除数保持一致。

参数：

that: BigInt - 除数。除数不得为 0。

返回值：

BigInt - 一个新 BigInt，它是此 BigInt 与另外一个 BigInt 相模后的结果。

异常：

ArithmeticException - 除数为 0 抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-23456789123456789")
    let that = BigInt("-23456789123456789")
    let mod = bigInt % that
    println(mod)
}

运行结果:

operator func &(BigInt)

public operator func &(that: BigInt): BigInt

功能：按位与。其功能是参与运算的两数各对应的二进位相与。只有对应的两个二进位都为 1 时，结果位才为 1。

参数：

that: BigInt - 按位与运算的另外一个 BigInt。

返回值：

BigInt - 返回与另一个 BigInt 的按位与的结果。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("8")
    let that = BigInt("7")
    let and = bigInt & that
    println(and)
}

运行结果:

operator func *(BigInt)

public operator func *(that: BigInt): BigInt

功能：BigInt 乘法。

参数：

that: BigInt - 乘数。

返回值：

BigInt - 一个新 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 次幂。

参数：

n: UInt64 - 指数。

返回值：

BigInt - 幂运算结果。

示例：

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 加法。

参数：

that: BigInt - 加数。

返回值：

BigInt - 一个新 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 的相反数。

返回值：

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 减法。

参数：

that: BigInt - 减数。

返回值：

BigInt - 一个新 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

功能：小于比较运算。

参数：

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 <<(Int64)

public operator func <<(n: Int64): BigInt

功能：左移运算。

参数：

n: Int64 - 左移 n 位，n 需要大于等于 0。

返回值：

BigInt - 返回此 BigInt 左移 n 位的结果。

异常：

ArithmeticException - 入参小于 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

功能：判等运算。

参数：

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

功能：大于比较运算。

参数：

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 >=(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。

返回值：

BigInt - 返回此 BigInt 右移 n 位的结果。

异常：

ArithmeticException - 入参小于 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。

返回值：

BigInt - 一个新 BigInt，它是此 BigInt 与另外一个 BigInt 相除后的结果。

异常：

ArithmeticException - 除数为 0 抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-23456789123456789")
    let that = BigInt("-23456789123456789")
    let div = bigInt / that
    println(div)
}

运行结果:

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。

参数：

that: BigInt - 按位或运算的另外一个 BigInt。

返回值：

BigInt - 返回与另一个 BigInt 的按位或的结果。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("8")
    let that = BigInt("7")
    let or = bigInt | that
    println(or)
}

运行结果:

struct Decimal

public struct Decimal <: Comparable<Decimal> & Hashable & ToString

功能：Decimal 用于表示任意精度的有符号的十进制数。允许操作过程指定上下文，指定结果精度及舍入规则。提供基础类型 (Int、UInt、String、Float等) 与 BigInt 类型互相转换能力，支持 Decimal 对象基本属性查询等能力，支持基础数学运算操作，提供对象比较、hash、字符串打印等基础能力。

static let defaultDecimalContext

public static let defaultDecimalContext: DecimalContext

功能：默认上下文，精度值为 0，舍入规则为 “银行家舍入”。即无精度限制，保留操作结果实际精度，在操作结果为无限小数场景下，默认遵循 IEEE 754-2019 decimal128 规则，精度保留 34 位 “银行家” 规则舍入。

返回值：DecimalContext 默认值

类型：DecimalContext

prop precision

public prop precision: Int64

功能：获取 Decimal 精度值，即无标度整数部分十进制有效数字位数，非负数。

类型：Int64

prop scale

public prop scale: Int32

功能：获取 Decimal 标度值。

类型：Int32

prop sign

public prop sign: Int64

功能：获取 Decimal 实例符号值。

Decimal 值大于 0，返回 1；
Decimal 值等于 0，返回 0；
Decimal 值小于 0，返回 -1。

类型：Int64

prop value

public prop value: BigInt

功能：获取 Decimal 无标度整数值，BigInt 承载。

类型：BigInt

init(BigInt, Int32, DecimalContext)

public init(val: BigInt, scale: Int32, ctx!: DecimalContext = defaultDecimalContext)

功能：通过有符号大整数 BigInt 和标度值构建 Deciaml 结构体。

允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

val: BigInt - 有符号大整数值。
scale: Int32 - 标度值。
ctx!: DecimalContext - Deciaml 上下文。

异常：

OverflowException - 当构建值范围超过 [-(maxValue(ctx.precision) * (10 ^Int32.MAX )), maxValue(ctx.precision) * (10 ^Int32.MAX)] 时，抛出此异常。

init(Float16, DecimalContext)

public init(val: Float16, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 16 位有符号浮点数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

注意：

由于部分十进制小数无法通过二进制浮点数精确表示，此构造函数以精确值构建 Decimal 对象，传入浮点数值可能与最终构建 Decimal 对象字符串打印值不一致。

参数：

val: Float16 - 16 位有符号二进制浮点数。
ctx!: DecimalContext - Decimal 上下文。

异常：

IllegalArgumentException - 当入参为 inf、-inf 或 nan 时，抛出此异常。

init(Float32, DecimalContext)

public init(val: Float32, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 32 位有符号浮点数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

注意：

由于部分十进制小数无法通过二进制浮点数精确表示，此构造函数以精确值构建 Decimal 对象，传入浮点数值可能与最终构建 Decimal 对象字符串打印值不一致。

参数：

val: Float32 - 32 位有符号二进制浮点数。
ctx!: DecimalContext - Decimal 上下文。

异常：

IllegalArgumentException - 当入参为 inf、-inf 或 nan 时，抛出此异常。

init(Float64, DecimalContext)

public init(val: Float64, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 64 位有符号浮点数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

注意：

由于部分十进制小数无法通过二进制浮点数精确表示，此构造函数以精确值构建 Decimal 对象，传入浮点数值可能与最终构建 Decimal 对象字符串打印值不一致。

参数：

val: Float64 - 64 位有符号二进制浮点数。
ctx!: DecimalContext - Decimal 上下文。

异常：

IllegalArgumentException - 当入参为 inf、-inf 或 nan 时，抛出此异常。

init(Int16, DecimalContext)

public init(val: Int16, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 16 位有符号整数构建 Decimal 结构体。

允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

val: Int16 - 16 位有符号整数。
ctx!: DecimalContext - Decimal 上下文。

init(Int32, DecimalContext)

public init(val: Int32, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 32 位有符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

val: Int32 - 32 位有符号整数。
ctx!: DecimalContext - Decimal 上下文。

init(Int64, DecimalContext)

public init(val: Int64, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 64 位有符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

val: Int64 - 64 位有符号整数。
ctx!: DecimalContext - Decimal 上下文。

init(Int8, DecimalContext)

public init(val: Int8, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 8 位有符号整数构建 Decimal 结构体。

允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

val: Int8 - 8 位有符号整数。
ctx!: DecimalContext - Decimal 上下文。

init(IntNative, DecimalContext)

public init(val: IntNative, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 32 位或 64 位 (具体长度与平台相关) 有符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

val: IntNative - 32 位或 64位有符号整数。
ctx!: DecimalContext - Decimal 上下文。

init(String, DecimalContext)

public init(val: String, ctx!: DecimalContext = defaultDecimalContext)

功能：通过规定格式字符串构建 Decimal 结构体。

允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。字符串需满足格式如下，即开头可选的符号（正号或负号），接 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 - 规定格式字符串。
ctx!: DecimalContext - Deciaml 上下文。

异常：

IllegalArgumentException - 当入参字符串不满足规定格式时，抛此异常。
OverflowException - 当构建值范围超过 [-(maxValue(ctx.precision) * (10 ^Int32.MAX)), maxValue(ctx.precision) * (10 ^Int32.MAX)] 时，抛出此异常。

init(UInt16, DecimalContext)

public init(val: UInt16, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 16 位无符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

val: UInt16 - 16 位无符号整数。
ctx!: DecimalContext - Decimal 上下文。

init(UInt32, DecimalContext)

public init(val: UInt32, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 32 位无符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

val: UInt32 - 32 位无符号整数。
ctx!: DecimalContext - Decimal 上下文。

init(UInt64, DecimalContext)

public init(val: UInt64, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 64 位无符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

val: UInt64 - 64 位无符号整数。
ctx!: DecimalContext - Decimal 上下文。

init(UInt8, DecimalContext)

public init(val: UInt8, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 8 位无符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

val: UInt8 - 8 位无符号整数。
ctx!: DecimalContext - Decimal 上下文。

init(UIntNative, DecimalContext)

public init(val: UIntNative, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 32 位或 64 位 (具体长度与平台相关) 无符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

val: UIntNative - 32 位或 64位无符号整数。
ctx!: DecimalContext - Decimal 上下文。

func abs()

public func abs(): Decimal

功能：获取当前 Decimal 对象的绝对值。

返回值：

Decimal - 返回当前 Decimal 对象的绝对值。

func add(Decimal)

public func add(d: Decimal): Decimal

功能：加法运算，加上入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留加和结果实际精度值。

参数：

d: Decimal - Decimal 加数对象。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储两个加数的加和结果值。

异常：

OverflowException - 当两个加数标度值相减值溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A.add(B)
    println("C = ${C}")
}

运行结果:

C = 5

func add(Decimal, DecimalContext)

public func add(d: Decimal, ctx: DecimalContext): Decimal

功能：加法运算，支持自定义运算上下文，加上入参 Decimal 对象，返回结果值，如果结果精度超过上下文指定精度，则根据指定的上下文对加和结果进行舍入。

参数：

d: Decimal - Decimal 加数对象。
ctx: DecimalContext - Decimal 上下文。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储两个加数的加和结果值。

异常：

OverflowException - 当两个加数标度值相减值溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A.add(B, Decimal.defaultDecimalContext)
    println("C = ${C}")
}

运行结果:

C = 5

func compare(Decimal)

public func compare(d: Decimal): Ordering

功能：比较当前对象与入参 Decimal 对象，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象。

返回值：

Ordering - 返回比较结果，当前对象小于入参时，返回 Ordering.LT，大于入参时，返回 Ordering.GT，否则返回 Ordering.EQ。

示例：

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 div(Decimal)

public func div(d: Decimal): Decimal

功能：除法运算，除以入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留除法运算结果实际精度值。

注意：

结果为无限小数场景时，默认采用 IEEE 754-2019 decimal128 对结果进行舍入。

参数：

d: Decimal - Decimal 除数对象。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储除法运算结果值。

异常：

IllegalArgumentException - 当除数为 0 时，抛出此异常
OverflowException - 当除法结果值范围超过 [-(maxValue(ctx.precision) * (10 ^Int32.MAX)), maxValue(ctx.precision) * (10 ^Int32.MAX)] 时，抛出此异常。

func div(Decimal, DecimalContext)

public func div(d: Decimal, ctx: DecimalContext): Decimal

功能：除法运算，支持自定义运算上下文，除以入参 Decimal 对象，返回结果值，如果结果精度超过上下文指定精度，则根据指定的上下文对除法运算结果进行舍入。

参数：

d: Decimal - Decimal 除数对象。
ctx: DecimalContext - Decimal 上下文。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储除法运算结果值。

异常：

IllegalArgumentException - 当除数为 0 时，抛出此异常。
OverflowException - 当除法结果值范围超过 [-(maxValue(ctx.precision) * (10 ^Int32.MAX)), maxValue(ctx.precision) * (10 ^Int32.MAX)] 时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A.div(B, Decimal.defaultDecimalContext)
    println("C = ${C}")
}

运行结果:

C = 0.6666666666666666666666666666666667

func divAndRem(Decimal)

public func divAndRem(d: Decimal): (BigInt, Decimal)

功能：除法取商和余数运算，除以入参 Decimal 对象，返回整数商值和余数值。上下文默认 defaultDecimalContext 保留结果实际精度值。

参数：

d: Decimal - Decimal 除数对象。

返回值：

(BigInt, Decimal) - 生成一个元组对象，分别用于存储整数商值结果和余数结果值。

异常：

IllegalArgumentException - 当除数为 0 时，抛出此异常。
OverflowException - 当除法结果值范围超过 [-(maxValue(ctx.precision) * (10 ^Int32.MAX)), maxValue(ctx.precision) * (10 ^Int32.MAX)] 时，抛出此异常。

func divAndRem(Decimal, DecimalContext)

public func divAndRem(d: Decimal, ctx: DecimalContext): (BigInt, Decimal)

功能：除法取商和余数运算，支持自定义运算上下文，除以入参 Decimal 对象，返回整数商值和余数值。如果结果精度超过上下文指定精度，则根据指定的上下文对除法运算结果进行舍入。

注意：

这里传入的舍入规则是无效的，默认使用 RoundingMode.DOWN。

参数：

d: Decimal - Decimal 除数对象。
ctx: DecimalContext - Decimal 上下文。

返回值：

(BigInt, Decimal) - 生成一个元组对象，分别用于存储整数商值结果和余数结果值。

异常：

IllegalArgumentException - 当除数为 0 时，抛出此异常。
OverflowException - 当除法结果值范围超过 [-(maxValue(ctx.precision) * (10 ^Int32.MAX)), maxValue(ctx.precision) * (10 ^Int32.MAX)] 时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(5)
    let B = Decimal(3)
    let (C, D)= A.divAndRem(B, Decimal.defaultDecimalContext)
    println("C = ${C}, D = ${D}")
}

运行结果:

C = 1, D = 2

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 mul(Decimal)

public func mul(d: Decimal): Decimal

功能：乘法运算，乘以入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留乘法运算结果实际精度值。

参数：

d: Decimal - Decimal 乘数对象。

返回值：

Decimal - 生产一个新的 Decimal 对象，用于存储乘法运算结果值。

异常:

OverflowException - 当两个乘数标度值相加溢出时，抛出此异常。

func mul(Decimal, DecimalContext)

public func mul(d: Decimal, ctx: DecimalContext): Decimal

功能：乘法运算，支持自定义运算上下文，乘以入参 Decimal 对象，返回结果值，如果结果精度超过上下文指定精度，则根据指定的上下文对乘法运算结果进行舍入。

参数：

d: Decimal - Decimal 乘数对象。
ctx: DecimalContext - Decimal 上下文。

返回值：

Decimal - 生产一个新的 Decimal 对象，用于存储乘法运算结果值。

异常:

OverflowException - 当两个乘数标度值相加溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A.mul(B, Decimal.defaultDecimalContext)
    println("C = ${C}")
}

运行结果:

C = 6

func neg()

public func neg(): Decimal

功能：取反运算，对当前 Decimal 对象取反，返回结果值。上下文默认 defaultDecimalContext 保留取反运算结果实际精度值。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储取反结果值。

func neg(DecimalContext)

public func neg(ctx: DecimalContext): Decimal

功能：取反运算，支持自定义运算上下文，对当前 Decimal 对象取反，返回结果值。如果结果精度超过上下文指定精度，则根据指定的上下文对取反运算结果进行舍入。

参数：

ctx: DecimalContext - Decimal 上下文。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储取反结果值。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(-5)
    let B = Decimal(3)
    let C = A.neg()
    let D = B.neg(Decimal.defaultDecimalContext)
    println("C = ${C}, D = ${D}")
}

运行结果:

C = 5, D = -3

func pow(Int64)

public func pow(n: Int64): Decimal

功能：乘方运算，获取当前对象为底数，入参 Int64 为指数的乘方运算结果。

注意：

指数为负值且结果为无限小数场景时，默认采用 IEEE 754-2019 decimal128 对结果进行舍入。

参数：

n: Int64 - 乘方运算的指数值。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储乘方运算结果值。

异常：

OverflowException - 当乘方运算结果标度值溢出时，抛出此异常。

func pow(Int64, DecimalContext)

public func pow(n: Int64, ctx: DecimalContext): Decimal

功能：乘方运算，支持自定义运算上下文，获取当前对象为底数，入参 Int64 为指数的乘方运算结果，如果运算结果超过上下文指定精度，则根据指定的上下文对乘方结果进行舍入。

参数：

n: Int64 - 乘方运算的指数值。
ctx: DecimalContext - Decimal 上下文。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储乘方运算结果值。

异常：

OverflowException - 当乘方运算结果标度值溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2.5)
    println("A.pow(3, DecimalContext) = ${A.pow(3, Decimal.defaultDecimalContext)}")
}

运行结果:

A.pow(3, DecimalContext) = 15.625

func reScale(Int32, RoundingMode)

public func reScale(newScale: Int32, rm!: RoundingMode = HALF_EVEN): Decimal

功能：调整 Decimal 对象标度值，允许指定舍入规则，返回标度调整后新的 Decimal 对象。

参数：

newScale: Int32 - 新的标度值。
rm!: RoundingMode - 舍入规则。

返回值：

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 对象移除尾部零，不改变对象数值。

返回值：

Decimal - 新的无尾部零的 Decimal 对象。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(1.00)
    println("A.removeTrailingZeros() = ${A.removeTrailingZeros()}")
}

运行结果:

A.removeTrailingZeros() = 1

func round(DecimalContext)

public func round(ctx: DecimalContext): Decimal

功能：按照指定上下文（舍入精度、舍入规则）对当前 Decimal 对象进行舍入操作。

参数：

ctx: DecimalContext - Decimal 上下文。

返回值：

Decimal - 舍入操作生成的新的 Decimal 对象。

异常：

OverflowException - 当舍入操作结果标度值溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(1.0)
    println("A.round(1.0) = ${A.round(Decimal.defaultDecimalContext)}")
}

运行结果:

A.round(1.0) = 1

func scaleUnit()

public func scaleUnit(): Decimal

功能：对当前 Decimal 对象返回标度单位，即数值为 1 ，标度值与当前对象相等的 Decimal 对象。

返回值：

Decimal - 标度单位 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 sqrt(DecimalContext)

public func sqrt(ctx!: DecimalContext = defaultDecimalContext): Decimal

功能：开方运算，支持自定义运算上下文，获取当前对象开方结果，如果运算结果超过上下文指定精度，则根据指定的上下文对开方结果进行舍入。

入参：

ctx!: DecimalContext - Decimal 上下文。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储开方运算结果值。

异常：

IllegalArgumentException - 当前 Decimal 对象为负数时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(0.25)
    println("A.abs() = ${A.abs()}")
    println("A.sqrt() = ${A.sqrt()}")
}

运行结果:

A.abs() = 0.25
A.sqrt() = 0.5

func sub(Decimal)

public func sub(d: Decimal): Decimal

功能：减法运算，减去入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留减法运算结果实际精度值。

参数：

d: Decimal - Decimal 减数对象。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储减法运算结果值。

异常：

OverflowException - 当被减数与减数标度值相减溢出时，抛出此异常。

func sub(Decimal, DecimalContext)

public func sub(d: Decimal, ctx: DecimalContext): Decimal

功能：减法运算，支持自定义运算上下文，减去入参 Decimal 对象，返回结果值，如果结果精度超过上下文指定精度，则根据指定的上下文对减法运算结果进行舍入。

参数：

d: Decimal - Decimal 减数对象。
ctx: DecimalContext - Decimal 上下文。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储减法运算结果值。

异常：

OverflowException - 当被减数与减数标度值相减溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A.sub(B, Decimal.defaultDecimalContext)
    println("C = ${C}")
}

运行结果:

C = -1

func toBigInt()

public func toBigInt(): BigInt

功能：将当前 Decimal 对象转化为 BigInt 类型。

返回值：

BigInt - 转换后的 BigInt 值。

func toEngString()

public func toEngString(): String

功能：以工程计数法的形式打印输出 Decimal 对象，指数为 3 的倍数, 当值小于 0 时以 “-” 开头后跟十进制数字，大于等于 0 时，直接打印输出数字，不额外添加 “+”。指数小于 0 时同样遵循以上规则。

返回值：

String - 工程计数法形式的 Decimal 字符串。

func toSciString()

public func toSciString(): String

功能：以科学计数法的形式打印输出 Decimal 对象，当值小于 0 时以 “-” 开头后跟十进制数字，大于等于 0 时，直接打印输出数字，不额外添加 “+”。指数小于 0 时同样遵循以上规则。

返回值：

String - 科学计数法形式的 Decimal 字符串。

示例：

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 类型，支持自定义溢出策略。

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

Int16 - 转换后的 Int16 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

func toInt32(OverflowStrategy)

public func toInt32(overflowHandling!: OverflowStrategy = throwing): Int32

功能：将当前 Decimal 对象转化为 Int32 类型，支持自定义溢出策略。

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

Int32 - 转换后的 Int32 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

func toInt64(OverflowStrategy)

public func toInt64(overflowHandling!: OverflowStrategy = throwing): Int64

功能：将当前 Decimal 对象转化为 Int64 类型，支持自定义溢出策略。

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

Int64 - 转换后的 Int64 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

func toInt8(OverflowStrategy)

public func toInt8(overflowHandling!: OverflowStrategy = throwing): Int8

功能：将当前 Decimal 对象转化为 Int8 类型，支持自定义溢出策略。

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

Int8 - 转换后的 Int8 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

func toIntNative(OverflowStrategy)

public func toIntNative(overflowHandling!: OverflowStrategy = throwing): IntNative

功能：将当前 Decimal 对象转化为 IntNative 类型，支持自定义溢出策略。

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

IntNative - 转换后的 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 时，直接打印输出数字，不额外添加 “+”。

返回值：

String - 不带指数形式的 Decimal 字符串。

示例：

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 类型，支持自定义溢出策略。

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

UInt16 - 转换后的 UInt16 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

func toUInt32(OverflowStrategy)

public func toUInt32(overflowHandling!: OverflowStrategy = throwing): UInt32

功能：将当前 Decimal 对象转化为 UInt32 类型，支持自定义溢出策略。

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

UInt32 - 转换后的 UInt32 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

func toUInt64(OverflowStrategy)

public func toUInt64(overflowHandling!: OverflowStrategy = throwing): UInt64

功能：将当前 Decimal 对象转化为 UInt64 类型，支持自定义溢出策略。

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

UInt64 - 转换后的 UInt64 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

func toUInt8(OverflowStrategy)

public func toUInt8(overflowHandling!: OverflowStrategy = throwing): UInt8

功能：将当前 Decimal 对象转化为 UInt8 类型，支持自定义溢出策略。

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

UInt8 - 转换后的 UInt8 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

func toUIntNative(OverflowStrategy)

public func toUIntNative(overflowHandling!: OverflowStrategy = throwing): UIntNative

功能：将当前 Decimal 对象转化为 UIntNative 类型，支持自定义溢出策略。

入参：

overflowHandling!: OverflowStrategy - 转换溢出策略。

返回值：

UIntNative - 转换后的 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 对象与当前对象是否不相等，返回比较结果值。

参数：

d: Decimal - 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

功能：乘法运算，乘法运算符重载，行为与 mul 函数相同，乘以入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留乘法运算结果实际精度值。

参数：

d: 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 = 6

operator func **(Int64)

public operator func **(n: Int64): Decimal

功能：乘方运算，乘方运算符重载，行为与 pow 函数相同，获取当前对象为底数，入参 Int64 为指数的乘方运算结果，其中指数为入参 Decimal 对象的整数部分。

注意：

指数为负值且结果为无限小数场景时，默认采用 IEEE 754-2019 decimal128 对结果进行舍入。

参数：

n: Int64 - 乘方运算的指数值。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储乘方运算结果值。

异常：

OverflowException - 当乘方运算结果标度值溢出时，抛出此异常。

示例：

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

功能：加法运算，加法运算符重载，行为与 add 函数相同，加上入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留加合结果实际精度值。

参数：

d: 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 = 5

operator func -()

public operator func -(): Decimal

功能：取反运算，一元负数运算符重载，行为与 neg 函数相同，对当前 Decimal 对象取反，返回结果值。上下文默认 defaultDecimalContext 保留取反运算结果实际精度值。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储取反结果值。

operator func -(Decimal)

public operator func -(d: Decimal): Decimal

功能：减法运算，减法运算符重载，行为与 sub 函数相同，减去入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留减法运算结果实际精度值。

参数：

d: 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 对象是否小于当前对象，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象。

返回值：

Bool - 返回小于比较运算结果。当前对象小于入参时，返回 true，否则返回 false。

operator func <=(Decimal)

public operator func <=(d: Decimal): Bool

功能：小于等于比较运算，小于等于运算符重载，判断入参 Decimal 对象是否小于等于当前对象，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象。

返回值：

Bool - 返回小于等于比较运算结果。当前对象小于等于入参时，返回 true，否则返回 false

operator func ==(Decimal)

public operator func ==(d: Decimal): Bool

功能：等于比较运算，等于运算符重载，判断入参 Decimal 对象与当前对象是否相等，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象。

返回值：

Bool - 返回等于比较运算结果。当前对象等于入参时，返回 true，否则返回 false。

operator func >(Decimal)

public operator func >(d: Decimal): Bool

功能：大于比较运算，大于运算符重载，判断入参 Decimal 对象是否大于当前对象，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象

返回值：

Bool - 返回大于比较运算结果。当前对象大于入参时，返回 true，否则返回 false

operator func >=(Decimal)

public operator func >=(d: Decimal): Bool

功能：大于等于比较运算，大于等于运算符重载，判断入参 Decimal 对象是否大于等于当前对象，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象。

返回值：

Bool - 返回大于等于比较运算结果。当前对象大于等于入参时，返回 true，否则返回 false。

operator func /(Decimal)

public operator func /(d: Decimal): Decimal

功能：除法运算，除法运算符重载，行为与 div 函数相同，除以入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留除法运算结果实际精度值。

注意：

结果为无限小数场景时，默认采用 IEEE 754-2019 decimal128 对结果进行舍入。

参数：

d: Decimal - Decimal 除数对象。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储除法运算结果值。

异常：

IllegalArgumentException - 当除数为 0 时，抛出此异常。
OverflowException - 当除法结果值范围超过 [-(maxValue(ctx.precision) * (10 ^Int32.MAX)), maxValue(ctx.precision) * (10 ^Int32.MAX)] 时，抛出此异常。

示例：

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

struct DecimalContext

public struct DecimalContext {
    public init(precision: Int64, roundingMode: RoundingMode)
}

功能：DecimalContext 对象作用于用户对 Decimal 操作过程中，对生成结果指定上下文，设定结果的精度与对应舍入规则。

let precision

public let precision: Int64

功能：获取上下文中指定的精度值。

类型：Int64

let roundingMode

public let roundingMode: RoundingMode

功能：获取上下文中指定的舍入规则。

类型：RoundingMode

init(Int64, RoundingMode)

public init(precision: Int64, roundingMode: RoundingMode)

功能：指定精度与舍入规则构建上下文结构体，可作用于 Decimal 操作结果。

参数：

precision: Int64 - 精度值，限制 Decimal 结果有效数值位数。
roundingMode: RoundingMode - 舍入规则，Decimal 结果有效位超出精度限制时舍入操作遵循该指定规则。

异常：

IllegalArgumentException - 当传入精度小于 0 时，抛出此异常。

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.numeric.*

main() {
    let decimal1: Decimal = Decimal("12345.6789")
    let decimal2: Decimal = Decimal(BigInt("987654321"), 6)
    println("without ctx:")
    println("${decimal1} + ${decimal2} = ${decimal1 + decimal2}")
    println("${decimal1} - ${decimal2} = ${decimal1 - decimal2}")
    println("${decimal1} * ${decimal2} = ${decimal1 * decimal2}")
    println("${decimal1} / ${decimal2} = ${decimal1 / decimal2}")
    let (quo, rem) = decimal1.divAndRem(decimal2)
    println("${decimal1} / ${decimal2} = ${quo} .. ${rem}")
    println("with ctx(precision: 8, HALF_EVEN):")
    let baseOperCtx = DecimalContext(8, HALF_EVEN)
    println("${decimal1} + ${decimal2} = ${decimal1.add(decimal2, baseOperCtx)}")
    println("${decimal1} - ${decimal2} = ${decimal1.sub(decimal2, baseOperCtx)}")
    println("${decimal1} * ${decimal2} = ${decimal1.mul(decimal2, baseOperCtx)}")
    println("${decimal1} / ${decimal2} = ${decimal1.div(decimal2, baseOperCtx)}")
    let (quoWithCtx, remWithCtx) = decimal1.divAndRem(decimal2, baseOperCtx)
    println("${decimal1} / ${decimal2} = ${quoWithCtx} .. ${remWithCtx}")
    return 0
}

运行结果:

without ctx:
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 = 12 .. 493.827048
with ctx(precision: 8, HALF_EVEN):
12345.6789 + 987.654321 = 13333.333
12345.6789 - 987.654321 = 11358.025
12345.6789 * 987.654321 = 12193263
12345.6789 / 987.654321 = 12.500000
12345.6789 / 987.654321 = 12 .. 493.827048

Decimal 基本属性示例

以下为初始化 Decimal 对象，并查询对象的基本属性的示例：

import std.math.numeric.*

main() {
    let decimalProperties = Decimal("-123456.7890123456789")
    println("deciaml: ${decimalProperties}")
    println("decimal sign: ${decimalProperties.sign}")
    println("decimal scale: ${decimalProperties.scale}")
    println("decimal value: ${decimalProperties.value}")
    println("decimal precision: ${decimalProperties.precision}")
    return 0
}

运行结果:

deciaml: -123456.7890123456789
decimal sign: -1
decimal scale: 13
decimal value: -1234567890123456789
decimal precision: 19

Decimal 大小比较示例

以下为初始化多个 Decimal 对象，相互之间大小比较的示例：

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.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

功能: 此类提供了一个并发安全的对象缓存类型，该类型可以储存已经分配内存但未使用的对象。

说明：

当一个对象不需要使用时可以将对象存入 ObjectPool，当需要使用对象时再从该 ObjectPool 中取出。

储存在一个 ObjectPool 中的对象只能是同一种类型。

在一个 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 后不应该再对该对象进行任何操作，否则可能导致不可期问题。

参数：

item: T - 需要放入 ObjectPool 的对象。

std.os 包

功能介绍

os 包提供了包括获取或操作当前进程相关信息(如进程参数、环境变量、目录信息等)，注册回调函数及退出当前进程等能力。

目前支持 Linux 平台，macOS 平台，Windows 平台与 OHOS 平台。

API 列表

函数

函数名	功能	支持平台
currentDir()	获取当前工作目录。	`Linux` `Windows` `macOS` `OHOS`
envVars()	获取所有环境变量。	`Linux` `Windows` `macOS` `OHOS`
getArgs()	返回命令行参数列表，例如在命令行中执行 `a.out ab cd ef`，其中 `a.out` 是程序名，返回的列表包含三个元素 ab cd ef。	`Linux` `Windows` `macOS` `OHOS`
getEnv(String)	获取指定名称的环境变量值。	`Linux` `Windows` `macOS` `OHOS`
homeDir()	获取 `home` 目录。	`Linux` `Windows` `macOS` `OHOS`
processorCount()	获取处理器数量。	`Linux` `Windows` `macOS` `OHOS`
removeEnv(String)	通过指定环境变量名称移除环境变量。	`Linux` `Windows` `macOS` `OHOS`
setEnv(String, String)	用于设置一对环境变量。	`Linux` `Windows` `macOS` `OHOS`
tempDir()	获取临时目录。	`Linux` `Windows` `macOS` `OHOS`

函数

func currentDir()

public func currentDir(): Directory

功能：获取当前工作目录。

说明：

返回值为 Directory 类型，可以使用 Directory.info.path.toString() 获取路径的字符串。

返回值：

func envVars()

public func envVars(): HashMap<String, String>

功能：获取所有环境变量。

说明：

返回值为 HashMap，它以 key 和 value 的形式存储环境变量。

返回值：

HashMap < String, String > - 所有环境变量值。

func getArgs()

public func getArgs(): Array<String>

功能：返回命令行参数列表，例如在命令行中执行 a.out ab cd ef，其中 a.out 是程序名，返回的列表包含三个元素 ab cd ef。

说明：

使用 C 语言调用仓颉动态库方式时，通过 int SetCJCommandLineArgs(int argc, const char* argv[]) 设置的命令行参数，在使用 getArgs() 获取时将会被舍弃掉第一个参数。

返回值：

Array<String> - 命令行参数列表。

func getEnv(String)

public func getEnv(k: String): Option<String>

功能：获取指定名称的环境变量值。

参数：

k: String - 环境变量名称。

返回值：

Option<String> - 指定名称对应的环境变量值。

异常：

IllegalArgumentException - 当函数参数 k 包含空字符时，抛出异常。

func homeDir()

public func homeDir(): Directory

功能：获取 home 目录。

说明：

返回值为 Directory 类型，可以使用 Directory.info.path.toString() 获取路径的字符串。

返回值：

Directory - home 目录。

func processorCount()

public func processorCount(): Int64

功能：获取处理器数量。

返回值：

Int64 - 处理器数量。

func removeEnv(String)

public func removeEnv(k: String): Unit

功能：通过指定环境变量名称移除环境变量。

参数：

k: String - 环境变量名称。

异常：

IllegalArgumentException - 当函数参数 k 包含空字符时，抛出异常。

func setEnv(String, String)

public func setEnv(k: String, v: String): Unit

功能：用于设置一对环境变量。如果设置了同名环境变量，原始环境变量值将被覆盖。

参数：

k: String - 环境变量名称。
v: String - 环境变量值。

异常：

IllegalArgumentException - 当函数参数 k 或 v 中包含空字符时，抛出异常。

func tempDir()

public func tempDir(): Directory

功能：获取临时目录。从环境变量中获取 TMPDIR、TMP、TEMP 和 TEMPDIR 环境变量。如果以上值在环境变量中均不存在，则默认返回 /tmp 目录。

说明：

返回值为 Directory 类型，可以使用 Directory.info.path.toString() 获取路径的字符串。

返回值：

std.os.posix 包

功能介绍

os.posix 包主要适配 POSIX 系统接口。

本包提供多平台统一操控能力，目前支持 Linux 平台，macOS 平台，Windows 平台与 OHOS 平台。

API 列表

函数

函数名	功能	支持平台
open(String, Int32)	打开文件并为其返回新的文件描述符，或在失败时返回 `-1`。	`Linux` `Windows` `macOS` `OHOS`
open(String, Int32, UInt32)	打开文件并为其返回新的文件描述符，或在失败时返回 `-1`。	`Linux` `Windows` `macOS` `OHOS`
access(String, Int32)	判断某个文件是否具有某种权限，具有返回 `0`，否则返回 `-1`。	`Linux` `Windows` `macOS` `OHOS`
chdir(String)	通过指定路径的方式，更改调用进程的当前工作目录。	`Linux` `Windows` `macOS` `OHOS`
chmod(String, UInt32)	修改文件访问权限。	`Linux` `Windows` `macOS` `OHOS`
chown(String, UInt32, UInt32)	修改文件所有者和文件所有者所属组。	`Linux` `macOS` `OHOS`
close(Int32)	关闭文件，`close` 将会触发数据写回磁盘，并释放文件占用的资源。	`Linux` `Windows` `macOS` `OHOS`
creat(String, UInt32)	创建文件并为其返回文件描述符，或在失败时返回 `-1`。	`Linux` `Windows` `macOS` `OHOS`
dup(Int32)	用于复制旧 `fd` 参数指定的文件描述符并返回。	`Linux` `Windows` `macOS` `OHOS`
dup2(Int32, Int32)	用于复制 `oldfd` 参数指定的文件描述符，并将其返回到 `newfd` 参数。	`Linux` `Windows` `macOS` `OHOS`
faccessat(Int32, String, Int32, Int32)	判断 `fd` 对应的文件是否具有某种权限，具有返回 `0`，否则返回 `-1`。	`Linux` `macOS` `OHOS`
fchdir(Int32)	通过指定文件路径的描述符，更改调用进程的当前工作目录。	`Linux` `macOS` `OHOS`
fchmod(Int32, UInt32)	修改文件描述符对应的文件访问权限。	`Linux` `Windows` `macOS` `OHOS`
fchmodat(Int32, String, UInt32, Int32)	修改文件描述符对应的文件访问权限。	`Linux` `Windows` `macOS` `OHOS`
fchown(Int32, UInt32, UInt32)	修改 `fd` 对应的文件所有者和文件所有者所属组。	`Linux` `macOS` `OHOS`
fchownat(Int32, String, UInt32, UInt32, Int32)	修改文件描述符对应的文件所有者和文件所有者所属组。	`Linux` `macOS` `OHOS`
getcwd()	获取当前执行进程工作目录的绝对路径。	`Linux` `Windows` `macOS` `OHOS`
getgid()	获取用户组 `ID`。	`Linux` `macOS` `OHOS`
getgroups(Int32, CPointer<UInt32>)	获取当前用户所属组的代码。	`Linux` `macOS` `OHOS`
gethostname()	获取主机名称，此名称通常是 `TCP/IP` 网络上主机的名称。	`Linux` `macOS` `OHOS`
getlogin()	获取当前登录名。	`Linux` `macOS` `OHOS`
getos()	从 `/proc/version` 文件中获取 `Linux` 系统的信息。	`Linux`
getpgid(Int32)	获取 `pid` 指定的进程的 `PGID`，如果 `pid` 为零，返回调用进程的进程 `ID`。	`Linux` `macOS` `OHOS`
getpgrp()	获取调用进程的父进程 `ID`。	`Linux` `macOS` `OHOS`
getpid()	获取调用进程的进程 `ID(PID)`。	`Linux` `Windows` `macOS` `OHOS`
getppid()	获取调用进程的父进程 `ID`。	`Linux` `macOS` `OHOS`
getuid()	获取调用进程的真实用户 `ID`。	`Linux` `macOS` `OHOS`
isBlk(String)	检查传入对象是否为块设备，并返回布尔类型。	`Linux` `Windows` `macOS` `OHOS`
isChr(String)	检查传入对象是否为字符设备，返回布尔类型。	`Linux` `Windows` `macOS` `OHOS`
isDir(String)	检查传入对象是否为文件夹，返回布尔类型。	`Linux` `Windows` `macOS` `OHOS`
isFIFO(String)	检查传入对象是否为 `FIFO` 文件，返回布尔类型。	`Linux` `macOS` `OHOS`
isLnk(String)	检查传入对象是否为软链路，返回布尔类型。	`Linux` `macOS` `OHOS`
isReg(String)	检查传入对象是否为普通文件，返回布尔类型。	`Linux` `Windows` `macOS` `OHOS`
isSock(String)	检查传入对象是否为套接字文件，返回布尔类型。	`Linux` `macOS` `OHOS`
isType(String, UInt32)	检查文件是否为指定模式的文件。	`Linux` `macOS` `OHOS`
isatty(Int32)	用于测试文件描述符是否引用终端，成功时返回 `true`，否则返回 `false`。	`Linux` `Windows` `macOS` `OHOS`
kill(Int32, Int32)	系统调用可用于向任何进程组或进程发送任何信号。	`Linux` `macOS` `OHOS`
killpg(Int32, Int32)	将信号 `sig` 发送到进程组 `pgrp`，如果 `pgrp` 为 `0`，则 killpg() 将信号发送到调用进程的进程组。	`Linux` `macOS` `OHOS`
lchown(String, UInt32, UInt32)	修改文件链接本身所有者和所有者所属组。	`Linux` `macOS`
link(String, String)	为存在的文件创建链接，一个文件可以有多个指向其 `i-node` 的目录条目。	`Linux` `macOS` `OHOS`
linkat(Int32, String, Int32, String, Int32)	创建相对于目录文件描述符的文件链接。	`Linux` `macOS` `OHOS`
lseek(Int32, Int64, Int32)	当文件进行读或写时，读或写位置相应增加。	`Linux` `Windows` `macOS` `OHOS`
nice(Int32)	更改当前线程的优先级。	`Linux` `macOS` `OHOS`
open64(String, Int32)	打开文件并为其返回新的文件描述符，或在失败时返回 `-1`。	`Linux` `OHOS`
open64(String, Int32, UInt32)	打开文件并为其返回新的文件描述符，或在失败时返回 `-1`。	`Linux` `OHOS`
openat(Int32, String, Int32)	打开文件并为其返回新的文件描述符，或在失败时返回 `-1`。	`Linux` `macOS` `OHOS`
openat(Int32, String, Int32, UInt32)	打开文件并为其返回新的文件描述符，或在失败时返回 `-1`。	`Linux` `macOS` `OHOS`
openat64(Int32, String, Int32)	打开文件并为其返回新的文件描述符，或在失败时返回 `-1`。	`Linux` `macOS` `OHOS`
openat64(Int32, String, Int32, UInt32)	打开文件并为其返回新的文件描述符，或在失败时返回 `-1`。	`Linux` `macOS` `OHOS`
pread(Int32, CPointer<UInt8>, UIntNative, Int32)	将 `fd` 指向的文件的 `nbyte` 字节传输到 `buffer` 指向的内存中。	`Linux` `macOS` `OHOS`
pwrite(Int32, CPointer<UInt8>, UIntNative, Int32)	将 `buffer` 指向的内存中 `nbyte` 字节从指定偏移位置开始写入到 `fd` 指向的文件。	`Linux` `macOS` `OHOS`
read(Int32, CPointer<UInt8>, UIntNative)	将 `fd` 指向的文件的 `nbyte` 字节传输到 `buffer` 指向的内存中。	`Linux` `Windows` `macOS` `OHOS`
remove(String)	删除文件或目录。	`Linux` `Windows` `macOS` `OHOS`
rename(String, String)	重命名文件，如果需要将会移动文件所在目录。	`Linux` `Windows` `macOS` `OHOS`
renameat(Int32, String, Int32, String)	重命名文件，如果需要将会移动文件所在目录。	`Linux` `macOS` `OHOS`
setgid(UInt32)	设置调用进程的有效组 `ID`，需要适当的权限。	`Linux` `macOS`
sethostname(String)	设置主机名，仅超级用户可以调用。	`Linux` `macOS`
setpgid(Int32, Int32)	此函数将参数 `pid` 指定的组 `ID` 设置为参数 `pgrp` 指定的组 `ID`。	`Linux` `macOS` `OHOS`
setpgrp()	将当前进程所属的组 `ID` 设置为当前进程的进程 `ID`，此函数等同于调用 setpgid(0, 0)。	`Linux` `macOS` `OHOS`
setuid(UInt32)	设置调用进程的有效用户 `ID`，需要适当的权限。	`Linux` `macOS`
symlink(String, String)	创建一个名为 `symPath` 链接到 `path` 所指定的文件。	`Linux` `macOS` `OHOS`
symlinkat(String, Int32, String)	创建一个名为 `symPath` 链接到 `path` 与 `fd` 所指定的文件。	`Linux` `macOS` `OHOS`
ttyname(Int32)	返回终端名称。	`Linux` `Windows` `macOS` `OHOS`
umask(UInt32)	设置权限掩码。	`Linux` `Windows` `macOS` `OHOS`
unlink(String)	从文件系统中删除文件。	`Linux` `macOS` `OHOS`
unlinkat(Int32, String, Int32)	从文件系统中删除文件。	`Linux` `macOS` `OHOS`
write(Int32, CPointer<UInt8>, UIntNative)	将 `buffer` 指向的内存中 `nbyte` 字节写入到 `fd` 指向的文件。	`Linux` `Windows` `macOS` `OHOS`

常量

常量名	功能	支持平台
AT_EMPTY_PATH	表示在文件系统中空路径（即没有指定任何文件或目录）时返回的文件描述符，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `Windows` `OHOS`
AT_REMOVEDIR	如果指定了 `AT_REMOVEDIR` 标志，则对 `pathname` 执行等效于 `rmdir(2)` 的操作，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `Windows` `macOS` `OHOS`
O_CLOEXEC	在某些多线程程序中，使用此标志是必不可少的。因为在一个线程同时打开文件描述符，而另一个线程执行 `fork(2)` 加 `execve(2)` 场景下使用单独的 `fcntl(2)` `F_SETFD` 操作设置 `FD_CLOEXEC` 标志并不足以避免竞争条件，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `macOS` `OHOS`
O_DIRECTORY	如果 `pathname` 指定的文件不是目录，则打开文件失败，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `macOS` `OHOS`
O_CREAT	如果要打开的文件不存在，则自动创建该文件，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `Windows` `macOS` `OHOS`
O_DSYNC	每次写入都会等待物理 `I/O` 完成，但如果写操作不影响读取刚写入的数据，则不等待文件属性更新，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `macOS` `OHOS`
O_EXCL	如同时设置 `O_CREAT`，则此指令检查文件是否存在。如果文件不存在，则创建文件。否则，打开文件出错。此外，如果同时设置了 `O_CREAT` 和 `O_EXCL`，并且要打开的文件是符号链接，则打开文件失败，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `Windows` `macOS` `OHOS`
O_NOCTTY	如要打开的文件是终端设备，则该文件不会成为这个进程的控制终端，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `macOS` `OHOS`
O_NOFOLLOW	如 `pathname` 指定的文件是单符号连接，则打开文件失败，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `macOS` `OHOS`
O_NONBLOCK	以非阻塞的方式打开文件，即 `I/O` 操作不会导致调用进程等待，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `macOS` `OHOS`
O_SYNC	同步打开文件，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `macOS` `OHOS`
O_RDONLY	以只读方式打开文件，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `Windows` `macOS` `OHOS`
O_RDWR	以读写模式打开文件，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `Windows` `macOS` `OHOS`
O_WRONLY	以只写方式打开文件，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `Windows` `macOS` `OHOS`
O_APPEND	读取或写入文件时，数据将从文件末尾移动。即写入的数据将附加到文件的末尾，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `Windows` `macOS` `OHOS`
O_RSYNC	此标志仅影响读取操作，必须与 `O_SYNC` 或 `O_DSYNC` 结合使用。如果有必要，它将导致读取调用阻塞，直到正在读取的数据（可能还有元数据）刷新到磁盘，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `OHOS`
O_TRUNC	如果文件存在且打开可写，则此标志将文件长度清除为 0，文件中以前存储的数据消失，适用函数 `open`、`open64`、`openat`、`openat64`，所属函数参数 `oflag`。	`Linux` `Windows` `macOS` `OHOS`
R_OK	测试文件读权限，适用函数 `access`，`faccessat`，所属函数参数 `mode`。	`Linux` `Windows` `macOS` `OHOS`
W_OK	测试文件写权限，适用函数 `access`，`faccessat`，所属函数参数 `mode`。	`Linux` `Windows` `macOS` `OHOS`
X_OK	测试文件执行权限，适用函数 `access`，`faccessat`，所属函数参数 `mode`。	`Linux` `Windows` `macOS` `OHOS`
F_OK	测试文件是否存在，适用函数 `access`，`faccessat`，所属函数参数 `mode`。	`Linux` `Windows` `macOS` `OHOS`
SEEK_SET	偏移参数表示新的读写位置，适用函数 `lseek`，所属函数参数 `whence`。	`Linux` `Windows` `macOS` `OHOS`
SEEK_CUR	向当前读或写位置添加偏移量，适用函数 `lseek`，所属函数参数 `whence`。	`Linux` `Windows` `macOS` `OHOS`
SEEK_END	将读写位置设置为文件末尾，并添加偏移量，适用函数 `lseek`，所属函数参数 `whence`。	`Linux` `Windows` `macOS` `OHOS`
SIGABRT	异常终止，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGBUS	硬件故障，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGFPE	算术错误，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGKILL	终止，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGCONT	暂停过程的继续，默认操作继续或忽略，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGHUP	连接已断开，默认操作已终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGINT	终端中断字符，默认动作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGQUIT	终端退出字符，默认动作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGILL	硬件指令无效，默认动作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGTRAP	硬件故障，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGIOT	硬件故障，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGIO	异步 `IO`，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGPIPE	写入未读进程的管道，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGALRM	计时器到期，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGPWR	电源故障或重启，系统调用无效，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `OHOS`
SIGSEGV	内存引用无效，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGSTOP	停止，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGTERM	终止，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGSTKFLT	协处理器堆栈故障，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `OHOS`
SIGCHLD	子进程状态更改，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGTSTP	终端停止符号，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGTTIN	后台读取控件 `tty`，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGTTOU	后台写控制 `tty`，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGURG	紧急情况（套接字），忽略默认操作，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGUSR1	用户定义的信号，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGUSR2	用户定义的信号，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGVTALRM	虚拟时间警报，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGPROF	摘要超时，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGWINCH	终端窗口大小更改，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGXCPU	`CPU` 占用率超过上限，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
SIGXFSZ	文件长度超过上限，默认操作终止，适用函数 `kill`，`killpg`，所属函数参数 `sig`。	`Linux` `Windows` `macOS` `OHOS`
S_IRUSR	表示文件所有者具有读权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`
S_IWUSR	表示文件所有者具有写权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`
S_IRGRP	表示文件用户组具有读权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`
S_IWGRP	表示文件用户组具有写权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`
S_IFREG	文件类型为一般文件，适用函数 `isType`，所属函数参数 `mode`。	`Linux` `Windows` `macOS` `OHOS`
S_IFBLK	文件类型为块设备，适用函数 `isType`，所属函数参数 `mode`。	`Linux` `Windows` `macOS` `OHOS`
S_IFDIR	文件类型为目录，适用函数 `isType`，所属函数参数 `mode`。	`Linux` `Windows` `macOS` `OHOS`
S_IFCHR	文件类型为字符设备，适用函数 `isType`，所属函数参数 `mode`。	`Linux` `Windows` `macOS` `OHOS`
S_IFIFO	文件类型为 `FIFO` 文件，适用函数 `isType`，所属函数参数 `mode`。	`Linux` `Windows` `macOS` `OHOS`
S_IFLNK	文件类型为软连接，适用函数 `isType`，所属函数参数 `mode`。	`Linux` `Windows` `macOS` `OHOS`
S_IFSOCK	文件类型为套接字文件，适用函数 `isType`，所属函数参数 `mode`。	`Linux` `Windows` `macOS` `OHOS`
S_IROTH	表示其他用户对文件具有读权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`
S_IRWXG	表示文件用户组具有读、写、执行权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`
S_IRWXU	表示文件所有者具有读、写和执行权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`
S_IWOTH	表示其他用户对文件具有写权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`
S_IXOTH	表示其他用户对文件具有执行权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`
S_IRWXO	表示其他用户对文件具有读、写和执行权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`
S_IXGRP	表示文件用户组具有执行权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`
S_IXUSR	表示文件所有者具有执行权限，适用函数 `open`，`open64`，`openat`，`openat64`，`chmod(mode)`，`fchmod(mode)`，`fchmodat(mode)`，`creat`，所属函数参数 `flag`。	`Linux` `Windows` `macOS` `OHOS`

常量&变量

const AT_EMPTY_PATH

public const AT_EMPTY_PATH: Int32

功能：表示在文件系统中空路径（即没有指定任何文件或目录）时返回的文件描述符，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const AT_REMOVEDIR

public const AT_REMOVEDIR: Int32

功能：如果指定了 AT_REMOVEDIR 标志，则对 pathname 执行等效于 rmdir(2) 的操作，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const F_OK

public const F_OK: Int32

功能：测试文件是否存在，适用函数 access，faccessat，所属函数参数 mode。

类型：Int32

const O_APPEND

public const O_WRONLY: Int32

功能：读取或写入文件时，数据将从文件末尾移动。即写入的数据将附加到文件的末尾，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_CLOEXEC

public const O_CLOEXEC: Int32

功能：在某些多线程程序中，使用此标志是必不可少的。因为在一个线程同时打开文件描述符，而另一个线程执行 fork(2) 加 execve(2) 场景下使用单独的 fcntl(2) F_SETFD 操作设置 FD_CLOEXEC 标志并不足以避免竞争条件，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_CREAT

public const O_CREAT: Int32

功能：如果要打开的文件不存在，则自动创建该文件，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_DIRECTORY

public const O_DIRECTORY: Int32

功能：如果 pathname 指定的文件不是目录，则打开文件失败，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_DSYNC

public const O_DSYNC: Int32

功能：每次写入都会等待物理 I/O 完成，但如果写操作不影响读取刚写入的数据，则不等待文件属性更新，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_EXCL

public const O_EXCL: Int32

功能：如同时设置 O_CREAT，则此指令检查文件是否存在。如果文件不存在，则创建文件。否则，打开文件出错。此外，如果同时设置了 O_CREAT 和 O_EXCL，并且要打开的文件是符号链接，则打开文件失败，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_NOCTTY

public const O_NOCTTY: Int32

功能：如要打开的文件是终端设备，则该文件不会成为这个进程的控制终端，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_NOFOLLOW

public const O_NOFOLLOW: Int32

功能：如 pathname 指定的文件是单符号连接，则打开文件失败，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_NONBLOCK

public const O_NONBLOCK: Int32

功能：以非阻塞的方式打开文件，即 I/O 操作不会导致调用进程等待，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_RDONLY

public const O_RDONLY: Int32

功能：以只读方式打开文件，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_RDWR

public const O_RDWR: Int32

功能：以读写模式打开文件，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_RSYNC

public const O_RSYNC: Int32

功能：此标志仅影响读取操作，必须与 O_SYNC 或 O_DSYNC 结合使用。如果有必要，它将导致读取调用阻塞，直到正在读取的数据（可能还有元数据）刷新到磁盘，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_SYNC

public const O_SYNC: Int32

功能：同步打开文件，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_TRUNC

public const O_TRUNC: Int32

功能：如果文件存在且打开可写，则此标志将文件长度清除为 0，文件中以前存储的数据消失，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const O_WRONLY

public const O_WRONLY: Int32

功能：以只写方式打开文件，适用函数 open、open64、openat、openat64，所属函数参数 oflag。

类型：Int32

const R_OK

public const R_OK: Int32

功能：测试文件读权限，适用函数 access，faccessat，所属函数参数 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

功能：异常终止，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGALRM

public const SIGALRM: Int32

功能：计时器到期，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGBUS

public const SIGBUS: Int32

功能：硬件故障，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGCHLD

public const SIGCHLD: Int32

功能：子进程状态更改，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGCONT

public const SIGCONT: Int32

功能：暂停过程的继续，默认操作继续或忽略，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGFPE

public const SIGFPE: Int32

功能：算术错误，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGHUP

public const SIGHUP: Int32

功能：连接已断开，默认操作已终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGILL

public const SIGILL: Int32

功能：硬件指令无效，默认动作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGINT

public const SIGINT: Int32

功能：终端中断字符，默认动作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGIO

public const SIGIO: Int32

功能：异步 IO，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGIOT

public const SIGIOT: Int32

功能：硬件故障，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGKILL

public const SIGKILL: Int32

功能：终止，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGPIPE

public const SIGPIPE: Int32

功能：写入未读进程的管道，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGPROF

public const SIGPROF: Int32

功能：摘要超时，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGPWR

public const SIGPWR: Int32

功能：电源故障或重启，系统调用无效，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGQUIT

public const SIGQUIT: Int32

功能：终端退出字符，默认动作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGSEGV

public const SIGSEGV: Int32

功能：内存引用无效，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGSTKFLT

public const SIGSTKFLT: Int32

功能：协处理器堆栈故障，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGSTOP

public const SIGSTOP: Int32

功能：停止，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGTERM

public const SIGTERM: Int32

功能：终止，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGTRAP

public const SIGTRAP: Int32

功能：硬件故障，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGTSTP

public const SIGTSTP: Int32

功能：终端停止符号，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGTTIN

public const SIGTTIN: Int32

功能：后台读取控件 tty，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGTTOU

public const SIGTTOU: Int32

功能：后台写控制 tty，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGURG

public const SIGURG: Int32

功能：紧急情况（套接字），忽略默认操作，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGUSR1

public const SIGUSR1: Int32

功能：用户定义的信号，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGUSR2

public const SIGUSR2: Int32

功能：用户定义的信号，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGVTALRM

public const SIGVTALRM: Int32

功能：虚拟时间警报，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGWINCH

public const SIGWINCH: Int32

功能：终端窗口大小更改，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGXCPU

public const SIGXCPU: Int32

功能：CPU 占用率超过上限，默认操作终止，适用函数 kill，killpg，所属函数参数 sig。

类型：Int32

const SIGXFSZ

public const SIGXFSZ: Int32

功能：文件长度超过上限，默认操作终止，适用函数 kill，killpg，所属函数参数 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

功能：测试文件写权限，适用函数 access，faccessat，所属函数参数 mode。

类型：UInt32

const X_OK

public const X_OK: Int32

功能：测试文件执行权限，适用函数 access，faccessat，所属函数参数 mode。

类型：Int32

函数

func `open`(String, Int32)

public func `open`(path: String, oflag: Int32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。

说明：

当文件打开方式参数 oflag 设置为 O_CREAT 时，可以通过参数设置文件权限。

O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 。

参数：

path: String - 文件路径。
oflag: Int32 - 文件打开的方式。

返回值：

Int32 - 返回新的文件描述符，执行失败时返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

func `open`(String, Int32, UInt32)

public func `open`(path: String, oflag: Int32, flag: UInt32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。path 代表文件路径，oflag 代表文件打开的方式，其中 O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 操作。

说明：

当文件打开方式参数 oflag 设置为 O_CREAT 时，可以通过参数设置文件权限。

O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 。

参数：

path: String - 文件路径。
oflag: Int32 - 文件打开的方式。
flag: UInt32 - 如果 oflag 设置了 O_CREAT 并且需要创建新文件，则 flag 参数标识对新文件的权限，否则 flag 不改变文件权限。

返回值：

Int32 - 返回新的文件描述符，执行失败时返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

func access(String, Int32)

public func access(path: String, mode: Int32): Int32

功能：判断某个文件是否具有某种权限，具有返回 0，否则返回 -1。

说明：

mode 为指定权限，传入类型 R_OK、W_OK、X_OK、F_OK。

参数：

path: String - 文件路径。
mode: Int32 - 待检查的权限。

返回值：

Int32 - 文件具有待检查的权限返回 0，否则返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

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。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

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。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

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。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

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_OK、W_OK、X_OK、F_OK。

参数：

fd: Int32 - 文件描述符。
path: String - 文件路径。
mode: Int32 - 待检查的权限。
flag: Int32 - 将以下一个或多个值按位或运算获取。(512)使用有效的用户和组 ID 执行访问检查，默认情况下使用有效 ID；(256) 如果路径名是符号链接，不会取消引用而是返回有关链接本身信息。

返回值：

Int32 - 文件具有待检查的权限返回 0，否则返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

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。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

func fchmodat(Int32, String, UInt32, Int32)

public func fchmodat(fd: Int32, path: String, mode: UInt32, flag: Int32): Int32

功能：修改文件描述符对应的文件访问权限。

说明：

path 为相对路径且 fd 为特殊值 AT_FDCWD 时，则路径将相对于调用进程的当前工作目录。

path 为相对路径且 fd 非 AT_FDCWD 时，则路径将相对于 fd 引用的文件所属目录。

path 为绝对路径时 fd 参数将被忽略。

参数：

fd: Int32 - 文件描述符。
path: String - 文件路径。
mode: UInt32 - 要修改的权限。
flag: Int32 - 取值可为 0，或 (256) 如果路径名是符号链接，不会取消引用它，而是返回有关链接本身的信息。

返回值：

Int32 - 操作成功时返回 0，失败时返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

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 为相对路径且 fd 非 AT_FDCWD 时，则路径将相对于 fd 引用的文件所属目录。

path 为绝对路径时 fd 参数将被忽略。

参数：

fd: Int32 - 文件描述符。
path: String - 文件路径。
owner: UInt32 - 所有者 uid。
group: UInt32 - 指定 gid 参数。
flag: Int32 - 取值可为 0，或 (256) 如果路径名是符号链接，不会取消引用它，而是返回有关链接本身的信息。

返回值：

Int32 - 操作成功时返回 0，失败时返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

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，如果 pgrp 为 0，则 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。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

func link(String, String)

public func link(path: String, newpath: String): Int32

功能：为存在的文件创建链接，一个文件可以有多个指向其 i-node 的目录条目。

参数：

path: String - 文件路径。
newpath: String - 其他文件路径。

返回值：

Int32 - 成功返回 0，错误返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 或 newPath 包含空字符时，抛出异常。

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 为相对路径且 fd 非 AT_FDCWD 时，则路径将相对于 fd 引用的文件所属目录。

path 为绝对路径时 fd 参数将被忽略。

newPath 的场景与 path 相同，只是当 newPath 为相对路径时是相对于 nfd 引用的文件所属目录。

参数：

fd: Int32 - 文件描述符。
path: String - 文件路径。
nfd: Int32 - 其他文件描述符。
newPath: String - 其他文件路径，如果 newpath 存在，则不会覆盖。
lflag: Int32 - AT_EMPTY_PATH 或 AT_SYMLINK_FOLLOW 或 0。

返回值：

Int32 - 成功返回 0，错误返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 或 newPath 包含空字符时，抛出异常。

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。

成功时返回新值，失败时返回 -1。 inc 在值大于 19 时，返回最大值 19。

参数：

inc: Int32 - 当前进程的优先级, 值的范围是 +19（低优先级）到 -20。

返回值：

Int32 - 返回新优先级值。

func open64(String, Int32)

public func open64(path: String, oflag: Int32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。

说明：

当文件打开方式参数 oflag 设置为 O_CREAT 时，可以通过参数设置文件权限。

O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 。

参数：

path: String - 文件路径。
oflag: Int32 - 文件打开的方式。

返回值：

Int32 - 返回新的文件描述符，执行失败时返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

func open64(String, Int32, UInt32)

public func open64(path: String, oflag: Int32, flag: UInt32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。

说明：

当文件打开方式参数 oflag 设置为 O_CREAT 时，可以通过参数设置文件权限。

O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 。

参数：

path: String - 文件路径。
oflag: Int32 - 文件打开的方式。
flag: UInt32 - 如果 oflag 设置了 O_CREAT 并且需要创建新文件，则 flag 参数标识对新文件的权限，否则 flag 不改变文件权限。

返回值：

Int32 - 返回新的文件描述符，执行失败时返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

func openat(Int32, String, Int32)

public func openat(fd: Int32, path: String, oflag: Int32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。

说明：

当文件打开方式参数 oflag 设置为 O_CREAT 时，可以通过参数设置文件权限。

O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 。

参数：

fd: Int32 - 路径的文件描述符。
path: String - 文件路径。
oflag: Int32 - 文件打开的方式。

返回值：

Int32 - 返回新的文件描述符，执行失败时返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

func openat(Int32, String, Int32, UInt32)

public func openat(fd: Int32, path: String, oflag: Int32, flag: UInt32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。

说明：

当文件打开方式参数 oflag 设置为 O_CREAT 时，可以通过参数设置文件权限。

O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 。

参数：

fd: Int32 - 路径的文件描述符。
path: String - 文件路径。
oflag: Int32 - 文件打开的方式。
flag: UInt32 - 如果 oflag 设置了 O_CREAT 并且需要创建新文件，则 flag 参数标识对新文件的权限，否则 flag 不改变文件权限。

返回值：

Int32 - 返回新的文件描述符，执行失败时返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

func openat64(Int32, String, Int32)

public func openat64(fd: Int32, path: String, oflag: Int32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。

说明：

当文件打开方式参数 oflag 设置为 O_CREAT 时，可以通过参数设置文件权限。

O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 。

参数：

fd: Int32 - 路径的文件描述符。
path: String - 文件路径。
oflag: Int32 - 文件打开的方式。

返回值：

Int32 - 返回新的文件描述符，执行失败时返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

func openat64(Int32, String, Int32, UInt32)

public func openat64(fd: Int32, path: String, oflag: Int32, flag: UInt32): Int32

功能：打开文件并为其返回新的文件描述符，或在失败时返回 -1。

说明：

当文件打开方式参数 oflag 设置为 O_CREAT 时，可以通过参数设置文件权限。

O_RDONLY、O_RDWR、O_WRONLY 作为 oflag 取值为互斥关系，但可以与其他操作标识一起使用，如 O_APPEND 。

参数：

fd: Int32 - 路径的文件描述符。
path: String - 文件路径。
oflag: Int32 - 文件打开的方式。
flag: UInt32 - 如果 oflag 设置了 O_CREAT 并且需要创建新文件，则 flag 参数标识对新文件的权限，否则 flag 不改变文件权限。

返回值：

Int32 - 返回新的文件描述符，执行失败时返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

func pread(Int32, CPointer<UInt8>, UIntNative, Int32)

public unsafe func pread(fd: Int32, buffer: CPointer<UInt8>, nbyte: UIntNative, offset: Int32): IntNative

功能：将 fd 指向的文件的 nbyte 字节传输到 buffer 指向的内存中。如果 nbyte 为 0，则函数无效果，并返回 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

说明：

建议 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。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

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。

异常：

IllegalArgumentException - 当函数参数 oldName 或 newName 包含空字符时，抛出异常。

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 为相对路径且 oldfd 非 AT_FDCWD 时，则路径将相对于 oldfd 引用的文件所属目录。

oldName 为绝对路径时 oldfd 参数将被忽略。

newName 的场景与 oldName 相同，只是当 newName 为相对路径时是相对于 newfd 引用的文件所属目录。

参数：

oldfd: Int32 - 文件描述符。
oldName: String - 文件名。
newName: String - 文件名。
newfd: Int32 - 文件描述符。

返回值：

Int32 - 成功返回 0，错误返回 -1。

异常：

IllegalArgumentException - 当函数参数 oldName 或 newName 包含空字符时，抛出异常。

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。

异常：

IllegalArgumentException - 如果参数 buf 包含空字符则抛出异常。

func setpgid(Int32, Int32)

public func setpgid(pid: Int32, pgrp: Int32): Int32

功能：此函数将参数 pid 指定的组 ID 设置为参数 pgrp 指定的组 ID。如果 pid 为 0，则使用当前进程的组 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。

异常：

IllegalArgumentException - 当函数参数 path 或 symPath 包含空字符时，抛出异常。

func symlinkat(String, Int32, String)

public func symlinkat(path: String, fd: Int32, symPath: String): Int32

功能：创建一个名为 symPath 链接到 path 与 fd 所指定的文件。

说明：

symPath 为相对路径且 fd 为特殊值 AT_FDCWD 时，则路径将相对于调用进程的当前工作目录。

symPath 为相对路径且 fd 非 AT_FDCWD 时，则路径将相对于 fd 引用的文件所属目录。

symPath 为绝对路径时 fd 参数将被忽略。

参数：

path: String - 文件路径。
fd: Int32 - 文件描述符。
symPath: String - 链接文件路径。

返回值：

Int32 - 成功返回 0，错误返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 或 symPath 包含空字符时，抛出异常。

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。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

func unlinkat(Int32, String, Int32)

public func unlinkat(fd: Int32, path: String, ulflag: Int32): Int32

功能：从文件系统中删除文件。

说明：

该函数系统调用的操作方式与 unlink 函数完全相同，但此处描述的差异除外：

path 为相对路径且 fd 为特殊值 AT_FDCWD 时，则路径将相对于调用进程的当前工作目录。

path 为相对路径且 fd 非 AT_FDCWD 时，则路径将相对于 fd 引用的文件所属目录。

path 为绝对路径时 fd 参数将被忽略。

参数：

fd: Int32 - 文件描述符。
path: String - 文件路径。
ulflag: Int32 - 可以指定为 0，或者可以设置为控制 unlinkat() 操作的标志值按位或运算。标志值当前取值仅支持 AT_REMOVEDIR。

返回值：

Int32 - 成功返回 0，错误返回 -1。

异常：

IllegalArgumentException - 当函数参数 path 包含空字符时，抛出异常。

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 - 待写入文件的文件描述符。
buffer - 缓冲区容器。
nbyte - 写入字节数，建议采用 buffer.size。

返回值：返回实际写入数，执行失败时返回 -1。

文件内容相关操作

下面是文件内容相关操作示例。

代码如下:

import std.os.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.os.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.os.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.os.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.os.process 包

功能介绍

os.process 包主要提供 Process 进程操作接口，主要包括进程创建，标准流获取，进程等待，进程信息查询等。

本包提供多平台统一操控能力，目前支持 Linux 平台，macOS 平台，Windows 平台与 OHOS 平台。

API 列表

类

类名	功能
CurrentProcess	此类为当前进程类，继承 `Process` 类，提供对当前进程操作相关功能。
Process	此类为进程类，提供进程操作相关功能。
SubProcess	此类为子进程类，继承 `Process` 类，提供对子进程操作相关功能。

枚举

枚举名	功能
ProcessRedirect	用于在创建进程时设置子进程标准流的重定向模式。

异常类

异常类名	功能
ProcessException	`os.process` 包的异常类。

兼容性说明

class Process

成员	支持平台
current	`Linux` `Windows` `macOS` `OHOS`
pid	`Linux` `Windows` `macOS` `OHOS`
name	`Linux` `Windows` `macOS` `OHOS`
command	`Linux` `Windows` `macOS` `OHOS`
arguments	`Linux` `macOS` `OHOS`
commandLine	`Linux` `macOS` `OHOS`
workingDirectory	`Linux` `macOS` `OHOS`
environment	`Linux` `OHOS`
of(Int64)	`Linux` `Windows` `macOS` `OHOS`
start(String, Array, Path, Map<String, String>, ProcessRedirect, ProcessRedirect, ProcessRedirect)	`Linux` `Windows` `macOS` `OHOS`
run(String, Array, Path, Map<String, String>, ProcessRedirect, ProcessRedirect, ProcessRedirect, Duration)	`Linux` `Windows` `macOS` `OHOS`
runOutput(String, Array, Path, Map<String, String>, ProcessRedirect, ProcessRedirect, ProcessRedirect)	`Linux` `Windows` `macOS` `OHOS`
terminate(Bool)	`Linux` `Windows` `macOS` `OHOS`

class CurrentProcss

成员	支持平台
stdIn	`Linux` `Windows` `macOS` `OHOS`
stdOut	`Linux` `Windows` `macOS` `OHOS`
stdErr	`Linux` `Windows` `macOS` `OHOS`
atExit(() -> Unit)	`Linux` `Windows` `macOS` `OHOS`
exit(Int64)	`Linux` `Windows` `macOS` `OHOS`

class SubProcess

成员	支持平台
stdIn	`Linux` `Windows` `macOS` `OHOS`
stdOut	`Linux` `Windows` `macOS` `OHOS`
stdErr	`Linux` `Windows` `macOS` `OHOS`
wait(Duration)	`Linux` `Windows` `macOS` `OHOS`
waitOutput()	`Linux` `Windows` `macOS` `OHOS`

类

class CurrentProcess

public class CurrentProcess <: Process

功能：此类为当前进程类，继承 Process 类，提供对当前进程操作相关功能。

说明：

提供功能具体如下：

提供获取当前进程标准流（stdIn、stdOut、stdErr）机制。

提供当前进程退出注册回调函数机制。

提供当前进程退出机制，允许设置退出状态码。

prop stdErr

public prop stdErr: OutputStream

功能：获取当前进程标准错误流。

类型：OutputStream

prop stdIn

public prop stdIn: InputStream

功能：获取当前进程标准输入流。

类型：InputStream

prop stdOut

public prop stdOut: OutputStream

功能：获取当前进程标准输出流。

类型：OutputStream

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 - 当前进程退出状态码。

class Process

public open class Process

功能：此类为进程类，提供进程操作相关功能。

说明：

提供功能具体如下：

提供获取当前进程实例的功能。

提供根据进程 id 绑定进程实例的功能。

提供根据输入信息创建子进程的功能。

提供获取进程信息的功能。

提供关闭进程的功能，允许设置是否强制关闭进程。

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 current

public static prop current: CurrentProcess

功能：获取当前进程实例。

类型：CurrentProcess

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 对应的进程实例。

异常：

IllegalArgumentException - 当输入进程 id 大于 Int32 最大值或小于 0时，抛出异常。
ProcessException - 当内存分配失败或 pid 对应的进程不存在时，抛出异常。

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 字符串中包含空字符，或者 stdIn、stdOut、stdErr 输入为文件模式，输入的文件已被关闭或删除时，抛出异常。
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 字符串中包含空字符，或者 stdIn、stdOut、stdErr 输入为文件模式，输入的文件已被关闭或删除时，抛出异常。
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

功能：根据输入参数创建并运行一个子进程，并返回一个子进程实例。调用该函数创建子进程后，需要调用 wait 或 waitOutput 函数，否则该子进程结束后成为的僵尸进程的资源不会被回收。

参数：

command: String - 指定子进程命令，command 不允许包含空字符。
arguments: Array<String> - 指定子进程参数，arguments 不允许数组中字符串中包含空字符。
workingDirectory!: ?Path - 命名可选参数，指定子进程的工作路径，默认继承当前进程工作路径，路径必须为存在的目录且不允许为空路径或包含空字符。
environment!: ?Map<String, String> - 命名可选参数，指定子进程环境变量，默认继承当前进程环境变量，key 不允许字符串中包含空字符或 '='，value 不允许字符串中包含空字符。
stdIn!: ProcessRedirect - 命名可选参数，指定子进程重定向标准输入，默认继承当前进程标准输入。
stdOut!: ProcessRedirect - 命名可选参数，指定子进程重定向标准输出，默认继承当前进程标准输出。
stdErr!: ProcessRedirect - 命名可选参数，指定子进程重定向标准错误，默认继承当前进程标准错误。

返回值：

SubProcess - 返回一个子进程实例。

异常：

IllegalArgumentException - 当入参 command 包含空字符，或者 arguments 数组中字符串中包含空字符，或者 workingDirectory 不是存在的目录或为空路径或包含空字符，或者 environment 表中 key 字符串中包含空字符或 '='，或 value 字符串中包含空字符，或者 stdIn、stdOut、stdErr 输入为文件模式，输入的文件已被关闭或删除时，抛出异常。
ProcessException - 当内存分配失败或 command 对应的命令不存在时，抛出异常。

func terminate(Bool)

public func terminate(force!: Bool = false): Unit

功能：终止进程。

参数：

force!: Bool - 命名可选参数，指定是否强制关闭进程，默认为 false，若设置为 false，对应进程可以在释放资源后结束；若设置为 true，对应进程将被直接杀死。Windows 平台实现为强制关闭进程。

返回值：

Unit - 子进程执行返回结果，包含子进程退出状态（若子进程正常退出，返回子进程退出码，若子进程被信号杀死，返回导致子进程终止的信号编号），进程标准输出结果和进程错误结果。

异常：

ProcessException - 如果进程不存在，不允许终止，则抛出异常。

class SubProcess

public class SubProcess <: Process

功能：此类为子进程类，继承 Process 类，提供对子进程操作相关功能。

说明：

提供功能具体如下：

提供获取子进程标准流（stdIn、stdOut、stdErr）机制。

提供等待子进程执行返回退出状态码机制，允许设置等待超时时长。

提供等待子进程执行返回输出结果(包含运行正常、异常结果)机制，允许设置等待超时时长。

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 - 返回子进程退出状态。若子进程正常退出，返回子进程退出码，若子进程被信号杀死，返回导致子进程终止的信号编号。

异常：

ProcessException - 当等待超时，子进程未退出时，抛出异常。

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 <: Exception {
    init(message: String)
}

功能：os.process 包的异常类。

init(String)

public init(message: String)

功能：创建 ProcessException 实例。

参数：

message: String - 异常提示信息。

当前进程相关操作

下面是当前进程相关操作示例，以下示例不支持 Windows 平台。

代码如下：

import std.os.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.os.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 {
            File.delete(".\\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.os.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.os.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 包提供了四种溢出处理策略，并定义了对应的接口，列举如下：

策略	接口	描述
返回 Option	CheckedOp	当整数运算出现溢出，返回 `None`。
饱和	SaturatingOp	当计算结果大于目标类型的 MAX 值，返回 MAX 值；当计算结果小于目标类型的 MIN 值，返回 MIN 值。
抛出异常	ThrowingOp	当整数运算出现溢出，抛出异常。
高位截断	WrappingOp	当整数运算出现溢出，将运算结果中超出目标类型位数的高位截断。

overflow 包中通过扩展为所有的整数类型提供了这些接口的实现，用户可以用同样的方式为其他类型实现 overflow 接口。

API 列表

接口

接口名	功能
CheckedOp	当整数运算出现溢出，返回 `None`。
SaturatingOp	当整数运算出现溢出，饱和处理。
ThrowingOp	当整数运算出现溢出，抛出异常。
WrappingOp	当整数运算出现溢出，将运算结果中超出目标类型位数的高位截断。

异常类

类名	功能
OvershiftException	移位运算时移位位数超过操作数位数时抛出的异常。
UndershiftException	移位运算时移位位数小于 0 时抛出的异常。

接口

interface CheckedOp

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，否则返回运算结果。

参数：

y: Int16 - 加数。

返回值：

?Int16 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?Int16

功能：使用返回 Option 策略的自减运算。

当运算出现溢出时，返回 ?Int16.None，否则返回运算结果。

返回值：

?Int16 - 自减运算结果。

func checkedDiv(Int16)

public func checkedDiv(y: Int16): ?Int16

功能：使用返回 Option 策略的除法运算。

当运算出现溢出时，返回 ?Int16.None，否则返回运算结果。

参数：

y: Int16 - 除数。

返回值：

?Int16 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?Int16

功能：使用返回 Option 策略的自增运算。

当运算出现溢出时，返回 ?Int16.None，否则返回运算结果。

返回值：

?Int16 - 自增运算结果。

func checkedMod(Int16)

public func checkedMod(y: Int16): ?Int16

功能：使用返回 Option 策略的取余运算。

当运算出现溢出时，返回 ?Int16.None，否则返回运算结果。

参数：

y: Int16 - 除数。

返回值：

?Int16 - 取余运算结果。

func checkedMul(Int16)

public func checkedMul(y: Int16): ?Int16

功能：使用返回 Option 策略的乘法运算。

当运算出现溢出时，返回 ?Int16.None，否则返回运算结果。

参数：

y: Int16 - 乘数。

返回值：

?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，否则返回运算结果。

参数：

y: Int16 - 减数。

返回值：

?Int16 - 减法运算结果。

extend Int32 <: CheckedOp

extend Int32 <: CheckedOp<Int32>

功能：为 Int32 实现 CheckedOp 接口。

func checkedAdd(Int32)

public func checkedAdd(y: Int32): ?Int32

功能：使用返回 Option 策略的加法运算。

当运算出现溢出时，返回 ?Int32.None，否则返回运算结果。

参数：

y: Int32 - 加数。

返回值：

?Int32 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?Int32

功能：使用返回 Option 策略的自减运算。

当运算出现溢出时，返回 ?Int32.None，否则返回运算结果。

返回值：

?Int32 - 自减运算结果。

func checkedDiv(Int32)

public func checkedDiv(y: Int32): ?Int32

功能：使用返回 Option 策略的除法运算。

当运算出现溢出时，返回 ?Int32.None，否则返回运算结果。

参数：

y: Int32 - 除数。

返回值：

?Int32 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?Int32

功能：使用返回 Option 策略的自增运算。

当运算出现溢出时，返回 ?Int32.None，否则返回运算结果。

返回值：

?Int32 - 自增运算结果。

func checkedMod(Int32)

public func checkedMod(y: Int32): ?Int32

功能：使用返回 Option 策略的取余运算。

当运算出现溢出时，返回 ?Int32.None，否则返回运算结果。

参数：

y: Int32 - 除数。

返回值：

?Int32 - 取余运算结果。

func checkedMul(Int32)

public func checkedMul(y: Int32): ?Int32

功能：使用返回 Option 策略的乘法运算。

当运算出现溢出时，返回 ?Int32.None，否则返回运算结果。

参数：

y: Int32 - 乘数。

返回值：

?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，否则返回运算结果。

参数：

y: Int32 - 减数。

返回值：

?Int32 - 减法运算结果。

extend Int64 <: CheckedOp

extend Int64 <: CheckedOp<Int64>

功能：为 Int64 实现 CheckedOp 接口。

func checkedAdd(Int64)

public func checkedAdd(y: Int64): ?Int64

功能：使用返回 Option 策略的加法运算。

当运算出现溢出时，返回 ?Int64.None，否则返回运算结果。

参数：

y: Int64 - 加数。

返回值：

?Int64 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?Int64

功能：使用返回 Option 策略的自减运算。

当运算出现溢出时，返回 ?Int64.None，否则返回运算结果。

返回值：

?Int64 - 自减运算结果。

func checkedDiv(Int64)

public func checkedDiv(y: Int64): ?Int64

功能：使用返回 Option 策略的除法运算。

当运算出现溢出时，返回 ?Int64.None，否则返回运算结果。

参数：

y: Int64 - 除数。

返回值：

?Int64 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?Int64

功能：使用返回 Option 策略的自增运算。

当运算出现溢出时，返回 ?Int64.None，否则返回运算结果。

返回值：

?Int64 - 自增运算结果。

func checkedMod(Int64)

public func checkedMod(y: Int64): ?Int64

功能：使用返回 Option 策略的取余运算。

当运算出现溢出时，返回 ?Int64.None，否则返回运算结果。

参数：

y: Int64 - 除数。

返回值：

?Int64 - 取余运算结果。

func checkedMul(Int64)

public func checkedMul(y: Int64): ?Int64

功能：使用返回 Option 策略的乘法运算。

当运算出现溢出时，返回 ?Int64.None，否则返回运算结果。

参数：

y: Int64 - 乘数。

返回值：

?Int64 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?Int64

功能：使用返回 Option 策略的负号运算。

当运算出现溢出时，返回 ?Int64.None，否则返回运算结果。

返回值：

?Int64 - 负号运算结果。

func checkedPow(UInt64)

public func checkedPow(y: UInt64): ?Int64

功能：使用返回 Option 策略的幂运算。

当运算出现溢出时，返回 ?Int64.None，否则返回运算结果。

参数：

y: UInt64 - 指数。

返回值：

?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，否则返回运算结果。

参数：

y: Int64 - 减数。

返回值：

?Int64 - 减法运算结果。

extend Int8 <: CheckedOp

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

extend IntNative <: CheckedOp<IntNative>

功能：为 IntNative 实现 CheckedOp 接口。

func checkedAdd(IntNative)

public func checkedAdd(y: IntNative): ?IntNative

功能：使用返回 Option 策略的加法运算。

当运算出现溢出时，返回 ?IntNative.None，否则返回运算结果。

参数：

y: IntNative - 加数。

返回值：

?IntNative - 加法运算结果。

func checkedDec()

public func checkedDec(): ?IntNative

功能：使用返回 Option 策略的自减运算。

当运算出现溢出时，返回 ?IntNative.None，否则返回运算结果。

返回值：

?IntNative - 自减运算结果。

func checkedDiv(IntNative)

public func checkedDiv(y: IntNative): ?IntNative

功能：使用返回 Option 策略的除法运算。

当运算出现溢出时，返回 ?IntNative.None，否则返回运算结果。

参数：

y: IntNative - 除数。

返回值：

?IntNative - 除法运算结果。

func checkedInc()

public func checkedInc(): ?IntNative

功能：使用返回 Option 策略的自增运算。

当运算出现溢出时，返回 ?IntNative.None，否则返回运算结果。

返回值：

?IntNative - 自增运算结果。

func checkedMod(IntNative)

public func checkedMod(y: IntNative): ?IntNative

功能：使用返回 Option 策略的取余运算。

当运算出现溢出时，返回 ?IntNative.None，否则返回运算结果。

参数：

y: IntNative - 除数。

返回值：

?IntNative - 取余运算结果。

func checkedMul(IntNative)

public func checkedMul(y: IntNative): ?IntNative

功能：使用返回 Option 策略的乘法运算。

当运算出现溢出时，返回 ?IntNative.None，否则返回运算结果。

参数：

y: IntNative - 乘数。

返回值：

?IntNative - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?IntNative

功能：使用返回 Option 策略的负号运算。

当运算出现溢出时，返回 ?IntNative.None，否则返回运算结果。

返回值：

?IntNative - 负号运算结果。

func checkedShl(IntNative)

public func checkedShl(y: IntNative): ?IntNative

功能：使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，返回 ?IntNative.None，否则返回运算结果。

参数：

y: IntNative - 移位位数。

返回值：

?IntNative - 左移运算结果。

func checkedShr(IntNative)

public func checkedShr(y: IntNative): ?IntNative

功能：使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数或小于 0 时，返回 ?IntNative.None，否则返回运算结果。

参数：

y: IntNative - 移位位数。

返回值：

?IntNative - 右移运算结果。

func checkedSub(IntNative)

public func checkedSub(y: IntNative): ?IntNative

功能：使用返回 Option 策略的减法运算。

当运算出现溢出时，返回 ?IntNative.None，否则返回运算结果。

参数：

y: IntNative - 减数。

返回值：

?IntNative - 减法运算结果。

extend UInt16 <: CheckedOp

extend UInt16 <: CheckedOp<UInt16>

功能：为 UInt16 实现 CheckedOp 接口。

func checkedAdd(UInt16)

public func checkedAdd(y: UInt16): ?UInt16

功能：使用返回 Option 策略的加法运算。

当运算出现溢出时，返回 ?UInt16.None，否则返回运算结果。

参数：

y: UInt16 - 加数。

返回值：

?UInt16 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?UInt16

功能：使用返回 Option 策略的自减运算。

当运算出现溢出时，返回 ?UInt16.None，否则返回运算结果。

返回值：

?UInt16 - 自减运算结果。

func checkedDiv(UInt16)

public func checkedDiv(y: UInt16): ?UInt16

功能：使用返回 Option 策略的除法运算。

当运算出现溢出时，返回 ?UInt16.None，否则返回运算结果。

参数：

y: UInt16 - 除数。

返回值：

?UInt16 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?UInt16

功能：使用返回 Option 策略的自增运算。

当运算出现溢出时，返回 ?UInt16.None，否则返回运算结果。

返回值：

?UInt16 - 自增运算结果。

func checkedMod(UInt16)

public func checkedMod(y: UInt16): ?UInt16

功能：使用返回 Option 策略的取余运算。

当运算出现溢出时，返回 ?UInt16.None，否则返回运算结果。

参数：

y: UInt16 - 除数。

返回值：

?UInt16 - 取余运算结果。

func checkedMul(UInt16)

public func checkedMul(y: UInt16): ?UInt16

功能：使用返回 Option 策略的乘法运算。

当运算出现溢出时，返回 ?UInt16.None，否则返回运算结果。

参数：

y: UInt16 - 乘数。

返回值：

?UInt16 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?UInt16

功能：使用返回 Option 策略的负号运算。

当运算出现溢出时，返回 ?UInt16.None，否则返回运算结果。

返回值：

?UInt16 - 负号运算结果。

func checkedShl(UInt16)

public func checkedShl(y: UInt16): ?UInt16

功能：使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数时，返回 ?UInt16.None，否则返回运算结果。

参数：

y: UInt16 - 移位位数。

返回值：

?UInt16 - 左移运算结果。

func checkedShr(UInt16)

public func checkedShr(y: UInt16): ?UInt16

功能：使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数时，返回 ?UInt16.None，否则返回运算结果。

参数：

y: UInt16 - 移位位数。

返回值：

?UInt16 - 右移运算结果。

func checkedSub(UInt16)

public func checkedSub(y: UInt16): ?UInt16

功能：使用返回 Option 策略的减法运算。

当运算出现溢出时，返回 ?UInt16.None，否则返回运算结果。

参数：

y: UInt16 - 减数。

返回值：

?UInt16 - 减法运算结果。

extend UInt32 <: CheckedOp

extend UInt32 <: CheckedOp<UInt32>

功能：为 UInt32 实现 CheckedOp 接口。

func checkedAdd(UInt32)

public func checkedAdd(y: UInt32): ?UInt32

功能：使用返回 Option 策略的加法运算。

当运算出现溢出时，返回 ?UInt32.None，否则返回运算结果。

参数：

y: UInt32 - 加数。

返回值：

?UInt32 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?UInt32

功能：使用返回 Option 策略的自减运算。

当运算出现溢出时，返回 ?UInt32.None，否则返回运算结果。

返回值：

?UInt32 - 自减运算结果。

func checkedDiv(UInt32)

public func checkedDiv(y: UInt32): ?UInt32

功能：使用返回 Option 策略的除法运算。

当运算出现溢出时，返回 ?UInt32.None，否则返回运算结果。

参数：

y: UInt32 - 除数。

返回值：

?UInt32 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?UInt32

功能：使用返回 Option 策略的自增运算。

当运算出现溢出时，返回 ?UInt32.None，否则返回运算结果。

返回值：

?UInt32 - 自增运算结果。

func checkedMod(UInt32)

public func checkedMod(y: UInt32): ?UInt32

功能：使用返回 Option 策略的取余运算。

当运算出现溢出时，返回 ?UInt32.None，否则返回运算结果。

参数：

y: UInt32 - 除数。

返回值：

?UInt32 - 取余运算结果。

func checkedMul(UInt32)

public func checkedMul(y: UInt32): ?UInt32

功能：使用返回 Option 策略的乘法运算。

当运算出现溢出时，返回 ?UInt32.None，否则返回运算结果。

参数：

y: UInt32 - 乘数。

返回值：

?UInt32 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?UInt32

功能：使用返回 Option 策略的负号运算。

当运算出现溢出时，返回 ?UInt32.None，否则返回运算结果。

返回值：

?UInt32 - 负号运算结果。

func checkedShl(UInt32)

public func checkedShl(y: UInt32): ?UInt32

功能：使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数时，返回 ?UInt32.None，否则返回运算结果。

参数：

y: UInt32 - 移位位数。

返回值：

?UInt32 - 左移运算结果。

func checkedShr(UInt32)

public func checkedShr(y: UInt32): ?UInt32

功能：使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数时，返回 ?UInt32.None，否则返回运算结果。

参数：

y: UInt32 - 移位位数。

返回值：

?UInt32 - 右移运算结果。

func checkedSub(UInt32)

public func checkedSub(y: UInt32): ?UInt32

功能：使用返回 Option 策略的减法运算。

当运算出现溢出时，返回 ?UInt32.None，否则返回运算结果。

参数：

y: UInt32 - 减数。

返回值：

?UInt32 - 减法运算结果。

extend UInt64 <: CheckedOp

extend UInt64 <: CheckedOp<UInt64>

功能：为 UInt64 实现 CheckedOp 接口。

func checkedAdd(UInt64)

public func checkedAdd(y: UInt64): ?UInt64

功能：使用返回 Option 策略的加法运算。

当运算出现溢出时，返回 ?UInt64.None，否则返回运算结果。

参数：

y: UInt64 - 加数。

返回值：

?UInt64 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?UInt64

功能：使用返回 Option 策略的自减运算。

当运算出现溢出时，返回 ?UInt64.None，否则返回运算结果。

返回值：

?UInt64 - 自减运算结果。

func checkedDiv(UInt64)

public func checkedDiv(y: UInt64): ?UInt64

功能：使用返回 Option 策略的除法运算。

当运算出现溢出时，返回 ?UInt64.None，否则返回运算结果。

参数：

y: UInt64 - 除数。

返回值：

?UInt64 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?UInt64

功能：使用返回 Option 策略的自增运算。

当运算出现溢出时，返回 ?UInt64.None，否则返回运算结果。

返回值：

?UInt64 - 自增运算结果。

func checkedMod(UInt64)

public func checkedMod(y: UInt64): ?UInt64

功能：使用返回 Option 策略的取余运算。

当运算出现溢出时，返回 ?UInt64.None，否则返回运算结果。

参数：

y: UInt64 - 除数。

返回值：

?UInt64 - 取余运算结果。

func checkedMul(UInt64)

public func checkedMul(y: UInt64): ?UInt64

功能：使用返回 Option 策略的乘法运算。

当运算出现溢出时，返回 ?UInt64.None，否则返回运算结果。

参数：

y: UInt64 - 乘数。

返回值：

?UInt64 - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?UInt64

功能：使用返回 Option 策略的负号运算。

当运算出现溢出时，返回 ?UInt64.None，否则返回运算结果。

返回值：

?UInt64 - 负号运算结果。

func checkedShl(UInt64)

public func checkedShl(y: UInt64): ?UInt64

功能：使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数时，返回 ?UInt64.None，否则返回运算结果。

参数：

y: UInt64 - 移位位数。

返回值：

?UInt64 - 左移运算结果。

func checkedShr(UInt64)

public func checkedShr(y: UInt64): ?UInt64

功能：使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数时，返回 ?UInt64.None，否则返回运算结果。

参数：

y: UInt64 - 移位位数。

返回值：

?UInt64 - 右移运算结果。

func checkedSub(UInt64)

public func checkedSub(y: UInt64): ?UInt64

功能：使用返回 Option 策略的减法运算。

当运算出现溢出时，返回 ?UInt64.None，否则返回运算结果。

参数：

y: UInt64 - 减数。

返回值：

?UInt64 - 减法运算结果。

extend UInt8 <: CheckedOp

extend UInt8 <: CheckedOp<UInt8>

功能：为 UInt8 实现 CheckedOp 接口。

func checkedAdd(UInt8)

public func checkedAdd(y: UInt8): ?UInt8

功能：使用返回 Option 策略的加法运算。

当运算出现溢出时，返回 ?UInt8.None，否则返回运算结果。

参数：

y: UInt8 - 加数。

返回值：

?UInt8 - 加法运算结果。

func checkedDec()

public func checkedDec(): ?UInt8

功能：使用返回 Option 策略的自减运算。

当运算出现溢出时，返回 ?UInt8.None，否则返回运算结果。

返回值：

?UInt8 - 自减运算结果。

func checkedDiv(UInt8)

public func checkedDiv(y: UInt8): ?UInt8

功能：使用返回 Option 策略的除法运算。

当运算出现溢出时，返回 ?UInt8.None，否则返回运算结果。

参数：

y: UInt8 - 除数。

返回值：

?UInt8 - 除法运算结果。

func checkedInc()

public func checkedInc(): ?UInt8

功能：使用返回 Option 策略的自增运算。

当运算出现溢出时，返回 ?UInt8.None，否则返回运算结果。

返回值：

?UInt8 - 自增运算结果。

func checkedMod(UInt8)

public func checkedMod(y: UInt8): ?UInt8

功能：使用返回 Option 策略的取余运算。

当运算出现溢出时，返回 ?UInt8.None，否则返回运算结果。

参数：

y: UInt8 - 除数。

返回值：

?UInt8 - 取余运算结果。

func checkedMul(UInt8)

public func checkedMul(y: UInt8): ?UInt8

功能：使用返回 Option 策略的乘法运算。

当运算出现溢出时，返回 ?UInt8.None，否则返回运算结果。

参数：

y: UInt8 - 乘数。

返回值：

?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，否则返回运算结果。

参数：

y: UInt8 - 减数。

返回值：

?UInt8 - 减法运算结果。

extend UIntNative <: CheckedOp

extend UIntNative <: CheckedOp<UIntNative>

功能：为 UIntNative 实现 CheckedOp 接口。

func checkedAdd(UIntNative)

public func checkedAdd(y: UIntNative): ?UIntNative

功能：使用返回 Option 策略的加法运算。

当运算出现溢出时，返回 ?UIntNative.None，否则返回运算结果。

参数：

y: UIntNative - 加数。

返回值：

?UIntNative - 加法运算结果。

func checkedDec()

public func checkedDec(): ?UIntNative

功能：使用返回 Option 策略的自减运算。

当运算出现溢出时，返回 ?UIntNative.None，否则返回运算结果。

返回值：

?UIntNative - 自减运算结果。

func checkedDiv(UIntNative)

public func checkedDiv(y: UIntNative): ?UIntNative

功能：使用返回 Option 策略的除法运算。

当运算出现溢出时，返回 ?UIntNative.None，否则返回运算结果。

参数：

y: UIntNative - 除数。

返回值：

?UIntNative - 除法运算结果。

func checkedInc()

public func checkedInc(): ?UIntNative

功能：使用返回 Option 策略的自增运算。

当运算出现溢出时，返回 ?UIntNative.None，否则返回运算结果。

返回值：

?UIntNative - 自增运算结果。

func checkedMod(UIntNative)

public func checkedMod(y: UIntNative): ?UIntNative

功能：使用返回 Option 策略的取余运算。

当运算出现溢出时，返回 ?UIntNative.None，否则返回运算结果。

参数：

y: UIntNative - 除数。

返回值：

?UIntNative - 取余运算结果。

func checkedMul(UIntNative)

public func checkedMul(y: UIntNative): ?UIntNative

功能：使用返回 Option 策略的乘法运算。

当运算出现溢出时，返回 ?UIntNative.None，否则返回运算结果。

参数：

y: UIntNative - 乘数。

返回值：

?UIntNative - 乘法运算结果。

func checkedNeg()

public func checkedNeg(): ?UIntNative

功能：使用返回 Option 策略的负号运算。

当运算出现溢出时，返回 ?UIntNative.None，否则返回运算结果。

返回值：

?UIntNative - 负号运算结果。

func checkedShl(UIntNative)

public func checkedShl(y: UIntNative): ?UIntNative

功能：使用返回 Option 策略的左移运算。

当移位位数大于等于操作数位数时，返回 ?UIntNative.None，否则返回运算结果。

参数：

y: UIntNative - 移位位数。

返回值：

?UIntNative - 左移运算结果。

func checkedShr(UIntNative)

public func checkedShr(y: UIntNative): ?UIntNative

功能：使用返回 Option 策略的右移运算。

当移位位数大于等于操作数位数时，返回 ?UIntNative.None，否则返回运算结果。

参数：

y: UIntNative - 移位位数。

返回值：

?UIntNative - 右移运算结果。

func checkedSub(UIntNative)

public func checkedSub(y: UIntNative): ?UIntNative

功能：使用返回 Option 策略的减法运算。

当运算出现溢出时，返回 ?UIntNative.None，否则返回运算结果。

参数：

y: UIntNative - 减数。

返回值：

?UIntNative - 减法运算结果。

interface SaturatingOp

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<T>

extend Int16 <: SaturatingOp<Int16>

功能：为 Int16 实现 SaturatingOp 接口。

func saturatingAdd(Int16)

public func saturatingAdd(y: Int16): Int16

功能：使用饱和策略的加法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: Int16 - 加数。

返回值：

Int16 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): Int16

功能：使用饱和策略的自减运算。

当运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

Int16 - 自减运算结果。

func saturatingDiv(Int16)

public func saturatingDiv(y: Int16): Int16

功能：使用饱和策略的除法运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: Int16 - 除数。

返回值：

Int16 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): Int16

功能：使用饱和策略的自增运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

返回值：

Int16 - 自增运算结果。

func saturatingMod(Int16)

public func saturatingMod(y: Int16): Int16

功能：使用饱和策略的取余运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: Int16 - 除数。

返回值：

Int16 - 取余运算结果。

func saturatingMul(Int16)

public func saturatingMul(y: Int16): Int16

功能：使用饱和策略的乘法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: 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

功能：使用饱和策略的减法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: Int16 - 减数。

返回值：

Int16 - 减法运算结果。

extend Int32 <: SaturatingOp

extend Int32 <: SaturatingOp<Int32>

功能：为 Int32 实现 SaturatingOp 接口。

func saturatingAdd(Int32)

public func saturatingAdd(y: Int32): Int32

功能：使用饱和策略的加法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: Int32 - 加数。

返回值：

Int32 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): Int32

功能：使用饱和策略的自减运算。

当运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

Int32 - 自减运算结果。

func saturatingDiv(Int32)

public func saturatingDiv(y: Int32): Int32

功能：使用饱和策略的除法运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: Int32 - 除数。

返回值：

Int32 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): Int32

功能：使用饱和策略的自增运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

返回值：

Int32 - 自增运算结果。

func saturatingMod(Int32)

public func saturatingMod(y: Int32): Int32

功能：使用饱和策略的取余运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: Int32 - 除数。

返回值：

Int32 - 取余运算结果。

func saturatingMul(Int32)

public func saturatingMul(y: Int32): Int32

功能：使用饱和策略的乘法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: 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

功能：使用饱和策略的减法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: Int32 - 减数。

返回值：

Int32 - 减法运算结果。

extend Int64 <: SaturatingOp

extend Int64 <: SaturatingOp<Int64>

功能：为 Int64 实现 SaturatingOp 接口。

func saturatingAdd(Int64)

public func saturatingAdd(y: Int64): Int64

功能：使用饱和策略的加法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: Int64 - 加数。

返回值：

Int64 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): Int64

功能：使用饱和策略的自减运算。

当运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

Int64 - 自减运算结果。

func saturatingDiv(Int64)

public func saturatingDiv(y: Int64): Int64

功能：使用饱和策略的除法运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: Int64 - 除数。

返回值：

Int64 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): Int64

功能：使用饱和策略的自增运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

返回值：

Int64 - 自增运算结果。

func saturatingMod(Int64)

public func saturatingMod(y: Int64): Int64

功能：使用饱和策略的取余运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: Int64 - 除数。

返回值：

Int64 - 取余运算结果。

func saturatingMul(Int64)

public func saturatingMul(y: Int64): Int64

功能：使用饱和策略的乘法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: Int64 - 乘数。

返回值：

Int64 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): Int64

功能：使用饱和策略的负号运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

Int64 - 负号运算结果。

func saturatingPow(UInt64)

public func saturatingPow(y: UInt64): Int64

功能：使用饱和策略的幂运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt64 - 指数。

返回值：

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

功能：使用饱和策略的减法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: Int64 - 减数。

返回值：

Int64 - 减法运算结果。

extend Int8 <: SaturatingOp

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

extend IntNative <: SaturatingOp<IntNative>

功能：为 IntNative 实现 SaturatingOp 接口。

func saturatingAdd(IntNative)

public func saturatingAdd(y: IntNative): IntNative

功能：使用饱和策略的加法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: IntNative - 加数。

返回值：

IntNative - 加法运算结果。

func saturatingDec()

public func saturatingDec(): IntNative

功能：使用饱和策略的自减运算。

当运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

IntNative - 自减运算结果。

func saturatingDiv(IntNative)

public func saturatingDiv(y: IntNative): IntNative

功能：使用饱和策略的除法运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: IntNative - 除数。

返回值：

IntNative - 除法运算结果。

func saturatingInc()

public func saturatingInc(): IntNative

功能：使用饱和策略的自增运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

返回值：

IntNative - 自增运算结果。

func saturatingMod(IntNative)

public func saturatingMod(y: IntNative): IntNative

功能：使用饱和策略的取余运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: IntNative - 除数。

返回值：

IntNative - 取余运算结果。

func saturatingMul(IntNative)

public func saturatingMul(y: IntNative): IntNative

功能：使用饱和策略的乘法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: IntNative - 乘数。

返回值：

IntNative - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): IntNative

功能：使用饱和策略的负号运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

IntNative - 负号运算结果。

func saturatingShl(IntNative)

public func saturatingShl(y: IntNative): IntNative

功能：使用饱和策略的左移运算。

当移位位数大于等于操作数位数时，将移位位数置为操作数位数 - 1，移位位数小于 0 时，将移位位数置为 0，否则返回运算结果。

参数：

y: IntNative - 移位位数。

返回值：

IntNative - 左移运算结果。

func saturatingShr(IntNative)

public func saturatingShr(y: IntNative): IntNative

功能：使用饱和策略的右移运算。

当移位位数大于等于操作数位数时，将移位位数置为操作数位数 - 1，移位位数小于 0 时，将移位位数置为 0，否则返回运算结果。

参数：

y: IntNative - 移位位数。

返回值：

IntNative - 右移运算结果。

func saturatingSub(IntNative)

public func saturatingSub(y: IntNative): IntNative

功能：使用饱和策略的减法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: IntNative - 减数。

返回值：

IntNative - 减法运算结果。

extend UInt16 <: SaturatingOp

extend UInt16 <: SaturatingOp<UInt16>

功能：为 UInt16 实现 SaturatingOp 接口。

func saturatingAdd(UInt16)

public func saturatingAdd(y: UInt16): UInt16

功能：使用饱和策略的加法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt16 - 加数。

返回值：

UInt16 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): UInt16

功能：使用饱和策略的自减运算。

当运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

UInt16 - 自减运算结果。

func saturatingDiv(UInt16)

public func saturatingDiv(y: UInt16): UInt16

功能：使用饱和策略的除法运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: UInt16 - 除数。

返回值：

UInt16 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): UInt16

功能：使用饱和策略的自增运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

返回值：

UInt16 - 自增运算结果。

func saturatingMod(UInt16)

public func saturatingMod(y: UInt16): UInt16

功能：使用饱和策略的取余运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: UInt16 - 除数。

返回值：

UInt16 - 取余运算结果。

func saturatingMul(UInt16)

public func saturatingMul(y: UInt16): UInt16

功能：使用饱和策略的乘法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt16 - 乘数。

返回值：

UInt16 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): UInt16

功能：使用饱和策略的负号运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

UInt16 - 负号运算结果。

func saturatingShl(UInt16)

public func saturatingShl(y: UInt16): UInt16

功能：使用饱和策略的左移运算。

当移位位数大于等于操作数位数时，将移位位数置为操作数位数 - 1，移位位数小于 0 时，将移位位数置为 0，否则返回运算结果。

参数：

y: UInt16 - 移位位数。

返回值：

UInt16 - 左移运算结果。

func saturatingShr(UInt16)

public func saturatingShr(y: UInt16): UInt16

功能：使用饱和策略的右移运算。

当移位位数大于等于操作数位数时，将移位位数置为操作数位数 - 1，移位位数小于 0 时，将移位位数置为 0，否则返回运算结果。

参数：

y: UInt16 - 移位位数。

返回值：

UInt16 - 右移运算结果。

func saturatingSub(UInt16)

public func saturatingSub(y: UInt16): UInt16

功能：使用饱和策略的减法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt16 - 减数。

返回值：

UInt16 - 减法运算结果。

extend UInt32 <: SaturatingOp

extend UInt32 <: SaturatingOp<UInt32>

功能：为 UInt32 实现 SaturatingOp 接口。

func saturatingAdd(UInt32)

public func saturatingAdd(y: UInt32): UInt32

功能：使用饱和策略的加法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt32 - 加数。

返回值：

UInt32 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): UInt32

功能：使用饱和策略的自减运算。

当运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

UInt32 - 自减运算结果。

func saturatingDiv(UInt32)

public func saturatingDiv(y: UInt32): UInt32

功能：使用饱和策略的除法运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: UInt32 - 除数。

返回值：

UInt32 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): UInt32

功能：使用饱和策略的自增运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

返回值：

UInt32 - 自增运算结果。

func saturatingMod(UInt32)

public func saturatingMod(y: UInt32): UInt32

功能：使用饱和策略的取余运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: UInt32 - 除数。

返回值：

UInt32 - 取余运算结果。

func saturatingMul(UInt32)

public func saturatingMul(y: UInt32): UInt32

功能：使用饱和策略的乘法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt32 - 乘数。

返回值：

UInt32 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): UInt32

功能：使用饱和策略的负号运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

UInt32 - 负号运算结果。

func saturatingShl(UInt32)

public func saturatingShl(y: UInt32): UInt32

功能：使用饱和策略的左移运算。

当移位位数大于等于操作数位数时，将移位位数置为操作数位数 - 1，移位位数小于 0 时，将移位位数置为 0，否则返回运算结果。

参数：

y: UInt32 - 移位位数。

返回值：

UInt32 - 左移运算结果。

func saturatingShr(UInt32)

public func saturatingShr(y: UInt32): UInt32

功能：使用饱和策略的右移运算。

当移位位数大于等于操作数位数时，将移位位数置为操作数位数 - 1，移位位数小于 0 时，将移位位数置为 0，否则返回运算结果。

参数：

y: UInt32 - 移位位数。

返回值：

UInt32 - 右移运算结果。

func saturatingSub(UInt32)

public func saturatingSub(y: UInt32): UInt32

功能：使用饱和策略的减法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt32 - 减数。

返回值：

UInt32 - 减法运算结果。

extend UInt64 <: SaturatingOp

extend UInt64 <: SaturatingOp<UInt64>

功能：为 UInt64 实现 SaturatingOp 接口。

func saturatingAdd(UInt64)

public func saturatingAdd(y: UInt64): UInt64

功能：使用饱和策略的加法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt64 - 加数。

返回值：

UInt64 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): UInt64

功能：使用饱和策略的自减运算。

当运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

UInt64 - 自减运算结果。

func saturatingDiv(UInt64)

public func saturatingDiv(y: UInt64): UInt64

功能：使用饱和策略的除法运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: UInt64 - 除数。

返回值：

UInt64 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): UInt64

功能：使用饱和策略的自增运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

返回值：

UInt64 - 自增运算结果。

func saturatingMod(UInt64)

public func saturatingMod(y: UInt64): UInt64

功能：使用饱和策略的取余运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: UInt64 - 除数。

返回值：

UInt64 - 取余运算结果。

func saturatingMul(UInt64)

public func saturatingMul(y: UInt64): UInt64

功能：使用饱和策略的乘法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt64 - 乘数。

返回值：

UInt64 - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): UInt64

功能：使用饱和策略的负号运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

UInt64 - 负号运算结果。

func saturatingShl(UInt64)

public func saturatingShl(y: UInt64): UInt64

功能：使用饱和策略的左移运算。

当移位位数大于等于操作数位数时，将移位位数置为操作数位数 - 1，移位位数小于 0 时，将移位位数置为 0，否则返回运算结果。

参数：

y: UInt64 - 移位位数。

返回值：

UInt64 - 左移运算结果。

func saturatingShr(UInt64)

public func saturatingShr(y: UInt64): UInt64

功能：使用饱和策略的右移运算。

当移位位数大于等于操作数位数时，将移位位数置为操作数位数 - 1，移位位数小于 0 时，将移位位数置为 0，否则返回运算结果。

参数：

y: UInt64 - 移位位数。

返回值：

UInt64 - 右移运算结果。

func saturatingSub(UInt64)

public func saturatingSub(y: UInt64): UInt64

功能：使用饱和策略的减法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt64 - 减数。

返回值：

UInt64 - 减法运算结果。

extend UInt8 <: SaturatingOp

extend UInt8 <: SaturatingOp<UInt8>

功能：为 UInt8 实现 SaturatingOp 接口。

func saturatingAdd(UInt8)

public func saturatingAdd(y: UInt8): UInt8

功能：使用饱和策略的加法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt8 - 加数。

返回值：

UInt8 - 加法运算结果。

func saturatingDec()

public func saturatingDec(): UInt8

功能：使用饱和策略的自减运算。

当运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

UInt8 - 自减运算结果。

func saturatingDiv(UInt8)

public func saturatingDiv(y: UInt8): UInt8

功能：使用饱和策略的除法运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: UInt8 - 除数。

返回值：

UInt8 - 除法运算结果。

func saturatingInc()

public func saturatingInc(): UInt8

功能：使用饱和策略的自增运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

返回值：

UInt8 - 自增运算结果。

func saturatingMod(UInt8)

public func saturatingMod(y: UInt8): UInt8

功能：使用饱和策略的取余运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: UInt8 - 除数。

返回值：

UInt8 - 取余运算结果。

func saturatingMul(UInt8)

public func saturatingMul(y: UInt8): UInt8

功能：使用饱和策略的乘法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: 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

功能：使用饱和策略的减法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UInt8 - 减数。

返回值：

UInt8 - 减法运算结果。

extend UIntNative <: SaturatingOp

extend UIntNative <: SaturatingOp<UIntNative>

功能：为 UIntNative 实现 SaturatingOp 接口。

func saturatingAdd(UIntNative)

public func saturatingAdd(y: UIntNative): UIntNative

功能：使用饱和策略的加法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UIntNative - 加数。

返回值：

UIntNative - 加法运算结果。

func saturatingDec()

public func saturatingDec(): UIntNative

功能：使用饱和策略的自减运算。

当运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

UIntNative - 自减运算结果。

func saturatingDiv(UIntNative)

public func saturatingDiv(y: UIntNative): UIntNative

功能：使用饱和策略的除法运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: UIntNative - 除数。

返回值：

UIntNative - 除法运算结果。

func saturatingInc()

public func saturatingInc(): UIntNative

功能：使用饱和策略的自增运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

返回值：

UIntNative - 自增运算结果。

func saturatingMod(UIntNative)

public func saturatingMod(y: UIntNative): UIntNative

功能：使用饱和策略的取余运算。

当运算出现上溢时，返回操作数类型的最大值，否则返回运算结果。

参数：

y: UIntNative - 除数。

返回值：

UIntNative - 取余运算结果。

func saturatingMul(UIntNative)

public func saturatingMul(y: UIntNative): UIntNative

功能：使用饱和策略的乘法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UIntNative - 乘数。

返回值：

UIntNative - 乘法运算结果。

func saturatingNeg()

public func saturatingNeg(): UIntNative

功能：使用饱和策略的负号运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

返回值：

UIntNative - 负号运算结果。

func saturatingShl(UIntNative)

public func saturatingShl(y: UIntNative): UIntNative

功能：使用饱和策略的左移运算。

当移位位数大于等于操作数位数时，将移位位数置为操作数位数 - 1，移位位数小于 0 时，将移位位数置为 0，否则返回运算结果。

参数：

y: UIntNative - 移位位数。

返回值：

UIntNative - 左移运算结果。

func saturatingShr(UIntNative)

public func saturatingShr(y: UIntNative): UIntNative

功能：使用饱和策略的右移运算。

当移位位数大于等于操作数位数时，将移位位数置为操作数位数 - 1，移位位数小于 0 时，将移位位数置为 0，否则返回运算结果。

参数：

y: UIntNative - 移位位数。

返回值：

UIntNative - 右移运算结果。

func saturatingSub(UIntNative)

public func saturatingSub(y: UIntNative): UIntNative

功能：使用饱和策略的减法运算。

当运算出现上溢时，返回操作数类型的最大值，运算出现下溢时，返回操作数类型的最小值，否则返回运算结果。

参数：

y: UIntNative - 减数。

返回值：

UIntNative - 减法运算结果。

interface ThrowingOp

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 - 加法运算结果。

异常：

OverflowException - 当加法运算出现溢出时，抛出异常。

func throwingDec()

func throwingDec(): T

功能：使用抛出异常策略的自减运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

T - 自减运算结果。

异常：

OverflowException - 当自减运算出现溢出时，抛出异常。

func throwingDiv(T)

func throwingDiv(y: T): T

功能：使用抛出异常策略的除法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: T - 除数。

返回值：

T - 除法运算结果。

异常：

OverflowException - 当除法运算出现溢出时，抛出异常。

func throwingInc()

func throwingInc(): T

功能：使用抛出异常策略的自增运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

T - 自增运算结果。

异常：

OverflowException - 当自增运算出现溢出时，抛出异常。

func throwingMod(T)

func throwingMod(y: T): T

功能：使用抛出异常策略的取余运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: T - 除数。

返回值：

T - 取余运算结果。

异常：

OverflowException - 当取余运算出现溢出时，抛出异常。

func throwingMul(T)

func throwingMul(y: T): T

功能：使用抛出异常策略的乘法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: T - 乘数。

返回值：

T - 乘法运算结果。

异常：

OverflowException - 当乘法运算出现溢出时，抛出异常。

func throwingNeg()

func throwingNeg(): T

功能：使用抛出异常策略的负号运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

T - 负号运算结果。

异常：

OverflowException - 当负号运算出现溢出时，抛出异常。

func throwingShl(T)

func throwingShl(y: T): T

功能：使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，抛出异常，否则返回运算结果。

参数：

y: T - 移位位数。

返回值：

T - 左移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingShr(T)

func throwingShr(y: T): T

功能：右移运算。

当移位位数大于等于操作数位数时，抛出异常，否则返回运算结果。

参数：

y: T - 移位位数。

返回值：

T - 右移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingSub(T)

func throwingSub(y: T): T

功能：使用抛出异常策略的减法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: T - 减数。

返回值：

T - 减法运算结果。

异常：

OverflowException - 当减法运算出现溢出时，抛出异常。

extend Int16 <: ThrowingOp

extend Int16 <: ThrowingOp<Int16>

功能：为 Int16 实现 ThrowingOp 接口。

func throwingAdd(Int16)

public func throwingAdd(y: Int16): Int16

功能：使用抛出异常策略的加法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int16 - 加数。

返回值：

Int16 - 加法运算结果。

异常：

OverflowException - 当加法运算出现溢出时，抛出异常。

func throwingDec()

public func throwingDec(): Int16

功能：使用抛出异常策略的自减运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int16 - 自减运算结果。

异常：

OverflowException - 当自减运算出现溢出时，抛出异常。

func throwingDiv(Int16)

public func throwingDiv(y: Int16): Int16

功能：使用抛出异常策略的除法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int16 - 除数。

返回值：

Int16 - 除法运算结果。

异常：

OverflowException - 当除法运算出现溢出时，抛出异常。

func throwingInc()

public func throwingInc(): Int16

功能：使用抛出异常策略的自增运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int16 - 自增运算结果。

异常：

OverflowException - 当自增运算出现溢出时，抛出异常。

func throwingMod(Int16)

public func throwingMod(y: Int16): Int16

功能：使用抛出异常策略的取余运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int16 - 除数。

返回值：

Int16 - 取余运算结果。

异常：

OverflowException - 当取余运算出现溢出时，抛出异常。

func throwingMul(Int16)

public func throwingMul(y: Int16): Int16

功能：使用抛出异常策略的乘法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int16 - 乘数。

返回值：

Int16 - 乘法运算结果。

异常：

OverflowException - 当乘法运算出现溢出时，抛出异常。

func throwingNeg()

public func throwingNeg(): Int16

功能：使用抛出异常策略的负号运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int16 - 负号运算结果。

异常：

OverflowException - 当负号运算出现溢出时，抛出异常。

func throwingShl(Int16)

public func throwingShl(y: Int16): Int16

功能：使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，抛出异常，否则返回运算结果。

参数：

y: Int16 - 移位位数。

返回值：

Int16 - 左移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingShr(Int16)

public func throwingShr(y: Int16): Int16

功能：右移运算。

当移位位数大于等于操作数位数时，抛出异常，否则返回运算结果。

参数：

y: Int16 - 移位位数。

返回值：

Int16 - 右移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingSub(Int16)

public func throwingSub(y: Int16): Int16

功能：使用抛出异常策略的减法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int16 - 减数。

返回值：

Int16 - 减法运算结果。

异常：

OverflowException - 当减法运算出现溢出时，抛出异常。

extend Int32 <: ThrowingOp

extend Int32 <: ThrowingOp<Int32>

功能：为 Int32 实现 ThrowingOp 接口。

func throwingAdd(Int32)

public func throwingAdd(y: Int32): Int32

功能：使用抛出异常策略的加法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int32 - 加数。

返回值：

Int32 - 加法运算结果。

异常：

OverflowException - 当加法运算出现溢出时，抛出异常。

func throwingDec()

public func throwingDec(): Int32

功能：使用抛出异常策略的自减运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int32 - 自减运算结果。

异常：

OverflowException - 当自减运算出现溢出时，抛出异常。

func throwingDiv(Int32)

public func throwingDiv(y: Int32): Int32

功能：使用抛出异常策略的除法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int32 - 除数。

返回值：

Int32 - 除法运算结果。

异常：

OverflowException - 当除法运算出现溢出时，抛出异常。

func throwingInc()

public func throwingInc(): Int32

功能：使用抛出异常策略的自增运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int32 - 自增运算结果。

异常：

OverflowException - 当自增运算出现溢出时，抛出异常。

func throwingMod(Int32)

public func throwingMod(y: Int32): Int32

功能：使用抛出异常策略的取余运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int32 - 除数。

返回值：

Int32 - 取余运算结果。

异常：

OverflowException - 当取余运算出现溢出时，抛出异常。

func throwingMul(Int32)

public func throwingMul(y: Int32): Int32

功能：使用抛出异常策略的乘法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int32 - 乘数。

返回值：

Int32 - 乘法运算结果。

异常：

OverflowException - 当乘法运算出现溢出时，抛出异常。

func throwingNeg()

public func throwingNeg(): Int32

功能：使用抛出异常策略的负号运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int32 - 负号运算结果。

异常：

OverflowException - 当负号运算出现溢出时，抛出异常。

func throwingShl(Int32)

public func throwingShl(y: Int32): Int32

功能：使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，抛出异常，否则返回运算结果。

参数：

y: Int32 - 移位位数。

返回值：

Int32 - 左移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingShr(Int32)

public func throwingShr(y: Int32): Int32

功能：右移运算。

当移位位数大于等于操作数位数时，抛出异常，否则返回运算结果。

参数：

y: Int32 - 移位位数。

返回值：

Int32 - 右移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingSub(Int32)

public func throwingSub(y: Int32): Int32

功能：使用抛出异常策略的减法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int32 - 减数。

返回值：

Int32 - 减法运算结果。

异常：

OverflowException - 当减法运算出现溢出时，抛出异常。

extend Int64 <: ThrowingOp

extend Int64 <: ThrowingOp<Int64>

功能：为 Int64 实现 ThrowingOp 接口。

func throwingAdd(Int64)

public func throwingAdd(y: Int64): Int64

功能：使用抛出异常策略的加法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int64 - 加数。

返回值：

Int64 - 加法运算结果。

异常：

OverflowException - 当加法运算出现溢出时，抛出异常。

func throwingDec()

public func throwingDec(): Int64

功能：使用抛出异常策略的自减运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int64 - 自减运算结果。

异常：

OverflowException - 当自减运算出现溢出时，抛出异常。

func throwingDiv(Int64)

public func throwingDiv(y: Int64): Int64

功能：使用抛出异常策略的除法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int64 - 除数。

返回值：

Int64 - 除法运算结果。

异常：

OverflowException - 当除法运算出现溢出时，抛出异常。

func throwingInc()

public func throwingInc(): Int64

功能：使用抛出异常策略的自增运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int64 - 自增运算结果。

异常：

OverflowException - 当自增运算出现溢出时，抛出异常。

func throwingMod(Int64)

public func throwingMod(y: Int64): Int64

功能：使用抛出异常策略的取余运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int64 - 除数。

返回值：

Int64 - 取余运算结果。

异常：

OverflowException - 当取余运算出现溢出时，抛出异常。

func throwingMul(Int64)

public func throwingMul(y: Int64): Int64

功能：使用抛出异常策略的乘法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int64 - 乘数。

返回值：

Int64 - 乘法运算结果。

异常：

OverflowException - 当乘法运算出现溢出时，抛出异常。

func throwingNeg()

public func throwingNeg(): Int64

功能：使用抛出异常策略的负号运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int64 - 负号运算结果。

异常：

OverflowException - 当负号运算出现溢出时，抛出异常。

func throwingPow(UInt64)

public func throwingPow(y: UInt64): Int64

功能：使用抛出异常策略的幂运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt64 - 指数。

返回值：

Int64 - 幂运算结果。

异常：

OverflowException - 当幂运算出现溢出时，抛出异常。

func throwingShl(Int64)

public func throwingShl(y: Int64): Int64

功能：使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，抛出异常，否则返回运算结果。

参数：

y: Int64 - 移位位数。

返回值：

Int64 - 左移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingShr(Int64)

public func throwingShr(y: Int64): Int64

功能：右移运算。

当移位位数大于等于操作数位数时，抛出异常，否则返回运算结果。

参数：

y: Int64 - 移位位数。

返回值：

Int64 - 右移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingSub(Int64)

public func throwingSub(y: Int64): Int64

功能：使用抛出异常策略的减法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int64 - 减数。

返回值：

Int64 - 减法运算结果。

异常：

OverflowException - 当减法运算出现溢出时，抛出异常。

extend Int8 <: ThrowingOp

extend Int8 <: ThrowingOp<Int8>

功能：为 Int8 实现 ThrowingOp 接口。

func throwingAdd(Int8)

public func throwingAdd(y: Int8): Int8

功能：使用抛出异常策略的加法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int8 - 加数。

返回值：

Int8 - 加法运算结果。

异常：

OverflowException - 当加法运算出现溢出时，抛出异常。

func throwingDec()

public func throwingDec(): Int8

功能：使用抛出异常策略的自减运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int8 - 自减运算结果。

异常：

OverflowException - 当自减运算出现溢出时，抛出异常。

func throwingDiv(Int8)

public func throwingDiv(y: Int8): Int8

功能：使用抛出异常策略的除法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int8 - 除数。

返回值：

Int8 - 除法运算结果。

异常：

OverflowException - 当除法运算出现溢出时，抛出异常。

func throwingInc()

public func throwingInc(): Int8

功能：使用抛出异常策略的自增运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int8 - 自增运算结果。

异常：

OverflowException - 当自增运算出现溢出时，抛出异常。

func throwingMod(Int8)

public func throwingMod(y: Int8): Int8

功能：使用抛出异常策略的取余运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int8 - 除数。

返回值：

Int8 - 取余运算结果。

异常：

OverflowException - 当取余运算出现溢出时，抛出异常。

func throwingMul(Int8)

public func throwingMul(y: Int8): Int8

功能：使用抛出异常策略的乘法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int8 - 乘数。

返回值：

Int8 - 乘法运算结果。

异常：

OverflowException - 当乘法运算出现溢出时，抛出异常。

func throwingNeg()

public func throwingNeg(): Int8

功能：使用抛出异常策略的负号运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

Int8 - 负号运算结果。

异常：

OverflowException - 当负号运算出现溢出时，抛出异常。

func throwingShl(Int8)

public func throwingShl(y: Int8): Int8

功能：使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，抛出异常，否则返回运算结果。

参数：

y: Int8 - 移位位数。

返回值：

Int8 - 左移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingShr(Int8)

public func throwingShr(y: Int8): Int8

功能：右移运算。

当移位位数大于等于操作数位数时，抛出异常，否则返回运算结果。

参数：

y: Int8 - 移位位数。

返回值：

Int8 - 右移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingSub(Int8)

public func throwingSub(y: Int8): Int8

功能：使用抛出异常策略的减法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: Int8 - 减数。

返回值：

Int8 - 减法运算结果。

异常：

OverflowException - 当减法运算出现溢出时，抛出异常。

extend IntNative <: ThrowingOp

extend IntNative <: ThrowingOp<IntNative>

功能：为 IntNative 实现 ThrowingOp 接口。

func throwingAdd(IntNative)

public func throwingAdd(y: IntNative): IntNative

功能：使用抛出异常策略的加法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: IntNative - 加数。

返回值：

IntNative - 加法运算结果。

异常：

OverflowException - 当加法运算出现溢出时，抛出异常。

func throwingDec()

public func throwingDec(): IntNative

功能：使用抛出异常策略的自减运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

IntNative - 自减运算结果。

异常：

OverflowException - 当自减运算出现溢出时，抛出异常。

func throwingDiv(IntNative)

public func throwingDiv(y: IntNative): IntNative

功能：使用抛出异常策略的除法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: IntNative - 除数。

返回值：

IntNative - 除法运算结果。

异常：

OverflowException - 当除法运算出现溢出时，抛出异常。

func throwingInc()

public func throwingInc(): IntNative

功能：使用抛出异常策略的自增运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

IntNative - 自增运算结果。

异常：

OverflowException - 当自增运算出现溢出时，抛出异常。

func throwingMod(IntNative)

public func throwingMod(y: IntNative): IntNative

功能：使用抛出异常策略的取余运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: IntNative - 除数。

返回值：

IntNative - 取余运算结果。

异常：

OverflowException - 当取余运算出现溢出时，抛出异常。

func throwingMul(IntNative)

public func throwingMul(y: IntNative): IntNative

功能：使用抛出异常策略的乘法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: IntNative - 乘数。

返回值：

IntNative - 乘法运算结果。

异常：

OverflowException - 当乘法运算出现溢出时，抛出异常。

func throwingNeg()

public func throwingNeg(): IntNative

功能：使用抛出异常策略的负号运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

IntNative - 负号运算结果。

异常：

OverflowException - 当负号运算出现溢出时，抛出异常。

func throwingShl(IntNative)

public func throwingShl(y: IntNative): IntNative

功能：使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，抛出异常，否则返回运算结果。

参数：

y: IntNative - 移位位数。

返回值：

IntNative - 左移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingShr(IntNative)

public func throwingShr(y: IntNative): IntNative

功能：右移运算。

当移位位数大于等于操作数位数时，抛出异常，否则返回运算结果。

参数：

y: IntNative - 移位位数。

返回值：

IntNative - 右移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。
UndershiftException - 当移位位数小于 0 时，抛出异常。

func throwingSub(IntNative)

public func throwingSub(y: IntNative): IntNative

功能：使用抛出异常策略的减法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: IntNative - 减数。

返回值：

IntNative - 减法运算结果。

异常：

OverflowException - 当减法运算出现溢出时，抛出异常。

extend UInt16 <: ThrowingOp

extend UInt16 <: ThrowingOp<UInt16>

功能：为 UInt16 实现 ThrowingOp 接口。

func throwingAdd(UInt16)

public func throwingAdd(y: UInt16): UInt16

功能：使用抛出异常策略的加法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt16 - 加数。

返回值：

UInt16 - 加法运算结果。

异常：

OverflowException - 当加法运算出现溢出时，抛出异常。

func throwingDec()

public func throwingDec(): UInt16

功能：使用抛出异常策略的自减运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt16 - 自减运算结果。

异常：

OverflowException - 当自减运算出现溢出时，抛出异常。

func throwingDiv(UInt16)

public func throwingDiv(y: UInt16): UInt16

功能：使用抛出异常策略的除法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt16 - 除数。

返回值：

UInt16 - 除法运算结果。

异常：

OverflowException - 当除法运算出现溢出时，抛出异常。

func throwingInc()

public func throwingInc(): UInt16

功能：使用抛出异常策略的自增运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt16 - 自增运算结果。

异常：

OverflowException - 当自增运算出现溢出时，抛出异常。

func throwingMod(UInt16)

public func throwingMod(y: UInt16): UInt16

功能：使用抛出异常策略的取余运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt16 - 除数。

返回值：

UInt16 - 取余运算结果。

异常：

OverflowException - 当取余运算出现溢出时，抛出异常。

func throwingMul(UInt16)

public func throwingMul(y: UInt16): UInt16

功能：使用抛出异常策略的乘法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt16 - 乘数。

返回值：

UInt16 - 乘法运算结果。

异常：

OverflowException - 当乘法运算出现溢出时，抛出异常。

func throwingNeg()

public func throwingNeg(): UInt16

功能：使用抛出异常策略的负号运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt16 - 负号运算结果。

异常：

OverflowException - 当负号运算出现溢出时，抛出异常。

func throwingShl(UInt16)

public func throwingShl(y: UInt16): UInt16

功能：使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，抛出异常，否则返回运算结果。

参数：

y: UInt16 - 移位位数。

返回值：

UInt16 - 左移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。

func throwingShr(UInt16)

public func throwingShr(y: UInt16): UInt16

功能：右移运算。

当移位位数大于等于操作数位数时，抛出异常，否则返回运算结果。

参数：

y: UInt16 - 移位位数。

返回值：

UInt16 - 右移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。

func throwingSub(UInt16)

public func throwingSub(y: UInt16): UInt16

功能：使用抛出异常策略的减法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt16 - 减数。

返回值：

UInt16 - 减法运算结果。

异常：

OverflowException - 当减法运算出现溢出时，抛出异常。

extend UInt32 <: ThrowingOp

extend UInt32 <: ThrowingOp<UInt32>

功能：为 UInt32 实现 ThrowingOp 接口。

func throwingAdd(UInt32)

public func throwingAdd(y: UInt32): UInt32

功能：使用抛出异常策略的加法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt32 - 加数。

返回值：

UInt32 - 加法运算结果。

异常：

OverflowException - 当加法运算出现溢出时，抛出异常。

func throwingDec()

public func throwingDec(): UInt32

功能：使用抛出异常策略的自减运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt32 - 自减运算结果。

异常：

OverflowException - 当自减运算出现溢出时，抛出异常。

func throwingDiv(UInt32)

public func throwingDiv(y: UInt32): UInt32

功能：使用抛出异常策略的除法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt32 - 除数。

返回值：

UInt32 - 除法运算结果。

异常：

OverflowException - 当除法运算出现溢出时，抛出异常。

func throwingInc()

public func throwingInc(): UInt32

功能：使用抛出异常策略的自增运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt32 - 自增运算结果。

异常：

OverflowException - 当自增运算出现溢出时，抛出异常。

func throwingMod(UInt32)

public func throwingMod(y: UInt32): UInt32

功能：使用抛出异常策略的取余运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt32 - 除数。

返回值：

UInt32 - 取余运算结果。

异常：

OverflowException - 当取余运算出现溢出时，抛出异常。

func throwingMul(UInt32)

public func throwingMul(y: UInt32): UInt32

功能：使用抛出异常策略的乘法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt32 - 乘数。

返回值：

UInt32 - 乘法运算结果。

异常：

OverflowException - 当乘法运算出现溢出时，抛出异常。

func throwingNeg()

public func throwingNeg(): UInt32

功能：使用抛出异常策略的负号运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt32 - 负号运算结果。

异常：

OverflowException - 当负号运算出现溢出时，抛出异常。

func throwingShl(UInt32)

public func throwingShl(y: UInt32): UInt32

功能：使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，抛出异常，否则返回运算结果。

参数：

y: UInt32 - 移位位数。

返回值：

UInt32 - 左移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。

func throwingShr(UInt32)

public func throwingShr(y: UInt32): UInt32

功能：右移运算。

当移位位数大于等于操作数位数时，抛出异常，否则返回运算结果。

参数：

y: UInt32 - 移位位数。

返回值：

UInt32 - 右移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。

func throwingSub(UInt32)

public func throwingSub(y: UInt32): UInt32

功能：使用抛出异常策略的减法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt32 - 减数。

返回值：

UInt32 - 减法运算结果。

异常：

OverflowException - 当减法运算出现溢出时，抛出异常。

extend UInt64 <: ThrowingOp

extend UInt64 <: ThrowingOp<UInt64>

功能：为 UInt64 实现 ThrowingOp 接口。

func throwingAdd(UInt64)

public func throwingAdd(y: UInt64): UInt64

功能：使用抛出异常策略的加法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt64 - 加数。

返回值：

UInt64 - 加法运算结果。

异常：

OverflowException - 当加法运算出现溢出时，抛出异常。

func throwingDec()

public func throwingDec(): UInt64

功能：使用抛出异常策略的自减运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt64 - 自减运算结果。

异常：

OverflowException - 当自减运算出现溢出时，抛出异常。

func throwingDiv(UInt64)

public func throwingDiv(y: UInt64): UInt64

功能：使用抛出异常策略的除法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt64 - 除数。

返回值：

UInt64 - 除法运算结果。

异常：

OverflowException - 当除法运算出现溢出时，抛出异常。

func throwingInc()

public func throwingInc(): UInt64

功能：使用抛出异常策略的自增运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt64 - 自增运算结果。

异常：

OverflowException - 当自增运算出现溢出时，抛出异常。

func throwingMod(UInt64)

public func throwingMod(y: UInt64): UInt64

功能：使用抛出异常策略的取余运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt64 - 除数。

返回值：

UInt64 - 取余运算结果。

异常：

OverflowException - 当取余运算出现溢出时，抛出异常。

func throwingMul(UInt64)

public func throwingMul(y: UInt64): UInt64

功能：使用抛出异常策略的乘法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt64 - 乘数。

返回值：

UInt64 - 乘法运算结果。

异常：

OverflowException - 当乘法运算出现溢出时，抛出异常。

func throwingNeg()

public func throwingNeg(): UInt64

功能：使用抛出异常策略的负号运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt64 - 负号运算结果。

异常：

OverflowException - 当负号运算出现溢出时，抛出异常。

func throwingShl(UInt64)

public func throwingShl(y: UInt64): UInt64

功能：使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，抛出异常，否则返回运算结果。

参数：

y: UInt64 - 移位位数。

返回值：

UInt64 - 左移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。

func throwingShr(UInt64)

public func throwingShr(y: UInt64): UInt64

功能：右移运算。

当移位位数大于等于操作数位数时，抛出异常，否则返回运算结果。

参数：

y: UInt64 - 移位位数。

返回值：

UInt64 - 右移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。

func throwingSub(UInt64)

public func throwingSub(y: UInt64): UInt64

功能：使用抛出异常策略的减法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt64 - 减数。

返回值：

UInt64 - 减法运算结果。

异常：

OverflowException - 当减法运算出现溢出时，抛出异常。

extend UInt8 <: ThrowingOp

extend UInt8 <: ThrowingOp<UInt8>

功能：为 UInt8 实现 ThrowingOp 接口。

func throwingAdd(UInt8)

public func throwingAdd(y: UInt8): UInt8

功能：使用抛出异常策略的加法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt8 - 加数。

返回值：

UInt8 - 加法运算结果。

异常：

OverflowException - 当加法运算出现溢出时，抛出异常。

func throwingDec()

public func throwingDec(): UInt8

功能：使用抛出异常策略的自减运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt8 - 自减运算结果。

异常：

OverflowException - 当自减运算出现溢出时，抛出异常。

func throwingDiv(UInt8)

public func throwingDiv(y: UInt8): UInt8

功能：使用抛出异常策略的除法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt8 - 除数。

返回值：

UInt8 - 除法运算结果。

异常：

OverflowException - 当除法运算出现溢出时，抛出异常。

func throwingInc()

public func throwingInc(): UInt8

功能：使用抛出异常策略的自增运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt8 - 自增运算结果。

异常：

OverflowException - 当自增运算出现溢出时，抛出异常。

func throwingMod(UInt8)

public func throwingMod(y: UInt8): UInt8

功能：使用抛出异常策略的取余运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt8 - 除数。

返回值：

UInt8 - 取余运算结果。

异常：

OverflowException - 当取余运算出现溢出时，抛出异常。

func throwingMul(UInt8)

public func throwingMul(y: UInt8): UInt8

功能：使用抛出异常策略的乘法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt8 - 乘数。

返回值：

UInt8 - 乘法运算结果。

异常：

OverflowException - 当乘法运算出现溢出时，抛出异常。

func throwingNeg()

public func throwingNeg(): UInt8

功能：使用抛出异常策略的负号运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UInt8 - 负号运算结果。

异常：

OverflowException - 当负号运算出现溢出时，抛出异常。

func throwingShl(UInt8)

public func throwingShl(y: UInt8): UInt8

功能：使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，抛出异常，否则返回运算结果。

参数：

y: UInt8 - 移位位数。

返回值：

UInt8 - 左移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。

func throwingShr(UInt8)

public func throwingShr(y: UInt8): UInt8

功能：右移运算。

当移位位数大于等于操作数位数时，抛出异常，否则返回运算结果。

参数：

y: UInt8 - 移位位数。

返回值：

UInt8 - 右移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。

func throwingSub(UInt8)

public func throwingSub(y: UInt8): UInt8

功能：使用抛出异常策略的减法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UInt8 - 减数。

返回值：

UInt8 - 减法运算结果。

异常：

OverflowException - 当减法运算出现溢出时，抛出异常。

extend UIntNative <: ThrowingOp

extend UIntNative <: ThrowingOp<UIntNative>

功能：为 UIntNative 实现 ThrowingOp 接口。

func throwingAdd(UIntNative)

public func throwingAdd(y: UIntNative): UIntNative

功能：使用抛出异常策略的加法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UIntNative - 加数。

返回值：

UIntNative - 加法运算结果。

异常：

OverflowException - 当加法运算出现溢出时，抛出异常。

func throwingDec()

public func throwingDec(): UIntNative

功能：使用抛出异常策略的自减运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UIntNative - 自减运算结果。

异常：

OverflowException - 当自减运算出现溢出时，抛出异常。

func throwingDiv(UIntNative)

public func throwingDiv(y: UIntNative): UIntNative

功能：使用抛出异常策略的除法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UIntNative - 除数。

返回值：

UIntNative - 除法运算结果。

异常：

OverflowException - 当除法运算出现溢出时，抛出异常。

func throwingInc()

public func throwingInc(): UIntNative

功能：使用抛出异常策略的自增运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UIntNative - 自增运算结果。

异常：

OverflowException - 当自增运算出现溢出时，抛出异常。

func throwingMod(UIntNative)

public func throwingMod(y: UIntNative): UIntNative

功能：使用抛出异常策略的取余运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UIntNative - 除数。

返回值：

UIntNative - 取余运算结果。

异常：

OverflowException - 当取余运算出现溢出时，抛出异常。

func throwingMul(UIntNative)

public func throwingMul(y: UIntNative): UIntNative

功能：使用抛出异常策略的乘法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UIntNative - 乘数。

返回值：

UIntNative - 乘法运算结果。

异常：

OverflowException - 当乘法运算出现溢出时，抛出异常。

func throwingNeg()

public func throwingNeg(): UIntNative

功能：使用抛出异常策略的负号运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

返回值：

UIntNative - 负号运算结果。

异常：

OverflowException - 当负号运算出现溢出时，抛出异常。

func throwingShl(UIntNative)

public func throwingShl(y: UIntNative): UIntNative

功能：使用抛出异常策略的左移运算。

当移位位数大于等于操作数位数或小于 0 时，抛出异常，否则返回运算结果。

参数：

y: UIntNative - 移位位数。

返回值：

UIntNative - 左移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。

func throwingShr(UIntNative)

public func throwingShr(y: UIntNative): UIntNative

功能：右移运算。

当移位位数大于等于操作数位数时，抛出异常，否则返回运算结果。

参数：

y: UIntNative - 移位位数。

返回值：

UIntNative - 右移运算结果。

异常：

OvershiftException - 当移位位数大于等于操作数位数时，抛出异常。

func throwingSub(UIntNative)

public func throwingSub(y: UIntNative): UIntNative

功能：使用抛出异常策略的减法运算。

当运算出现溢出时，抛出异常，否则返回运算结果。

参数：

y: UIntNative - 减数。

返回值：

UIntNative - 减法运算结果。

异常：

OverflowException - 当减法运算出现溢出时，抛出异常。

interface WrappingOp

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

功能：使用高位截断策略的右移运算。

参数：

y: T - 移位位数。

返回值：

T - 右移运算结果。

func wrappingSub(T)

func wrappingSub(y: T): T

功能：使用高位截断策略的减法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: T - 减数。

返回值：

T - 减法运算结果。

extend Int16 <: WrappingOp

extend Int16 <: WrappingOp<Int16>

功能：为 Int16 实现 WrappingOp 接口。

func wrappingAdd(Int16)

public func wrappingAdd(y: Int16): Int16

功能：使用高位截断策略的加法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int16 - 加数。

返回值：

Int16 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): Int16

功能：使用高位截断策略的自减运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

Int16 - 自减运算结果。

func wrappingDiv(Int16)

public func wrappingDiv(y: Int16): Int16

功能：使用高位截断策略的除法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int16 - 除数。

返回值：

Int16 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): Int16

功能：使用高位截断策略的自增运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

Int16 - 自增运算结果。

func wrappingMod(Int16)

public func wrappingMod(y: Int16): Int16

功能：使用高位截断策略的取余运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int16 - 除数。

返回值：

Int16 - 取余运算结果。

func wrappingMul(Int16)

public func wrappingMul(y: Int16): Int16

功能：使用高位截断策略的乘法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: 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

功能：使用高位截断策略的减法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int16 - 减数。

返回值：

Int16 - 减法运算结果。

extend Int32 <: WrappingOp

extend Int32 <: WrappingOp<Int32>

功能：为 Int32 实现 WrappingOp 接口。

func wrappingAdd(Int32)

public func wrappingAdd(y: Int32): Int32

功能：使用高位截断策略的加法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int32 - 加数。

返回值：

Int32 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): Int32

功能：使用高位截断策略的自减运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

Int32 - 自减运算结果。

func wrappingDiv(Int32)

public func wrappingDiv(y: Int32): Int32

功能：使用高位截断策略的除法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int32 - 除数。

返回值：

Int32 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): Int32

功能：使用高位截断策略的自增运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

Int32 - 自增运算结果。

func wrappingMod(Int32)

public func wrappingMod(y: Int32): Int32

功能：使用高位截断策略的取余运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int32 - 除数。

返回值：

Int32 - 取余运算结果。

func wrappingMul(Int32)

public func wrappingMul(y: Int32): Int32

功能：使用高位截断策略的乘法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: 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

功能：使用高位截断策略的减法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int32 - 减数。

返回值：

Int32 - 减法运算结果。

extend Int64 <: WrappingOp

extend Int64 <: WrappingOp<Int64>

功能：为 Int64 实现 WrappingOp 接口。

func wrappingAdd(Int64)

public func wrappingAdd(y: Int64): Int64

功能：使用高位截断策略的加法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int64 - 加数。

返回值：

Int64 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): Int64

功能：使用高位截断策略的自减运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

Int64 - 自减运算结果。

func wrappingDiv(Int64)

public func wrappingDiv(y: Int64): Int64

功能：使用高位截断策略的除法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int64 - 除数。

返回值：

Int64 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): Int64

功能：使用高位截断策略的自增运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

Int64 - 自增运算结果。

func wrappingMod(Int64)

public func wrappingMod(y: Int64): Int64

功能：使用高位截断策略的取余运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int64 - 除数。

返回值：

Int64 - 取余运算结果。

func wrappingMul(Int64)

public func wrappingMul(y: Int64): Int64

功能：使用高位截断策略的乘法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int64 - 乘数。

返回值：

Int64 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): Int64

功能：使用高位截断策略的负号运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

Int64 - 负号运算结果。

func wrappingPow(UInt64)

public func wrappingPow(y: UInt64): Int64

功能：使用高位截断策略的幂运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt64 - 指数。

返回值：

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

功能：使用高位截断策略的减法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: Int64 - 减数。

返回值：

Int64 - 减法运算结果。

extend Int8 <: WrappingOp

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

extend IntNative <: WrappingOp<IntNative>

功能：为 IntNative 实现 WrappingOp 接口。

func wrappingAdd(IntNative)

public func wrappingAdd(y: IntNative): IntNative

功能：使用高位截断策略的加法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: IntNative - 加数。

返回值：

IntNative - 加法运算结果。

func wrappingDec()

public func wrappingDec(): IntNative

功能：使用高位截断策略的自减运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

IntNative - 自减运算结果。

func wrappingDiv(IntNative)

public func wrappingDiv(y: IntNative): IntNative

功能：使用高位截断策略的除法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: IntNative - 除数。

返回值：

IntNative - 除法运算结果。

func wrappingInc()

public func wrappingInc(): IntNative

功能：使用高位截断策略的自增运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

IntNative - 自增运算结果。

func wrappingMod(IntNative)

public func wrappingMod(y: IntNative): IntNative

功能：使用高位截断策略的取余运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: IntNative - 除数。

返回值：

IntNative - 取余运算结果。

func wrappingMul(IntNative)

public func wrappingMul(y: IntNative): IntNative

功能：使用高位截断策略的乘法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: IntNative - 乘数。

返回值：

IntNative - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): IntNative

功能：使用高位截断策略的负号运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

IntNative - 负号运算结果。

func wrappingShl(IntNative)

public func wrappingShl(y: IntNative): IntNative

功能：使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数或小于 0 时，取右操作数的低位作为移位位数，具体取的位数取决于当前系统下 IntNative 的位数。

参数：

y: IntNative - 移位位数。

返回值：

IntNative - 左移运算结果。

func wrappingShr(IntNative)

public func wrappingShr(y: IntNative): IntNative

功能：使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数或小于 0 时，取右操作数的低位作为移位位数，具体取的位数取决于当前系统下 IntNative 的位数。

参数：

y: IntNative - 移位位数。

返回值：

IntNative - 右移运算结果。

func wrappingSub(IntNative)

public func wrappingSub(y: IntNative): IntNative

功能：使用高位截断策略的减法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: IntNative - 减数。

返回值：

IntNative - 减法运算结果。

extend UInt16 <: WrappingOp

extend UInt16 <: WrappingOp<UInt16>

功能：为 UInt16 实现 WrappingOp 接口。

func wrappingAdd(UInt16)

public func wrappingAdd(y: UInt16): UInt16

功能：使用高位截断策略的加法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt16 - 加数。

返回值：

UInt16 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): UInt16

功能：使用高位截断策略的自减运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UInt16 - 自减运算结果。

func wrappingDiv(UInt16)

public func wrappingDiv(y: UInt16): UInt16

功能：使用高位截断策略的除法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt16 - 除数。

返回值：

UInt16 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): UInt16

功能：使用高位截断策略的自增运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UInt16 - 自增运算结果。

func wrappingMod(UInt16)

public func wrappingMod(y: UInt16): UInt16

功能：使用高位截断策略的取余运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt16 - 除数。

返回值：

UInt16 - 取余运算结果。

func wrappingMul(UInt16)

public func wrappingMul(y: UInt16): UInt16

功能：使用高位截断策略的乘法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt16 - 乘数。

返回值：

UInt16 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): UInt16

功能：使用高位截断策略的负号运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UInt16 - 负号运算结果。

func wrappingShl(UInt16)

public func wrappingShl(y: UInt16): UInt16

功能：使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数时，取右操作数的低 4 位作为移位位数。

参数：

y: UInt16 - 移位位数。

返回值：

UInt16 - 左移运算结果。

func wrappingShr(UInt16)

public func wrappingShr(y: UInt16): UInt16

功能：使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数时，取右操作数的低 4 位作为移位位数。

参数：

y: UInt16 - 移位位数。

返回值：

UInt16 - 右移运算结果。

func wrappingSub(UInt16)

public func wrappingSub(y: UInt16): UInt16

功能：使用高位截断策略的减法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt16 - 减数。

返回值：

UInt16 - 减法运算结果。

extend UInt32 <: WrappingOp

extend UInt32 <: WrappingOp<UInt32>

功能：为 UInt32 实现 WrappingOp 接口。

func wrappingAdd(UInt32)

public func wrappingAdd(y: UInt32): UInt32

功能：使用高位截断策略的加法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt32 - 加数。

返回值：

UInt32 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): UInt32

功能：使用高位截断策略的自减运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UInt32 - 自减运算结果。

func wrappingDiv(UInt32)

public func wrappingDiv(y: UInt32): UInt32

功能：使用高位截断策略的除法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt32 - 除数。

返回值：

UInt32 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): UInt32

功能：使用高位截断策略的自增运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UInt32 - 自增运算结果。

func wrappingMod(UInt32)

public func wrappingMod(y: UInt32): UInt32

功能：使用高位截断策略的取余运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt32 - 除数。

返回值：

UInt32 - 取余运算结果。

func wrappingMul(UInt32)

public func wrappingMul(y: UInt32): UInt32

功能：使用高位截断策略的乘法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt32 - 乘数。

返回值：

UInt32 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): UInt32

功能：使用高位截断策略的负号运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UInt32 - 负号运算结果。

func wrappingShl(UInt32)

public func wrappingShl(y: UInt32): UInt32

功能：使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数时，取右操作数的低 5 位作为移位位数。

参数：

y: UInt32 - 移位位数。

返回值：

UInt32 - 左移运算结果。

func wrappingShr(UInt32)

public func wrappingShr(y: UInt32): UInt32

功能：使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数时，取右操作数的低 5 位作为移位位数。

参数：

y: UInt32 - 移位位数。

返回值：

UInt32 - 右移运算结果。

func wrappingSub(UInt32)

public func wrappingSub(y: UInt32): UInt32

功能：使用高位截断策略的减法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt32 - 减数。

返回值：

UInt32 - 减法运算结果。

extend UInt64 <: WrappingOp

extend UInt64 <: WrappingOp<UInt64>

功能：为 UInt64 实现 WrappingOp 接口。

func wrappingAdd(UInt64)

public func wrappingAdd(y: UInt64): UInt64

功能：使用高位截断策略的加法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt64 - 加数。

返回值：

UInt64 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): UInt64

功能：使用高位截断策略的自减运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UInt64 - 自减运算结果。

func wrappingDiv(UInt64)

public func wrappingDiv(y: UInt64): UInt64

功能：使用高位截断策略的除法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt64 - 除数。

返回值：

UInt64 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): UInt64

功能：使用高位截断策略的自增运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UInt64 - 自增运算结果。

func wrappingMod(UInt64)

public func wrappingMod(y: UInt64): UInt64

功能：使用高位截断策略的取余运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt64 - 除数。

返回值：

UInt64 - 取余运算结果。

func wrappingMul(UInt64)

public func wrappingMul(y: UInt64): UInt64

功能：使用高位截断策略的乘法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt64 - 乘数。

返回值：

UInt64 - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): UInt64

功能：使用高位截断策略的负号运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UInt64 - 负号运算结果。

func wrappingShl(UInt64)

public func wrappingShl(y: UInt64): UInt64

功能：使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数时，取右操作数的低 6 位作为移位位数。

参数：

y: UInt64 - 移位位数。

返回值：

UInt64 - 左移运算结果。

func wrappingShr(UInt64)

public func wrappingShr(y: UInt64): UInt64

功能：使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数时，取右操作数的低 6 位作为移位位数。

参数：

y: UInt64 - 移位位数。

返回值：

UInt64 - 右移运算结果。

func wrappingSub(UInt64)

public func wrappingSub(y: UInt64): UInt64

功能：使用高位截断策略的减法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt64 - 减数。

返回值：

UInt64 - 减法运算结果。

extend UInt8 <: WrappingOp

extend UInt8 <: WrappingOp<UInt8>

功能：为 UInt8 实现 WrappingOp 接口。

func wrappingAdd(UInt8)

public func wrappingAdd(y: UInt8): UInt8

功能：使用高位截断策略的加法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt8 - 加数。

返回值：

UInt8 - 加法运算结果。

func wrappingDec()

public func wrappingDec(): UInt8

功能：使用高位截断策略的自减运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UInt8 - 自减运算结果。

func wrappingDiv(UInt8)

public func wrappingDiv(y: UInt8): UInt8

功能：使用高位截断策略的除法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt8 - 除数。

返回值：

UInt8 - 除法运算结果。

func wrappingInc()

public func wrappingInc(): UInt8

功能：使用高位截断策略的自增运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UInt8 - 自增运算结果。

func wrappingMod(UInt8)

public func wrappingMod(y: UInt8): UInt8

功能：使用高位截断策略的取余运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt8 - 除数。

返回值：

UInt8 - 取余运算结果。

func wrappingMul(UInt8)

public func wrappingMul(y: UInt8): UInt8

功能：使用高位截断策略的乘法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: 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

功能：使用高位截断策略的减法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UInt8 - 减数。

返回值：

UInt8 - 减法运算结果。

extend UIntNative <: WrappingOp

extend UIntNative <: WrappingOp<UIntNative>

功能：为 UIntNative 实现 WrappingOp 接口。

func wrappingAdd(UIntNative)

public func wrappingAdd(y: UIntNative): UIntNative

功能：使用高位截断策略的加法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UIntNative - 加数。

返回值：

UIntNative - 加法运算结果。

func wrappingDec()

public func wrappingDec(): UIntNative

功能：使用高位截断策略的自减运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UIntNative - 自减运算结果。

func wrappingDiv(UIntNative)

public func wrappingDiv(y: UIntNative): UIntNative

功能：使用高位截断策略的除法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UIntNative - 除数。

返回值：

UIntNative - 除法运算结果。

func wrappingInc()

public func wrappingInc(): UIntNative

功能：使用高位截断策略的自增运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UIntNative - 自增运算结果。

func wrappingMod(UIntNative)

public func wrappingMod(y: UIntNative): UIntNative

功能：使用高位截断策略的取余运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UIntNative - 除数。

返回值：

UIntNative - 取余运算结果。

func wrappingMul(UIntNative)

public func wrappingMul(y: UIntNative): UIntNative

功能：使用高位截断策略的乘法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

y: UIntNative - 乘数。

返回值：

UIntNative - 乘法运算结果。

func wrappingNeg()

public func wrappingNeg(): UIntNative

功能：使用高位截断策略的负号运算。

当运算出现溢出时，高位截断，否则返回运算结果。

返回值：

UIntNative - 负号运算结果。

func wrappingShl(UIntNative)

public func wrappingShl(y: UIntNative): UIntNative

功能：使用高位截断策略的左移运算。

当右操作数大于等于左操作数位数时，取右操作数的低位作为移位位数，具体取的位数取决于当前系统下 UIntNative 的位数。

参数：

y: UIntNative - 移位位数。

返回值：

UIntNative - 左移运算结果。

func wrappingShr(UIntNative)

public func wrappingShr(y: UIntNative): UIntNative

功能：使用高位截断策略的右移运算。

当右操作数大于等于左操作数位数时，取右操作数的低位作为移位位数，具体取的位数取决于当前系统下 UIntNative 的位数。

参数：

y: UIntNative - 移位位数。

返回值：

UIntNative - 右移运算结果。

func wrappingSub(UIntNative)

public func wrappingSub(y: UIntNative): UIntNative

功能：使用高位截断策略的减法运算。

当运算出现溢出时，高位截断，否则返回运算结果。

参数：

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))
}

运行结果如下：

抛出异常策略的示例

下面是抛出异常策略的示例，示例中尝试运算 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))
}

运行结果如下：

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]。

返回值：用户指定位长的伪随机数。

异常:

IllegalArgumentException - 如果 bits 等于 0 ，或大于 64，超过所能截取的 UInt64 长度，则抛出异常。

func nextBool()

public open func nextBool(): Bool

功能：获取一个布尔类型的伪随机值。

返回值：

Bool - 一个 Bool 类型的伪随机数。

func nextFloat16()

public open func nextFloat16(): Float16

功能：获取一个 Float16 类型的伪随机数，其范围为 [0.0, 1.0)。

返回值：

Float16 - 一个 Float16 类型的伪随机数。

func nextFloat32()

public open func nextFloat32(): Float32

功能：获取一个 Float32 类型的伪随机数，其范围为 [0.0, 1.0)。

返回值：

Float32 - 一个 Float32 类型的伪随机数。

func nextFloat64()

public open func nextFloat64(): Float64

功能：获取一个 Float64 类型的伪随机数，其范围为 [0.0, 1.0)。

返回值：

Float64 - 一个 Float64 类型的伪随机数。

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。

返回值：

Float16 - 一个 Float16 类型的随机数。

func nextGaussianFloat16Implement(Float16, Float16)

protected open func nextGaussianFloat16Implement(mean: Float16, sigma: Float16): Float16

功能: nextGaussianFloat16 的实现函数，获取一个 Float16 类型的符合指定均值与标准差的高斯分布的随机数。

获取一个 Float16 类型，且符合均值为 mean 标准差为 sigma 的高斯分布的随机数。其中均值是期望值，可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。此函数是 nextGaussianFloat16 的实现函数，非公开，当子类继承 Random 并覆写此函数时，调用子类的 nextGaussianFloat16 函数将会返回此函数的返回值。

参数：

mean: Float16 - 均值。
sigma: Float16 - 标准差。

返回值：

Float16 - 一个 Float16 类型的随机数。

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。

返回值：

Float32 - 一个 Float32 类型的随机数。

func nextGaussianFloat32Implement(Float32, Float32)

protected open func nextGaussianFloat32Implement(mean: Float32, sigma: Float32): Float32

功能: nextGaussianFloat32 的实现函数，获取一个 Float32 类型的符合指定均值与标准差的高斯分布的随机数。

获取一个 Float32 类型，且符合均值为 mean 标准差为 sigma 的高斯分布的随机数。其中均值是期望值，可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。此函数是 nextGaussianFloat32 的实现函数，非公开，当子类继承 Random 并覆写此函数时，调用子类的 nextGaussianFloat32 函数将会返回此函数的返回值。

参数：

mean: Float32 - 均值。
sigma: Float32 - 标准差。

返回值：

Float32 - 一个 Float32 类型的随机数。

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。

返回值：

Float64 - 一个 Float64 类型的随机数。

func nextGaussianFloat64Implement(Float64, Float64)

protected open func nextGaussianFloat64Implement(mean: Float64, sigma: Float64): Float64

功能: nextGaussianFloat64 的实现函数，获取一个 Float64 类型的符合指定均值与标准差的高斯分布的随机数。

获取一个 Float64 类型，且符合均值为 mean 标准差为 sigma 的高斯分布的随机数。其中均值是期望值，可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。此函数是 nextGaussianFloat64 的实现函数，非公开，当子类继承 Random 并覆写此函数时，调用子类的 nextGaussianFloat64 函数将会返回此函数的返回值。

参数：

mean: Float64 - 均值。
sigma: Float64 - 标准差。

返回值：

Float64 - 一个 Float64 类型的随机数。

func nextInt16()

public open func nextInt16(): Int16

功能：获取一个 Int16 类型的伪随机数。

返回值：

Int16 - 一个 Int16 类型的伪随机数。

func nextInt16(Int16)

public open func nextInt16(upper: Int16): Int16

功能：获取一个范围在 [0, upper) 的 Int16 类型的伪随机数。

参数：

upper: Int16 - 表示生成的伪随机数范围上界（不包括 upper），取值范围 (0, Int16.Max]。

返回值：

Int16 - 一个 Int16 类型的伪随机数。

异常：

IllegalArgumentException - 如果 upper 小于等于 0，抛出异常。

func nextInt32()

public open func nextInt32(): Int32

功能：获取一个 Int32 类型的伪随机数。

返回值：

Int32 - 一个 Int32 类型的伪随机数。

func nextInt32(Int32)

public open func nextInt32(upper: Int32): Int32

功能：获取一个范围在 [0, upper) 的 Int32 类型的伪随机数。

参数：

upper: Int32 - 表示生成的伪随机数范围上界（不包括 upper），取值范围 (0, Int32.Max]。

返回值：

Int32 - 一个 Int32 类型的伪随机数。

异常：

IllegalArgumentException - 如果 upper 小于等于 0，抛出异常。

func nextInt64()

public open func nextInt64(): Int64

功能：获取一个 Int64 类型的伪随机数。

返回值：

Int64 - 一个 Int64 类型的伪随机数。

func nextInt64(Int64)

public open func nextInt64(upper: Int64): Int64

功能：获取一个范围在 [0, upper) 的 Int64 类型的伪随机数。

参数：

upper: Int64 - 生成的伪随机数范围上界（不包括 upper），取值范围 (0, Int64.Max]。

返回值：

Int64 - 一个 Int64 类型的伪随机数。

异常：

IllegalArgumentException - 如果 upper 小于等于 0，抛出异常。

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 类型的伪随机数。

异常：

IllegalArgumentException - 如果 upper 小于等于 0，抛出异常。

func nextUInt16()

public open func nextUInt16(): UInt16

功能：获取一个 UInt16 类型的伪随机数。

返回值：

UInt16 - 一个 UInt16 类型的伪随机数。

func nextUInt16(UInt16)

public open func nextUInt16(upper: UInt16): UInt16

功能：获取一个范围在 [0, upper) 的 UInt16 类型的伪随机数。

参数：

upper: UInt16 - 生成的伪随机数范围上界（不包括 upper），取值范围 (0, UInt16.Max]。

返回值：

UInt16 - 一个 UInt16 类型的伪随机数。

异常：

IllegalArgumentException - 如果 upper 等于 0，抛出异常。

func nextUInt32()

public open func nextUInt32(): UInt32

功能：获取一个 UInt32 类型的伪随机数。

返回值：

UInt32 - 一个 UInt32 类型的伪随机数。

func nextUInt32(UInt32)

public open func nextUInt32(upper: UInt32): UInt32

功能：获取一个范围在 [0, upper) 的 UInt32 类型的伪随机数。

参数：

upper: UInt32 - 生成的伪随机数范围上界（不包括 upper），取值范围 (0, UInt32.Max]。

返回值：

UInt32 - 一个 UInt32 类型的伪随机数。

异常：

IllegalArgumentException - 如果 upper 等于 0，抛出异常。

func nextUInt64()

public open func nextUInt64(): UInt64

功能：获取一个 UInt64 类型的伪随机数。

返回值：

UInt64 - 一个 UInt64 类型的伪随机数。

func nextUInt64(UInt64)

public open func nextUInt64(upper: UInt64): UInt64

功能：获取一个范围在 [0, upper) 的 UInt64 类型的伪随机数。

参数：

upper: UInt64 - 生成的伪随机数范围上界（不包括 upper），取值范围 (0, UInt64.Max]。

返回值：

UInt64 - 一个 UInt64 类型的伪随机数。

异常：

IllegalArgumentException - 如果 upper 等于 0，抛出异常。

func nextUInt8()

public open func nextUInt8(): UInt8

功能：获取一个 UInt8 类型的伪随机数。

返回值：

UInt8 - 一个 UInt8 类型的伪随机数。

func nextUInt8(UInt8)

public open func nextUInt8(upper: UInt8): UInt8

功能：获取一个范围在 [0, upper) 的 UInt8 类型的伪随机数。

参数：

upper: UInt8 - 生成的伪随机数范围上界（不包括 upper），取值范围 (0, UInt8.Max]。

返回值：

UInt8 - 一个 UInt8 类型的伪随机数。

异常：

IllegalArgumentException - 如果 upper 等于 0，抛出异常。

func nextUInt8s(Array<UInt8>)

public open func nextUInt8s(array: Array<UInt8>): Array<UInt8>

功能：生成随机数替换入参数组中的每个元素。

参数：

array: Array<UInt8> - 被替换的数组

返回值：

Array<UInt8> - 返回替换后的 Array。

std.reflect 包

功能介绍

reflect 包提供了反射功能，使得程序在运行时能够获取到各种实例的类型信息，并进行各种读写和调用操作。

本包暂不支持 macOS 平台。

注意：

对于全局信息仓颉的反射功能只能访问公开的全局变量和全局函数。

对于当前所在包，仓颉的反射功能可以访问所有全局定义的类型，而对于外部导入的包或动态加载的模块，则只能访问其中公开的全局定义的类型。

对于成员信息仓颉的反射功能只能访问类型内的公开成员（实例/静态成员变量/属性/函数），使用非 public 修饰符修饰的或缺省修饰符的成员均是不可见的。

目前，仓颉的反射功能尚不支持 Nothing 类型、函数类型、元组类型、enum 类型和带有泛型的 struct 类型。

API 列表

函数

函数名	功能
parseParameterTypes(String)	将字符串转换为包含具体类型信息的函数签名，以便 `getStaticFunction` 等函数使用。

类

类名	功能
TypeInfo	`TypeInfo`提供了所有数据类型通用的操作接口，支持用户进行反射操作。
ClassTypeInfo	描述`class`类型的类型信息。
InterfaceTypeInfo	描述`interface`类型的类型信息。
PrimitiveTypeInfo	描述原始数据类型的类型信息。
StructTypeInfo	描述`struct`类型的类型信息。
InfoList	信息列表，用于保存只读的反射信息。
ConstructorInfo	描述构造函数信息。
ParameterInfo	描述函数形参信息。
InstanceFunctionInfo	描述实例成员函数信息。
StaticFunctionInfo	描述静态成员函数信息。
InstancePropertyInfo	描述实例成员属性信息。
StaticPropertyInfo	描述静态成员属性信息。
InstanceVariableInfo	描述实例成员变量信息。
StaticVariableInfo	描述静态成员变量信息。
ModuleInfo	描述模块信息，提供了仓颉动态模块加载、缓存能力以及模块内包信息查询能力。
PackageInfo	描述包信息。
GlobalFunctionInfo	描述全局函数信息。
GlobalVariableInfo	描述全局变量信息。

枚举

枚举名	功能
ModifierInfo	描述修饰符信息。

异常类

异常类名	功能
ReflectException	`ReflectException` 为 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 - 函数参数类型限定名称。

返回值：

Array<TypeInfo> - 字符串对应的参数类型信息。

异常：

IllegalArgumentException - 字符串格式错误，则会抛出异常。
InfoNotFoundException - 如果无法获得参数中的类型信息，则会抛出异常。

类

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 类型中根据实参列表搜索匹配的构造函数并调用，传入实参列表，返回调用结果。

参数：

args: Array<Any> - 实参列表。

返回值：

Any - 该 class 类型的实例。

异常：

IllegalTypeException - 如果该 class 类型拥有 abstract 语义，调用 construct 则抛出异常，因为抽象类不可被实例化。
MisMatchException - 如果 args 未能成功匹配任何该 class 类型的公开构造函数，则抛出异常。
InvocationTargetException - 在被调用的构造函数内部抛出的任何异常均将被封装为 InvocationTargetException 异常并抛出。

func getConstructor(Array<TypeInfo>)

public func getConstructor(parameterTypes: Array<TypeInfo>): ConstructorInfo

功能：尝试在该 ClassTypeInfo 对应的 class 类型中获取与给定形参类型信息列表匹配的公开构造函数的信息。

参数：

parameterTypes: Array<TypeInfo> - 形参类型信息列表。

返回值：

ConstructorInfo - 如果成功匹配则返回该公开构造函数的信息。

异常：

InfoNotFoundException - 如果没找到对应公开构造函数，则抛出异常。

func getInstanceVariable(String)

public func getInstanceVariable(name: String): InstanceVariableInfo

功能：给定变量名称，尝试获取该 ClassTypeInfo 所对应的 class 类型中匹配的实例成员变量的信息。

参数：

name: String - 变量名称。

返回值：

InstanceVariableInfo - 如果成功匹配则返回该实例成员变量的信息。

异常：

InfoNotFoundException - 如果没找到对应实例成员变量，则抛出异常。

func getStaticVariable(String)

public func getStaticVariable(name: String): StaticVariableInfo

功能：给定变量名称，尝试获取该 ClassTypeInfo 所对应的 class 类型中匹配的静态成员变量的信息。

参数：

name: String - 变量名称。

返回值：

StaticVariableInfo - 如果成功匹配则返回该静态成员变量的信息。

异常：

InfoNotFoundException - 如果没找到对应静态成员变量，则抛出异常。

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 类型中定义的构造函数不支持被调用。

参数：

args: Array<Any> - 实参列表。

返回值：

Any - 由该构造函数构造得到的类型实例。

异常：

InvocationTargetException - 如果该构造函数信息所对应的构造函数所属的类型是抽象类，则会抛出异常。
IllegalArgumentException - 如果实参列表 args 中的实参的数目与该构造函数信息所对应的构造函数的形参列表中的形参的数目不等，则抛出异常。
IllegalTypeException - 如果实参列表 args 中的任何一个实参的运行时类型不是该构造函数信息所对应的构造函数的对应形参的声明类型的子类型，则抛出异常。
Exception - 如果被调用的构造函数信息所对应的构造函数内部抛出异常，则该异常将被封装为 Exception 异常并抛出。

func findAnnotation<T>()

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

功能：判断该构造器信息与给定的另一个构造器信息是否不等。

参数：

that: ConstructorInfo - 被比较相等性的另一个构造器信息。

返回值：

Bool - 如果该构造器信息与 that 不等则返回 true，否则返回 false。

operator func ==(ConstructorInfo)

public operator func ==(that: ConstructorInfo): Bool

功能：判断该构造器信息与给定的另一个构造器信息是否相等。

参数：

that: ConstructorInfo - 被比较相等性的另一个构造器信息。

返回值：

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 类型的实例。

参数：

args: Array<Any> - 实参列表。

返回值：

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

功能：判断该全局函数信息与给定的另一个全局函数信息是否相等。

参数：

that: GlobalFunctionInfo - 被比较相等性的另一个全局函数信息。

返回值：

Bool - 如果该全局函数信息与 that 相等则返回 true，否则返回 false。

operator func !=(GlobalFunctionInfo)

public operator func !=(that: GlobalFunctionInfo): Bool

功能：判断该全局函数信息与给定的另一个全局函数信息是否不等。

参数：

that: GlobalFunctionInfo - 被比较相等性的另一个全局函数信息。

返回值：

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

功能：判断该全局变量信息与给定的另一个全局变量信息是否相等。

参数：

that: GlobalVariableInfo - 被比较相等性的另一个全局变量信息。

返回值：

Bool - 如果该全局变量信息与 that 相等则返回 true，否则返回 false。

operator func !=(GlobalVariableInfo)

public operator func !=(that: GlobalVariableInfo): Bool

功能：判断该全局变量信息与给定的另一个全局变量信息是否不等。

参数：

that: GlobalVariableInfo - 被比较相等性的另一个全局变量信息。

返回值：

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 - 该信息列表指定位置上的元素。

异常：

IndexOutOfBoundsException - 如果 index 超出索引范围，则抛出异常。

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>()

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

功能：判断该实例成员函数信息与给定的另一个实例成员函数信息是否相等。

参数：

that: InstanceFunctionInfo - 被比较相等性的另一个实例成员函数信息。

返回值：

Bool - 如果该实例成员函数信息与 that 相等则返回 true，否则返回 false。

operator func !=(InstanceFunctionInfo)

public operator func !=(that: InstanceFunctionInfo): Bool

功能：判断该实例成员函数信息与给定的另一个实例成员函数信息是否不等。

参数：

that: InstanceFunctionInfo - 被比较相等性的另一个实例成员函数信息。

返回值：

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>()

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

功能：判断该实例成员属性信息与给定的另一个实例成员属性信息是否不等。

参数：

that: InstancePropertyInfo - 被比较相等性的另一个实例成员属性信息。

返回值：

Bool - 如果该实例成员属性信息与 that 不等则返回 true，否则返回 false。

operator func ==(InstancePropertyInfo)

public operator func ==(that: InstancePropertyInfo): Bool

功能：判断该实例成员属性信息与给定的另一个实例成员属性信息是否相等。

参数：

that: InstancePropertyInfo - 被比较相等性的另一个实例成员属性信息。

返回值：

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>()

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

功能：判断该实例成员变量信息与给定的另一个实例成员变量信息是否相等。

参数：

that: InstanceVariableInfo - 被比较相等性的另一个实例成员变量信息。

返回值：

Bool - 如果该实例成员变量信息与 that 相等则返回 true，否则返回 false。

operator func !=(InstanceVariableInfo)

public operator func !=(that: InstanceVariableInfo): Bool

功能：判断该实例成员变量信息与给定的另一个实例成员变量信息是否不等。

参数：

that: InstanceVariableInfo - 被比较相等性的另一个实例成员变量信息。

返回值：

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

func find(String)

public static func find(moduleName: String): Option<ModuleInfo>

功能：尝试在所有已加载的仓颉动态库模块中获取与给定模块名称匹配的模块的信息。

参数：

moduleName: String - 仓颉动态库模块名称。

返回值：

Option<ModuleInfo> - 如果匹配成功则返回该模块的信息，否则返回 None。

func getPackageInfo(String)

public func getPackageInfo(packageName: String): PackageInfo

功能：尝试在该 ModuleInfo 对应的模块中获取与给定包的名称或限定名称匹配的包的信息。

参数：

packageName: String - 包的名称或限定名称。

返回值：

PackageInfo - 如果匹配成功则返回该包的信息。

异常：

InfoNotFoundException - 如果没找到对应包，则抛出异常。

func hashCode()

public func hashCode(): Int64

功能：获取该模块信息的哈希值。

返回值：

Int64 - 该模块信息的哈希值。

注意：

内部实现为该模块信息的名称和版本号字符串的哈希值。

func load

public static func load(path: String): ModuleInfo

功能：运行时动态加载指定路径下的一个仓颉动态库模块并获得该模块的信息。

注意：

为了提升兼容性，路径 path 中的共享库文件名不需要后缀名（如 .so 和 .dll 等）。

由于当前实现局限性，具有相同模块名称的动态库不能被同时加载，否则将抛出异常。如 m/a、m/a.b、m/a.c 这三个包所对应的共享库的加载是互斥的。

参数：

path: String - 共享库文件的绝对路径或相对路径。

异常：

ReflectException - 如果共享库加载失败，则会抛出异常。
UnsupportedException - 如果具有相同模块名称的共享库被重复加载，则会抛出异常。

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> - 形参类型信息列表。

异常：

InfoNotFoundException - 如果没找到对应全局定义的公开全局函数，则抛出异常。

func getTypeInfo(String)

public func getTypeInfo(qualifiedName: String): TypeInfo

功能：尝试在该 PackageInfo 对应的包中获取拥有给定类型名称的全局定义的公开类型的类型信息。

参数：

qualifiedName: String - 类型的限定名称

返回值：

TypeInfo - 如果成功匹配则返回该全局定义的公开类型的类型信息。

异常：

InfoNotFoundException - 如果没找到对应全局定义的公开类型，则抛出异常。

func getVariable(String)

public func getVariable(name: String): GlobalVariableInfo

功能：尝试在该 PackageInfo 对应的包中获取拥有给定变量名称的公开全局变量的信息。

参数：

name: String - 全局变量的名称。

异常：

InfoNotFoundException - 如果没找到对应全局定义的公开全局变量，则抛出异常。

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>()

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），整形类型（Int8，Int16，Int32，Int64，IntNative，UInt8，UInt16，UInt32，UInt64，UIntNative）和浮点类型（Float16，Float32，Float64）。

注意：

目前尚不支持 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 类型的实例。

参数：

args: Array<Any> - 实参列表。

返回值：

Any - 该静态成员函数的调用结果。

异常：

IllegalArgumentException - 如果实参列表 args 中的实参的数目与该静态成员函数信息所对应的静态成员函数的形参列表中的形参的数目不等，则抛出异常。
IllegalTypeException - 如果实参列表 args 中的任何一个实参的运行时类型不是该静态成员函数信息所对应的静态成员函数的对应形参的声明类型的子类型，则抛出异常。
Exception - 如果被调用的静态成员函数信息所对应的静态成员函数内部抛出异常，则该异常将被封装为 Exception 异常并抛出。

func findAnnotation<T>()

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

功能：判断该静态成员函数信息与给定的另一个静态成员函数信息是否不等。

参数：

that: StaticFunctionInfo - 被比较相等性的另一个静态成员函数信息。

返回值：

Bool - 如果该静态成员函数信息与 that 不等则返回 true，否则返回 false。

operator func ==(StaticFunctionInfo)

public operator func ==(that: StaticFunctionInfo): Bool

功能：判断该静态成员函数信息与给定的另一个静态成员函数信息是否相等。

参数：

that: StaticFunctionInfo - 被比较相等性的另一个静态成员函数信息。

返回值：

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>()

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

功能：判断该静态成员属性信息与给定的另一个静态成员属性信息是否不等。

参数：

that: StaticPropertyInfo - 被比较相等性的另一个静态成员属性信息。

返回值：

Bool - 如果该静态成员属性信息与 that 不等则返回 true，否则返回 false。

operator func ==(StaticPropertyInfo)

public operator func ==(that: StaticPropertyInfo): Bool

功能：判断该静态成员属性信息与给定的另一个静态成员属性信息是否相等。

参数：

that: StaticPropertyInfo - 被比较相等性的另一个静态成员属性信息。

返回值：

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>()

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

功能：判断该静态成员变量信息与给定的另一个静态成员变量信息是否不等。

参数：

that: StaticVariableInfo - 被比较相等性的另一个静态成员变量信息。

返回值：

Bool - 如果该静态成员变量信息与 that 不等则返回 true，否则返回 false。

operator func ==(StaticVariableInfo)

public operator func ==(that: StaticVariableInfo): Bool

功能：判断该静态成员变量信息与给定的另一个静态成员变量信息是否相等。

参数：

that: StaticVariableInfo - 被比较相等性的另一个静态成员变量信息。

返回值：

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 类型中根据实参列表搜索匹配的构造函数并调用，传入实参列表，返回调用结果。

参数：

args: Array<Any> - 实参列表。

返回值：

Any - 该 struct 类型的实例。

异常：

MisMatchException - 如果 args 未能成功匹配任何该 struct 类型的公开构造函数，则抛出异常
InvocationTargetException - 在被调用的构造函数内部抛出的任何异常均将被封装为 InvocationTargetException 异常并抛出。

注意：

由于 construct 函数本质上调用的是 apply 函数，而目前 struct 类型中定义的构造函数不支持被调用 apply 函数，故该函数目前无法正常使用

func getConstructor(Array<TypeInfo>)

public func getConstructor(parameterTypes: Array<TypeInfo>): ConstructorInfo

功能：尝试在该 StructTypeInfo 对应的 struct 类型中获取与给定形参类型信息列表匹配的公开构造函数的信息。

参数：

parameterTypes: Array<TypeInfo> - 形参类型信息列表。

返回值：

ConstructorInfo - 如果成功匹配则返回该公开构造函数的信息。

异常：

InfoNotFoundException - 如果没找到对应公开构造函数，则抛出异常。

func getInstanceVariable(String)

public func getInstanceVariable(name: String): InstanceVariableInfo

功能：给定变量名称，尝试获取该 StructTypeInfo 对应的 struct 类型中匹配的实例成员变量的信息。

参数：

name: String - 变量名称。

返回值：

InstanceVariableInfo - 如果成功匹配则返回该实例成员变量的信息。

异常：

InfoNotFoundException - 如果没找到对应公开实例成员变量，则抛出异常。

func getStaticVariable(String)

public func getStaticVariable(name: String): StaticVariableInfo

功能：给定变量名称，尝试获取该 StructTypeInfo 对应的 struct 类型中匹配的静态成员变量的信息。

参数：

name: String - 变量名称。

返回值：

StaticVariableInfo - 如果成功匹配则返回该静态成员变量的信息。

异常：

InfoNotFoundException - 如果没找到对应公开静态成员变量，则抛出异常。

class TypeInfo

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

功能：TypeInfo 提供了所有数据类型通用的操作接口。开发者通常无需向下转型为更具体的数据类型，如 ClassTypeInfo 等，就能进行反射操作。

TypeInfo 的子类包括 PrimitiveTypeInfo、StructTypeInfo、ClassTypeInfo 和 InterfaceTypeInfo，分别对应基本数据类型，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 对应的类型无任何公开实例成员函数，则返回空集合。

该集合不保证遍历顺序恒定。

如果该类型信息所对应的类型是 struct 或 class 类型，则该集合包含从其他 interface 类型继承而来的非抽象的实例成员函数的信息。

类型：Collection<InstanceFunctionInfo>

prop instanceProperties

public prop instanceProperties: Collection<InstancePropertyInfo>

功能：获取该 TypeInfo 对应类型的所有公开实例成员属性信息，返回对应集合。

注意：

如果该 TypeInfo 对应的类型无任何公开实例成员属性，则返回空集合。

该集合不保证遍历顺序恒定。

如果该类型信息所对应的类型是 struct 或 class 类型，则该集合包含从其他 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 对应的类型无任何公开静态成员函数，则返回空集合。

该集合不保证遍历顺序恒定。

如果该类型信息所对应的类型是 struct 、class 或 interface 类型，则该集合包含从其他 interface 类型继承而来的非抽象的静态成员函数的信息。

类型：Collection<StaticFunctionInfo>

prop staticProperties

public prop staticProperties: Collection<StaticPropertyInfo>

功能：获取该 TypeInfo 对应类型的所有公开静态成员属性信息，返回对应集合。

注意：

如果该 TypeInfo 对应的类型无任何公开静态成员属性，则返回空集合。

该集合不保证遍历顺序恒定。

如果该类型信息所对应的类型是 struct 、class 或 interface 类型，则该集合包含从其他 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 类型信息，则抛出异常。

func findAnnotation<T>()

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> - 函数形参类型列表所对应的类型信息列表。

返回值：

InstanceFunctionInfo - 如果成功匹配则返回该实例成员函数的信息。

异常：

InfoNotFoundException - 如果没找到对应公开实例成员函数，则抛出异常。

func getInstanceProperty(String)

public func getInstanceProperty(name: String): InstancePropertyInfo

功能：尝试获取该类型中与给定属性名称匹配的实例成员属性的信息。

参数：

name: String - 属性名称。

返回值：

InstancePropertyInfo - 如果成功匹配则返回该实例成员属性的信息。

异常：

InfoNotFoundException - 如果没找到对应公开实例成员属性，则抛出异常。

func getStaticFunction(String, Array<TypeInfo>)

public func getStaticFunction(name: String, parameterTypes: Array<TypeInfo>): StaticFunctionInfo

功能：通过给定函数名称与函数形参类型列表所对应的类型信息列表，尝试获取该类型中匹配的静态成员函数的信息。

参数：

name: String - 函数名称。
parameterTypes: Array<TypeInfo> - 函数形参类型列表所对应的类型信息列表。

返回值：

StaticFunctionInfo - 如果成功匹配则返回该静态成员函数的信息。

异常：

InfoNotFoundException - 如果没找到对应公开静态成员函数，则抛出异常。

func getStaticProperty(String)

public func getStaticProperty(name: String): StaticPropertyInfo

功能：尝试获取该类型中与给定属性名称匹配的静态成员属性的信息。

参数：

name: String - 属性名称。

返回值：

StaticPropertyInfo - 如果成功匹配则返回该静态成员属性的信息。

异常：

InfoNotFoundException - 如果没找到对应公开静态成员属性，则抛出异常。

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 of<T>()

public static func of<T>(): TypeInfo

功能：获取给定类型对应的类型信息。

注意：

目前，泛型 T 不支持 Nothing 类型、函数类型，元组类型，enum 类型和带有泛型的 struct 类型。

T 支持传入类型别名，包括内置类型别名（如 Int、UInt 和 Rune 等）与用户自定义类型别名。

返回值：

TypeInfo - T 类型对应的类型信息。

异常：

InfoNotFoundException - 如果无法获得类型 T 所对应的类型信息，抛出异常。

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 下分别创建两个目录 myModuleDirectory 和 myExecutableDirectory，分别在其中使用 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`能匹配`z`,`zo`以及`zoo`。``等价于`{0,}`。
`+`	匹配前面的子表达式一次或多次。例如，`zo+`能匹配`zo`以及`zoo`，但不能匹配`z`。`+`等价于`{1,}`。
`?`	匹配前面的子表达式零次或一次。例如，`do(es)?`可以匹配`does`中的`do`和`does`。`?`等价于`{0,1}`。
`{n}`	n 是一个非负整数。匹配确定的 n 次。例如，`o{2}`不能匹配`Bob`中的`o`，但是能匹配`food`中的两个`o`。
`{n,}`	n 是一个非负整数。至少匹配 n 次。例如，`o{2,}`不能匹配`Bob`中的`o`，但能匹配`foooood`中的所有`o`。`o{1,}`等价于`o+`。`o{0,}`则等价于`o*`。
`{n,m}`	m 和 n 均为非负整数，其中 n<=m。最少匹配 n 次且最多匹配 m 次。例如，`o{1,3}`将匹配`fooooood`中的前三个`o`。`o{0,1}`等价于`o?`。请注意在逗号和两个数之间不能有空格。
`?`	非贪心量化（Non-greedy quantifiers）：当该字符紧跟在任何一个其他重复修饰符（*,+,?，{n}，{n,}，{n,m}）后面时，匹配模式是非贪婪的。非贪婪模式尽可能少的匹配所搜索的字符串，而默认的贪婪模式则尽可能多的匹配所搜索的字符串。例如，对于字符串`oooo`，`o+?`将匹配单个`o`，而`o+`将匹配所有`o`。
`.`	匹配除`\n`之外的任何单个字符。要匹配包括`\n`在内的任何字符，请使用像`(.\\|\n)`的模式。
`(pattern)`	匹配 pattern 并获取这一匹配的子字符串。该子字符串用于向后引用。所获取的匹配可以从产生的 Matches 集合中得到。要匹配圆括号字符，请使用`$`或`$`。可带数量后缀。
`x\\|y`	没有包围在()里，其范围是整个正则表达式。例如，z\|food 能匹配`z`或`food`。(?:z\|f)ood 则匹配`zood`或`food`。
`[xyz]`	字符集合（character class）。匹配所包含的任意一个字符。例如，`[abc]`可以匹配`plain`中的`a`。特殊字符仅有反斜线\保持特殊含义，用于转义字符。其它特殊字符如星号、加号、各种括号等均作为普通字符。脱字符^如果出现在首位则表示负值字符集合；如果出现在字符串中间就仅作为普通字符。连字符 - 如果出现在字符串中间表示字符范围描述；如果如果出现在首位（或末尾）则仅作为普通字符。右方括号应转义出现，也可以作为首位字符出现。
`[^xyz]`	排除型字符集合（negated character classes）。匹配未列出的任意字符。例如，`[^abc]`可以匹配`plain`中的`plin`。
`[a-z]`	字符范围。匹配指定范围内的任意字符。例如，`[a-z]`可以匹配`a`到`z`范围内的任意小写字母字符。
`[^a-z]`	排除型的字符范围。匹配任何不在指定范围内的任意字符。例如，`[^a-z]`可以匹配任何不在`a`到`z`范围内的任意字符。
`\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:]]`	表示除任意标点符号以外的任意字符。

在仓颉中，还存在一些特殊的规则：

?、+、* 前面的字符不可量化时, 会被忽略; 特例：(*、|*、* 开头时 * 会被视为普通字符。
*? 在匹配全部 *? 之前的字符组成的字符串时，会匹配不到该字符。
正则表达式的捕获组的最大个数为 63，编译后的最大规则长度为 65535。
暂不支持的场景：((pattern1){m1,n1}pattern2){m2,n2}，即： a：组定义 1 被{m1,n1}修饰； b：组定义 1 被组定义 2 包裹； c：组定义 2 被{m2,n2}修饰。

API 列表

类

类名	功能
Matcher	正则匹配器，用于扫描输入序列并进行匹配。
MatchData	存储正则表达式匹配结果，并提供对正则匹配结果进行查询的函数。
Regex	用来指定编译类型和输入序列。
RegexOption	用于指定正则匹配的模式。

结构体

枚举名	功能
Position	用来存储位置信息，表示的是一个前闭后开区间。

异常类

异常类名	功能
RegexException	提供 io 流相关的异常处理。

类

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 - 对应捕获组的位置信息。

异常：

IndexOutOfBoundsException - 当 group 小于 0 或者大于 groupNumber 时，抛出异常。
RegexException - 当 group 不为 0 且没有捕获组时，抛出异常。

func matchStr()

public func matchStr(): String

功能：获取上一次匹配到的子字符串，结果与调用 matchStr(0) 相同。

返回值：

String - 匹配到的子字符串。

异常：

IndexOutOfBoundsException - 当匹配字符串数组长度小于 1，抛出异常。

func matchStr(Int64)

public func matchStr(group: Int64): String

功能：根据给定的索引获取上一次匹配中该捕获组匹配到的子字符串。

捕获组的索引从 1 开始，索引为 0 表示获取整个正则表达式的匹配结果。

参数：

group: Int64 - 指定组。

返回值：

String - 匹配到的子字符串。

异常：

IndexOutOfBoundsException - 当 group 小于 0 或者大于 groupNumber 时，抛出异常。
RegexException - 当 group 不为 0 且没有捕获组时，抛出异常。

class Matcher

public class Matcher {
    public init(re: Regex, input: String)
}

功能：正则匹配器，用于扫描输入序列并进行匹配。

注意：

要匹配的字符串最大长度不得超过 2³¹-1。

要使用 replaceAll 替换的字符串最大长度不得超过 2³⁰-2。

init(Regex, String)

public init(re: Regex, input: String)

功能：使用传入的正则表达式和输入序列创建 Matcher 实例。

参数：

re: Regex - 正则表达式。
input: String - 输入序列。

异常：

RegexException - 当初始化失败时，抛出异常。
IllegalArgumentException - 当 input 中包含空字符或长度大于2³¹-1时，抛出异常。

func allCount()

public func allCount(): Int64

功能：获取正则表示式的匹配结果总数。

默认是从头到尾匹配的结果，使用了 setRegion 后只会在设置的范围内查找。

返回值：

Int64 - 匹配结果总数。

func find()

public func find(): Option<MatchData>

功能：自当前字符串偏移位置起，查找第一个匹配到的子序列。

find 调用一次，当前偏移位置为最新一次匹配到的子序列后第一个字符位置，下次调用, find 从当前位置开始匹配。

返回值：

Option<MatchData> - 匹配到结果返回 Option<MatchData>，如果匹配不到，返回 Option<MatchData>.None。

异常：

RegexException - 当重置匹配器失败时，抛出异常。

func find(Int64)

public func find(index: Int64): Option<MatchData>

功能：重置该匹配器索引位置，从 index 对应的位置处开始对输入序列进行匹配, 返回匹配到的子序列。

返回值：

Option<MatchData> - 匹配到结果返回 Option<MatchData>，如果匹配不到，返回 Option<MatchData>.None。

异常：

IndexOutOfBoundsException - 当 index 小于 0，或 index 大于等于输入序列的 size 时，抛出异常。
RegexException - 当重置匹配器失败时，抛出异常。

func findAll()

public func findAll(): Option<Array<MatchData>>

功能：对整个输入序列进行匹配，查找所有匹配到的子序列。

返回值：

Option < Array<MatchData>> - 如果匹配到结果，返回 Option<Array<MatchData>>；如果匹配不到，返回 Option<Array<MatchData>>.None

异常：

RegexException - 当重置匹配器内存分配失败或申请内存失败时，抛出异常。

func fullMatch()

public func fullMatch(): Option<MatchData>

功能：对整个输入序列进行匹配。

返回值：

Option<MatchData> - 如果全部匹配成功，返回 Option<MatchData>；否则返回 Option<MatchData>.None。

func getString()

public func getString(): String

功能：获取匹配序列。

返回值：

String - 匹配序列。

func matchStart()

public func matchStart(): Option<MatchData>

功能：对输入序列的头部进行匹配。

返回值：

Option<MatchData> - 如果匹配成功，返回 Option<MatchData>；否则返回 Option<MatchData>.None。

异常：

RegexException - 当重置匹配器失败时，抛出异常。

func region()

public func region(): Position

功能：返回匹配器的区域设置。

返回值：

Position - 匹配器的区域设置。

func replace(String)

public func replace(replacement: String): String

功能：自当前字符串偏移位置起，匹配到的第一个子序列替换为目标字符串, 并将当前索引位置设置到匹配子序列的下一个位置。

参数：

replacement: String - 指定替换字符串。

返回值：

String - 替换后字符串。

异常：

RegexException - 当重置匹配器失败时，抛出异常。
IllegalArgumentException - 当 replacement 长度大于 2³⁰-2，或者 replacement 包含空字符时，抛出异常。

func replace(String, Int64)

public func replace(replacement: String, index: Int64): String

功能：从输入序列的 index 位置起匹配正则，将匹配到的第一个子序列替换为目标字符串。

参数：

replacement: String - 指定替换字符串。
index: Int64 - 匹配开始位置。

返回值：

String - 替换后字符串。

异常：

IndexOutOfBoundsException - 当 index 小于 0，或 index 大于等于输入序列的 size 时，抛出异常。
RegexException - 当重置匹配器失败时，抛出异常。
IllegalArgumentException - 当 replacement 长度大于 2³⁰-2，或者 replacement 包含空字符时，抛出异常。

func replaceAll(String)

public func replaceAll(replacement: String): String

功能：将输入序列中所有与正则匹配的子序列替换为给定的目标字符串。

参数：

replacement: String - 指定替换字符串。

返回值：

String - 替换后的字符串。

异常：

RegexException - 当重置匹配器失败时，或者 c 侧申请内存失败，或者替换字符串时发生了 GC 时，抛出异常。
IllegalArgumentException - 当 replacement 长度大于 2³⁰-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 长度大于 2³⁰-2，或者 replacement 包含空字符时，抛出异常。

func resetRegion()

public func resetRegion(): Matcher

功能：重置匹配器开始位置和结束位置。

返回值：

Matcher - 匹配器自身。

异常：

RegexException - 当重置匹配器失败时，抛出异常。

func resetString(String)

public func resetString(input: String): Matcher

功能：重设匹配序列，并重置匹配器。

参数：

input: String - 新的匹配序列。

返回值：

Matcher - 匹配器自身。

异常：

RegexException - 当重置匹配器失败时，抛出异常。
IllegalArgumentException - 当 input 长度大于 2³¹-1 或者包含空字符时，抛出异常。

func setRegion(Int64, Int64)

public func setRegion(beginIndex: Int64, endIndex: Int64): Matcher

功能：设置匹配器可搜索区域的位置信息，具体位置由指定的 begin 和 end 决定。

参数：

beginIndex: Int64 - 区域开始位置。
endIndex: Int64 - 区域结束位置。

返回值：

Matcher - 匹配器自身。

异常：

IndexOutOfBoundsException - 当 beginIndex 小于0，或 beginIndex 大于输入序列的 size 时，抛出异常。
IndexOutOfBoundsException - 当 endIndex 小于0，或 endIndex 大于输入序列的 size 时，抛出异常。
IndexOutOfBoundsException - 当 beginIndex 大于 endIndex 时，抛出异常。

func split()

public func split(): Array<String>

功能：将给定的输入序列根据正则尽可能的分割成多个子序列。

返回值：

Array<String> - 子序列数组。

func split(Int64)

public func split(limit: Int64): Array<String>

功能：将给定的输入序列根据正则尽可能的分割成多个子序列 (最多分割成 limit 个子串)。

参数：

limit: Int64 - 最多分割的子串个数。

返回值：

Array<String> - 如果 limit>0, 返回最多 limit 个子串；如果 limit<=0, 返回最大可分割数个子串。

异常：

RegexException - 当重置匹配器失败时，抛出异常。

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 - 正则表达式。

异常：

RegexException - 当初始化失败时，抛出异常。
IllegalArgumentException - 当 s 中包含空字符时，抛出异常。

init(String, RegexOption)

public init(s: String, option: RegexOption)

功能：使用指定的模式创建一个 Regex 实例。

参数：

s: String - 正则表达式。
option: RegexOption - 正则匹配的模式。

异常：

RegexException - 当初始化失败时，抛出异常。
IllegalArgumentException - 当 s 中包含空字符时，抛出异常。

func matcher(String)

public func matcher(input: String): Matcher

功能：创建匹配器。

参数：

input: String - 要匹配的字符串, 字符串长度最大 2³¹ - 1。

返回值：

Matcher - 创建的匹配器。

异常：

RegexException - 当初始化失败时，抛出异常。
IllegalArgumentException - 当 input 中包含空字符时，抛出异常。

func matches(String)

public func matches(input: String): Option<MatchData>

功能：创建匹配器，并将入参 input 与正则表达式进行完全匹配。

参数：

input: String - 要匹配的字符串, 字符串长度最大 2³¹ - 1。

返回值：

Option<MatchData> - 如果匹配成功，返回 Option<MatchData>，否则返回 Option<MatchData>.None。

异常：

RegexException - 当初始化失败时，抛出异常。
IllegalArgumentException - 当 input 中包含空字符时，抛出异常。

func string()

public func string(): 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）。

返回值：

RegexOption - 修改后的 RegexOption。

func multiLine()

public func multiLine(): RegexOption

功能：修改 RegexOption，修改匹配模式为多行文本模式（MULTILINE）。

返回值：

RegexOption - 修改后的 RegexOption。

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())
}

运行结果：

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	提供获取一些堆内存统计数据的接口。
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

功能：获取仓颉堆实际占用的物理内存大小，单位为 byte。

类型：Int64

static prop maxHeapSize

public static prop maxHeapSize: Int64

功能：获取仓颉堆可以使用的最大值，单位为 byte。

实例：

import std.runtime.*
main() {
  println(MemoryInfo.maxHeapSize)
}

运行结果（以实际环境为准）：

268435456

类型：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 包用于进行网络通信，提供启动 Socket 服务器、连接 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_BROADCAST	IPV4 广播地址。
IPV4_ALL_SYSTEM	IPV4 多播地址。
IPV4_ALL_ROUTER	IPV4 预留的组播地址。
IPV4_ZERO	IPV4 通用地址。
IPV4_LOCAL_HOST	IPV4 本地地址。
IPV6_ZERO	IPV6 通用地址。
IPV6_LOOPBACK	IPV6 环回地址（本地地址）。
IPV6_INTERFACE_LOCAL_ALL_NODES	IPv6 在节点本地范围的所有节点多播地址。
IPV6_LINK_LOCAL_ALL_NODES	IPv6 在链路本地范围的所有节点多播地址。
IPV6_LINK_LOCAL_ALL_ROUTERS	IPv6 链路本地范围的所有路由器多播地址。

接口

接口名	功能
DatagramSocket	`DatagramSocket` 是一种接收和读取数据包的套接字。
ServerSocket	提供服务端的 `Socket` 需要的接口。
StreamingSocket	双工流模式下的运行的 `Socket`，可被读写。

类

类名	功能
IPMask	IP 掩码，操作 IP 地址和路由地址。
RawSocket	`RawSocket` 提供了套接字的基本功能。
SocketAddress	具有特定类型、地址和端口的套接字地址。
SocketAddressWithMask	提供带有掩码的 `SocketAddress`。
TcpServerSocket	监听 TCP 连接的服务端。
TcpSocket	请求 TCP 连接的客户端。
UdpSocket	提供 udp 报文通信。
UnixDatagramSocket	提供基于数据包的主机通讯能力。
UnixServerSocket	提供基于双工流的主机通讯服务端。
UnixSocket	提供基于双工流的主机通讯客户端。

枚举

枚举名	功能
SocketAddressKind	互联网通信协议种类。
SocketNet	传输层协议类型。

结构体

结构体名	功能
OptionLevel	提供了常用的套接字选项级别。
OptionName	提供了常用的套接字选项。
ProtocolType	提供了常用的套接字协议，以及通过指定 `Int32` 值来构建套接字协议的功能。
RawAddress	提供了 `RawSocket` 的通信地址创建和获取功能。
SocketDomain	提供了常用的套接字通信域，以及通过指定 Int32 值来构建套接字通信域的功能。
SocketKeepAliveConfig	TCP KeepAlive 属性配置。
SocketOptions	`SocketOptions` 存储了设置套接字选项的一些参数常量方便后续调用。
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>

let IPV6_LINK_LOCAL_ALL_NODES

public let IPV6_LINK_LOCAL_ALL_NODES: Array<UInt8>

功能：IPv6 在链路本地范围的所有节点多播地址。

类型：Array<UInt8>

let IPV6_LINK_LOCAL_ALL_ROUTERS

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。

如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None。

类型：?Duration

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

prop remoteAddress

prop remoteAddress: ?SocketAddress

功能：读取 Socket 已经连接的远端地址，当 Socket 未连接时返回 None。

类型：?SocketAddress

异常：

SocketException - 当 Socket 已经被关闭时，抛出异常。

prop sendTimeout

mut prop sendTimeout: ?Duration

功能：设置和读取 sendTo 超时时间，默认设置为 None。

如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None。

类型：?Duration

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

func receiveFrom(Array<Byte>)

func receiveFrom(buffer: Array<Byte>): (SocketAddress, Int64)

功能：阻塞式等待收取报文到 buffer 中。

参数：

buffer: Array<Byte> - 存储报文内容的缓存空间，buffer 应当有一个合适的大小，否则可能导致收取报文时报文被截断，并且返回的报文大小值大于 buffer 的大小。

返回值：

(SocketAddress, Int64) - 报文发送地址和收取到的报文大小（可能为 0，或大于参数 buffer 大小）。

异常：

SocketException - 当本机缓存过小无法读取报文时，抛出异常。
SocketTimeoutException - 当读取超时时，抛出异常。

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

异常：

SocketException - 当 Socket 已经被关闭时，抛出异常。

func accept()

func accept(): StreamingSocket

功能：接受一个客户端套接字的连接请求，阻塞式等待连接请求。

返回值：

StreamingSocket - 连接成功的客户端套接字。

func accept(?Duration)

func accept(timeout!: ?Duration): StreamingSocket

功能：接受一个客户端套接字的连接请求，阻塞式等待连接请求。

参数：

timeout!: ?Duration - 等待连接超时的时间。

返回值：

StreamingSocket - 连接成功的客户端套接字。

异常：

SocketTimeoutException - 当等待连接请求超时，抛出异常。
IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

func bind()

func bind(): Unit

功能：绑定套接字。

当没有设置 reuse 属性，本地端口、地址、文件路径已被占用或者上次绑定套接字的连接失败后需要 close 套接字。不支持多次重试此操作后可执行 accept() 操作。

异常：

SocketException - 当因系统原因绑定失败时，抛出异常。

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

功能：设置和读取读超时时间。

如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None。

类型：?Duration

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

prop remoteAddress

prop remoteAddress: SocketAddress

功能：读取 Socket 将要或已经连接的远端地址。

类型：SocketAddress

异常：

SocketException - 当 Socket 已经被关闭时，抛出异常。

prop writeTimeout

mut prop writeTimeout: ?Duration

功能：设置和读取写超时时间。

如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None。

类型：?Duration

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

类

class IPMask

public class IPMask <: ToString {
    public init(buf: Array<UInt8>)
    public init(ones: Int64, bits: Int64)
    public init(a: UInt8, b: UInt8, c: UInt8, d: UInt8)
}

功能：IP 掩码，操作 IP 地址和路由地址。

init(Array<UInt8>)

public init(buf: Array<UInt8>)

功能：初始化掩码值。

参数：

buf: Array<UInt8> - 掩码值。

异常：

IllegalArgumentException - 当 buf 里的值超出阈值，不符合 IPv4/IPv6 要求时，抛出异常。

init(Int64, Int64)

public init(ones: Int64, bits: Int64)

功能：初始化掩码值。

参数：

ones: Int64 - 高位 1 的个数。
bits: Int64 - bit 位总个数。

异常：

IllegalArgumentException - 当 bits 值超出阈值，不符合 IPv4/IPv6 要求时，抛出异常。

init(UInt8, UInt8, UInt8, UInt8)

public init(a: UInt8, b: UInt8, c: UInt8, d: UInt8)

功能：初始化掩码值，参数值分别是 IPv4 的 4 个字节 a.b.c.d。

参数：

a: UInt8 - 最高字节。
b: UInt8 - 次高字节。
c: UInt8 - 次低字节。
d: UInt8 - 最低字节。

func size()

public func size(): (Int64, Int64)

功能：获取高位 1 的个数，以及总 bit 位数。

返回值：

(Int64，Int64) - 高位 1 的个数，以及总 bit 位数，若掩码格式不符合高位均为 1 的格式，返回 (0, 0)。

func toString()

public func toString(): String

功能：将 IP 掩码转换为字符串。

返回值：

String - 转换后的字符串。

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 协议套接字，其它类型使用上可能存在预期之外的问题。

此外，由于接口的开放性，可以使用 connect 再 listen 的组合，部分场景可能存在预期外的问题。建议开发者使用时遵循正常的调用逻辑，避免产生问题。

prop localAddr

public prop localAddr: RawAddress

功能：获取当前 RawSocket 实例的本地地址。

类型：RawAddress

异常：

SocketException - 当前 RawSocket 实例已经关闭，或无法获取本地地址时，抛出异常。

prop readTimeout

public mut prop readTimeout: ?Duration

功能：获取或设置当前 RawSocket 实例的读超时时间。

类型：?Duration

异常：

SocketException - 当前 RawSocket 实例已经关闭时，抛出异常。
IllegalArgumentException - 当设置的读超时时间为负时，抛出异常。

prop remoteAddr

public prop remoteAddr: RawAddress

功能：获取当前 RawSocket 实例的对端地址。

类型：RawAddress

异常：

SocketException - 当前 RawSocket 实例已经关闭，或无法获取对端地址时，抛出异常。

prop writeTimeout

public mut prop writeTimeout: ?Duration

功能：获取或设置当前 RawSocket 实例的写超时时间。

类型：?Duration

异常：

SocketException - 当前 RawSocket 实例已经关闭时，抛出异常。
IllegalArgumentException - 当设置的写超时时间为负时，抛出异常。

init(SocketDomain, SocketType, ProtocolType)

public init(domain: SocketDomain, `type`: SocketType, protocol: ProtocolType)

功能：创建特定通信域、类型、协议组合的套接字。

参数：

domain: SocketDomain - 通信域。
type: SocketType - 套接字类型。
protocol: ProtocolType - 协议类型。

异常：

SocketException - 当通信域、类型、协议组合无法创建套接字时，抛出异常。

func accept(?Duration)

public func accept(timeout!: ?Duration = None): RawSocket

功能：接收当前 RawSocket 实例监听时挂起连接队列上的第一个连接请求，返回一个用于通信的 RawSocket。

参数：

timeout!: ?Duration - 等待连接请求的最大时间，默认值 None 表示一直等待。

返回值：

RawSocket - 用于通信的新 RawSocket 实例。

异常：

SocketException - 当前 RawSocket 实例已经关闭，或接收失败时，抛出异常。
SocketTimeoutException - 当等待超时时，抛出异常。

func bind(RawAddress)

public func bind(addr: RawAddress): Unit

功能：将当前 RawSocket 实例与指定的套接字地址进行绑定。

参数：

addr: RawAddress - 套接字地址。

异常：

SocketException - 当前 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 表示一直等待。

异常：

SocketException - 当前 RawSocket 实例已经关闭，或接收失败时，抛出异常。
SocketTimeoutException - 当等待超时时，抛出异常。

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> - 套接字选项值的长度。

异常：

SocketException - 当前 RawSocket 实例已经关闭，或获取套接字选项失败时，抛出异常。

func listen(Int32)

public func listen(backlog: Int32): Unit

功能：监听当前 RawSocket 实例绑定的地址。

参数：

backlog: Int32 - 等待队列增长的最大长度。

异常：

SocketException - 当前 RawSocket 实例已经关闭，或监听失败时，抛出异常。

func receive(Array<Byte>, Int32)

public func receive(buffer: Array<Byte>, flags: Int32): Int64

功能：接收来自连接对端发送的数据。

参数：

buffer: Array<Byte> - 存储接收数据的数组。
flags: Int32 - 指定函数行为的标志。

返回值：

Int64 - 数据长度。

异常：

SocketException - 当前 RawSocket 实例已经关闭，或接收数据失败时，抛出异常。
SocketTimeoutException - 当超过指定的读超时时间时，抛出异常。

func receiveFrom(Array<Byte>, Int32)

public func receiveFrom(buffer: Array<Byte>, flags: Int32): (RawAddress, Int64)

功能：接收来自其它 RawSocket 实例的数据。

参数：

buffer: Array<Byte> - 存储接收数据的数组。
flags: Int32 - 指定函数行为的标志。

返回值：

(RawAddress, Int64) - 数据来源的地址和数据长度。

异常：

SocketException - 当前 RawSocket 实例已经关闭，或接收数据失败时，抛出异常。
SocketTimeoutException - 当超过指定的读超时时间时，抛出异常。

func send(Array<Byte>, Int32)

public func send(buffer: Array<Byte>, flags: Int32): Unit

功能：向连接的对端发送数据。

参数：

buffer: Array<Byte> - 数据。
flags: Int32 - 指定函数行为的标志。

异常：

SocketException - 当前 RawSocket 实例已经关闭，或发送数据失败时，抛出异常。
SocketTimeoutException - 当超过指定的写超时时间时，抛出异常。

func sendTo(RawAddress, Array<Byte>, Int32)

public func sendTo(addr: RawAddress, buffer: Array<Byte>, flags: Int32): Unit

功能：向目标地址发送数据。若 RawSocket 是 DATAGRAM 类型，发送的数据包大小不允许超过 65507 字节。

参数：

addr: RawAddress - 发送数据的目标地址。
buffer: Array<Byte> - 数据。
flags: Int32 - 指定函数行为的标志。

异常：

SocketException - 当前 RawSocket 实例已经关闭，或发送数据失败时，抛出异常。
SocketTimeoutException - 当超过指定的写超时时间时，抛出异常。
SocketException - macOS 平台下当 connect 被调用后调用 sendTo，抛出异常。

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 - 套接字选项值的长度。

异常：

SocketException - 当前 RawSocket 实例已经关闭，或设置套接字选项失败时，抛出异常。

class SocketAddress

public open class SocketAddress <: ToString & Hashable & Equatable<SocketAddress> {
    public init(kind: SocketAddressKind, address: Array<UInt8>, port: UInt16)
    public init(hostAddress: String, port: UInt16)
    public init(unixPath!: String)
}

功能：具有特定类型、地址和端口的套接字地址。

prop address

public prop address: Array<UInt8>

功能：获取地址。

类型：Array<UInt8>

prop defaultMask

public prop defaultMask: Option<IPMask>

功能：获取默认掩码。

类型：Option<IPMask>

prop hostAddress

public prop hostAddress: String

功能：获取主机地址。

类型：String

prop hostName

public prop hostName: Option<String>

功能：获取名称，不存在时返回 None。

类型：Option<String>

prop kind

public prop kind: SocketAddressKind

功能：获取地址类型。

类型：SocketAddressKind

prop port

public prop port: UInt16

功能：获取端口。

类型：UInt16

prop zone

public prop zone: Option<String>

功能：获取 IPv6 地址族。

类型：Option<String>

init(SocketAddressKind, Array<UInt8>, UInt16)

public init(kind: SocketAddressKind, address: Array<UInt8>, port: UInt16)

功能：根据传入的套接字地址类型，IP 地址和端口号创建 SocketAddress 实例。

参数：

kind: SocketAddressKind - 套接字地址类型。
address: Array<UInt8> - IP 地址。
port: UInt16 - 端口号。

异常：

SocketException - 当地址长度不符合地址类型要求时，抛出异常。

init(String)

public init(unixPath!: String)

功能：根据传入的文件地址创建 SocketAddress 实例。

参数：

unixPath!: String - 连接的文件地址。

异常：

SocketException - 当地址无法解析成 IP 格式，或不符合地址类型要求，抛出异常。

init(String, UInt16)

public init(hostAddress: String, port: UInt16)

功能：根据传入的 IP 地址和端口号创建 SocketAddress 实例。

参数：

hostAddress: String - IP 地址。
port: UInt16 - 端口号。

异常：

SocketException - 当地址无法解析成 IP 格式，或不符合地址类型要求时，抛出异常。

static func resolve(String, UInt64)

public static func resolve(domain: String, port: UInt16): ?SocketAddress

功能：解析域和端口，并构造 SocketAddress 的实例。

当传入 IP 地址时，不包含 DNS 能力。当传入域名地址时，通过 getaddrinfo 解析得到 IP 地址，其中优先解析 IPv4 地址，并仅返回获取到的首个 IP 地址。

参数：

domain: String - 域。
port: UInt16 - 端口。

返回值：

?SocketAddress - 如果解析域和端口成功，返回 SocketAddress 实例，否则返回 None。

func hashCode()

public open func hashCode(): Int64

功能：获取 hashcode 值。

返回值：

Int64 - hashcode 值。

func kapString()

public func kapString(): String

功能：获取 IP 协议、地址和端口字符串。

返回值：

String - IP 协议、地址和端口字符串。

异常：

SocketException - 当地址的大小与 IPv4 或 IPv6 不匹配时，抛出异常。

func mask(IPMask)

public func mask(mask: IPMask): SocketAddressWithMask

功能：使用掩码处理地址。

参数：

mask: IPMask - 掩码。

返回值：

SocketAddressWithMask - 被处理后的地址。

异常：

SocketException - 当掩码长度不符合地址长度时，抛出异常。
IllegalArgumentException - 当缓存空间不符合 IPv4/IPv6 要求时，抛出异常。

func setHostName(String)

public func setHostName(name: String): Unit

功能：设置主机名。

func toString()

public open func toString(): String

功能：获取地址对象字符串。

格式为："127.0.0.1:2048"， "[::]:2048"，"[212c:3742::ffff:5863:6f00]:2048" 等。

异常：

SocketException - 当地址不合法时，抛出异常。

operator func !=(SocketAddress)

public operator func != (that: SocketAddress): Bool

功能：判断两个 SocketAddress 是否不相等。

参数：

that: SocketAddress - 传入的 SocketAddress。

返回值：

Bool - 如果两个 SocketAddress 不相等，则返回 true；否则，返回 false。

operator func ==(SocketAddress)

public operator func ==(that: SocketAddress): Bool

功能：判断两个 SocketAddress 是否相等。

参数：

that: SocketAddress - 传入的 SocketAddress。

返回值：

Bool - 如果两个 SocketAddress 相等，则返回 true；否则，返回 false。

class SocketAddressWithMask

public class SocketAddressWithMask <: SocketAddress {
    public init(kind: SocketAddressKind, address: Array<UInt8>, port: UInt16, mask: IPMask)
    public init(hostAddress: String, port: UInt16, mask: IPMask)
    public init(socketAddr: SocketAddress, mask: IPMask)
}

功能：提供带有掩码的 SocketAddress。

prop ipMask

public mut prop ipMask: IPMask

功能：设置/获取 IP 掩码。

类型：IPMask

init(SocketAddress, IPMask)

public init(socketAddr: SocketAddress, mask: IPMask)

功能：创建 SocketAddressWithMask 实例。

参数：

socketAddr: SocketAddress - 地址。
mask: IPMask - 掩码。

异常：

SocketException - 当参数 socketAddr 不合法时，抛出异常。

init(SocketAddressKind, Array<UInt8>, UInt16, IPMask)

public init(kind: SocketAddressKind, address: Array<UInt8>, port: UInt16, mask: IPMask)

功能：创建 SocketAddressWithMask 实例。

参数：

kind: SocketAddressKind - SocketAddress 类型。
address: Array<UInt8> - 符合 kind 所指定类型的地址。
port: UInt16 - 端口。
mask: IPMask - 掩码。

异常：

SocketException - 当参数 address 传入的地址不符合参数 kind 地址类型的要求时，抛出异常。

init(String, UInt16, IPMask)

public init(hostAddress: String, port: UInt16, mask: IPMask)

功能：创建 SocketAddressWithMask 实例。

参数：

hostAddress: String - IP 地址字符串。
port: UInt16 - 端口。
mask: IPMask - 掩码。

异常：

SocketException - 当参数 hostAddress 无法解析成合法的 IP 地址时，抛出异常。

func clone()

public func clone(): SocketAddressWithMask

功能：使用绑定的掩码处理地址，复制一个 SocketAddressWithMask 实例。

异常：

SocketException - 当掩码长度不符合地址长度时，抛出异常。
IllegalArgumentException - 当缓存长度不足时，抛出异常。

func hashCode()

public override func hashCode(): Int64

功能：获取 SocketAddressWithMask 的 hashcode 值。

返回值：

Int64 - hashcode 值。

func toString()

public override func toString(): String

功能：将 SocketAddressWithMask 转换为字符串。

返回值：

String - 转换后的字符串。

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

异常：

SocketException - 当在 bind 后调用时，抛出异常。

prop bindToDevice

public mut prop bindToDevice: ?String

功能：设置和读取绑定网卡。

类型：?String

prop localAddress

public override prop localAddress: SocketAddress

功能：读取 Socket 将要或已经被绑定的本地地址。

类型：SocketAddress

异常：

SocketException - 当 Socket 已经被关闭时，抛出异常。

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能：设置和读取 SO_RCVBUF 属性。

类型：Int64

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

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

异常：

SocketException - Windows 上不支持此类型，抛出异常。

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性。

类型：Int64

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

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

功能：监听或接受客户端连接。阻塞等待。

返回值：

TcpSocket - 客户端套接字。

异常：

SocketException - 当因系统原因监听失败时，抛出异常。

func accept(?Duration)

public override func accept(timeout!: ?Duration): TcpSocket

功能：监听或接受客户端连接。

参数：

timeout!: ?Duration - 超时时间。

返回值：

TcpSocket - 客户端套接字。

异常：

SocketTimeoutException - 当连接超时，抛出异常。
SocketException - 当因系统原因监听失败时，抛出异常。
IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

func bind()

public override func bind(): Unit

功能：绑定本地端口失败后需要 close 套接字，不支持多次重试。

异常：

SocketException - 当因系统原因绑定失败时，抛出异常。

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

功能：获取指定的套接字参数。

参数：

level: Int32 - 层级，例如 SOL_SOCKET。
option: Int32 - 参数，例如 SO_KEEPALIVE。
value: CPointer<Unit> - 参数值。
valueLength: CPointer<UIntNative> - 参数值长度。

异常：

SocketException - 当 getsockopt 返回失败时，抛出异常。

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。

异常：

SocketException - 当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时，抛出异常。

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：获取指定的套接字参数。

参数：

level: Int32 - 层级，例如 SOL_SOCKET。
option: Int32 - 参数，例如 SO_KEEPALIVE。

返回值：

IntNative - 获取的套接字参数值。

异常：

SocketException - 当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时，抛出异常。

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 - 参数值长度。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

func toString()

public override func toString(): String

功能：返回当前 TcpServerSocket 的状态信息。

返回值：

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

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

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

功能：设置和读取读操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None。

类型：?Duration

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能：设置和读取 SO_RCVBUF 属性，提供一种方式指定收包缓存大小。选项的生效情况取决于系统。

类型：Int64

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

prop remoteAddress

public override prop remoteAddress: SocketAddress

功能：读取 Socket 已经或将要连接的远端地址。

类型：SocketAddress

异常：

SocketException - 当 Socket 已经被关闭时，抛出异常。

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性，提供一种方式指定发包缓存大小。选项的生效情况取决于系统。

类型：Int64

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

prop writeTimeout

public override mut prop writeTimeout: ?Duration

功能：设置和读取写操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None。

类型：?Duration

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

init(SocketAddress)

public init(address: SocketAddress)

功能：创建一个未连接的套接字。

参数：

address: SocketAddress - 即将要连接的地址。

异常：

SocketException - 当 address 参数不合法时，抛出异常。
SocketException - Windows 平台下地址为全零地址时，抛出异常。

init(SocketAddress, ?SocketAddress)

public init(address: SocketAddress, localAddress!: ?SocketAddress)

功能：创建一个未连接的套接字，并且绑定到指定本地地址，本地地址为 None 时，将随机选定地址去绑定。

此接口当 localAddress 不为 None 时，将默认设置 SO_REUSEADDR 为 true，否则可能导致 "address already in use" 的错误。如果需要变更此配置，可以通过调用 setSocketOptionBool(SocketOptions.SOL_SOCKET, SocketOptions.SO_REUSEADDR, false)。另外，本地地址和远端地址需要均为 IPv4。

参数：

address: SocketAddress - 即将要连接的地址。
localAddress!: ?SocketAddress - 绑定的本地地址。

异常：

SocketException - 当 address 参数不合法时，抛出异常。
SocketException - Windows 平台下地址为全零地址时，抛出异常。

init(String, UInt16)

public init(address: String, port: UInt16)

功能：创建一个未连接的套接字。

参数：

address: String - 即将要连接的地址。
port: UInt16 - 即将要连接的端口。

异常：

SocketException - 当 address 参数不合法时，抛出异常。
SocketException - 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

功能：读取指定的套接字参数。

参数：

level: Int32 - 层级，例如 SOL_SOCKET。
option: Int32 - 参数，例如 SO_KEEPALIVE。
value: CPointer<Unit> - 参数值。
valueLength: CPointer<UIntNative> - 参数值长度。

异常：

SocketException - 当 getsockopt 返回失败时，抛出异常。

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 - 读取到的参数值。

异常：

SocketException - 当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时，抛出异常。

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：读取指定的套接字参数。

参数：

level: Int32 - 层级，例如 SOL_SOCKET。
option: Int32 - 参数，例如 SO_KEEPALIVE。

返回值：

IntNative - 参数值。

异常：

SocketException - 当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时，抛出异常。

func hashCode()

public override func hashCode(): Int64

功能：获取当前 TcpSocket 实例的哈希值。

返回值：

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。

说明：

由于系统底层接口差异，如果连接被对端关闭，read 和 write 接口的行为也有相应的差异。

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 - 参数值长度。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

func toString()

public override func toString(): String

功能：返回当前 TcpSocket 的状态信息。

返回值：

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 实例是否不等。

参数：

other: TcpSocket - 参与比较的 TcpSocket 实例。

返回值：

Bool - 如果两个 TcpSocket 实例不等，则返回 true；否则，返回 false。

operator func ==(TcpSocket)

public override operator func ==(other: TcpSocket): Bool

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

参数：

other: TcpSocket - 参与比较的 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

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

prop receiveTimeout

public override mut prop receiveTimeout: ?Duration

功能：设置和读取 receive/receiveFrom 操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None。

类型：?Duration

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

prop remoteAddress

public override prop remoteAddress: ?SocketAddress

功能：读取 Socket 已经连接的远端地址，当 Socket 未连接时返回 None。

类型：?SocketAddress

异常：

SocketException - 当 Socket 已经被关闭时，抛出异常。

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

异常：

SocketException - Windows 上不支持此类型，抛出异常。

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性。

类型：Int64

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

prop sendTimeout

public override mut prop sendTimeout: ?Duration

功能：设置和读取 send/sendTo 操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None。

类型：?Duration

init(SocketAddress)

public init(bindAt!: SocketAddress)

功能：创建一个未绑定的 UDPSocket 实例。

参数：

bindAt!: SocketAddress - 绑定地址及端口。

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

init(UInt64)

public init(bindAt!: UInt16)

功能：创建一个未绑定的 UDPSocket 实例。

参数：

bindAt!: UInt16 - 绑定端口。

func bind()

public func bind(): Unit

功能：绑定本地端口失败后需要 close 套接字，不支持多次重试。

异常：

SocketException - 当因系统原因绑定失败时，抛出异常。

func close()

public override func close(): Unit

功能：关闭套接字，所有操作除了 close/isClosed 之外，均不允许再调用。接口允许多次调用。

func connect(SocketAddress)

public func connect(remote: SocketAddress): Unit

功能：连接特定远端地址，可通过 disconnect 撤销配置。

仅接受该远端地址的报文。必须在调用 bind 后执行。此操作执行后，端口将开始接收 ICMP 报文，若收到异常报文后，可能导致 send/sendTo 执行失败。

参数：

remote: SocketAddress - 远端地址。

异常：

IllegalArgumentException - 当远端地址不合法时，抛出异常，
SocketException - 当端口未绑定时，抛出异常，
SocketException - 当连接因系统原因无法建立时，抛出异常，
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

功能：获取指定的套接字参数。

参数：

level: Int32 - 层级，例如 SOL_SOCKET。
option: Int32 - 参数，例如 SO_KEEPALIVE。
value: CPointer<Unit> - 参数值。
valueLength: CPointer<UIntNative> - 参数值长度。

异常：

SocketException - 当 getsockopt 返回失败时，抛出异常。

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。

异常：

SocketException - 当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时，抛出异常。

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：获取指定的套接字参数。

参数：

level: Int32 - 层级，例如 SOL_SOCKET
option: Int32 - 参数，例如 SO_KEEPALIVE

返回值：

IntNative - 指定的套接字参数值

异常：

SocketException - 当 getsockopt 返回失败时或参数大小超过 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 的大小。

异常：

SocketException - 当本机缓存过小无法读取报文时，抛出异常。
SocketTimeoutException - 当读取超时时，抛出异常。

func send(Array<Byte>)

public func send(payload: Array<Byte>): Unit

功能：发送报文到 connect 连接到的地址。

参数：

payload: Array<Byte> - 发送报文内容。

异常：

SocketException - 当 payload 的大小超出系统限制，抛出异常。
SocketException - 系统发送失败，例如：当 connect 被调用，并且收到异常 ICMP 报文时，抛出异常。

func sendTo(SocketAddress, Array<Byte>)

public override func sendTo(recipient: SocketAddress, payload: Array<Byte>): Unit

功能：发送报文。当没有足够的缓存地址时可能会被阻塞。

参数：

recipient: SocketAddress - 发送的对端地址。
payload: Array<Byte> - 发送报文内容。

异常：

SocketException - 当 payload 的大小超出系统限制时，抛出异常。
SocketException - 系统发送失败，例如：当 connect 被调用，并且收到异常 ICMP 报文时，抛出异常。
SocketException - Windows 平台下远端地址为全零地址时，抛出异常。
SocketException - 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 - 参数值长度。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

func toString()

public override func toString(): String

功能：返回当前 UdpSocket 的状态信息。

返回值：

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

异常：

SocketException - 当 socket 已经关闭时，抛出异常。

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能：设置和读取 SO_RCVBUF 属性，提供一种方式指定发包缓存大小。选项的生效情况取决于系统。

类型：Int64

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

prop receiveTimeout

public override mut prop receiveTimeout: ?Duration

功能：设置和读取 receive/receiveFrom 操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None。

类型：?Duration

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

prop remoteAddress

public override prop remoteAddress: ?SocketAddress

功能：读取 Socket 已经连接的远端地址，当 Socket 未连接时返回 None。

类型：?SocketAddress

异常：

SocketException - 当 Socket 已经被关闭时，抛出异常。

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性，提供一种方式指定发包缓存大小。选项的生效情况取决于系统。

类型：Int64

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

prop sendTimeout

public override mut prop sendTimeout: ?Duration

功能：设置和读取 send/sendTo 操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None。

类型：?Duration

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

init(SocketAddress)

public init(bindAt!: SocketAddress)

功能：创建一个未连接的 UnixDatagramSocket 实例。

此文件类型可通过 isSock() 判断是否存在，可通过 unlink() 接口删除。

参数：

bindAt!: SocketAddress - 连接的套接字地址。地址应当不存在，在 bind 时会创建。

异常：

SocketException - 当路径为空或已存在时，抛出异常。

init(String)

public init(bindAt!: String)

功能：创建一个未连接的 UnixDatagramSocket 实例。

此文件类型可通过 isSock() 判断是否存在，可通过 unlink() 接口删除。

参数：

bindAt!: String - 连接的文件地址。文件地址应当不存在，在 bind 时会创建。

异常：

SocketException - 当路径为空或已存在时，抛出异常。

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 执行失败。

参数：

remote: SocketAddress - 远端套接字地址。

异常：

SocketException - 当地址未绑定时，抛出异常。

func connect(String)

public func connect(remotePath: String): Unit

功能：连接特定远端地址，可通过 disconnect 撤销配置。

仅接受该远端地址的报文。必须在 bind 后调用。此操作执行后，端口将开始接收 ICMP 报文，若收到异常报文后，可能导致 send/sendTo 执行失败。

参数：

remotePath: String - 远端文件地址。

异常：

SocketException - 当地址未绑定时，抛出异常。

func disconnect()

public func disconnect(): Unit

功能：停止连接。取消仅收取特定对端报文。可在 connect 前调用，可多次调用。

异常：

SocketException - 当未绑定时，抛出异常。

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> - 参数值长度。

异常：

SocketException - 当 getsockopt 返回失败时，抛出异常。

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：获取指定的套接字参数。

参数：

level: Int32 - 层级，例如 SOL_SOCKET。
option: Int32 - 参数，例如 SO_KEEPALIVE。

返回值：

IntNative - 返回指定的套接字参数值。

异常：

SocketException - 当 getsockopt 返回失败时或参数大小超过 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 的大小。

异常：

SocketException - 本机缓存过小无法读取报文时，抛出异常。
SocketTimeoutException - 当读取超时时，抛出异常。

func send(Array<Byte>)

public func send(payload: Array<Byte>): Unit

功能：发送报文到 connect 连接到的地址。

参数：

payload: Array<Byte> - 发送报文内容。

异常：

SocketException - 当 payload 的大小超出系统限制时，抛出异常。
SocketException - 系统发送失败，例如：当 connect 被调用，并且收到异常 ICMP 报文时，发送将失败。

func sendTo(SocketAddress, Array<Byte>)

public override func sendTo(recipient: SocketAddress, payload: Array<Byte>): Unit

功能：发送报文。当没有足够的缓存地址时可能会被阻塞。

参数：

recipient: SocketAddress - 发送的对端地址。
payload: Array<Byte> - 发送报文内容。

异常：

SocketException - 当 payload 的大小超出系统限制时，抛出异常。
SocketException - 系统发送失败，例如：当 connect 被调用，并且收到异常 ICMP 报文时，发送将失败。
SocketException - 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 - 参数值长度。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时抛出异常

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。

异常：

SocketException - 当 getsockopt 返回失败时，抛出异常。

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

异常：

SocketException - 当在 bind 后调用，将抛出异常。

prop localAddress

public override prop localAddress: SocketAddress

功能：读取 Socket 将要或已经被绑定的本地地址。

类型：SocketAddress

异常：

SocketException - 当 Socket 已经被关闭时，抛出异常。

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能：设置和读取 SO_RCVBUF 属性。

类型：Int64

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性。

类型：Int64

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

init(SocketAddress)

public init(bindAt!: SocketAddress)

功能：创建一个未连接的 UnixServerSocket 实例。

参数：

bindAt!: SocketAddress - 连接的套接字地址

init(String)

public init(bindAt!: String)

功能：创建一个未连接的 UnixServerSocket 实例。

此文件类型可通过 isSock 判断是否存在，可通过 unlink() 接口删除。

参数：

bindAt!: String - 连接的文件地址

func accept()

public override func accept(): UnixSocket

功能：等待接受一个客户端的连接，或从队列中读取连接。

返回值：

UnixSocket - 连接的客户端套接字。

func accept(?Duration)

public override func accept(timeout!: ?Duration): UnixSocket

功能：等待接受一个客户端的连接，或从队列中读取连接。

参数：

timeout!: ?Duration - 超时时间。

返回值：

UnixSocket - 连接的客户端套接字

异常：

SocketTimeoutException - 当连接超时时，抛出异常。
IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

func bind()

public override func bind(): Unit

功能：绑定一个 Unix domain 套接字，并创建监听队列。

此接口自动在本地地址中创建一个套接字文件，如该文件已存在则会绑定失败。此文件类型可通过 isSock 接口判断是否存在，可通过 unlink() 接口删除，失败后需要 close 套接字，不支持多次重试。

异常：

SocketException - 当因系统原因绑定失败时，抛出异常。

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

功能：获取指定的套接字参数。

参数：

level: Int32 - 层级，例如 SOL_SOCKET。
option: Int32 - 参数，例如 SO_KEEPALIVE。
value: CPointer<Unit> - 参数值。
valueLength: CPointer<UIntNative> - 参数值长度。

异常：

SocketException - 当 getsockopt 返回失败时，抛出异常。

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。

异常：

SocketException - 当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时，抛出异常。

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：获取返回值为整型的套接字参数。

参数：

level: Int32 - 层级，例如 SOL_SOCKET。
option: Int32 - 参数，例如 SO_KEEPALIVE。

返回值：

IntNative - 指定的套接字参数值。

异常：

SocketException - 当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时，抛出异常。

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 - 参数值长度。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

func toString()

public override func toString(): String

功能：返回当前 UnixServerSocket 的状态信息。

返回值：

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

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

prop receiveBufferSize

public mut prop receiveBufferSize: Int64

功能：设置和读取 SO_RCVBUF 属性。

类型：Int64

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

prop remoteAddress

public override prop remoteAddress: SocketAddress

功能：读取 Socket 已经或将要连接的远端地址。

类型：SocketAddress

异常：

SocketException - 当 Socket 已经被关闭时，抛出异常。

prop sendBufferSize

public mut prop sendBufferSize: Int64

功能：设置和读取 SO_SNDBUF 属性。

类型：Int64

异常：

IllegalArgumentException - 当 size 小于等于 0 时，抛出异常。
SocketException - 当 Socket 已关闭时，抛出异常。

prop writeTimeout

public override mut prop writeTimeout: ?Duration

功能：设置和读取写操作超时时间。

如果设置的时间过小将会设置为最小时钟周期值；过大时将设置为最大超时时间（2⁶³-1 纳秒）；默认值为 None。

类型：?Duration

异常：

IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

init(SocketAddress)

public init(address: SocketAddress)

功能：创建一个未连接的 UnixSocket 实例。

参数：

address: SocketAddress - 连接的套接字地址。

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 不同，队列已满时，调用立即返回错误，而非重试阻塞等待。

异常：

IllegalArgumentException - 当远端地址不合法时，抛出异常。
SocketException - 当连接因系统原因无法建立时。抛出异常。
SocketTimeoutException - 当连接超时时。抛出异常。
IllegalArgumentException - 当超时时间小于 0 时，抛出异常。

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> - 参数值长度。

异常：

SocketException - 当 getsockopt 返回失败时，抛出异常。

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。

异常：

SocketException - 当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时，抛出异常。

func getSocketOptionIntNative(Int32, Int32)

public func getSocketOptionIntNative(
    level: Int32,
    option: Int32
): IntNative

功能：获取指定的套接字参数。

参数：

level: Int32 - 层级，例如 SOL_SOCKET。
option: Int32 - 参数，例如 SO_KEEPALIVE。

返回值：

IntNative - 指定的套接字参数值。

异常：

SocketException - 当 getsockopt 返回失败时或参数大小超过 IntNative 的阈值时，抛出异常。

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 - 参数值长度。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

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 - 参数值。

异常：

SocketException - 当 setsockopt 返回失败时，抛出异常。

func toString()

public override func toString(): String

功能：返回当前 UnixSocket 的状态信息。

返回值：

String - 包含当前 UnixSocket 状态信息的字符串。

func write(Array<Byte>)

public override func write(buffer: Array<Byte>): Unit

功能：读取写入。超时情况按 writeTimeout 决定，详见 writeTimeout。

参数：

buffer: Array<Byte> - 写入的数据存储变量

异常：

SocketException - 当 buffer 大小为 0 时抛出异常，当因系统原因写入失败时，抛出异常。

枚举

enum SocketAddressKind

public enum SocketAddressKind <: ToString & Equatable<SocketAddressKind> {
    | IPv4
    | IPv6
    | Unix
}

功能：互联网通信协议种类。

IPv4

IPv4

功能：代表 IPv4 协议。

IPv6

IPv6

功能：代表 IPv6 协议。

Unix

Unix

功能：代表 Unix 协议。

func toString()

public func toString(): String

功能：将枚举值转换为字符串。

返回值：

String - 转换后的字符串。

operator func !=(SocketAddressKind)

public operator func !=(that: SocketAddressKind): Bool

功能：判断两个 SocketAddressKind 是否不相等。

参数：

that: SocketAddressKind - 传入的 SocketAddressKind。

返回值：

Bool - 如果不相等，则返回 true；否则，返回 false。

operator func ==(SocketAddressKind)

public operator func ==(that: SocketAddressKind): Bool

功能：判断两个 SocketAddressKind 是否相等。

参数：

that: SocketAddressKind - 传入的 SocketAddressKind。

返回值：

Bool - 如果相等，则返回 true；否则，返回 false。

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 是否不相等。

参数：

that: SocketNet - 传入的 SocketNet。

返回值：

Bool - 如果不相等，则返回 true；否则，返回 false。

operator func ==(SocketNet)

public operator func ==(that: SocketNet): Bool

功能：判断两个 SocketNet 是否相等。

参数：

that: SocketNet - 的 SocketNet。

返回值：

Bool - 如果相等，则返回 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 实例的哈希值。

返回值：

Int64 - 当前 ProtocolType 实例的哈希值。

func toString()

public func toString(): String

功能：返回当前 ProtocolType 实例的字符串表示。

返回值：

String - 当前 ProtocolType 实例的字符串表示。

operator func !=(ProtocolType)

public operator func !=(r: ProtocolType): Bool

功能：判断两个 ProtocolType 实例是否不等。

参数：

r: ProtocolType - 参与比较的 ProtocolType 实例。

返回值：

Bool - 当二者代表的 Int32 值不等时，返回 true；否则，返回 false。

operator func ==(ProtocolType)

public operator func ==(r: ProtocolType): Bool

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

参数：

r: ProtocolType - 参与比较的 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

static let NETLINK

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 实例的哈希值。

返回值：

Int64 - 当前 SocketDomain 实例的哈希值。

func toString()

public func toString(): String

功能：返回当前 SocketDomain 实例的字符串表示。

返回值：

String - 当前 SocketDomain 实例的字符串表示。

operator func !=(SocketDomain)

public operator func !=(r: SocketDomain): Bool

功能：比较两个 SocketDomain 实例是否不等。

参数：

r: SocketDomain - 参与比较的 SocketDomain 实例。

返回值：

Bool - 当二者代表的 Int32 值不等时，返回 true；否则，返回 false。

operator func ==(SocketDomain)

public operator func ==(r: SocketDomain): Bool

功能：比较两个 SocketDomain 实例是否相等。

参数：

r: SocketDomain - 参与比较的 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 个。

异常：

IllegalArgumentException - 当配置为空闲状态或设置间隔小于 0 时，抛出异常。

func toString()

public override func toString(): String

功能：将 TCP KeepAlive 属性配置转换为字符串。

返回值：

String - 转换后的字符串。

operator func !=(SocketKeepAliveConfig)

public override operator func !=(other: SocketKeepAliveConfig): Bool

功能：判断两个 SocketKeepAliveConfig 实例是否不等。

参数：

other: SocketKeepAliveConfig - 参与比较的 SocketKeepAliveConfig 实例。

返回值：

Bool - 如果不等，则返回 true；否则，返回 false。

operator func ==(SocketKeepAliveConfig)

public override operator func ==(other: SocketKeepAliveConfig): Bool

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

参数：

other: SocketKeepAliveConfig - 参与比较的 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 实例的哈希值。

返回值：

Int64 - 当前 SocketType 实例的哈希值。

func toString()

public func toString(): String

功能：返回当前 SocketType 实例的字符串表示。

返回值：

String - 当前 SocketType 实例的字符串表示。

operator func !=(SocketType)

public operator func !=(r: SocketType): Bool

功能：判断两个 SocketType 实例是否不等。

参数：

r: SocketType - 参与比较的 SocketType 实例。

返回值：

Bool - 当二者代表的 Int32 值不等时，返回 true；否则，返回 false。

operator func ==(SocketType)

public operator func ==(r: SocketType): Bool

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

参数：

r: SocketType - 参与比较的 SocketType 实例。

返回值：

Bool - 当二者代表的 Int32 值相等时，返回 true；否则，返回 false。

异常类

class SocketException

public class SocketException <: Exception {
    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.socket.*
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.socket.*

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)
}

运行结果:

TCP 使用示例

import std.socket.*
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, item: 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(Array<Byte>([1, 2, 3]))
    }

    return 0
}

运行结果:

Server read 3 bytes: [1, 2, 3, 0, 0, 0, 0, 0, 0, 0]

UDP 使用示例

import std.socket.*
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, item: 0)

        let (clientAddr, count) = serverSocket.receiveFrom(buf)
        let sender = clientAddr.hostAddress

        // 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(
            SocketAddress("127.0.0.1", SERVER_PORT),
            Array<Byte>([1, 2, 3])
        )
    }

    return 0
}

运行结果:

Server receive 3 bytes: [1, 2, 3] from 127.0.0.1

UNIX 使用示例

import std.socket.*
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, item: 0)
        socket.read(buf)

        println(String.fromUtf8(buf)) // hello
    }

    return 0
}

运行结果:

hello

UnixDatagram 使用示例

import std.socket.*
import std.time.*
import std.sync.*
import std.fs.*
import std.os.*
import std.random.*

func createTempFile(): String {
    let tempDir: Path = tempDir().info.path

    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, item: 0)

        let (clientAddr, read) = serverSocket.receiveFrom(buf)

        if (read == 3 && buf == Array<Byte>([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(Array<Byte>([1, 2, 3]))
        sleep(Duration.second)
    }

    return 0
}

运行结果:

server received
client address correct

std.sort 包

功能介绍

sort 包提供数组类型的排序函数。

根据排序方式，本包提供了稳定排序和不稳定排序两套实现。稳定排序是指，相等元素的前后顺序在排序前后保持不变。反之，不稳定排序是指，不保证相等元素的前后顺序在排序前后保持一致。

本包提供了一组带泛型的排序函数，可用来对元素为 T 类型的数组进行排序。排序必然要求元素是可以比较的，因此，这组函数进一步分为两类：1、要求 T 实现 Comparable<T> 接口，2、将 T 相关的比较函数作为参数传入函数。

此外，本包提供辅助接口 SortByExtension 和 SortExtension，可用来为其他类型实现与排序相关的函数。

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，排序后 t1 在 t2 后；如果 comparator 的返回值为 Ordering.LT，排序后 t1 在 t2 前；如果 comparator 的返回值为 Ordering.EQ，排序后 t1 与 t2 的位置较排序前保持不变。

参数：

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

功能：对数组进行不稳定排序。

参数：

data: Array<T> - 需要排序的数组。
comparator: (T, T) ->Ordering - 用户传入的比较函数。

接口

interface SortByExtension

public interface SortByExtension

功能: 此接口作为排序相关的辅助接口，内部为空。

extend<T> Array<T> <: SortByExtension

extend<T> Array<T> <: SortByExtension

功能: 此扩展用于实现 Array 的 sortBy 函数。

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，排序后 t1 在 t2 后；如果 comparator 的返回值为 Ordering.LT，排序后 t1 在 t2 前；如果 comparator 的返回值为 Ordering.EQ，且为稳定排序那么 t1 与 t2 的位置较排序前保持不变；如果 comparator 的返回值为 Ordering.EQ，且为不稳定排序，那么 t1，t2 顺序不确定

interface SortExtension

public interface SortExtension

功能: 此接口作为排序相关的辅助接口，内部为空。

extend<T> Array<T> <: SortExtension where T <: Comparable<T>

extend<T> Array<T> <: SortExtension where T <: Comparable<T>

功能: 此扩展用于实现 Array 的 sort/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 关键字创建一个仓颉线程：

import std.sync.sleep
import std.time.Duration

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 修饰的代码块之前（包括在代码块中使用 break、continue、return、throw 等控制转移表达式），会自动释放该 ReentrantMutex 实例的锁。

示例:

在每个 for 循环的线程进入 synchronized 代码块前，会自动获取 mtx 实例对应的锁，在退出代码块前，会释放 mtx 实例对应的锁。

import std.sync.{ReentrantMutex, sleep}
import std.time.Duration

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。

函数

函数名	功能
sleep(Duration)	休眠当前线程。

接口

接口名	功能
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

函数

func sleep(Duration)

public func sleep(dur: Duration): Unit

功能：休眠当前线程。

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

参数：

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

接口

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 次该函数来完全解锁。一旦互斥体被完全解锁，如果有其他线程阻塞在此锁上，则唤醒其中一个线程。

异常：

IllegalSynchronizationStateException - 如果当前线程没有持有该互斥体，抛出异常。

类

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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

参数：

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 - 写入原子类型的值。

返回值：

UInt16 - 写入前的值。

func swap(UInt16, MemoryOrder)

public func swap(val: UInt16, memoryOrder!: MemoryOrder): UInt16

功能：交换操作，采用参数 memoryOrder 指定的内存排序方式，将参数 val 指定的值写入原子类型，并返回写入前的值。

参数：

val: UInt16 - 写入原子类型的值。
memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值：

UInt16 - 写入前的值。

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

参数：

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

参数：

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

参数：

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

参数：

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 - 写入原子类型的值。

返回值：

UInt32 - 写入前的值。

func swap(UInt32, MemoryOrder)

public func swap(val: UInt32, memoryOrder!: MemoryOrder): UInt32

功能：交换操作，采用参数 memoryOrder 指定的内存排序方式，将参数 val 指定的值写入原子类型，并返回写入前的值。

参数：

val: UInt32 - 写入原子类型的值。
memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值：

UInt32 - 写入前的值。

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

参数：

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

参数：

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

参数：

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

参数：

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 - 写入原子类型的值。

返回值：

UInt64 - 写入前的值。

func swap(UInt64, MemoryOrder)

public func swap(val: UInt64, memoryOrder!: MemoryOrder): UInt64

功能：交换操作，采用参数 memoryOrder 指定的内存排序方式，将参数 val 指定的值写入原子类型，并返回写入前的值。

参数：

val: UInt64 - 写入原子类型的值。
memoryOrder!: MemoryOrder - 当前操作的内存排序方式。

返回值：

UInt64 - 写入前的值。

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

参数：

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

参数：

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

参数：

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

参数：

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 - 表示需要协调的线程数。

异常：

IllegalArgumentException - 参数 count 为负数。

func wait(Duration)

public func wait(timeout!: Duration = Duration.Max): Unit

功能：线程进入 Barrier 等待点。

如果 Barrier 对象所有调用 wait 的次数（即进入等待点的线程数）等于初始值，那么唤醒所有等待的线程；如果调用 wait 方法次数仍小于初始值，那么当前线程进入阻塞状态直到被唤醒或者等待时间超过 timeout；如果调用 wait 次数已大于初始值，那么线程继续执行。

参数：

timeout!: Duration - 阻塞时等待的最大时长，其默认值为 Duration.Max。

class Monitor

public class Monitor <: ReentrantMutex

功能：提供使线程阻塞并等待来自另一个线程的信号以恢复执行的功能。

这是一种利用共享变量进行线程同步的机制，当一些线程因等待共享变量的某个条件成立而挂起时，另一些线程改变共享的变量，使条件成立，然后执行唤醒操作。这使得挂起的线程被唤醒后可以继续执行。

init()

public init()

功能：通过默认构造函数创建 Monitor。

func notify()

public func notify(): Unit

功能：唤醒一个等待在该 Montior 上的线程。

异常：

IllegalSynchronizationStateException - 如果当前线程没有持有该互斥体，抛出异常。

func notifyAll()

public func notifyAll(): Unit

功能：唤醒所有等待在该 Montior 上的线程。

异常：

IllegalSynchronizationStateException - 如果当前线程没有持有该互斥体，抛出异常。

func wait(Duration)

public func wait(timeout!: Duration = Duration.Max): Bool

功能：当前线程挂起，直到对应的 notify 函数被调用，或者挂起时间超过 timeout。

参数：

timeout!: Duration - 挂起时间，其默认值为 Duration.Max。

返回值：

Bool - 如果 Monitor 被其它线程唤醒，返回 true；如果超时，则返回 false。

异常：

IllegalArgumentException - 如果 timeout 小于等于 Duration.Zero，抛出异常。
IllegalSynchronizationStateException - 如果当前线程没有持有该互斥体，抛出异常。

class MultiConditionMonitor

public class MultiConditionMonitor <: ReentrantMutex

功能：提供对同一个互斥锁绑定多个条件变量的功能。

注意：

该类应仅当在 Monitor 类不足以实现高级并发算法时被使用。

初始化时，MultiConditionMonitor 没有与之相关的条件变量。

每次调用 newCondition 将创建一个新的等待队列并与当前对象关联，并返回ConditionID类型实例作为唯一标识符。

init()

public init()

功能：通过默认构造函数创建 MultiConditionMonitor。

func newCondition()

public func newCondition(): ConditionID

功能：创建一个与该 Monitor 相关的 ConditionID，可能被用来实现 “单互斥体多等待队列” 的并发原语。

返回值：

ConditionID - 新的 ConditionID。

异常：

IllegalSynchronizationStateException - 如果当前线程没有持有该互斥体，抛出异常。

func notify(ConditionID)

public func notify(condID: ConditionID): Unit

功能：唤醒等待在所指定的条件变量的线程（如果有）。

参数：

condID: ConditionID - 条件变量。

异常：

IllegalSynchronizationStateException - 如果当前线程没有持有该互斥体，或 condID 不是由该 MultiConditionMonitor 实例通过 newCondition 函数创建时，抛出异常。

func notifyAll(ConditionID)

public func notifyAll(condID: ConditionID): Unit

功能：唤醒所有等待在所指定的条件变量的线程（如果有）。

参数：

condID: ConditionID - 条件变量。

异常：

IllegalSynchronizationStateException - 如果当前线程没有持有该互斥体，或 condID 不是由该 MultiConditionMonitor 实例通过 newCondition 函数创建时，抛出异常。

func wait(ConditionID, Duration)

public func wait(condID: ConditionID, timeout!: Duration = Duration.Max): Bool

功能：当前线程挂起，直到对应的 notify 函数被调用。

参数：

condID: ConditionID - 条件变量。
timeout!: Duration - 挂起时间，其默认值为 Duration.Max。

返回值：

Bool - 如果该 Monitor 指定的条件变量被其它线程唤醒，返回 true；如果超时，则返回 false。

异常：

IllegalSynchronizationStateException - 如果当前线程没有持有该互斥体，或者挂起时间超过 timeout 或 condID 不是由该 MultiConditionMonitor 实例通过 newCondition 函数创建时，抛出异常。
IllegalArgumentException - 如果 timeout 小于等于 Duration.Zero，抛出异常。

class ReentrantMutex

public open class ReentrantMutex <: IReentrantMutex

功能：提供可重入锁相关功能。

可重入互斥锁的作用是对临界区加以保护，使得任意时刻最多只有一个线程能够执行临界区的代码。当一个线程试图获取一个已被其他线程持有的锁时，该线程会被阻塞，直到锁被释放，该线程才会被唤醒，可重入是指线程获取该锁后可再次获得该锁。

注意：

ReentrantMutex 是内置的互斥锁，开发者需要保证不继承它。

在访问共享数据之前，必须尝试获取锁。

处理完共享数据后，必须进行解锁，以便其他线程可以获得锁。

init()

public init()

功能：创建可重入互斥锁。

异常：

IllegalSynchronizationStateException - 当出现系统错误时，抛出异常。

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 次该函数来完全解锁，一旦互斥体被完全解锁，如果有其他线程阻塞在此锁上，那么唤醒他们中的一个。

异常：

IllegalSynchronizationStateException - 如果当前线程没有持有该互斥体，抛出异常。

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

功能：释放读锁。如果一个线程多次持有读锁，那么仅当释放操作和获取操作数量相同时才释放读锁；如果读锁被释放并且存在线程等待写锁，那么唤醒其中一个线程。

异常：

IllegalSynchronizationStateException - 当前线程未持有读锁，那么将抛出异常。

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

功能：获取写锁。只允许唯一线程能够持有写锁，且该线程能多次重复持有写锁。如果存在其他线程持有写锁或是读锁，那么当前线程进入等待状态。

异常：

IllegalSynchronizationStateException - 当前线程已持有读锁。

func tryLock()

public func tryLock(): Bool

功能：尝试获取写锁。该方法获取读锁时并不遵循公平模式。

返回值：

Bool - 若成功获取写锁，返回 true；若未能获取写锁，返回 false。

func unlock()

public func unlock(): Unit

功能：释放写锁。

注意：

如果一个线程多次持有读锁，那么仅当释放操作和获取操作数量相同时才释放读锁；如果读锁被释放并且存在线程等待写锁，那么唤醒其中一个线程。

在公平模式下，如果写锁被释放并且存在线程等待读锁，那么优先唤醒这些等待线程；如果没有线程等待读锁，但存在线程等待写锁，那么唤醒其中一个线程。

在非公平模式下，如果写锁被释放，优先唤醒等待写锁的线程还是等待读锁的线程不做保证，交由具体实现决定。

异常：

IllegalSynchronizationStateException - 当前线程未持有写锁。

class Semaphore

public class Semaphore

功能：提供信号量相关功能。

Semaphore 可以被视为携带计数器的 Monitor，常用于控制并发访问共享资源的线程数量。

prop count

public prop count: Int64

功能：返回当前内部计数器的值。

类型：Int64

init(Int64)

public init(count: Int64)

功能：创建一个 Semaphore 对象并初始化内部计数器的值。

参数：

count: Int64 - 计数器初始值, 取值范围 [0, Int64.Max]。

异常：

IllegalArgumentException - 参数 count 为负数时抛出异常。

func acquire(Int64)

public func acquire(amount!: Int64 = 1): Unit

功能：向 Semaphore 对象获取指定值。

如果当前计数器小于要求的数值，那么当前线程将被阻塞，直到获取满足数量的值后才被唤醒。

参数：

amount!: Int64 - 向对象内部计数器中获取的数值，默认值为 1。

异常：

IllegalArgumentException - 参数 amount 为负数，或大于初始值。

func release(Int64)

public func release(amount!: Int64 = 1): Unit

功能：向 Semaphore 对象释放指定值。

如果内部计数器在累加释放值后能够满足当前阻塞在 Semaphore 对象的线程，那么将得到满足的线程唤醒；内部计数器的值不会大于初始值，即如果计数器的值在累加后大于初始值，那么仍被设置为初始值。所有在调用 release 之前的操作都先发生于调用 acquire/tryAcquire 之后的操作。

参数：

amount!: Int64 - 向对象内部计数器中释放的数值，默认值为 1。

返回值：

Unit - 如果当前计数器小于要求的数值，则获取失败并返回 false；成功获取值时返回 true。

异常：

IllegalArgumentException - 参数 amount 为负数，或大于初始值。

func tryAcquire(Int64)

public func tryAcquire(amount!: Int64 = 1): Bool

功能：尝试向 Semaphore 对象获取指定值。

该方法不会阻塞线程。如果有多个线程并发执行获取操作，则无法保证线程间的获取顺序。

参数：

amount!: Int64 - 向对象内部计数器中获取的数值，默认值为 1。

返回值：

Bool - 如果当前计数器小于要求的数值，则获取失败并返回 false；成功获取值时返回 true。

异常：

IllegalArgumentException - 参数 amount 为负数，或大于初始值。

class SyncCounter

public class SyncCounter

功能：提供倒数计数器功能。

线程可以等待计数器变为零。

prop count

public prop count: Int64

功能：获取计数器的当前值。

类型：Int64

init(Int64)

public init(count: Int64)

功能：创建倒数计数器。

参数：

count: Int64 - 倒数计数器的初始值。

异常：

IllegalArgumentException - 如果参数 count 为负数。

func dec()

public func dec(): Unit

功能：计数器减一。

如果计数器变为零，那么唤醒所有等待的线程；如果计数器已经为零，那么数值保持不变。

func waitUntilZero(Duration)

public func waitUntilZero(timeout!: Duration = Duration.Max): Unit

功能：当前线程等待直到计数器变为零，或等待时间超过 timeout。

参数：

timeout!: Duration - 阻塞时等待的最大时长，其默认值为 Duration.Max。

class Timer

public class Timer <: Equatable<Timer> & Hashable

功能：提供定时器功能。

用于在指定时间点或指定时间间隔后，执行指定任务一次或多次。

注意：

Timer 隐式包含了 spawn 操作，即，每个 Timer 会创建一个线程用于执行该 Timer 关联的 Task。

每个 Timer 只能在初始化时绑定一个 Task，初始化完成后，无法重置关联的 Task。

只有关联 Task 执行完毕，或使用 cancel 接口主动取消 Timer，Timer 的生命周期才会结束，之后才能被 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

返回值：

Timer - 一个 Timer 实例

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.sync.{Timer, sleep}
import std.time.{Duration, 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 对象实例。

异常:

IllegalArgumentException: 当 interval 小于等于 Duration.Zero 时，抛出异常。

示例:

import std.sync.{Timer, sleep}
import std.time.{Duration, 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 对象实例。

异常:

IllegalArgumentException: 当 period 小于等于 Duration.Zero 或 interval 小于等于 Duration.Zero 时，抛出异常。

示例:

import std.sync.{Timer, sleep}
import std.time.{Duration, 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 对象实例。

异常:

IllegalArgumentException: 当 count <= 0 或 interval 小于等于 Duration.Zero 时，抛出异常。

示例:

import std.sync.{Timer, sleep}
import std.time.{Duration, 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, sleep, CatchupStyle}
import std.time.{Duration, 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.*
import std.time.{Duration, DurationExtension}

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.*
import std.time.{Duration, DurationExtension}

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 标准的周
h	12小时制的小时
H	24小时制的小时
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 列表

接口

接口名	功能
DurationExtension	`DurationExtension` 用于拓展 `Duration` 实例作为右操作数时，返回乘积为新 `Duration` 实例的乘法运算。

类

类名	功能
DateTimeFormat	提供时间格式的功能，用于解析和生成 DateTime 。
TimeZone	`TimeZone` 表示时区，记录了某一地区在不同时间较零时区的时间偏移，提供了从系统加载时区、自定义时区等功能。

枚举

枚举名	功能
DayOfWeek	`DayOfWeek` 表示一周中的某一天，提供了与 `Int64` 类型转换，相等性判别以及获取枚举值的字符串表示的功能。
Month	`Month` 用以表示月份，表示一年中的某一月，提供了与 `Int64` 类型转换和计算，相等性判别以及获取枚举值的字符串表示的功能。

结构体

结构体名	功能
DateTime	`DateTime` 表示日期时间，是一个描述某一时间点的时间类型，提供了基于时区的日期时间读取、计算、比较、转换，以及序列化和反序列化等功能。
Duration	`Duration` 表示时间间隔，是一个描述一段时间的时间类型，提供了常用的静态实例，以及计算、比较等功能。
MonoTime	`MonoTime` 表示单调时间，是一个用来衡量经过时间的时间类型，类似于一直运行的秒表，提供了获取当前时间，计算和比较等功能。

异常类

异常类名	功能
InvalidDataException	`InvalidDataException` 表示加载时区时的异常。
TimeParseException	`TimeParseException` 表示解析时间字符串时的异常。

接口

interface DurationExtension

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

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

operator func *(Duration)

operator func *(r: Duration): Duration

功能：实现 T 类型（T 是实现 DurationExtension 接口的类型）和 Duration 类型的乘法，即 T * Duration 运算。

参数：

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

返回值：

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

异常：

ArithmeticException - 当相乘后的结果超出 Duration 的表示范围时，抛出异常。

extend Float64 <: DurationExtension

extend Float64 <: DurationExtension

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

operator func *(Duration)

public operator func *(r: Duration): Duration

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

参数：

r: Duration - Duration 实例。

返回值：

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

异常：

ArithmeticException - 当相乘后的结果超出 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 - 乘法的右操作数。

返回值：

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

异常：

ArithmeticException - 当相乘后的结果超出 Duration 的表示范围时，抛出异常。

类

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 - 字符串格式

返回值：

DateTimeFormat - 时间格式。

异常：

IllegalArgumentException - 当入参格式不符合时间字符串格式中字母数量的规定时，抛出异常。

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 从系统时区文件中加载时区。若环境变量 TZ 未设置或者为空，则加载名为 localtime 的本地时区。

环境变量 TZ 的取值为标准时区 ID 格式（各操作系统遵循相同规范），例如“Asia/Shanghai”。

Linux 和 macOS：系统时区文件依赖路径“/usr/share/zoneinfo”，本地时区文件依赖“/etc/localtime”链接。若系统不存在这些依赖路径，则返回 UTC。通过时区 ID 方式加载时区时，若无法从相应路径中找到 ID 对应的时区文件，则返回 UTC。通过本地时区文件方式加载时区时，若本地时区文件依赖“/etc/localtime" 未链接时区文件时，则返回 UTC 。
Windows 和 OHOS：返回 UTC。

类型：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)。

异常：

IllegalArgumentException - 当输入 id 为空字符串，或 offset 超出有效区间时，抛出异常。

static func load(String)

public static func load(id: String): TimeZone

功能：从系统中加载参数 id 指定的时区。

在 Linux 和 macOS 系统中，若存在环境变量 CJ_TZPATH，则使用环境变量指定的路径加载时区文件（若存在多个通过分隔符 “:” 分开的环境变量值，则按照分隔路径的先后顺序依次查找时区文件，并加载第一个找到的时区文件），否则从系统时区文件目录 "/usr/share/zoneinfo" 加载时区。
在 Windows 和 OHOS 系统中，用户需下载时区文件并编译，设置环境变量 CJ_TZPATH 指向 zoneinfo 目录（若存在多个通过分隔符 “;” 分开的环境变量值，则按照分隔路径的先后顺序依次查找时区文件，并加载第一个找到的时区文件），否则会导致异常。

参数：

id: String - 时区 ID。

返回值：

TimeZone - 时区。

异常：

IllegalArgumentException - 当参数 id 为空，或长度超过 4096 字节，或不符合标准时区 ID 格式时，抛出异常。
InvalidDataException - 当时区文件加载失败(找不到文件，文件解析失败等)时，抛出异常。

static func loadFromPaths(String, Array<String>)

public static func loadFromPaths(id: String, tzpaths: Array<String>): TimeZone

功能：根据参数 tzpaths 指定的时区文件目录，加载参数 id 指定的时区。

加载时区时，将从第一个被读取成功的时区文件路径中加载时区。时区文件格式需要满足时区信息格式。

参数：

id: String - 时区 ID。
tzpaths: Array<String> - 时区文件路径数组。

返回值：

TimeZone - 加载的时区。

异常：

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 实例，否则抛出异常。

参数：

id: String - 时区 ID。
data: Array<UInt8> - 满足时区信息格式的数据。

返回值：

TimeZone - 加载的时区。

异常：

IllegalArgumentException - 当 id 为空时，抛出异常。
InvalidDataException - 如果 data 解析失败，则抛出异常。

func toString()

public func toString(): String

功能：获取本 TimeZone 实例时区 ID 的字符串表示。

返回值：

String - 时区 ID 的字符串表示。

operator func !=(TimeZone)

public operator func !=(r: TimeZone): Bool

功能：判断当前 TimeZone 实例的引用是否不等于 r 的引用。

参数：

r: TimeZone - TimeZone 实例。

返回值：

Bool - true 或 false。当前 TimeZone 实例的引用不等于 r 的引用时，返回 true；否则，返回 false。

operator func ==(TimeZone)

public operator func ==(r: TimeZone): Bool

功能：判断当前 TimeZone 实例的引用是否等于 r 的引用。

参数：

r: TimeZone - TimeZone 实例。

返回值：

Bool - true 或 false。当前 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 表示周一至周六。

返回值：

DayOfWeek - 参数 dayOfWeek 对应的 DayOfWeek 实例。

异常：

IllegalArgumentException - 当参数 dayOfWeek 不在 [0, 6] 范围内时，抛出异常。

func toString()

public func toString(): String

功能：返回当前 DayOfWeek 实例的字符串表示，如 "Monday" 表示周一。

返回值：

String - 当前 DayOfWeek 实例的字符串表示。

func value()

public func value(): Int64

功能：获取当前 DayOfWeek 实例的整数表示，周日表示为 0，周一至周六表示为 1 至 6。

返回值：

Int64 - 当前 DayOfWeek 实例的整数表示。

operator func !=(DayOfWeek)

public operator func !=(r: DayOfWeek): Bool

功能：判断当前 DayOfWeek 和 r 是否不为一周中的同一天。

参数：

r: DayOfWeek - DayOfWeek 实例。

返回值：

Bool - true 或 false。当前 DayOfWeek 实例不等于 r 时，返回 true；否则，返回 false。

operator func ==(DayOfWeek)

public operator func ==(r: DayOfWeek): Bool

功能：判断当前 DayOfWeek 和 r 是否表示一周中的同一天。

参数：

r: DayOfWeek - DayOfWeek 实例。

返回值：

Bool - true 或 false。当前 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 类型实例。

异常：

IllegalArgumentException - 当参数 mon 不在 [1, 12] 范围内时，抛出异常。

func toString()

public func toString(): String

功能：返回当前 Month 实例的字符串表示，如 "January" 表示一月。

返回值：

String - 当前 Month 实例的字符串表示。

func value()

public func value(): Int64

功能：获取当前 Month 实例的整数表示，一月至十二月分别表示为 1 至 12。

返回值：

Int64 - 当前 Month 实例的整数表示。

operator func !=(Month)

public operator func !=(r: Month): Bool

功能：判断当前 Month 实例和 r 是否不为同一个月。

参数：

r: Month - Month 实例。

返回值：

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 是否表示同一个月。

参数：

r: Month - Month 实例。

返回值：

Bool - true 或 false。当前 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]，该区间适用于任何合法的时区。
以下为 DateTime 中 now 和 nowUTC 函数获取当前时间使用的系统调用函数：

系统系统调用函数时钟类型

Linux clock_gettime CLOCK_REALTIME

Windows clock_gettime CLOCK_REALTIME

macOS clock_gettime CLOCK_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 指定时间间隔后的日期时间。

参数：

d: Duration - 时间间隔。

返回值：

DateTime - 自 UnixEpoch 开始，指定 d 后的日期时间。

异常：

ArithmeticException - 当结果超过日期时间的表示范围时，抛出异常。

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() 替代。

返回值：

DateTime - UTC 时区当前时间。

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 - 时区。

返回值：

DateTime - 根据指定参数构造的 DateTime 实例。

异常：

IllegalArgumentException - 当参数值超出指定范围，抛出异常。

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 - 时区。

返回值：

DateTime - 根据指定参数构造的 DateTime 实例。

异常：

IllegalArgumentException - 当参数值超出指定范围，抛出异常。

static func ofEpoch(Int64, Int64)

public static func ofEpoch(second!: Int64, nanosecond!: Int64): DateTime

功能：根据入参 second 和 nanosecond 构造 DateTime 实例。入参 second 表示 unix 时间的秒部分，nanosecond 表示 unix 时间的纳秒部分。unix 时间以 UnixEpoch 开始计算，nanosecond 的范围不可以超过[0, 999,999,999]，否则抛出异常。

参数：

second!: Int64 - unix 时间的秒部分。
nanosecond!: Int64 - unix 时间的纳秒部分，范围不可以超过[0, 999,999,999]。

返回值：

DateTime - 自 UnixEpoch 开始，指定 second 和 nanosecond 后的时间。

异常：

IllegalArgumentException - 当 nanosecond 值超出指定范围时，抛出异常。
ArithmeticException - 当结果超过日期时间的表示范围时，抛出异常。

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]。

返回值：

DateTime - 根据指定参数构造的 UTC 时区 DateTime 实例。

异常：

IllegalArgumentException - 当参数值超出指定范围时，抛出异常

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]。

返回值：

DateTime - 根据指定参数构造的 UTC 时区 DateTime 实例。

异常：

IllegalArgumentException - 当参数值超出指定范围时，抛出异常。

static func parse(String)

public static func parse(str: String): DateTime

功能：从参数 str 中解析得到时间，解析成功时返回 DateTime 实例。

参数：

str: String - 时间字符串，格式为 RFC3339 中 date-time 格式，可包含小数秒，如 "2023-04-10T08:00:00[.123456]+08:00"([] 中的内容表示可选项)。

返回值：

DateTime - 从参数 str 中解析出的 DateTime 实例。

异常：

TimeParseException - 无法正常解析时，抛出异常。

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 实例。

异常：

TimeParseException - 当无法正常解析时，或存在同一 format 的多次取值时，抛出异常。
IllegalArgumentException - 当 format 格式不正确时，抛出异常。

static func parse(String, DateTimeFormat)

public static func parse(str: String, format: DateTimeFormat): DateTime

参数：

str: String - 时间字符串，例如："2023/04/10 08:00:00 +08:00"。
format: DateTimeFormat - 时间格式，例如："yyyy/MM/dd HH:mm:ss OOOO"对应的时间格式。格式说明详见时间字符串格式。

返回值：

DateTime - 根据参数 format 指定的时间格式，从参数 str 中解析出的 DateTime 实例。

异常：

TimeParseException - 当无法正常解析时，或存在同一 format 的多次取值时，抛出异常。
IllegalArgumentException - 当 format 格式不正确时，抛出异常。

func addDays(Int64)

public func addDays(n: Int64): DateTime

功能：获取 DateTime 实例 n 天之后的时间，返回新的 DateTime 实例。

参数：

n: Int64 - 自 DateTime 实例后多少天的数量。

返回值：

DateTime - DateTime 实例 n 天后的时间。

异常：

ArithmeticException - DateTime 实例 n 天后的日期时间超过表示范围时，抛出异常。

func addHours(Int64)

public func addHours(n: Int64): DateTime

功能：获取 DateTime 实例 n 小时之后的时间，返回新的 DateTime 实例。

参数：

n: Int64 - 自 DateTime 实例后多少小时的数量。

返回值：

DateTime - DateTime 实例 n 小时后的时间。

异常：

ArithmeticException - DateTime 实例 n 小时后的日期时间超过表示范围时，抛出异常。

func addMinutes(Int64)

public func addMinutes(n: Int64): DateTime

功能：获取 DateTime 实例 n 分钟之后的时间，返回新的 DateTime 实例。

参数：

n: Int64 - 自 DateTime 实例后多少分钟的数量。

返回值：

DateTime - DateTime 实例 n 分钟后的时间。

异常：

ArithmeticException - DateTime 实例 n 分钟后的日期时间超过表示范围时，抛出异常。

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日”。

参数：

n: Int64 - 自 DateTime 实例后多少月的数量。

返回值：

DateTime - DateTime 实例 n 月后的时间。

异常：

ArithmeticException - DateTime 实例 n 月后的日期时间超过表示范围时，抛出异常。

func addNanoseconds(Int64)

public func addNanoseconds(n: Int64): DateTime

功能：获取 DateTime 实例 n 纳秒之后的时间，返回新的 DateTime 实例。

参数：

n: Int64 - 自 DateTime 实例后多少纳秒的数量。

返回值：

DateTime - DateTime 实例 n 纳秒后的时间。

异常：

ArithmeticException - DateTime 实例 n 纳秒后时间的日期时间超过表示范围时，抛出异常。

func addSeconds(Int64)

public func addSeconds(n: Int64): DateTime

功能：获取 DateTime 实例 n 秒之后的时间，返回新的 DateTime 实例。

参数：

n: Int64 - 自 DateTime 实例后多少秒的数量。

返回值：

DateTime - DateTime 实例 n 秒后的时间。

异常：

ArithmeticException - DateTime 实例 n 秒后的日期时间超过表示范围时，抛出异常。

func addWeeks(Int64)

public func addWeeks(n: Int64): DateTime

功能：获取 DateTime 实例 n 周之后的时间，返回新的 DateTime 实例。

参数：

n: Int64 - 自 DateTime 实例后多少周的数量。

返回值：

DateTime - DateTime 实例 n 周后的时间。

异常：

功能：获取入参 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日”。

参数：

n: Int64 - 自 DateTime 实例后多少年的数量。

返回值：

DateTime - DateTime 实例 n 年后的时间。

异常：

ArithmeticException - DateTime 实例 n 年后的日期时间超过表示范围时，抛出异常。

func compare(DateTime)

public func compare(rhs: DateTime): Ordering

功能：判断一个 DateTime 实例与参数 rhs 的大小关系。如果大于，返回 Ordering.GT；如果等于，返回 Ordering.EQ；如果小于，返回 Ordering.LT。

参数：

rhs: DateTime - 参与比较的 DateTime 实例。

返回值：

Ordering - DateTime 实例与 rhs 大小关系。

func hashCode()

public func hashCode(): Int64

功能：获取 DateTime 实例的哈希值。

返回值：

Int64 - 哈希值。

func inLocal()

public func inLocal(): DateTime

功能：获取 DateTime 实例在本地时区的时间。

返回值：

DateTime - DateTime 实例在本地时区的时间。

异常：

ArithmeticException - 当返回的 DateTime 实例表示的日期时间超过表示范围时，抛出异常。

func inTimeZone(TimeZone)

public func inTimeZone(timeZone: TimeZone): DateTime

功能：获取 DateTime 实例在参数 timeZone 指定时区的时间。

参数：

timeZone: TimeZone - 目标时区。

返回值：

DateTime - DateTime 实例在参数 timezone 指定时区的时间。

异常：

ArithmeticException - 当返回的 DateTime 实例表示的日期时间超过表示范围时，抛出异常。

func inUTC()

public func inUTC(): DateTime

功能：获取 DateTime 实例在 UTC 时区的时间。

返回值：

DateTime - DateTime 实例在 UTC 时区的时间。

异常：

ArithmeticException - 当返回的 DateTime 实例表示的日期时间超过表示范围时，抛出异常。

func toString()

public func toString(): String

功能：返回一个表示 DateTime 实例的字符串，其格式为 RFC3339 中 date-time 格式，如果时间包含纳秒信息（不为零），会打印出小数秒。

返回值：

String - DateTime 实例的字符串表示。

func toString(String)

public func toString(format: String): String

功能：返回一个表示 DateTime 实例的字符串，其格式由参数 format 指定。格式说明详见时间字符串格式

参数：

format: String - 返回字符串的格式，其格式可为 "yyyy/MM/dd HH:mm:ss OOOO"。

返回值：

String - DateTime 实例在 format 指定格式下的字符串。

异常：

IllegalArgumentException - 当 format 格式不正确时，抛出异常。

func toString(DateTimeFormat)

public func toString(format: DateTimeFormat): String

功能：返回一个表示 DateTime 实例的字符串，其格式由参数 format 指定。格式说明详见时间字符串格式

参数：

format: DateTimeFormat - 时间格式，其格式可为 "yyyy/MM/dd HH:mm:ss OOOO"。

返回值：

String - DateTime 实例在 format 指定格式下的字符串。

异常：

IllegalArgumentException - 当 format 格式不正确时，抛出异常。

func toUnixTimeStamp()

public func toUnixTimeStamp(): Duration

功能：获取当前实例自 UnixEpoch 的时间间隔。

返回值：

Duration - 当前实例自 UnixEpoch 的时间间隔。

operator func !=(DateTime)

public operator func !=(r: DateTime): Bool

功能：判断当前 DateTime 实例是否不等于 r。

若两个 DateTime 不相等，那么它们指向的不是同一 UTC 时间。

参数：

r: DateTime - DateTime 实例。

返回值：

Bool - true 或 false。当前 DateTime 实例不等于 r 时，返回 true；否则，返回 false。

operator func +(Duration)

public operator func +(r: Duration): DateTime

功能：实现 DateTime 类型和 Duration 类型加法，即 DateTime + Duration 运算。

参数：

r: Duration - 加法的右操作数。

返回值：

DateTime - DateTime 类型实例和 r 的和。

异常：

ArithmeticException - 当结果超过日期时间的表示范围时，抛出异常。

operator func -(DateTime)

public operator func -(r: DateTime): Duration

功能：实现 DateTime 类型之间的减法，即 DateTime - DateTime 运算。

参数：

r: DateTime - 减法的右操作数。

返回值：

Duration - DateTime 类型实例和 r 的差。

operator func -(Duration)

public operator func -(r: Duration): DateTime

功能：实现 DateTime 类型和 Duration 类型减法，即 DateTime - Duration 运算。

参数：

r: Duration - 减法的右操作数。

返回值：

DateTime - DateTime 类型实例和 r 的差。

异常：

ArithmeticException - 当结果超过日期时间的表示范围时，抛出异常。

operator func <(DateTime)

public operator func <(r: DateTime): Bool

功能：判断当前 DateTime 实例是否早于 r（指向更早的 UTC 时间的 DateTime 更小）。

参数：

r: DateTime - DateTime 实例。

返回值：

Bool - true 或 false。当前 DateTime 实例早于 r 时，返回 true；否则，返回 false。

operator func <=(DateTime)

public operator func <=(r: DateTime): Bool

功能：判断当前 DateTime 实例是否早于或等于 r（指向更早的 UTC 时间的 DateTime 更小）。

参数：

r: DateTime - DateTime 实例。

返回值：

Bool - true 或 false。当前 DateTime 实例早于或等于 r 时，返回 true；否则，返回 false。

operator func ==(DateTime)

public operator func ==(r: DateTime): Bool

功能：判断当前 DateTime 实例是否等于 r。

若两个 DateTime 相等，那么它们指向同一 UTC 时间。

参数：

r: DateTime - DateTime 实例。

返回值：

Bool - true 或 false。当前 DateTime 实例等于 r 时，返回 true；否则，返回 false。

operator func >(DateTime)

public operator func >(r: DateTime): Bool

功能：判断当前 DateTime 实例是否晚于 r（指向更晚的 UTC 时间的 DateTime 更大）。

参数：

r: DateTime - DateTime 实例。

返回值：

Bool - true 或 false。当前 DateTime 实例晚于 r 时，返回 true；否则，返回 false。

operator func >=(DateTime)

public operator func >=(r: DateTime): Bool

功能：判断当前 DateTime 实例是否晚于或等于 r（指向更晚的 UTC 时间的 DateTime 更大）。

参数：

r: DateTime - DateTime 实例。

返回值：

Bool - true 或 false。当前 DateTime 实例晚于或等于 r 时，返回 true；否则，返回 false。

struct Duration

public struct Duration <: ToString & Hashable & Comparable<Duration>

功能：Duration 表示时间间隔，是一个描述一段时间的时间类型，提供了常用的静态实例，以及计算、比较等功能。

说明：

Duration 表示范围为 Duration.Min 至 Duration.Max，数值表示为 [-2⁶³, 2⁶³)（单位为秒），精度为纳秒。

Duration 每个时间单位均用整数表示，如果实际值不为整数，则向绝对值小的方向取整。例如表示 1小时30分46秒 的 Duration 实例调用 toHours 方法，将返回结果 1 而不是 1.5 或 2。

static prop Max

public static prop Max: Duration

功能：表示最大时间间隔的 Duration 实例。

类型：Duration

static prop Min

public static prop Min: Duration

功能：表示最小时间间隔的 Duration 实例。

类型：Duration

static prop Zero

public static prop Zero: Duration

功能：表示 0 纳秒时间间隔的 Duration 实例。

类型：Duration

static prop day

public static prop day: Duration

功能：表示 1 天时间间隔的 Duration 实例。

类型：Duration

static prop hour

public static prop hour: Duration

功能：表示 1 小时时间间隔的 Duration 实例。

类型：Duration

static prop microsecond

public static prop microsecond: Duration

功能：表示 1 微秒时间间隔的 Duration 实例。

类型：Duration

static prop millisecond

public static prop millisecond: Duration

功能：表示 1 毫秒时间间隔的 Duration 实例。

类型：Duration

static prop minute

public static prop minute: Duration

功能：表示 1 分钟时间间隔的 Duration 实例。

类型：Duration

static prop nanosecond

public static prop nanosecond: Duration

功能：表示 1 纳秒时间间隔的 Duration 实例。

类型：Duration

static prop second

public static prop second: Duration

功能：表示 1 秒时间间隔的 Duration 实例。

类型：Duration

static func since(DateTime)

public static func since(t: DateTime): Duration

功能：计算从参数 t 开始到当前时间为止的时间间隔。

参数：

t: DateTime - DateTime 实例。

返回值：

Duration - Duration 实例。

static func until(DateTime)

public static func until(t: DateTime): Duration

功能：计算从当前时间开始到参数 t 为止的时间间隔。

参数：

t: DateTime - DateTime 实例。

返回值：

Duration - Duration 实例。

func abs()

public func abs(): Duration

功能：返回一个新的 Duration 实例，其值大小为当前 Duration 实例绝对值。

返回值：

Duration - 当前 Duration 实例取绝对值的结果。

异常：

ArithmeticException - 如果当前 Duration 实例等于 Duration.Min，会因为取绝对值超出 Duration 表示范围而抛异常。

func compare(Duration)

public func compare(rhs: Duration): Ordering

功能：比较当前 Duration 实例与另一个 Duration 实例的关系，如果大于，返回 Ordering.GT；如果等于，返回 Ordering.EQ；如果小于，返回 Ordering.LT。

参数：

rhs: Duration - 参与比较的 Duration 实例。

返回值：

Ordering - 当前 Duration 实例与 rhs 的大小关系。

func hashCode()

public func hashCode(): Int64

功能：获得当前 Duration 实例的哈希值。

返回值：

Int64 - 当前 Duration 实例的哈希值。

func toDays()

public func toDays(): Int64

功能：获得当前 Duration 实例以天为单位的整数大小。

返回值：

Int64 - 当前 Duration 实例以天为单位的大小。

func toHours()

public func toHours(): Int64

功能：获得当前 Duration 实例以小时为单位的整数大小。

返回值：

Int64 - 当前 Duration 实例以小时为单位的大小。

func toMicroseconds()

public func toMicroseconds(): Int64

功能：获得当前 Duration 实例以微秒为单位的整数大小。

返回值：

Int64 - 当前 Duration 实例以微秒为单位的大小。

异常：

ArithmeticException - 当 Duration 实例以微秒为单位的大小超过 Int64 表示范围时，抛出异常。

func toMilliseconds()

public func toMilliseconds(): Int64

功能：获得当前 Duration 实例以毫秒为单位的整数大小。

返回值：

Int64 - 当前 Duration 实例以毫秒为单位的大小。

异常：

ArithmeticException - 当 Duration 实例以毫秒为单位的大小超过 Int64 表示范围时，抛出异常。

func toMinutes()

public func toMinutes(): Int64

功能：获得当前 Duration 实例以分钟为单位的整数大小。

返回值：

Int64 - 当前 Duration 实例以分钟为单位的大小。

func toNanoseconds()

public func toNanoseconds(): Int64

功能：获得当前 Duration 实例以纳秒为单位的整数大小，向绝对值小的方向取整。

返回值：

Int64 - 当前 Duration 实例以纳秒为单位的大小。

异常：

ArithmeticException - 当 Duration 实例以“纳秒”为单位的大小超过 Int64 表示范围时，抛出异常。

func toSeconds()

public func toSeconds(): Int64

功能：获得当前 Duration 实例以秒为单位的整数大小。

返回值：

Int64 - 当前 Duration 实例以秒为单位的大小。

func toString()

public func toString(): String

功能：获得当前 Duration 实例的字符串表示，格式形如："1d2h3m4s5ms6us7ns"，表示“1天2小时3分钟4秒5毫秒6微秒7纳秒”。某个单位下数值为 0 时此项会被省略，特别地，当所有单位下数值都为 0 时，返回 "0s"。

返回值：

String - 当前 Duration 实例的字符串表示。

operator func !=(Duration)

public operator func !=(r: Duration): Bool

功能：判断当前 Duration 实例是否不等于 r。

参数：

r: Duration - Duration 实例。

返回值：

Bool - true 或 false。当前 Duration 实例不等于 r 时，返回 true；否则，返回 false。

operator func *(Float64)

public operator func *(r: Float64): Duration

功能：实现 Duration 类型与 Float64 类型的乘法，即 Duration * Float64 运算。

参数：

r: Float64 - 乘法的右操作数。

返回值：

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

异常：

ArithmeticException - 当相乘后的结果超出 Duration 的表示范围时，抛出异常。

operator func *(Int64)

public operator func *(r: Int64): Duration

功能：实现 Duration 类型与 Int64 类型的乘法，即 Duration * Int64 运算。

参数：

r: Int64 - 乘法的右操作数。

返回值：

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

异常：

ArithmeticException - 当相乘后的结果超出 Duration 的表示范围时，抛出异常。

operator func +(Duration)

public operator func +(r: Duration): Duration

功能：实现 Duration 类型之间的加法，即 Duration + Duration 运算。

参数：

r: Duration - 加法的右操作数。

返回值：

Duration - Duration 类型实例和 r 的和。

异常：

ArithmeticException - 当相加后的结果超出 Duration 的表示范围时，抛出异常。

operator func -(Duration)

public operator func -(r: Duration): Duration

功能：实现 Duration 类型之间的减法，即 Duration - Duration 运算。

参数：

r: Duration - 减法的右操作数。

返回值：

Duration - Duration 类型实例和 r 的差。

异常：

ArithmeticException - 当相减后的结果超出 Duration 的表示范围时，抛出异常。

operator func /(Duration)

public operator func /(r: Duration): Float64

功能：实现 Duration 类型与 Duration 类型的除法，即 Duration / Duration 运算。

参数：

r: Duration - 除数。

返回值：

Float64 - Duration 类型实例和 r 的商。

异常：

IllegalArgumentException - 当 r 等于 Duration.Zero 时，抛出异常。

operator func /(Float64)

public operator func /(r: Float64): Duration

功能：实现 Duration 类型与 Float64 类型的除法，即 Duration / Float64 运算。

参数：

r: Float64 - 除数。

返回值：

Duration - Duration 类型实例和 r 的商。

异常：

IllegalArgumentException - 当 r 等于 0 时，抛出异常。
ArithmeticException - 当相除后的结果超出 Duration 的表示范围时，抛出异常。

operator func /(Int64)

public operator func /(r: Int64): Duration

功能：实现 Duration 类型与 Int64 类型的除法，即 Duration / Int64 运算。

参数：

r: Int64 - 除数。

返回值：

Duration - Duration 类型实例和 r 的商。

异常：

IllegalArgumentException - 当 r 等于 0 时，抛出异常。
ArithmeticException - 当相除后的结果超出 Duration 的表示范围时，抛出异常。

operator func <(Duration)

public operator func <(r: Duration): Bool

功能：判断当前 Duration 实例是否小于 r。

参数：

r: Duration - Duration 实例。

返回值：

Bool - true 或 false。当前 Duration 实例小于 r 时，返回 true；否则，返回 false。

operator func <=(Duration)

public operator func <=(r: Duration): Bool

功能：判断当前 Duration 实例是否小于等于 r。

参数：

r: Duration - Duration 实例。

返回值：

Bool - true 或 false。当前 Duration 实例小于等于 r 时，返回 true；否则，返回 false。

operator func ==(Duration)

public operator func ==(r: Duration): Bool

功能：判断当前 Duration 实例是否等于 r。

参数：

r: Duration - Duration 实例。

返回值：

Bool - true 或 false。当前 Duration 实例等于 r 时，返回 true；否则，返回 false。

operator func >(Duration)

public operator func >(r: Duration): Bool

功能：判断当前 Duration 实例是否大于 r。

参数：

r: Duration - Duration 实例。

返回值：

Bool - true 或 false。当前 Duration 实例大于 r 时，返回 true；否则，返回 false。

operator func >=(Duration)

public operator func >=(r: Duration): Bool

功能：判断当前 Duration 实例是否大于等于 r。

参数：

r: Duration - Duration 实例。

返回值：

Bool - true 或 false。当前 Duration 实例大于等于 r 时，返回 true；否则，返回 false。

struct MonoTime

public struct MonoTime <: Hashable & Comparable<MonoTime>

功能：MonoTime 表示单调时间，是一个用来衡量经过时间的时间类型，类似于一直运行的秒表，提供了获取当前时间，计算和比较等功能。

MonoTime 可表示的范围为 Duration.Zero 至 Duration.Max，数值表示为 [0, 2⁶³)（单位为秒），精度为纳秒。通过 now 方法创建的 MonoTime 总是晚于先使用该方式创建的 MonoTime，常用于性能测试和时间优先的任务队列。
以下为 MonoTime 中 now 函数获取当前时间使用的系统调用函数：

系统系统调用函数时钟类型

Linux clock_gettime CLOCK_MONOTONIC

Windows clock_gettime CLOCK_MONOTONIC

macOS clock_gettime CLOCK_MONOTONIC

static func now()

public static func now(): MonoTime

功能：获取与当前时间对应的 MonoTime。

返回值：

MonoTime - 与当前时间对应的 MonoTime。

func compare(MonoTime)

public func compare(rhs: MonoTime): Ordering

功能：判断一个 MonoTime 实例与参数 rhs 的大小关系。如果大于，返回 Ordering.GT；如果等于，返回 Ordering.EQ；如果小于，返回 Ordering.LT。

参数：

rhs: MonoTime - 参与比较的 MonoTime 实例。

返回值：

Ordering - 当前 MonoTime 实例与 rhs 大小关系。

func hashCode()

public func hashCode(): Int64

功能：获取当前 MonoTime 实例的哈希值。

返回值：

Int64 - 哈希值。

operator func !=(MonoTime)

public operator func !=(r: MonoTime): Bool

功能：判断当前 MonoTime 实例是否不等于 r。

参数：

r: MonoTime - 单调时间。

返回值：

Bool - true 或 false。当前 MonoTime 实例不等于 r 时，返回 true；否则，返回 false。

operator func +(Duration)

public operator func +(r: Duration): MonoTime

功能：实现 MonoTime 类型和 Duration 类型加法，即 MonoTime + Duration 运算。

参数：

r: Duration - 时间间隔。

返回值：

MonoTime - 参数 r 表示时间间隔后的单调时间。

异常：

ArithmeticException - 当结果超过单调时间的表示范围时，抛出异常。

operator func -(Duration)

public operator func -(r: Duration): MonoTime

功能：实现 MonoTime 类型和 Duration 类型减法，即 MonoTime - Duration 运算。

参数：

r: Duration - 时间间隔。

返回值：

MonoTime - 参数 r 表示时间间隔前的单调时间。

异常：

ArithmeticException - 当结果超过单调时间的表示范围时，抛出异常。

operator func -(MonoTime)

public operator func -(r: MonoTime): Duration

功能：实现 MonoTime 类型之间的减法，即 MonoTime - MonoTime 运算。

参数：

r: MonoTime - 单调时间。

返回值：

Duration - 当前实例距 r 经过的时间间隔。

operator func <(MonoTime)

public operator func <(r: MonoTime): Bool

功能：判断当前 MonoTime 实例是否早于 r。

参数：

r: MonoTime - 单调时间。

返回值：

Bool - true 或 false。当前 MonoTime 实例早于 r 时，返回 true；否则，返回 false。

operator func <=(MonoTime)

public operator func <=(r: MonoTime): Bool

功能：判断当前 MonoTime 实例是否早于或等于 r。

参数：

r: MonoTime - 单调时间。

返回值：

Bool - true 或 false。当前 MonoTime 实例早于或等于 r 时，返回 true；否则，返回 false。

operator func ==(MonoTime)

public operator func ==(r: MonoTime): Bool

功能：判断当前 MonoTime 实例是否等于 r。

参数：

r: MonoTime - 单调时间。

返回值：

Bool - true 或 false。当前 MonoTime 实例等于 r 时，返回 true；否则，返回 false。

operator func >(MonoTime)

public operator func >(r: MonoTime): Bool

功能：判断当前 MonoTime 实例是否晚于 r。

参数：

r: MonoTime - 单调时间。

返回值：

Bool - true 或 false。当前 MonoTime 实例晚于 r 时，返回 true；否则，返回 false。

operator func >=(MonoTime)

public operator func >=(r: MonoTime): Bool

功能：判断当前 MonoTime 实例是否晚于或等于 r。

参数：

r: MonoTime - 单调时间。

返回值：

Bool - true 或 false。当前 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 相关的字符操作。并为 Rune、String 类型实现了若干扩展方法，包括字符类型判断、字符大小写转换等。

API 列表

接口

接口名	功能
UnicodeExtension	`Unicode` 字符集相关扩展的接口，用于为其他类型扩展 `Unicode` 字符集相关的操作。

接口

interface UnicodeExtension

public interface UnicodeExtension

功能：Unicode 字符集相关扩展的接口，用于为其他类型扩展 Unicode 字符集相关的操作。

可用于为 Rune 和 String 类型增加一系列与 Unicode 字符集相关的扩展函数，包括字符类型判断，字符大小写转换，删除空白字符等。

extend Rune <: UnicodeExtension

extend Rune <: UnicodeExtension

func isLetter()

public func isLetter(): Bool

功能：判断字符是否是 Unicode 字母字符。

返回值：

Bool - 如果该字符是 Unicode 字母字符，返回 true，否则返回 false。

示例：

import std.unicode.*

main(): Unit {
    println('a'.isLetter())
    println('1'.isLetter())
}

运行结果：

true
false

func isLowerCase()

public func isLowerCase(): Bool

功能：判断字符是否是 Unicode 小写字符。

返回值：

Bool - 如果该字符是 Unicode 小写字符，返回 true，否则返回 false。

示例：

import std.unicode.*

main(): Unit {
    println('a'.isLowerCase())
    println('A'.isLowerCase())
}

运行结果：

true
false

func isNumber()

public func isNumber(): Bool

功能：判断字符是否是 Unicode 数字字符。

返回值：

Bool - 如果该字符是 Unicode 数字字符，返回 true，否则返回 false。

示例：

import std.unicode.*

main(): Unit {
    println('a'.isNumber())
    println('1'.isNumber())
}

运行结果：

false
true

func isTitleCase()

public func isTitleCase(): Bool

功能：判断字符是否是 Unicode 标题化字符。

Unicode 中的标题化字符指的是一种特殊的字母形式，它们在某些语言中用于表示标题中每个单词的首字母大写的形式。这些字母由特殊的字符表示，例如U+01C5（ǅ）和U+01F1（Ǳ）。这些字符通常用于一些东欧语言，如克罗地亚语和塞尔维亚语。

标题化字符包括：0x01C5、0x01C8、0x01CB、0x01F2、0x1F88 - 0x1F8F、0x1F98 - 0x1F9F、0x1F98 - 0x1F9F、0x1FA8 - 0x1FAF、0x1FBC、0x1FCC、0x1FFC

返回值：

Bool - 如果该字符是 Unicode 标题大写字符，返回 true，否则返回 false。

示例：

import std.unicode.*

main(): Unit {
    println('ǅ'.isTitleCase())
}

运行结果：

true

func isUpperCase()

public func isUpperCase(): Bool

功能：：判断字符是否是 Unicode 大写字符。

返回值：

Bool - 如果该字符是 Unicode 大写字符，返回 true，否则返回 false。

示例：

import std.unicode.*

main(): Unit {
    println('a'.isUpperCase())
    println('A'.isUpperCase())
}

运行结果：

false
true

func isWhiteSpace()

public func isWhiteSpace(): Bool

功能：判断字符是否是 Unicode 空白字符。

空白字符包括 0x0009、0x000A、0x000B、0x000C、0x000D、0x0020、0x0085、0x00A0、0X1680、0X2000、0X2001、0X2002、0X2003、0X2004、0X2005、0X2006、0X2007、0X2008、0X2009、0X200A、0X2028、0X2029、0X202F、0X205F、0X3000。

返回值：

Bool - 如果该字符是 Unicode 空白字符，返回 true，否则返回 false。

示例：

import std.unicode.*

main(): Unit {
    println(' '.isWhiteSpace())
}

运行结果：

true

func toLowerCase()

public func toLowerCase(): Rune

功能：获取该字符对应的 Unicode 小写字符。

返回值：

Rune - 当前字符对应的小写字符。

示例：

import std.unicode.*

main(): Unit {
    println('A'.toLowerCase())
}

运行结果：

func toTitleCase()

public func toTitleCase(): Rune

功能：获取该字符对应的 Unicode 标题大写字符。

返回值：

Rune - 当前字符对应的标题大写字符。

示例：

import std.unicode.*

main(): Unit {
    println('a'.toTitleCase())
}

运行结果：

func toUpperCase()

public func toUpperCase(): Rune

功能：获取该字符对应的 Unicode 大写字符。

返回值：

Rune - 当前字符对应的小写字符。

示例：

import std.unicode.*

main(): Unit {
    println('a'.toUpperCase())
}

运行结果：

extend String <: UnicodeExtension

extend String <: UnicodeExtension

func isBlank()

public func isBlank(): Bool

功能：判断当前字符串是否为空，或仅包含 Unicode 字符集中的空字符。

返回值：

Bool - 如果字符串为空，或仅包含空字符，返回 true，否则返回 false。

示例：

import std.unicode.*

main(): Unit {
    println(" \t\n\r".isBlank())
}

运行结果：

true

func toLower()

public func toLower(): String

功能：将当前字符串中所有 Unicode 字符集范围内的大写字符转化为小写字符。

返回值：

String - 转换后的全小写字符串。

异常：

IllegalArgumentException - 如果字符串中存在无效的 UTF-8 编码，抛出异常。

示例：

import std.unicode.*

main(): Unit {
    println("AbcDEF".toLower())
}

运行结果：

abcdef

func toTitle()

public func toTitle(): String

功能：将当前字符串中 Unicode 字符集范围内可以转换为标题大写字符的转换为标题大写字符。

返回值：

String - 转换后的标题大写字符串。

异常：

IllegalArgumentException - 如果字符串中存在无效的 UTF-8 编码，抛出异常。

示例：

import std.unicode.*

main(): Unit {
    println("AbcDEF".toTitle())
}

运行结果：

ABCDEF

func toUpper()

public func toUpper(): String

功能：将当前字符串中所有 Unicode 字符集范围内的小写字符转化为大写字符。

返回值：

String - 转换后的全大写字符串。

异常：

IllegalArgumentException - 如果字符串中存在无效的 UTF-8 编码，抛出异常。

示例：

import std.unicode.*

main(): Unit {
    println("AbcDEF".toUpper())
}

运行结果：

ABCDEF

func trim()

public func trim(): String

功能：去除原字符串开头结尾以空字符组成的子字符串，空字符定义见 Rune 类型的扩展函数 isWhiteSpace。

返回值：

String - 去除首尾空字符后的字符串。

异常：

IllegalArgumentException - 如果字符串中不存在有效的 UTF-8 编码，抛出异常。

示例：

import std.unicode.*

main(): Unit {
    println("\nx \t ".trim())
}

运行结果：

func trimLeft()

public func trimLeft(): String

功能：去除原字符串开头以空字符组成的子字符串，空字符定义见 Rune 类型的扩展函数 isWhiteSpace。

返回值：

String - 去除开头空字符后的字符串。

异常：

IllegalArgumentException - 如果字符串中不存在有效的 UTF-8 编码，抛出异常。

示例：

import std.unicode.*

main(): Unit {
    println("  x  ".trimLeft())
}

运行结果：

func trimRight()

public func trimRight(): String

功能：去除原字符串结尾以空字符组成的子字符串，空字符定义见 Rune 类型的扩展函数 isWhiteSpace。

返回值：

String - 去除结尾空字符后的字符串。

异常：

IllegalArgumentException - 如果字符串中不存在有效的 UTF-8 编码，抛出异常。

示例：

import std.unicode.*

main(): Unit {
    println("  x  ".trimRight())
}

运行结果：

std.unittest 包

功能介绍

Unittest 库用于编写仓颉项目单元测试代码，提供包括代码编写、运行和调测在内的基本功能，并为有经验的用户提供的一些高级功能。仓颉单元测试支持 cjc 编译器（单包编译模式）和 cjpm 包管理器（多包模式）。

用户可通过快速入门写出第一个单元测试程序。同时文档对于一些基础概念及用法做了说明并附有示例代码，另外，对于一些高阶特性例如参数化测试等做了进一步说明。

API 列表

函数

函数名	功能
csv<T>(String, Rune, Rune, Rune, Option<Rune>, Option<Array<String>>, Array<UInt64>, Array<UInt64>, Bool)	该函数可从 csv 文件中读取类型 T 的数据值，其中 T 必须可被序列化。该函数的返回值是参数化测试的一种参数源。
json<T>(String)	该函数可从 JSON 文件中读取类型 T 的数据值，其中 T 必须可被序列化。该函数的返回值是参数化测试的一种参数源。
random<T>()	该函数生成 T 类型的随机数据，其中 T 必须实现接口 Arbitrary<T> 。该函数的返回值是参数化测试的一种参数源。
tsv<T>(String, Rune, Rune, Option<Rune>, Option<Array<String>>, Array<UInt64>, Array<UInt64>, Bool)	该函数可从 tsv 文件中读取类型 T 的数据值，其中 T 必须可被序列化。该函数的返回值是参数化测试的一种参数源。

接口

接口名	功能
Arbitrary	生成 T 类型随机值的接口。
BenchInputProvider	用于处理性能测试的接口，其中需要在每次性能测试调用之前执行一些代码或者性能测试的输入发生了变化，并且每次都必须从头开始生成。
BenchmarkInputMarker	当我们不知道 `T` 时，该接口能够检测 `BenchInputProvider<T>` 。
DataProvider	DataStrategy 的组件，用于提供测试数据, T 指定提供者提供的数据类型。
DataShrinker	DataStrategy 的组件，用于在测试期间缩减数据，T 指定该收缩器处理的数据类型。
DataStrategy	为参数化测试提供数据的策略，T 指定该策略操作的数据类型。
Generator	生成器生成 T 类型的值。
Measurement	在性能测试过程中可以收集和分析各种数据的接口。性能测试框架使用的特定实例由 `@Configure` 宏的 `measurement` 参数指定。
Shrink	将 T 类型的值缩减到多个“更小”的值。
TestClass	提供创建 TestSuite 的方法。

类

类名	功能
Benchmark	该类提供创建和运行单个性能测试用例的方法。
BenchReport	提供性能用例执行结果报告处理能力。
CartesianProductProcessor	笛卡尔积处理器。
Configuration	存储 `@Configure` 宏生成的 `unittest` 配置数据的对象。`Configuration` 是一个类似 `HashMap` 的类，但它的键不是键和值类型，而是 `String` 类型，和任何给定类型的值。
ConsoleReporter	打印单元测试用例结果或者性能测试用例结果到控制台。
CsvReporter	打印性能测试用例结果数据到 Csv 文件上。
CsvRawReporter	打印性能测试用例结果数据，该数据只有批次的原始测量值，到 Csv 文件上。
CsvStrategy	`DataStrategy` 对 CSV 数据格式的序列化实现。
DataStrategyProcessor	所有 DataStrategy 组件的基类。该类的实例由 @Strategy 宏或成员函数创建。
FlatMapProcessor	对参数数据进行 FlatMap 的处理器。
FlatMapStrategyProcessor	对参数数据进行 FlatMap 的处理器。
InputParameter	入参对象类型。
JsonStrategy	`DataStrategy` 对 JSON 数据格式的序列化实现。
LazyCyclicNode	用于在一个循环中一个接一个地推进类型擦除的内部惰性迭代器。
MapProcessor	对参数数据进行 Map 的处理器。
RandomDataProvider	使用随机数据生成的 DataProvider 接口的实现。
RandomDataShrinker	使用随机数据生成的 DataShrinker 接口的实现。
RandomDataStrategy	使用随机数据生成的 DataStrategy 接口的实现。
Report	打印测试用例结果报告的基类。
SerializableProvider	获取序列化数据 DataProvider 接口的实现。
SimpleProcessor	简单的数据策略处理器。对 DataStrategyProcessor 的一种实现。
TestGroup	提供构建和运行测试组合方法的类。
TestGroupBuilder	提供配置测试组合的方法的构造器。
TestReport	单元测试执行结果报告。
TestSuite	提供构建和执行测试套方法的类。
TestSuiteBuilder	提供配置测试套方法的测试套构造器。
UnitTestCase	提供创建和执行单元测试用例的方法的类。
XmlReporter	打印单元测试用例结果数据到 Xml 文件上。

枚举

枚举名	功能
ExplicitGcType	用于指定 `@Configure` 宏的 `explicitGC` 配置参数。表示 GC 执行的三种不同方式。
TimeoutInfo	指定测试超时的信息。目前，可以通过 `@Timeout[expr]` 宏或者运行时选项 `--timeout-each` 提供此超时信息。
TimeUnit	可以在 `TimeNow` 类构造函数中使用的时间单位。

结构体

结构体名	功能
BatchInputProvider	输入提供程序，在执行之前在缓冲区中生成整个基准批次的输入。
BatchSizeOneInputProvider	基准输入提供程序，在每次执行基准之前生成输入。
GenerateEachInputProvider	基准输入提供程序，在每次执行基准之前生成输入。
ImmutableInputProvider	最简单的输入提供程序，只需为基准测试的每次调用复制数据。适用于基准测试不会改变输入的情况。它在框架内默认使用。
TimeNow	Measurement 的实现，用于测量执行一个函数所花费的时间。

函数

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 ：转义括住元素的符号。默认值为 " （双引号）。
escapeChar!: 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 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 。

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 random<T>() where T <: Arbitrary<T>

public func random<T>(): RandomDataStrategy<T> where T <: Arbitrary<T>

功能：该函数生成 T 类型的随机数据，其中 T 必须实现接口 Arbitrary<T> 。该函数的返回值是参数化测试的一种参数源。

返回值：

Arbitrary<T> - 使用随机数据生成的 RandomDataStrategy 接口的实例。

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

有几种方式可以序列化上述数据：

将数据表示为 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")
    }

将数据表示为 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)
    }

接口

interface Arbitrary

public interface Arbitrary<T> {
    static func arbitrary(random: Random): Generator<T>
}

功能：生成 T 类型随机值的接口。

func arbitrary(Random)

static func arbitrary(random: Random): Generator<T>

功能：获取生成 T 类型随机值生成器。

参数：

random: Random - 随机数。

返回值：

Generator<T> - 生成 T 类型随机值生成器。

extend Bool <: Arbitrary<Bool>

extend Bool <: Arbitrary<Bool>

功能：为 Bool 实现了 Arbitrary<T> 接口。

extend Float16 <: Arbitrary<Float16>

extend Float16 <: Arbitrary<Float16>

功能：为 Float16 实现了 Arbitrary<T> 接口。

extend Float32 <: Arbitrary<Float32>

extend Float32 <: Arbitrary<Float32>

功能：为 Float32 实现了 Arbitrary<T> 接口。

extend Float64 <: Arbitrary<Float64>

extend Float64 <: Arbitrary<Float64>

功能：为 Float64 实现了 Arbitrary<T> 接口。

extend Int16 <: Arbitrary<Int16>

extend Int16 <: Arbitrary<Int16>

功能：为 Int16 实现了 Arbitrary<T> 接口。

extend Int32 <: Arbitrary<Int32>

extend Int32 <: Arbitrary<Int32>

功能：为 Int32 实现了 Arbitrary<T> 接口。

extend Int64 <: Arbitrary<Int64>

extend Int64 <: Arbitrary<Int64>

功能：为 Int64 实现了 Arbitrary<T> 接口。

extend Int8 <: Arbitrary<Int8>

extend Int8 <: Arbitrary<Int8>

功能：为 Int8 实现了 Arbitrary<T> 接口。

extend IntNative <: Arbitrary<IntNative>

extend IntNative <: Arbitrary<IntNative>

功能：为 IntNative 实现了 Arbitrary<T> 接口。

extend Ordering <: Arbitrary<Ordering>

extend Ordering <: Arbitrary<Ordering>

功能：为 Ordering 实现了 Arbitrary<T> 接口。

extend Ordering <: Arbitrary<Ordering>

extend Ordering <: Arbitrary<Ordering>

功能：为 Ordering 实现了 Arbitrary<T> 接口。

extend Rune <: Arbitrary<Rune>

extend Rune <: Arbitrary<Rune>

功能：为 Rune 实现了 Arbitrary<T> 接口。

extend String <: Arbitrary<String>

extend String <: Arbitrary<String>

功能：为 String 实现了 Arbitrary<T> 接口。

extend UInt16 <: Arbitrary<UInt16>

extend UInt16 <: Arbitrary<UInt16>

功能：为 UInt16 实现了 Arbitrary<T> 接口。

extend UInt32 <: Arbitrary<UInt32>

extend UInt32 <: Arbitrary<UInt32>

功能：为 UInt32 实现了 Arbitrary<T> 接口。

extend UInt64 <: Arbitrary<UInt64>

extend UInt64 <: Arbitrary<UInt64>

功能：为 UInt64 实现了 Arbitrary<T> 接口。

extend UInt8 <: Arbitrary<UInt8>

extend UInt8 <: Arbitrary<UInt8>

功能：为 UInt8 实现了 Arbitrary<T> 接口。

extend UIntNative <: Arbitrary<UIntNative>

extend UIntNative <: Arbitrary<UIntNative>

功能：为 UIntNative 实现了 Arbitrary<T> 接口。

extend Unit <: Arbitrary<Unit>

extend Unit <: Arbitrary<Unit>

功能：为 Unit 实现了 Arbitrary<T> 接口。

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> 接口。

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> 接口。

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 BenchmarkInputMarker

public interface BenchmarkInputMarker

功能：当我们不知道 T 时，该接口能够检测 BenchInputProvider<T> 。

interface DataProvider

public interface DataProvider<T> {
    func provide(): Iterable<T>
    prop isInfinite: Bool
}

功能：DataStrategy 的组件，用于提供测试数据，T 指定提供者提供的数据类型。

prop isInfinite

prop isInfinite: Bool

功能：是否无法穷尽。

类型：Bool

func provide()

func provide(): Iterable<T>

功能：获取数据迭代器。

返回值：

Iterable<T> - 数据迭代器。

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 finisher(configuration: Configuration): DataFinisher<T>
    func provider(configuration: Configuration): DataProvider<T>
    func shrinker(configuration: Configuration): DataShrinker<T>
}

功能：为参数化测试提供数据的策略，T 指定该策略操作的数据类型。

func finisher(Configuration)

func finisher(configuration: Configuration): DataFinisher<T>

功能：获取对测试数据进行测试后操作的组件。

参数：

configuration: Configuration - 配置信息。

返回值：

DataFinisher<T> - 对测试数据进行测试后操作测试数据的组件对象。

func provider(Configuration)

func provider(configuration: Configuration): DataProvider<T>

功能：获取提供测试数据组件。

参数：

configuration: Configuration - 配置信息。

返回值：

DataProvider<T> - 提供测试数据的组件对象。

func shrinker(Configuration)

func shrinker(configuration: Configuration): DataShrinker<T>

功能：获取缩减测试数据的组件。

参数：

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 Generator<T>

public interface Generator<T> {
    func next(): T
}

功能：生成器生成 T 类型的值。

func next()

func next(): T

功能：获取生成出来的 T 类型的值。

返回值：

T - 生成的 T 类型的值。

interface Measurement

public interface Measurement {
    func measure(f: () -> Unit): Float64
    func toString(f: Float64): String
}

功能：在性能测试过程中可以收集和分析各种数据的接口。性能测试框架使用的特定实例由 @Configure 宏的 measurement 参数指定。

func measure(() -> Unit)

func measure(f: () -> Unit): Float64

功能：返回将用于统计分析的测量数据的表示。

参数：

f: () -> Unit - 是一个 lambda，应该测量它的执行信息。

返回值：

Float64 - 测量得到的数据。

func toString(Float64)

func toString(f: Float64): String

功能：将测量数据的浮点表示转换为将在性能测试输出中使用的字符串。

参数：

f: Float64 - 测量数据的浮点表示。

返回值：

String - 按规则转换后的字符串。

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> 接口。

extend Float16 <: Shrink<Float16>

extend Float16 <: Shrink<Float16>

功能：为 Float16 实现了 Shrink<T> 接口。

extend Float32 <: Shrink<Float32>

extend Float32 <: Shrink<Float32>

功能：为 Float32 实现了 Shrink<T> 接口。

extend Float64 <: Shrink<Float64>

extend Float64 <: Shrink<Float64>

功能：为 Float64 实现了 Shrink<T> 接口。

extend Int16 <: Shrink<Int16>

extend Int16 <: Shrink<Int16>

功能：为 Int16 实现了 Shrink<T> 接口。

extend Int32 <: Shrink<Int32>

extend Int32 <: Shrink<Int32>

功能：为 Int32 实现了 Shrink<T> 接口。

extend Int64 <: Shrink<Int64>

extend Int64 <: Shrink<Int64>

功能：为 Int64 实现了 Shrink<T> 接口。

extend Int8 <: Shrink<Int8>

extend Int8 <: Shrink<Int8>

功能：为 Int8 实现了 Shrink<T> 接口。

extend IntNative <: Shrink<IntNative>

extend IntNative <: Shrink<IntNative>

功能：为 IntNative 实现了 Shrink<T> 接口。

extend Ordering <: Shrink<Ordering>

extend Ordering <: Shrink<Ordering>

功能：为 Ordering 实现了 Shrink<T> 接口。

extend Rune <: Shrink<Rune>

extend Rune <: Shrink<Rune>

功能：为 Rune 实现了 Shrink<T> 接口。

extend String <: Shrink<String>

extend String <: Shrink<String>

功能：为 String 实现了 Shrink<T> 接口。

extend UInt16 <: Shrink<UInt16>

extend UInt16 <: Shrink<UInt16>

功能：为 UInt16 实现了 Shrink<T> 接口。

extend UInt32 <: Shrink<UInt32>

extend UInt32 <: Shrink<UInt32>

功能：为 UInt32 实现了 Shrink<T> 接口。

extend UInt64 <: Shrink<UInt64>

extend UInt64 <: Shrink<UInt64>

功能：为 UInt64 实现了 Shrink<T> 接口。

extend UInt8 <: Shrink<UInt8>

extend UInt8 <: Shrink<UInt8>

功能：为 UInt8 实现了 Shrink<T> 接口。

extend UIntNative <: Shrink<UIntNative>

extend UIntNative <: Shrink<UIntNative>

功能：为 UIntNative 实现了 Shrink<T> 接口。

extend Unit <: Shrink<Unit>

extend Unit <: Shrink<Unit>

功能：为 Unit 实现了 Shrink<T> 接口。

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> 接口。

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> 接口。

interface TestClass

public interface TestClass {
    func asTestSuite(): TestSuite
}

功能：提供创建 TestSuite 的方法。

func asTestSuite()

func asTestSuite(): TestSuite

功能：创建 TestSuite 的方法。

返回值：

TestSuite - 测试套对象。

类

class Benchmark

public class Benchmark {}

功能：该类提供创建和运行单个性能测试用例的方法。

func run()

public func run(): BenchReport

功能：运行该性能用例。

返回值：

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 - 用例执行体。

返回值：

Benchmark - 性能测试用例对象。

static func createParameterized<T>(String, DataStrategy<T>, Configuration, (T) -> Unit)

static func createParameterized<T>(name: String, strategy: DataStrategy<T>, configuration!: Configuration = Configuration(), body!: (T) -> Unit): Benchmark

功能：创建一个参数化的性能测试用例对象。

参数：

name : String - 用例名称。
strategy : DataStrategy - 参数数据策略。
configuration : Configuration - 用例配置信息。
body : () -> Unit - 用例执行体。

返回值：

Benchmark - 性能测试用例对象。

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

功能：创建一个参数化的性能测试用例对象。

参数：

name : String - 用例名称。
strategy : DataStrategyProcessor - 参数数据处理器。
configuration : Configuration - 用例配置信息。
body : () -> Unit - 用例执行体。

返回值：

Benchmark - 性能测试用例对象。

prop name

public prop name: String

功能：获取用例名称。

类型：String

class BenchReport

public class BenchReport <: Report {}

功能：提供性能用例执行结果报告处理能力。

func reportTo<T>(Reporter<BenchReport, T>)

public func reportTo<T>(reporter: Reporter<BenchReport, T>): T

功能：打印性能用例结果报告。

参数：

reporter : Reporter<BenchReport, 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>)

功能：构造函数

参数：

left : DataStrategyProcessor - 数据策略处理器
right : DataStrategyProcessor - 数据策略处理器

class Configuration

public class Configuration <: ToString {
    public init()
}

功能：存储 @Configure 宏生成的 unittest 配置数据的对象。Configuration 是一个类似 HashMap 的类，但它的键不是键和值类型，而是 String 类型，和任何给定类型的值。

init()

public init()

功能：构造一个空的实例。

func clone()

public func clone(): Configuration

功能：拷贝一份对象。

返回值：

Configuration - 拷贝的对象。

func get<T>(String)

public func get<T>(key: String): ?T

功能：获取 key 对应的值。

T 为泛型参数，用于在对象中查找对应类型的值。

参数：

key: String - 键名称。

返回值：

?T - 未找到时返回 None，找到对应类型及名称的值时返回 Some<T>(v) 。

func remove<T>(String)

public func remove<T>(key: String): ?T

功能：删除对应键名称和类型的值。

参数：

key: String - 键名称。

返回值：

?T - 当存在该值时返回该值，当不存在时返回 None。

func set<T>(String, T)

public func set<T>(key: String, value: T): Unit

功能：给对应键名称和类型设置值。

参数：

key: String - 键名称。
value: T - 键值。

func toString()

public func toString(): String

功能：该对象的字符化对象，当内部对象未实现 ToString 接口时，输出 '<not printable>' 。

返回值：

String - 字符串。

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

功能：生成序列化数据迭代器。

参数：

configuration: Configuration - 数据配置信息。

返回值：

SerializableProvider<T> - 序列化迭代器对象。

class DataStrategyProcessor

abstract sealed class DataStrategyProcessor<T> {}

功能：所有 DataStrategy 组件的基类。该类的实例由 @Strategy 宏或成员函数创建。

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 - 性能测试用例执行体。

返回值：

Benchmark - 性能测试用例对象。

func intoUnitTestCase(String, Configuration, (T) -> Unit)

public func intoUnitTestCase(
    caseName!: String,
    configuration!: Configuration,
    doRun!: (T) -> Unit
): UnitTestCase

功能：宏生成的代码使用的辅助函数。用于创建使用该策略的测试用例。

参数：

caseName : String - 用例名称。
configuration : Configuration - 配置信息。
doRun : (T) -> Unit - 性能测试用例执行体。

返回值：

UnitTestCase - 测试用例对象。

func map<R>((T) -> R)

public func map<R>(f: (T) -> R): MapProcessor<T, R>

功能：简单地将 f 应用于原始数据策略的每个项目。 Shrink 也会发生在原始输入上，然后进行映射。

参数：

f: (T) -> R - 需要增加的处理逻辑函数。

返回值：

MapProcessor<T, R> - 应用 f 后的处理器。

func mapWithConfig<R>((T, Configuration) -> R)

public func mapWithConfig<R>(f: (T, Configuration) -> R): MapProcessor<T, R>

功能：可以访问当前的 Configuration ，只需将 f 应用于原始数据策略的每个项目。 Shrink 也会发生在原始输入上，然后进行映射。

参数：

f: (T, Configuration) -> R - 需要增加的处理逻辑函数。

返回值：

MapProcessor<T, R> - 应用 f 后的处理器。

func flatMap<R>((T) -> DataProvider)

public func flatMap<R>(f: (T) -> DataProvider<R>): FlatMapProcessor<T, R>

功能：简单地将 f 应用于原始数据策略的每个项目，然后展平结果。 Shrink 也会发生在原始输入上，然后进行 flatMap 。

参数：

f: (T) -> DataProvider - 需要增加的处理逻辑函数。

返回值：

FlatMapProcessor<T, R> - 应用 f 后的处理器。

func flatMapStrategy((T) -> DataStrategy<R>)

public func flatMapStrategy<R>(f: (T) -> DataStrategy<R>): FlatMapStrategyProcessor<T, R>

功能：简单地将 f 应用于原始数据策略的每个项目，然后展平结果。 Shrink 是通过返回的策略而不是原始输入来完成的。

参数：

f: (T) -> DataStrategy - 需要增加的处理逻辑函数。

返回值：

FlatMapStrategyProcessor<T, R> - 应用 f 后的处理器。

func product(DataStrategyProcessor<R>)

public func product<R>(p: DataStrategyProcessor<R>): CartesianProductProcessor<T, R>

功能：笛卡尔积组合器创建包含原始策略中元素的所有可能排列的数据策略。对于无限策略，它首先迭代所有有限的子策略，然后才推进无限的子策略。 Shrink 独立且统一地发生在原始策略的每个元素上。

参数：

p: DataStrategyProcessor - 数据策略处理器。

返回值：

CartesianProductProcessor<T, R> - 笛卡尔积处理器。

static func start(DataStrategy<T>, String)

public static func start(s: DataStrategy<T>, name: String): SimpleProcessor<T>

功能：DataStrategy 的组合和映射的起点。

参数：

s: DataStrategy - 数据策略。
name: String - 用例名称。

返回值：

SimpleProcessor - 测试用例处理器。

static func start(() -> DataStrategy, String)

public static func start<U>(f: () -> DataStrategy<U>, name: String): DataStrategyProcessor<U>

功能：DataStrategy 的组合和映射的起点。

参数：

s: () -> DataStrategy - 生成数据策略的闭包。
name: String - 用例名称。

返回值：

DataStrategyProcessor - 数据策略处理器。

static func start(() -> DataStrategy<T>, String, Int64)

public static func start(f: () -> DataStrategy<T>, name: String, x!: Int64 = 0): SimpleProcessor<T>

功能：DataStrategy 的组合和映射的起点。

参数：

s: () -> DataStrategy - 生成数据策略的闭包。
name: String - 用例名称。
x: Int64 - 为实现不同返回值的重构增加的参数。

返回值：

SimpleProcessor - 测试用例处理器。

static func start(() -> DataStrategyProcessor<T>, String)

public static func start(f: () -> DataStrategyProcessor<T>, name: String): DataStrategyProcessor<T>

功能：DataStrategy 的组合和映射的起点。

参数：

s: () -> DataStrategyProcessor - 生成数据策略处理器的闭包。
name: String - 用例名称。

返回值：

DataStrategyProcessor - 数据策略处理器。

static func start(() -> DataStrategyProcessor, String, Int64)

public static func start<U>(f: () -> DataStrategyProcessor<U>, name: String, x!: Int64 = 0):
    DataStrategyProcessor<U> where U <: BenchInputProvider<T>

功能：DataStrategy 的组合和映射的起点。

参数：

s: () -> DataStrategyProcessor - 生成数据策略处理器的闭包。

name: String - 用例名称。

x: Int64 - 为实现不同返回值的重构增加的参数。

返回值：

DataStrategyProcessor where U <: BenchInputProvider - 数据策略处理器。

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>

功能：生成序列化数据迭代器。

参数：

configuration: Configuration - 数据配置信息。

返回值：

SerializableProvider<T> - 序列化迭代器对象。

class LazyCyclicNode

public open class LazyCyclicNode {}

功能：用于在一个循环中一个接一个地推进类型擦除的内部惰性迭代器。

class MapProcessor

public class MapProcessor<T,R> <: DataStrategyProcessor<R> {}

功能：对参数数据进行 Map 的处理器。

class RandomDataProvider

public class RandomDataProvider<T> <: DataProvider<T> where T <: Arbitrary<T> {
    public init(configuration:Configuration)
}

功能：使用随机数据生成的 DataProvider 接口的实现。

prop isInfinite

public override prop isInfinite: Bool

功能：是否生成无限的数据。

类型：Bool

init(Configuration)

public init(configuration: Configuration)

功能：构造一个随机数据提供者的对象。

参数：

configuration: Configuration - 配置对象，必须包含一个随机生成器，名称为 random ，类型为 random.Random。

异常：

IllegalArgumentException - 当 configuration 不包含 random 实例时，抛出异常。

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>

功能：获取随机数据的提供者。

参数：

configuration: Configuration - 参数配置信息。

返回值：

RandomDataProvider - 随机数提供者。

func shrinker(Configuration)

public override func shrinker(_: Configuration): RandomDataShrinker<T>

功能：获取随机数据的缩减器。

参数：

_: Configuration - 参数配置信息。

返回值：

RandomDataShrinker - 随机数据的缩减器。

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 SerializableProvider

public class SerializableProvider<T> <: DataProvider<T> where T <: Serializable<T> {}

功能：获取序列化数据 DataProvider 接口的实现。

func provide()

public override func provide(): Iterable<T>

功能：获取数据迭代器。

返回值：

Iterable<T> - 数据迭代器。

prop isInfinite

public prop isInfinite: Bool

功能：是否生成无限的数据。

类型：Bool

class SimpleProcessor

public class SimpleProcessor<T> <: DataStrategyProcessor<T> {}

功能：简单的数据策略处理器。对 DataStrategyProcessor 的一种实现。

init(() -> DataStrategy<T>, String)

功能：构造函数。

参数：

buildDelegate : () -> DataStrategy - 生成数据策略的闭包。
name : String - 处理器名称。

class TestGroup

public class TestGroup {}

功能：提供构建和运行测试组合方法的类。

func runBenchmarks()

public func runBenchmarks(): BenchReport

功能：运行所有性能测试用例。

返回值：

BenchReport - 性能测试用例报告。

func runBenchmarks(Configuration)

public func runBenchmarks(Configuration): BenchReport

功能：带运行配置得执行所有性能测试用例。

参数：

configuration: Configuration - 运行配置。

返回值：

BenchReport - 性能测试用例报告。

func runTests()

public func runTests(): TestReport

功能：执行所有单元测试用例。

返回值：

TestReport - 单元测试用例报告。

func runTests(Configuration)

public func runTests(configuration: Configuration): TestReport

功能：带运行配置得执行所有单元测试用例。

参数：

configuration: Configuration - 运行配置。

返回值：

TestReport - 单元测试用例报告。

static func builder(String)

public static func builder(name: String): TestGroupBuilder

功能：创建测试组合构造器。

参数：

name : String - 测试组合名称。

返回值：

TestGroupBuilder - 测试组合构造器。

static func builder(TestGroup)

public static func builder(group: TestGroup): TestGroupBuilder

功能：创建测试组合构造器。

参数：

group : TestGroup - 测试组合。

返回值：

TestGroupBuilder - 测试组合构造器。

prop name

public prop name: String

功能：获取测试组合名称。

类型：String

class TestGroupBuilder

public class TestGroupBuilder {}

功能：提供配置测试组合的方法的构造器。

func add(Benchmark)

public func add(benchmark: Benchmark): TestGroupBuilder

功能：为测试组合增加性能测试用例。

参数：

benchmark : Benchmark - 性能测试用例。

返回值：

TestGroupBuilder - 测试组合构造器。

func add(TestSuite)

public func add(suite: TestSuite): TestGroupBuilder

功能：为测试组合增加单元测试套。

参数：

suite : TestSuite - 单元测试套。

返回值：

TestGroupBuilder - 测试组合构造器。

func add(UnitTestCase)

public func add(test: UnitTestCase): TestGroupBuilder

功能：为测试组合增加单元测试用例。

参数：

test : UnitTestCase - 单元测试用例。

返回值：

TestGroupBuilder - 测试组合构造器。

func build()

public func build(): TestGroup

功能：配置完成后，构建测试组合对象。

返回值：

TestGroup - 测试组合。

func configure(Configuration)

public func configure(configuration: Configuration): TestGroupBuilder

功能：为测试组合配置配置信息。

参数：

configuration : Configuration - 配置信息。

返回值：

TestGroupBuilder - 测试组合构造器。

func setName(String)

public func setName(name: String): TestGroupBuilder

功能：为测试组合设置名称。

参数：

name : String - 名称。

返回值：

TestGroupBuilder - 测试组合构造器。

class TestReport

public class TestReport <: Report {}

功能：单元测试执行结果报告。

func reportTo<T>(Reporter<TestReport, T>)

public func reportTo<T>(reporter: Reporter<TestReport, T>): T

功能：打印单元测试执行报告。

参数：

reporter : Reporter<TestReport, T> - 单元测试报告打印器。

返回值：

T : 打印返回值，一般为 Unit 。

class TestSuite

public class TestSuite {}

功能：提供构建和执行测试套方法的类。

func runBenchmarks()

public func runBenchmarks(): BenchReport

功能：运行所有性能测试用例。

返回值：

BenchReport - 性能测试运行结果。

func runBenchmarks(Configuration)

public func runBenchmarks(configuration: Configuration): BenchReport

功能：带配置信息得运行所有性能测试用例。

参数：

configuration : Configuration - 运行配置信息。

返回值：

BenchReport - 性能测试用例运行结果。

func runTests()

public func runTests(): TestReport

功能：运行测试套。

返回值：

TestReport - 测试套运行结果。

func runTests(Configuration)

public func runTests(configuration: Configuration): TestReport

功能：带配置信息得运行测试套。

参数：

configuration : Configuration - 运行配置信息。

返回值：

TestReport - 测试套运行结果。

static func builder(String)

public static func builder(name: String): TestSuiteBuilder

功能：创建测试套构建器。

参数：

name : String - 测试套名称。

返回值：

TestSuiteBuilder - 测试套构造器。

static func builder(TestSuite)

public static func builder(suite: TestSuite): TestSuiteBuilder

功能：创建测试套构建器。

参数：

suite : TestSuite - 测试套。

返回值：

TestSuiteBuilder - 测试套构造器。

prop name

public prop name: String

功能：获取测试套名称。

类型：String

class TestSuiteBuilder

public class TestSuiteBuilder {}

功能：提供配置测试套方法的测试套构造器。

add(Benchmark)

public func add(benchmark: Benchmark): TestSuiteBuilder

功能：为测试套添加性能用例。

参数：

benchmark : Benchmark - 性能测试用例。

返回值：

TestGroupBuilder - 测试组合构造器。

add(UnitTestCase)

public func add(test: UnitTestCase): TestSuiteBuilder

功能：为测试套添加单元测试用例。

参数：

test : UnitTestCase - 单元测试用例。

返回值：

TestGroupBuilder - 测试组合构造器。

afterAll(() -> Unit)

public func afterAll(body: () -> Unit): TestSuiteBuilder

功能：为测试套添加在所有用例执行完成后执行的生命周期管理闭包。

参数：

body : () -> Unit - 执行体。

返回值：

TestGroupBuilder - 测试组合构造器。

afterEach(() -> Unit)

public func afterEach(body: () -> Unit): TestSuiteBuilder

功能：为测试套添加在每个用例执行完成后执行的生命周期管理闭包。

参数：

body : () -> Unit - 执行体。

返回值：

TestGroupBuilder - 测试组合构造器。

afterEach((String) -> Unit)

public func afterEach(body: (String) -> Unit): TestSuiteBuilder

功能：为测试套添加在每个用例执行完成后执行的生命周期管理闭包。

参数：

body : (String) -> Unit - 执行体。

返回值：

TestGroupBuilder - 测试组合构造器。

beforeAll(() -> Unit)

public func beforeAll(body: () -> Unit): TestSuiteBuilder

功能：为测试套添加在所有用例执行前执行的生命周期管理闭包。

参数：

body : () -> Unit - 执行体。

返回值：

TestGroupBuilder - 测试组合构造器。

beforeEach(() -> Unit)

public func beforeEach(body: () -> Unit): TestSuiteBuilder

功能：为测试套添加在每个用例执行前执行的生命周期管理闭包。

参数：

body : () -> Unit - 执行体。

返回值：

TestGroupBuilder - 测试组合构造器。

beforeEach((String) -> Unit)

public func beforeEach(body: (String) -> Unit): TestSuiteBuilder

功能：为测试套添加在每个用例执行前执行的生命周期管理闭包。

参数：

body : (String) -> Unit - 执行体。

返回值：

TestGroupBuilder - 测试组合构造器。

build()

public func build(): TestSuite

功能：配置完成后构造测试套。

返回值：

TestSuite - 测试套。

configure(Configuration)

public func configure(configuration: Configuration): TestSuiteBuilder

功能：为测试套添加配置信息。

参数：

configuration : Configuration - 测试配置信息。

返回值：

TestGroupBuilder - 测试组合构造器。

setName(String)

public func setName(name: String): TestSuiteBuilder

功能：为测试套设置名称。

参数：

name : String - 测试套名称。

返回值：

TestGroupBuilder - 测试组合构造器。

class UnitTestCase

public class UnitTestCase {}

功能：提供创建和执行单元测试用例的方法的类。

func run()

public func run(): TestReport

功能：运行单元测试用例。

返回值：

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 - 用例执行体。

返回值：

UnitTestCase - 单元测试用例对象。

static func createParameterized<T>(String, DataStrategy<T>, Configuration, (T) -> Unit)

static func createParameterized<T>(name: String, strategy: DataStrategy<T>, configuration!: Configuration = Configuration(), body!: (T) -> Unit): UnitTestCase

功能：创建参数化的单元测试用例。

参数：

name : String - 用例名称。
strategy : DataStrategy - 参数数据策略。
configuration : Configuration - 用例配置信息。
body : () -> Unit - 用例执行体。

返回值：

UnitTestCase - 单元测试用例对象。

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

功能：创建参数化的单元测试用例。

参数：

name : String - 用例名称。
strategy : DataStrategyProcessor - 参数数据处理器。
configuration : Configuration - 用例配置信息。
body : () -> Unit - 用例执行体。

返回值：

UnitTestCase - 单元测试用例对象。

prop name

public prop name: String

功能：获取单元测试名称。

类型：String

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{
    Disabled |
    Heavy |
    Light
}

功能：用于指定 @Configure 宏的 explicitGC 配置参数。表示 GC 执行的三种不同方式。

Disabled

Disabled

功能: GC 不会被框架显式调用。

Heavy

Heavy

功能：std.runtime.GC(heavy: true) 将在性能测试执行期间由框架显式调用。

Light

Light

功能：std.runtime.GC(heavy: false) 将在 Benchmark 函数执行期间由框架显式调用。这是默认设置。

enum TimeUnit

public enum TimeUnit {
    | Micros
    | Millis
    | Nanos
    | Seconds
}

功能：可以在 TimeNow 类构造函数中使用的时间单位。

Micros

Micros

功能: 单位为微秒。

Millis

Millis

功能: 单位为毫秒。

Nanos

Nanos

功能: 单位为纳秒。

Seconds

Seconds

功能: 单位为秒。

enum TimeoutInfo

public enum TimeoutInfo {
    | NoTimeout
    | Timeout(Duration)
}

功能：指定测试超时的信息。目前，可以通过 @Timeout[expr] 宏或者运行时选项 --timeout-each 提供此超时信息。

NoTimeout

NoTimeout

功能：没有提供超时信息。

Timeout(Duration)

Timeout(Duration)

功能：指定超时时间。

static func fromDefaultConfiguration()

public static func fromDefaultConfiguration(): TimeoutInfo

功能：返回测试过程的控制台输入参数中提供的超时信息。

返回值：

TimeoutInfo - 超时信息。

func applyDefault(TimeoutInfo)

public func applyDefault(default: TimeoutInfo): TimeoutInfo

功能：返回根据默认值更新的超时信息。

参数：

default: TimeoutInfo - 来自于控制台输入参数或测试类上的超时信息，作为默认值。

返回值：

TimeoutInfo - 超时信息。

结构体

struct BatchInputProvider

public struct BatchInputProvider<T> <: BenchInputProvider<T> {
    public init(builder: () -> T)
}

功能：输入提供程序，在执行之前在缓冲区中生成整个基准批次的输入。

func init(() -> T)

public init(builder: () -> T)

功能：默认构造函数。

参数：

builder: () -> T - 用于生成基准测试输入的闭包。

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 - 最大值。

struct BatchSizeOneInputProvider

public struct BatchSizeOneInputProvider<T> <: BenchInputProvider<T>{
    public init(builder: () -> T)
}

功能：基准输入提供程序，在每次执行基准之前生成输入。与 GenerateEachInputProvider 的区别在于，当批量大小为 1 时，我们可以测量。每个基准测试调用都是独立的，因此输入生成永远不会包含在测量中。如果 GenerateEachInputProvider 给出的结果质量较差，则应使用。这种情况可能会发生，因为生成输入所需的时间比实际基准要多得多，或者如果输入生成的执行时间非常不稳定。

func init(() -> T)

public init(builder: () -> T)

功能：默认构造函数。

参数：

builder: () -> T - 用于生成基准测试输入的 lambda

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 - 最大值。

struct GenerateEachInputProvider

public struct GenerateEachInputProvider<T> <: BenchInputProvider<T>{
    public init(builder: () -> T)
}

功能：基准输入提供程序，在每次执行基准之前生成输入。生成时间包含在基准测量中，然后作为框架开销计算的一部分从最终结果中排除。

func init(() -> T)

public init(builder: () -> T)

功能：默认构造函数。

参数：

builder: () -> T - 用于生成基准测试输入的闭包。

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 - 最大值。

struct ImmutableInputProvider

public struct ImmutableInputProvider<T> <: BenchInputProvider<T> {
    public int(data: T)
}

功能：最简单的输入提供程序，只需为基准测试的每次调用复制数据。适用于基准测试不会改变输入的情况。它在框架内默认使用。

func init(T)

public init(data: T)

功能：默认构造函数。

参数：

data: T - 基准测试的输入

mut func get(Int64)

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 - 输入提供器

static func createOrExisting(U): U where U <: BenchInputProvider

public static func createOrExisting<U>(arg: U): U where U <: BenchInputProvider<T>

功能：创建或获取一个 BenchInputProvider 的子类型对象。

参数：

arg : T - 提供器需复制的参数。

返回值：

U where U <: BenchInputProvider - 输入提供器

struct TimeNow

public struct TimeNow <: Measurement {
    public init()
    public init(unit: ?TimeUnit)
}

功能：Measurement 的实现，用于测量执行一个函数所花费的时间。

init()

public init()

功能：自动选择输出格式的默认构造函数。

init(?TimeUnit)

public init(unit: ?TimeUnit)

功能： unit 参数用于指定打印结果时将使用的时间单位。

参数：

unit: ?TimeUnit - 指定的时间单位。

func measure(() -> Unit)

public func measure(f: () -> Unit): Float64

功能：计算将用于统计分析的测量数据。

参数：

f: () -> Unit - 被计算时间的执行体。

返回值：

Float64 - 计算得到的数据，用于统计分析。

func toString(Float64)

public func toString(duration: Float64): String

功能：按时间单位打印传入的时间值。

参数：

duration: Float64 - 需要被打印的时间数值。

返回值：

String - 按指定单位输出的时间数字字符串。

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 宏标记。每个测试用例都是测试类内部的一个函数。上一节中的示例，相同的测试可以改写为如下所示的测试类：

@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 。创建一个错误的测试来说明两者的区别：

@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 不会有什么变化。添加一个检查项后，再次运行：

@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 ：

@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) 的两个参数 a 和 b ，检查他们的参数值是否相等；假设 a 的类型为 A ， b 的类型为 B ， A 必须实现了 Equatable 。
布尔断言 @Assert(c) 或 @Expect(c) ，其参数 c 为 Bool 类型，参数值 true 或 false 。

断言的第二种形式 @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 或类似宏的函数上。

如果多个函数被标记为相同的生命周期步骤，则可以按照它们在代码中声明的顺序（从上到下）执行。

测试框架确保：

标记为 Before all 的步骤在所有测试用例运行之前，至少运行一次。
对于测试类中的每个测试用例 TC ： 1）标记为 Before each 的步骤在 TC 之前运行一次。 2）运行 TC 。 3）标记为 After each 的步骤在 TC 之后运行一次。
在测试类中的所有测试用例之后运行标记为 After all 的步骤。

注意：

如果没有运行测试用例，上述并不适用。

简单场景中，标识为 before all 和 after 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 each 或 after each 的步骤仅在执行测试用例或基准之前或之后为其所有参数执行一次。也就是说，从生命周期的角度看，使用不同参数执行多次的测试主体会被视为单个测试用例。

如果参数化测试的每个参数都需要单独创建清理，需要将相应的代码配置在测试用例主体本身中。此外，还可以访问参数本身。

测试配置

单元测试框架中其他更高级的功能可能需要额外配置。参考如下三种方式配置测试：

使用 @Configure 宏
直接在运行测试时或在 cjpm test 测试中使用命令行参数
使用 cjpm 配置文件

运行配置

使用方法

运行 cjc 编译的可执行文件 test ，添加参数选项

./test --bench --filter MyTest.*Test,-stringTest

`--bench`

默认情况下，只有被 @TestCase 修饰的函数会被执行。在使用 --bench 的情况下只执行 @Bench 宏修饰的用例。

`--filter`

如果您希望以测试类和测试用例过滤出测试的子集，可以使用 --filter=测试类名.测试用例名 的形式来筛选匹配的用例，例如：

--filter=* 匹配所有测试类
--filter=*.* 匹配所有测试类所有测试用例(结果和*相同)
--filter=*.*Test,*.*case* 匹配所有测试类中以 Test 结尾的用例，或者所有测试类中名字中带有 case 的测试用例
--filter=MyTest*.*Test,*.*case*,-*.*myTest 匹配所有 MyTest 开头测试类中以 Test 结尾的用例，或者名字中带有 case的用例，或者名字中不带有 myTest 的测试用例

另外，--filter 后有 = 和无 = 均支持。

`--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> 可为 true 或 false ，指定为 true 时，测试类可被并行运行，并行进程个数将受运行系统上的CPU核数控制。另外，--parallel 可省略 =true 。
--parallel=nCores 指定了并行的测试进程个数应该等于可用的 CPU 核数。
--parallel=NUMBER 指定了并行的测试进程个数值。该数值应该为正整数。
--parallel=NUMBERnCores 指定了并行的测试进程个数值为可用的 CPU 核数的指定数值倍。该数值应该为正数（支持浮点数或整数）。

`--option=value`

以 --option=value 形式提供的任何非上述的选项均按以下规则处理并转换为配置参数（类似于 @Configure 宏处理的参数），并按顺序应用：

option 与 value 为任意自定义的运行配置选项键值对，option 可以为任意通过 - 连接的英文字符，转换到 @Configure 时将转换为小驼峰格式。value 的格式规则如下：

注：当前未检查 option 与 value 的合法性，并且选项的优先级低于代码中 @Configure 的优先级。

如果省略 =value 部分，则该选项被视为 Bool 值 true , 例如：--no-color 生成配置条目 noColor = true 。
如果 value 严格为 true 或 false ，则该选项被视为具有相应含义的 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

参数化测试

参数化测试入门

仓颉 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, item: 0)
    let expected = Array(size, item: 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, item: item)
    let expected = Array(size, item: item)
    sort(arr)
    @Expect(expected, arr)
}

注意，item 的取值范围为 -1..20 ，不是一个数组。那么，运行这个测试，结果会如何？参数 size 和 item 的取值会进行组合再测试和返回结果。因此，测试函数时，不要配置过多参数；否则组合数量过大，导致测试变慢。上述例子中，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 接口，否则将只打印占位符。
以及前面提到的随机种子，用于重现随机测试。

有些测试比较棘手，需要调整随机生成的步骤数。可以通过如下两个配置项控制：generationSteps 和 reductionSteps 。随机测试一个最大的优点是，只要设置了足够多的步骤，它可以运行很长时间，这样就可以检查数百万个值。

为了不使测试太耗时，默认 generationSteps 和 reductionSteps 的最大值都是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 宏设置测试，这样就可以运行测试 Int64、 Float64 和 String 这些类型了。

@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)
}

动态测试

动态测试入门

仓颉测试框架支持动态测试，其支持在存在编译期未知的测试数据时构造测试用例。关键场景如下：

创建基于外部数据的测试套。
创建基于参数或配置文件的测试套。

通过与普通测试用例对比，可以看到如何通过 @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 包中其他的宏组合。

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`, 这个对象默认情况下，所有的成员函数、属性或运算符重载函数没有任何具体实现。
spy<T>(T)	创建类型 T 的 `spy object` ( `mock object` 的扩展，对象的成员拥有默认实现的“骨架”对象)。这个对象包装了所传入的对象，并且默认情况下成员函数、属性或运算符重载函数实现为对这个传入的实例对象的对应成员函数、属性或运算符重载函数的调用。

接口

接口名	功能
ActionSelector<R>	此接口提供了为成员函数指定一个操作 API ，并允许链式调用。
CardinalitySelector<R>	此接口提供了可定义桩签名的最近一次行为的执行次数的 API 。
ContinuationSelector<R>	此接口提供了可继续定义桩签名的行为的 API 。
ValueListener<T>	此接口提供了多个成员函数以支持“监听”传入给桩签名的参数。

类

类名	功能
Matchers	该类提供生成匹配器的静态函数。匹配器对象仅可通过此处的静态函数生成。匹配器可在桩链中使用。
OrderedVerifier	此类型用于收集 “验证语句”, 可在 ordered 函数中动态传入验证行为。
UnorderedVerifier	此类型用于收集 “验证语句”, 可在 unordered 函数中动态传入验证行为。
Verify	`Verify` 提供了一系列静态方法来支持定义所需验证的动作，如 `that` 、 `ordered` 以及 `unorder` 。
VerifyStatement	此类型表示对“桩签名”在验证范围内的单个验证验证语句（即上文中的“验证语句”），提供了成员函数指定“桩签名”的执行次数。

枚举

枚举名	功能
Exhaustiveness	此枚举类型用于指定 `unordered` 函数的验证模式，包含两种模式。

宏

宏名	功能
Called	创建一个验证语句。
On	使用配置 API定义 mock/spy 对象成员的行为（或重新定义 spy 对象）。

函数

func mock<T>()

public func mock<T>(): T

功能：创建类型 T 的 mock object, 这个对象默认情况下，所有的成员函数、属性或运算符重载函数没有任何具体实现。可以通过 @On 指定这个对象的成员函数、属性或运算符重载函数的行为。

返回值：

T - 类型 T 的 mock object 。

func spy<T>(T)

public func spy<T>(objectToSpyOn: T): T

功能：创建类型 T 的 spy object ( mock object 的扩展，对象的成员拥有默认实现的“骨架”对象)。这个对象包装了所传入的对象，并且默认情况下成员函数、属性或运算符重载函数实现为对这个传入的实例对象的对应成员函数、属性或运算符重载函数的调用。可以通过 @On 重载这个对象的成员函数、属性或运算符重载函数的行为。

参数：

objectToSpyOn: T - 传入实例对象，默认情况下，使用该对象的实现。

返回值：

T - 类型 T 的 spy object 。

接口

interface ActionSelector<R>

public interface ActionSelector<R> {
    func returns(value: R): CardinalitySelector<R>
    func returns(valueFactory: () -> R): CardinalitySelector<R>
    func returnsConsecutively(values: Array<R>): Continuation<R>
    func returnsConsecutively(values: ArrayList<R>): Continuation<R>
    func throws(exception: Exception): CardinalitySelector<R>
    func throws(exceptionFactory: () -> Exception): CardinalitySelector<R>
    func fails(): Unit
    func callsOriginal(): CardinalitySelector<R>
}

功能：此接口提供了为成员函数指定一个操作 API ，并允许链式调用。入参为 mock object 或 spy object 的某个成员函数的调用表达式的 @On 宏调用表达式，将返回 ActionSelector<R> 的实例（其中 R 代表正在配置的函数成员的返回值类型）。即，此接口中的 API 可为成员函数插入桩代码。

func callsOriginal()

func callsOriginal(): CardinalitySelector<R>

功能：定义桩签名执行原始代码逻辑的行为。

返回值：

CardinalitySelector<R> - 定义了桩签名执行原始代码逻辑的 CardinalitySelector<R> 对象实例。

func fails()

func fails(): Unit

功能：定义桩签名抛出 AssertionException 异常的行为。

说明：

throws vs fails

throws 意味着测试桩签名抛出异常后的行为是测试的目的。例如，当某些服务不可用时，系统是否可以正确恢复等。 fails 意味着调用桩签名将导致测试失败。即，如果系统行为正确，则永远不应调用该桩签名。

func returns(() -> R)

func returns(valueFactory: () -> R): CardinalitySelector<R>

功能：定义桩签名返回指定的值的行为，该值由传入的闭包生成。

参数：

valueFactory: () ->R - 生成预期返回值的闭包函数（生成器）。

返回值：

CardinalitySelector<R> - 定义了桩签名返回指定值的行为的 CardinalitySelector<R> 对象实例。

func returns(R)

func returns(value: R): CardinalitySelector<R>

功能：定义桩签名返回指定值的行为。

参数：

value: R - 预期桩签名的返回值。

返回值：

CardinalitySelector<R> - 定义了桩签名返回行为的 CardinalitySelector<R> 对象实例。

func returnsConsecutively(Array<R>)

func returnsConsecutively(values: Array<R>): Continuation<R>

功能：定义桩签名按列表顺序返回指定的值的行为。桩签名将被调用多次，次数与数组内值的个数相同。

参数：

values: Array<R> - 桩签名的返回值列表。

返回值：

Continuation<R> - 定义了桩签名按序返回指定值的行为的 Continuation<R> 对象实例。

异常：

IllegalArgumentException - 当参数列表为空时，抛出异常。

func returnsConsecutively(ArrayList<R>)

func returnsConsecutively(values: ArrayList<R>): Continuation<R>

功能：定义桩签名按列表顺序返回指定的值的行为。桩签名将被连续调用多次，次数与数组列表内值的个数相同。

参数：

values: ArrayList<R> - 桩签名的返回值列表。

返回值：

Continuation<R> - 定义了桩签名按序返回指定值的 Continuation<R> 对象实例。

异常：

IllegalArgumentException - 当参数列表为空时，抛出异常。

func throws(() -> Exception)

func throws(exceptionFactory: () -> Exception): CardinalitySelector<R>

功能：定义桩签名抛出异常的行为，异常由参数闭包函数生成。

参数：

exceptionFactory: () ->Exception - 构造预期桩签名抛出的异常对象的闭包函数（生成器）。

返回值：

CardinalitySelector<R> - 定义了桩签名抛出异常行为的 CardinalitySelector<R> 对象实例。

func throws(Exception)

func throws(exception: Exception): CardinalitySelector<R>

功能：定义桩签名抛出异常的行为。

参数：

exception: Exception - 预期桩签名抛出的异常对象。

返回值：

CardinalitySelector<R> - 定义了桩签名抛出异常的行为的 CardinalitySelector<R> 对象实例。

interface CardinalitySelector<R>

public interface CardinalitySelector<R> {
    func anyTimes(): Unit
    func once(): Continuation<R>
    func atLeastOnce(): Unit
    func times(expectedTimes: Int64): Continuation<R>
    func times(min!: Int64, max!: Int64): Unit
    func atLeastTimes(minTimesExpected: Int64): Unit
}

功能：此接口提供了可定义桩签名的最近一次行为的执行次数的 API 。该实例仅可被 ActionSelector<R> 的 API 生成（其中 R 代表桩签名的返回类型）。例如：@On(foo.bar()).returns("Predefined value").atLeastOnce() 。为方便表达，后文将桩签名的最近一次行为称为“桩行为”。此接口提供的 API 提供的验证能力如下：

桩签名的调用次数超过指定次数将立即抛出 ExpectationFailedException 。
桩签名的调用次数不足时，框架将在测试用例执行完成后抛出 ExceptionFailedException 。

func anyTimes()

func anyTimes(): Unit

功能：定义“桩行为”可以执行任意次数。此函数对桩签名的调用次数不做任何校验。

func atLeastOnce()

func atLeastOnce(): Unit

功能：定义“桩行为”最少被执行一次。验证不到一次时，抛出异常。

异常：

ExpectationFailedException - 验证“桩行为”执行次数不到一次时，抛出异常。

func atLeastTimes(Int64)

func atLeastTimes(minTimesExpected: Int64): Unit

功能：定义“桩行为”最少被执行指定次数的行为。验证实际执行次数低于最少指定次数时，抛出异常。

参数：

minTimesExpected: Int64 - 预期“桩行为”最少被执行的次数。

异常：

ExpectationFailedException - 验证“桩行为”执行少于指定次数时，抛出异常。

func once()

func once(): Continuation<R>

功能：定义“桩行为”仅被执行一次。此函数将在验证桩签名执行次数超出一次时，抛出异常。

返回值：

Continuation<R> - 定义了验证“桩行为”仅被执行一次的行为的 Continuation<R> 对象实例。

异常：

ExpectationFailedException - 验证“桩行为”执行次数超过一次时，立即抛出异常。

func times(Int64)

func times(expectedTimes: Int64): Continuation<R>

功能：定义“桩行为”被执行指定次数。验证不是指定次数时，抛出异常。

参数：

expectedTimes: Int64 - 预期“桩行为”被执行的次数。

返回值：

Continuation<R> - 定义了验证“桩行为”被执行指定次数的行为的 Continuation<R> 对象实例。

异常：

ExpectationFailedException - 验证“桩行为”执行次数不是指定次数时，抛出异常。

func times(Int64, Int64)

func times(min!: Int64, max!: Int64): Unit

功能：定义“桩行为”执行指定次数范围。验证超出指定次数范围时，抛出异常。

参数：

min!: Int64 - 预期“桩行为”被执行的最小次数。
max!: Int64 - 预期“桩行为”被执行的最大次数。

异常：

ExpectationFailedException - 验证“桩行为”执行次数不是指定次数范围时，抛出异常。

interface ContinuationSelector<R>

public interface Continuation<R> {
    func then(): ActionSelector<R>
}

功能：此接口提供了可继续定义桩签名的行为的 API 。该实例可由ActionSelector<R> 或 CardinalitySelector<R> 的 API 调用后生成。此接口提供的接口能力如下：

允许当先前的操作得到满足时，桩签名将执行额外的操作。仅当后面跟着一个行为定义时，Continuation 实例才有意义。
当先前的操作未得到满足时，将抛出 MockFrameworkException 异常。并不保证抛出此异常的确切位置。

func then()

func then(): ActionSelector<R>

功能：当链中的先前操作完成时，返回 ActionSelector<R> 对象。

返回值：

ActionSelector<R> - ActionSelector<R> 对象实例。

异常：

MockFrameworkException - 当先前的操作未得到满足时，将抛出异常。

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>

功能：创建一个新的“值监听器”对象，不包含任何处理参数的闭包方法。

返回值：

ValueListener<T> - “值监听器”对象

func onEach((T) -> Unit)

static func onEach(callback: (T) -> Unit): ValueListener<T>

功能：创建一个新的“值监听器”对象，带有一个处理参数的闭包方法。

参数：

callback: (T) ->Unit - 处理参数值的闭包函数。

返回值：

ValueListener<T> - “值监听器”对象。

类

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 object 。spy 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 - 过滤器。

返回值：

TypedMatcher<T> - 参数过滤类型匹配器实例。

static func capture<T>(ValueListener<T>)

public static func capture<T>(listener: ValueListener<T>): TypedMatcher<T>

允许 listener 值监听器对类型为 T 的传入参数值进行处理。当 capture 的类型参数未指定时，将使用值监听器的类型参数值。

参数：

listener: ValueListener<T> - 值监听器。

返回值：

TypedMatcher<T> - 拥有值监听器的类型匹配器。

注意：值监听器不允许在 @Called 的参数范围内使用。

static func default<T>(T)

public static func default<T>(target: T): TypedMatcher<T>

功能：根据结构（更高优先级）或引用相等性来匹配值。如果传入的参数既不是 Equatable<T> 也不是引用类型，则会在运行时抛出异常（编译期不做检查）。

参数：

target: T - 必须通过结构或引用相等来匹配的匹配对象。

返回值：

TypedMatcher<T> - 默认类型匹配器。

异常：

MockFrameworkException - 如果参数 target 既不是 Equatable<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> - 仅允许与给定对象引用相等的参数的参数匹配器。

class OrderedVerifier

public class OrderedVerifier {}

功能：此类型用于收集 “验证语句”，可在 ordered 函数中动态传入验证行为。

func checkThat(VerifyStatement)

public func checkThat(statement: VerifyStatement): OrderedVerifier

功能：添加一条 “验证语句”。

参数：

statement: VerifyStatement - 待被添加的“验证语句”。

返回值：

OrderedVerifier - 返回对象自身。

class UnorderedVerifier

public class UnorderedVerifier{
    public func checkThat(statement: VerifyStatement):UnorderedVerifier
}

功能：此类型用于收集 “验证语句”，可在 unordered 函数中动态传入验证行为。

func checkThat(VerifyStatement)

public func checkThat(statement: VerifyStatement):UnorderedVerifier

功能：添加一条 “验证语句”。

参数：

statement: VerifyStatement - 待被添加的“验证语句”。

返回值：

UnorderedVerifier - 返回对象自身。

class Verify

public class Verify {}

功能：Verify 提供了一系列静态方法来支持定义所需验证的动作，如 that 、 ordered 以及 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

功能：在验证范围内，对象没有任何执行动作时，验证通过。

参数：

mocks: Array<Object> - 被验证的对象列表。

异常：

VerificationFailedException - 验证不通过时，抛出异常。

static func ordered((OrderedVerifier) -> Unit)

public static func ordered( collectStatements: (OrderedVerifier) -> Unit): Unit

功能：此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义，并且校验执行顺序。默认情况下，“验证语句”的执行次数为一次。传入列表中的“验证语句”必须是不相交的（即当单个调用行为，可以匹配多个“验证语句”时，将抛出异常）。 “验证语句”通过入参中的闭包动态增加。验证模式为 exhaustive (全量匹配，验证范围内的所有执行情况都应在验证动作中被指定)。

参数：

collectStatements: (OrderedVerifier) ->Unit - 支持可动态增加“验证语句”的闭包。

异常：

VerificationFailedException - 验证不通过时，抛出异常。

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(_)),
)

static func that(VerifyStatement)

public static func that(statement: VerifyStatement): Unit

功能：验证是否正确执行了传入的单个“验证语句”。

参数：

statement: VerifyStatement - 所需验证的“验证语句”。

异常：

VerificationFailedException - 验证不通过时，将抛出异常。

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))))
    }
}

参数：

collectStatements: (UnorderedVerifier) ->Unit - 支持可动态增加“验证语句”的闭包。

异常：

VerificationFailedException - 验证不通过时，抛出异常。

static func unordered(Array<VerifyStatement>)

public static func unordered(statements: Array<VerifyStatement>): Unit

举例来说:

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> - 待验证的多条“验证语句”，变长参数语法支持参数省略 [] 。

异常：

VerificationFailedException - 验证不通过时，抛出异常。

static func unordered(Exhaustiveness, (UnorderedVerifier) -> Unit)

public static func unordered(exhaustive: Exhaustiveness, collectStatements: (UnorderedVerifier) -> Unit): Unit

功能：此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义，并且不校验执行顺序。默认情况下，“验证语句”的执行次数为至少一次。传入列表中的“验证语句”必须是不相交的（即当单个调用行为，可以匹配多个“验证语句”时，将抛出异常）。 “验证语句”通过入参中的闭包动态增加。

参数：

collectStatements: (UnorderedVerifier) ->Unit - 支持可动态增加“验证语句”的闭包。
exhaustive: Exhaustiveness - 验证模式

异常：

VerificationFailedException - 验证不通过时，抛出异常

static func unordered(Exhaustiveness, Array<VerifyStatement>)

public static func unordered(exhaustive: Exhaustiveness, statements: Array<VerifyStatement>): Unit

功能：此函数支持验证“验证语句”是否被执行或执行的次数是否符合定义，并且不校验执行顺序。默认情况下，“验证语句”的执行次数为至少一次。传入列表中的“验证语句”必须是不相交的（即当单个调用行为，可以匹配多个“验证语句”时，将抛出异常）。

参数：

statements: Array<VerifyStatement> - 待验证的多条“验证语句”，变长参数语法支持参数省略 [] 。
exhaustive: Exhaustiveness - 验证模式。

异常：

VerificationFailedException - 验证不通过时，抛出异常。

class VerifyStatement

public class VerifyStatement {}

功能：此类型表示对“桩签名”在验证范围内的单个验证验证语句（即上文中的“验证语句”），提供了成员函数指定“桩签名”的执行次数。该类型的对象仅可通过 @Called 宏调用表达式创建。对一个对象连续调用多个成员函数没有意义，并且会抛出异常。即，执行次数仅可被指定一次。当未调用成员函数指定执行次数时，将基于语句所在的验证动作类型定义默认的执行次数验证值。例如在 Verify.ordered() 中的“验证语句”默认为验证执行一次。

func atLeastOnce()

public func atLeastOnce(): VerifyStatement

功能：指定此“验证语句”验证在验证范围内“桩签名”最少被执行一次。

返回值：

VerifyStatement - 返回对象自身。

异常：

MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时，将抛出异常。

func atLeastTimes(Int64)

public func atLeastTimes(minTimesExpected: Int64): VerifyStatement

功能：指定此“验证语句”验证在验证范围内“桩签名”最少执行指定的次数。

参数：

minTimesExpected: Int64 - 预期验证的执行最少次数。

返回值：

VerifyStatement - 返回对象自身。

异常：

MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时，将抛出异常。

func once()

public func once(): VerifyStatement

功能：指定此“验证语句”验证在验证范围内“桩签名”仅被执行一次。

返回值：

VerifyStatement - 返回对象自身。

异常：

MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时，将抛出异常。

func times(Int64)

public func times(expectedTimes: Int64): VerifyStatement

功能：指定此“验证语句”验证在验证范围内“桩签名”被执行指定次数。

参数：

expectedTimes: Int64 - 预期验证的执行次数。

返回值：

VerifyStatement - 返回对象自身。

异常：

MockFrameworkException - 当对象已被指定过执行次数或已被传入过“验证动作”中时，将抛出异常。

func times(Int64, Int64)

public func times(min!: Int64, max!: Int64): VerifyStatement

功能：指定此“验证语句”验证在验证范围内“桩签名”的执行次数在指定范围内。

参数：

min!: Int64 - 预期验证的最小执行次数。
max!: Int64 - 预期验证的最大执行次数。

返回值：

VerifyStatement - 返回对象自身。

异常：

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

功能：允许验证范围内存在未在验证动作中被定义的“桩签名”的调用行为。

宏

`@Called` 宏

功能：创建一个验证语句。

`@On` 宏

功能：使用配置 API定义 mock/spy 对象成员的行为（或重新定义 spy 对象）。

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> 函数来创建两种对象：mock和spy，其中 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 成员）才能打桩。以下实体不能打桩：

静态成员
扩展成员
顶层函数，包括外部函数

一个完整的桩声明包含以下部分：

@On 宏调用中描述的桩签名。
用于描述桩行为的操作。
（可选）用于设置预期的基数说明符( cardinality specifier, 指定预期执行次数的表达式)。
（可选）续体( 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()：不做任何操作并返回 ()，仅当 R 为 Unit 时可用。
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 或设置原始实例中的字段值。

预期

定义桩时会隐式或显式地向桩附加预期。桩可以定义期望的基数。操作（ fails 和 returnsConcesecutively 除外）返回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	不可调用	否
returns	atLeastOnce	是
returnsConsecutively	times(values.size)	否
throws	atLeastOnce	是
doesNothing	atLeastOnce	是
(calls/gets/sets)Original	atLeastOnce	是

桩链

returnsConsecutively 操作，once 和 times(n) 基数说明符返回一个续体实例。顾名思义，续体表示可以继续使用链，即指定某操作在前一个操作完全完成时立即执行。

续体本身只提供了一个返回新 ActionSelector 的 then() 函数。链上的所有操作都适用相同的规则。如果调用了 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 含有可变属性和字段的接口或抽象类的场景。

执行 getsField 和 setsField 桩操作将字段绑定到特定的调用，这些操作可以将预期配置为任何其他操作。

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 对象可以配置增加默认行为，此时，当匹配不到任何桩时，将执行默认行为。这通过启用桩模式来实现。有两种可用的模式 ReturnsDefaults 和 SyntheticFields 。这些模式通过枚举类型 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)

此类成员返回的默认值也如如下表格所示。

类型	默认值
Bool	false
numbers	0
String	empty string
Option	None
ArrayList, HashSet, Array	new empty collection
HashMap	new 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")

赋给属性和字段的值仅在相应的测试用例中可见。当同时启用 SyntheticFields 和 ReturnsDefaults 时，赋的值优先于默认值。但是，只要字段或属性尚未被赋值，就可以使用默认值。

let foo = mock<Foo>(ReturnsDefaults, SyntheticFields)
@Assert(foo.bar, "")
foo.bar = "Hello"
@Assert(foo.bar, "Hello")

mock 框架验证 API

验证 API 是 mock 框架的一部分，其功能如下：

验证是否进行了某些调用。
验证特定调用的次数。
验证是否使用特定参数进行调用。
验证调用是否按特定顺序进行。

验证通过检查在执行测试期间构建的调用日志来运行断言。调用日志涵盖让 mock 和 spy 对象在测试中可访问的所有调用。只能验证在 mock/spy 对象上进行的调用。

Verify 类是验证 API 的入口。 @Called 宏用于构建关于代码的断言。

@Called 宏调用构造了一个 验证语句 ，即根据调用日志检查代码的单个断言。 Verify 类本身是静态方法的集合。诸如 that 、 ordered 、 unordered 等方法可构造验证块。

示例

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)
)

无序验证包括 Partial 和 Exhaustive 。

默认为 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()
)

动态构建验证块

ordered 和 unordered 函数为接受 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

仓颉语言库 API