初识仓颉语言

仓颉编程语言是一种面向全场景应用开发的通用编程语言，可以兼顾开发效率和运行性能，并提供良好的编程体验，主要具有如下特点：

• 语法简明高效：仓颉编程语言提供了一系列简明高效的语法，旨在减少冗余书写、提升开发效率，例如插值字符串、主构造函数、Flow 表达式、match、if-let、while-let 和重导出等语法，让开发者可以用较少编码表达相关逻辑。
• 多范式编程：仓颉编程语言支持函数式、命令式和面向对象等多范式编程，融合了高阶函数、代数数据类型、模式匹配、泛型等函数式语言的先进特性，还有封装、接口、继承、子类型多态等支持模块化开发的面向对象语言特性，以及值类型、全局函数等简洁高效的命令式语言特性。开发者可以根据开发偏好或应用场景，选用不同的编程范式。
• 类型安全：仓颉编程语言是静态强类型语言，通过编译时类型检查尽早识别程序错误，降低运行时风险，也便于代码维护。同时，仓颉编译器提供了强大的类型推断能力，可以减少类型标注工作，提高开发效率。
• 内存安全：仓颉编程语言支持自动内存管理，并在运行时进行数组下标越界检查、溢出检查等，确保运行时内存安全。
• 高效并发：仓颉编程语言提供了用户态轻量化线程（原生协程），以及简单易用的并发编程机制，保证并发场景的高效开发和运行。
• 兼容语言生态：仓颉编程语言支持和 C 等主流编程语言的互操作，并采用便捷的声明式编程范式，可实现对其他语言库的高效复用和生态兼容。
• 领域易扩展：仓颉编程语言提供了基于词法宏的元编程能力，支持在编译时变换代码，此外，还提供了尾随 lambda、属性、操作符重载、部分关键字可省略等特性，开发者可由此深度定制程序的语法和语义，有利于内嵌式领域专用语言（Embedded Domain Specific Languages，EDSL）的构建。
• 助力 UI 开发：UI 开发是构建端侧应用的重要环节，基于仓颉编程语言的元编程和尾随 lambda 等特性，可以搭建声明式 UI 开发框架，提升 UI 开发效率和体验。
• 内置库功能丰富：仓颉编程语言提供了功能丰富的内置库，涉及数据结构、常用算法、数学计算、正则匹配、系统交互、文件操作、网络通信、数据库访问、日志打印、解压缩、编解码、加解密和序列化等功能。

安装仓颉工具链

在开发仓颉程序时，必用的工具之一是仓颉编译器，它可以将仓颉源代码编译为可运行的二进制文件，但现代编程语言的配套工具并不止于此，实际上，我们为开发者提供了编译器、调试器、包管理器、静态检查工具、格式化工具和覆盖率统计工具等一整套仓颉开发工具链，同时提供了友好的安装和使用方式，基本能做到“开箱即用”。

目前仓颉工具链已适配部分版本的 Linux 和 Windows 平台，但是仅针对部分 Linux 发行版做了完整功能测试，详情可参阅附录Linux 版本工具链的支持与安装章节，在暂未进行过完整功能测试的平台上，仓颉工具链的功能完整性不受到保证。此外，当前 Windows 平台上的仓颉编译器基于 MinGW 实现，相较于 Linux 版本的仓颉编译器，功能会有部分欠缺，二者的具体差异请见版本 Release Note。

Linux

环境准备

Linux 版仓颉工具链的系统环境要求如下：

除此之外，对于不同的 Linux 发行版，还需要安装相应的依赖软件包：

Ubuntu 18.04

$ apt-get install binutils libc-dev libc++-dev libgcc-7-dev

EulerOS R11

$ yum install binutils glibc-devel gcc

此外，仓颉工具链还依赖 OpenSSL 3 组件，由于该组件可能无法从以上发行版的默认软件源直接安装，因此你需要自行手动安装，安装方式请参考附录Linux 版本工具链的支持与安装章节。

其他 Linux 发行版

您可以在附录Linux 版本工具链的支持与安装章节找到更多 Linux 发行版的依赖安装命令。

安装指导

首先请前往仓颉官方发布渠道，下载适配您平台架构的安装包：

• Cangjie-x.y.z-linux_x64.tar.gz：适用于 x86_64 架构 Linux 系统的仓颉工具链
• Cangjie-x.y.z-linux_aarch64.tar.gz：适用于 aarch64 架构 Linux 系统的仓颉工具链

假设这里选择了 Cangjie-x.y.z-linux_x64.tar.gz，下载到本地后，请执行如下命令解压：

tar xvf Cangjie-x.y.z-linux_x64.tar.gz

解压完成，您会在当前工作路径下看到一个名为 cangjie 的目录，其中存放了仓颉工具链的全部内容，请执行如下命令完成仓颉工具链的安装配置：

source cangjie/envsetup.sh

为了验证是否安装成功，可以执行如下命令：

cjc -v

其中 cjc 是仓颉编译器的可执行文件名，如果您在命令行中看到了仓颉编译器版本信息，那么恭喜您，已经成功安装了仓颉工具链。值得说明的是，envsetup.sh 脚本只是在当前 shell 环境中配置了工具链相关的环境变量，所以仓颉工具链仅在当前 shell 环境中可用，在新的 shell 环境中，您需要重新执行 envsetup.sh 脚本配置环境。

卸载与更新

在 Linux 平台，删除上述仓颉工具链的安装包目录，同时移除上述环境变量（最简单的，您可以新开一个 shell 环境），即可完成卸载。

$ rm -rf <path>/<to>/cangjie

若需要更新仓颉工具链，您需要先卸载当前版本，然后按上述指导重新安装最新版本的仓颉工具链。

Windows

本节以 Windows 10 平台为例，介绍仓颉工具链的安装方式。

安装指导

在 Windows 平台上，我们为开发者提供了 exe 和 zip 两种格式的安装包，请前往仓颉官方发布渠道，选择和下载适配您平台架构的 Windows 版安装包。

如果您选择了 exe 格式的安装包（例如 Cangjie-x.y.z-windows_x64.exe），请直接执行此文件，跟随安装向导点击操作，即可完成安装。

如果您选择了 zip 格式的安装包（例如 Cangjie-x.y.z-windows_x64.zip），请将它解压到适当目录，在安装包中，我们为开发者提供了三种不同格式的安装脚本，分别是 envsetup.bat，envsetup.ps1 和 envsetup.sh，您可以根据使用习惯及环境配置，选择一种执行：

若使用 Windows 命令提示符（CMD）环境，请执行：

path\to\cangjie\envsetup.bat

若使用 PowerShell 环境，请执行：

. path\to\cangjie\envsetup.ps1

若使用 MSYS shell、bash 等环境，请执行：

source path/to/cangjie/envsetup.sh

为了验证是否安装成功，请在以上命令环境中继续执行 cjc -v 命令，如果输出了仓颉编译器版本信息，那么恭喜您，已经成功安装了仓颉工具链。

注意：

基于 zip 安装包和执行脚本的安装方式，类似于 Linux 平台，即 envsetup 脚本所配置的环境变量，只在当前命令行环境中有效，如果打开新的命令行窗口，需要重新执行 envsetup 脚本配置环境。

卸载与更新

运行仓颉安装目录下的 unins000.exe 可执行文件，跟随卸载向导点击操作，即可完成卸载。

若需要更新仓颉工具链，您需要先卸载当前版本，然后按上述指导重新安装最新版本的仓颉工具链。

运行第一个仓颉程序

万事俱备，让我们编写和运行第一个仓颉程序吧！

首先，请在适当目录下新建一个名为 hello.cj 的文本文件，并向文件中写入以下仓颉代码：

// hello.cj
main() {
    println("你好，仓颉")
}

在这段代码中，使用了仓颉的注释语法，您可以在 // 符号之后写单行注释，也可以在一对 /* 和 */ 符号之间写多行注释，这与 C/C++ 等语言的注释语法相同。注释内容不影响程序的编译和运行。

然后，请在此目录下执行如下命令：

cjc hello.cj -o hello

这里仓颉编译器会将 hello.cj 中的源代码编译为此平台上的可执行文件 hello，在命令行环境中运行此文件，您将看到程序输出了如下内容：

你好，仓颉

注意：

以上编译命令是针对 Linux 平台的，如果您使用 Windows 平台，只需要将编译命令改为 cjc hello.cj -o hello.exe 即可。

标识符

在仓颉编程语言中，开发者可以给一些程序元素命名，这些名字也被称为“标识符”，标识符分为普通标识符和原始标识符两类，它们分别遵从不同的命名规则。

普通标识符不能和仓颉关键字相同，可以取自以下两类字符序列：

• 由 XID_Start 字符开头，后接任意长度的 XID_Continue 字符
• 由一个_开头，后接至少一个 XID_Continue 字符

其中，XID_Start、XID_Continue 定义见Unicode 标准。仓颉使用 Unicode 标准 15.0.0。

仓颉把所有标识符识别为 Normalization Form C (NFC) 后的形式。两个标识符如果在 NFC 后相等，则认为是相同的标识符。

例如，以下每行字符串都是合法的普通标识符：

abc
_abc
abc_
a1b2c3
a_b_c
a1_b2_c3
仓颉
__こんにちは

以下每行字符串都是不合法的普通标识符：

ab&c  // 使用了非法字符 “&”
3abc  // 数字不能出现在头部
while // 不能使用仓颉关键字

原始标识符是在普通标识符或仓颉关键字的外面加上一对反引号，主要用于将仓颉关键字作为标识符的场景。

例如，以下每行字符串都是合法的原始标识符：

`abc`
`_abc`
`a1b2c3`
`if`
`while`
`à֮̅̕b`

以下每行字符串，由于反引号内的部分是不合法的普通标识符，所以它们整体也是不合法的原始标识符：

`ab&c`
`3abc`

程序结构

通常，我们都会在扩展名为 .cj 的文本文件中编写仓颉程序，这些程序和文件也被称为源代码和源文件，在程序开发的最后阶段，这些源代码将被编译为特定格式的二进制文件。

在仓颉程序的顶层作用域中，可以定义一系列的变量、函数和自定义类型（如 struct、class、enum 和 interface 等），其中的变量和函数分别被称为全局变量和全局函数。如果要将仓颉程序编译为可执行文件，您需要在顶层作用域中定义一个 main 函数作为程序入口，它可以有 Array<String> 类型的参数，也可以没有参数，它的返回值类型可以是整数类型或 Unit 类型。

注意：

定义 main 函数时，不需要写 func 修饰符。此外，如果需要获取程序启动时的命令行参数，可以声明和使用 Array<String> 类型参数。

例如在以下程序中，我们在顶层作用域定义了全局变量 a 和全局函数 b，还有自定义类型 C、D 和 E，以及作为程序入口的 main 函数。

// example.cj
let a = 2023
func b() {}
struct C {}
class D {}
enum E { F | G }

main() {
    println(a)
}

在非顶层作用域中不能定义上述自定义类型，但可以定义变量和函数，称之为局部变量和局部函数。特别地，对于定义在自定义类型中的变量和函数，称之为成员变量和成员函数。

注意：

enum 和 interface 中仅支持定义成员函数，不支持定义成员变量。

例如在以下程序中，我们在顶层作用域定义了全局函数 a 和自定义类型 A，在函数 a 中定义了局部变量 b 和局部函数 c，在自定义类型 A 中定义了成员变量 b 和成员函数 c。

// example.cj
func a() {
    let b = 2023
    func c() {
        println(b)
    }
    c()
}

class A {
    let b = 2024
    public func c() {
        println(b)
    }
}

main() {
    a()
    A().c()
}

运行以上程序，将输出：

2023
2024

变量

在仓颉编程语言中，一个变量由对应的变量名、数据（值）和若干属性构成，开发者通过变量名访问变量对应的数据，但访问操作需要遵从相关属性的约束（如数据类型、可变性和可见性等）。

变量定义的具体形式为：

修饰符 变量名: 变量类型 = 初始值

其中修饰符用于设置变量的各类属性，可以有一个或多个，常用的修饰符包括：

• 可变性修饰符：let 与 var，分别对应不可变和可变属性，可变性决定了变量被初始化后其值还能否改变，仓颉变量也由此分为不可变变量和可变变量两类。
• 可见性修饰符：private 与 public 等，影响全局变量和成员变量的可引用范围，详见后续章节的相关介绍。
• 静态性修饰符：static，影响成员变量的存储和引用方式，详见后续章节的相关介绍。

在定义仓颉变量时，可变性修饰符是必要的，在此基础上，还可以根据需要添加其他修饰符。

• 变量名应是一个合法的仓颉标识符。
• 变量类型指定了变量所持有数据的类型。当初始值具有明确类型时，可以省略变量类型标注，此时编译器可以自动推断出变量类型。
• 初始值是一个仓颉表达式，用于初始化变量，如果标注了变量类型，需要保证初始值类型和变量类型一致。在定义全局变量或静态成员变量时，必须指定初始值。在定义局部变量或实例成员变量时，可以省略初始值，但需要标注变量类型，同时要在此变量被引用前完成初始化，否则编译会报错。

例如，下列程序定义了两个 Int64 类型的不可变变量 a 和可变变量 b，随后修改了变量 b 的值，并调用 println 函数打印 a 与 b 的值。

main() {
    let a: Int64 = 20
    var b: Int64 = 12
    b = 23
    println("${a}${b}")
}

编译运行此程序，将输出：

2023

如果尝试修改不可变变量，编译时会报错，例如：

main() {
    let pi: Float64 = 3.14159
    pi = 2.71828 // Error, cannot assign to immutable value
}

当初始值具有明确类型时，可以省略变量类型标注，例如：

main() {
    let a: Int64 = 2023
    let b = a
    println("a - b = ${a - b}")
}

其中变量 b 的类型可以由其初值 a 的类型自动推断为 Int64，所以此程序也可以被正常编译和运行，将输出：

a - b = 0

在定义局部变量时，可以不进行初始化，但一定要在变量被引用前赋予初值，例如：

main() {
    let text: String
    text = "仓颉造字"
    println(text)
}

编译运行此程序，将输出：

仓颉造字

在定义全局变量和静态成员变量时必须初始化，否则编译会报错，例如：

// example.cj
let global: Int64 // Error, variable in top-level scope must be initialized

// example.cj
class Player {
    static let score: Int32 // Error, static variable 'score' needs to be initialized when declaring
}

值类型和引用类型变量

程序在运行阶段，只有指令流转和数据变换，仓颉程序中的各种标识符已不复存在。由此可见，编译器使用了一些机制，将这些名字和编程所取用的数据实体/存储空间绑定起来。

从编译器实现层面看，任何变量总会关联一个值（一般是通过内存地址/寄存器关联），只是在使用时，对有些变量，我们将直接取用这个值本身，这被称为值类型变量，而对另一些变量，我们把这个值作为索引、取用这个索引指示的数据，这被称为引用类型变量。值类型变量通常在线程栈上分配，每个变量都有自己的数据副本；引用类型变量通常在进程堆中分配，多个变量可引用同一数据对象，对一个变量执行的操作可能会影响其他变量。

从语言层面看，值类型变量对它所绑定的数据/存储空间是独占的，而引用类型变量所绑定的数据/存储空间可以和其他引用类型变量共享。

基于上述原理，在使用值类型变量和引用类型变量时，会存在一些行为差异，以下几点值得注意：

1. 在给值类型变量赋值时，一般会产生拷贝操作，且原来绑定的数据/存储空间被覆写。在给引用类型变量赋值时，只是改变了引用关系，原来绑定的数据/存储空间不会被覆写。
2. 用 let 定义的变量，要求变量被初始化后都不能再赋值。对于引用类型，这只是限定了引用关系不可改变，但是所引用的数据是可以被修改的。

在仓颉编程语言中，基础数据类型和 struct 等类型属于值类型，而 class 和 Array 等类型属于引用类型。

例如，以下程序演示了 struct 和 class 类型变量的行为差异：

struct Copy {
    var data = 2012
}

class Share {
    var data = 2012
}

main() {
    let c1 = Copy()
    var c2 = c1
    c2.data = 2023
    println("${c1.data}, ${c2.data}")

    let s1 = Share()
    let s2 = s1
    s2.data = 2023
    println("${s1.data}, ${s2.data}")
}

运行以上程序，将输出：

2012, 2023
2023, 2023

由此可以看出，对于值类型的 Copy 类型变量，在赋值时总是获取 Copy 实例的拷贝，如 c2 = c1，随后对 c2 成员的修改并不影响 c1。对于引用类型的 Share 类型变量，在赋值时将建立变量和实例之间的引用关系，如 s2 = s1，随后对 s2 成员的修改会影响 s1。

如果将以上程序中的 var c2 = c1 改成 let c2 = c1，则编译会报错，例如：

struct Copy {
    var data = 2012
}

main() {
    let c1 = Copy()
    let c2 = c1
    c2.data = 2023 // Error, cannot assign to immutable value
}

作用域

在前文中，我们初步介绍了如何给仓颉程序元素命名，实际上，除了变量，我们还可以给函数和自定义类型等命名，在程序中将使用这些名字访问对应的程序元素。

但在实际应用中，需要考虑一些特殊情况：

• 当程序规模较大时，那些简短的名字很容易重复，即产生命名冲突。
• 结合运行时考虑，在有些代码片段中，另一些程序元素是无效的，对它们的引用会导致运行时错误。
• 在某些逻辑构造中，为了表达元素之间的包含关系，不应通过名字直接访问子元素，而是要通过其父元素名间接访问。

为了应对这些问题，现代编程语言引入了“作用域”的概念及设计，将名字和程序元素的绑定关系限制在一定范围里。不同作用域之间可以是并列或无关的，也可以是嵌套或包含关系。一个作用域将明确我们能用哪些名字访问哪些程序元素，具体规则是：

1. 当前作用域中定义的程序元素与名字的绑定关系，在当前作用域和其内层作用域中是有效的，可以通过此名字直接访问对应的程序元素。
2. 内层作用域中定义的程序元素与名字的绑定关系，在外层作用域中无效。
3. 内层作用域可以使用外层作用域中的名字重新定义绑定关系，根据规则 1，此时内层作用域中的命名相当于遮盖了外层作用域中的同名定义，对此我们称内层作用域的级别比外层作用域的级别高。

在仓颉编程语言中，用一对大括号“{}”包围一段仓颉代码，即构造了一个新的作用域，其中可以继续使用大括号“{}”包围仓颉代码，由此产生了嵌套作用域，这些作用域均服从上述规则。特别的，在一个仓颉源文件中，不被任何大括号“{}”包围的代码，它们所属的作用域被称为“顶层作用域”，即当前文件中“最外层”的作用域，按上述规则，其作用域级别最低。

注意：

用大括号“{}”包围代码构造作用域时，其中不限于使用表达式，还可以定义函数和自定义类型等。

例如在以下名为 test.cj 的仓颉源文件里，在顶层作用域中定义了名字 element，它和字符串“仓颉”绑定，而 main 和 if 引导的代码块中也定义了名字 element，分别对应整数 9 和整数 2023。由上述作用域规则，在第 4 行，element 的值为“仓颉”，在第 8 行，element 的值为 2023，在第 10 行，element 的值为 9。

// test.cj
let element = "仓颉"
main() {
    println(element)
    let element = 9
    if (element > 0) {
        let element = 2023
        println(element)
    }
    println(element)
}

运行以上程序，将输出：

仓颉
2023
9

表达式

在一些传统编程语言中，一个表达式由一个或多个操作数（operand）通过零个或多个操作符（operator）组合而成，表达式总是隐含着一个计算过程，因此每个表达式都会有一个计算结果，对于只有操作数而没有操作符的表达式，其计算结果就是操作数自身，对于包含操作符的表达式，计算结果是对操作数执行操作符定义的计算而得到的值。在这种定义下的表达式也被称为算术运算表达式。

在仓颉编程语言中，我们简化并延伸了表达式的传统定义——凡是可求值的语言元素都是表达式。因此，仓颉不仅有传统的算术运算表达式，还有条件表达式、循环表达式和 try 表达式等，它们都可以被求值，并作为值去使用，如作为变量定义的初值和函数实参等。此外，因为仓颉是强类型的编程语言，所以仓颉表达式不仅可求值，还有确定的类型。

仓颉编程语言的各种表达式将在后续章节中逐一介绍，本节介绍最常用的条件表达式、循环表达式以及部分控制转移表达式（break、continue）。

我们知道，任何一段程序的执行流程，只会涉及三种基本结构——顺序结构、分支结构和循环结构。实际上，分支结构和循环结构，是由某些指令控制当前顺序执行流产生跳转而得到的，它们让程序能够表达更复杂的逻辑，在仓颉中，这种用来控制执行流的语言元素就是条件表达式和循环表达式。

在仓颉编程语言中，条件表达式分为 if 表达式和 if-let 表达式两种，它们的值与类型需要根据使用场景来确定。循环表达式有四种：for-in 表达式、while 表达式、do-while 表达式和 while-let 表达式，它们的类型都是 Unit、值为 ()。其中 if-let 表达式和 while-let 表达式都与模式匹配相关，请参见if-let 表达式和while-let 表达式章节，本节只介绍以上提及的其他几种表达式。

在仓颉程序中，由一对大括号“{}”包围起来的一组表达式，被称为“代码块”，它将作为程序的一个顺序执行流，其中的表达式将按编码顺序依次执行。如果代码块中有至少一个表达式，我们规定此代码块的值与类型等于其中最后一个表达式的值与类型，如果代码块中没有表达式，规定这种空代码块的类型为 Unit、值为 ()。

注意：

代码块本身不是一个表达式，不能被单独使用，它将依附于函数、条件表达式和循环表达式等执行和求值。

if 表达式

if 表达式的基本形式为：

if (条件) {
  分支 1
} else {
  分支 2
}

其中“条件”是布尔类型表达式，“分支 1”和“分支 2”是两个代码块。if 表达式将按如下规则执行：

1. 计算“条件”表达式，如果值为 true 则转到第 2 步，值为 false 则转到第 3 步。
2. 执行“分支 1”，转到第 4 步。
3. 执行“分支 2”，转到第 4 步。
4. 继续执行 if 表达式后面的代码。

在一些场景中，我们可能只关注条件成立时该做些什么，所以 else 和对应的代码块是允许省略的。

如下程序演示了 if 表达式的基本用法：

import std.random.*

main() {
    let number: Int8 = Random().nextInt8()
    println(number)
    if (number % 2 == 0) {
        println("偶数")
    } else {
        println("奇数")
    }
}

在这段程序中，我们使用仓颉标准库的 random 包生成了一个随机整数，然后使用 if 表达式判断这个整数是否能被 2 整除，并在不同的条件分支中打印“偶数”或“奇数”。

仓颉编程语言是强类型的，if 表达式的条件只能是布尔类型，不能使用整数或浮点数等类型，和 C 语言等不同，仓颉不以条件取值是否为 0 作为分支选择依据，例如以下程序将编译报错：

main() {
    let number = 1
    if (number) { // Error, mismatched types
        println("非零数")
    }
}

在许多场景中，当一个条件不成立时，我们可能还要判断另一个或多个条件、再执行对应的动作，仓颉允许在 else 之后跟随新的 if 表达式，由此支持多级条件判断和分支执行，例如：

import std.random.*

main() {
    let speed = Random().nextFloat64() * 20.0
    println("${speed} km/s")
    if (speed > 16.7) {
        println("第三宇宙速度，鹊桥相会")
    } else if (speed > 11.2) {
        println("第二宇宙速度，嫦娥奔月")
    } else if (speed > 7.9) {
        println("第一宇宙速度，腾云驾雾")
    } else {
        println("脚踏实地，仰望星空")
    }
}

if 表达式的值与类型，需要根据使用形式与场景来确定：

• 当含 else 分支的 if 表达式被求值时，需要根据求值上下文确定 if 表达式的类型：

  • 如果上下文明确要求值类型为 T，则 if 表达式各分支代码块的类型必须是 T 的子类型，这时 if 表达式的类型被确定为 T，如果不满足子类型约束，编译会报错。
  • 如果上下文没有明确的类型要求，则 if 表达式的类型是其各分支代码块类型的最小公共父类型，如果最小公共父类型不存在，编译会报错。

  如果编译通过，则 if 表达式的值就是所执行分支代码块的值。

• 如果含 else 分支的 if 表达式没有被求值，在这种场景里，开发者一般只想在不同分支里做不同操作，不会关注各分支最后一个表达式的值与类型，为了不让上述类型检查规则影响这一思维习惯，仓颉规定这种场景下的 if 表达式类型为 Unit、值为 ()，且各分支不参与上述类型检查。

• 对于不含 else 分支的 if 表达式，由于 if 分支也可能不被执行，所以我们规定这类 if 表达式的类型为 Unit、值为 ()。

例如，以下程序基于 if 表达式求值，模拟一次简单的模数转换过程：

main() {
    let zero: Int8 = 0
    let one: Int8 = 1
    let voltage = 5.0
    let bit = if (voltage < 2.5) {
        zero
    } else {
        one
    }
}

在以上程序中，if 表达式作为变量定义的初值使用，由于变量 bit 没有被标注类型、需要从初值中推导，所以 if 表达式的类型取为两个分支代码块类型的最小公共父类型，根据前文对“代码块”的介绍，可知两个分支代码块类型都是 Int8，所以 if 表达式的类型被确定为 Int8，其值为所执行分支即 else 分支代码块的值，所以变量 bit 的类型为 Int8、值为 1。

while 表达式

while 表达式的基本形式为：

while (条件) {
  循环体
}

其中“条件”是布尔类型表达式，“循环体”是一个代码块。while 表达式将按如下规则执行：

1. 计算“条件”表达式，如果值为 true 则转第 2 步，值为 false 转第 3 步。
2. 执行“循环体”，转第 1 步。
3. 结束循环，继续执行 while 表达式后面的代码。

例如，以下程序使用 while 表达式，基于二分法，近似计算数字 2 的平方根：

main() {
    var root = 0.0
    var min = 1.0
    var max = 2.0
    var error = 1.0
    let tolerance = 0.1 ** 10

    while (error ** 2 > tolerance) {
        root = (min + max) / 2.0
        error = root ** 2 - 2.0
        if (error > 0.0) {
            max = root
        } else {
            min = root
        }
    }
    println("2 的平方根约等于：${root}")
}

运行以上程序，将输出：

2 的平方根约等于：1.414215

do-while 表达式

do-while 表达式的基本形式为：

do {
  循环体
} while (条件)

其中“条件”是布尔类型表达式，“循环体”是一个代码块。do-while 表达式将按如下规则执行：

1. 执行“循环体”，转第 2 步。
2. 计算“条件”表达式，如果值为 true 则转第 1 步，值为 false 转第 3 步。
3. 结束循环，继续执行 do-while 表达式后面的代码。

例如，以下程序使用 do-while 表达式，基于蒙特卡洛算法，近似计算圆周率的值：

import std.random.*

main() {
    let random = Random()
    var totalPoints = 0
    var hitPoints = 0

    do {
        // 在 ((0, 0), (1, 1)) 这个正方形中随机取点
        let x = random.nextFloat64()
        let y = random.nextFloat64()
        // 判断是否落在正方形内接圆里
        if ((x - 0.5) ** 2 + (y - 0.5) ** 2 < 0.25) {
            hitPoints++
        }
        totalPoints++
    } while (totalPoints < 1000000)

    let pi = 4.0 * Float64(hitPoints) / Float64(totalPoints)
    println("圆周率近似值为：${pi}")
}

运行以上程序，将输出：

圆周率近似值为：3.141872

说明：

由于算法涉及随机数，所以每次运行程序输出的数值可能都不同，但都会约等于 3.14。

for-in 表达式

for-in 表达式可以遍历那些扩展了迭代器接口 Iterable<T> 的类型实例。for-in 表达式的基本形式为：

for (迭代变量 in 序列) {
  循环体
}

其中“循环体”是一个代码块。“迭代变量”是单个标识符或由多个标识符构成的元组，用于绑定每轮遍历中由迭代器指向的数据，可以作为“循环体”中的局部变量使用。“序列”是一个表达式，它只会被计算一次，遍历是针对此表达式的值进行的，其类型必须扩展了迭代器接口 Iterable<T>。for-in 表达式将按如下规则执行：

1. 计算“序列”表达式，将其值作为遍历对象，并初始化遍历对象的迭代器。
2. 更新迭代器，如果迭代器终止，转第 4 步，否则转第 3 步。
3. 将当前迭代器指向的数据与“迭代变量”绑定，并执行“循环体”，转第 2 步。
4. 结束循环，继续执行 for-in 表达式后面的代码。

说明：

仓颉内置的区间和数组等类型已经扩展了 Iterable<T> 接口。

例如，以下程序使用 for-in 表达式，遍历中国地支字符构成的数组 noumenonArray，输出农历 2024 年各月的干支纪法：

main() {
    let metaArray = [r'甲', r'乙', r'丙', r'丁', r'戊',
        r'己', r'庚', r'辛', r'壬', r'癸']
    let noumenonArray = [r'寅', r'卯', r'辰', r'巳', r'午', r'未',
        r'申', r'酉', r'戌', r'亥', r'子', r'丑']
    let year = 2024
    // 年份对应的天干索引
    let metaOfYear = ((year % 10) + 10 - 4) % 10
    // 此年首月对应的天干索引
    var index = (2 * metaOfYear + 3) % 10 - 1
    println("农历 2024 年各月干支：")
    for (noumenon in noumenonArray) {
        print("${metaArray[index]}${noumenon} ")
        index = (index + 1) % 10
    }
}

运行以上程序，将输出：

农历 2024 年各月干支：
丙寅 丁卯 戊辰 己巳 庚午 辛未 壬申 癸酉 甲戌 乙亥 丙子 丁丑

遍历区间

for-in 表达式可以遍历区间类型实例，例如：

main() {
    var sum = 0
    for (i in 1..=100) {
        sum += i
    }
    println(sum)
}

运行以上程序，将输出：

5050

关于区间类型的详细内容，请参阅基本数据类型区间类型章节。

遍历元组构成的序列

如果一个序列的元素是元组类型，则使用 for-in 表达式遍历时，“迭代变量”可以写成元组形式，以此实现对序列元素的解构，例如：

main() {
    let array = [(1, 2), (3, 4), (5, 6)]
    for ((x, y) in array) {
        println("${x}, ${y}")
    }
}

运行以上程序，将输出：

1, 2
3, 4
5, 6

迭代变量不可修改

在 for-in 表达式的循环体中，不能修改迭代变量，例如以下程序在编译时会报错：

main() {
    for (i in 0..5) {
        i = i * 10 // Error, cannot assign to value which is an initialized 'let' constant
        println(i)
    }
}

使用通配符 _ 代替迭代变量

在一些应用场景中，我们只需要循环执行某些操作，但并不使用迭代变量，这时您可以使用通配符 _ 代替迭代变量，例如：

main() {
    var number = 2
    for (_ in 0..5) {
        number *= number
    }
    println(number)
}

运行以上程序，将输出：

4294967296

注意：

在这种场景下，如果您使用普通的标识符定义迭代变量，编译会输出“unused variable”告警，使用通配符 _ 则可以避免这一告警。

where 条件

在部分循环遍历场景中，对于特定取值的迭代变量，我们可能需要直接跳过、进入下一轮循环，虽然可以使用 if 表达式和 continue 表达式在循环体中实现这一逻辑，但仓颉为此提供了更便捷的表达方式——可以在所遍历的“序列”之后用 where 关键字引导一个布尔表达式，这样在每次将进入循环体执行前，会先计算此表达式，如果值为 true 则执行循环体，反之直接进入下一轮循环。例如：

main() {
    for (i in 0..8 where i % 2 == 1) { // i 为奇数才会执行循环体
        println(i)
    }
}

运行以上程序，将输出：

1
3
5
7

break 与 continue 表达式

在循环结构的程序中，有时我们需要根据特定条件提前结束循环或跳过本轮循环，为此仓颉引入了 break 与 continue 表达式，它们可以出现在循环表达式的循环体中，break 用于终止当前循环表达式的执行、转去执行循环表达式之后的代码，continue 用于提前结束本轮循环、进入下一轮循环。break 与 continue 表达式的类型都是 Nothing。

例如，以下程序使用 for-in 表达式和 break 表达式，在给定的整数数组中，找到第一个能被 5 整除的数字：

main() {
    let numbers = [12, 18, 25, 36, 49, 55]
    for (number in numbers) {
        if (number % 5 == 0) {
            println(number)
            break
        }
    }
}

当 for-in 迭代至 numbers 数组的第三个数 25 时，由于 25 可以被 5 整除，所以将执行 if 分支中的 println 和 break，break 将终止 for-in 循环，numbers中的后续数字不会被遍历到，因此运行以上程序，将输出：

25

以下程序使用 for-in 表达式和 continue 表达式，将给定整数数组中的奇数打印出来：

main() {
    let numbers = [12, 18, 25, 36, 49, 55]
    for (number in numbers) {
        if (number % 2 == 0) {
            continue
        }
        println(number)
    }
}

在循环迭代中，当 number 是偶数时，continue 将被执行，这会提前结束本轮循环、进入下一轮循环，println 不会被执行，因此运行以上程序，将输出：

25
49
55

函数

仓颉使用关键字 func 来表示函数定义的开始，func 之后依次是函数名、参数列表、可选的函数返回值类型、函数体。其中，函数名可以是任意的合法标识符，参数列表定义在一对圆括号内（多个参数间使用逗号分隔），参数列表和函数返回值类型（如果存在）之间使用冒号分隔，函数体定义在一对花括号内。

函数定义举例：

func add(a: Int64, b: Int64): Int64 {
    return a + b
}

上例中定义了一个名为 add 的函数，其参数列表由两个 Int64 类型的参数 a 和 b 组成，函数返回值类型为 Int64，函数体中将 a 和 b 相加并返回。

详细介绍可参考函数模块介绍。

整数类型

整数类型分为有符号（signed）整数类型和无符号（unsigned）整数类型。

有符号整数类型包括 Int8、Int16、Int32、Int64 和 IntNative，分别用于表示编码长度为 8-bit、16-bit、32-bit、64-bit 和平台相关大小的有符号整数值的类型。

无符号整数类型包括 UInt8、UInt16、UInt32、UInt64 和 UIntNative，分别用于表示编码长度为 8-bit、16-bit、32-bit、64-bit 和平台相关大小的无符号整数值的类型。

对于编码长度为 N 的有符号整数类型，其表示范围为：$-2^{N-1} \sim 2^{N-1}-1$；对于编码长度为 N 的无符号整数类型，其表示范围为：$0 \sim 2^{N}-1$。下表列出了所有整数类型的表示范围：

程序具体使用哪种整数类型，取决于该程序中需要处理的整数的性质和范围。在 Int64 类型适合的情况下，首选 Int64 类型，因为 Int64 的表示范围足够大，并且整数类型字面量在没有类型上下文的情况下默认推断为 Int64 类型，可以避免不必要的类型转换。

整数类型字面量

整数类型字面量有 4 种进制表示形式：二进制（使用 0b 或 0B 前缀）、八进制（使用 0o 或 0O 前缀）、十进制（没有前缀）、十六进制（使用 0x 或 0X 前缀）。例如，对于十进制数 24，表示成二进制是 0b00011000（或 0B00011000），表示成八进制是 0o30（或 0O30），表示成十六进制是 0x18（或 0X18）。

在各进制表示中，可以使用下划线 _ 充当分隔符的作用，方便识别数值的位数，如 0b0001_1000。

对于整数类型字面量，如果它的值超出了上下文要求的整数类型的表示范围，编译器将会报错。

let x: Int8 = 128          // Error, 128 out of the range of Int8
let y: UInt8 = 256         // Error, 256 out of the range of UInt8
let z: Int32 = 0x8000_0000 // Error, 0x8000_0000 out of the range of Int32

在使用整数类型字面量时，可以通过加入后缀来明确整数字面量的类型，后缀与类型的对应为：

加入了后缀的整数字面量可以像下面的方式来使用：

var x = 100i8  // x is 100 with type Int8
var y = 0x10u64 // y is 16 with type UInt64
var z = 0o432i32  // z is 282 with type Int32

字符字节字面量

仓颉编程语言支持字符字节字面量，以方便使用 ASCII 码表示 UInt8 类型的值。字符字节字面量由字符 b、一对标识首尾的单引号、以及一个 ASCII 字符组成，例如：

var a = b'x' // a is 120 with type UInt8
var b = b'\n' // b is 10 with type UInt8
var c = b'\u{78}' // c is 120 with type UInt8

b'x' 表示类型为 UInt8 大小是 120 的字面值。另外还可以通过 b'\u{78}' 这种转义形式表示类型为 UInt8，16 进制大小为 0x78 或 10 进制大小为 120 的字面值。需要注意的是，\u 内部最多有两位 16 进制数，并且值必须小于 256（十进制）。

整数类型支持的操作

整数类型默认支持的操作符包括：算术操作符、位操作符、关系操作符、自增和自减操作符、赋值操作符、复合赋值操作符。各操作符的优先级参见附录中的操作符。

1. 算术操作符包括：一元负号（-）、加法（+）、减法（-）、乘法（*）、除法（/）、取模（%）、幂运算（**）。

   • 除了一元负号（-）和幂运算（**），其他操作符要求左右操作数是相同的类型。

   • *，/，+ 和 - 的操作数可以是整数类型或浮点类型。

   • % 的操作数只支持整数类型。

   • ** 的左操作数只能为 Int64 类型或 Float64 类型，并且：

     • 当左操作数类型为 Int64 时，右操作数只能为 UInt64 类型，表达式的类型为 Int64。
     • 当左操作数类型为 Float64 时，右操作数只能为 Int64 类型或 Float64 类型，表达式的类型为 Float64。

   幂运算的使用，见如下示例：

   let p1 = 2 ** 3               // p1 = 8
   let p2 = 2 ** UInt64(3 ** 2)  // p2 = 512
   let p3 = 2.0 ** 3.0           // p3 = 8.0
   let p4 = 2.0 ** 3 ** 2        // p4 = 512.0
   let p5 = 2.0 ** 3.0           // p5 = 8.0
   let p6 = 2.0 ** 3.0 ** 2.0    // p6 = 512.0
   

2. 位操作符包括：按位求反（!）、左移（<<）、右移（>>）、按位与（&）、按位异或（^）、按位或（|）。注意，按位与、按位异或和按位或操作符要求左右操作数是相同的整数类型。

3. 关系操作符包括：小于（<）、大于（>）、小于等于（<=）、大于等于（>=）、相等（==）、不等（!=）。要求关系操作符的左右操作数是相同的整数类型。

4. 自增和自减操作符包括：自增（++）和自减（--）。注意，仓颉中的自增和自减操作符只能作为一元后缀操作符使用。

5. 赋值操作符即 =，复合赋值操作符包括：+=、-=、*=、/=、%=、**=、<<=、>>=、&=、^=、|=。

注意：

本章中我们所提及的某个类型支持的操作，均是指在没有操作符重载的前提下。

浮点类型

浮点类型包括 Float16、 Float32 和 Float64，分别用于表示编码长度为 16-bit、 32-bit 和 64-bit 的浮点数（带小数部分的数字，如 3.14159、8.24 和 0.1 等）的类型。Float16、 Float32 和 Float64 分别对应 IEEE 754 中的半精度格式（即 binary16）、单精度格式（即 binary32）和双精度格式（即 binary64）。

Float64 的精度约为小数点后 15 位，Float32 的精度约为小数点后 6 位，Float16 的精度约为小数点后 3 位。使用哪种浮点类型，取决于代码中需要处理的浮点数的性质和范围。在多种浮点类型都适合的情况下，首选精度高的浮点类型，因为精度低的浮点类型的累计计算误差很容易扩散，并且它能精确表示的整数范围也很有限。

浮点类型字面量

浮点类型字面量有两种进制表示形式：十进制、十六进制。在十进制表示中，一个浮点字面量至少要包含一个整数部分或一个小数部分，没有小数部分时必须包含指数部分（以 e 或 E 为前缀，底数为 10）。在十六进制表示中，一个浮点字面量除了至少要包含一个整数部分或小数部分（以 0x 或 0X 为前缀），同时必须包含指数部分（以 p 或 P 为前缀，底数为 2）。

下面的例子展示了浮点字面量的使用：

let a: Float32 = 3.14
let b: Float32 = 2e3
let c: Float32 = 2.4e-1
let d: Float64 = .123e2
let e: Float64 = 0x1.1p0
let f: Float64 = 0x1p2
let g: Float64 = 0x.2p4

在使用十进制浮点数字面量时，可以通过加入后缀来明确浮点数字面量的类型，后缀与类型的对应为：

加入了后缀的浮点数字面量可以像下面的方式来使用：

let a = 3.14f32   // a is 3.14 with type Float32
let b = 2e3f32    // b is 2e3 with type Float32
let c = 2.4e-1f64 // c is 2.4e-1 with type Float64
let d = .123e2f64 // d is .123e2 with type Float64

浮点类型支持的操作

浮点类型默认支持的操作符包括：算术操作符、关系操作符、赋值操作符、复合赋值操作符。浮点类型不支持自增和自减操作符。

布尔类型

布尔类型使用 Bool 表示，用来表示逻辑中的真和假。

布尔类型字面量

布尔类型只有两个字面量：true 和 false。

下面的例子展示了布尔字面量的使用：

let a: Bool = true
let b: Bool = false

布尔类型支持的操作

布尔类型支持的操作符包括：逻辑操作符（逻辑非 !，逻辑与 &&，逻辑或 ||）、部分关系操作符（== 和 !=）、赋值操作符、部分复合赋值操作符（&&= 和 ||=）。

字符类型

字符类型使用 Rune 表示，可以表示 Unicode 字符集中的所有字符。

字符类型字面量

字符类型字面量有三种形式：单个字符、转义字符和通用字符。一个 Rune 字面量由字符 r 开头，后跟一个由一对单引号或双引号包含的字符。

单个字符的字符字面量举例：

let a: Rune = r'a'
let b: Rune = r"b"

转义字符是指在一个字符序列中对后面的字符进行另一种解释的字符。转义字符使用转义符号 \ 开头，后面加需要转义的字符。举例如下：

let slash: Rune = r'\\'
let newLine: Rune = r'\n'
let tab: Rune = r'\t'

通用字符以 \u 开头，后面加上定义在一对花括号中的 1~8 个十六进制数，即可表示对应的 Unicode 值代表的字符。举例如下：

main() {
    let he: Rune = r'\u{4f60}'
    let llo: Rune = r'\u{597d}'
    print(he)
    print(llo)
}

编译并执行上述代码，输出结果为：

你好

字符类型支持的操作

字符类型仅支持关系操作符：小于（<）、大于（>）、小于等于（<=）、大于等于（>=）、相等（==）、不等（!=）。比较的是字符的 Unicode 值。

字符串类型

字符串类型使用 String 表示，用于表达文本数据，由一串 Unicode 字符组合而成。

字符串字面量

字符串字面量分为三类：单行字符串字面量，多行字符串字面量，多行原始字符串字面量。

单行字符串字面量的内容定义在一对单引号或一对双引号之内，引号中的内容可以是任意数量的（除了非转义的双引号和单独出现的 \ 之外的）任意字符。单行字符串字面量只能写在同一行，不能跨越多行。举例如下：

let s1: String = ""
let s2 = 'Hello Cangjie Lang'
let s3 = "\"Hello Cangjie Lang\""
let s4 = 'Hello Cangjie Lang\n'

多行字符串字面量开头结尾需各存在三个双引号（"""）或三个单引号（'''）。字面量的内容从开头的三个引号换行后的第一行开始，到结尾的三个引号之前为止，之间的内容可以是任意数量的（除单独出现的 \ 之外的）任意字符。不同于单行字符串字面量，多行字符串字面量可以跨越多行。举例如下：

let s1: String = """
    """
let s2 = '''
    Hello,
    Cangjie Lang'''

多行原始字符串字面量以一个或多个井号（#）和一个单引号（'）或双引号（"）开头，后跟任意数量的合法字符，直到出现与字符串开头相同的引号和与字符串开头相同数量的井号为止。在当前文件结束之前，如果还没遇到匹配的双引号和相同个数的井号，则编译报错。与多行字符串字面量一样，原始多行字符串字面量可以跨越多行。不同之处在于，转义规则不适用于多行原始字符串字面量，字面量中的内容会维持原样（转义字符不会被转义，如下例中 s2 中的 \n 不是换行符，而是由 \ 和 n 组成的字符串 \n）。举例如下：

let s1: String = #""#
let s2 = ##'\n'##
let s3 = ###"
    Hello,
    Cangjie
    Lang"###

对于形如 left = right 的赋值操作，如果左操作数的类型是 Byte（内置类型 UInt8 的别名），并且右操作数是一个表示 ASCII 字符的字符串字面量，那么右操作数的字符串将分别被强制转换为 Byte 类型，再进行赋值；如果左操作数的类型是 Rune，并且右操作数是一个单字符的字符串字面量，那么右操作数的字符串将分别被强制转换为 Rune 类型，再进行赋值。

main() {
    var b: Byte = "0"
    print(b)
    b = "1"
    print(b)
    var r: Rune = "0"
    print(r)
    r = "1"
    print(r)
}

编译并执行上述代码，输出结果为：

484901

插值字符串

插值字符串是一种包含一个或多个插值表达式的字符串字面量（不适用于多行原始字符串字面量），通过将表达式插入到字符串中，可以有效避免字符串拼接的问题。虽然我们直到现在才介绍它，但其实它早已经出现在之前的示例代码中，因为我们经常在 println 函数中输出非字符串类型的变量值，例如 println("${x}")。

插值表达式必须用花括号 {} 包起来，并在 {} 之前加上 $ 前缀。{} 中可以包含一个或者多个声明或表达式。

当插值字符串求值时，每个插值表达式所在位置会被 {} 中的最后一项的值替换，整个插值字符串最终仍是一个字符串。

下面是插值字符串的简单示例：

main() {
    let fruit = "apples"
    let count = 10
    let s = "There are ${count * count} ${fruit}"
    println(s)

    let r = 2.4
    let area = "The area of a circle with radius ${r} is ${let PI = 3.141592; PI * r * r}"
    println(area)
}

编译并执行上述代码，输出结果为：

There are 100 apples
The area of a circle with radius 2.400000 is 18.095570

字符串类型支持的操作

字符串类型支持使用关系操作符进行比较，支持使用 + 进行拼接。下面的例子展示了字符串类型的判等和拼接：

main() {
    let s1 = "abc"
    var s2 = "ABC"
    let r1 = s1 == s2
    println("The result of 'abc' == 'ABC' is: ${r1}")
    let r2 = s1 + s2
    println("The result of 'abc' + 'ABC' is: ${r2}")
}

编译并执行上述代码，输出结果为：

The result of 'abc' == 'ABC' is: false
The result of 'abc' + 'ABC' is: abcABC

字符串还支持其他常见操作，例如拆分、替换等。

元组类型

元组（Tuple）可以将多个不同的类型组合在一起，成为一个新的类型。元组类型使用 (T1, T2, ..., TN) 表示，其中 T1 到 TN 可以是任意类型，不同类型间使用逗号（,）连接。元组至少是二元，例如，(Int64, Float64) 表示一个二元组类型，(Int64, Float64, String) 表示一个三元组类型。

元组的长度是固定的，即一旦定义了一个元组类型的实例，它的长度不能再被更改。

元组类型是不可变类型，即一旦定义了一个元组类型的实例，它的内容不能再被更新。例如

var tuple = (true, false)
tuple[0] = false // Error, 'tuple element' can not be assigned

元组类型的字面量

元组类型的字面量使用 (e1, e2, ..., eN) 表示，其中 e1 到 eN 是表达式，多个表达式之间使用逗号分隔。下面的例子中，分别定义了一个 (Int64, Float64) 类型的变量 x，以及一个 (Int64, Float64, String) 类型的变量 y，并且使用元组类型的字面量为它们定义了初值：

let x: (Int64, Float64) = (3, 3.141592)
let y: (Int64, Float64, String) = (3, 3.141592, "PI")

元组支持通过 t[index] 的方式访问某个具体位置的元素，其中 t 是一个元组，index 是下标，并且 index 只能是从 0 开始且小于元组元素个数的整数类型字面量，否则，编译报错。下面的例子中，使用 pi[0] 和 pi[1] 可以分别访问二元组 pi 的第一个元素和第二个元素。

main() {
    var pi = (3.14, "PI")
    println(pi[0])
    println(pi[1])
}

编译并执行上述代码，输出结果为：

3.140000
PI

在赋值表达式中，可使用元组字面量对表达式的右值进行解构，这要求赋值表达式等号左边必须是一个元组字面量，这个元组字面量里面的元素必须都是左值（左值即出现在赋值操作符左边的，可保存值的表达式，具体参见各章节对赋值操作的描述）或者一个元组字面量，当元组字面量中出现 _ 时，表示忽略等号右侧 tuple 对应位置处的求值结果（意味着这个位置处的类型检查总是可以通过的），等号右边的表达式也必须是 tuple 类型，右边 tuple 每个元素的类型必须是对应位置左值类型的子类型。注意，复合赋值不支持这种解构方式。求值顺序上先计算等号右边表达式的值，再对左值部分从左往右逐个赋值，例如：

var a: Int64
var b: String
var c: Unit
var f = { => ((1, "abc"), ())}
((a, b), c) = f() // value of a is 1, value of b is "abc", value of c is '()'
((a, b), _) = ((2, "def"), 3.0) // value of a is 2, value of b is "def", 3.0 is ignored

元组类型的类型参数

可以为元组类型标记显式的类型参数名，下面例子中的 name 和 price 就是 类型参数名。

func getFruitPrice (): (name: String, price: Int64) {
    return ("banana", 10)
}

对于一个元组类型，只允许统一写类型参数名，或者统一不写类型参数名，不允许交替存在。

let c: (name: String, Int64) = ("banana", 5)   // Error

数组类型

Array

我们可以使用 Array 类型来构造单一元素类型，有序序列的数据。

仓颉使用 Array<T> 来表示 Array 类型。T 表示 Array 的元素类型，T 可以是任意类型。

var a: Array<Int64> = ... // Array whose element type is Int64
var b: Array<String> = ... // Array whose element type is String

元素类型不相同的 Array 是不相同的类型，所以它们之间不可以互相赋值。

因此以下例子是不合法的。

b = a // Type mismatch

我们可以轻松使用字面量来初始化一个 Array，只需要使用方括号将逗号分隔的值列表括起来即可。

编译器会根据上下文自动推断 Array 字面量的类型。

let a: Array<String> = [] // Created an empty Array whose element type is String
let b = [1, 2, 3, 3, 2, 1] // Created a Array whose element type is Int64, containing elements 1, 2, 3, 3, 2, 1

也可以使用构造函数的方式构造一个指定元素类型的 Array。

需要注意的是，当通过 item 指定的初始值初始化 Array 时，该构造函数不会拷贝 item，如果 item 是一个引用类型，构造后数组的每一个元素都将指向相同的引用。

let a = Array<Int64>() // Created an empty Array whose element type is Int64
let b = Array<Int64>(a) // Use another Array to initialize b
let c = Array<Int64>(3, item: 0) // Created an Array whose element type is Int64, length is 3 and all elements are initialized as 0
let d = Array<Int64>(3, {i => i + 1}) // Created an Array whose element type is Int64, length is 3 and all elements are initialized by the initialization function

访问 Array 成员

当我们需要对 Array 的所有元素进行访问时，可以使用 for-in 循环遍历 Array 的所有元素。

Array 是按元素插入顺序排列的，因此对 Array 遍历的顺序总是恒定的。

main() {
    let arr = [0, 1, 2]
    for (i in arr) {
        println("The element is ${i}")
    }
}

编译并执行上面的代码，会输出：

The element is 0
The element is 1
The element is 2

当我们需要知道某个 Array 包含的元素个数时，可以使用 size 属性获得对应信息。

main() {
    let arr = [0, 1, 2]
    if (arr.size == 0) {
        println("This is an empty array")
    } else {
        println("The size of array is ${arr.size}")
    }
}

编译并执行上面的代码，会输出：

The size of array is 3

当我们想访问单个指定位置的元素时，可以使用下标语法访问（下标的类型必须是 Int64）。非空 Array 的第一个元素总是从位置 0 开始的。我们可以从 0 开始访问 Array 的任意一个元素，直到最后一个位置（Array 的 size - 1）。索引值不能使用负数或者大于等于 size，当编译器能检查出索引值非法时，会在编译时报错，否则会在运行时抛异常。

main() {
    let arr = [0, 1, 2]
    let a = arr[0] // a == 0
    let b = arr[1] // b == 1
    let c = arr[-1] // array size is '3', but access index is '-1', which would overflow
}

如果我们想获取某一段 Array 的元素，可以在下标中传入 Range 类型的值，就可以一次性取得 Range 对应范围的一段 Array。

let arr1 = [0, 1, 2, 3, 4, 5, 6]
let arr2 = arr1[0..5] // arr2 contains the elements 0, 1, 2, 3, 4

当 Range 字面量在下标语法中使用时，我们可以省略 start 或 end。

当省略 start 时，Range 会从 0 开始；当省略 end 时，Range 的 end 会延续到最后一位。

let arr1 = [0, 1, 2, 3, 4, 5, 6]
let arr2 = arr1[..3] // arr2 contains elements 0, 1, 2
let arr3 = arr1[2..] // arr3 contains elements 2, 3, 4, 5, 6

修改 Array

Array 是一种长度不变的 Collection 类型，因此 Array 没有提供添加和删除元素的成员函数。

但是 Array 允许我们对其中的元素进行修改，同样使用下标语法。

main() {
    let arr = [0, 1, 2, 3, 4, 5]
    arr[0] = 3
    println("The first element is ${arr[0]}")
}

编译并执行上面的代码，会输出：

The first element is 3

Array 是引用类型，因此 Array 在作为表达式使用时不会拷贝副本，同一个 Array 实例的所有引用都会共享同样的数据。

因此对 Array 元素的修改会影响到该实例的所有引用。

let arr1 = [0, 1, 2]
let arr2 = arr1
arr2[0] = 3
// arr1 contains elements 3, 1, 2
// arr2 contains elements 3, 1, 2

VArray

仓颉编程语言引入了值类型数组 VArray<T, $N> ，其中 T 表示该值类型数组的元素类型，$N 是一个固定的语法，通过 $ 加上一个数值字面量表示这个值类型数组的长度。需要注意的是，VArray<T, $N> 不能省略 <T, $N>，且使用类型别名时，不允许拆分 VArray 关键字与其泛型参数。

type varr1 = VArray<Int64, $3> // Ok
type varr2 = VArray // Error

注意：

由于运行时后端限制，当前 VArray<T, $N> 的元素类型 T 或 T 的成员不能包含引用类型、枚举类型、Lambda 表达式（CFunc 除外）以及未实例化的泛型类型。

VArray 可以由一个数组的字面量来进行初始化，左值 a 必须标识出 VArray 的实例化类型：

var a: VArray<Int64, $3> = [1, 2, 3]

同时，它拥有两个构造函数：

// VArray<T, $N>(initElement: (Int64) -> T)
let b = VArray<Int64, $5>({ i => i}) // [0, 1, 2, 3, 4]
// VArray<T, $N>(item!: T)
let c = VArray<Int64, $5>(item: 0) // [0, 0, 0, 0, 0]

除此之外，VArray<T, $N> 类型提供了两个成员方法：

• 用于下标访问和修改的 [] 操作符方法：

  var a: VArray<Int64, $3> = [1, 2, 3]
  let i = a[1] // i is 2
  a[2] = 4 // a is [1, 2, 4]
  

• 用于获取 VArray 长度的 size 成员：

  var a: VArray<Int64, $3> = [1, 2, 3]
  let s = a.size // s is 3
  

区间类型

区间类型用于表示拥有固定步长的序列，区间类型是一个泛型（详见泛型章节），使用 Range<T> 表示。当 T 被实例化不同的类型时（要求此类型必须支持关系操作符，并且可以和 Int64 类型的值做加法），会得到不同的区间类型，如最常用的 Range<Int64> 用于表示整数区间。

每个区间类型的实例都会包含 start、end 和 step 三个值。其中，start 和 end 分别表示序列的起始值和终止值，step 表示序列中前后两个元素之间的差值（即步长）；start 和 end 的类型相同（即 T 被实例化的类型），step 类型是 Int64，并且它的值不能等于 0。

下面的例子给出了区间类型的实例化方式（关于区间类型定义和其中的属性，详见《仓颉编程语言库 API》）：

// Range<T>(start: T, end: T, step: Int64, hasStart: Bool, hasEnd: Bool, isClosed: Bool)
let r1 = Range<Int64>(0, 10, 1, true, true, true) // r1 contains 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
let r2 = Range<Int64>(0, 10, 1, true, true, false) // r2 contains 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
let r3 = Range<Int64>(10, 0, -2, true, true, false) // r3 contains 10, 8, 6, 4, 2

区间类型字面量

区间字面量有两种形式：“左闭右开”区间和“左闭右闭”区间。

• “左闭右开”区间的格式是 start..end : step，它表示一个从 start 开始，以 step 为步长，到 end（不包含 end）为止的区间；
• “左闭右闭”区间的格式是 start..=end : step，它表示一个从 start 开始，以 step 为步长，到 end（包含 end）为止的区间。

下面的例子定义了若干区间类型的变量：

let n = 10
let r1 = 0..10 : 1   // r1 contains 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
let r2 = 0..=n : 1   // r2 contains 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
let r3 = n..0 : -2   // r3 contains 10, 8, 6, 4, 2
let r4 = 10..=0 : -2 // r4 contains 10, 8, 6, 4, 2, 0

区间字面量中，可以不写 step，此时 step 默认等于 1，但是注意，step 的值不能等于 0。另外，区间也有可能是空的（即不包含任何元素的空序列），举例如下：

let r5 = 0..10   // the step of r5 is 1, and it contains 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
let r6 = 0..10 : 0 // Error, step cannot be 0

let r7 = 10..0 : 1 // r7 to r10 are empty ranges
let r8 = 0..10 : -1
let r9 = 10..=0 : 1
let r10 = 0..=10 : -1

注意：

• 表达式 start..end : step 中，当 step > 0 且 start >= end，或者 step < 0 且 start <= end 时，start..end : step 是一个空区间；
• 表达式 start..=end : step 中，当 step > 0 且 start > end，或者 step < 0 且 start < end 时，start..=end : step 是一个空区间。

Unit 类型

对于那些只关心副作用而不关心值的表达式，它们的类型是 Unit。例如，print 函数、赋值表达式、复合赋值表达式、自增和自减表达式、循环表达式，它们的类型都是 Unit。

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

Nothing 类型

Nothing 是一种特殊的类型，它不包含任何值，并且 Nothing 类型是所有类型的子类型。

break、continue、return 和 throw 表达式的类型是 Nothing，程序执行到这些表达式时，它们之后的代码将不会被执行。其中 break、continue 只能在循环体中使用，return 只能在函数体中使用。

包围着的循环体“无法穿越”函数边界。在下面的例子中，break 出现在函数 f 中，外层的 while 循环体不被视作包围着它的循环体；continue 出现在 lambda 表达式中，外层的 while 循环体不被视作包围着它的循环体。

while (true) {
    func f() {
        break // Error, break must be used directly inside a loop
    }
    let g = { =>
        continue // Error, continue must be used directly inside a loop
    }
}

由于函数的形参和其默认值不属于该函数的函数体，所以下面例子中的 return 表达式缺少包围它的函数体——它既不属于外层函数 f（因为内层函数定义 g 已经开始），也不在内层函数 g 的函数体中：

func f() {
    func g(x!: Int64 = return) { // Error, return must be used inside a function body
        0
    }
    1
}

注意：

目前编译器还不允许在使用类型的地方显式地使用 Nothing 类型。

定义函数

仓颉使用关键字 func 来表示函数定义的开始，func 之后依次是函数名、参数列表、可选的函数返回值类型、函数体。其中，函数名可以是任意的合法标识符，参数列表定义在一对圆括号内（多个参数间使用逗号分隔），参数列表和函数返回值类型（如果存在）之间使用冒号分隔，函数体定义在一对花括号内。

函数定义举例：

func add(a: Int64, b: Int64): Int64 {
    return a + b
}

上例中定义了一个名为 add 的函数，其参数列表由两个 Int64 类型的参数 a 和 b 组成，函数返回值类型为 Int64，函数体中将 a 和 b 相加并返回。

下面依次对函数定义中的参数列表、函数返回值类型和函数体作进一步介绍。

参数列表

一个函数可以拥有 0 个或多个参数，这些参数均定义在函数的参数列表中。根据函数调用时是否需要给定参数名，可以将参数列表中的参数分为两类：非命名参数和命名参数。

非命名参数的定义方式是 p: T，其中 p 表示参数名，T 表示参数 p 的类型，参数名和其类型间使用冒号连接。例如，上例中 add 函数的两个参数 a 和 b 均为非命名参数。

命名参数的定义方式是 p!: T，与非命名参数的不同是在参数名 p 之后多了一个 !。可以将上例中 add 函数的两个非命名参数修改为命名参数，如下所示：

func add(a!: Int64, b!: Int64): Int64 {
    return a + b
}

命名参数还可以设置默认值，通过 p!: T = e 方式将参数 p 的默认值设置为表达式 e 的值。例如，可以将上述 add 函数的两个参数的默认值都设置为 1：

func add(a!: Int64 = 1, b!: Int64 = 1): Int64 {
    return a + b
}

注意：

只能为命名参数设置默认值，不能为非命名参数设置默认值。

参数列表中可以同时定义非命名参数和命名参数，但是需要注意的是，非命名参数只能定义在命名参数之前，也就意味着命名参数之后不能再出现非命名参数。例如，下例中 add 函数的参数列表定义是不合法的：

func add(a!: Int64, b: Int64): Int64 { // Error, named parameter 'a' must be defined after non-named parameter 'b'
    return a + b
}

非命名参数和命名参数的主要差异在于调用时的不同，具体可参见下文调用函数中的介绍。

函数参数均为不可变变量，在函数定义内不能对其赋值。

func add(a: Int64, b: Int64): Int64 {
    a = a + b // Error
    return a
}

函数参数作用域从定义处起至函数体结束：

func add(a: Int64, b: Int64): Int64 {
    var a_ = a // OK
    var b = b  // Error, redefinition of declaration 'b'
    return a
}

函数返回值类型

函数返回值类型是函数被调用后得到的值的类型。函数定义时，返回值类型是可选的：可以显式地定义返回值类型（返回值类型定义在参数列表和函数体之间），也可以不定义返回值类型，交由编译器推导确定。

当显式地定义了函数返回值类型时，就要求函数体的类型（关于如何确定函数体的类型可参见下节函数体）、函数体中所有 return e 表达式中 e 的类型是返回值类型的子类型。例如，对于上述 add 函数，显式地定义了它的返回值类型为 Int64，如果将函数体中的 return a + b 修改为 return (a, b)，则会因为类型不匹配而报错：

// Error, the type of the expression after return does not match the return type of the function
func add(a: Int64, b: Int64): Int64 {
    return (a, b)
}

在函数定义时如果未显式定义返回值类型，编译器将根据函数体的类型以及函数体中所有的 return 表达式来共同推导出函数的返回值类型。例如，下例中 add 函数的返回值类型虽然被省略，但编译器可以根据 return a + b 推导出 add 函数的返回值类型是 Int64：

func add(a: Int64, b: Int64) {
    return a + b
}

注意：

函数的返回值类型并不是任何情况下都可以被推导出来的，如果返回值类型推导失败，编译器会报错。

函数体

函数体中定义了函数被调用时执行的操作，通常包含一系列的变量定义和表达式，也可以包含新的函数定义（即嵌套函数）。如下 add 函数的函数体中首先定义了 Int64 类型的变量 r（初始值为 0），接着将 a + b 的值赋值给 r，最后将 r 的值返回：

func add(a: Int64, b: Int64) {
    var r = 0
    r = a + b
    return r
}

在函数体的任意位置都可以使用 return 表达式来终止函数的执行并返回。return 表达式有两种形式：return 和 return expr（expr 是一个表达式）。

对于 return expr，要求 expr 的类型与函数定义中的返回值类型保持一致。例如，下例中会因为 return 100 中 100 类型（Int64）和函数 foo 的返回值类型（String）不同而报错。

// Error, cannot convert an integer literal to type 'Struct-String'
func foo(): String {
    return 100
}

对于 return，其等价于 return ()，所以要求函数的返回值类型为 Unit。

func add(a: Int64, b: Int64) {
    var r = 0
    r = a + b
    return r
}

func foo(): Unit {
    add(1, 2)
    return
}

注意：

return 表达式作为一个整体，其类型并不由后面跟随的表达式决定，而是 Nothing 类型。

在函数体内定义的变量属于局部变量的一种（如上例中的 r 变量），它的作用域从其定义之后开始到函数体结束。

对于一个局部变量，允许在其外层作用域中定义同名变量，并且在此局部变量的作用域内，局部变量会“遮盖”外层作用域的同名变量。例如：

let r = 0
func add(a: Int64, b: Int64) {
    var r = 0
    r = a + b
    return r
}

上例中，add 函数之前定义了 Int64 类型的全局变量 r，同时 add 函数体内定义了同名的局部变量 r，那么在函数体内，所有使用变量 r 的地方（如 r = a + b），用到的将是局部变量 r，即（在函数体内）局部变量 r “遮盖”了全局变量 r。

函数返回值类型中我们提到函数体也是有类型的，函数体的类型是函数体内最后一“项”的类型：若最后一项为表达式，则函数体的类型是此表达式的类型，若最后一项为变量定义或函数声明，或函数体为空，则函数体的类型为 Unit。例如：

func add(a: Int64, b: Int64): Int64 {
    a + b
}

上例中，因为函数体的最后一“项”是 Int64 类型的表达式（即 a + b），所以函数体的类型也是 Int64，与函数定义的返回值类型相匹配。又如，下例中函数体的最后一项是 print 函数调用，所以函数体的类型是 Unit，同样与函数定义的返回值类型相匹配：

func foo(): Unit {
    let s = "Hello"
    print(s)
}

调用函数

函数调用的形式为 f(arg1, arg2, ..., argn)。其中，f 是要调用的函数的名字，arg1 到 argn 是 n 个调用时的参数（称为实参），要求每个实参的类型必须是对应参数类型的子类型。实参可以有 0 个或多个，当实参个数为 0 时，调用方式为 f()。

根据函数定义时参数是非命名参数还是命名参数的不同，函数调用时传实参的方式也有所不同：对于非命名参数，它对应的实参是一个表达式，对于命名参数，它对应的实参需要使用 p: e 的形式，其中 p 是命名参数的名字，e 是表达式（即传递给参数 p 的值）。

非命名参数调用举例：

func add(a: Int64, b: Int64) {
    return a + b
}

main() {
    let x = 1
    let y = 2
    let r = add(x, y)
    println("The sum of x and y is ${r}")
}

执行结果为：

The sum of x and y is 3

命名参数调用举例：

func add(a: Int64, b!: Int64) {
    return a + b
}

main() {
    let x = 1
    let y = 2
    let r = add(x, b: y)
    println("The sum of x and y is ${r}")
}

执行结果为：

The sum of x and y is 3

对于多个命名参数，调用时的传参顺序可以和定义时的参数顺序不同。例如，下例中调用 add 函数时 b 可以出现在 a 之前：

func add(a!: Int64, b!: Int64) {
    return a + b
}

main() {
    let x = 1
    let y = 2
    let r = add(b: y, a: x)
    println("The sum of x and y is ${r}")
}

执行结果为：

The sum of x and y is 3

对于拥有默认值的命名参数，调用时如果没有传实参，那么此参数将使用默认值作为实参的值。例如，下例中调用 add 函数时没有为参数 b 传实参，那么参数 b 的值等于其定义时的默认值 2：

func add(a: Int64, b!: Int64 = 2) {
    return a + b
}

main() {
    let x = 1
    let r = add(x)
    println("The sum of x and y is ${r}")
}

执行结果为：

The sum of x and y is 3

对于拥有默认值的命名参数，调用时也可以为其传递新的实参，此时命名参数的值等于新的实参的值，即定义时的默认值将失效。例如，下例中调用 add 函数时为参数 b 传了新的实参值 20，那么参数 b 的值就等于 20：

func add(a: Int64, b!: Int64 = 2) {
    return a + b
}

main() {
    let x = 1
    let r = add(x, b: 20)
    println("The sum of x and y is ${r}")
}

执行结果为：

The sum of x and y is 21

函数类型

仓颉编程语言中，函数是一等公民（first-class citizens），可以作为函数的参数或返回值，也可以赋值给变量。因此函数本身也有类型，称之为函数类型。

函数类型由函数的参数类型和返回类型组成，参数类型和返回类型之间使用 -> 连接。参数类型使用圆括号 () 括起来，可以有 0 个或多个参数，如果参数超过一个，参数类型之间使用逗号（,）分隔。

例如：

func hello(): Unit {
    println("Hello!")
}

上述示例定义了一个函数，函数名为 hello，其类型是 () -> Unit，表示该函数没有参数，返回类型为 Unit。

以下给出另一些示例：

• 示例：函数名为 display，其类型是 (Int64) -> Unit，表示该函数有一个参数，参数类型为 Int64，返回类型为 Unit。

  func display(a: Int64): Unit {
      println(a)
  }
  

• 示例：函数名为 add，其类型是 (Int64, Int64) -> Int64，表示该函数有两个参数，两个参数类型均为 Int64，返回类型为 Int64。

  func add(a: Int64, b: Int64): Int64 {
      a + b
  }
  

• 示例：函数名为 returnTuple，其类型是 (Int64, Int64) -> (Int64, Int64)，两个参数类型均为 Int64, 返回类型为元组类型：(Int64, Int64)。

  func returnTuple(a: Int64, b: Int64): (Int64, Int64) {
      (a, b)
  }
  

函数类型的类型参数

可以为函数类型标记显式的类型参数名，下面例子中的 name 和 price 就是 类型参数名。

main() {
    let fruitPriceHandler: (name: String, price: Int64) -> Unit
    fruitPriceHandler = {n, p => println("fruit: ${n} price: ${p} yuan")}
    fruitPriceHandler("banana", 10)
}

另外对于一个函数类型，只允许统一写类型参数名，或者统一不写类型参数名，不能交替存在。

let handler: (name: String, Int64) -> Int64   // Error

函数类型作为参数类型

示例：函数名为 printAdd，其类型是 ((Int64, Int64) -> Int64, Int64, Int64) -> Unit，表示该函数有三个参数，参数类型分别为函数类型 (Int64, Int64) -> Int64 和两个 Int64，返回类型为 Unit。

func printAdd(add: (Int64, Int64) -> Int64, a: Int64, b: Int64): Unit {
    println(add(a, b))
}

函数类型作为返回类型

函数类型可以作为另一个函数的返回类型。

如下示例中，函数名为 returnAdd，其类型是 () -> (Int64, Int64) -> Int64，表示该函数无参数，返回类型为函数类型 (Int64, Int64) -> Int64。注意，-> 是右结合的。

func add(a: Int64, b: Int64): Int64 {
    a + b
}

func returnAdd(): (Int64, Int64) -> Int64 {
    add
}

main() {
    var a = returnAdd()
    println(a(1,2))
}

函数类型作为变量类型

函数名本身也是表达式，它的类型为对应的函数类型。

func add(p1: Int64, p2: Int64): Int64 {
    p1 + p2
}

let f: (Int64, Int64) -> Int64 = add

上述示例中，函数名是 add，其类型为 (Int64, Int64) -> Int64。变量 f 的类型与 add 类型相同，add 被用来初始化 f。

若一个函数在当前作用域中被重载（见函数重载）了，那么直接使用该函数名作为表达式可能产生歧义，如果产生歧义编译器会报错，例如：

func add(i: Int64, j: Int64) {
    i + j
}

func add(i: Float64, j: Float64) {
    i + j
}

main() {
    var f = add   // Error, ambiguous function 'add'
    var plus: (Int64, Int64) -> Int64 = add  // OK
}

嵌套函数

定义在源文件顶层的函数被称为全局函数。定义在函数体内的函数被称为嵌套函数。

示例，函数 foo 内定义了一个嵌套函数 nestAdd，可以在 foo 内调用该嵌套函数 nestAdd，也可以将嵌套函数 nestAdd 作为返回值返回，在 foo 外对其进行调用：

func foo() {
    func nestAdd(a: Int64, b: Int64) {
        a + b + 3
    }

    println(nestAdd(1, 2))  // 6

    return nestAdd
}

main() {
    let f = foo()
    let x = f(1, 2)
    println("result: ${x}")
}

程序会输出：

6
result: 6

Lambda 表达式

Lambda 表达式定义

Lambda 表达式的语法为如下形式： { p1: T1, ..., pn: Tn => expressions | declarations }。

其中，=> 之前为参数列表，多个参数之间使用 , 分隔，每个参数名和参数类型之间使用 : 分隔。=> 之前也可以没有参数。=> 之后为 lambda 表达式体，是一组表达式或声明序列。Lambda 表达式的参数名的作用域与函数的相同，为 lambda 表达式的函数体部分，其作用域级别可视为与 lambda 表达式的函数体内定义的变量等同。

let f1 = { a: Int64, b: Int64 => a + b }

var display = { => println("Hello") }   // Parameterless lambda expression.

Lambda 表达式不管有没有参数，都不可以省略 =>，除非其作为尾随 lambda。例如：

var display = { => println("Hello") }

func f2(lam: () -> Unit) { }
let f2Res = f2{ println("World") } // OK to omit the =>

Lambda 表达式中参数的类型标注可缺省。以下情形中，若参数类型省略，编译器会尝试进行类型推断，当编译器无法推断出类型时会编译报错：

• Lambda 表达式赋值给变量时，其参数类型根据变量类型推断；
• Lambda 表达式作为函数调用表达式的实参使用时，其参数类型根据函数的形参类型推断。

// The parameter types are inferred from the type of the variable sum1
var sum1: (Int64, Int64) -> Int64 = { a, b => a + b }

var sum2: (Int64, Int64) -> Int64 = { a: Int64, b => a + b }

func f(a1: (Int64) -> Int64): Int64 {
    a1(1)
}

main(): Int64 {
    // The parameter type of lambda is inferred from the type of function f
    f({ a2 => a2 + 10 })
}

Lambda 表达式中不支持声明返回类型，其返回类型总是从上下文中推断出来，若无法推断则报错。

• 若上下文明确指定了 lambda 表达式的返回类型，则其返回类型为上下文指定的类型。

  • Lambda 表达式赋值给变量时，其返回类型根据变量类型推断返回类型：

    let f: () -> Unit = { ... }
    

  • Lambda 表达式作为参数使用时，其返回类型根据使用处所在的函数调用的形参类型推断：

    func f(a1: (Int64) -> Int64): Int64 {
        a1(1)
    }
    
    main(): Int64 {
        f({ a2: Int64 => a2 + 10 })
    }
    

  • Lambda 表达式作为返回值使用时，其返回类型根据使用处所在函数的返回类型推断：

    func f(): (Int64) -> Int64 {
        { a: Int64 => a }
    }
    

• 若上下文中类型未明确，与推导函数的返回值类型类似，编译器会根据 lambda 表达式体中所有 return 表达式 return xxx 中 xxx 的类型，以及 lambda 表达式体的类型，来共同推导出 lambda 表达式的返回类型。

  • => 右侧的内容与普通函数体的规则一样，返回类型为 Int64:

    let sum1 = { a: Int64, b: Int64 => a + b }
    

  • => 的右侧为空，返回类型为 Unit:

    let f = { => }
    

Lambda 表达式调用

Lambda 表达式支持立即调用，例如：

let r1 = { a: Int64, b: Int64 => a + b }(1, 2) // r1 = 3
let r2 = { => 123 }()                          // r2 = 123

Lambda 表达式也可以赋值给一个变量，使用变量名进行调用，例如：

func f() {
    var g = { x: Int64 => println("x = ${x}") }
    g(2)
}

闭包

一个函数或 lambda 从定义它的静态作用域中捕获了变量，函数或 lambda 和捕获的变量一起被称为一个闭包，这样即使脱离了闭包定义所在的作用域，闭包也能正常运行。

函数或 lambda 的定义中对于以下几种变量的访问，称为变量捕获：

• 函数的参数缺省值中访问了本函数之外定义的局部变量；

• 函数或 lambda 内访问了本函数或本 lambda 之外定义的局部变量;

• class/struct 内定义的不是成员函数的函数或 lambda 访问了实例成员变量或 this。

以下情形的变量访问不是变量捕获：

• 对定义在本函数或本 lambda 内的局部变量的访问；

• 对本函数或本 lambda 的形参的访问；

• 对全局变量和静态成员变量的访问；

• 对实例成员变量在实例成员函数或属性中的访问。由于实例成员函数或属性将 this 作为参数传入，在实例成员函数或属性内通过 this 访问所有实例成员变量。

变量的捕获发生在闭包定义时，因此变量捕获有以下规则：

• 被捕获的变量必须在闭包定义时可见，否则编译报错；

• 被捕获的变量必须在闭包定义时已经完成初始化，否则编译报错。

示例 1：闭包 add，捕获了 let 声明的局部变量 num，之后通过返回值返回到 num 定义的作用域之外，调用 add 时仍可正常访问 num。

func returnAddNum(): (Int64) -> Int64 {
    let num: Int64 = 10

    func add(a: Int64) {
        return a + num
    }
    add
}

main() {
    let f = returnAddNum()
    println(f(10))
}

程序输出的结果为：

20

示例 2：捕获的变量必须在闭包定义时可见。

func f() {
    let x = 99
    func f1() {
        println(x)
    }
    let f2 = { =>
        println(y)      // Error, cannot capture 'y' which is not defined yet
    }
    let y = 88
    f1()          // Print 99.
    f2()
}

示例 3：捕获的变量必须在闭包定义前完成初始化。

func f() {
    let x: Int64
    func f1() {
        println(x)    // Error, x is not initialized yet.
    }
    x = 99
    f1()
}

如果捕获的变量是引用类型，可修改其可变实例成员变量的值。

class C {
    public var num: Int64 = 0
}

func returnIncrementer(): () -> Unit {
    let c: C = C()

    func incrementer() {
        c.num++
    }

    incrementer
}

main() {
    let f = returnIncrementer()
    f() // c.num increases by 1
}

为了防止捕获了 var 声明变量的闭包逃逸，这类闭包只能被调用，不能作为一等公民使用，包括不能赋值给变量，不能作为实参或返回值使用，不能直接将闭包的名字作为表达式使用。

func f() {
    var x = 1
    let y = 2

    func g() {
        println(x)  // OK, captured a mutable variable.
    }
    let b = g  // Error, g cannot be assigned to a variable

    g  // Error, g cannot be used as an expression
    g()  // OK, g can be invoked

    g  // Error, g cannot be used as a return value.
}

需要注意的是，捕获具有传递性，如果一个函数 f 调用了捕获 var 变量的函数 g，且存在 g 捕获的 var 变量不在函数 f 内定义，那么函数 f 同样捕获了 var 变量，此时，f 也不能作为一等公民使用。

以下示例中，g 捕获了 var 声明的变量 x，f 调用了 g，且 g 捕获的 x 不在 f 内定义，f 同样不能作为一等公民使用：

func h(){
    var x = 1

    func g() {  x }   // captured a mutable variable

    func f() {
        g()      // invoked g
    }
    return f // Error
}

以下示例中，g 捕获了 var 声明的变量 x，f 调用了 g。但 g 捕获的 x 在 f 内定义，f 没有捕获其它 var 声明的变量。因此，f 仍作为一等公民使用：

func h(){
    func f() {
        var x = 1
        func g() { x }   // captured a mutable variable

        g()
    }
    return f // Ok
}

静态成员变量和全局变量的访问，不属于变量捕获，因此访问了 var 修饰的全局变量、静态成员变量的函数或 lambda 仍可作为一等公民使用。

class C {
    static public var a: Int32 = 0
    static public func foo() {
        a++       // OK
        return a
    }
}

var globalV1 = 0

func countGlobalV1() {
    globalV1++
    C.a = 99
    let g = C.foo  // OK
}

func g(){
    let f = countGlobalV1 // OK
    f()
}

函数调用语法糖

尾随 lambda

尾随 lambda 可以使函数的调用看起来像是语言内置的语法一样，增加语言的可扩展性。

当函数最后一个形参是函数类型，并且函数调用对应的实参是 lambda 时，我们可以使用尾随 lambda 语法，将 lambda 放在函数调用的尾部，圆括号外面。

例如，下例中我们定义了一个 myIf 函数，它的第一个参数是 Bool 类型，第二个参数是函数类型。当第一个参数的值为 true 时，返回第二个参数调用后的值，否则返回 0。调用 myIf 时可以像普通函数一样调用，也可以使用尾随 lambda 的方式调用。

func myIf(a: Bool, fn: () -> Int64) {
    if(a) {
        fn()
    } else {
        0
    }
}

func test() {
    myIf(true, { => 100 }) // General function call

    myIf(true) {        // Trailing closure call
        100
    }
}

当函数调用有且只有一个 lambda 实参时，我们还可以省略 ()，只写 lambda。

示例：

func f(fn: (Int64) -> Int64) { fn(1) }

func test() {
    f { i => i * i }
}

Flow 表达式

流操作符包括两种：表示数据流向的中缀操作符 |> （称为 pipeline）和表示函数组合的中缀操作符 ~> （称为 composition）。

Pipeline 表达式

当需要对输入数据做一系列的处理时，可以使用 pipeline 表达式来简化描述。pipeline 表达式的语法形式如下：e1 |> e2。等价于如下形式的语法糖：let v = e1; e2(v) 。

其中 e2 是函数类型的表达式，e1 的类型是 e2 的参数类型的子类型。

示例：

func inc(x: Array<Int64>): Array<Int64> { // Increasing the value of each element in the array by '1'
    let s = x.size
    var i = 0
    for (e in x where i < s) {
        x[i] = e + 1
        i++
    }
    x
}

func sum(y: Array<Int64>): Int64 { // Get the sum of elements in the array.
    var s = 0
    for (j in y) {
        s += j
    }
    s
}

let arr: Array<Int64> = Array<Int64>([1, 3, 5])
let res = arr |> inc |> sum // res = 12

Composition 表达式

composition 表达式表示两个单参函数的组合。composition 表达式语法如下： f ~> g。等价于如下形式： { x => g(f(x)) }。

其中 f，g 均为只有一个参数的函数类型的表达式。

f 和 g 组合，则要求 f(x) 的返回类型是 g(...) 的参数类型的子类型。

示例 1：

func f(x: Int64): Float64 {
    Float64(x)
}
func g(x: Float64): Float64 {
    x
}

var fg = f ~> g // The same as { x: Int64 => g(f(x)) }

示例 2：

func f(x: Int64): Float64 {
    Float64(x)
}

let lambdaComp = ({x: Int64 => x}) ~> f // The same as { x: Int64 => f({x: Int64 => x}(x)) }

示例 3：

func h1<T>(x: T): T { x }
func h2<T>(x: T): T { x }
var hh = h1<Int64> ~> h2<Int64> // The same as { x: Int64 => h2<Int64>(h1<Int64>(x)) }

注意：

表达式 f ~> g 中，会先对 f 求值，然后对 g 求值，最后才会进行函数的组合。

另外，流操作符不能与无默认值的命名形参函数直接一同使用，这是因为无默认值的命名形参函数必须给出命名实参才可以调用。例如：

func f(a!: Int64): Unit {}

var a = 1 |> f  // Error

如果需要使用，用户可以通过 lambda 表达式传入 f 函数的命名实参：

func f(a!: Int64): Unit {}

var x = 1 |>  { x: Int64 => f(a: x) } // Ok

由于相同的原因，当 f 的参数有默认值时，直接与流运算符一起使用也是错误的，例如：

func f(a!: Int64 = 2): Unit {}

var a = 1 |> f // Error

但是当命名形参都存在默认值时，不需要给出命名实参也可以调用该函数，函数仅需要传入非命名形参，那么这种函数是可以同流运算符一起使用的，例如：

func f(a: Int64, b!: Int64 = 2): Unit {}

var a = 1 |> f  // Ok

当然，如果想要在调用f时，为参数 b 传入其他参数，那么也需要借助 lambda 表达式：

func f(a: Int64, b!: Int64 = 2): Unit {}

var a = 1 |> {x: Int64 => f(x,  b: 3)}  // Ok

变长参数

变长参数是一种特殊的函数调用语法糖。当形参最后一个非命名参数是 Array 类型时，实参中对应位置可以直接传入参数序列代替 Array 字面量（参数个数可以是 0 个或多个）。示例如下：

func sum(arr: Array<Int64>) {
    var total = 0
    for (x in arr) {
        total += x
    }
    return total
}

main() {
    println(sum())
    println(sum(1, 2, 3))
}

程序输出：

0
6

需要注意，只有最后一个非命名参数可以作为变长参数，命名参数不能使用这个语法糖。

func length(arr!: Array<Int64>) {
    return arr.size
}

main() {
    println(length())        // Error, expected 1 argument, found 0
    println(length(1, 2, 3)) // Error, expected 1 argument, found 3
}

变长参数可以出现在全局函数、静态成员函数、实例成员函数、局部函数、构造函数、函数变量、lambda、函数调用操作符重载、索引操作符重载的调用处。不支持其他操作符重载、compose、pipeline 这几种调用方式。示例如下：

class Counter {
    var total = 0
    init(data: Array<Int64>) { total = data.size }
    operator func ()(data: Array<Int64>) { total += data.size }
}

main() {
    let counter = Counter(1, 2)
    println(counter.total)
    counter(3, 4, 5)
    println(counter.total)
}

程序输出：

2
5

函数重载决议总是会优先考虑不使用变长参数就能匹配的函数，只有在所有函数都不能匹配，才尝试使用变长参数解析。示例如下：

func f<T>(x: T) where T <: ToString {
    println("item: ${x}")
}

func f(arr: Array<Int64>) {
    println("array: ${arr}")
}

main() {
    f()
    f(1)
    f(1, 2)
}

程序输出：

array: []
item: 1
array: [1, 2]

当编译器无法决议时会报错：

func f(arr: Array<Int64>) { arr.size }
func f(first: Int64, arr: Array<Int64>) { first + arr.size }

main() {
    println(f(1, 2, 3)) // Error
}

函数重载

函数重载定义

在仓颉编程语言中，如果一个作用域中，一个函数名对应多个函数定义，这种现象称为函数重载。

• 函数名相同，函数参数不同（是指参数个数不同，或者参数个数相同但参数类型不同）的两个函数构成重载。示例如下：

  // Scenario 1
  func f(a: Int64): Unit {
  }
  
  func f(a: Float64): Unit {
  }
  
  func f(a: Int64, b: Float64): Unit {
  }
  

• 对于两个同名泛型函数，如果重命名一个函数的泛型形参后，其非泛型部分与另一个函数的非泛型部分函数参数不同，则两个函数构成重载，否则这两个泛型函数构成重复定义错误（类型变元的约束不参与判断）。示例如下：

  interface I1{}
  interface I2{}
  
  func f1<X, Y>(a: X, b: Y) {}
  func f1<Y, X>(a: X, b: Y) {} // Ok: after rename generic type parameter, it will be 'func f1<X, Y>(a: Y, b: X)'
  
  func f2<T>(a: T) where T <: I1 {}
  func f2<T>(a: T) where T <: I2 {} // Error, not overloading
  

• 同一个类内的两个构造函数参数不同，构成重载。示例如下：

  // Scenario 2
  class C {
      var a: Int64
      var b: Float64
  
      public init(a: Int64, b: Float64) {
          this.a = a
          this.b = b
      }
  
      public init(a: Int64) {
          b = 0.0
          this.a = a
      }
  }
  

• 同一个类内的主构造函数和 init 构造函数参数不同，构成重载（认为主构造函数和 init 函数具有相同的名字）。示例如下：

  // Scenario 3
  class C {
      C(var a!: Int64, var b!: Float64) {
          this.a = a
          this.b = b
      }
  
      public init(a: Int64) {
          b = 0.0
          this.a = a
      }
  }
  

• 两个函数定义在不同的作用域，在两个函数可见的作用域中构成重载。示例如下：

  // Scenario 4
  func f(a: Int64): Unit {
  }
  
  func g() {
      func f(a: Float64): Unit {
      }
  }
  

• 两个函数分别定义在父类和子类中，在两个函数可见的作用域中构成重载。示例如下：

  // Scenario 5
  open class Base {
      public func f(a: Int64): Unit {
      }
  }
  
  class Sub <: Base {
      public func f(a: Float64): Unit {
      }
  }
  

只允许函数声明引入的函数重载，但是以下情形不构成重载，不构成重载的两个名字不能定义或声明在同一个作用域内：

• class、interface、struct 类型的静态成员函数和实例成员函数之间不能重载
• enum 类型的 constructor、静态成员函数和实例成员函数之间不能重载

如下示例，两个变量均为函数类型且函数参数类型不同，但由于它们不是函数声明所以不能重载，如下示例将编译报错（重定义错）：

main() {
    var f: (Int64) -> Unit
    var f: (Float64) -> Unit
}

如下示例，虽然变量 f 为函数类型，但由于变量和函数之间不能同名，如下示例将编译报错（重定义错）：

main() {
    var f: (Int64) -> Unit

    func f(a: Float64): Unit {   // Error, functions and variables cannot have the same name.
    }
}

如下示例，静态成员函数 f 与实例成员函数 f 的参数类型不同，但由于类内静态成员函数和实例成员函数之间不能重载，如下示例将编译报错：

class C {
    public static func f(a: Int64): Unit {
    }
    public func f(a: Float64): Unit {
    }
}

函数重载决议

函数调用时，所有可被调用的函数（是指当前作用域可见且能通过类型检查的函数）构成候选集，候选集中有多个函数，究竟选择候选集中哪个函数，需要进行函数重载决议，有如下规则：

• 优先选择作用域级别高的作用域内的函数。在嵌套的表达式或函数中，越是内层作用域级别越高。

  如下示例中在 inner 函数体内调用 g(Sub()) 时，候选集包括 inner 函数内定义的函数 g 和 inner 函数外定义的函数 g，函数决议选择作用域级别更高的 inner 函数内定义的函数 g。

  open class Base {}
  class Sub <: Base {}
  
  func outer() {
      func g(a: Sub) {
          print("1")
      }
  
      func inner() {
          func g(a: Base) {
              print("2")
          }
  
          g(Sub())   // Output: 2
      }
  }
  

• 如果作用域级别相对最高的仍有多个函数，则需要选择最匹配的函数（对于函数 f 和 g 以及给定的实参，如果 f 可以被调用时 g 也总是可以被调用的，但反之不然，则我们称 f 比 g 更匹配）。如果不存在唯一最匹配的函数，则报错。

  如下示例中，两个函数 g 定义在同一作用域，选择更匹配的函数 g(a: Sub): Unit。

  open class Base {}
  class Sub <: Base {}
  
  func outer() {
      func g(a: Sub) {
          print("1")
      }
      func g(a: Base) {
          print("2")
      }
  
      g(Sub())   // Output: 1
  
  }
  

• 子类和父类认为是同一作用域。如下示例中，一个函数 g 定义在父类中，另一个函数 g 定义在子类中，在调用 s.g(Sub()) 时，两个函数 g 当成同一作用域级别决议，则选择更匹配的父类中定义的函数 g(a: Sub): Unit。

  open class Base {
      public func g(a: Sub) { print("1") }
  }
  
  class Sub <: Base {
      public func g(a: Base) {
          print("2")
      }
  }
  
  func outer() {
      let s: Sub = Sub()
      s.g(Sub())   // Output: 1
  }
  

操作符重载

如果希望在某个类型上支持此类型默认不支持的操作符，可以使用操作符重载实现。

如果需要在某个类型上重载某个操作符，可以通过为类型定义一个函数名为此操作符的函数的方式实现，这样，在该类型的实例使用该操作符时，就会自动调用此操作符函数。

操作符函数定义与普通函数定义相似，区别如下：

• 定义操作符函数时需要在 func 关键字前面添加 operator 修饰符；
• 操作符函数的参数个数需要匹配对应操作符的要求（详见附录操作符）；
• 操作符函数只能定义在 class、interface、struct、enum 和 extend 中；
• 操作符函数具有实例成员函数的语义，所以禁止使用 static 修饰符；
• 操作符函数不能为泛型函数。

另外，需要注意的是，被重载后的操作符不改变它们固有的优先级和结合性（详见附录操作符）。

操作符重载函数定义和使用

定义操作符函数有两种方式：

1. 对于可以直接包含函数定义的类型 (包括 struct、enum、class 和 interface )，可以直接在其内部定义操作符函数的方式实现操作符的重载。
2. 使用 extend 的方式为其添加操作符函数，从而实现操作符在这些类型上的重载。对于无法直接包含函数定义的类型（是指除 struct、class、enum 和 interface 之外其他的类型）或无法改变其实现的类型，比如第三方定义的 struct、class、enum 和 interface，只能采用这种方式（参见扩展）；

操作符函数对参数类型的约定如下：

1. 对于一元操作符，操作符函数没有参数，对返回值的类型没有要求。

2. 对于二元操作符，操作符函数只有一个参数，对返回值的类型没有要求。

   如下示例中介绍了一元操作符和二元操作符的定义和使用：

   - 实现对一个 Point 实例中两个成员变量 x 和 y 取负值，然后返回一个新的 Point 对象，+ 实现对两个 Point 实例中两个成员变量 x 和 y 分别求和，然后返回一个新的 Point 对象。

   open class Point {
       var x: Int64 = 0
       var y: Int64 = 0
       public init (a: Int64, b: Int64) {
           x = a
           y = b
       }
   
       public operator func -(): Point {
           Point(-x, -y)
       }
       public operator func +(right: Point): Point {
           Point(this.x + right.x, this.y + right.y)
       }
   }
   

   接下来，就可以在 Point 的实例上直接使用一元 - 操作符和二元 + 操作符：

   main() {
       let p1 = Point(8, 24)
       let p2 = -p1      // p2 = Point(-8, -24)
       let p3 = p1 + p2  // p3 = Point(0, 0)
   }
   

3. 索引操作符（[]）分为取值 let a = arr[i] 和赋值 arr[i] = a 两种形式，它们通过是否存在特殊的命名参数 value 来区分不同的重载。索引操作符重载不要求同时重载两种形式，可以只重载赋值不重载取值，反之亦可。

   索引操作符取值形式 [] 内的参数序列对应操作符重载的非命名参数，可以是 1 个或多个，可以是任意类型。不可以有其它命名参数。返回类型可以是任意类型。

   class A {
       operator func [](arg1: Int64, arg2: String): Int64 {
           return 0
       }
   }
   
   func f() {
       let a = A()
       let b: Int64 = a[1, "2"]
       // b == 0
   }
   

   索引操作符赋值形式 [] 内的参数序列对应操作符重载的非命名参数，可以是 1 个或多个，可以是任意类型。= 右侧的表达式对应操作符重载的命名参数，有且只能有一个命名参数，该命名参数的名称必须是 value, 不能有默认值，value 可以是任意类型。返回类型必须是 Unit 类型。

   需要注意的是，value 只是一种特殊的标记，在索引操作符赋值时并不需要使用命名参数的形式调用。

   class A {
       operator func [](arg1: Int64, arg2: String, value!: Int64): Unit {
           return
       }
   }
   
   func f() {
       let a = A()
       a[1, "2"] = 0
   }
   

   特别的，除 enum 外的不可变类型不支持重载索引操作符赋值形式。

4. 函数调用操作符（()）重载函数，输入参数和返回值类型可以是任意类型。示例如下：

   open class A {
       public init() {}
   
       public operator func ()(): Unit {}
   }
   
   func test1() {
       let a = A() // Ok, A() is call the constructor of A.
       a() // Ok, a() is to call the operator () overloading function.
   }
   

   不能使用 this 或 super 调用 () 操作符重载函数。示例如下：

   open class A {
       public init() {}
       public init(x: Int64) {
           this() // Ok, this() calls the constructor of A.
       }
   
       public operator func ()(): Unit {}
   
       public func foo() {
           this()  // Error, this() calls the constructor of A.
           super() // Error
       }
   }
   
   class B <: A {
       public init() {
           super() // Ok, super()  calls the constuctor of the super class.
       }
   
       public func goo() {
           super() // Error
       }
   }
   

   对于枚举类型，当构造器形式和 () 操作符重载函数形式都满足时，优先匹配构造器形式。示例如下：

   enum E {
       Y | X | X(Int64)
   
       public operator func ()(p: Int64) {}
       public operator func ()(p: Float64) {}
   }
   
   main() {
       let e = X(1) // Ok, X(1) is to call the constructor X(Int64).
       X(1.0) // Ok, X(1.0) is to call the operator () overloading function.
       let e1 = X
       e1(1) // Ok, e1(1) is to call the operator () overloading function.
       Y(1) // oK, Y(1) is to call the operator () overloading function.
   }
   

可以被重载的操作符

下表列出了所有可以被重载的操作符（优先级从高到低）：

需要注意的是：

1. 一旦在某个类型上重载了除关系操作符（<、<=、>、>=、==和!=）之外的其他二元操作符，并且操作符函数的返回类型与左操作数的类型一致或是其子类型，那么此类型支持对应的复合赋值操作符。当操作符函数的返回类型与左操作数的类型不一致且不是其子类型时，在使用对应的复合赋值符号时将报类型不匹配错误。
2. 仓颉编程语言不支持自定义操作符，即不允许定义除上表中所列 operator 之外的其他操作符函数。
3. 对于类型 T, 如果 T 已经默认支持了上述若干可重载操作符，那么通过扩展的方式再次为其实现同签名的操作符函数时将报重定义错误。例如，为数值类型重载其已支持的同签名算术操作符、位操作符或关系操作符等操作符时，为 Rune 重载同签名的关系操作符时，为 Bool 类型重载同签名的逻辑操作符、判等或不等操作符时，等等这些情况，均会报重定义错误。

const 函数和常量求值

常量求值允许某些特定形式的表达式在编译时求值，可以减少程序运行时需要的计算。本章主要介绍常量求值的使用方法与规则。

const 变量

const 变量是一种特殊的变量，它以关键字 const 修饰，定义在编译时完成求值，并且在运行时不可改变的变量。例如，下面的例子定义了万有引力常数 G：

const G = 6.674e-11

const 变量可以省略类型标注，但是不可省略初始化表达式。const 变量可以是全局变量，局部变量，静态成员变量。但是 const 变量不能在扩展中定义。const 变量可以访问对应类型的所有实例成员，也可以调用对应类型的所有非 mut 实例成员函数。

下例定义了一个 struct，记录行星的质量和半径，同时定义了一个 const 成员函数 gravity 用来计算该行星对距离为 r 质量为 m 的物体的万有引力：

struct Planet {
    const Planet(let mass: Float64, let radius: Float64) {}

    const func gravity(m: Float64, r: Float64) {
        G * mass * m / r**2
    }
}

main() {
    const myMass = 71.0
    const earth = Planet(5.972e24, 6.378e6)
    println(earth.gravity(myMass, earth.radius))
}

编译执行得到地球对地面上一个质量为 71 kg 的成年人的万有引力：

695.657257

const 变量初始化后该类型实例的所有成员都是 const 的（深度 const，包含成员的成员），因此不能被用于左值。

main() {
    const myMass = 71.0
    myMass = 70.0 // Error, cannot assign to immutable value
}

const 上下文与 const 表达式

const 上下文是指 const 变量初始化表达式，这些表达式始终在编译时求值。因此需要对 const 上下文中允许的表达式加以限制，避免修改全局状态、I/O 等副作用，确保其可以在编译时求值。

const 表达式具备了可以在编译时求值的能力。满足如下规则的表达式是 const 表达式：

1. 数值类型、Bool、Unit、Rune、String 类型的字面量（不包含插值字符串）。
2. 所有元素都是 const 表达式的 Array 字面量（不能是 Array 类型，可以使用 VArray 类型），tuple 字面量。
3. const 变量，const 函数形参，const 函数中的局部变量。
4. const 函数，包含使用 const 声明的函数名、符合 const 函数要求的 lambda、以及这些函数返回的函数表达式。
5. const 函数调用（包含 const 构造函数），该函数的表达式必须是 const 表达式，所有实参必须都是 const 表达式。
6. 所有参数都是 const 表达式的 enum 构造器调用，和无参数的 enum 构造器。
7. 数值类型、Bool、Unit、Rune、String 类型的算术表达式、关系表达式、位运算表达式，所有操作数都必须是 const 表达式。
8. if、match、try、控制转移表达式（包含 return、break、continue、throw）、is、as。这些表达式内的表达式必须都是 const 表达式。
9. const 表达式的成员访问（不包含属性的访问），tuple 的索引访问。
10. const init 和 const 函数中的 this 和 super 表达式。
11. const 表达式的 const 实例成员函数调用，且所有实参必须都是 const 表达式。

const 函数

const 函数是一类特殊的函数，这些函数具备了可以在编译时求值的能力。在 const 上下文中调用这种函数时，这些函数会在编译时执行计算。而在其它非 const 上下文，const 函数会和普通函数一样在运行时执行。

下例是一个计算平面上两点距离的 const 函数，distance 中使用 let 定义了两个局部变量 dx 和 dy：

struct Point {
    const Point(let x: Float64, let y: Float64) {}
}

const func distance(a: Point, b: Point) {
    let dx = a.x - b.x
    let dy = a.y - b.y
    (dx**2 + dy**2)**0.5
}

main() {
    const a = Point(3.0, 0.0)
    const b = Point(0.0, 4.0)
    const d = distance(a, b)
    println(d)
}

编译运行输出：

5.000000

需要注意：

1. const 函数声明必须使用 const 修饰。
2. 全局 const 函数和 static const 函数中只能访问 const 声明的外部变量，包含 const 全局变量、const 静态成员变量，其它外部变量都不可访问。const init 函数和 const 实例成员函数除了能访问 const 声明的外部变量，还可以访问当前类型的实例成员变量。
3. const 函数中的表达式都必须是 const 表达式，const init 函数除外。
4. const 函数中可以使用 let、const 声明新的局部变量。但不支持 var。
5. const 函数中的参数类型和返回类型没有特殊规定。如果该函数调用的实参不符合 const 表达式要求，那这个函数调用不能作为 const 表达式使用，但仍然可以作为普通表达式使用。
6. const 函数不一定都会在编译时执行，例如可以在非 const 函数中运行时调用。
7. const 函数与非 const 函数重载规则一致。
8. 数值类型、Bool、Unit、Rune、String 类型 和 enum 支持定义 const 实例成员函数。
9. 对于 struct 和 class，只有定义了 const init 才能定义 const 实例成员函数。class 中的 const 实例成员函数不能是 open 的。struct 中的 const 实例成员函数不能是 mut 的。

另外，接口中也可以定义 const 函数，但会受到以下规则限制：

1. 接口中的 const 函数，实现类型必须也用 const 函数才算实现接口。
2. 接口中的非 const 函数，实现类型使用 const 或非 const 函数都算实现接口。
3. 接口中的 const 函数与接口的 static 函数一样，只有在该接口作为泛型约束的时候，受约束的泛型变元或变量才能使用这些 const 函数。

在下面的例子中，在接口 I 里定义了两个 const 函数，类 A 实现了接口 I，泛型函数 g 的形参类型上界是 I。

interface I {
    const func f(): Int64
    const static func f2(): Int64
}

class A <: I {
    public const func f() { 0 }
    public const static func f2() { 1 }
    const init() {}
}

const func g<T>(i: T) where T <: I {
    return i.f() + T.f2()
}

main() {
    println(g(A()))
}

编译执行上述代码，输出结果为：

1

const init

如果一个 struct 或 class 定义了 const 构造器，那么这个 struct/class 实例可以用在 const 表达式中。

1. 如果当前类型是 class，则不能具有 var 声明的实例成员变量，否则不允许定义 const init 。如果当前类型具有父类，当前的 const init 必须调用父类的 const init（可以显式调用或者隐式调用无参const init），如果父类没有 const init 则报错。
2. 当前类型的实例成员变量如果有初始值，初始值必须要是 const 表达式，否则不允许定义 const init。
3. const init 内可以使用赋值表达式对实例成员变量赋值，除此以外不能有其它赋值表达式。

const init 与 const 函数的区别是 const init 内允许对实例成员变量进行赋值（需要使用赋值表达式）。

定义 struct 类型

struct 类型的定义以关键字 struct 开头，后跟 struct 的名字，接着是定义在一对花括号中的 struct 定义体。struct 定义体中可以定义一系列的成员变量、成员属性（参见属性）、静态初始化器、构造函数和成员函数。

struct Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }

    public func area() {
        width * height
    }
}

上例中定义了名为 Rectangle 的 struct 类型，它有两个 Int64 类型的成员变量 width 和 height，一个有两个 Int64 类型参数的构造函数（使用关键字 init 定义，函数体中通常是对成员变量的初始化），以及一个成员函数 area（返回 width 和 height 的乘积）。

注意：

struct 只能定义在源文件顶层。

struct 成员变量

struct 成员变量分为实例成员变量和静态成员变量（使用 static 修饰符修饰，且必须有初值），二者的区别在于实例成员变量只能通过 struct 实例（我们说 a 是 T 类型的实例，指的是 a 是一个 T 类型的值）访问，静态成员变量只能通过 struct 类型名访问。

实例成员变量定义时可以不设置初值（但必须标注类型，如上例中的 width 和 height），也可以设置初值，例如：

struct Rectangle {
    let width = 10
    let height = 20
}

struct 静态初始化器

struct 支持定义静态初始化器，并在静态初始化器中通过赋值表达式来对静态成员变量进行初始化。

静态初始化器以关键字组合 static init 开头，后跟无参参数列表和函数体，且不能被访问修饰符修饰。函数体中必须完成对所有未初始化的静态成员变量的初始化，否则编译报错。

struct Rectangle {
    static let degree: Int64
    static init() {
        degree = 180
    }
}

一个 struct 中最多允许定义一个静态初始化器，否则报重定义错误。

struct Rectangle {
    static let degree: Int64
    static init() {
        degree = 180
    }
    static init() { // Error, redefinition with the previous static init function
        degree = 180
    }
}

struct 构造函数

struct 支持两类构造函数：普通构造函数和主构造函数。

普通构造函数以关键字 init 开头，后跟参数列表和函数体，函数体中必须完成对所有未初始化的实例成员变量的初始化（如果参数名和成员变量名无法区分，可以在成员变量前使用 this 加以区分，this 表示 struct 的当前实例），否则编译报错。

struct Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64, height: Int64) { // Error, 'height' is not initialized in the constructor
        this.width = width
    }
}

一个 struct 中可以定义多个普通构造函数，但它们必须构成重载（参见函数重载），否则报重定义错误。

struct Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64) {
        this.width = width
        this.height = width
    }

    public init(width: Int64, height: Int64) { // Ok: overloading with the first init function
        this.width = width
        this.height = height
    }

    public init(height: Int64) { // Error, redefinition with the first init function
        this.width = height
        this.height = height
    }
}

除了可以定义若干普通的以 init 为名字的构造函数外，struct 内还可以定义（最多）一个主构造函数。主构造函数的名字和 struct 类型名相同，它的参数列表中可以有两种形式的形参：普通形参和成员变量形参（需要在参数名前加上 let 或 var），成员变量形参同时扮演定义成员变量和构造函数参数的功能。

使用主构造函数通常可以简化 struct 的定义，例如，上述包含一个 init 构造函数的 Rectangle 可以简化为如下定义：

struct Rectangle {
    public Rectangle(let width: Int64, let height: Int64) {}
}

主构造函数的参数列表中也可以定义普通形参，例如：

struct Rectangle {
    public Rectangle(name: String, let width: Int64, let height: Int64) {}
}

如果 struct 定义中不存在自定义构造函数（包括主构造函数），并且所有实例成员变量都有初始值，则会自动为其生成一个无参构造函数（调用此无参构造函数会创建一个所有实例成员变量的值均等于其初值的对象）；否则，不会自动生成此无参构造函数。例如，对于如下 struct 定义，注释中给出了自动生成的无参构造函数：

struct Rectangle {
    let width: Int64 = 10
    let height: Int64 = 10
    /* Auto-generated memberwise constructor:
    public init() {
    }
    */
}

struct 成员函数

struct 成员函数分为实例成员函数和静态成员函数（使用 static 修饰符修饰），二者的区别在于：实例成员函数只能通过 struct 实例访问，静态成员函数只能通过 struct 类型名访问；静态成员函数中不能访问实例成员变量，也不能调用实例成员函数，但在实例成员函数中可以访问静态成员变量以及静态成员函数。

下例中，area 是实例成员函数，typeName 是静态成员函数。

struct Rectangle {
    let width: Int64 = 10
    let height: Int64 = 20

    public func area() {
        this.width * this.height
    }

    public static func typeName(): String {
        "Rectangle"
    }
}

实例成员函数中可以通过 this 访问实例成员变量，例如：

struct Rectangle {
    let width: Int64 = 1
    let height: Int64 = 1

    public func area() {
        this.width * this.height
    }
}

struct 成员的访问修饰符

struct 的成员（包括成员变量、成员属性、构造函数、成员函数、操作符函数（详见操作符重载章节））用 4 种访问修饰符修饰：private、internal、protected 和 public，缺省的含义是 internal。

• private 表示在 struct 定义内可见。
• internal 表示仅当前包及子包（包括子包的子包，详见包章节）内可见。
• protected 表示当前模块（详见包章节）可见。
• public 表示模块内外均可见。

下面的例子中，width 是 public 修饰的成员，在类外可以访问，height 是缺省访问修饰符的成员，仅在当前包及子包可见，其他包无法访问。

package a
public struct Rectangle {
    public var width: Int64
    var height: Int64
    private var area: Int64
    ...
}

func samePkgFunc() {
    var r = Rectangle(10, 20)
    r.width = 8               // Ok: public 'width' can be accessed here
    r.height = 24             // Ok: 'height' has no modifier and can be accessed here
    r.area = 30               // Error, private 'area' can't be accessed here
}

package b
import a.*
main() {
    var r = Rectangle(10, 20)
    r.width = 8               // Ok: public 'width' can be accessed here
    r.height = 24             // Error, no modifier 'height' can't be accessed here
    r.area = 30               // Error, private 'area' can't be accessed here
}

禁止递归 struct

递归和互递归定义的 struct 均是非法的。例如：

struct R1 { // Error, 'R1' recursively references itself
    let other: R1
}
struct R2 { // Error, 'R2' and 'R3' are mutually recursive
    let other: R3
}
struct R3 { // Error, 'R2' and 'R3' are mutually recursive
    let other: R2
}

创建 struct 实例

定义了 struct 类型后，即可通过调用 struct 的构造函数来创建 struct 实例。在 struct 定义之外，通过 struct 类型名调用构造函数。例如，下例中定义了一个 Rectangle 类型的变量 r。

let r = Rectangle(10, 20)

创建了 struct 实例之后，可以通过实例访问它的（public 修饰的）实例成员变量和实例成员函数。例如，下例中通过 r.width 和 r.height 可分别访问 r 中 width 和 height 的值，通过 r.area() 可以调用 r 的成员函数 area。

let r = Rectangle(10, 20)
let width = r.width   // width = 10
let height = r.height // height = 20
let a = r.area()      // a = 200

如果希望通过 struct 实例去修改成员变量的值，需要将 struct 类型的变量定义为可变变量，并且被修改的成员变量也必须是可变成员变量（使用 var 定义）。举例如下：

struct Rectangle {
    public var width: Int64
    public var height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }

    public func area() {
        width * height
    }
}

main() {
    var r = Rectangle(10, 20) // r.width = 10, r.height = 20
    r.width = 8               // r.width = 8
    r.height = 24             // r.height = 24
    let a = r.area()          // a = 192
}

在赋值或传参时，会对 struct 实例进行复制，生成新的实例，对其中一个实例的修改并不会影响另外一个实例。以赋值为例，下面的例子中，将 r1 赋值给 r2 之后，修改 r1 的 width 和 height 的值，并不会影响 r2 的 width 和 height 值。

struct Rectangle {
    public var width: Int64
    public var height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }

    public func area() {
        width * height
    }
}

main() {
    var r1 = Rectangle(10, 20) // r1.width = 10, r1.height = 20
    var r2 = r1                // r2.width = 10, r2.height = 20
    r1.width = 8               // r1.width = 8
    r1.height = 24             // r1.height = 24
    let a1 = r1.area()         // a1 = 192
    let a2 = r2.area()         // a2 = 200
}

mut 函数

struct 类型是值类型，其实例成员函数无法修改实例本身。例如，下例中，成员函数 g 中不能修改成员变量 i 的值。

struct Foo {
    var i = 0

    public func g() {
        i += 1  // Error, the value of a instance member variable cannot be modified in an instance member function
    }
}

mut 函数是一种可以修改 struct 实例本身的特殊的实例成员函数。在 mut 函数内部，this 的语义是特殊的，这种 this 拥有原地修改字段的能力。

注意：

只允许在 interface、struct 和 struct 的扩展内定义 mut 函数（class 是引用类型，实例成员函数不需要加 mut 也可以修改实例成员变量，所以禁止在 class 中定义 mut 函数）。

mut 函数定义

mut 函数与普通的实例成员函数相比，多一个 mut 关键字来修饰。

例如，下例中在函数 g 之前增加 mut 修饰符之后，即可在函数体内修改成员变量 i 的值。

struct Foo {
    var i = 0

    public mut func g() {
        i += 1  // Ok
    }
}

mut 只能修饰实例成员函数，不能修饰静态成员函数。

struct A {
    public mut func f(): Unit {} // Ok
    public mut operator func +(rhs: A): A { // Ok
        A()
    }
    public mut static func g(): Unit {} // Error, static member functions cannot be modified with 'mut'
}

mut 函数中的 this 不能被捕获，也不能作为表达式。不能在 mut 函数中对 struct 的实例成员变量进行捕获。

示例：

struct Foo {
    var i = 0

    public mut func f(): Foo {
        let f1 = { => this } // Error, 'this' in mut functions cannot be captured
        let f2 = { => this.i = 2 } // Error, instance member variables in mut functions cannot be captured
        let f3 = { => this.i } // Error, instance member variables in mut functions cannot be captured
        let f4 = { => i } // Error, instance member variables in mut functions cannot be captured
        this // Error, 'this' in mut functions cannot be used as expressions
    }
}

接口中的 mut 函数

接口中的实例成员函数，也可以使用 mut 修饰。

struct 类型在实现 interface 的函数时必须保持一样的 mut 修饰。struct 以外的类型实现 interface 的函数时不能使用 mut 修饰。

示例：

interface I {
    mut func f1(): Unit
    func f2(): Unit
}

struct A <: I {
    public mut func f1(): Unit {} // Ok: as in the interface, the 'mut' modifier is used
    public func f2(): Unit {} // Ok: as in the interface, the 'mut' modifier is not used
}

struct B <: I {
    public func f1(): Unit {} // Error, 'f1' is modified with 'mut' in interface, but not in struct
    public mut func f2(): Unit {} // Error, 'f2' is not modified with 'mut' in interface, but did in struct
}

class C <: I {
    public func f1(): Unit {} // Ok
    public func f2(): Unit {} // Ok
}

当 struct 的实例赋值给 interface 类型时是拷贝语义，因此 interface 的 mut 函数并不能修改 struct 实例的值。

示例：

interface I {
    mut func f(): Unit
}
struct Foo <: I {
    public var v = 0
    public mut func f(): Unit {
        v += 1
    }
}
main() {
    var a = Foo()
    var b: I = a  
    b.f()  // Calling 'f' via 'b' cannot modify the value of 'a'
    println(a.v) // 0
}

程序输出结果为：

0

mut 函数的使用限制

因为 struct 是值类型，所以如果一个变量是 struct 类型且使用 let 声明，那么不能通过这个变量访问该类型的 mut 函数。

示例：

interface I {
    mut func f(): Unit
}
struct Foo <: I {
    public var i = 0
    public mut func f(): Unit {
        i += 1
    }
}
main() {
    let a = Foo()
    a.f() // Error, 'a' is of type struct and is declared with 'let', the 'mut' function cannot be accessed via 'a'
    var b = Foo()
    b.f() // Ok
    let c: I = Foo()
    c.f() // Ok
}

为避免逃逸，如果一个变量的类型是 struct 类型，那么这个变量不能将该类型使用 mut 修饰的函数作为一等公民来使用，只能调用这些 mut 函数。

示例：

interface I {
    mut func f(): Unit
}

struct Foo <: I {
    var i = 0

    public mut func f(): Unit {
        i += 1
    }
}

main() {
    var a = Foo()
    var fn = a.f // Error, mut function 'f' of 'a' cannot be used as a first class citizen.
    var b: I = Foo()
    fn = b.f // Ok
}

为避免逃逸，非 mut 的实例成员函数（包括 lambda 表达式）不能直接访问所在类型的 mut 函数，反之可以。

示例：

struct Foo {
    var i = 0

    public mut func f(): Unit {
        i += 1
        g() // Ok
    }

    public func g(): Unit {
        f() // Error, mut functions cannot be invoked in non-mut functions
    }
}

interface I {
    mut func f(): Unit {
        g() // Ok
    }

    func g(): Unit {
        f() // Error, mut functions cannot be invoked in non-mut functions
    }
}

枚举类型

本节介绍仓颉中的 enum 类型。enum 类型提供了通过列举一个类型的所有可能取值来定义此类型的方式。

在很多语言中都有 enum 类型（或者称枚举类型），但是不同语言中的 enum 类型的使用方式和表达能力均有所差异，仓颉中的 enum 类型可以理解为函数式编程语言中的代数数据类型（Algebraic Data Types）。

接下来，首先介绍如何定义和使用 enum，然后介绍如何使用模式匹配使得 enum 取不同值时执行不同的操作，最后介绍一个名为 Option 的常用 enum 类型，用于表示某个类型的实例要么有值要么没值。

enum 的定义

定义 enum 时需要把它所有可能的取值一一列出，我们称这些值为 enum 的构造器（或者 constructor）。

enum RGBColor {
    | Red | Green | Blue
}

enum 类型的定义以关键字 enum 开头，接着是 enum 的名字，之后是定义在一对花括号中的 enum 体，enum 体中定义了若干构造器，多个构造器之间使用 | 进行分隔（第一个构造器之前的 | 是可选的）。上例中定义了一个名为 RGBColor 的 enum 类型，它有 3 个构造器：Red、Green 和 Blue，分别表示 RGB 色彩模式中的红色、绿色和蓝色。

上述 enum 中的构造器还可以携带若干（至少一个）参数，称为有参构造器。例如，可以为 Red、Green 和 Blue 设置一个 UInt8 的类型的参数，用来表示每个颜色的亮度级别：

enum RGBColor {
    | Red(UInt8) | Green(UInt8) | Blue(UInt8)
}

仓颉支持同一个 enum 中定义多个同名构造器，但是要求这些构造器的参数个数不同（认为没有参数的构造器的参数个数等于 0），例如：

enum RGBColor {
    | Red | Green | Blue
    | Red(UInt8) | Green(UInt8) | Blue(UInt8)
}

enum 支持递归定义，例如，下面的例子中使用 enum 定义了一种表达式（即 Expr），此表达式只能有 3 种形式：单独的一个数字 Num（携带一个 Int64 类型的参数）、加法表达式 Add（携带两个 Expr 类型的参数）、减法表达式 Sub（携带两个 Expr 类型的参数）。对于 Add 和 Sub 这两个构造器，其参数中递归地使用到了 Expr 自身。

enum Expr {
    | Num(Int64)
    | Add(Expr, Expr)
    | Sub(Expr, Expr)
}

另外，在 enum 体中还可以定义一系列成员函数、操作符函数（详见操作符重载章节）和成员属性（详见属性章节），但是要求构造器、成员函数、成员属性之间不能重名。例如，下面的例子在 RGBColor 中定义了一个名为 printType 的函数，它会输出字符串 RGBColor：

enum RGBColor {
    | Red | Green | Blue

    public static func printType() {
        print("RGBColor")
    }
}

注意：

• enum 只能定义在源文件顶层。
• 当 enum 和 struct 类型存在互递归关系时，且 enum 类型作为 Option 的类型参数，可能存在编译错误。

enum 的使用

定义了 enum 类型之后，就可以创建此类型的实例（即 enum 值），enum 值只能取 enum 类型定义中的一个构造器。enum 没有构造函数，可以通过 类型名.构造器，或者直接使用构造器的方式来构造一个 enum 值（对于有参构造器，需要传实参）。

下例中，RGBColor 中定义了三个构造器，其中有两个无参构造器（Red 和 Green）和一个有参构造器（Blue(UInt8)），main 中定义了三个 RGBColor 类型的变量 r，g 和 b，其中，r 的值使用 RGBColor.Red 进行初始化，g 的值直接使用 Green 进行初始化，b 的值使用 Blue(100) 进行初始化：

enum RGBColor {
    | Red | Green | Blue(UInt8)
}

main() {
    let r = RGBColor.Red
    let g = Green
    let b = Blue(100)
}

当省略类型名时，enum 构造器的名字可能和类型名、变量名、函数名发生冲突。此时必须加上 enum 类型名来使用 enum 构造器，否则只会选择同名的类型、变量、函数定义。

下面的例子中，只有构造器 Blue(UInt8) 可以不带类型名使用，Red 和 Green(UInt8) 皆会因为名字冲突而不能直接使用，必须加上类型名 RGBColor。

let Red = 1

func Green(g: UInt8) {
    return g
}

enum RGBColor {
    | Red | Green(UInt8) | Blue(UInt8)
}

let r1 = Red                 // Will choose 'let Red'
let r2 = RGBColor.Red        // Ok: constructed by enum type name

let g1 = Green(100)          // Will choose 'func Green'
let g2 = RGBColor.Green(100) // Ok: constructed by enum type name

let b = Blue(100)            // Ok: can be uniquely identified as an enum constructor

如下的例子中，只有构造器 Blue 会因为名称冲突而不能直接使用，必须加上类型名 RGBColor。

class Blue {}

enum RGBColor {
    | Red | Green(UInt8) | Blue(UInt8)
}

let r = Red                 // Ok: constructed by enum type name

let g = Green(100)          // Ok: constructed by enum type name

let b = Blue(100)           // Will choose constructor of 'class Blue' and report an error

Option 类型

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

Option 类型被定义为一个泛型 enum 类型，定义如下（这里我们仅需要知道尖括号中的 T 是一个类型形参，当 T 为不同类型时会得到不同的 Option 类型即可。关于泛型的详细介绍，可参见泛型）：

enum Option<T> {
    | Some(T)
    | None
}

其中，Some 构造器的参数类型就是类型形参 T，当 T 被实例化为不同的类型时，会得到不同的 Option 类型，例如：Option<Int64>、Option<String>等。

Option 类型还有一种简单的写法：在类型名前加 ?。也就是说，对于任意类型 Ty，?Ty 等价于 Option<Ty>。例如，?Int64 等价于 Option<Int64>，?String 等价于 Option<String> 等等。

下面的例子展示了如何定义 Option 类型的变量：

let a: Option<Int64> = Some(100)
let b: ?Int64 = Some(100)
let c: Option<String> = Some("Hello")
let d: ?String = None

另外，虽然 T 和 Option<T> 是不同的类型，但是当明确知道某个位置需要的是 Option<T> 类型的值时，可以直接传一个 T 类型的值，编译器会用 Option<T> 类型的 Some 构造器将 T 类型的值封装成 Option<T> 类型的值（注意：这里并不是类型转换）。例如，下面的定义是合法的（等价于上例中变量 a，b 和 c 的定义）：

let a: Option<Int64> = 100
let b: ?Int64 = 100
let c: Option<String> = "100"

在上下文没有明确的类型要求时，无法使用 None 直接构造出想要的类型，此时应使用 None<T> 这样的语法来构造 Option<T> 类型的数据，例如

let a = None<Int64> // a: Option<Int64>
let b = None<Bool> // b: Option<Bool>

最后，关于 Option 的使用，请参见使用 Option。

模式概述

对于包含匹配值的 match 表达式，case 之后支持哪些模式决定了 match 表达式的表达能力，本节中我们将依次介绍仓颉支持的模式，包括：常量模式、通配符模式、绑定模式、tuple 模式、类型模式和 enum 模式。

常量模式

常量模式可以是整数字面量、浮点数字面量、字符字面量、布尔字面量、字符串字面量（不支持字符串插值）、Unit 字面量。

在包含匹配值的 match 表达式中使用常量模式时，要求常量模式表示的值的类型与待匹配值的类型相同，匹配成功的条件是待匹配的值与常量模式表示的值相等。

下面的例子中，根据 score 的值（假设 score 只能取 0 到 100 间被 10 整除的值），输出考试成绩的等级：

main() {
    let score = 90
    let level = match (score) {
        case 0 | 10 | 20 | 30 | 40 | 50 => "D"
        case 60 => "C"
        case 70 | 80 => "B"
        case 90 | 100 => "A" // Matched.
        case _ => "Not a valid score"
    }
    println(level)
}

编译执行上述代码，输出结果为：

A

• 在模式匹配的目标是静态类型为 Rune 的值时，Rune 字面量和单字符字符串字面量都可用于表示 Rune 类型字面量的常量 pattern。

  func translate(n: Rune) {
      match (n) {
          case "一" => 1
          case "二" => 2
          case "三" => 3
          case _ => -1
      }
  }
  
  main() {
      println(translate(r"三"))
  }
  

  编译执行上述代码，输出结果为：

  3
  

• 在模式匹配的目标是静态类型为 Byte 的值时，一个表示 ASCII 字符的字符串字面量可用于表示 Byte 类型字面量的常量 pattern。

  func translate(n: Byte) {
      match (n) {
          case "1" => 1
          case "2" => 2
          case "3" => 3
          case _ => -1
      }
  }
  
  main() {
      println(translate(51)) // UInt32(r'3') == 51
  }
  

  编译执行上述代码，输出结果为：

  3
  

通配符模式

通配符模式使用下划线 _ 表示，可以匹配任意值。通配符模式通常作为最后一个 case 中的模式，用来匹配其他 case 未覆盖到的情况，如常量模式中匹配 score 值的示例中，最后一个 case 中使用 _ 来匹配无效的 score 值。

绑定模式

绑定模式使用 id 表示，id 是一个合法的标识符。与通配符模式相比，绑定模式同样可以匹配任意值，但绑定模式会将匹配到的值与 id 进行绑定，在 => 之后可以通过 id 访问其绑定的值。

下面的例子中，最后一个 case 中使用了绑定模式，用于绑定非 0 值：

main() {
    let x = -10
    let y = match (x) {
        case 0 => "zero"
        case n => "x is not zero and x = ${n}" // Matched.
    }
    println(y)
}

编译执行上述代码，输出结果为：

x is not zero and x = -10

使用 | 连接多个模式时不能使用绑定模式，也不可嵌套出现在其它模式中，否则会报错：

main() {
    let opt = Some(0)
    match (opt) {
        case x | x => {} // Error, variable cannot be introduced in patterns connected by '|'
        case Some(x) | Some(x) => {} // Error, variable cannot be introduced in patterns connected by '|'
        case x: Int64 | x: String => {} // Error, variable cannot be introduced in patterns connected by '|'
    }
}

绑定模式 id 相当于新定义了一个名为 id 的不可变变量（其作用域从引入处开始到该 case 结尾处），因此在 => 之后无法对 id 进行修改。例如，下例中最后一个 case 中对 n 的修改是不允许的。

main() {
    let x = -10
    let y = match (x) {
        case 0 => "zero"
        case n => n = n + 0 // Error, 'n' cannot be modified.
                  "x is not zero"
    }
    println(y)
}

对于每个 case 分支，=> 之后变量作用域级别与 case 后 => 前引入的变量作用域级别相同，在 => 之后再次引入相同名字会触发重定义错误。例如：

main() {
    let x = -10
    let y = match (x) {
        case 0 => "zero"
        case n => let n = 0 // Error, redefinition
                  println(n)
                  "x is not zero"
    }
    println(y)
}

注意：

当模式的 identifier 为 enum 构造器时，该模式会被当成 enum 模式进行匹配，而不是绑定模式（关于 enum 模式，详见 enum 模式章节）。

enum RGBColor {
    | Red | Green | Blue
}

main() {
    let x = Red
    let y = match (x) {
        case Red => "red" // The 'Red' is enum mode here.
        case _ => "not red"
    }
    println(y)
}

编译执行上述代码，输出结果为：

red

Tuple 模式

Tuple 模式用于 tuple 值的匹配，它的定义和 tuple 字面量类似：(p_1, p_2, ..., p_n)，区别在于这里的 p_1 到 p_n（n 大于等于 2）是模式（可以是本章节中介绍的任何模式，多个模式间使用逗号分隔）而不是表达式。

例如，(1, 2, 3) 是一个包含三个常量模式的 tuple 模式，(x, y, _) 是一个包含两个绑定模式，一个通配符模式的 tuple 模式。

给定一个 tuple 值 tv 和一个 tuple 模式 tp，当且仅当 tv 每个位置处的值均能与 tp 中对应位置处的模式相匹配，才称 tp 能匹配 tv。例如，(1, 2, 3) 仅可以匹配 tuple 值 (1, 2, 3)，(x, y, _) 可以匹配任何三元 tuple 值。

下面的例子中，展示了 tuple 模式的使用：

main() {
    let tv = ("Alice", 24)
    let s = match (tv) {
        case ("Bob", age) => "Bob is ${age} years old"
        case ("Alice", age) => "Alice is ${age} years old" // Matched, "Alice" is a constant pattern, and 'age' is a variable pattern.
        case (name, 100) => "${name} is 100 years old"
        case (_, _) => "someone"
    }
    println(s)
}

编译执行上述代码，输出结果为：

Alice is 24 years old

同一个 tuple 模式中不允许引入多个名字相同的绑定模式。例如，下例中最后一个 case 中的 case (x, x) 是不合法的。

main() {
    let tv = ("Alice", 24)
    let s = match (tv) {
        case ("Bob", age) => "Bob is ${age} years old"
        case ("Alice", age) => "Alice is ${age} years old"
        case (name, 100) => "${name} is 100 years old"
        case (x, x) => "someone" // Error, Cannot introduce a variable pattern with the same name, which will be a redefinition error.
    }
    println(s)
}

类型模式

类型模式用于判断一个值的运行时类型是否是某个类型的子类型。类型模式有两种形式：_: Type（嵌套一个通配符模式 _）和 id: Type（嵌套一个绑定模式 id），它们的差别是后者会发生变量绑定，而前者并不会。

对于待匹配值 v 和类型模式 id: Type（或 _: Type），首先判断 v 的运行时类型是否是 Type 的子类型，若成立则视为匹配成功，否则视为匹配失败；如匹配成功，则将 v 的类型转换为 Type 并与 id 进行绑定（对于 _: Type，不存在绑定这一操作）。

假设有如下两个类，Base 和 Derived，并且 Derived 是 Base 的子类，Base 的无参构造函数中将 a 的值设置为 10，Derived 的无参构造函数中将 a 的值设置为 20：

open class Base {
    var a: Int64
    public init() {
        a = 10
    }
}

class Derived <: Base {
    public init() {
        a = 20
    }
}

下面的代码展示了使用类型模式并匹配成功的例子：

main() {
    var d = Derived()
    var r = match (d) {
        case b: Base => b.a // Matched.
        case _ => 0
    }
    println("r = ${r}")
}

编译执行上述代码，输出结果为：

r = 20

下面的代码展示了使用类型模式但类型模式匹配失败的例子：

open class Base {
    var a: Int64
    public init() {
        a = 10
    }
}

class Derived <: Base {
    public init() {
        a = 20
    }
}

main() {
    var b = Base()
    var r = match (b) {
        case d: Derived => d.a // Type pattern match failed.
        case _ => 0 // Matched.
    }
    println("r = ${r}")
}

编译执行上述代码，输出结果为：

r = 0

enum 模式

enum 模式用于匹配 enum 类型的实例，它的定义和 enum 的构造器类似：无参构造器 C 或有参构造器 C(p_1, p_2, ..., p_n)，构造器的类型前缀可以省略，区别在于这里的 p_1 到 p_n（n 大于等于 1）是模式。例如，Some(1) 是一个包含一个常量模式的 enum 模式，Some(x) 是一个包含一个绑定模式的 enum 模式。

给定一个 enum 实例 ev 和一个 enum 模式 ep，当且仅当 ev 的构造器名字和 ep 的构造器名字相同，且 ev 参数列表中每个位置处的值均能与 ep 中对应位置处的模式相匹配，才称 ep 能匹配 ev。例如，Some("one") 仅可以匹配 Option<String> 类型的Some 构造器 Option<String>.Some("one")，Some(x) 可以匹配任何 Option 类型的 Some 构造器。

下面的例子中，展示了 enum 模式的使用，因为 x 的构造器是 Year，所以会和第一个 case 匹配：

enum TimeUnit {
    | Year(UInt64)
    | Month(UInt64)
}

main() {
    let x = Year(2)
    let s = match (x) {
        case Year(n) => "x has ${n * 12} months" // Matched.
        case TimeUnit.Month(n) => "x has ${n} months"
    }
    println(s)
}

编译执行上述代码，输出结果为：

x has 24 months

使用 | 连接多个 enum 模式：

enum TimeUnit {
    | Year(UInt64)
    | Month(UInt64)
}

main() {
    let x = Year(2)
    let s = match (x) {
        case Year(0) | Year(1) | Month(_) => "Ok" // Ok
        case Year(2) | Month(m) => "invalid" // Error, Variable cannot be introduced in patterns connected by '|'
        case Year(n: UInt64) | Month(n: UInt64) => "invalid" // Error, Variable cannot be introduced in patterns connected by '|'
    }
    println(s)
}

使用 match 表达式匹配 enum 值时，要求 case 之后的模式要覆盖待匹配 enum 类型中的所有构造器，如果未做到完全覆盖，编译器将报错：

enum RGBColor {
    | Red | Green | Blue
}

main() {
    let c = Green
    let cs = match (c) { // Error, Not all constructors of RGBColor are covered.
        case Red => "Red"
        case Green => "Green"
    }
    println(cs)
}

我们可以通过加上 case Blue 来实现完全覆盖，也可以在 match 表达式的最后通过使用 case _ 来覆盖其他 case 未覆盖的到的情况，如：

enum RGBColor {
    | Red | Green | Blue
}

main() {
    let c = Blue
    let cs = match (c) {
        case Red => "Red"
        case Green => "Green"
        case _ => "Other" // Matched.
    }
    println(cs)
}

上述代码的执行结果为：

Other

模式的嵌套组合

Tuple 模式和 enum 模式可以嵌套任意模式。下面的代码展示了不同模式嵌套组合使用：

enum TimeUnit {
    | Year(UInt64)
    | Month(UInt64)
}

enum Command {
    | SetTimeUnit(TimeUnit)
    | GetTimeUnit
    | Quit
}

main() {
    let command = SetTimeUnit(Year(2022))
    match (command) {
        case SetTimeUnit(Year(year)) => println("Set year ${year}")
        case SetTimeUnit(Month(month)) => println("Set month ${month}")
        case _ => ()
    }
}

编译执行上述代码，输出结果为：

Set year 2022

模式的 Refutability

模式可以分为两类：refutable 模式和 irrefutable 模式。在类型匹配的前提下，当一个模式有可能和待匹配值不匹配时，称此模式为 refutable 模式；反之，当一个模式总是可以和待匹配值匹配时，称此模式为 irrefutable 模式。

对于上述介绍的各种模式，规定如下：

常量模式是 refutable 模式。例如，下例中第一个 case 中的 1 和第二个 case 中的 2 都有可能和 x 的值不相等。

func constPat(x: Int64) {
    match (x) {
        case 1 => "one"
        case 2 => "two"
        case _ => "_"
    }
}

通配符模式是 irrefutable 模式。例如，下例中无论 x 的值是多少，_ 总能和其匹配。

func wildcardPat(x: Int64) {
    match (x) {
        case _ => "_"
    }
}

绑定模式是 irrefutable 模式。例如，下例中无论 x 的值是多少，绑定模式 a 总能和其匹配。

func varPat(x: Int64) {
    match (x) {
        case a => "x = ${a}"
    }
}

Tuple 模式是 irrefutable 模式，当且仅当其包含的每个模式都是 irrefutable 模式。例如，下例中 (1, 2) 和 (a, 2) 都有可能和 x 的值不匹配，所以它们是 refutable 模式，而 (a, b) 可以匹配任何 x 的值，所以它是 irrefutable 模式。

func tuplePat(x: (Int64, Int64)) {
    match (x) {
        case (1, 2) => "(1, 2)"
        case (a, 2) => "(${a}, 2)"
        case (a, b) => "(${a}, ${b})"
    }
}

类型模式是 refutable 模式。例如，下例中（假设 Base 是 Derived 的父类，并且 Base 实现了接口 I），x 的运行时类型有可能既不是 Base 也不是 Derived，所以 a: Derived 和 b: Base 均是 refutable 模式。

interface I {}
open class Base <: I {}
class Derived <: Base {}

func typePat(x: I) {
    match (x) {
        case a: Derived => "Derived"
        case b: Base => "Base"
        case _ => "Other"
    }
}

enum 模式是 irrefutable 模式，当且仅当它对应的 enum 类型中只有一个有参构造器，且 enum 模式中包含的其他模式也是 irrefutable 模式。例如，对于下例中的 E1 和 E2 定义，函数 enumPat1 中的 A(1) 是 refutable 模式，A(a) 是 irrefutable 模式；而函数 enumPat2 中的 B(b) 和 C(c) 均是 refutable 模式。

enum E1 {
    A(Int64)
}

enum E2 {
    B(Int64) | C(Int64)
}

func enumPat1(x: E1) {
    match (x) {
        case A(1) => "A(1)"
        case A(a) => "A(${a})"
    }
}

func enumPat2(x: E2) {
    match (x) {
        case B(b) => "B(${b})"
        case C(c) => "C(${c})"
    }
}

match 表达式

match 表达式的定义

仓颉支持两种 match 表达式，第一种是包含待匹配值的 match 表达式，第二种是不含待匹配值的 match 表达式。

含匹配值的 match 表达式：

main() {
    let x = 0
    match (x) {
        case 1 => let r1 = "x = 1"
                  print(r1)
        case 0 => let r2 = "x = 0" // Matched.
                  print(r2)
        case _ => let r3 = "x != 1 and x != 0"
                  print(r3)
    }
}

match 表达式以关键字 match 开头，后跟要匹配的值（如上例中的 x，x 可以是任意表达式），接着是定义在一对花括号内的若干 case 分支。

每个 case 分支以关键字 case 开头，case 之后是一个模式或多个由 | 连接的相同种类的模式（如上例中的 1、0、_ 都是模式，详见模式概述章节）；模式之后可以接一个可选的 pattern guard，表示本条 case 匹配成功后额外需要满足的条件；接着是一个 =>，=> 之后即本条 case 分支匹配成功后需要执行的操作，可以是一系列表达式、变量和函数定义（新定义的变量或函数的作用域从其定义处开始到下一个 case 之前结束），如上例中的变量定义和 print 函数调用。

match 表达式执行时依次将 match 之后的表达式与每个 case 中的模式进行匹配，一旦匹配成功（如果有 pattern guard，也需要 where 之后的表达式的值为 true；如果 case 中有多个由 | 连接的模式，只要待匹配值和其中一个模式匹配则认为匹配成功）则执行 => 之后的代码然后退出 match 表达式的执行（意味着不会再去匹配它之后的 case），如果匹配不成功则继续与它之后的 case 中的模式进行匹配，直到匹配成功（match 表达式可以保证一定存在匹配的 case 分支）。

上例中，因为 x 的值等于 0，所以会和第二条 case 分支匹配（此处使用的是常量模式，匹配的是值是否相等，详见常量模式章节），最后输出 x = 0。

编译并执行上述代码，输出结果为：

x = 0

match 表达式要求所有匹配必须是穷尽（exhaustive）的，意味着待匹配表达式的所有可能取值都应该被考虑到。当 match 表达式非穷尽，或者编译器判断不出是否穷尽时，均会编译报错，换言之，所有 case 分支（包含 pattern guard）所覆盖的取值范围的并集，应该包含待匹配表达式的所有可能取值。常用的确保 match 表达式穷尽的方式是在最后一个 case 分支中使用通配符模式 _，因为 _ 可以匹配任何值。

match 表达式的穷尽性保证了一定存在和待匹配值相匹配的 case 分支。下面的例子将编译报错，因为所有的 case 并没有覆盖 x 的所有可能取值：

func nonExhaustive(x: Int64) {
    match (x) {
        case 0 => print("x = 0")
        case 1 => print("x = 1")
        case 2 => print("x = 2")
    }
}

在 case 分支的模式之后，可以使用 pattern guard 进一步对匹配出来的结果进行判断。pattern guard 使用 where cond 表示，要求表达式 cond 的类型为 Bool。

在下面的例子中（使用到了 enum 模式，详见 enum 模式章节），当 RGBColor 的构造器的参数值大于等于 0 时，输出它们的值，当参数值小于 0 时，认为它们的值等于 0：

enum RGBColor {
    | Red(Int16) | Green(Int16) | Blue(Int16)
}
main() {
    let c = RGBColor.Green(-100)
    let cs = match (c) {
        case Red(r) where r < 0 => "Red = 0"
        case Red(r) => "Red = ${r}"
        case Green(g) where g < 0 => "Green = 0" // Matched.
        case Green(g) => "Green = ${g}"
        case Blue(b) where b < 0 => "Blue = 0"
        case Blue(b) => "Blue = ${b}"
    }
    print(cs)
}

编译执行上述代码，输出结果为：

Green = 0

没有匹配值的 match 表达式：

main() {
    let x = -1
    match {
        case x > 0 => print("x > 0")
        case x < 0 => print("x < 0") // Matched.
        case _ => print("x = 0")
    }
}

与包含待匹配值的 match 表达式相比，关键字 match 之后并没有待匹配的表达式，并且 case 之后不再是 pattern，而是类型为 Bool 的表达式（上述代码中的 x > 0 和 x < 0）或者 _（表示 true），当然，case 中也不再有 pattern guard。

无匹配值的 match 表达式执行时依次判断 case 之后的表达式的值，直到遇到值为 true 的 case 分支；一旦某个 case 之后的表达式值等于 true，则执行此 case 中 => 之后的代码，然后退出 match 表达式的执行（意味着不会再去判断该 case 之后的其他 case）。

上例中，因为 x 的值等于 -1，所以第二条 case 分支中的表达式（即 x < 0）的值等于 true，执行 print("x < 0")。

编译并执行上述代码，输出结果为：

x < 0

match 表达式的类型

对于 match 表达式（无论是否有匹配值），

• 在上下文有明确的类型要求时，要求每个 case 分支中 => 之后的代码块的类型是上下文所要求的类型的子类型；

• 在上下文没有明确的类型要求时，match 表达式的类型是每个 case 分支中 => 之后的代码块的类型的最小公共父类型；

• 当 match 表达式的值没有被使用时，其类型为 Unit，不要求各分支的类型有最小公共父类型。

下面分别举例说明。

let x = 2
let s: String = match (x) {
    case 0 => "x = 0"
    case 1 => "x = 1"
    case _ => "x != 0 and x != 1" // Matched.
}

上面的例子中，定义变量 s 时，显式地标注了其类型为 String，属于上下文类型信息明确的情况，因此要求每个 case 的 => 之后的代码块的类型均是 String 的子类型，显然上例中 => 之后的字符串类型的字面量均满足要求。

再来看一个没有上下文类型信息的例子：

let x = 2
let s = match (x) {
    case 0 => "x = 0"
    case 1 => "x = 1"
    case _ => "x != 0 and x != 1" // Matched.
}

上例中，定义变量 s 时，未显式标注其类型，因为每个 case 的 => 之后的代码块的类型均是 String，所以 match 表达式的类型是 String，进而可确定 s 的类型也是 String。

if-let 表达式

if-let 表达式首先对条件中 <- 右侧的表达式进行求值，如果此值能匹配 <- 左侧的模式，则执行 if 分支，否则执行 else 分支（可省略）。例如：

main() {
    let result = Option<Int64>.Some(2023)

    if (let Some(value) <- result) {
        println("操作成功，返回值为：${value}")
    } else {
        println("操作失败")
    }
}

运行以上程序，将输出：

操作成功，返回值为：2023

对于以上程序，如果将 result 的初始值修改为 Option<Int64>.None，则 if-let 的模式匹配会失败，将执行 else 分支：

main() {
    let result = Option<Int64>.None

    if (let Some(value) <- result) {
        println("操作成功，返回值为：${value}")
    } else {
        println("操作失败")
    }
}

运行以上程序，将输出：

操作失败

while-let 表达式

while-let 表达式首先对条件中 <- 右侧的表达式进行求值，如果此值能匹配 <- 左侧的模式，则执行循环体，然后重复执行此过程。如果模式匹配失败，则结束循环，继续执行 while-let 表达式之后的代码。例如：

import std.random.*

// 此函数模拟在通信中接收数据，获取数据可能失败
func recv(): Option<UInt8> {
    let number = Random().nextUInt8()
    if (number < 128) {
        return Some(number)
    }
    return None
}

main() {
    // 模拟循环接收通信数据，如果失败就结束循环
    while (let Some(data) <- recv()) {
        println(data)
    }
    println("receive failed")
}

运行以上程序，可能的输出为：

73
94
receive failed

其他使用模式的地方

模式除了可以在 match 表达式中使用外，还可以使用在变量定义（等号左侧是个模式）和 for in 表达式（for 关键字和 in 关键字之间是个模式）中。

但是，并不是所有的模式都能使用在变量定义和 for in 表达式中，只有 irrefutable 的模式才能在这两处被使用，所以只有通配符模式、绑定模式、irrefutable tuple 模式和 irrefutable enum 模式是允许的。

1. 变量定义和 for in 表达式中使用通配符模式的例子如下：

   main() {
       let _ = 100
       for (_ in 1..5) {
           println("0")
       }
   }
   

   上例中，变量定义时使用了通配符模式，表示定义了一个没有名字的变量（当然此后也就没办法对其进行访问），for in 表达式中使用了通配符模式，表示不会将 1..5 中的元素与某个变量绑定（当然循环体中就无法访问 1..5 中元素值）。编译执行上述代码，输出结果为：

   0
   0
   0
   0
   

2. 变量定义和 for in 表达式中使用绑定模式的例子如下：

   main() {
       let x = 100
       println("x = ${x}")
       for (i in 1..5) {
           println(i)
       }
   }
   

   上例中，变量定义中的 x 以及 for in 表达式中的 i 都是绑定模式。编译执行上述代码，输出结果为：

   x = 100
   1
   2
   3
   4
   

3. 变量定义和 for in 表达式中使用 irrefutable tuple 模式的例子如下：

   main() {
       let (x, y) = (100, 200)
       println("x = ${x}")
       println("y = ${y}")
       for ((i, j) in [(1, 2), (3, 4), (5, 6)]) {
           println("Sum = ${i + j}")
       }
   }
   
   

   上例中，变量定义时使用了 tuple 模式，表示对 (100, 200) 进行解构并分别和 x 与 y 进行绑定，效果上相当于定义了两个变量 x 和 y。for in 表达式中使用了 tuple 模式，表示依次将 [(1, 2), (3, 4), (5, 6)] 中的 tuple 类型的元素取出，然后解构并分别和 i 与 j 进行绑定，循环体中输出 i + j 的值。编译执行上述代码，输出结果为：

   x = 100
   y = 200
   Sum = 3
   Sum = 7
   Sum = 11
   

4. 变量定义和 for in 表达式中使用 irrefutable enum 模式的例子如下：

   enum RedColor {
       Red(Int64)
   }
   main() {
       let Red(red) = Red(0)
       println("red = ${red}")
       for (Red(r) in [Red(10), Red(20), Red(30)]) {
           println("r = ${r}")
       }
   }
   

   上例中，变量定义时使用了 enum 模式，表示对 Red(0) 进行解构并将构造器的参数值（即 0）与 red 进行绑定。for in 表达式中使用了 enum 模式，表示依次将 [Red(10), Red(20), Red(30)] 中的元素取出，然后解构并将构造器的参数值与 r 进行绑定，循环体中输出 r 的值。编译执行上述代码，输出结果为：

   red = 0
   r = 10
   r = 20
   r = 30
   

类

class 类型是面向对象编程中的经典概念，仓颉中同样支持使用 class 来实现面向对象编程。class 与 struct 的主要区别在于：class 是引用类型，struct 是值类型，它们在赋值或传参时行为是不同的；class 之间可以继承，但 struct 之间不能继承。

本节依次介绍如何定义 class 类型，如何创建对象，以及 class 的继承。

class 定义

class 类型的定义以关键字 class 开头，后跟 class 的名字，接着是定义在一对花括号中的 class 定义体。class 定义体中可以定义一系列的成员变量、成员属性（参见属性）、静态初始化器、构造函数、成员函数和操作符函数（详见操作符重载章节））。

class Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
    }

    public func area() {
        width * height
    }
}

上例中定义了名为 Rectangle 的 class 类型，它有两个 Int64 类型的成员变量 width 和 height，一个有两个 Int64 类型参数的构造函数，以及一个成员函数 area（返回 width 和 height 的乘积）。

注意：

class 只能定义在源文件顶层。

class 成员变量

class 成员变量分为实例成员变量和静态成员变量，静态成员变量使用 static 修饰符修饰，必须有初值，只能通过类型名访问，参考如下示例：

class Rectangle {
    let width = 10
    static let height = 20
}

let l = Rectangle.height // l = 20

实例成员变量定义时可以不设置初值（但必须标注类型），也可以设置初值，只能通过对象（即类的实例）访问，参考如下示例：

class Rectangle {
    let width = 10
    let height: Int64
    init(h: Int64){
        height = h
    }
}
let rec = Rectangle(20)
let l = rec.height // l = 20

class 静态初始化器

class 支持定义静态初始化器，并在静态初始化器中通过赋值表达式来对静态成员变量进行初始化。

静态初始化器以关键字组合 static init 开头，后跟无参参数列表和函数体，且不能被访问修饰符修饰。函数体中必须完成对所有未初始化的静态成员变量的初始化，否则编译报错。

class Rectangle {
    static let degree: Int64
    static init() {
        degree = 180
    }
}

一个 class 中最多允许定义一个静态初始化器，否则报重定义错误。

class Rectangle {
    static let degree: Int64
    static init() {
        degree = 180
    }
    static init() { // Error, redefinition with the previous static init function
        degree = 180
    }
}

class 构造函数

和 struct 一样，class 中也支持定义普通构造函数和主构造函数。

普通构造函数以关键字 init 开头，后跟参数列表和函数体，函数体中必须完成所有未初始化实例成员变量的初始化，否则编译报错。

class Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64, height: Int64) { // Error, 'height' is not initialized in the constructor
        this.width = width
    }
}

一个类中可以定义多个普通构造函数，但它们必须构成重载（参见函数重载），否则报重定义错误。

class Rectangle {
    let width: Int64
    let height: Int64

    public init(width: Int64) {
        this.width = width
        this.height = width
    }

    public init(width: Int64, height: Int64) { // Ok: overloading with the first init function
        this.width = width
        this.height = height
    }

    public init(height: Int64) { // Error, redefinition with the first init function
        this.width = height
        this.height = height
    }
}

除了可以定义若干普通的以 init 为名字的构造函数外，class 内还可以定义（最多）一个主构造函数。主构造函数的名字和 class 类型名相同，它的参数列表中可以有两种形式的形参：普通形参和成员变量形参（需要在参数名前加上 let 或 var），成员变量形参同时具有定义成员变量和构造函数参数的功能。

使用主构造函数通常可以简化 class 的定义，例如，上述包含一个 init 构造函数的 Rectangle 可以简化为如下定义：

class Rectangle {
    public Rectangle(let width: Int64, let height: Int64) {}
}

主构造函数的参数列表中也可以定义普通形参，例如：

class Rectangle {
    public Rectangle(name: String, let width: Int64, let height: Int64) {}
}

如果 class 定义中不存在自定义构造函数（包括主构造函数），并且所有实例成员变量都有初值，则会自动为其生成一个无参构造函数（调用此无参构造函数会创建一个所有实例成员变量的值均等于其初值的对象）；否则，不会自动生成此无参构造函数。例如，对于如下 class 定义，编译器会为其自动生成一个无参构造函数：

class Rectangle {
    let width = 10
    let height = 20

    /* Auto-generated parameterless constructor:
    public init() {

    }
    */
}

// Invoke the auto-generated parameterless constructor
let r = Rectangle() // r.width = 10，r.height = 20

class 终结器

class 支持定义终结器，这个函数在类的实例被垃圾回收的时候被调用。终结器的函数名固定为 ~init。终结器一般被用于释放系统资源：

class C {
    var p: CString

    init(s: String) {
        p = unsafe { LibC.mallocCString(s) }
        println(s)
    }
    ~init() {
        unsafe { LibC.free(p) }
    }
}

使用终结器有些限制条件，需要开发者注意：

1. 终结器没有参数，没有返回类型，没有泛型类型参数，没有任何修饰符，也不可以被显式调用。
2. 带有终结器的类不可被 open 修饰，只有非 open 的类可以拥有终结器。
3. 一个类最多只能定义一个终结器。
4. 终结器不可以定义在扩展中。
5. 终结器被触发的时机是不确定的。
6. 终结器可能在任意一个线程上执行。
7. 多个终结器的执行顺序是不确定的。
8. 终结器向外抛出未捕获异常属于未定义行为。
9. 终结器中创建线程或者使用线程同步功能属于未定义行为。
10. 终结器执行结束之后，如果这个对象还可以被继续访问，则属于未定义行为。

class 成员函数

class 成员函数同样分为实例成员函数和静态成员函数（使用 static 修饰符修饰），实例成员函数只能通过对象访问，静态成员函数只能通过 class 类型名访问；静态成员函数中不能访问实例成员变量，也不能调用实例成员函数，但在实例成员函数中可以访问静态成员变量以及静态成员函数。

下例中，area 是实例成员函数，typeName 是静态成员函数。

class Rectangle {
    let width: Int64 = 10
    let height: Int64 = 20

    public func area() {
        this.width * this.height
    }

    public static func typeName(): String {
        "Rectangle"
    }
}

根据有没有函数体，实例成员函数又可以分为抽象成员函数和非抽象成员函数。抽象成员函数没有函数体，只能定义在抽象类或接口（详见接口章节）中。例如，下例中在抽象类 AbRectangle（使用关键字 abstract 修饰）中定义了抽象函数 foo。

abstract class AbRectangle {
    public func foo(): Unit
}

需要注意的是，抽象实例成员函数默认具有 open 的语义，open 修饰符是可选的，且必须使用 public 或 protected 进行修饰。

非抽象函数必须有函数体，在函数体中可以通过 this 访问实例成员变量，例如：

class Rectangle {
    let width: Int64 = 10
    let height: Int64 = 20

    public func area() {
        this.width * this.height
    }
}

class 成员的访问修饰符

对于 class 的成员（包括成员变量、成员属性、构造函数、成员函数），可以使用的访问修饰符有 4 种访问修饰符修饰：private、internal、protected 和 public，缺省的含义是 internal。

• private 表示在 class 定义内可见。
• internal 表示仅当前包及子包（包括子包的子包，详见包章节）内可见。
• protected 表示当前模块（详见包章节）及当前类的子类可见。
• public 表示模块内外均可见。

package a
public open class Rectangle {
    public var width: Int64
    protected var height: Int64
    private var area: Int64
    public init(width: Int64, height: Int64) {
        this.width = width
        this.height = height
        this.area = this.width * this.height
    }
    init(width: Int64, height: Int64, multiple: Int64) {
        this.width = width
        this.height = height
        this.area = width * height * multiple
    }
}

func samePkgFunc() {
    var r = Rectangle(10, 20) // Ok: constructor 'Rectangle' can be accessed here
    r.width = 8               // Ok: public 'width' can be accessed here
    r.height = 24             // Ok: protected 'height' can be accessed here
    r.area = 30               // Error, private 'area' cannot be accessed here
}

package b
import a.*
public class Cuboid <: Rectangle {
    private var length: Int64
    public init(width: Int64, height: Int64, length: Int64) {
        super(width, height)
        this.length = length
    }
    public func volume() {
        this.width * this.height * this.length // Ok: protected 'height' can be accessed here
    }
}

main() {
    var r = Rectangle(10, 20, 2) // Error, Rectangle has no `public` constructor with three parameters
    var c = Cuboid(20, 20, 20)
    c.width = 8               // Ok: public 'width' can be accessed here
    c.height = 24             // Error, protected 'height' cannot be accessed here
    c.area = 30               // Error, private 'area' cannot be accessed here
}

This 类型

在类内部，我们支持 This 类型占位符，代指当前类的类型。它只能被作为实例成员函数的返回类型来使用，当使用子类对象调用在父类中定义的返回 This 类型的函数时，该函数调用的类型会被识别为子类类型，而非定义所在的父类类型。

如果实例成员函数没有声明返回类型，并且只存在返回 This 类型表达式时，当前函数的返回类型会推断为 This。示例如下：

open class C1 {
    func f(): This {  // its type is `() -> C1`
        return this
    }

    func f2() { // its type is `() -> C1`
        return this
    }

    public open func f3(): C1 {
        return this
    }
}
class C2 <: C1 {
    // member function f is inherited from C1, and its type is `() -> C2` now
    public override func f3(): This { // Ok
        return this
    }
}

var obj1: C2 = C2()
var obj2: C1 = C2()

var x = obj1.f()    // During compilation, the type of x is C2
var y = obj2.f()    // During compilation, the type of y is C1

创建对象

定义了 class 类型后，即可通过调用其构造函数来创建对象（通过 class 类型名调用构造函数）。例如，下例中通过 Rectangle(10, 20) 创建 Rectangle 类型的对象并赋值给变量 r。

let r = Rectangle(10, 20)

创建对象之后，可以通过对象访问（public 修饰的）实例成员变量和实例成员函数。例如，下例中通过 r.width 和 r.height 可分别访问 r 中 width 和 height 的值，通过 r.area() 可以调用成员函数 area。

let r = Rectangle(10, 20) // r.width = 10, r.height = 20
let width = r.width       // width = 10
let height = r.height     // height = 20
let a = r.area()          // a = 200

如果希望通过对象去修改成员变量的值（不鼓励这种方式，最好还是通过成员函数去修改），需要将 class 类型中的成员变量定义为可变成员变量（即使用 var 定义）。举例如下：

class Rectangle {
    public var width: Int64
    public var height: Int64

    ...
}

main() {
    let r = Rectangle(10, 20) // r.width = 10, r.height = 20
    r.width = 8               // r.width = 8
    r.height = 24             // r.height = 24
    let a = r.area()          // a = 192
}

不同于 struct，对象在赋值或传参时，不会将对象进行复制，多个变量指向的是同一个对象，通过一个变量去修改对象中成员的值，其他变量中对应的成员变量也会被修改。以赋值为例，下面的例子中，将 r1 赋值给 r2 之后，修改 r1 的 width 和 height 的值，r2 的 width 和 height 值也同样会被修改。

main() {
    var r1 = Rectangle(10, 20) // r1.width = 10, r1.height = 20
    var r2 = r1                // r2.width = 10, r2.height = 20
    r1.width = 8               // r1.width = 8
    r1.height = 24             // r1.height = 24
    let a1 = r1.area()         // a1 = 192
    let a2 = r2.area()         // a2 = 192
}

class 的继承

像大多数支持 class 的编程语言一样，仓颉中的 class 同样支持继承。如果类 B 继承类 A，则我们称 A 为父类，B 为子类。子类将继承父类中除 private 成员和构造函数以外的所有成员。

抽象类总是可被继承的，故抽象类定义时的 open 修饰符是可选的，也可以使用 sealed 修饰符修饰抽象类，表示该抽象类只能在本包被继承。但非抽象的类可被继承是有条件的：定义时必须使用修饰符 open 修饰。当带 open 修饰的实例成员被 class 继承时，该 open 的修饰符也会被继承。当非 open 修饰的类中存在 open 修饰的成员时，编译器会给出告警。

可以在子类定义处通过 <: 指定其继承的父类，但要求父类必须是可继承的。例如，下面的例子中，class A 使用 open 修饰，是可以被类 B 继承的，但是因为类 B 是不可继承的，所以 C 在继承 B 的时候会报错。

open class A {
    let a: Int64 = 10
}

class B <: A { // Ok: 'B' Inheritance 'A'
    let b: Int64 = 20
}

class C <: B { // Error, 'B' is not inheritable
    let c: Int64 = 30
}

class 仅支持单继承，因此下面这样一个类继承两个类的代码是不合法的（& 是类实现多个接口时的语法，详见接口章节）。

open class A {
    let a: Int64 = 10
}

open class B {
    let b: Int64 = 20
}

class C <: A & B { // Error, 'C' can only inherit one class
    let c: Int64 = 30
}

因为类是单继承的，所以任何类都最多只能有一个直接父类。对于定义时指定了父类的 class，它的直接父类就是定义时指定的类，对于定义时未指定父类的 class，它的直接父类是 Object 类型。Object 是所有类的父类（注意，Object 没有直接父类，并且 Object 中不包含任何成员）。

因为子类是继承自父类的，所以子类的对象天然可以当做父类的对象使用，但是反之不然。例如，下例中 B 是 A 的子类，那么 B 类型的对象可以赋值给 A 类型的变量，但是 A 类型的对象不能赋值给 B 类型的变量。

open class A {
    let a: Int64 = 10
}

class B <: A {
    let b: Int64 = 20
}

let a: A = B() // Ok: subclass objects can be assigned to superclass variables

open class A {
    let a: Int64 = 10
}

class B <: A {
    let b: Int64 = 20
}

let b: B = A() // Error, superclass objects can not be assigned to subclass variables

class 定义的类型不允许继承类型本身。

class A <: A {}  // Error, 'A' inherits itself.

sealed 修饰符只能修饰抽象类，表示被修饰的类定义只能在本定义所在的包内被其他类继承。sealed 已经蕴含了 public/open 的语义，因此定义 sealed abstract class 时若提供 public/open 修饰符，编译器将会告警。sealed 的子类可以不是 sealed 类，仍可被 open/sealed 修饰，或不使用任何继承性修饰符。若 sealed 类的子类被 open 修饰，则其子类可在包外被继承。sealed 的子类可以不被 public 修饰。

package A
public sealed abstract class C1 {}   // Warning, redundant modifier, 'sealed' implies 'public'
sealed open abstract class C2 {}     // Warning, redundant modifier, 'sealed' implies 'open'
sealed abstract class C3 {}          // OK, 'public' is optional when 'sealed' is used

class S1 <: C1 {}  // OK
public open class S2 <: C1 {}   // OK
public sealed abstract class S3 <: C1 {}  // OK
open class S4 <: C1 {}   // OK

package B
import A.*

class SS1 <: S2 {}  // OK
class SS2 <: S3 {}  // Error, S3 is sealed class, cannot be inherited here.
sealed class SS3 {} // Error, 'sealed' cannot be used on non-abstract class.

父类构造函数调用

子类的 init 构造函数可以使用 super(args) 的形式调用父类构造函数，或使用 this(args) 的形式调用本类其它构造函数，但两者之间只能调用一个。如果调用，必须在构造函数体内的第一个表达式处，在此之前不能有任何表达式或声明。

open class A {
    A(let a: Int64) {}
}

class B <: A {
    let b: Int64
    init(b: Int64) {
        super(30)
        this.b = b
    }

    init() {
        this(20)
    }
}

子类的主构造函数中，可以使用 super(args) 的形式调用父类构造函数，但不能使用 this(args) 的形式调用本类其它构造函数。

如果子类的构造函数没有显式调用父类构造函数，也没有显式调用其他构造函数，编译器会在该构造函数体的开始处插入直接父类的无参构造函数的调用。如果此时父类没有无参构造函数，则会编译报错；

open class A {
    let a: Int64
    init() {
        a = 100
    }
}

open class B <: A {
    let b: Int64
    init(b: Int64) {
        // OK, `super()` added by compiler
        this.b = b
    }
}

open class C <: B {
    let c: Int64
    init(c: Int64) {  // Error, there is no non-parameter constructor in super class
        this.c = c
    }
}

覆盖和重定义

子类中可以覆盖（override）父类中的同名非抽象实例成员函数，即在子类中为父类中的某个实例成员函数定义新的实现。覆盖时，要求父类中的成员函数使用 open 修饰，子类中的同名函数使用 override 修饰，其中 override 是可选的。例如，下面的例子中，子类 B 中的函数 f 覆盖了父类 A 中的函数 f。

open class A {
    public open func f(): Unit {
        println("I am superclass")
    }
}

class B <: A {
    public override func f(): Unit {
        println("I am subclass")
    }
}

main() {
    let a: A = A()
    let b: A = B()
    a.f()
    b.f()
}

对于被覆盖的函数，调用时将根据变量的运行时类型（由实际赋给该变量的对象决定）确定调用的版本（即所谓的动态派发）。例如，上例中 a 的运行时类型是 A，因此 a.f() 调用的是父类 A 中的函数 f；b 的运行时类型是 B（编译时类型是 A），因此 b.f() 调用的是子类 B 中的函数 f。所以程序会输出：

I am superclass
I am subclass

对于静态函数，子类中可以重定义父类中的同名非抽象静态函数，即在子类中为父类中的某个静态函数定义新的实现。重定义时，要求子类中的同名静态函数使用 redef 修饰，其中 redef 是可选的。例如，下面的例子中，子类 D 中的函数 foo 重定义了父类 C 中的函数 foo。

open class C {
    public static func foo(): Unit {
        println("I am class C")
    }
}

class D <: C {
    public redef static func foo(): Unit {
        println("I am class D")
    }
}

main() {
    C.foo()
    D.foo()
}

对于被重定义的函数，调用时将根据 class 的类型决定调用的版本。例如，上例中 C.foo() 调用的是父类 C 中的函数 foo，D.foo() 调用的是子类 D 中的函数 foo。

I am class C
I am class D

如果抽象函数或 open 修饰的函数有命名形参，那么实现函数或 override 修饰的函数也需要保持同样的命名形参。

open class A {
    public open func f(a!: Int32): Int32 {
        a + 1
    }
}

class B <: A {
    public override func f(a!: Int32): Int32 { // Ok
        a + 2
    }
}

class C <: A {
    public override func f(b!: Int32): Int32 { // Error
        b + 3
    }
}

main() {
    B().f(a: 0)
    C().f(b: 0)
}

还需要注意的是，当实现或重定义的函数为泛型函数时，子类型函数的类型变元约束需要比父类型中对应函数更宽松或相同。

open class A {}
open class B <: A {}
open class C <: B {}

open class Base {
    static func f<T>(a: T): Unit where T <: B {}
    static func g<T>(): Unit where T <: B {}
}

class D <: Base {
    redef static func f<T>(a: T): Unit where T <: C {} // Error, stricter constraint
    redef static func g<T>(): Unit where T <: C {} // Error, stricter constraint
}

class E <: Base {
    redef static func f<T>(a: T): Unit where T <: A {} // OK: looser constraint
    redef static func g<T>(): Unit where T <: A {} // OK: looser constraint
}

class F <: Base {
    redef static func f<T>(a: T): Unit where T <: B {} // OK: same constraint
    redef static func g<T>(): Unit where T <: B {} // OK: same constraint
}

接口

接口用来定义一个抽象类型，它不包含数据，但可以定义类型的行为。一个类型如果声明实现某接口，并且实现了该接口中所有的成员，就被称为实现了该接口。

接口的成员可以包含：

• 成员函数
• 操作符重载函数
• 成员属性

这些成员都是抽象的，要求实现类型必须拥有对应的成员实现。

接口定义

一个简单的接口定义如下：

interface I { // 'open' modifier is optional.
    func f(): Unit
}

接口使用关键字 interface 声明，其后是接口的标识符 I 和接口的成员。接口成员可被 open 修饰符修饰，并且 open 修饰符是可选的。

当接口 I 声明了一个成员函数 f 之后，要为一个类型实现 I 时，就必须在该类型中实现一个对应的 f 函数。

因为 interface 默认具有 open 语义，所以 interface 定义时的 open 修饰符是可选的。

如下面的代码所示，定义了一个 class Foo，使用 Foo <: I 的形式声明了 Foo 实现 I 接口。

在 Foo 中必须包含 I 声明的所有成员的实现，即需要定义一个相同类型的 f，否则会由于没有实现接口而编译报错。

class Foo <: I {
    public func f(): Unit {
        println("Foo")
    }
}

main() {
    let a = Foo()
    let b: I = a
    b.f() // "Foo"
}

当某个类型实现了某个接口之后，该类型就会成为该接口的子类型。

对于上面的例子，Foo 是 I 的子类型，因此任何一个 Foo 类型的实例，都可以当作 I 类型的实例使用。

在 main 中我们将一个 Foo 类型的变量 a，赋值给一个 I 类型的变量 b。然后我们再调用 b 中的函数 f，就会打印出 Foo 实现的 f 版本。程序的输出结果为：

Foo

interface 也可以使用 sealed 修饰符表示只能在 interface 定义所在的包内继承、实现或扩展该 interface。sealed 已经蕴含了 public/open 的语义，因此定义 sealed interface 时若提供 public/open 修饰符，编译器将会告警。继承 sealed 接口的子接口或实现 sealed 接口的类仍可被 sealed 修饰或不使用 sealed 修饰。若 sealed 接口的子接口被 public 修饰，且不被 sealed 修饰，则其子接口可在包外被继承、实现或扩展。继承、实现 sealed 接口的类型可以不被 public 修饰。

package A
public interface I1 {}
sealed interface I2 {}         // OK
public sealed interface I3 {}  // Warning, redundant modifier, 'sealed' implies 'public'
sealed open interface I4 {}    // Warning, redundant modifier, 'sealed' implies 'open'

class C1 <: I1 {}
public open class C2 <: I1 {}
sealed class C3 <: I2 {}
extend Int64 <: I2 {}

package B
import A.*

class S1 <: I1 {}  // OK
class S2 <: I2 {}  // Error, I2 is sealed interface, cannot be inherited here.

通过接口的这种约束能力，我们可以对一系列的类型约定共同的功能，达到对功能进行抽象的目的。

例如下面的代码，我们可以定义一个 Flyable 接口，并且让其他具有 Flyable 属性的类实现它。

interface Flyable {
    func fly(): Unit
}

class Bird <: Flyable {
    public func fly(): Unit {
        println("Bird flying")
    }
}

class Bat <: Flyable {
    public func fly(): Unit {
        println("Bat flying")
    }
}

class Airplane <: Flyable {
    public func fly(): Unit {
        println("Airplane flying")
    }
}

func fly(item: Flyable): Unit {
    item.fly()
}

main() {
    let bird = Bird()
    let bat = Bat()
    let airplane = Airplane()
    fly(bird)
    fly(bat)
    fly(airplane)
}

编译并执行上面的代码，我们会看到如下输出：

Bird flying
Bat flying
Airplane flying

接口的成员可以是实例的或者静态的，以上的例子已经展示过实例成员函数的作用，接下来我们来看看静态成员函数的作用。

静态成员函数和实例成员函数类似，都要求实现类型提供实现。

例如下面的例子，我们定义了一个 NamedType 接口，这个接口含有一个静态成员函数 typename 用来获得每个类型的字符串名称。

这样其它类型在实现 NamedType 接口时就必须实现 typename 函数，之后我们就可以安全地在 NamedType 的子类型上获得类型的名称。

interface NamedType {
    static func typename(): String
}

class A <: NamedType {
    public static func typename(): String {
        "A"
    }
}

class B <: NamedType {
    public static func typename(): String {
        "B"
    }
}

main() {
    println("the type is ${ A.typename() }")
    println("the type is ${ B.typename() }")
}

程序输出结果为：

the type is A
the type is B

接口中的静态成员函数（或属性）可以没有默认实现，也可以拥有默认实现。

当其没有默认实现时，将无法通过接口类型名对其进行访问。例如下面的代码，直接访问 NamedType 的 typename 函数会发生编译报错，因为 NamedType 不具有 typename 函数的实现。

main() {
    NamedType.typename() // Error
}

接口中的静态成员函数（或属性）也可以拥有默认实现，当另一个类型继承拥有默认静态函数（或属性）实现的接口时，该类型可以不再实现这个静态成员函数（或属性），该函数（或属性）可以通过接口名和该类型名直接访问。如下用例，NamedType 的成员函数 typename 拥有默认实现，且在 A 中都可以不用再重新实现它，同时，也可以通过接口名和该类型名对其进行直接访问。

interface NamedType {
    static func typename(): String {
        "interface NamedType"
    }
}

class A <: NamedType {}

main() {
    println(NamedType.typename())
    println(A.typename())
    0
}

程序输出结果为：

interface NamedType
interface NamedType

通常我们会通过泛型约束，在泛型函数中使用这类静态成员。

例如下面的 printTypeName 函数，当我们约束泛型变元 T 是 NamedType 的子类型时，我们需要保证 T 的实例化类型中所有的静态成员函数（或属性）都必须拥有实现，以保证可以使用 T.typename 的方式访问泛型变元的实现，达到了我们对静态成员抽象的目的。详见泛型章节。

interface NamedType {
    static func typename(): String
}

interface I <: NamedType {
    static func typename(): String {
        f()
    }
    static func f(): String
}

class A <: NamedType {
    public static func typename(): String {
        "A"
    }
}

class B <: NamedType {
    public static func typename(): String {
        "B"
    }
}

func printTypeName<T>() where T <: NamedType {
    println("the type is ${ T.typename() }")
}

main() {
    printTypeName<A>() // Ok
    printTypeName<B>() // Ok
    printTypeName<I>() // Error, 'I' must implement all static function. Otherwise, an unimplemented 'f' is called, causing problems.
}

需要注意的是，接口的成员默认就被 public 修饰，不可以声明额外的访问控制修饰符，同时也要求实现类型必须使用 public 实现。

interface I {
    func f(): Unit
}

open class C <: I {
    protected func f() {} // Compiler Error, f needs to be public semantics
}

接口继承

当我们想为一个类型实现多个接口，可以在声明处使用 & 分隔多个接口，实现的接口之间没有顺序要求。

例如下面的例子，我们可以让 MyInt 同时实现 Addable 和 Subtractable 两个接口。

interface Addable {
    func add(other: Int64): Int64
}

interface Subtractable {
    func sub(other: Int64): Int64
}

class MyInt <: Addable & Subtractable {
    var value = 0
    public func add(other: Int64): Int64 {
        value + other
    }
    public func sub(other: Int64): Int64 {
        value - other
    }
}

接口可以继承一个或多个接口，但不能继承类。与此同时，接口继承的时候可以添加新的接口成员。

例如下面的例子，Calculable 接口继承了 Addable 和 Subtractable 两个接口，并且增加了乘除两种运算符重载。

interface Addable {
    func add(other: Int64): Int64
}

interface Subtractable {
    func sub(other: Int64): Int64
}

interface Calculable <: Addable & Subtractable {
    func mul(other: Int64): Int64
    func div(other: Int64): Int64
}

这样实现类型实现 Calculable 接口时就必须同时实现加减乘除四种运算符重载，不能缺少任何一个成员。

class MyInt <: Calculable {
    var value = 0
    public func add(other: Int64): Int64 {
        value + other
    }
    public func sub(other: Int64): Int64 {
        value - other
    }
    public func mul(other: Int64): Int64 {
        value * other
    }
    public func div(other: Int64): Int64 {
        value / other
    }
}

MyInt 实现 Calculable 的同时，也同时实现了 Calculable 继承的所有接口，因此 MyInt 也实现了 Addable 和 Subtractable，即同时是它们的子类型。

main() {
    let myInt = MyInt()
    let add: Addable = myInt
    let sub: Subtractable = myInt
    let calc: Calculable = myInt
}

对于 interface 的继承，子接口如果继承了父接口中有默认实现的函数或属性，则在子接口中不允许仅写此函数或属性的声明（即没有默认实现），而是必须要给出新的默认实现，并且函数定义前的 override 修饰符（或 redef 修饰符）是可选的；子接口如果继承了父接口中没有默认实现的函数或属性，则在子接口中允许仅写此函数或属性的声明（当然也允许定义默认实现），并且函数声明或定义前的 override 修饰符（或 redef 修饰符）是可选的。

interface I1 {
   func f(a: Int64) {
        a
   }
   static func g(a: Int64) {
        a
   }
   func f1(a: Int64): Unit
   static func g1(a: Int64): Unit
}

interface I2 <: I1 {
    /*'override' is optional*/ func f(a: Int64) {
       a + 1
    }
    override func f(a: Int32) {} // Error, override function 'f' does not have an overridden function from its supertypes
    static /*'redef' is optional*/ func g(a: Int64) {
       a + 1
    }
    /*'override' is optional*/ func f1(a: Int64): Unit {}
    static /*'redef' is optional*/ func g1(a: Int64): Unit {}
}

接口实现

仓颉所有的类型都可以实现接口，包括数值类型、Rune、String、struct、class、enum、Tuple、函数以及其它类型。

一个类型实现接口有三种途径：

1. 在定义类型时就声明实现接口，在以上的内容中我们已经见过相关例子。
2. 通过扩展实现接口，这种方式详见扩展章节。
3. 由语言内置实现，具体详见《仓颉编程语言库 API》相关文档。

实现类型声明实现接口时，需要实现接口中要求的所有成员，为此需要满足下面一些规则。

1. 对于成员函数和操作符重载函数，要求实现类型提供的函数实现与接口对应的函数名称相同、参数列表相同、返回类型相同。
2. 对于成员属性，要求是否被 mut 修饰保持一致，并且属性的类型相同。

所以大部分情况都如同上面的例子，我们需要让实现类型中包含与接口要求的一样的成员的实现。

但有个地方是个例外，如果接口中的成员函数或操作符重载函数的返回值类型是 class 类型，那么允许实现函数的返回类型是其子类型。

例如下面这个例子，I 中的 f 返回类型是一个 class 类型 Base，因此 C 中实现的 f 返回类型可以是 Base 的子类型 Sub。

open class Base {}
class Sub <: Base {}

interface I {
    func f(): Base
}

class C <: I {
    public func f(): Sub {
        Sub()
    }
}

除此以外，接口的成员还可以为 class 类型提供默认实现。拥有默认实现的接口成员，当实现类型是 class 的时候，class 可以不提供自己的实现而继承接口的实现。

注意：

默认实现只对类型是 class 的实现类型有效，对其它类型无效。

例如下面的代码中，SayHi 中的 say 拥有默认实现，因此 A 实现 SayHi 时可以继承 say 的实现，而 B 也可以选择提供自己的 say 实现。

interface SayHi {
    func say() {
        "hi"
    }
}

class A <: SayHi {}

class B <: SayHi {
    public func say() {
        "hi, B"
    }
}

特别地，如果一个类型在实现多个接口时，多个接口中包含同一个成员的默认实现，这时会发生多重继承的冲突，语言无法选择最适合的实现，因此这时接口中的默认实现也会失效，需要实现类型提供自己的实现。

例如下面的例子，SayHi 和 SayHello 中都包含了 say 的实现，Foo 在实现这两个接口时就必须提供自己的实现，否则会出现编译错误。

interface SayHi {
    func say() {
        "hi"
    }
}

interface SayHello {
    func say() {
        "hello"
    }
}

class Foo <: SayHi & SayHello {
    public func say() {
        "Foo"
    }
}

struct、enum 和 class 在实现接口时，函数或属性定义前的 override 修饰符（或 redef 修饰符）是可选的，无论接口中的函数或属性是否存在默认实现。

interface I {
    func foo(): Int64 {
        return 0
    }
}
enum E <: I{
    elem
    public override func foo(): Int64 {
        return 1
    }
}
struct S <: I {
    public override func foo(): Int64 {
        return 1
    }
}

Any 类型

Any 类型是一个内置的接口，它的定义如下面。

interface Any {}

仓颉中所有接口都默认继承它，所有非接口类型都默认实现它，因此所有类型都可以作为 Any 类型的子类型使用。

如下面的代码，我们可以将一系列不同类型的变量赋值给 Any 类型的变量。

main() {
    var any: Any = 1
    any = 2.0
    any = "hello, world!"
}

属性

属性（Properties）提供了一个 getter 和一个可选的 setter 来间接获取和设置值。

使用属性的时候与普通变量无异，我们只需要对数据操作，对内部的实现无感知，可以更便利地实现访问控制、数据监控、跟踪调试、数据绑定等机制。

属性在使用时可以作为表达式或被赋值。此处以类和接口为例进行说明，但属性不仅限于类和接口。

以下是一个简单的例子，b 是一个典型的属性，封装了外部对 a 的访问：

class Foo {
    private var a = 0

    public mut prop b: Int64 {
        get() {
            println("get")
            a
        }
        set(value) {
            println("set")
            a = value
        }
    }
}

main() {
    var x = Foo()
    let y = x.b + 1 // get
    x.b = y // set
}

此处 Foo 提供了一个名为 b 的属性，针对 getter/setter 这两个功能，仓颉提供了 get 和 set 两种语法来定义。当一个类型为 Foo 的变量 x 在访问 b 时，会调用 b 的 get 操作返回类型为 Int64 的值，因此可以用来与 1 相加；而当 x 在对 b 进行赋值时，会调用 b 的 set 操作，将 y 的值传给 set 的 value，最终将 value 的值赋值给 a。

通过属性 b，外部对 Foo 的成员变量 a 完全不感知，但却可以通过 b 做到同样地访问和修改操作，实现了有效的封装性。所以程序的输出如下：

get
set

属性定义

属性可以在 interface、class、struct、enum、extend 中定义。

一个典型的属性语法结构如下：

class Foo {
    public prop a: Int64 {
        get() { 0 }
    }
    public mut prop b: Int64 {
        get() { 0 }
        set(v) {}
    }
}

其中使用 prop 声明的 a 和 b 都是属性，a 和 b 的类型都是 Int64。a 是无 mut 修饰符的属性，这类属性有且仅有定义 getter（对应取值）实现。b 是使用 mut 修饰的属性，这类属性必须分别定义 getter（对应取值）和 setter（对应赋值）的实现。

属性的 getter 和 setter 分别对应两个不同的函数。

1. getter 函数类型是 () -> T，T 是该属性的类型，当使用该属性作为表达式时会执行 getter 函数。
2. setter 函数类型是 (T) -> Unit，T 是该属性的类型，形参名需要显式指定，当对该属性赋值时会执行 setter 函数。

getter 和 setter 的实现中可以和函数体一样包含声明和表达式，与函数体的规则一样，详见函数体章节。

setter 中的参数对应的是赋值时传入的值。

class Foo {
    private var j = 0
    public mut prop i: Int64 {
        get() {
            j
        }
        set(v) {
            j = v
        }
    }
}

需要注意的是，在属性的 getter 和 setter 中访问属性自身属于递归调用，与函数调用一样可能会出现死循环的情况。

修饰符

我们可以在 prop 前面声明需要的修饰符。

class Foo {
    public prop a: Int64 {
        get() {
            0
        }
    }
    private prop b: Int64 {
        get() {
            0
        }
    }
}

和成员函数一样，成员属性也支持 open、override、redef 修饰，所以我们也可以在子类型中覆盖/重定义父类型属性的实现。

子类型覆盖父类型的属性时，如果父类型属性带有 mut 修饰符，则子类型属性也需要带有 mut 修饰符，同时也必须保持一样的类型。

如下代码所示，A 中定义了 x 和 y 两个属性，B 中可以分别对 x 和 y 进行 override/redef：

open class A {
    private var valueX = 0
    private static var valueY = 0

    public open prop x: Int64 {
        get() { valueX }
    }

    public static mut prop y: Int64 {
        get() { valueY }
        set(v) {
            valueY = v
        }
    }
}
class B <: A {
    private var valueX2 = 0
    private static var valueY2 = 0

    public override prop x: Int64 {
        get() { valueX2 }
    }

    public redef static mut prop y: Int64 {
        get() { valueY2 }
        set(v) {
            valueY2 = v
        }
    }
}

抽象属性

类似于抽象函数，我们在 interface 和抽象类中也可以声明抽象属性，这些抽象属性没有实现。

interface I {
    prop a: Int64
}

abstract class C {
    public prop a: Int64
}

当实现类型实现 interface 或者非抽象子类继承抽象类时，必须要实现这些抽象属性。

与覆盖的规则一样，实现类型或子类在实现这些属性时，如果父类型属性带有 mut 修饰符，则子类型属性也需要带有 mut 修饰符，同时也必须保持一样的类型。

interface I {
    prop a: Int64
    mut prop b: Int64
}
class C <: I {
    private var value = 0

    public prop a: Int64 {
        get() { value }
    }

    public mut prop b: Int64 {
        get() { value }
        set(v) {
            value = v
        }
    }
}

通过抽象属性，我们可以让接口和抽象类对一些数据操作能以更加易用的方式进行约定，相比函数的方式要更加直观。

如下代码所示，如果我们要对一个 size 值的获取和设置进行约定，使用属性的方式 (I1) 相比使用函数的方式 (I2) 代码更少，也更加符合对数据操作的意图。

interface I1 {
    mut prop size: Int64
}

interface I2 {
    func getSize(): Int64
    func setSize(value: Int64): Unit
}

class C <: I1 & I2 {
    private var mySize = 0

    public mut prop size: Int64 {
        get() {
            mySize
        }
        set(value) {
            mySize = value
        }
    }

    public func getSize() {
        mySize
    }

    public func setSize(value: Int64) {
        mySize = value
    }
}

main() {
    let a: I1 = C()
    a.size = 5
    println(a.size)

    let b: I2 = C()
    b.setSize(5)
    println(b.getSize())
}

5
5

属性使用

属性分为实例成员属性和静态成员属性。成员属性的使用和成员变量的使用方式一样，详见成员变量章节。

class A {
    public prop x: Int64 {
        get() {
            123
        }
    }
    public static prop y: Int64 {
        get() {
            321
        }
    }
}

main() {
    var a = A()
    println(a.x) // 123
    println(A.y) // 321
}

结果为：

123
321

无 mut 修饰符的属性类似 let 声明的变量，不可以被赋值。

class A {
    private let value = 0
    public prop i: Int64 {
        get() {
            value
        }
    }
}

main() {
    var x = A()
    println(x.i) // OK
    x.i = 1 // Error
}

带有 mut 修饰符的属性类似 var 声明的变量，可以取值也可以被赋值。

class A {
    private var value: Int64 = 0
    public mut prop i: Int64 {
        get() {
            value
        }
        set(v) {
            value = v
        }
    }
}

main() {
    var x = A()
    println(x.i) // OK
    x.i = 1 // OK
}

0

子类型关系

与其他面向对象语言一样，仓颉语言提供子类型关系和子类型多态。举例说明（不限于下述用例）：

• 假设函数的形参是类型 T，则函数调用时传入的参数的实际类型既可以是 T 也可以是 T 的子类型（严格地说，T 的子类型已经包括 T 自身，下同）。
• 假设赋值表达式 = 左侧的变量的类型是 T，则 = 右侧的表达式的实际类型既可以是 T 也可以是 T 的子类型。
• 假设函数定义中用户标注的返回类型是 T，则函数体的类型（以及函数体内所有 return 表达式的类型）既可以是 T 也可以是 T 的子类型。

那么如何判定两个类型是否存在子类型关系呢？下面我们对此展开说明。

继承 class 带来的子类型关系

继承 class 后，子类即为父类的子类型。如下代码中， Sub 即为 Super 的子类型。

open class Super { }
class Sub <: Super { }

实现接口带来的子类型关系

实现接口（含扩展实现）后，实现接口的类型即为接口的子类型。如下代码中，I3 是 I1 和 I2 的子类型， C 是 I1 的子类型， Int64 是 I2 的子类型：

interface I1 { }
interface I2 { }

interface I3 <: I1 & I2 { }

class C <: I1 { }

extend Int64 <: I2 { }

需要注意的是，部分跨扩展类型赋值后的类型向下转换场景（is 或 as）暂不支持，可能出现判断失败，见如下示例：

// file1.cj
package p1

public class A{}

public func get(): Any {
    return A()
}

// =====================
// file2.cj
import p1.*

interface I0 {}

extend A <: I0 {}

main() {
    let v: Any = get()
    println(v is I0) // 无法正确判断类型，打印内容不确定
}

元组类型的子类型关系

仓颉语言中的元组类型也有子类型关系。直观的，如果一个元组 t1 的每个元素的类型都是另一个元组 t2 的对应位置元素类型的子类型，那么元组 t1 的类型也是元组 t2 的类型的子类型。例如下面的代码中，由于 C2 <: C1 和 C4 <: C3，因此也有 (C2, C4) <: (C1, C3) 以及 (C4, C2) <: (C3, C1)。

open class C1 { }
class C2 <: C1 { }

open class C3 { }
class C4 <: C3 { }

let t1: (C1, C3) = (C2(), C4()) // OK
let t2: (C3, C1) = (C4(), C2()) // OK

函数类型的子类型关系

仓颉语言中，函数是一等公民，而函数类型亦有子类型关系：给定两个函数类型 (U1) -> S2 和 (U2) -> S1，(U1) -> S2 <: (U2) -> S1 当且仅当 U2 <: U1 且 S2 <: S1（注意顺序）。例如下面的代码定义了两个函数 f : (U1) -> S2 和 g : (U2) -> S1，且 f 的类型是 g 的类型的子类型。由于 f 的类型是 g 的子类型，所以代码中使用到 g 的地方都可以换为 f。

open class U1 { }
class U2 <: U1 { }

open class S1 { }
class S2 <: S1 { }


func f(a: U1): S2 { S2() }
func g(a: U2): S1 { S1() }

func call1() {
    g(U2()) // Ok.
    f(U2()) // Ok.
}

func h(lam: (U2) -> S1): S1 {
    lam(U2())
}

func call2() {
    h(g) // Ok.
    h(f) // Ok.
}

对于上面的规则，S2 <: S1 部分很好理解：函数调用产生的结果数据会被后续程序使用，函数 g 可以产生 S1 类型的结果数据，函数 f 可以产生 S2 类型的结果，而 g 产生的结果数据应当能被 f 产生的结果数据替代，因此要求 S2 <: S1。

对于 U2 <: U1 的部分，可以这样理解：在函数调用产生结果前，它本身应当能够被调用，函数调用的实参类型固定不变，同时形参类型要求更宽松时，依然可以被调用，而形参类型要求更严格时可能无法被调用——例如给定上述代码中的定义 g(U2()) 可以被换为 f(U2())，正是因为实参类型 U2 的要求更严格于形参类型 U1 。

永远成立的子类型关系

仓颉语言中，有些预设的子类型关系是永远成立的：

• 一个类型 T 永远是自身的子类型，即 T <: T。
• Nothing 类型永远是其他任意类型 T 的子类型，即 Nothing <: T。
• 任意类型 T 都是 Any 类型的子类型，即 T <: Any。
• 任意 class 定义的类型都是 Object 的子类型，即如果有 class C {}，则 C <: Object。

传递性带来的子类型关系

子类型关系具有传递性。如下代码中，虽然只描述了 I2 <: I1，C <: I2，以及 Bool <: I2，但根据子类型的传递性，也隐式存在 C <: I1 以及 Bool <: I1 这两个子类型关系。

interface I1 { }
interface I2 <: I1 { }

class C <: I2 { }

extend Bool <: I2 { }

泛型类型的子类型关系

泛型类型间也有子类型关系，详见泛型类型的子类型关系章节。

类型转换

仓颉不支持不同类型之间的隐式转换（子类型天然是父类型，所以子类型到父类型的转换不是隐式类型转换），类型转换必须显式地进行。下面将依次介绍数值类型之间的转换，Rune 到 UInt32 和整数类型到 Rune 的转换，以及 is 和 as 操作符。

数值类型之间的转换

对于数值类型（包括：Int8，Int16，Int32，Int64，IntNative，UInt8，UInt16，UInt32，UInt64，UIntNative，Float16，Float32，Float64），仓颉支持使用 T(e) 的方式得到一个值等于 e，类型为 T 的值。其中，表达式 e 的类型和 T 可以是上述任意数值类型。

下面的例子展示了数值类型之间的类型转换：

main() {
    let a: Int8 = 10
    let b: Int16 = 20
    let r1 = Int16(a)
    println("The type of r1 is 'Int16', and r1 = ${r1}")
    let r2 = Int8(b)
    println("The type of r2 is 'Int8', and r2 = ${r2}")

    let c: Float32 = 1.0
    let d: Float64 = 1.123456789
    let r3 = Float64(c)
    println("The type of r3 is 'Float64', and r3 = ${r3}")
    let r4 = Float32(d)
    println("The type of r4 is 'Float32', and r4 = ${r4}")

    let e: Int64 = 1024
    let f: Float64 = 1024.1024
    let r5 = Float64(e)
    println("The type of r5 is 'Float64', and r5 = ${r5}")
    let r6 = Int64(f)
    println("The type of r6 is 'Int64', and r6 = ${r6}")
}

上述代码的执行结果为：

The type of r1 is 'Int16', and r1 = 10
The type of r2 is 'Int8', and r2 = 20
The type of r3 is 'Float64', and r3 = 1.000000
The type of r4 is 'Float32', and r4 = 1.123457
The type of r5 is 'Float64', and r5 = 1024.000000
The type of r6 is 'Int64', and r6 = 1024

Rune 到 UInt32 和整数类型到 Rune 的转换

Rune 到 UInt32 的转换使用 UInt32(e) 的方式，其中 e 是一个 Rune 类型的表达式，UInt32(e) 的结果是 e 的 Unicode scalar value 对应的 UInt32 类型的整数值。

整数类型到 Rune 的转换使用 Rune(num) 的方式，其中 num 的类型可以是任意的整数类型，且仅当 num 的值落在 [0x0000, 0xD7FF] 或 [0xE000, 0x10FFFF] （即 Unicode scalar value）中时，返回对应的 Unicode scalar value 表示的字符，否则，编译报错（编译时可确定 num 的值）或运行时抛异常。

下面的例子展示了 Rune 和 UInt32 之间的类型转换：

main() {
    let x: Rune = 'a'
    let y: UInt32 = 65
    let r1 = UInt32(x)
    let r2 = Rune(y)
    println("The type of r1 is 'UInt32', and r1 = ${r1}")
    println("The type of r2 is 'Rune', and r2 = ${r2}")
}

上述代码的执行结果为：

The type of r1 is 'UInt32', and r1 = 97
The type of r2 is 'Rune', and r2 = A

is 和 as 操作符

仓颉支持使用 is 操作符来判断某个表达式的类型是否是指定的类型（或其子类型）。具体而言，对于表达式 e is T（e 可以是任意表达式，T 可以是任何类型），当 e 的运行时类型是 T 的子类型时，e is T 的值为 true，否则 e is T 的值为 false。

下面的例子展示了 is 操作符的使用：

open class Base {
    var name: String = "Alice"
}
class Derived <: Base {
    var age: UInt8 = 18
}

main() {
    let a = 1 is Int64
    println("Is the type of 1 'Int64'? ${a}")
    let b = 1 is String
    println("Is the type of 1 'String'? ${b}")

    let b1: Base = Base()
    let b2: Base = Derived()
    var x = b1 is Base
    println("Is the type of b1 'Base'? ${x}")
    x = b1 is Derived
    println("Is the type of b1 'Derived'? ${x}")
    x = b2 is Base
    println("Is the type of b2 'Base'? ${x}")
    x = b2 is Derived
    println("Is the type of b2 'Derived'? ${x}")
}

上述代码的执行结果为：

Is the type of 1 'Int64'? true
Is the type of 1 'String'? false
Is the type of b1 'Base'? true
Is the type of b1 'Derived'? false
Is the type of b2 'Base'? true
Is the type of b2 'Derived'? true

as 操作符可以用于将某个表达式的类型转换为指定的类型。因为类型转换有可能会失败，所以 as 操作返回的是一个 Option 类型。具体而言，对于表达式 e as T（e 可以是任意表达式，T 可以是任何类型），当 e 的运行时类型是 T 的子类型时，e as T 的值为 Option<T>.Some(e)，否则 e as T 的值为 Option<T>.None。

下面的例子展示了 as 操作符的使用（注释中标明了 as 操作的结果）：

open class Base {
    var name: String = "Alice"
}
class Derived <: Base {
    var age: UInt8 = 18
}

let a = 1 as Int64     // a = Option<Int64>.Some(1)
let b = 1 as String    // b = Option<String>.None

let b1: Base = Base()
let b2: Base = Derived()
let d: Derived = Derived()
let r1 = b1 as Base    // r1 = Option<Base>.Some(b1)
let r2 = b1 as Derived // r2 = Option<Derived>.None
let r3 = b2 as Base    // r3 = Option<Base>.Some(b2)
let r4 = b2 as Derived // r4 = Option<Derived>.Some(b2)
let r5 = d as Base     // r5 = Option<Base>.Some(d)
let r6 = d as Derived  // r6 = Option<Derived>.Some(d)

泛型概述

在仓颉编程语言中，泛型指的是参数化类型，参数化类型是一个在声明时未知并且需要在使用时指定的类型。类型声明与函数声明可以是泛型的。最为常见的例子就是 Array<T>、Set<T> 等容器类型。以数组类型为例，当使用数组类型 Array 时，会需要其中存放的是不同的类型，我们不可能定义所有类型的数组，通过在类型声明中声明类型形参，在应用数组时再指定其中的类型，这样就可以减少在代码上的重复。

在仓颉中，class、interface、struct 与 enum 的声明都可以声明类型形参，也就是说它们都可以是泛型的。

为了方便讨论我们先定义以下几个常用的术语：

• 类型形参：一个类型或者函数声明可能有一个或者多个需要在使用处被指定的类型，这些类型就被称为类型形参。在声明形参时，需要给定一个标识符，以便在声明体中引用。
• 类型变元：在声明类型形参后，当我们通过标识符来引用这些类型时，这些标识符被称为类型变元。
• 类型实参：当我们在使用泛型声明的类型或函数时指定了泛型参数，这些参数被称为类型实参。
• 类型构造器：一个需要零个、一个或者多个类型作为实参的类型称为类型构造器。

类型形参在声明时一般在类型名称的声明或者函数名称的声明后，使用尖括号 <...> 括起来。例如泛型列表可声明为：

class List<T> {
    var elem: Option<T> = None
    var tail: Option<List<T>> = None
}

func sumInt(a: List<Int64>) {  }

其中 List<T> 中的 T 被称为类型形参。对于 elem: Option<T> 中对 T 的引用称为类型变元，同理 tail: Option<List<T>> 中的 T 也称为类型变元。函数 sumInt 的参数中 List<Int64> 的 Int64 被称为 List 的类型实参。 List 就是类型构造器，List<Int64> 通过 Int64 类型实参构造出了一个类型 Int64 的列表类型。

泛型函数

如果一个函数声明了一个或多个类型形参，则将其称为泛型函数。语法上，类型形参紧跟在函数名后，并用 <> 括起，如果有多个类型形参，则用“,”分离。

全局泛型函数

在声明全局泛型函数时，只需要在函数名后使用尖括号声明类型形参，然后就可以在函数形参、返回类型及函数体中对这一类型形参进行引用。例如 id 函数定义为：

func id<T>(a: T): T {
    return a
}

其中 (a: T) 是函数声明的形参，其中使用到了 id 函数声明的类型形参 T，并且在 id 函数的返回类型使用。

再比如另一个复杂的例子，定义如下一个泛型函数 composition，该函数声明了 3 个类型形参，分别是 T1, T2, T3，其功能是把两个函数 f: (T1) -> T2, g: (T2) -> T3 复合成类型为 (T1) -> T3 的函数。

func composition<T1, T2, T3>(f: (T1) -> T2, g: (T2) -> T3): (T1) -> T3 {
    return {x: T1 => g(f(x))}
}

因为被用来复合的函数可以是任意类型，例如可以是 (Int32) -> Bool, (Bool) -> Int64 的复合，也可以是 (Int64) -> Rune, (Rune) -> Int8 的复合，所以才需要使用泛型函数。

func times2(a: Int64): Int64 {
    return a * 2
}

func plus10(a: Int64): Int64 {
    return a + 10
}

func times2plus10(a: Int64) {
    return composition<Int64, Int64, Int64>(times2, plus10)(a)
}

main() {
  println(times2plus10(9))
  return 0
}

这里，我们复合两个 (Int64) -> Int64 的函数，将 9 先乘以 2，再加 10，结果会是 28。

28

局部泛型函数

局部函数也可以是泛型函数。例如泛型函数 id 可以嵌套定义在其它函数中：

func foo(a: Int64) {
    func id<T>(a: T): T { a }

    func double(a: Int64): Int64 { a + a }

    return (id<Int64> ~> double)(a) == (double ~> id<Int64>)(a)
}

main() {
    println(foo(1))
    return 0
}

这里由于 id 的单位元性质，函数 id<Int64> ~> double 和 double ~> id<Int64> 是等价的，结果是 true。

true

泛型成员函数

class、struct 与 enum 的成员函数可以是泛型的。例如：

class A {
    func foo<T>(a: T): Unit where T <: ToString {
        println("${a}")
    }
}

struct B {
    func bar<T>(a: T): Unit where T <: ToString {
        println("${a}")
    }
}

enum C {
    | X | Y

    func coo<T>(a: T): Unit where T <: ToString {
        println("${a}")
    }
}

main() {
    var a = A()
    var b = B()
    var c = C.X
    a.foo<Int64>(10)
    b.bar<String>("abc")
    c.coo<Bool>(false)
    return 0
}

程序输出的结果为：

10
abc
false

这里需要注意的是，class 中声明的泛型成员函数不能被 open 修饰，如果被 open 修饰则会报错，例如：

class A {
    public open func foo<T>(a: T): Unit where T <: ToString { // Error, open generic function is not allowed
        println("${a}")
    }
}

在为类型使用 extend 声明进行扩展时，扩展中的函数也可以是泛型的，例如我们可以为 Int64 类型增加一个泛型成员函数：

extend Int64 {
    func printIntAndArg<T>(a: T) where T <: ToString {
        println(this)
        println("${a}")
    }
}

main() {
    var a: Int64 = 12
    a.printIntAndArg<String>("twelve")
}

程序输出的结果将为：

12
twelve

静态泛型函数

interface、class、struct、enum 与 extend 中可以定义静态泛型函数，例如下例 ToPair class 中从 ArrayList 中返回一个元组：

import std.collection.*

class ToPair {
    public static func fromArray<T>(l: ArrayList<T>): (T, T) {
        return (l[0], l[1])
    }
}

main() {
    var res: ArrayList<Int64> = ArrayList([1,2,3,4])
    var a: (Int64, Int64) = ToPair.fromArray<Int64>(res)
    return 0
}

泛型接口

泛型可以用来定义泛型接口，以标准库中定义的 Iterable 为例，它需要返回一个 Iterator 类型，这一类型是一个容器的遍历器。 Iterator 是一个泛型接口，Iterator 内部有一个从容器类型中返回下一个元素的 next 成员函数，next 成员函数返回的类型是一个需要在使用时指定的类型，所以 Iterator 需要声明泛型参数。

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

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

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

泛型类

泛型接口中介绍了泛型接口的定义和使用，本节我们介绍泛型类的定义和使用。如 Map 的键值对就是使用泛型类来定义的。

可以看一下 Map 类型中的键值对 Node 类型就可以使用泛型类来定义：

public open class Node<K, V> where K <: Hashable & Equatable<K> {
    public var key: Option<K> = Option<K>.None
    public var value: Option<V> = Option<V>.None

    public init() {}

    public init(key: K, value: V) {
        this.key = Option<K>.Some(key)
        this.value = Option<V>.Some(value)
    }
}

由于键与值的类型有可能不相同，且可以为任意满足条件的类型，所以 Node 需要两个类型形参 K 与 V ，K <: Hashable, K <: Equatable<K> 是对于键类型的约束，意为 K 要实现 Hashable 与 Equatable<K> 接口，也就是 K 需要满足的条件。对于泛型约束，详见泛型约束章节。

泛型结构体

struct 类型的泛型与 class 是类似的，下面我们可以使用 struct 定义一个类似于二元元组的类型：

struct Pair<T, U> {
    let x: T
    let y: U
    public init(a: T, b: U) {
        x = a
        y = b
    }
    public func first(): T {
        return x
    }
    public func second(): U {
        return y
    }
}

main() {
    var a: Pair<String, Int64> = Pair<String, Int64>("hello", 0)
    println(a.first())
    println(a.second())
}

程序输出的结果为：

hello
0

在 Pair 中我们提供了 first 与 second 两个函数来取得元组的第一个与第二个元素。

泛型枚举

在仓颉编程语言中，泛型 enum 声明的类型里被使用得最广泛的例子之一就是 Option 类型了，关于 Option 详细描述可以详见 Option 类型章节。 Option 类型是用来表示在某一类型上的值可能是个空的值。这样，Option 就可以用来表示在某种类型上计算的失败。这里是何种类型上的失败是不确定的，所以很明显，Option 是一个泛型类型，需要声明类型形参。

package core // `Option` is defined in core.

public enum Option<T> {
      Some(T)
    | None

    public func getOrThrow(): T {
        match (this) {
            case Some(v) => v
            case None => throw NoneValueException()
        }
    }
    ...
}

可以看到，Option<T> 分成两种情况，一种是 Some(T)，用来表示一个正常的返回结果，另一种是 None 用来表示一个空的结果。其中的 getOrThrow 函数会是将 Some(T) 内部的值返回出来的函数，返回的结果就是 T 类型，而如果参数是 None，那么直接抛出异常。

例如：如果我们想定义一个安全的除法，因为在除法上的计算是可能失败的。如果除数为 0，那么返回 None ，否则返回一个用 Some 包装过的结果：

func safeDiv(a: Int64, b: Int64): Option<Int64> {
    var res: Option<Int64> = match (b) {
                case 0 => None
                case _ => Some(a/b)
            }
    return res
}

这样，在除数为 0 时，程序运行的过程中不会因除以 0 而抛出算术运算异常。

泛型类型的子类型关系

实例化后的泛型类型间也有子类型关系。例如当我们写出下列代码时，

interface I<X, Y> { }

class C<Z> <: I<Z, Z> { }

根据第 3 行，便知 C<Bool> <: I<Bool, Bool> 以及 C<D> <: I<D, D> 等。这里的第 3 行可以解读为“于所有的（不含类型变元的） Z 类型，都有 C<Z> <: I<Z, Z> 成立”。

但是对于下列代码

open class C { }
class D <: C { }

interface I<X> { }

I<D> <: I<C> 是不成立的（即使 D <: C 成立），这是因为在仓颉语言中，用户定义的类型构造器在其类型参数处是不型变的。

型变的具体定义为：如果 A 和 B 是（实例化后的）类型，T 是类型构造器，设有一个类型参数 X（例如 interface T<X>），那么

• 如果 T(A) <: T(B) 当且仅当 A = B，则 T 是不型变的。
• 如果 T(A) <: T(B) 当且仅当 A <: B ，则 T 在 X 处是协变的。
• 如果 T(A) <: T(B) 当且仅当 B <: A ，则 T 在 X 处是逆变的。

因为现阶段的仓颉中，所有用户自定义的泛型类型在其所有的类型变元处都是不变的，所以给定 interface I<X> 和类型 A、B，只有 A = B，我们才能得到 I<A> <: I<B>；反过来，如果知道了 I<A> <: I<B>，也可推出 A = B（内建类型除外：内建的元组类型对其每个元素类型来说，都是协变的；内建的函数类型在其入参类型处是逆变的，在其返回类型处是协变的。）

不型变限制了一些语言的表达能力，但也避免了一些安全问题，例如“协变数组运行时抛异常”的问题（Java 便有这个问题）。

类型别名

当某个类型的名字比较复杂或者在特定场景中不够直观时，可以选择使用类型别名的方式为此类型设置一个别名。

type I64 = Int64

类型别名的定义以关键字 type 开头，接着是类型的别名（如上例中的 I64），然后是等号 =，最后是原类型（即被取别名的类型，如上例中的 Int64）。

只能在源文件顶层定义类型别名，并且原类型必须在别名定义处可见。例如，下例中 Int64 的别名定义在 main 中将报错，LongNameClassB 类型在为其定义别名时不可见，同样报错。

main() {
    type I64 = Int64 // Error, type aliases can only be defined at the top level of the source file
}

class LongNameClassA { }
type B = LongNameClassB // Error, type 'LongNameClassB' is not defined

一个（或多个）类型别名定义中禁止出现（直接或间接的）循环引用。

type A = (Int64, A) // Error, 'A' refered itself

type B = (Int64, C) // Error, 'B' and 'C' are circularly refered
type C = (B, Int64)

类型别名并不会定义一个新的类型，它仅仅是为原类型定义了另外一个名字，它有如下几种使用场景：

1. 作为类型使用，例如：

   type A = B
   class B {}
   var a: A = B() // Use typealias A as type B
   

2. 当类型别名实际指向的类型为 class、struct 时，可以作为构造器名称使用：

   type A = B
   class B {}
   func foo() { A() }  // Use type alias A as constructor of B
   

3. 当类型别名实际指向的类型为 class、interface、struct 时，可以作为访问内部静态成员变量或函数的类型名：

   type A = B
   class B {
       static var b : Int32 = 0;
       static func foo() {}
   }
   func foo() {
       A.foo() // Use A to access static method in class B
       A.b
   }
   

4. 当类型别名实际指向的类型为 enum 时，可以作为 enum 声明的构造器的类型名：

   enum TimeUnit {
       Day | Month | Year
   }
   type Time = TimeUnit
   var a = Time.Day  
   var b = Time.Month   // Use type alias Time to access constructors in TimeUnit
   

需要注意的是，当前用户自定义的类型别名暂不支持在类型转换表达式中使用，参考如下示例：

type MyInt = Int32
MyInt(0)  // Error, no matching function for operator '()' function call

泛型别名

类型别名也是可以声明类型形参的，但是不能对其形参使用 where 声明约束，对于泛型变元的约束我们会在后面给出解释。

当一个泛型类型的名称过长时，我们就可以使用类型别名来为其声明一个更短的别名。例如，有一个类型为 RecordData ，我们可以把他用类型别名简写为 RD ：

struct RecordData<T> {
    var a: T
    public init(x: T){
        a = x
    }
}

type RD<T> = RecordData<T>

main(): Int64 {
    var struct1: RD<Int32> = RecordData<Int32>(2)
    return 1
}

在使用时就可以用 RD<Int32> 来代指 RecordData<Int32> 类型。

泛型约束

泛型约束的作用是在函数、class、enum、struct 声明时明确泛型形参所具备的操作与能力。只有声明了这些约束才能调用相应的成员函数。在很多场景下泛型形参是需要加以约束的。以 id 函数为例：

func id<T>(a: T) {
    return a
}

我们唯一能做的事情就是将函数形参 a 这个值返回，而不能进行 a + 1，println("${a}") 等操作，因为它可能是一个任意的类型，比如 (Bool) -> Bool，这样就无法与整数相加，同样因为是函数类型，也不能通过 println 函数来输出在命令行上。而如果这一泛型形参上有了约束，那么就可以做更多操作了。

约束大致分为接口约束与子类型约束。语法为在函数、类型的声明体之前使用 where 关键字来声明，对于声明的泛型形参 T1, T2，可以使用 where T1 <: Interface, T2 <: Type 这样的方式来声明泛型约束，同一个类型变元的多个约束可以使用 & 连接。例如：where T1 <: Interface1 & Interface2。

例如，仓颉中的 println 函数能接受类型为字符串的参数，如果我们需要把一个泛型类型的变量转为字符串后打印在命令行上，可以对这个泛型类型变元加以约束，这个约束是 core 中定义的 ToString 接口，显然它是一个接口约束：

package core // `ToString` is defined in core.

public interface ToString {
    func toString(): String
}

这样我们就可以利用这个约束，定义一个名为 genericPrint 的函数：

func genericPrint<T>(a: T) where T <: ToString {
    println(a)
}

main() {
    genericPrint<Int64>(10)
    return 0
}

结果为：

10

如果 genericPrint 函数的类型实参没有实现 ToString 接口，那么编译器会报错。例如我们传入一个函数做为参数时：

func genericPrint<T>(a: T) where T <: ToString {
    println(a)
}

main() {
    genericPrint<(Int64) -> Int64>({ i => 0 })
    return 0
}

如果我们对上面的文件进行编译，那么编译器会抛出泛型类型参数与满足约束的错误。因为 genericPrint 函数的泛型的类型实参不满足约束 (Int64) -> Int64 <: ToString。

除了上述通过接口来表示约束，还可以使用子类型来约束一个泛型类型变元。例如：当我们要声明一个动物园类型 Zoo<T>，但是我们需要这里声明的类型形参 T 受到约束，这个约束就是 T 需要是动物类型 Animal 的子类型， Animal 类型中声明了 run 成员函数。这里我们声明两个子类型 Dog 与 Fox 都实现了 run 成员函数，这样在 Zoo<T> 的类型中，我们就可以对于 animals 数组列表中存放的动物实例调用 run 成员函数：

import std.collection.*

abstract class Animal {
    public func run(): String
}

class Dog <: Animal {
    public func run(): String {
        return "dog run"
    }
}

class Fox <: Animal {
    public func run(): String {
        return "fox run"
    }
}

class Zoo<T> where T <: Animal {
    var animals: ArrayList<Animal> = ArrayList<Animal>()
    public func addAnimal(a: T) {
        animals.append(a)
    }

    public func allAnimalRuns() {
        for(a in animals) {
            println(a.run())
        }
    }
}

main() {
    var zoo: Zoo<Animal> = Zoo<Animal>()
    zoo.addAnimal(Dog())
    zoo.addAnimal(Fox())
    zoo.allAnimalRuns()
    return 0
}

程序的输出为：

dog run
fox run

扩展概述

扩展可以为在当前 package 可见的类型（除函数、元组、接口）添加新功能。

当我们不能破坏原有类型的封装性，但希望添加额外的功能时，可以使用扩展。

可以添加的功能包括：

• 添加成员函数
• 添加操作符重载函数
• 添加成员属性
• 实现接口

扩展虽然可以添加额外的功能，但不能变更原有类型的封装性，因此扩展不支持以下功能：

1. 扩展不能增加成员变量。
2. 扩展的函数和属性必须拥有实现。
3. 扩展的函数和属性不能使用 open、override、 redef修饰。
4. 扩展不能访问原类型 private 的成员。

根据扩展有没有实现新的接口，扩展可以分为 直接扩展 和 接口扩展 两种用法，直接扩展即不包含额外接口的扩展；接口扩展即包含接口的扩展，接口扩展可以用来为现有的类型添加新功能并实现接口，增强抽象灵活性。

直接扩展

一个简单的扩展语法结构示例如下：

extend String {
    public func printSize() {
        println("the size is ${this.size}")
    }
}

如上例所示，扩展使用 extend 关键字声明，其后跟着被扩展的类型 String 和扩展的功能。

当为 String 扩展了 printSize 函数之后，我们就能在当前 package 内对 String 的实例访问该函数，就像是 String 本身具备该函数。

main() {
    let a = "123"
    a.printSize() // the size is 3
}

编译执行上述代码，输出结果为：

the size is 3

被扩展类型是泛型类型时，有两种扩展语法可以对泛型类型扩展功能。

一种是针对特定泛型实例化类型进行扩展，关键字 extend 后允许带一个任意实例化完全的泛型类型。为这些类型增加的功能只有在类型完全匹配时才能使用，且泛型类型的类型实参必须符合泛型类型定义处的约束要求。

例如下面所示的 Foo<T>。

class Foo<T> where T <: ToString {}

extend Foo<Int64> {} // Ok

class Bar {}
extend Foo<Bar> {} // Error

另一种是在 extend 后面引入泛型形参的泛型扩展。泛型扩展可以用来扩展未实例化或未完全实例化的泛型类型。在 extend 后声明的泛型形参必须被直接或间接使用在被扩展的泛型类型上。为这些类型增加的功能只有在类型和约束完全匹配时才能使用。

例如下面所示的 MyList<T>。

class MyList<T> {
    public let data: Array<T> = Array<T>()
}

extend<T> MyList<T> {} // OK
extend<R> MyList<R> {} // OK
extend<T, R> MyList<(T, R)> {} // OK
extend MyList {} // Error
extend<T, R> MyList<T> {} // Error
extend<T, R> MyList<T, R> {} // Error

对于泛型类型的扩展，我们可以在其中声明额外的泛型约束，来实现一些有限情况下才能使用的函数。

例如我们可以定义一个叫 Pair 的类型，这个类型可以让我们方便的存储两个元素（类似于 Tuple）。

我们希望 Pair 类型可以容纳任何类型，因此两个泛型变元不应该有任何约束，这样才能保证 Pair 能容纳所有类型。

但同时我们又希望当两个元素可以判等的时候，让 Pair 也可以判等，这时就可以用扩展来实现这个功能。

如下面的代码所示，我们使用扩展语法，约束了 T1 和 T2 在支持 equals 的情况下，Pair 也可以实现 equals 函数。

class Pair<T1, T2> {
    var first: T1
    var second: T2
    public init(a: T1, b: T2) {
        first = a
        second = b
    }
}

interface Eq<T> {
    func equals(other: T): Bool
}

extend<T1, T2> Pair<T1, T2> where T1 <: Eq<T1>, T2 <: Eq<T2> {
    public func equals(other: Pair<T1, T2>) {
        first.equals(other.first) && second.equals(other.second)
    }
}

class Foo <: Eq<Foo> {
    public func equals(other: Foo): Bool {
        true
    }
}

main() {
    let a = Pair(Foo(), Foo())
    let b = Pair(Foo(), Foo())
    println(a.equals(b)) // true
}

编译执行上述代码，输出结果为：

true

接口扩展

例如下面的例子，类型 Array 本身没有实现接口 PrintSizeable，但我们可以通过扩展的方式为 Array 增加额外的成员函数 printSize，并实现 PrintSizeable。

interface PrintSizeable {
    func printSize(): Unit
}

extend<T> Array<T> <: PrintSizeable {
    public func printSize() {
        println("The size is ${this.size}")
    }
}

当使用扩展为 Array 实现 PrintSizeable 之后，就相当于在 Array 定义时实现接口 PrintSizeable。

因此我们可以将 Array 作为 PrintSizeable 的实现类型来使用了，如以下代码所示。

main() {
    let a: PrintSizeable = Array<Int64>()
    a.printSize() // 0
}

编译执行上述代码，输出结果为：

The size is 0

我们可以在同一个扩展内同时实现多个接口，多个接口之间使用 & 分开，接口的顺序没有先后关系。

如下面代码所示，我们可以在扩展中为 Foo 同时实现 I1、I2、I3。

interface I1 {
    func f1(): Unit
}

interface I2 {
    func f2(): Unit
}

interface I3 {
    func f3(): Unit
}

class Foo {}

extend Foo <: I1 & I2 & I3 {
    public func f1(): Unit {}
    public func f2(): Unit {}
    public func f3(): Unit {}
}

我们也可以在接口扩展中声明额外的泛型约束，来实现一些特定约束下才能满足的接口。

例如我们可以让上面的 Pair 类型实现 Eq 接口，这样 Pair 自己也能成为一个符合 Eq 约束的类型，如下代码所示。

class Pair<T1, T2> {
    var first: T1
    var second: T2
    public init(a: T1, b: T2) {
        first = a
        second = b
    }
}

interface Eq<T> {
    func equals(other: T): Bool
}

extend<T1, T2> Pair<T1, T2> <: Eq<Pair<T1, T2>> where T1 <: Eq<T1>, T2 <: Eq<T2> {
    public func equals(other: Pair<T1, T2>) {
        first.equals(other.first) && second.equals(other.second)
    }
}

class Foo <: Eq<Foo> {
    public func equals(other: Foo): Bool {
        true
    }
}

main() {
    let a = Pair(Foo(), Foo())
    let b = Pair(Foo(), Foo())
    println(a.equals(b)) // true
}

编译执行上述代码，输出结果为：

true

如果被扩展的类型已经包含接口要求的函数或属性，那么我们在扩展中不需要并且也不能重新实现这些函数或属性。

例如下面的例子，我们定义了一个新接口 Sizeable，目的是获得某个类型的 size，而我们已经知道 Array 中包含了这个函数，因此我们就可以通过扩展让 Array 实现 Sizeable，而不需要添加额外的函数。

interface Sizeable {
    prop size: Int64
}

extend<T> Array<T> <: Sizeable {}

main() {
    let a: Sizeable = Array<Int64>()
    println(a.size)
}

编译执行上述代码，输出结果为：

0

访问规则

扩展的修饰符

扩展本身不能使用修饰符修饰。

例如，下面的例子中对 A 的直接扩展前使用了 public 修饰，将编译报错。

public class A {}

public extend A {}  // Error, expected no modifier before extend

扩展成员可使用的修饰符有：static、public、protected（仅限于被扩展类型是 class 类型）、private、mut。

• 使用 private 修饰的成员只能在本扩展内使用，外部不可见。
• 使用 protected 修饰的成员除了能在本包内被访问，对包外的当前 class 子类也可以访问。
• 没有使用 private，protected 或 public 修饰的成员只能在本包内使用。
• 使用 static 修饰的成员，只能通过类型名访问，不能通过实例对象访问。
• 对 struct 类型的扩展可以定义 mut 函数。

package p1

public open class A {}

extend A {
    public func f1() {}
    protected func f2() {}
    private func f3() {}
    static func f4() {}
}

main() {
    A.f4()
    var a = A()
    a.f1()
    a.f2()
}

扩展内的成员定义不支持使用 open、override、redef 修饰。

class Foo {
    public open func f() {}
    static func h() {}
}

extend Foo {
    public override func f() {} // Error
    public open func g() {} // Error
    redef static func h() {} // Error
}

扩展的孤儿规则

为一个其它 package 的类型实现另一个 package 的接口，可能造成理解上的困扰。

为了防止一个类型被意外实现不合适的接口，仓颉不允许定义孤儿扩展，指的是既不与接口（包含接口继承链上的所有接口）定义在同一个包中，也不与被扩展类型定义在同一个包中的接口扩展。

如下代码所示，我们不能在 package c 中，为 package a 里的 Foo 实现 package b 里的 Bar。

我们只能在 package a 或者在 package b 中为 Foo 实现 Bar。

// package a
public class Foo {}

// package b
public interface Bar {}

// package c
import a.Foo
import b.Bar

extend Foo <: Bar {} // Error

扩展的访问和遮盖

扩展的实例成员与类型定义处一样可以使用 this，this 的功能保持一致。同样也可以省略 this 访问成员。扩展的实例成员不能使用 super。

class A {
    var v = 0
}

extend A {
    func f() {
        print(this.v) // Ok
        print(v) // Ok
    }
}

扩展不能访问被扩展类型的 private 修饰的成员（意味着非 private 修饰的成员均能被访问）。

class A {
    private var v1 = 0
    protected var v2 = 0
}

extend A {
    func f() {
        print(v1) // Error
        print(v2) // Ok
    }
}

扩展不能遮盖被扩展类型的任何成员。

class A {
    func f() {}
}

extend A {
    func f() {} // Error
}

扩展也不允许遮盖其它扩展增加的任何成员。

class A {}

extend A {
    func f() {}
}

extend A {
    func f() {} // Error
}

在同一个 package 内对同一类型可以扩展多次。

在扩展中可以直接调用（不加任何前缀修饰）其它对同一类型的扩展中的非 private 修饰的函数。

class Foo {}

extend Foo { // OK
    private func f() {}
    func g() {}
}

extend Foo { // OK
    func h() {
        g() // OK
        f() // Error
    }
}

扩展泛型类型时，可以使用额外的泛型约束。泛型类型的任意两个扩展之间的可见性规则如下：

• 如果两个扩展的约束相同，则两个扩展相互可见，即两个扩展内可以直接使用对方内的函数或属性；
• 如果两个扩展的约束不同，且两个扩展的约束有包含关系，约束更宽松的扩展对约束更严格的扩展可见，反之，不可见；
• 当两个扩展的约束不同时，且两个约束不存在包含关系，则两个扩展均互相不可见。

示例：假设对同一个类型 E<X> 的两个扩展分别为扩展 1 和扩展 2 ，X 的约束在扩展 1 中比扩展 2 中更严格，那么扩展 1 中的函数和属性对扩展 2 均不可见，反之，扩展 2 中的函数和属性对扩展 1 可见。

open class A {}
class B <: A {}
class E<X> {}

interface I1 {
    func f1(): Unit
}
interface I2 {
    func f2(): Unit
}

extend<X> E<X> <: I1 where X <: B {  // extension 1
    public func f1(): Unit {
        f2() // OK
    }
}

extend<X> E<X> <: I2 where X <: A   { // extension 2
    public func f2(): Unit {
        f1() // Error
    }
}

扩展的导入导出

扩展也是可以被导入和导出的，但是扩展本身不能使用 public 修饰，扩展的导出有一套特殊的规则。

对于直接扩展，只有当扩展与被扩展的类型在同一个 package，并且被扩展的类型和扩展中添加的成员都使用 public 或 protected 修饰时，扩展的功能才会被导出。

除此以外的直接扩展均不能被导出，只能在当前 package 使用。

如以下代码所示，Foo 是使用 public 修饰的类型，并且 f 与 Foo 在同一个 package 内，因此 f 会跟随 Foo 一起被导出。而 g 和 Foo 不在同一个 package，因此 g 不会被导出。

// package a

public class Foo {}

extend Foo {
    public func f() {}
}

// package b
import a.*

extend Foo {
    public func g() {}
}

// package c
import a.*
import b.*

main() {
    let a = Foo()
    a.f() // OK
    a.g() // Error
}

对于接口扩展则分为两种情况：

1. 如果接口扩展和被扩展类型在同一个 package，但接口是来自导入的，只有当被扩展类型使用 public 修饰时，扩展的功能才会被导出。
2. 如果接口扩展与接口在同一个 package，则只有当接口是使用 public 修饰时，扩展的功能才会被导出。

如下代码所示，Foo 和 I 都使用了 public 修饰，因此对 Foo 的扩展就可以被导出。

// package a

public class Foo {}

public interface I {
    func g(): Unit
}

extend Foo <: I {
    public func g(): Unit {}
}

// package b
import a.*

main() {
    let a: I = Foo()
    a.g()
}

与扩展的导出类似，扩展的导入也不需要显式地用 import 导入，扩展的导入只需要导入被扩展的类型和接口，就可以导入可访问的所有扩展。

如下面的代码所示，在 package b 中，只需要导入 Foo 就可以使用 Foo 对应的扩展中的函数 f。

而对于接口扩展，需要同时导入被扩展的类型和扩展的接口才能使用，因此在 package c 中，需要同时导入 Foo 和 I 才能使用对应扩展中的函数 g。

// package a
public class Foo {}
extend Foo {
    public func f() {}
}

// package b
import a.Foo

public interface I {
    func g(): Unit
}
extend Foo <: I {
    public func g() {
        this.f() // OK
    }
}

// package c
import a.Foo
import b.I

func test() {
    let a = Foo()
    a.f() // OK
    a.g() // OK
}

基础 Collection 类型概述

本章我们来看看仓颉中常用的几种基础 Collection 类型，包含 Array、ArrayList、HashSet、HashMap。

我们可以在不同的场景中选择适合我们业务的类型：

• Array：如果我们不需要增加和删除元素，但需要修改元素，就应该使用它。
• ArrayList：如果我们需要频繁对元素增删查改，就应该使用它。
• HashSet：如果我们希望每个元素都是唯一的，就应该使用它。
• HashMap：如果我们希望存储一系列的映射关系，就应该使用它。

下表是这些类型的基础特性：

ArrayList

使用 ArrayList 类型需要导入 collection 包：

import std.collection.*

仓颉使用 ArrayList<T> 表示 ArrayList 类型，T 表示 ArrayList 的元素类型，T 可以是任意类型。

ArrayList 具备非常好的扩容能力，适合于需要频繁增加和删除元素的场景。

相比 Array，ArrayList 既可以原地修改元素，也可以原地增加和删除元素。

ArrayList 的可变性是一个非常有用的特征，我们可以让同一个 ArrayList 实例的所有引用都共享同样的元素，并且对它们统一进行修改。

var a: ArrayList<Int64> = ... // ArrayList whose element type is Int64
var b: ArrayList<String> = ... // ArrayList whose element type is String

元素类型不相同的 ArrayList 是不相同的类型，所以它们之间不可以互相赋值。

因此以下例子是不合法的。

b = a // Type mismatch

仓颉中可以使用构造函数的方式构造一个指定的 ArrayList。

let a = ArrayList<String>() // Created an empty ArrayList whose element type is String
let b = ArrayList<String>(100) // Created an ArrayList whose element type is String, and allocate a space of 100
let c = ArrayList<Int64>([0, 1, 2]) // Created an ArrayList whose element type is Int64, containing elements 0, 1, 2
let d = ArrayList<Int64>(c) // Use another Collection to initialize an ArrayList
let e = ArrayList<String>(2, {x: Int64 => x.toString()}) // Created an ArrayList whose element type is String and size is 2. All elements are initialized by specified rule function

访问 ArrayList 成员

当我们需要对 ArrayList 的所有元素进行访问时，可以使用 for-in 循环遍历 ArrayList 的所有元素。

import std.collection.*

main() {
    let list = ArrayList<Int64>([0, 1, 2])
    for (i in list) {
        println("The element is ${i}")
    }
}

编译并执行上面的代码，会输出：

The element is 0
The element is 1
The element is 2

当我们需要知道某个 ArrayList 包含的元素个数时，可以使用 size 属性获得对应信息。

import std.collection.*

main() {
    let list = ArrayList<Int64>([0, 1, 2])
    if (list.size == 0) {
        println("This is an empty arraylist")
    } else {
        println("The size of arraylist is ${list.size}")
    }
}

编译并执行上面的代码，会输出：

The size of arraylist is 3

当我们想访问单个指定位置的元素时，可以使用下标语法访问（下标的类型必须是 Int64）。非空 ArrayList 的第一个元素总是从位置 0 开始的。我们可以从 0 开始访问 ArrayList 的任意一个元素，直到最后一个位置（ArrayList 的 size - 1）。使用负数或大于等于 size 的索引会触发运行时异常。

let a = list[0] // a == 0
let b = list[1] // b == 1
let c = list[-1] // Runtime exceptions

ArrayList 也支持下标中使用 Range 的语法，详见 Array 章节。

修改 ArrayList

我们可以使用下标语法对某个位置的元素进行修改。

let list = ArrayList<Int64>([0, 1, 2])
list[0] = 3

ArrayList 是引用类型，ArrayList 在作为表达式使用时不会拷贝副本，同一个 ArrayList 实例的所有引用都会共享同样的数据。

因此对 ArrayList 元素的修改会影响到该实例的所有引用。

let list1 = ArrayList<Int64>([0, 1, 2])
let list2 = list1
list2[0] = 3
// list1 contains elements 3, 1, 2
// list2 contains elements 3, 1, 2

如果需要将单个元素添加到 ArrayList 的末尾，请使用 append 函数。如果希望同时添加多个元素到末尾，可以使用 appendAll 函数，这个函数可以接受其它相同元素类型的 Collection 类型（例如 Array）。

import std.collection.*

main() {
    let list = ArrayList<Int64>()
    list.append(0) // list contains element 0
    list.append(1) // list contains elements 0, 1
    let li = [2, 3]
    list.appendAll(li) // list contains elements 0, 1, 2, 3
}

我们可以通过 insert 和 insertAll 函数将指定的单个元素或相同元素类型的 Collection 值插入到我们指定索引的位置。该索引处的元素和后面的元素会被挪后以腾出空间。

let list = ArrayList<Int64>([0, 1, 2]) // list contains elements 0, 1, 2
list.insert(1, 4) // list contains elements 0, 4, 1, 2

从 ArrayList 中删除元素，可以使用 remove 函数，需要指定删除的索引。该索引处后面的元素会挪前以填充空间。

let list = ArrayList<String>(["a", "b", "c", "d"]) // list contains the elements "a", "b", "c", "d"
list.remove(1) // Delete the element at subscript 1, now the list contains elements "a", "c", "d"

增加 ArrayList 的大小

每个 ArrayList 都需要特定数量的内存来保存其内容。当我们向 ArrayList 添加元素并且该 ArrayList 开始超出其保留容量时，该 ArrayList 会分配更大的内存区域并将其所有元素复制到新内存中。这种增长策略意味着触发重新分配内存的添加操作具有性能成本，但随着 ArrayList 的保留内存变大，它们发生的频率会越来越低。

如果我们知道大约需要添加多少个元素，可以在添加之前预备足够的内存以避免中间重新分配，这样可以提升性能表现。

import std.collection.*

main() {
    let list = ArrayList<Int64>(100) // Allocate space at once
    for (i in 0..100) {
        list.append(i) // Does not trigger reallocation of space
    }
    list.reserve(100) // Prepare more space
    for (i in 0..100) {
        list.append(i) // Does not trigger reallocation of space
    }
}

HashSet

使用 HashSet 类型需要导入 collection 包：

import std.collection.*

我们可以使用 HashSet 类型来构造只拥有不重复元素的 Collection。

仓颉使用 HashSet<T> 表示 HashSet 类型，T 表示 HashSet 的元素类型，T 必须是实现了 Hashable 和 Equatable<T> 接口的类型，例如数值或 String。

var a: HashSet<Int64> = ... // HashSet whose element type is Int64
var b: HashSet<String> = ... // HashSet whose element type is String

元素类型不相同的 HashSet 是不相同的类型，所以它们之间不可以互相赋值。

因此以下例子是不合法的。

b = a // Type mismatch

仓颉中可以使用构造函数的方式构造一个指定的 HashSet。

let a = HashSet<String>() // Created an empty HashSet whose element type is String
let b = HashSet<String>(100) // Created a HashSet whose capacity is 100
let c = HashSet<Int64>([0, 1, 2]) // Created a HashSet whose element type is Int64, containing elements 0, 1, 2
let d = HashSet<Int64>(c) // Use another Collection to initialize a HashSet
let e = HashSet<Int64>(10, {x: Int64 => (x * x)}) // Created a HashSet whose element type is Int64 and size is 10. All elements are initialized by specified rule function

访问 HashSet 成员

当我们需要对 HashSet 的所有元素进行访问时，可以使用 for-in 循环遍历 HashSet 的所有元素。

需要注意的是，HashSet 并不保证按插入元素的顺序排列，因此遍历的顺序和插入的顺序可能不同。

import std.collection.*

main() {
    let mySet = HashSet<Int64>([0, 1, 2])
    for (i in mySet) {
        println("The element is ${i}")
    }
}

编译并执行上面的代码，有可能会输出：

The element is 0
The element is 1
The element is 2

当我们需要知道某个 HashSet 包含的元素个数时，可以使用 size 属性获得对应信息。

import std.collection.*

main() {
    let mySet = HashSet<Int64>([0, 1, 2])
    if (mySet.size == 0) {
        println("This is an empty hashset")
    } else {
        println("The size of hashset is ${mySet.size}")
    }
}

编译并执行上面的代码，会输出：

The size of hashset is 3

当我们想判断某个元素是否被包含在某个 HashSet 中时，可以使用 contains 函数。如果该元素存在会返回 true，否则返回 false。

let mySet = HashSet<Int64>([0, 1, 2])
let a = mySet.contains(0) // a == true
let b = mySet.contains(-1) // b == false

修改 HashSet

HashSet 是一种可变的引用类型，HashSet 类型提供了添加元素、删除元素的功能。

HashSet 的可变性是一个非常有用的特征，我们可以让同一个 HashSet 实例的所有引用都共享同样的元素，并且对它们统一进行修改。

如果需要将单个元素添加到 HashSet 的末尾，请使用 put 函数。如果希望同时添加多个元素，可以使用 putAll 函数，这个函数可以接受另一个相同元素类型的 Collection 类型（例如 Array）。当元素不存在时，put 函数会执行添加的操作，当 HashSet 中存在相同元素时，put 函数将不会有效果。

let mySet = HashSet<Int64>()
mySet.put(0) // mySet contains elements 0
mySet.put(0) // mySet contains elements 0
mySet.put(1) // mySet contains elements 0, 1
let li = [2, 3]
mySet.putAll(li) // mySet contains elements 0, 1, 2, 3

HashSet 是引用类型，HashSet 在作为表达式使用时不会拷贝副本，同一个 HashSet 实例的所有引用都会共享同样的数据。

因此对 HashSet 元素的修改会影响到该实例的所有引用。

let set1 = HashSet<Int64>([0, 1, 2])
let set2 = set1
set2.put(3)
// set1 contains elements 0, 1, 2, 3
// set2 contains elements 0, 1, 2, 3

从 HashSet 中删除元素，可以使用 remove 函数，需要指定删除的元素。

let mySet = HashSet<Int64>([0, 1, 2, 3])
mySet.remove(1) // mySet contains elements 0, 2, 3

HashMap

使用 HashMap 类型需要导入 collection 包：

import std.collection.*

我们可以使用 HashMap 类型来构造元素为键值对的 Collection。

HashMap 是一种哈希表，提供对其包含的元素的快速访问。表中的每个元素都使用其键作为标识，我们可以使用键来访问相应的值。

仓颉使用 HashMap<K, V> 表示 HashMap 类型，K 表示 HashMap 的键类型，K 必须是实现了 Hashable 和 Equatable<K> 接口的类型，例如数值或 String。V 表示 HashMap 的值类型，V 可以是任意类型。

var a: HashMap<Int64, Int64> = ... // HashMap whose key type is Int64 and value type is Int64
var b: HashMap<String, Int64> = ... // HashMap whose key type is String and value type is Int64

元素类型不相同的 HashMap 是不相同的类型，所以它们之间不可以互相赋值。

因此以下例子是不合法的。

b = a // Type mismatch

仓颉中可以使用构造函数的方式构造一个指定的 HashMap。

let a = HashMap<String, Int64>() // Created an empty HashMap whose key type is String and value type is Int64
let b = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)]) // whose key type is String and value type is Int64, containing elements ("a", 0), ("b", 1), ("c", 2)
let c = HashMap<String, Int64>(b) // Use another Collection to initialize a HashMap
let d = HashMap<String, Int64>(10) // Created a HashMap whose key type is String and value type is Int64 and capacity is 10
let e = HashMap<Int64, Int64>(10, {x: Int64 => (x, x * x)}) // Created a HashMap whose key and value type is Int64 and size is 10. All elements are initialized by specified rule function

访问 HashMap 成员

当我们需要对 HashMap 的所有元素进行访问时，可以使用 for-in 循环遍历 HashMap 的所有元素。

需要注意的是，HashMap 并不保证按插入元素的顺序排列，因此遍历的顺序和插入的顺序可能不同。

import std.collection.*

main() {
    let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
    for ((k, v) in map) {
        println("The key is ${k}, the value is ${v}")
    }
}

编译并执行上面的代码，有可能会输出：

The key is a, the value is 0
The key is b, the value is 1
The key is c, the value is 2

当我们需要知道某个 HashMap 包含的元素个数时，可以使用 size 属性获得对应信息。

import std.collection.*

main() {
    let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
    if (map.size == 0) {
        println("This is an empty hashmap")
    } else {
        println("The size of hashmap is ${map.size}")
    }
}

编译并执行上面的代码，会输出：

The size of hashmap is 3

当我们想判断某个键是否被包含 HashMap 中时，可以使用 contains 函数。如果该键存在会返回 true，否则返回 false。

let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
let a = map.contains("a") // a == true
let b = map.contains("d") // b == false

当我们想访问指定键对应的元素时，可以使用下标语法访问（下标的类型必须是键类型）。使用不存在的键作为索引会触发运行时异常。

let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
let a = map["a"] // a == 0
let b = map["b"] // b == 1
let c = map["d"] // Runtime exceptions

修改 HashMap

HashMap 是一种可变的引用类型，HashMap 类型提供了修改元素、添加元素、删除元素的功能。

HashMap 的可变性是一个非常有用的特征，我们可以让同一个 HashMap 实例的所有引用都共享同样的元素，并且对它们统一进行修改。

我们可以使用下标语法对某个键对应的值进行修改。

let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
map["a"] = 3

HashMap 是引用类型，HashMap 在作为表达式使用时不会拷贝副本，同一个 HashMap 实例的所有引用都会共享同样的数据。

因此对 HashMap 元素的修改会影响到该实例的所有引用。

let map1 = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
let map2 = map1
map2["a"] = 3
// map1 contains the elements ("a", 3), ("b", 1), ("c", 2)
// map2 contains the elements ("a", 3), ("b", 1), ("c", 2)

如果需要将单个键值对添加到 HashMap 的末尾，请使用 put 函数。如果希望同时添加多个键值对，可以使用 putAll 函数。当键不存在时，put 函数会执行添加的操作，当键存在时，put 函数会将新的值覆盖旧的值。

let map = HashMap<String, Int64>()
map.put("a", 0) // map contains the element ("a", 0)
map.put("b", 1) // map contains the elements ("a", 0), ("b", 1)
let map2 = HashMap<String, Int64>([("c", 2), ("d", 3)])
map.putAll(map2) // map contains the elements ("a", 0), ("b", 1), ("c", 2), ("d", 3)

除了使用 put 函数以外，我们也可以使用赋值的方式直接将新的键值对添加到 HashMap。

let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2)])
map["d"] = 3 // map contains the elements ("a", 0), ("b", 1), ("c", 2), ("d", 3)

从 HashMap 中删除元素，可以使用 remove 函数，需要指定删除的键。

let map = HashMap<String, Int64>([("a", 0), ("b", 1), ("c", 2), ("d", 3)])
map.remove("d") // map contains the elements ("a", 0), ("b", 1), ("c", 2)

Iterable 和 Collections

前面我们已经了解过 Range、Array、ArrayList，它们都可以使用 for-in 进行遍历操作，那么对一个用户自定义类型，能不能实现类似的遍历操作呢？答案是可以的。

Range、Array、ArrayList 其实都是通过 Iterable 来支持 for-in 语法的。

Iterable 是如下形式（只展示了核心代码）的一个内置 interface。

interface Iterable<T> {
    func iterator(): Iterator<T>
    ...
}

iterator 函数要求返回的 Iterator 类型是如下形式（只展示了核心代码）的另一个内置 interface。

interface Iterator<T> <: Iterable<T> {
    mut func next(): Option<T>
    ...
}

我们可以使用 for-in 语法来遍历任何一个实现了 Iterable 接口类型的实例。

假设有这样一个 for-in 代码。

let list = [1, 2, 3]
for (i in list) {
    println(i)
}

那么它等价于如下形式的 while 代码。

let list = [1, 2, 3]
var it = list.iterator()
while (true) {
    match (it.next()) {
        case Some(i) => println(i)
        case None => break
    }
}

另外一种常见的遍历 Iterable 类型的方法是使用 while-let，比如上面 while 代码的另一种等价写法是：

let list = [1, 2, 3]
var it = list.iterator()
while (let Some(i) <- it.next()) {
    println(i)
}

Array、ArrayList、HashSet、HashMap 类型都实现了 Iterable，因此我们都可以将其用在 for-in 或者 while-let 中。

包的概述

随着项目规模的不断扩大，仅在一个超大文件中管理源代码会变得十分困难。这时可以将源代码根据功能进行分组，并将不同功能的代码分开管理，每组独立管理的代码会生成一个输出文件。在使用时，通过导入对应的输出文件使用相应的功能，或者通过不同功能的交互与组合实现更加复杂的特性，使得项目管理更加高效。

在仓颉编程语言中，包是编译的最小单元，每个包可以单独输出 AST 文件、静态库文件、动态库文件等产物。每个包有自己的名字空间，在同一个包内不允许有同名的顶层定义或声明（函数重载除外）。一个包中可以包含多个源文件。

模块是若干包的集合，是第三方开发者发布的最小单元。一个模块的程序入口只能在其根目录下，它的顶层最多只能有一个作为程序入口的 main ，该 main 没有参数或参数类型为 Array<String>，返回类型为整数类型或 Unit 类型。

包的声明

在仓颉编程语言中，包声明以关键字 package 开头，后接 root 包至当前包由 . 分隔路径上所有包的包名。包名必须是合法的普通标识符（不含原始标识符）。例如：

package pkg1      // root 包 pkg1
package pkg1.sub1 // root 包 pkg1 的子包 sub1

包声明必须在源文件的非空非注释的首行，且同一个包中的不同源文件的包声明必须保持一致。

// file 1
// Comments are accepted
package test
// declarations...

// file 2
let a = 1 // Error, package declaration must appear first in a file
package test
// declarations...

仓颉的包名需反映当前源文件相对于项目源码根目录 src 的路径，并将其中的路径分隔符替换为小数点。例如包的源代码位于 src/directory_0/directory_1 下，root 包名为 pkg 则其源代码中的包声明应为 package pkg.directory_0.directory_1。

需要注意的是：

• 包所在的文件夹名必须与包名一致。
• 源码根目录默认名为 src。
• 源码根目录下的包可以没有包声明，此时编译器将默认为其指定包名 default。

假设源代码目录结构如下：

// The directory structure is as follows:
src
`-- directory_0
    |-- directory_1
    |    |-- a.cj
    |    `-- b.cj
    `-- c.cj
`-- main.cj

则 a.cj、b.cj、c.cj、main.cj 中的包声明可以为:

// a.cj
// in file a.cj, the declared package name must correspond to relative path directory_0/directory_1.

package default.directory_0.directory_1

// b.cj
// in file b.cj, the declared package name must correspond to relative path directory_0/directory_1.

package default.directory_0.directory_1

// c.cj
// in file c.cj, the declared package name must correspond to relative path directory_0.

package default.directory_0

// main.cj
// file main.cj is in the module root directory and may omit package declaration.

main() {
    return 0
}

另外，包声明不能引起命名冲突：子包不能和当前包的顶层声明同名。

以下是一些错误示例：

// a.cj
package a
public class B { // Error, 'B' is conflicted with sub-package 'a.B'
    public static func f() {}
}

// b.cj
package a.B
public func f {}

// main.cj
import a.B // ambiguous use of 'a.B'

main() {
    a.B.f()
    return 0
}

顶层声明的可见性

仓颉中，可以使用访问修饰符来控制对类型、变量、函数等顶层声明的可见性。仓颉有 4 种访问修饰符：private、internal、protected、public，在修饰顶层元素时不同访问修饰符的语义如下。

• private 表示仅当前文件内可见。不同的文件无法访问这类成员。
• internal 表示仅当前包及子包（包括子包的子包）内可见。同一个包内可以不导入就访问这类成员，当前包的子包（包括子包的子包）内可以通过导入来访问这类成员。
• protected 表示仅当前模块内可见。同一个包的文件可以不导入就访问这类成员，不同包但是在同一个模块内的其它包可以通过导入访问这些成员，不同模块的包无法访问这些成员。
• public 表示模块内外均可见。同一个包的文件可以不导入就访问这类成员，其它包可以通过导入访问这些成员。

不同顶层声明支持的访问修饰符和默认修饰符（默认修饰符是指在省略情况下的修饰符语义，这些默认修饰符也允许显式写出）规定如下：

• pacakge 支持使用 internal、protected、public，默认修饰符为 public。
• import 支持使用全部访问修饰符，默认修饰符为 private。
• 其他顶层声明支持使用全部访问修饰符，默认修饰符为 internal。

package a

private func f1() { 1 }   // f1 仅在当前文件内可见
func f2() { 2 }           // f2 仅当前包及子包内可见
protected func f3() { 3 } // f3 仅当前模块内可见
public func f4() { 4 }    // f4 当前模块内外均可见

仓颉的访问级别排序为 public > protected > internal > private。一个声明的访问修饰符不得高于该声明中用到的类型的访问修饰符的级别，参考如下示例：

• 函数声明中的参数与返回值

  // a.cj
  package a
  class C {}
  public func f1(a1: C) // Error, public declaration f1 cannot use internal type C.
  {
      return 0
  }
  public func f2(a1: Int8): C // Error, public declaration f2 cannot use internal type C.
  {
      return C()
  }
  public func f3 (a1: Int8) // Error, public declaration f3 cannot use internal type C.
  {
      return C()
  }
  

• 变量声明

  // a.cj
  package a
  class C {}
  public let v1: C = C() // Error, public declaration v1 cannot use internal type C.
  public let v2 = C() // Error, public declaration v2 cannot use internal type C.
  

• 类声明中继承的类

  // a.cj
  package a
  open class C1 {}
  public class C2 <: C1 {} // Error, public declaration C2 cannot use internal type C1.
  

• 类型实现的接口

  // a.cj
  package a
  interface I {}
  public enum E <: I { A } // Error, public declaration uses internal types.
  

• 泛型类型的类型实参

  // a.cj
  package a
  public class C1<T> {}
  class C2 {}
  public let v1 = C1<C2>() // Error, public declaration v1 cannot use internal type C2.
  

• where 约束中的类型上界

  // a.cj
  package a
  interface I {}
  public class B<T> where T <: I {}  // Error, public declaration B cannot use internal type I.
  

值得注意的是：

• public 修饰的声明在其初始化表达式或者函数体里面可以使用本包可见的任意类型，包括 public 修饰的类型和没有 public 修饰的类型。

  // a.cj
  package a
  class C1 {}
  func f1(a1: C1)
  {
    return 0
  }
  public func f2(a1: Int8) // Ok.
  {
    var v1 = C1()
    return 0
  }
  public let v1 = f1(C1()) // Ok.
  public class C2 // Ok.
  {
    var v2 = C1()
  }
  

• public 修饰的顶层声明能使用匿名函数，或者任意顶层函数，包括 public 修饰的类型和没有 public 修饰的顶层函数。

  public var t1: () -> Unit = { => } // Ok.
  func f1(): Unit {}
  public let t2 = f1 // Ok.
  
  public func f2() // Ok.
  {
    return f1
  }
  

• 内置类型诸如 Rune、Int64 等也都默认是 public 的。

  var num = 5
  public var t3 = num // Ok.
  

包的导入

使用 import 语句导入其它包中的声明或定义

在仓颉编程语言中，可以通过 import fullPackageName.itemName 的语法导入其他包中的一个顶层声明或定义，fullPackageName 为完整路径包名，itemName 为声明的名字。导入语句在源文件中的位置必须在包声明之后，其他声明或定义之前。例如：

package a
import std.math.*
import package1.foo
import {package1.foo, package2.bar}

如果要导入的多个 itemName 同属于一个 fullPackageName，可以使用 import fullPackageName.{itemName[, itemName]*} 语法，例如：

import package1.{foo, bar, fuzz}

这等价于：

import package1.foo
import package1.bar
import package1.fuzz

除了通过 import fullPackagename.itemName 语法导入一个特定的顶层声明或定义外，还可以使用 import packageName.* 语法将 packageName 包中所有可见的顶层声明或定义全部导入。例如：

import package1.*
import {package1.*, package2.*}

需要注意：

• import 可以被 private、internal、protected、public 访问修饰符修饰。不写访问修饰符的 import 等价于 private import。
• 导入的成员的作用域级别低于当前包声明的成员。
• 当已导出的包的模块名或者包名被篡改，使其与导出时指定的模块名或包名不一致，在导入时会报错。
• 只允许导入当前文件可见的顶层声明或定义，导入不可见的声明或定义将会在导入处报错。
• 禁止通过 import 导入当前源文件所在包的声明或定义。
• 禁止包间的循环依赖导入，如果包之间存在循环依赖，编译器会报错。

示例如下：

// pkga/a.cj
package pkga    // Error, packages pkga pkgb are in circular dependencies.
import pkgb.*

class C {}
public struct R {}

// pkgb/b.cj
package pkgb

import pkga.*

// pkgc/c1.cj
package pkgc

import pkga.C // Error, 'C' is not accessible in package 'pkga'.
import pkga.R // OK, R is an external top-level declaration of package pkga.
import pkgc.f1 // Error, package 'pkgc' should not import itself.

public func f1() {}

// pkgc/c2.cj
package pkgc

func f2() {
    /* OK, the imported declaration is visible to all source files of the same package
     * and accessing import declaration by its name is supported.
     */
    R()

    // OK, accessing imported declaration by fully qualified name is supported.
    pkga.R()

    // OK, the declaration of current package can be accessed directly.
    f1()

    // OK, accessing declaration of current package by fully qualified name is supported.
    pkgc.f1()
}

在仓颉编程语言中，导入的声明或定义如果和当前包中的顶层声明或定义重名且不构成函数重载，则导入的声明和定义会被遮盖；导入的声明或定义如果和当前包中的顶层声明或定义重名且构成函数重载，函数调用时将会根据函数重载的规则进行函数决议。

// pkga/a.cj
package pkga

public struct R {}            // R1
public func f(a: Int32) {}    // f1
public func f(a: Bool) {} // f2

// pkgb/b.cj
package pkgb
import pkga.*

func f(a: Int32) {}         // f3
struct R {}                 // R2

func bar() {
    R()     // OK, R2 shadows R1.
    f(1)    // OK, invoke f3 in current package.
    f(true) // OK, invoke f2 in the imported package
}

隐式导入 core 包

诸如 String、Range 等类型能直接使用，并不是因为这些类型是内置类型，而是因为编译器会自动为源码隐式的导入 core 包中所有的 public 修饰的声明。

使用 import as 对导入的名字重命名

不同包的名字空间是分隔的，因此在不同的包之间可能存在同名的顶层声明。在导入不同包的同名顶层声明时，我们支持使用 import packageName.name as newName 的方式进行重命名来避免冲突。没有名字冲突的情况下仍然可以通过 import as 来重命名导入的内容。import as 具有如下规则：

• 使用 import as 对导入的声明进行重命名后，当前包只能使用重命名后的新名字，原名无法使用。

• 如果重命名后的名字与当前包顶层作用域的其它名字存在冲突，且这些名字对应的声明均为函数类型，则参与函数重载，否则报重定义的错误。

• 支持 import pkg as newPkgName 的形式对包名进行重命名，以解决不同模块中同名包的命名冲突问题。

  // a.cj
  package p1
  public func f1() {}
  
  // d.cj
  package p2
  public func f3() {}
  
  // b.cj
  package p1
  public func f2() {}
  
  // c.cj
  package pkgc
  public func f1() {}
  
  // main.cj
  import p1 as A
  import p1 as B
  import p2.f3 as f  // OK
  import pkgc.f1 as a
  import pkgc.f1 as b // OK
  
  func f(a: Int32) {}
  
  main() {
      A.f1()  // OK, package name conflict is resolved by renaming package name.
      B.f2()  // OK, package name conflict is resolved by renaming package name.
      p1.f1() // Error, the original package name cannot be used.
      a()     // Ok.
      b()     // Ok.
      pkgc.f1()    // Error, the original name cannot be used.
  }
  

• 如果没有对导入的存在冲突的名字进行重命名，在 import 语句处不报错；在使用处，会因为无法导入唯一的名字而报错。这种情况可以通过 import as 定义别名或者 import fullPackageName 导入包作为命名空间。

  // a.cj
  package p1
  public class C {}
  
  // b.cj
  package p2
  public class C {}
  
  // main1.cj
  package pkga
  import p1.C
  import p2.C
  
  main() {
      let _ = C() // Error
  }
  
  // main2.cj
  package pkgb
  import p1.C as C1
  import p2.C as C2
  
  main() {
      let _ = C1() // Ok
      let _ = C2() // Ok
  }
  
  // main3.cj
  package pkgc
  import p1
  import p2
  
  main() {
      let _ = p1.C() // Ok
      let _ = p2.C() // Ok
  }
  

重导出一个导入的名字

在功能繁多的大型项目的开发过程中，这样的场景是非常常见的：包 p2 大量地使用从包 p1 中导入的声明，当包 p3 导入包 p2 并使用其中的功能时，p1 中的声明同样需要对包 p3 可见。如果要求包 p3 自行导入 p2 中使用到的 p1 中的声明，这个过程将过于繁琐。因此希望能够在 p2 被导入时一并导入 p2 使用到的 p1 中的声明。

在仓颉编程语言中，import 可以被 private、internal、protected、public 访问修饰符修饰。其中，被 public、protected 或者 internal 修饰的 import 可以把导入的成员重导出（如果这些导入的成员没有因为名称冲突或者被遮盖导致在本包中不可用）。其它包可以根据可见性直接导入并使用本包中用重导出的内容，无需从原包中导入这些内容。

• private import 表示导入的内容仅当前文件内可访问，private 是 import 的默认修饰符，不写访问修饰符的 import 等价于 private import。
• internal import 表示导入的内容在当前包及其子包（包括子包的子包）均可访问。非当前包访问需要显式 import。
• protected import 表示导入的内容在当前 module 内都可访问。非当前包访问需要显式 import。
• public import 表示导入的内容外部都可访问。非当前包访问需要显式 import。

在下面的例子中，b 是 a 的子包，在 a 中通过 public import 重导出了 b 中定义的函数 f。

package a

public let x = 0
public import a.b.f

internal package a.b

public func f() { 0 }

import a.f  // Ok
let _ = f() // Ok

需要注意的是，包不可以被重导出：如果被 import 导入的是包，那么该 import 不允许被 public、protected 或者 internal 修饰。

public import a.b // Error, cannot re-export package

程序入口

仓颉程序入口为 main，源文件根目录下的包的顶层最多只能有一个 main。

如果模块采用生成可执行文件的编译方式，编译器只在源文件根目录下的顶层查找 main。如果没有找到，编译器将会报错；如果找到 main，编译器会进一步对其参数和返回值类型进行检查。需要注意的是，main 不可被访问修饰符修饰，当一个包被导入时，包中定义的 main 不会被导入。

作为程序入口的 main 可以没有参数或参数类型为 Array<String>，返回值类型为 Unit 或整数类型。

没有参数的 main：

// main.cj
main(): Int64 { // Ok.
    return 0
}

参数类型为 Array<String> 的 main：

// main.cj
main(args: Array<String>): Unit { // Ok.
    for (arg in args) {
        println(arg)
    }
}

使用 cjc main.cj 编译完成后，通过命令行执行：./main Hello, World，将会得到如下输出：

Hello,
World

以下是一些错误示例：

// main.cj
main(): String { // Error, return type of 'main' is not 'Integer' or 'Unit'.
    return ""
}

// main.cj
main(args: Array<Int8>): Int64 { // Error, 'main' cannot be defined with parameter whose type is not Array<String>.
    return 0
}

// main.cj
// Error, multiple 'main's are found in source files.
main(args: Array<String>): Int32 {
    return 0
}

main(): Int8 {
    return 0
}

定义异常

异常是一类特殊的可以被程序员捕获并处理的错误，是程序执行时出现的一系列不正常行为的统称，例如，数组越界、除零错误、计算溢出、非法输入等。为了保证系统的正确性和健壮性，很多软件系统中都包含大量的代码用于错误检测和错误处理。

异常不属于程序的正常功能，一旦发生异常，要求程序必须立即处理，即将程序的控制权从正常功能的执行处转移至处理异常的部分。仓颉编程语言提供异常处理机制用于处理程序运行时可能出现的各种异常情况。

在仓颉中，异常类有 Error 和 Exception ：

• Error 类描述仓颉语言运行时，系统内部错误和资源耗尽错误，应用程序不应该抛出这种类型错误，如果出现内部错误，只能通知给用户，尽量安全终止程序。
• Exception 类描述的是程序运行时的逻辑错误或者 IO 错误导致的异常，例如数组越界或者试图打开一个不存在的文件等，这类异常需要在程序中捕获处理。

用户不可以通过继承仓颉语言内置的 Error 或其子类类来自定义异常，但是可以继承内置的 Exception 或其子类来自定义异常，例如

open class FatherException <: Exception {
    public open func printException() {
        print("I am a FatherException")
    }
}

class ChildException <: FatherException {
    public override func printException() {
        print("I am a ChildException")
    }
}

下面列表展示了 Exception 的主要函数及其说明

下面列表展示了 Error 的主要函数及其说明

throw 和处理异常

上文介绍了如何自定义异常，接下来我们学习如何抛出和处理异常。

• 由于异常是 class 类型，只需要按 class 对象的构建方式去创建异常即可。如表达式 FatherException() 即创建了一个类型为 FatherException 的异常。
• 仓颉语言提供 throw 关键字，用于抛出异常。用 throw 来抛出异常时，throw 之后的表达式必须是 Exception 的子类型（同为异常的 Error 不可以手动 throw ），如 throw ArithmeticException("I am an Exception!") （被执行到时）会抛出一个算术运算异常。
• throw 关键字抛出的异常需要被捕获处理。若异常没有被捕获，则由系统调用默认的异常处理函数。

异常处理由 try 表达式完成，可分为：

• 不涉及资源自动管理的普通 try 表达式；
• 会进行资源自动管理 try-with-resources 表达式。

普通 try 表达式

普通 try 表达式包括三个部分：try 块，catch 块和 finally 块。

• try 块，以关键字 try 开始，后面紧跟一个由表达式与声明组成的块（用一对花括号括起来，定义了新的局部作用域，可以包含任意表达式和声明，后简称“块”），try 后面的块内可以抛出异常，并被紧随的 catch 块所捕获并处理（如果不存在 catch 块或未被捕获，则在执行完 finally 块后，该异常继续被抛出）。

• catch 块，一个普通 try 表达式可以包含零个或多个 catch 块（当没有 catch 块时必须有 finally 块）。每个 catch 块以关键字 catch 开头，后跟一条 catchPattern 和一个块，catchPattern 通过模式匹配的方式匹配待捕获的异常。一旦匹配成功，则交由其后跟随的块进行处理，并且忽略它后面的其他 catch 块。当某个 catch 块可捕获的异常类型均可被定义在它前面的某个 catch 块所捕获时，会在此 catch 块处报“catch 块不可达”的 warning。

• finally 块，以关键字 finally 开始，后面紧跟一个块。原则上，finally 块中主要实现一些“善后”的工作，如释放资源等，且要尽量避免在 finally 块中再抛异常。并且无论异常是否发生（即无论 try 块中是否抛出异常），finally 块内的内容都会被执行（若异常未被处理，执行完 finally 块后，继续向外抛出异常）。一个 try 表达式在包含 catch 块时可以不包含 finally 块，否则必须包含 finally 块。

try 后面紧跟的块以及每个 catch 块的的作用域互相独立。

下面是一个只有 try 块和 catch 块的简单示例：

main() {
    try {
        throw NegativeArraySizeException("I am an Exception!")
    } catch (e: NegativeArraySizeException) {
        println(e)
        println("NegativeArraySizeException is caught!")
    }
    println("This will also be printed!")
}

执行结果为

NegativeArraySizeException: I am an Exception!
NegativeArraySizeException is caught!
This will also be printed!

catchPattern 中引入的变量作用域级别与 catch 后面的块中变量作用域级别相同，在 catch 块中再次引入相同名字会触发重定义错误。例如：

main() {
    try {
        throw NegativeArraySizeException("I am an Exception!")
    } catch (e: NegativeArraySizeException) {
        println(e)
        let e = 0 // Error, redefinition
        println(e)
        println("NegativeArraySizeException is caught!")
    }
    println("This will also be printed!")
}

下面是带有 finally 块的 try 表达式的简单示例：

main() {
    try {
        throw NegativeArraySizeException("NegativeArraySizeException")
    } catch (e: NegativeArraySizeException) {
        println("Exception info: ${e}.")
    } finally {
        println("The finally block is executed.")
    }
}

执行结果为

Exception info: NegativeArraySizeException: NegativeArraySizeException.
The finally block is executed.

try 表达式可以出现在任何允许使用表达式的地方。try 表达式的类型的确定方式，与 if、match 表达式等多分支语法结构的类型的确定方式相似，为 finally 分支除外的所有分支的类型的最小公共父类型。例如下面代码中的 try 表达式和变量 x 的类型均为 E 和 D 的最小公共父类型 D；finally 分支中的 C() 并不参与公共父类型的计算（若参与，则最小公共父类型会变为 C）。

另外，当 try 表达式的值没有被使用时，其类型为 Unit，不要求各分支的类型有最小公共父类型。

open class C { }
open class D <: C { }
class E <: D { }
main () {
    let x = try {
        E()
    } catch (e: Exception) {
        D()
    } finally {
        C()
    }
    0
}

Try-with-resources 表达式

Try-with-resources 表达式主要是为了自动释放非内存资源。不同于普通 try 表达式，try-with-resources 表达式中的 catch 块和 finally 块均是可选的，并且 try 关键字其后的块之间可以插入一个或者多个 ResourceSpecification 用来申请一系列的资源（ResourceSpecification 并不会影响整个 try 表达式的类型）。这里所讲的资源对应到语言层面即指对象，因此 ResourceSpecification 其实就是实例化一系列的对象（多个实例化之间使用“,”分隔）。使用 try-with-resources 表达式的例子如下所示：

class R <: Resource {
    public func isClosed(): Bool {
        true
    }
    public func close(): Unit {
        print("R is closed")
    }
}

main() {
    try (r = R()) {
        println("Get the resource")
    }
}

程序输出结果为：

Get the resource

try 关键字和 {} 之间引入的名字，其作用域与 {} 中引入的变量作用域级别相同，在 {} 中再次引入相同名字会触发重定义错误。

class R <: Resource {
    public func isClosed(): Bool {
        true
    }
    public func close(): Unit {
        print("R is closed")
    }
}

main() {
    try (r = R()) {
        println("Get the resource")
        let r = 0 // Error, redefinition
        println(r)
    }
}

Try-with-resources 表达式中的 ResourceSpecification 的类型必须实现 Resource 接口，并且尽量保证其中的 isClosed 函数不要再抛异常：

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

需要说明的是，try-with-resources 表达式中一般没有必要再包含 catch 块和 finally 块，也不建议用户再手动释放资源。因为 try 块执行的过程中无论是否发生异常，所有申请的资源都会被自动释放，并且执行过程中产生的异常均会被向外抛出。但是，如果需要显式地捕获 try 块或资源申请和释放过程中可能抛出的异常并处理，仍可在 try-with-resources 表达式中包含 catch 块和 finally 块：

class R <: Resource {
    public func isClosed(): Bool {
        true
    }
    public func close(): Unit {
        print("R is closed")
    }
}

main() {
    try (r = R()) {
        println("Get the resource")
    } catch (e: Exception) {
        println("Exception happened when executing the try-with-resources expression")
    } finally {
        println("End of the try-with-resources expression")
    }
}

程序输出结果如下：

Get the resource
End of the try-with-resources expression

Try-with-resources 表达式的类型是 Unit。

CatchPattern 进阶介绍

大多数时候，我们只想捕获某一类型和其子类型的异常，这时候我们使用 CatchPattern 的类型模式来处理；但有时也需要所有异常做统一处理（如此处不该出现异常，出现了就统一报错），这时可以使用 CatchPattern 的通配符模式来处理。

类型模式在语法上有两种格式：

• Identifier: ExceptionClass。此格式可以捕获类型为 ExceptionClass 及其子类的异常，并将捕获到的异常实例转换成 ExceptionClass，然后与 Identifier 定义的变量进行绑定，接着就可以在 catch 块中通过 Identifier 定义的变量访问捕获到的异常实例。
• Identifier: ExceptionClass_1 | ExceptionClass_2 | ... | ExceptionClass_n。此格式可以通过连接符 | 将多个异常类进行拼接，连接符 | 表示“或”的关系：可以捕获类型为 ExceptionClass_1 及其子类的异常，或者捕获类型为 ExceptionClass_2 及其子类的异常，依次类推，或捕获类型为 ExceptionClass_n 及其子类的异常（假设 n 大于 1）。当待捕获异常的类型属于上述“或”关系中的任一类型或其子类型时，此异常将被捕获。但是由于无法静态地确定被捕获异常的类型，所以被捕获异常的类型会被转换成由 | 连接的所有类型的最小公共父类，并将异常实例与 Identifier 定义的变量进行绑定。因此在此类模式下，catch 块内只能通过 Identifier 定义的变量访问 ExceptionClass_i（1 <= i <= n） 的最小公共父类中的成员变量和成员函数。当然，也可以使用通配符代替类型模式中的 Identifier，差别仅在于通配符不会进行绑定操作。

示例如下：

main(): Int64 {
    try {
        throw IllegalArgumentException("This is an Exception!")
    } catch (e: OverflowException) {
        println(e.message)
        println("OverflowException is caught!")
    } catch (e: IllegalArgumentException | NegativeArraySizeException) {
        println(e.message)
        println("IllegalArgumentException or NegativeArraySizeException is caught!")
    } finally {
        println("finally is executed!")
    }
    return 0
}

执行结果：

This is an Exception!
IllegalArgumentException or NegativeArraySizeException is caught!
finally is executed!

关于“被捕获异常的类型是由 | 连接的所有类型的最小公共父类”的示例：

open class Father <: Exception {
    var father: Int32 = 0
}

class ChildOne <: Father {
    var childOne: Int32 = 1
}

class ChildTwo <: Father {
    var childTwo: Int32 = 2
}

main() {
    try {
        throw ChildOne()
    } catch (e: ChildTwo | ChildOne) {
        println("ChildTwo or ChildOne?")
    }
}

执行结果：

ChildTwo or ChildOne?

通配符模式的语法是 _，它可以捕获同级 try 块内抛出的任意类型的异常，等价于类型模式中的 e: Exception，即捕获 Exception 子类所定义的异常。示例：

// Catch with wildcardPattern.
try {
    throw OverflowException()
} catch (_) {
    println("catch an exception!")
}

常见运行时异常

在仓颉语言中内置了最常见的异常类，开发人员可以直接使用。

使用 Option

在Option 类型中我们介绍了 Option 类型的定义，因为 Option 类型可以同时表示有值和无值两种状态，而无值在某些情况下也可以理解为一种错误，所以 Option 类型也可以用作错误处理。

例如，在下例中，如果函数 getOrThrow 的参数值等于 Some(v) 则将 v 的值返回，如果参数值等于 None 则抛出异常。

func getOrThrow(a: ?Int64) {
    match (a) {
        case Some(v) => v
        case None => throw NoneValueException()
    }
}

因为 Option 是一种非常常用的类型，所以仓颉为其提供了多种解构方式，以方便 Option 类型的使用，具体包括：模式匹配、getOrThrow 函数、coalescing 操作符（??），以及问号操作符（?）。下面将对这些方式逐一介绍。

• 模式匹配：因为 Option 类型是一种 enum 类型，所以可以使用上文提到的 enum 的模式匹配来实现对 Option 值的解构。例如，下例中函数 getString 接受一个 ?Int64 类型的参数，当参数是 Some 值时，返回其中数值的字符串表示，当参数是 None 值时，返回字符串 "none"。

  func getString(p: ?Int64): String{
      match (p) {
          case Some(x) => "${x}"
          case None => "none"
      }
  }
  main() {
      let a = Some(1)
      let b: ?Int64 = None
      let r1 = getString(a)
      let r2 = getString(b)
      println(r1)
      println(r2)
  }
  

  上述代码的执行结果为：

  1
  none
  

• coalescing 操作符（??）：对于 ?T 类型的表达式 e1，如果希望 e1 的值等于 None 时同样返回一个 T 类型的值 e2，可以使用 ?? 操作符。对于表达式 e1 ?? e2，当 e1 的值等于 Some(v) 时返回 v 的值，否则返回 e2 的值。举例如下：

  main() {
      let a = Some(1)
      let b: ?Int64 = None
      let r1: Int64 = a ?? 0
      let r2: Int64 = b ?? 0
      println(r1)
      println(r2)
  }
  

  上述代码的执行结果为：

  1
  0
  

• 问号操作符（?）：? 需要和 . 或 () 或 [] 或 {}（特指尾随 lambda 调用的场景）一起使用，用以实现 Option 类型对 .，()，[] 和 {} 的支持。以 . 为例（()，[] 和 {}同理），对于 ?T1 类型的表达式 e，当 e 的值等于 Some(v) 时，e?.b 的值等于 Option<T2>.Some(v.b)，否则 e?.b 的值等于 Option<T2>.None，其中 T2 是 v.b 的类型。举例如下：

  struct R {
      public var a: Int64
      public init(a: Int64) {
          this.a = a
      }
  }
  
  let r = R(100)
  let x = Some(r)
  let y = Option<R>.None
  let r1 = x?.a   // r1 = Option<Int64>.Some(100)
  let r2 = y?.a   // r2 = Option<Int64>.None
  

  问号操作符（?）支持多层访问，以 a?.b.c?.d 为例（()，[] 和 {}同理）。表达式 a 的类型需要是某个 Option<T1> 且 T1 包含实例成员 b，b 的类型中包含实例成员变量 c 且 c 的类型是某个 Option<T2>，T2 包含实例成员 d；表达式 a?.b.c?.d 的类型为 Option<T3>，其中 T3 是 T2 的实例成员 d 的类型；当 a 的值等于 Some(va) 且 va.b.c 的值等于 Some(vc) 时，a?.b.c?.d 的值等于 Option<T3>.Some(vc.d)；当 a 的值等于 Some(va) 且 va.b.c 的值等于 None 时，a?.b.c?.d 的值等于 Option<T3>.None（d 不会被求值）；当 a 的值等于 None 时，a?.b.c?.d 的值等于 Option<T3>.None（b，c 和 d 都不会被求值）。

  struct A {
      let b: B = B()
  }
  
  struct B {
      let c: Option<C> = C()
      let c1: Option<C> = Option<C>.None
  }
  
  struct C {
      let d: Int64 = 100
  }
  
  let a = Some(A())
  let a1 = a?.b.c?.d // a1 = Option<Int64>.Some(100)
  let a2 = a?.b.c1?.d // a2 = Option<Int64>.None
  

• getOrThrow 函数：对于 ?T 类型的表达式 e，可以通过调用 getOrThrow 函数实现解构。当 e 的值等于 Some(v) 时，getOrThrow() 返回 v 的值，否则抛出异常。举例如下：

  main() {
      let a = Some(1)
      let b: ?Int64 = None
      let r1 = a.getOrThrow()
      println(r1)
      try {
          let r2 = b.getOrThrow()
      } catch (e: NoneValueException) {
          println("b is None")
      }
  }
  

  上述代码的执行结果为：

  1
  b is None
  

并发概述

并发编程是现代编程语言中不可或缺的特性，仓颉编程语言提供抢占式的线程模型作为并发编程机制。在谈及编程语言和线程时，线程其实可以细化为两种不同概念，语言线程和 native 线程。

• 前者是编程语言中并发模型的基本执行单位，语言线程的目的是屏蔽底层实现细节。例如，仓颉编程语言希望给开发者提供一个友好、高效、统一的并发编程界面，让开发者无需关心操作系统线程、用户态线程等差异，因此提供仓颉线程的概念。开发者在大多数情况下只需面向仓颉线程编写并发代码。
• 后者指语言实现中所使用到的线程（一般是操作系统线程），他们作为语言线程的具体实现载体。不同编程语言会以不同的方式实现语言线程。例如，一些编程语言直接通过操作系统调用来创建线程，这意味着每个语言线程对应一个 native 线程，这种实现方案一般被称之为 1:1 线程模型。此外，另有一些编程语言提供特殊的线程实现，他们允许多个语言线程在多个 native 线程上切换执行，这种也被称为 M:N 线程模型，即 M 个语言线程在 N 个 native 线程上调度执行，其中 M 和 N 不一定相等。当前，仓颉语言的实现同样采用 M:N 线程模型；因此，仓颉线程本质上是一种用户态的轻量级线程，支持抢占且相比操作系统线程更轻量化。

仓颉线程本质上是用户态的轻量级线程，每个仓颉线程都受到底层 native 线程的调度执行，并且多个仓颉线程可以由一个 native 线程执行。每个 native 线程会不断地选择一个就绪的仓颉线程完成执行，如果仓颉线程在执行过程中发生阻塞（例如等待互斥锁的释放），那么 native 线程会将当前的仓颉线程挂起，并继续选择下一个就绪的仓颉线程。发生阻塞的仓颉线程在重新就绪后会继续被 native 线程调度执行。

在大多数情况下，开发者只需要面向仓颉线程进行并发编程而不需要考虑这些细节。但在进行跨语言编程时，开发者需要谨慎调用可能发生阻塞的 foreign 函数，例如 IO 相关的操作系统调用等。例如，下列示例代码中的新线程会调用 foreign 函数 socket_read。在程序运行过程中，某一 native 线程将调度并执行该仓颉线程，在进入到 foreign 函数中后，系统调用会直接阻塞当前 native 线程直到函数执行完成。native 线程在阻塞期间将无法调度其他仓颉线程来执行，这会降低程序执行的吞吐量。

foreign socket_read(sock: Int64): CPointer<Int8>

let fut = spawn {
    let sock: Int64 = ...
    let ptr = socket_read(sock)
}

注意：

本文档在没有歧义的情况下将直接以线程简化对仓颉线程的指代。

创建线程

当开发者希望并发执行某一段代码时，只需创建一个仓颉线程即可。要创建一个新的仓颉线程，可以使用关键字 spawn 并传递一个无形参的 lambda 表达式，该 lambda 表达式即为在新线程中执行的代码。

下方示例代码中，主线程和新线程均会尝试打印一些文本：

import std.sync.*
import std.time.*

main(): Int64 {
    spawn { =>
        println("New thread before sleeping")
        sleep(100 * Duration.millisecond) // sleep for 100ms.
        println("New thread after sleeping")
    }

    println("Main thread")

    return 0
}

在上面的例子中，新线程会在主线程结束时一起停止，无论这个新线程是否已完成运行。上方示例的输出每次可能略有不同，有可能会输出类似如下的内容：

New thread before sleeping
Main thread

sleep() 函数会让当前线程睡眠指定的时长，之后再恢复执行，其时间由指定的 Duration 类型决定，详细介绍请参考线程睡眠指定时长章节。

访问线程

使用 Future<T> 等待线程结束并获取返回值

在上面的例子中，新创建的线程会由于主线程结束而提前结束，在缺乏顺序保证的情况下，甚至可能会出现新创建的线程还来不及得到执行就退出了。我们可以通过 spawn 表达式的返回值，来等待线程执行结束。

spawn 表达式的返回类型是 Future<T>，其中 T 是类型变元，其类型与 lambda 表达式的返回类型一致。当我们调用 Future<T> 的 get() 成员函数时，它将等待它的线程执行完成。

Future<T> 的原型声明如下：

public class Future<T> {
    // Blocking the current thread, waiting for the result of the thread corresponding to the current Future object.
    // If an exception occurs in the corresponding thread, the method will throw the exception.
    public func get(): T

    // Blocking the current thread, waiting for the result of the thread corresponding to the current Future object.
    // If the corresponding thread has not completed execution within ns nanoseconds, the method will return a Option<T>.None.
    // If `ns` <= 0, its behavior is the same as `get()`.
    public func get(ns: Int64): Option<T>

    // Non-blocking method that immediately returns Option<T>.None if thread has not finished execution.
    // Returns the computed result otherwise.
    // If an exception occurs in the corresponding thread, the method will throw the exception.
    public func tryGet(): Option<T>
}

下方示例代码演示了如何使用 Future<T> 在 main 中等待新创建的线程执行完成：

import std.sync.*
import std.time.*

main(): Int64 {
    let fut: Future<Unit> = spawn { =>
        println("New thread before sleeping")
        sleep(100 * Duration.millisecond) // sleep for 100ms.
        println("New thread after sleeping")
    }

    println("Main thread")

    fut.get() // wait for the thread to finish.
    return 0
}

调用 Future<T> 实例的 get() 会阻塞当前运行的线程，直到 Future<T> 实例所代表的线程运行结束。因此，上方示例有可能会输出类似如下内容：

New thread before sleeping
Main thread
New thread after sleeping

主线程在完成打印后会因为调用 get() 而等待新创建的线程执行结束。但主线程和新线程的打印顺序具有不确定性。

但是，如果我们将 fut.get() 移动到主线程的打印之前，会出现什么结果呢？就像下方这样：

import std.sync.*
import std.time.*

main(): Int64 {
    let fut: Future<Unit> = spawn { =>
        println("New thread before sleeping")
        sleep(100 * Duration.millisecond) // sleep for 100ms.
        println("New thread after sleeping")
    }

    fut.get() // wait for the thread to finish.

    println("Main thread")
    return 0
}

主线程将等待新创建的线程执行完成，然后再执行打印，因此程序的输出将变得确定，如下所示：

New thread before sleeping
New thread after sleeping
Main thread

可见，get() 的调用位置会影响线程是否能同时运行。

Future<T> 除了可以用于阻塞等待线程执行结束以外，还可以获取线程执行的结果。现在，我们来看一下它提供的具体成员函数：

• get(): T：阻塞等待线程执行结束，并返回执行结果，如果该线程已经结束，则直接返回执行结果。

  示例代码如下：

  import std.sync.*
  import std.time.*
  
  main(): Int64 {
      let fut: Future<Int64> = spawn {
          sleep(Duration.second) // sleep for 1s.
          return 1
      }
  
      try {
          // wait for the thread to finish, and get the result.
          let res: Int64 = fut.get()
          println("result = ${res}")
      } catch (_) {
          println("oops")
      }
      return 0
  }
  

  输出结果如下：

  result = 1
  

• get(ns: Int64): Option<T>：阻塞等待该 Future<T> 所代表的线程执行结束，并返回执行结果，当到达超时时间 ns 时，如果该线程还没有执行结束，将会返回 Option<T>.None。如果 ns <= 0,其行为与 get() 相同。

  示例代码如下：

  import std.sync.*
  import std.time.*
  
  main(): Int64 {
      let fut = spawn {
          sleep(Duration.second) // sleep for 1s.
          return 1
      }
  
      // wait for the thread to finish, but only for 1ms.
      let res: Option<Int64> = fut.get(1000 * 1000)
      match (res) {
          case Some(val) => println("result = ${val}")
          case None => println("oops")
      }
      return 0
  }
  

  输出结果如下：

  oops
  

访问线程属性

每个 Future<T> 对象都有一个对应的仓颉线程，以 Thread 对象为表示。Thread 类主要被用于访问线程的属性信息，例如线程标识等。需要注意的是，Thread 无法直接被实例化构造对象，仅能从 Future<T> 的 thread 成员属性获取对应的 Thread 对象，或是通过 Thread 的静态成员属性 currentThread 得到当前正在执行线程对应的 Thread 对象。

Thread 类的部分方法定义如下（完整的方法描述可参考《仓颉编程语言库 API》）。

class Thread {
    ... ...
    // Get the currently running thread
    static prop currentThread: Thread

    // Get the unique identifier (represented as an integer) of the thread object
    prop id: Int64

    // Check whether the thread has any cancellation request
    prop hasPendingCancellation: Bool
}

下列示例代码在创建新线程后分别通过两种方式获取线程标识。由于主线程和新线程获取的是同一个 Thread 对象，所以他们能够打印出相同的线程标识。

main(): Unit {
    let fut = spawn {
        println("Current thread id: ${Thread.currentThread.id}")
    }
    println("New thread id: ${fut.thread.id}")
    fut.get()
}

输出结果如下：

New thread id: 1
Current thread id: 1

终止线程

可以通过 Future<T> 的 cancel() 方法向对应的线程发送终止请求，该方法不会停止线程执行。开发者需要使用 Thread 的 hasPendingCancellation 属性来检查线程是否存在终止请求。

一般而言，如果线程存在终止请求，那么开发者可以实施相应的线程终止逻辑。因此，如何终止线程都交由开发者自行处理，如果开发者忽略终止请求，那么线程继续执行直到正常结束。

示例代码如下：

import std.sync.SyncCounter

main(): Unit {
    let syncCounter = SyncCounter(1)
    let fut = spawn {
        syncCounter.waitUntilZero()
        // Check cancellation request
        if (Thread.currentThread.hasPendingCancellation) {
            println("cancelled")
            return
        }
        println("hello")
    }
    fut.cancel()    // Send cancellation request
    syncCounter.dec()
    fut.get() // Join thread
}

输出结果如下：

cancelled

同步机制

在并发编程中，如果缺少同步机制来保护多个线程共享的变量，很容易会出现数据竞争问题（data race）。

仓颉编程语言提供三种常见的同步机制来确保数据的线程安全：原子操作，互斥锁以及条件变量。

原子操作 Atomic

仓颉提供整数类型、Bool 类型和引用类型的原子操作。

其中整数类型包括： Int8、Int16、Int32、Int64、UInt8、UInt16、UInt32、UInt64。

整数类型的原子操作支持基本的读写、交换以及算术运算操作：

需要注意的是：

1. 交换操作和算术操作的返回值是修改前的值。
2. compareAndSwap 是判断当前原子变量的值是否等于 old 值，如果等于，则使用 new 值替换；否则不替换。

以 Int8 类型为例，对应的原子操作类型声明如下：

class AtomicInt8 {
    public func load(): Int8
    public func store(val: Int8): Unit
    public func swap(val: Int8): Int8
    public func compareAndSwap(old: Int8, new: Int8): Bool
    public func fetchAdd(val: Int8): Int8
    public func fetchSub(val: Int8): Int8
    public func fetchAnd(val: Int8): Int8
    public func fetchOr(val: Int8): Int8
    public func fetchXor(val: Int8): Int8
}

上述每一种原子类型的方法都有一个对应的方法可以接收内存排序参数，目前内存排序参数仅支持顺序一致性。

类似的，其他整数类型对应的原子操作类型有：

class AtomicInt16 {...}
class AtomicInt32 {...}
class AtomicInt64 {...}
class AtomicUInt8 {...}
class AtomicUInt16 {...}
class AtomicUInt32 {...}
class AtomicUInt64 {...}

下方示例演示了如何在多线程程序中，使用原子操作实现计数：

import std.sync.*
import std.time.*
import std.collection.*

let count = AtomicInt64(0)

main(): Int64 {
    let list = ArrayList<Future<Int64>>()

    // create 1000 threads.
    for (i in 0..1000) {
        let fut = spawn {
            sleep(Duration.millisecond) // sleep for 1ms.
            count.fetchAdd(1)
        }
        list.append(fut)
    }

    // Wait for all threads finished.
    for (f in list) {
        f.get()
    }

    let val = count.load()
    println("count = ${val}")
    return 0
}

输出结果应为：

count = 1000

以下是使用整数类型原子操作的一些其他正确示例：

var obj: AtomicInt32 = AtomicInt32(1)
var x = obj.load() // x: 1, the type is Int32
x = obj.swap(2) // x: 1
x = obj.load() // x: 2
var y = obj.compareAndSwap(2, 3) // y: true, the type is Bool.
y = obj.compareAndSwap(2, 3) // y: false, the value in obj is no longer 2 but 3. Therefore, the CAS operation fails.
x = obj.fetchAdd(1) // x: 3
x = obj.load() // x: 4

Bool 类型和引用类型的原子操作只提供读写和交换操作：

注意：

引用类型原子操作只对引用类型有效。

原子引用类型是 AtomicReference，以下是使用 Bool 类型、引用类型原子操作的一些正确示例：

import std.sync.*

class A {}

main() {
    var obj = AtomicBool(true)
    var x1 = obj.load() // x1: true, the type is Bool
    println(x1)
    var t1 = A()
    var obj2 = AtomicReference(t1)
    var x2 = obj2.load() // x2 and t1 are the same object
    var y1 = obj2.compareAndSwap(x2, t1) // x2 and t1 are the same object, y1: true
    println(y1)
    var t2 = A()
    var y2 = obj2.compareAndSwap(t2, A()) // x and t1 are not the same object, CAS fails, y2: false
    println(y2)
    y2 = obj2.compareAndSwap(t1, A()) // CAS successes, y2: true
    println(y2)
}

编译执行上述代码，输出结果为：

true
true
false
true

可重入互斥锁 ReentrantMutex

可重入互斥锁的作用是对临界区加以保护，使得任意时刻最多只有一个线程能够执行临界区的代码。当一个线程试图获取一个已被其他线程持有的锁时，该线程会被阻塞，直到锁被释放，该线程才会被唤醒，可重入是指线程获取该锁后可再次获得该锁。

注意：

ReentrantMutex 是内置的互斥锁，开发者需要保证不继承它。

使用可重入互斥锁时，必须牢记两条规则：

1. 在访问共享数据之前，必须尝试获取锁；
2. 处理完共享数据后，必须进行解锁，以便其他线程可以获得锁。

ReentrantMutex 提供的主要成员函数如下：

public open class ReentrantMutex {
    // Create a ReentrantMutex.
    public init()

    // Locks the mutex, blocks if the mutex is not available.
    public func lock(): Unit

    // Unlocks the mutex. If there are other threads blocking on this
    // lock, then wake up one of them.
    public func unlock(): Unit

    // Tries to lock the mutex, returns false if the mutex is not
    // available, otherwise returns true.
    public func tryLock(): Bool
}

下方示例演示了如何使用 ReentrantMutex 来保护对全局共享变量 count 的访问，对 count 的操作即属于临界区：

import std.sync.*
import std.time.*
import std.collection.*

var count: Int64 = 0
let mtx = ReentrantMutex()

main(): Int64 {
    let list = ArrayList<Future<Unit>>()

    // creat 1000 threads.
    for (i in 0..1000) {
        let fut = spawn {
            sleep(Duration.millisecond) // sleep for 1ms.
            mtx.lock()
            count++
            mtx.unlock()
        }
        list.append(fut)
    }

    // Wait for all threads finished.
    for (f in list) {
        f.get()
    }

    println("count = ${count}")
    return 0
}

输出结果应为：

count = 1000

下方示例演示了如何使用 tryLock：

import std.sync.*

main(): Int64 {
    let mtx: ReentrantMutex = ReentrantMutex()
    var future: Future<Unit> = spawn {
        mtx.lock()
        while (true) {}
        mtx.unlock()
    }
    let res: Option<Unit> = future.get(10*1000*1000)
    match (res) {
        case Some(v) => ()
        case None =>
            if (mtx.tryLock()) {
                return 1
            }
            return 0
    }
    return 2
}

输出结果应为空。

以下是互斥锁的一些错误示例：

错误示例 1：线程操作临界区后没有解锁，导致其他线程无法获得锁而阻塞。

import std.sync.*

var sum: Int64 = 0
let mutex = ReentrantMutex()

main() {
    let foo = spawn { =>
        mutex.lock()
        sum = sum + 1
    }
    let bar = spawn { =>
        mutex.lock()
        sum = sum + 1
    }
    foo.get()
    println("${sum}")
    bar.get() // Because the thread is not unlocked, other threads waiting to obtain the current mutex will be blocked.
}

错误示例 2：在本线程没有持有锁的情况下调用 unlock 将会抛出异常。

import std.sync.*

var sum: Int64 = 0
let mutex = ReentrantMutex()

main() {
    let foo = spawn { =>
        sum = sum + 1
        mutex.unlock() // Error, Unlock without obtaining the lock and throw an exception: IllegalSynchronizationStateException.
    }
    foo.get()
    0
}

错误示例 3：tryLock() 并不保证获取到锁，可能会造成不在锁的保护下操作临界区和在没有持有锁的情况下调用 unlock 抛出异常等行为。

var sum: Int64 = 0
let mutex = ReentrantMutex()

main() {
    for (i in 0..100) {
        spawn { =>
            mutex.tryLock() // Error, `tryLock()` just trying to acquire a lock, there is no guarantee that the lock will be acquired, and this can lead to abnormal behavior.
            sum = sum + 1
            mutex.unlock()
        }
    }
}

另外，ReentrantMutex 在设计上是一个可重入锁，也就是说：在某个线程已经持有一个 ReentrantMutex 锁的情况下，再次尝试获取同一个 ReentrantMutex 锁，永远可以立即获得该 ReentrantMutex 锁。

注意：

虽然 ReentrantMutex 是一个可重入锁，但是调用 unlock() 的次数必须和调用 lock() 的次数相同，才能成功释放该锁。

下方示例代码演示了 ReentrantMutex 可重入的特性：

import std.sync.*
import std.time.*

var count: Int64 = 0
let mtx = ReentrantMutex()

func foo() {
    mtx.lock()
    count += 10
    bar()
    mtx.unlock()
}

func bar() {
    mtx.lock()
    count += 100
    mtx.unlock()
}

main(): Int64 {
    let fut = spawn {
        sleep(Duration.millisecond) // sleep for 1ms.
        foo()
    }

    foo()

    fut.get()

    println("count = ${count}")
    return 0
}

输出结果应为：

count = 220

在上方示例中，无论是主线程还是新创建的线程，如果在 foo() 中已经获得了锁，那么继续调用 bar() 的话，在 bar() 函数中由于是对同一个 ReentrantMutex 进行加锁，因此也是能立即获得该锁的，不会出现死锁。

Monitor

Monitor 是一个内置的数据结构，它绑定了互斥锁和单个与之相关的条件变量（也就是等待队列）。Monitor 可以使线程阻塞并等待来自另一个线程的信号以恢复执行。这是一种利用共享变量进行线程同步的机制，主要提供如下方法：

public class Monitor <: ReentrantMutex {
    // Create a monitor.
    public init()

    // Wait for a signal, blocking the current thread.
    public func wait(timeout!: Duration = Duration.Max): Bool

    // Wake up one thread of those waiting on the monitor, if any.
    public func notify(): Unit

    // Wake up all threads waiting on the monitor, if any.
    public func notifyAll(): Unit
}

调用 Monitor 对象的 wait、notify 或 notifyAll 方法前，需要确保当前线程已经持有对应的 Monitor 锁。wait 方法包含如下动作：

1. 添加当前线程到该 Monitor 对应的等待队列中;
2. 阻塞当前线程，同时完全释放该 Monitor 锁，并记录锁的重入次数;
3. 等待某个其它线程使用同一个 Monitor 实例的 notify 或 notifyAll 方法向该线程发出信号;
4. 当前线程被唤醒后，会自动尝试重新获取 Monitor 锁，且持有锁的重入状态与第 2 步记录的重入次数相同；但是如果尝试获取 Monitor 锁失败，则当前线程会阻塞在该 Monitor 锁上。

wait 方法接受一个可选参数 timeout。需要注意的是，业界很多常用的常规操作系统不保证调度的实时性，因此无法保证一个线程会被阻塞“精确的 N 纳秒”——可能会观察到与系统相关的不精确情况。此外，当前语言规范明确允许实现产生虚假唤醒——在这种情况下，wait 返回值是由实现决定的——可能为 true 或 false。因此鼓励开发者始终将 wait 包在一个循环中：

synchronized (obj) {
  while (<condition is not true>) {
    obj.wait()
  }
}

以下是使用 Monitor 的一个正确示例：

import std.sync.*
import std.time.*

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

    // Sleep for 10ms, to make sure the new thread can be executed.
    sleep(10 * Duration.millisecond)

    mon.lock()
    println("Main thread: set flag")
    flag = false
    mon.unlock()

    mon.lock()
    println("Main thread: notify")
    mon.notifyAll()
    mon.unlock()

    // wait for the new thread finished.
    fut.get()
    return 0
}

输出结果应为：

New thread: before wait
Main thread: set flag
Main thread: notify
New thread: after wait

Monitor 对象执行 wait 时，必须在锁的保护下进行，否则 wait 中释放锁的操作会抛出异常。

以下是使用条件变量的一些错误示例：

import std.sync.*

var m1 = Monitor()
var m2 = ReentrantMutex()
var flag: Bool = true
var count: Int64 = 0

func foo1() {
    spawn {
        m2.lock()
        while (flag) {
            m1.wait() // Error：The lock used together with the condition variable must be the same lock and in the locked state. Otherwise, the unlock operation in `wait` throws an exception.
        }
        count = count + 1
        m2.unlock()
    }
    m1.lock()
    flag = false
    m1.notifyAll()
    m1.unlock()
}

func foo2() {
    spawn {
        while (flag) {
            m1.wait() // Error：The `wait` of a conditional variable must be called with a lock held.
        }
        count = count + 1
    }
    m1.lock()
    flag = false
    m1.notifyAll()
    m1.unlock()
}

main() {
    foo1()
    foo2()
    m1.wait()
    return 0
}

MultiConditionMonitor

MultiConditionMonitor 是一个内置的数据结构，它绑定了互斥锁和一组与之相关的动态创建的条件变量。该类应仅当在 Monitor 类不足以满足复杂的线程间同步的场景下使用。主要提供如下方法：

public class MultiConditionMonitor <: ReentrantMutex {
   // Constructor.
   init()

   // Returns a new ConditionID associated with this monitor. May be used to implement
   // "single mutex -- multiple wait queues" concurrent primitives.
   // Throws IllegalSynchronizationStateException("Mutex is not locked by the current thread") if the current thread does not hold this mutex.
   func newCondition(): ConditionID

   // Blocks until either a paired `notify` is invoked or `timeout` nanoseconds pass.
   // Returns `true` if the specified condition was signalled by another thread or `false` on timeout.
   // Spurious wakeups are allowed.
   // Throws IllegalSynchronizationStateException("Mutex is not locked by the current thread") if the current thread does not hold this mutex.
   // Throws IllegalSynchronizationStateException("Invalid condition") if `id` was not returned by `newCondition` of this MultiConditionMonitor instance.
   func wait(id: ConditionID, timeout!: Duration = Duration.Max): Bool

   // Wakes up a single thread waiting on the specified condition, if any (no particular admission policy implied).
   // Throws IllegalSynchronizationStateException("Mutex is not locked by the current thread") if the current thread does not hold this mutex.
   // Throws IllegalSynchronizationStateException("Invalid condition") if `id` was not returned by `newCondition` of this MultiConditionMonitor instance.
   func notify(id: ConditionID): Unit

   // Wakes up all threads waiting on the specified condition, if any (no particular admission policy implied).
   // Throws IllegalSynchronizationStateException("Mutex is not locked by the current thread") if the current thread does not hold this mutex.
   // Throws IllegalSynchronizationStateException("Invalid condition") if `id` was not returned by `newCondition` of this MultiConditionMonitor instance.
   func notifyAll(id: ConditionID): Unit
}

1. newCondition(): ConditionID：创建一个新的条件变量并与当前对象关联，返回一个特定的 ConditionID 标识符
2. wait(id: ConditionID, timeout!: Duration = Duration.Max): Bool：等待信号，阻塞当前线程
3. notify(id: ConditionID): Unit：唤醒一个在 Monitor 上等待的线程（如果有）
4. notifyAll(id: ConditionID): Unit：唤醒所有在 Monitor 上等待的线程（如果有）

初始化时，MultiConditionMonitor 没有与之相关的 ConditionID 实例。每次调用 newCondition 都会将创建一个新的条件变量并与当前对象关联，并返回如下类型作为唯一标识符：

public struct ConditionID {
   private init() { ... } // constructor is intentionally private to prevent
                          // creation of such structs outside of MultiConditionMonitor
}

请注意使用者不可以将一个 MultiConditionMonitor 实例返回的 ConditionID 传给其它实例，或者手动创建 ConditionID（例如使用 unsafe）。由于 ConditionID 所包含的数据（例如内部数组的索引，内部队列的直接地址，或任何其他类型数据等）和创建它的 MultiConditionMonitor 相关，所以将“外部” conditonID 传入 MultiConditionMonitor 中会导致 IllegalSynchronizationStateException。

以下是使用 MultiConditionMonitor 去实现一个长度固定的有界 FIFO 队列，当队列为空，get() 会被阻塞；当队列满了时，put() 会被阻塞。

import std.sync.*

class BoundedQueue {
    // Create a MultiConditionMonitor, two Conditions.
    let m: MultiConditionMonitor = MultiConditionMonitor()
    var notFull: ConditionID
    var notEmpty: ConditionID

    var count: Int64 // Object count in buffer.
    var head: Int64  // Write index.
    var tail: Int64  // Read index.

    // Queue's length is 100.
    let items: Array<Object> = Array<Object>(100, {i => Object()})

    init() {
        count = 0
        head = 0
        tail = 0

        synchronized(m) {
          notFull  = m.newCondition()
          notEmpty = m.newCondition()
        }
    }

    // Insert an object, if the queue is full, block the current thread.
    public func put(x: Object) {
        // Acquire the mutex.
        synchronized(m) {
          while (count == 100) {
            // If the queue is full, wait for the "queue notFull" event.
            m.wait(notFull)
          }
          items[head] = x
          head++
          if (head == 100) {
            head = 0
          }
          count++

          // An object has been inserted and the current queue is no longer
          // empty, so wake up the thread previously blocked on get()
          // because the queue was empty.
          m.notify(notEmpty)
        } // Release the mutex.
    }

    // Pop an object, if the queue is empty, block the current thread.
    public func get(): Object {
        // Acquire the mutex.
        synchronized(m) {
          while (count == 0) {
            // If the queue is empty, wait for the "queue notEmpty" event.
            m.wait(notEmpty)
          }
          let x: Object = items[tail]
          tail++
          if (tail == 100) {
            tail = 0
          }
          count--

          // An object has been popped and the current queue is no longer
          // full, so wake up the thread previously blocked on put()
          // because the queue was full.
          m.notify(notFull)

          return x
        } // Release the mutex.
    }
}

synchronized 关键字

互斥锁 ReentrantMutex 提供了一种便利灵活的加锁的方式，同时因为它的灵活性，也可能引起忘了解锁，或者在持有互斥锁的情况下抛出异常不能自动释放持有的锁的问题。因此，仓颉编程语言提供一个 synchronized 关键字，搭配ReentrantMutex一起使用，可以在其后跟随的作用域内自动进行加锁解锁操作，用来解决类似的问题。

下方示例代码演示了如何使用 synchronized 关键字来保护共享数据：

import std.sync.*
import std.time.*
import std.collection.*

var count: Int64 = 0
let mtx = ReentrantMutex()

main(): Int64 {
    let list = ArrayList<Future<Unit>>()

    // creat 1000 threads.
    for (i in 0..1000) {
        let fut = spawn {
            sleep(Duration.millisecond) // sleep for 1ms.
            // Use synchronized(mtx), instead of mtx.lock() and mtx.unlock().
            synchronized(mtx) {
                count++
            }
        }
        list.append(fut)
    }

    // Wait for all threads finished.
    for (f in list) {
        f.get()
    }

    println("count = ${count}")
    return 0
}

输出结果应为：

count = 1000

通过在 synchronized 后面加上一个 ReentrantMutex 实例，对其后面修饰的代码块进行保护，可以使得任意时刻最多只有一个线程可以执行被保护的代码：

1. 一个线程在进入 synchronized 修饰的代码块之前，会自动获取 ReentrantMutex 实例对应的锁，如果无法获取锁，则当前线程被阻塞；
2. 一个线程在退出 synchronized 修饰的代码块之前，会自动释放该 ReentrantMutex 实例的锁。

对于控制转移表达式（如 break、continue、return、throw），在导致程序的执行跳出 synchronized 代码块时，也符合上面第 2 条的说明，也就说也会自动释放 synchronized 表达式对应的锁。

下方示例演示了在 synchronized 代码块中出现 break 语句的情况：

import std.sync.*
import std.collection.*

var count: Int64 = 0
var mtx: ReentrantMutex = ReentrantMutex()

main(): Int64 {
    let list = ArrayList<Future<Unit>>()
    for (i in 0..10) {
        let fut = spawn {
            while (true) {
                synchronized(mtx) {
                    count = count + 1
                    break
                    println("in thread")
                }
            }
        }
        list.append(fut)
    }

    // Wait for all threads finished.
    for (f in list) {
        f.get()
    }

    synchronized(mtx) {
        println("in main, count = ${count}")
    }
    return 0
}

输出结果应为：

in main, count = 10

实际上 in thread 这行不会被打印，因为 break 语句实际上会让程序执行跳出 while 循环（当然，在跳出 while 循环之前，是先跳出 synchronized 代码块）。

线程局部变量 ThreadLocal

使用 core 包中的 ThreadLocal 可以创建并使用线程局部变量，每一个线程都有它独立的一个存储空间来保存这些线程局部变量，因此，在每个线程可以安全地访问他们各自的线程局部变量，而不受其他线程的影响。

public class ThreadLocal<T> {
    /*
     * 构造一个携带空值的仓颉线程局部变量
     */
    public init()

    /*
     * 获得仓颉线程局部变量的值，如果值不存在，则返回 Option<T>.None
     * 返回值 Option<T> - 仓颉线程局部变量的值
     */
    public func get(): Option<T>

    /*
     * 通过 value 设置仓颉线程局部变量的值
     * 如果传入 Option<T>.None，该局部变量的值将被删除，在线程后续操作中将无法获取
     * 参数 value - 需要设置的局部变量的值
     */
    public func set(value: Option<T>): Unit
}

下方示例代码演示了如何通过 ThreadLocal类来创建并使用各自线程的局部变量：

main(): Int64 {
    let tl = ThreadLocal<Int64>()
    let fut1 = spawn {
        tl.set(123)
        println("tl in spawn1 = ${tl.get().getOrThrow()}")
    }
    let fut2 = spawn {
        tl.set(456)
        println("tl in spawn2 = ${tl.get().getOrThrow()}")
    }
    fut1.get()
    fut2.get()
    0
}

可能的输出结果如下：

tl in spawn1 = 123
tl in spawn2 = 456

或者

tl in spawn2 = 456
tl in spawn1 = 123

线程睡眠指定时长 sleep

sleep 函数会阻塞当前运行的线程，该线程会主动睡眠一段时间，之后再恢复执行，其参数类型为 Duration 类型。函数原型为：

func sleep(dur: Duration): Unit // Sleep for at least `dur`.

注意：

如果 dur <= Duration.Zero, 那么当前线程只会让出执行资源，并不会进入睡眠。

以下是使用 sleep 的示例：

import std.sync.*
import std.time.*

main(): Int64 {
    println("Hello")
    sleep(Duration.second)  // sleep for 1s.
    println("World")
    return 0
}

输出结果如下：

Hello
World

I/O 流概述

本章我们会介绍基本的 I/O 概念和文件操作。

在仓颉编程语言中，我们将与应用程序外部载体交互的操作称之为 I/O 操作。I 对应输入（Input），O 对应输出（Output）。

仓颉编程语言所有的 I/O 机制都是基于数据流进行输入输出，这些数据流表示了字节数据的序列。数据流是一串连续的数据集合，它就像承载数据的管道，在管道的一端输入数据，在管道的另一端就可以输出数据。

仓颉编程语言将输入输出抽象为流（Stream）：

• 将数据从外存中读取到内存中的称为输入流（InputStream），输入端可以一段一段地向管道中写入数据，这些数据段会按先后顺序形成一个长的数据流；
• 将数据从内存写入外存中的称为输出流（OutputStream），输出端也可以一段一段地从管道中读出数据，每次可以读取其中的任意长度的数据（不需要跟输入端匹配），但只能读取先输入的数据，再读取后输入的数据。

有了这一层抽象，仓颉编程语言就可以使用统一的接口来实现与外部数据的交互。

仓颉编程语言将标准输入输出、文件操作、网络数据流、字符串流、加密流、压缩流等等形式的操作，统一用 Stream 描述。

Stream 主要面向处理原始二进制数据，Stream 中最小的数据单元是 Byte。

仓颉编程语言将 Stream 定义成了 interface，它让不同的 Stream 可以用装饰器模式进行组合，极大地提升了可扩展性。

输入流

程序从输入流读取数据源（数据源包括外界的键盘、文件、网络...），即输入流是将数据源读入到程序的通信通道。

仓颉编程语言用 InputStream 接口类型来表示输入流，它提供了 read 函数，这个函数会将可读的数据写入到 buffer 中，返回值表示了该次读取的字节总数。

InputStream 接口定义：

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

当我们拥有一个输入流的时候，就可以像下面的代码那样去读取字节数据，读取的数据会被写到 read 的入参数组中。

输入流读取示例：

import std.io.InputStream

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

输出流

程序向输出流写入数据。输出流是将程序中的数据输出到外界（显示器、打印机、文件、网络等）的通信通道。

仓颉编程语言用 OutputStream 接口类型来表示输出流，它提供了 write 函数，这个函数会将 buffer 中的数据写入到绑定的流中。

特别的，有一些输出流的 write 不会立即写到外存中，而是有一定的缓冲策略，只有当符合条件或主动调用 flush 时才会真实写入，目的是提高性能。

为了统一处理这些 flush 操作，在 OutputStream 中有一个 flush 的默认实现，它有助于抹平 API 调用的差异性。

OutputStream 接口定义：

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

    func flush(): Unit {
        // 空实现
    }
}

当我们拥有一个输出流时，我们可以像下面的代码那样去写入字节数据。

输出流写入示例：

import std.io.OutputStream

main() {
    let output: OutputStream = ...
    let buf = Array<Byte>(256, item: 111)
    output.write(buf)
    output.flush()
}

数据流分类

按照数据流职责上的差异，我们可以给 Stream 简单分成两类：

• 节点流：直接提供数据源，节点流的构造方式通常是依赖某种直接的外部资源（即文件、网络等）。
• 处理流：只能代理其它数据流进行处理，处理流的构造方式通常是依赖其它的流。

I/O 节点流

节点流是指直接提供数据源的流，节点流的构造方式通常是依赖某种直接的外部资源（即文件、网络等）。

仓颉编程语言中常见的节点流包含标准流（StdIn、StdOut、StdErr）、文件流（File）、网络流（Socket）等。

我们本章会着重介绍一下标准流和文件流。

标准流

标准流包含了标准输入流（stdin）、标准输出流（stdout）和标准错误输出流（stderr）。

标准流是我们的程序与外部数据交互的标准接口。程序运行的时候从输入流读取数据，作为程序的输入，程序运行过程中输出的信息被传送到输出流，类似的，错误信息被传送到错误流。

在仓颉编程语言中我们可以使用 Console 类型来分别访问它们。

使用 Console 类型需要导入 console 包：

导入 console 包示例：

import std.console.*

Console 对三个标准流都进行了易用性封装，提供了更方便的基于 String 的扩展操作，并且对于很多常见类型都提供了丰富的重载来优化性能。

其中最重要的是 Console 提供了并发安全的保证，我们可以在任意线程中安全的通过 Console 提供的接口来读写内容。

默认情况下标准输入流来源于键盘输入的信息，例如我们在命令行界面中输入的文本。

当我们需要从标准输入流中获取数据时，可以通过 stdIn 来读取，例如通过 readln 函数来获取命令行的输入。

标准输入流读取示例：

import std.console.*

main() {
    let txt = Console.stdIn.readln()
    println(txt ?? "")
}

运行上面的代码，在命令行上输入一些文字，然后换行结束，我们就能看到我们输入的内容了！

输出流分为标准输出流和标准错误流，默认情况下，它们都会输出到屏幕，例如我们在命令行界面中看到的文本。

当我们需要往标准输出流中写入数据时，可以通过 stdOut/stdErr 来写入，例如通过 write 函数来向命令打印内容。

使用 stdOut 和直接使用 print 函数的差别是，stdOut 是并发安全的，并且由于 stdOut 使用了缓存技术，在输入内容较多时拥有更好的性能表现。

需要注意的是，写完数据后我们需要对 stdOut 调用 flush 才能保证内容被写到标准流中。

标准输出流写入示例：

import std.console.*

main() {
    for (i in 0..1000) {
        Console.stdOut.writeln("hello, world!")
    }
    Console.stdOut.flush()
}

文件流

仓颉编程语言提供了 fs 包来支持通用文件系统任务。虽然不同的操作系统对于文件系统提供的接口有所不同，但是仓颉编程语言抽象出以下一些共通的功能，通过统一的功能接口，屏蔽不同操作系统之间的差异，来简化我们的使用。

这些常规操作任务包括：创建文件/目录、读写文件、重命名或移动文件/目录、删除文件/目录、复制文件/目录、获取文件/目录元数据、检查文件/目录是否存在。具体 API 可以查阅库文档。

使用文件系统相关的功能需要导入 fs 包：

导入 fs 包示例：

import std.fs.*

本章会着重介绍 File 相关的使用，对于 Path 和 Directory 的使用可以查阅对应的 API 文档。

File 类型在仓颉编程语言中同时提供了常规文件操作和文件流两类功能。

常规文件操作

对于常规的文件操作，我们可以使用一系列静态函数来完成快捷的操作。

例如我们如果要检查某个路径对应的文件是否存在，可以使用 exists 函数。当 exists 函数返回 true 时表示文件存在，反之不存在。

exists 函数使用示例：

import std.fs.*

main() {
    let exist = File.exists("./tempFile.txt")
    println("exist: ${exist}")
}

移动文件、拷贝文件和删除文件也非常简单，File 同样提供了对应的静态函数 move、copy、delete。

move、copy、delete 函数使用示例：

import std.fs.*

main() {
    File.copy("./tempFile.txt", "./tempFile2.txt", false)
    File.move("./tempFile2.txt", "./tempFile3.txt", false)
    File.delete("./tempFile3.txt")
}

如果我们需要直接将文件的所有数据读出来，或者一次性将数据写入文件里，我们可以使用 File 提供的 readFrom、writeTo 函数直接读写文件。在数据量较少的情况下它们既简单易用又能提供较好的性能表现，让我们不需要手动处理数据流的事情。

readFrom、writeTo 函数使用示例：

import std.fs.*

main() {
    let bytes = File.readFrom("./tempFile.txt") // 一次性读取了所有的数据
    File.writeTo("./otherFile.txt", bytes) // 把数据一次性写入另一个文件中
}

文件流操作

除了上述的常规文件操作之外，File 类型也被设计为一种数据流类型，因此 File 类型本身实现了 IOStream 接口。当我们创建了一个 File 的实例，我们就可以把这个实例当成数据流来使用。

File 类定义：

public class File <: Resource & IOStream & Seekable {
    ...
}

File 提供了两种构造方式，一种是通过两个方便的静态函数 openRead/create 直接打开文件或创建新文件的实例，另一种是通过构造函数传入完整的打开文件选项来构造新实例。

其中，openRead 打开的文件是只读的，我们不能对实例进行写操作，否则会抛出运行时异常；而 create 创建的文件是只写的，我们不能对实例进行读操作，否则也会抛出运行时异常。

File 构造示例：

// 创建
internal import std.fs.*

main() {
    let file = File.create("./tempFile.txt")
    file.write("hello, world!".toArray())

    // 打开
    let file2 = File.openRead("./tempFile.txt")
    let bytes = file2.readToEnd() // 读取所有数据
    println(bytes)
}

当我们需要更精细的打开选项时，可以使用构造函数传入一个 OpenOption 值。OpenOption 是一个 enum 类型，它提供了丰富的文件打开选项，例如 Append、Create、Truncate、Open 以及其它便捷的复合操作。

File 打开选项使用示例：

// 使用指定选项打开文件
let file = File("./tempFile.txt", OpenOption.Truncate(false))
...

因为我们打开 File 的实例会占用宝贵的系统资源，所以使用完 File 的实例之后需要注意及时关闭 File，以释放系统资源。

所幸 File 实现了 Resource 接口，我们在大多数时候都可以使用 try-with-resource 语法来简化我们的使用。

try-with-resource 语法使用示例：

try (file2 = File.openRead("./tempFile.txt")) {
    ...
    // 结束使用后自动释放文件
}

I/O 处理流

处理流是指代理其它数据流进行处理的流。

仓颉编程语言中常见的处理流包含 BufferedInputStream、BufferedOutputStream、StringReader、StringWriter、ChainedInputStream 等。

我们本章会着重介绍一下缓冲流和字符串流。

缓冲流

由于涉及磁盘的 I/O 操作相比内存的 I/O 操作要慢很多，所以对于高频次且小数据量的读写操作来说，不带缓冲的数据流效率很低，每次读取和写入数据都会带来大量的 I/O 耗时。而带缓冲的数据流，可以多次读写数据，但不触发磁盘 I/O 操作，只是先放到内存里。等凑够了缓冲区大小的时候再一次性操作磁盘，这种方式可以显著减少磁盘操作次数，从而提升性能表现。

仓颉编程语言标准库提供了 BufferedInputStream 和 BufferedOutputStream 这两个类型用来提供缓冲功能。

使用 BufferedInputStream 和 BufferedOutputStream 类型需要导入 io 包。

导入 io 包示例：

import std.io.*

BufferedInputStream 的作用是为另一个输入流添加缓冲的功能。本质上 BufferedInputStream 是通过一个内部缓冲数组实现的。

当我们通过 BufferedInputStream 来读取流的数据时，BufferedInputStream 会一次性读取整个缓冲区大小的数据，然后我们再使用 read 函数就可以分多次读取更小规模的数据；当缓冲区中的数据被读完之后，输入流就会再次填充缓冲区；如此反复，直到我们读完数据流的所有数据。

构造一个 BufferedInputStream 很简单，我们只需要在构造函数中传入另一个输入流就可以了。如果我们需要指定缓冲区的大小，也可以额外传入 capacity 参数进行指定。

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 也是通过一个内部缓冲数组实现的。

当我们通过 BufferedOutputStream 来向输出流写入数据时，write 的数据会先写入内部缓冲数组中；当缓冲区中的数据被填满之后，BufferedOutputStream 会将缓冲区的数据一次性写入输出流中，然后清空缓冲区再次被写入；如此反复，直到我们写完所有的数据。

需要注意的是，由于我们没写够缓冲区时不会触发输出流的写入操作，所以当我们往 BufferedOutputStream 写完所有的数据后，需要额外调用 flush 函数来最终完成写入。

构造一个 BufferedOutputStream 也很简单，我们只需要在构造函数中传入另一个输出流就可以了。如果我们需要指定缓冲区的大小，也可以额外传入 capacity 参数指定。

BufferedOutputStream 构造示例：

import std.io.*

main(): Unit {
    let arr1 = "01234".toArray()
    let byteArrayStream = ByteArrayStream()
    byteArrayStream.write(arr1)
    let bufferedOutputStream = BufferedOutputStream(byteArrayStream)
    let arr2 = "56789".toArray()

    /* 向流中写入数据，此时数据在外部流的缓冲区中 */
    bufferedOutputStream.write(arr2)

    /* 调用 flush 函数，真正将数据写入内部流中 */
    bufferedOutputStream.flush()
    println(String.fromUtf8(byteArrayStream.readToEnd())) // 0123456789
}

字符串流

由于仓颉编程语言的输入流和输出流是基于字节数据来抽象的（拥有更好的性能），在部分以字符串为主的场景中使用起来不太友好，例如往文件里写入大量的文本内容时，需要将文本内容转换成字节数据，再写入文件。

为了提供友好的字符串操作能力，仓颉编程语言提供了 StringReader 和 StringWriter 来添加字符串处理能力。

使用 StringReader 和 StringWriter 类型需要导入 io 包：

导入 io 包示例：

import std.io.*

StringReader 提供了按行读、按筛选条件读的能力，相比将字节数据读出来再手动转换成字符串，具有更好的性能表现和易用性。

构造 StringReader 很简单，传入另一个输入流就可以了。

StringReader 使用示例：

import std.io.*

main(): Unit {
    let arr1 = "012\n346789".toArray()
    let byteArrayStream = ByteArrayStream()
    byteArrayStream.write(arr1)
    let stringReader = StringReader(byteArrayStream)

    /* 读取一行数据 */
    let line = stringReader.readln()
    println(line ?? "error") // 012
}

StringWriter 提供了直接写字符串、按行直接写字符串的能力，相比将字节数据手动转换成字符串再写入，具有更好的性能表现和易用性。

构造 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:\n100.000000
}

网络编程概述

网络通信是两个设备通过计算机网络进行数据交换的过程。通过编写软件达成网络通信的行为即为网络编程。

仓颉为开发者提供了基础的网络编程功能，在仓颉标准库中，用户可使用 std 模块下的 socket 包来实现传输层网络通信。

在传输层协议中，分为不可靠传输和可靠传输两种，仓颉将其抽象为 DatagramSocket 和 StreamSocket。其中不可靠传输协议常见的是 UDP，可靠传输协议常见的是 TCP，仓颉分别将其抽象为 UdpSocket 和 TcpSocket。另外，仓颉也实现了对传输层 Unix Domain 协议的支持，并支持其通过可靠和不可靠传输两种方式进行通信。

而在应用层协议中，较为常见的是 HTTP 协议，常用于开发 Web 应用程序等。当前 HTTP 协议已有多个版本，仓颉目前支持 HTTP/1.1、HTTP/2.0 等。

另外，WebSocket 作为一种提升 Web 服务端与客户端间的通信效率的应用层协议，仓颉将其抽象为 WebSocket 对象，并支持从 HTTP 协议升级至 WebSocket 协议。

需要注意的是，仓颉的网络编程是阻塞式的。但被阻塞的是仓颉线程，阻塞中的仓颉线程会将系统线程让渡出去，因此并不会真正阻塞一个系统线程。

Socket 编程

仓颉的 Socket 编程指的是基于传输层协议实现网络传输数据包的功能。

在可靠传输场景下，仓颉分别启动客户端套接字和服务端套接字。客户端套接字必须指定将要连接的远端地址，可选择性地绑定本端地址，在连接成功后，才可以收发报文。而服务端套接字必须绑定本端地址，在绑定成功后，才可以收发报文。

在不可靠传输场景下，套接字无需区分客户端和服务端，仓颉分别启动两个套接字进行数据传输。套接字必须绑定本端地址，绑定成功后，才可以收发报文。并且，套接字也可选择性地指定远端连接地址，指定后将仅接受指定的远端地址的报文，同时在 send 时无需指定远端地址，报文将发送至成功连接的地址。

Tcp 编程

Tcp 作为一种常见的可靠传输协议，以 Tcp 类型套接字举例，仓颉在可靠传输场景下的可参考的编程模型如下：

1. 创建服务端套接字，并指定本端绑定地址。
2. 执行绑定。
3. 执行 accept 动作，将阻塞等待，直到获取到一个客户端套接字连接。
4. 同步创建客户端套接字，并指定远端的待连接的地址。
5. 执行连接。
6. 连接成功后，服务端会在 accept 接口返回一个新的套接字，此时服务端可以通过此套接字进行读写操作，即收发报文。客户端则可以直接进行读写操作。

Tcp 服务端和客户端程序示例如下：

import std.socket.*
import std.time.*
import std.sync.*

let SERVER_PORT: UInt16 = 8080

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)

            // 服务端读取到的数据为: [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
}

Udp 编程

Udp 作为一种常见的不可靠传输协议，以 Udp 类型套接字举例，仓颉在不可靠传输场景下的可参考的编程模型如下：

1. 创建套接字，并指定本端绑定地址。
2. 执行绑定。
3. 指定远端地址进行报文发送。
4. 不连接远端地址场景下，可以收取来自不同远端地址的报文，并返回远端地址信息。

Udp 收发报文程序示例如下：

import std.socket.*
import std.time.*
import std.sync.*

let SERVER_PORT: UInt16 = 8080

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

        // 套接字收取到的报文以及远端地址: [1, 2, 3]， 127.0.0.1
        println("Server receive ${count} bytes: ${buf} from ${sender}")
    }
}

main(): Int64 {
    let future = spawn {
        runUpdServer()
    }
    sleep(Duration.second)

    try (udpSocket = UdpSocket(bindAt: 0)) {
        udpSocket.sendTimeout = Duration.second * 2
        udpSocket.bind()
        udpSocket.sendTo(
            SocketAddress("127.0.0.1", SERVER_PORT),
            Array<Byte>([1, 2, 3])
        )
    }

    future.get()

    return 0
}

HTTP 编程

HTTP 作为一种通用的应用层协议，通过请求-响应的机制实现数据传输，客户端发送请求，服务端返回响应。请求和响应的格式是固定的，由报文头和报文体组成。

常用的请求类型为 GET 和 POST，GET 请求只有报文头，用于向服务器请求应用层数据，POST 请求带有报文体，以一个空行与报文头进行分隔，用于向服务器提供应用层数据。

请求-响应的报文头字段内容较多，此处不再一一赘述，仓颉支持 HTTP 1.0/1.1/2.0 等协议版本，开发者可以基于协议 RFC 9110、9112、9113、9218、7541 以及仓颉所提供的 HttpRequestBuilder 和 HttpResponseBuilder 类构造请求及响应报文。

以下示例展示了如何使用仓颉进行客户端和服务端编程，实现的功能是客户端发送请求头为 GET /hello 的请求，服务端返回响应，响应体为 "Hello Cangjie!"，代码如下:

import net.http.*
import std.time.*
import std.sync.*

func startServer(): Unit {
    // 1. 构建 Server 实例
    let server = ServerBuilder()
                        .addr("127.0.0.1")
                        .port(8080)
                        .build()
    // 2. 注册请求处理逻辑
    server.distributor.register("/hello", {httpContext =>
        httpContext.responseBuilder.body("Hello Cangjie!")
    })
    // 3. 启动服务
    server.serve()
}

func startClient(): Unit {
    // 1. 构建 client 实例
    let client = ClientBuilder().build()
    // 2. 发送 request
    let resp = client.get("http://127.0.0.1:8080/hello")
    // 3. 读取response
    println(resp)
    // 4. 关闭连接
    client.close()
}

main () {
    spawn {
        startServer()
    }
    sleep(Duration.second)
    startClient()
}

WebSocket 编程

在网络编程中，WebSocket 也是一种常用的应用层协议，与 HTTP 一样，它也基于 TCP 协议之上，并且常用于 web 服务端应用开发。

不同于 HTTP 的是， WebSocket 只需要客户端和服务端进行一次握手，即可创建长久的连接，并且进行双向的数据传输。即，基于 WebSocket 实现的服务端可以主动传输数据给客户端，从而实现实时通讯。

WebSocket 是一个独立的协议，它与 HTTP 的关联在于，它的握手被 HTTP 服务端解释为一个升级请求。因此，仓颉将 WebSocket 包含在 http 包中。

仓颉将 WebSocket 协议通信机制抽象为 WebSocket 类，提供方法将一个 http/1.1 或 http/2.0 服务端句柄升级到 WebSocket 协议实例，通过返回的 WebSocket 实例进行 WebSocket 通信，例如数据报文的读写。

在仓颉中，WebSocket 所传输的数据基本单元称为帧，帧分为两类，一类为传输控制信息的帧，即 Close Frame 用于关闭连接， Ping Frame 用于实现 Keep-Alive ， Pong Frame 是 Ping Frame 的响应类型，另一类是传输应用数据的帧，应用数据帧支持分段传输。

仓颉的帧由三个属性构成，其中 fin 和 frameType 共同说明了帧是否分段和帧的类型，payload 为帧的载荷，除此之外开发者无需关心其他属性即可进行报文传输。

如下示例展示了 WebSocket 的握手以及消息收发过程：创建 HTTP 客户端和服务端，分别发起 WebSocket 升级（或握手），握手成功后开始帧的读写。

import net.http.*
import encoding.url.*
import std.time.*
import std.sync.*
import std.collection.*
import std.log.*

let server = ServerBuilder()
                        .addr("127.0.0.1")
                        .port(0)
                        .build()

// client：
main() {
    // 1 启动服务器
    spawn { startServer() }
    sleep(Duration.millisecond * 200)

    let client = ClientBuilder().build()
    let u = URL.parse("ws://127.0.0.1:${server.port}/webSocket")

    let subProtocol = ArrayList<String>(["foo1", "bar1"])
    let headers = HttpHeaders()
    headers.add("test", "echo")

    // 2 完成 WebSocket 握手，获取 WebSocket 实例
    let websocket: WebSocket
    let respHeaders: HttpHeaders
    (websocket, respHeaders) = WebSocket.upgradeFromClient(client, u, subProtocols: subProtocol, headers: headers)
    client.close()

    println("subProtocol: ${websocket.subProtocol}")      // fool1
    println(respHeaders.getFirst("rsp") ?? "") // echo

    // 3 消息收发
    // 发送 hello
    websocket.write(TextWebFrame, "hello".toArray())
    // 收
    let data = ArrayList<UInt8>()
    var frame = websocket.read()
    while(true) {
        match(frame.frameType) {
            case ContinuationWebFrame =>
                data.appendAll(frame.payload)
                if (frame.fin) {
                    break
                }
            case TextWebFrame | BinaryWebFrame =>
                if (!data.isEmpty()) {
                    throw Exception("invalid frame")
                }
                data.appendAll(frame.payload)
                if (frame.fin) {
                    break
                }
            case CloseWebFrame =>
                websocket.write(CloseWebFrame, frame.payload)
                break
            case PingWebFrame =>
                websocket.writePongFrame(frame.payload)
            case _ => ()
        }
        frame = websocket.read()
    }
    println("data size: ${data.size}")      // 4097
    println("last item: ${String.fromUtf8(Array(data)[4096])}")        // a


    // 4 关闭 websocket，
    // 收发 CloseFrame
    websocket.writeCloseFrame(status: 1000)
    let websocketFrame = websocket.read()
    println("close frame type: ${websocketFrame.frameType}")      // CloseWebFrame
    println("close frame payload: ${websocketFrame.payload}")     // 3, 232
    // 关闭底层连接
    websocket.closeConn()

    server.close()
}

func startServer() {
    // 1 注册 handler
    server.distributor.register("/webSocket", handler1)
    server.logger.level = OFF
    server.serve()
}

// server:
func handler1(ctx: HttpContext): Unit {
    // 2 完成 websocket 握手，获取 websocket 实例
    let websocketServer = WebSocket.upgradeFromServer(ctx, subProtocols: ArrayList<String>(["foo", "bar", "foo1"]),
        userFunc: {request: HttpRequest =>
            let value = request.headers.getFirst("test") ?? ""
            let headers = HttpHeaders()
            headers.add("rsp", value)
            headers
        })
    // 3 消息收发
    // 收 hello
    let data = ArrayList<UInt8>()
    var frame = websocketServer.read()
    while(true) {
        match(frame.frameType) {
            case ContinuationWebFrame =>
                data.appendAll(frame.payload)
                if (frame.fin) {
                    break
                }
            case TextWebFrame | BinaryWebFrame =>
                if (!data.isEmpty()) {
                    throw Exception("invalid frame")
                }
                data.appendAll(frame.payload)
                if (frame.fin) {
                    break
                }
            case CloseWebFrame =>
                websocketServer.write(CloseWebFrame, frame.payload)
                break
            case PingWebFrame =>
                websocketServer.writePongFrame(frame.payload)
            case _ => ()
        }
        frame = websocketServer.read()
    }
    println("data: ${String.fromUtf8(Array(data))}")    // hello
    // 发 4097 个 a
    websocketServer.write(TextWebFrame, Array<UInt8>(4097, item: 97))

    // 4 关闭 websocket，
    // 收发 CloseFrame
    let websocketFrame = websocketServer.read()
    println("close frame type: ${websocketFrame.frameType}")   // CloseWebFrame
    println("close frame payload: ${websocketFrame.payload}")     // 3, 232
    websocketServer.write(CloseWebFrame, websocketFrame.payload)
    // 关闭底层连接
    websocketServer.closeConn()
}

该示例运行结果如下：

subProtocol: foo1
echo
data: hello
data size: 4097
last item: a
close frame type: CloseWebFrame
close frame payload: [3, 232]
close frame type: CloseWebFrame
close frame payload: [3, 232]

宏的简介

宏可以理解为一种特殊的函数。一般的函数在输入的值上进行计算，然后输出一个新的值，而宏的输入和输出都是程序本身。在输入一段程序（或程序片段，例如表达式），输出一段新的程序，这段输出的程序随后用于编译和执行。为了把宏的调用和函数调用区分开来，我们在调用宏时使用 @ 加上宏的名称。

让我们从一个简单的例子开始：假设我们想在调试过程中打印某个表达式的值，同时打印出表达式本身。

let x = 3
let y = 2
@dprint(x)        // 打印 "x = 3"
@dprint(x + y)    // 打印 "x + y = 5"

显然，dprint 不能被写为常规的函数，由于函数只能获得输入的值，不能获得输入的程序片段。但是，我们可以将 dprint 实现为一个宏。一个基本的实现如下：

macro package define

import std.ast.*

public macro dprint(input: Tokens): Tokens {
    let inputStr = input.toString()
    let result = quote(
        print($(inputStr) + " = ")
        println($(input)))
    return result
}

在解释每行代码之前，我们先测试这个宏可以达到预期的效果。首先，在当前目录下创建一个 macros 文件夹，并在 macros 文件夹中创建 dprint.cj 文件，将以上内容复制到 dprint.cj 文件中。另外在当前目录下创建 main.cj，包含以下测试代码：

import define.*

main() {
    let x = 3
    let y = 2
    @dprint(x)
    @dprint(x + y)
}

请注意，得到的目录结构如下：

// Directory layout.
src
|-- macros
|     `-- dprint.cj
`-- main.cj

在当前目录（src）下，运行编译命令：

cjc macros/*.cj --compile-macro
cjc main.cj -o main

然后运行 ./main，可以看到如下输出：

x = 3
x + y = 5

让我们依次查看代码的每个部分：

• 第 1 行：macro package define

  宏必须声明在独立的包中（不能和其他 public 函数一起），含有宏的包使用 macro package 来声明。这里我们声明了一个名为 define 的宏包。

• 第 2 行：import std.ast.*

  实现宏需要的数据类型，例如 Tokens 和后面会讲到的语法节点类型，位于仓颉标准库的 ast 包中，因此任何宏的实现都需要首先引入 ast 包。

• 第 3 行：public macro dprint(input: Tokens): Tokens

  在这里我们声明一个名为 dprint 的宏。由于这个宏是一个非属性宏（之后我们会解释这个概念），它接受一个类型为 Tokens 的参数。该输入代表传给宏的程序片段。宏的返回值也是一个程序片段。

• 第 4 行：let inputStr = input.toString()

  在宏的实现中，首先将输入的程序片段转化为字符串。在前面的测试案例中，inputStr 成为 "x" 或 "x + y"

• 第 5-7 行：let result = quote(...)

  这里 quote 表达式是用于构造 Tokens 的一种表达式，它将括号内的程序片段转换为 Tokens。在 quote 的输入中，可以使用插值 $(...) 来将括号内的表达式转换为 Tokens，然后插入到 quote 构建的 Tokens 中。对于以上代码，$(inputStr) 插入 inputStr 字符串的值（包含字符串两端的引号），$(input) 插入 input，即输入的程序片段。因此，如果输入的表达式是 x + y，那么形成的Tokens为：

  print("x + y" + " = ")
  println(x + y)
  

• 第 8 行：return result

  最后，我们将构造出来的代码返回，这两行代码将被编译，运行时将输出 x + y = 5。

回顾 dprint 宏的定义，我们看到 dprint 使用 Tokens 作为入参，并使用 quote 和插值构造了另一个 Tokens 作为返回值。为了使用仓颉宏，我们需要详细了解 Tokens、quote 和插值的概念，下面我们将分别介绍它们。

Tokens 相关类型和 quote 表达式

Token 类型

宏操作的基本类型是 Tokens，代表一个程序片段。Tokens 由若干个 Token 组成，每个 Token 可以理解为用户可操作的词法单元。一个 Token 可能是一个标识符（例如变量名等）、字面量（例如整数、浮点数、字符串）、关键字或运算符。每个 Token 包含它的类型、内容和位置信息。

Token 的类型取值为 enum TokenKind 中的元素。TokenKind 的可用值详见《仓颉编程语言库 API》文档。通过提供 TokenKind 和（对于标识符和字面量）Token 的字符串，可以直接构造任何 Token。具体的构造函数如下：

Token(k: TokenKind)
Token(k: TokenKind, v: String)

下面给出一些Token构造的例子：

import std.ast.*

let tk1 = Token(TokenKind.ADD)   // '+'运算符
let tk2 = Token(TokenKind.FUNC)   // func关键字
let tk3 = Token(TokenKind.IDENTIFIER, "x")   // x标识符
let tk4 = Token(TokenKind.INTEGER_LITERAL, "3")  // 整数字面量
let tk5 = Token(TokenKind.STRING_LITERAL, "xyz")  // 字符串字面量

Tokens 类型

一个 Tokens 代表由多个 Token 组成的序列。我们可以通过 Token 数组直接构造 Tokens。下面是 3 种基本的构造 Tokens 实例的方式：

Tokens()   // 构造空列表
Tokens(tks: Array<Token>)
Tokens(tks: ArrayList<Token>)

此外，Tokens 类型支持以下函数：

• size：返回 Tokens 中包含 Token 的数量
• get(index: Int64)：获取指定下标的 Token 元素
• []：获取指定下标的 Token 元素
• +：拼接两个 Tokens，或者直接拼接 Tokens 和 Token
• dump()：打印包含的所有 Token，供调试使用
• toString()：打印 Tokens 对应的程序片段

在下面的案例中，我们使用构造函数直接构造 Token 和 Tokens，然后打印详细的调试信息：

import std.ast.*

let tks = Tokens(Array<Token>([
    Token(TokenKind.INTEGER_LITERAL, "1"),
    Token(TokenKind.ADD),
    Token(TokenKind.INTEGER_LITERAL, "2")
]))
main() {
    println(tks)
    tks.dump()
}

预期输出如下（具体的位置信息可能不同）：

1 + 2
description: integer_literal, token_id: 140, token_literal_value: 1, fileID: 1, line: 4, column: 5
description: add, token_id: 12, token_literal_value: +, fileID: 1, line: 5, column: 5
description: integer_literal, token_id: 140, token_literal_value: 2, fileID: 1, line: 6, column: 5

在 dump 信息中，包含了每个 Token 的类型（description）和值（token_literal_value），最后打印每个 Token 的位置信息。

quote 表达式和插值

在大多数情况下，直接构造和拼接 Tokens 会比较繁琐。因此，仓颉语言提供了 quote 表达式来从代码模版来构造 Tokens。之所以说是代码模版，因为在 quote 中可以使用 $(...) 来插入上下文中的表达式。插入的表达式的类型需要支持被转换为 Tokens（具体来说，实现了 ToTokens 接口）。在标准库中，以下类型实现了 ToTokens 接口：

• 所有的节点类型（节点将在语法节点中讨论）
• Token 和 Tokens 类型
• 所有基础数据类型：整数、浮点数、Bool、Rune和String
• Array<T> 和 ArrayList<T>，这里对 T 的类型有限制，并根据 T 的类型不同，输出不同的分隔符，详细请见《仓颉编程语言库 API》文档。

下面的例子展示 Array 和基础数据类型的插值。

import std.ast.*

let intList = Array<Int64>([1, 2, 3, 4, 5])
let float: Float64 = 1.0
let str: String = "Hello"
let tokens = quote(
    arr = $(intList)
    x = $(float)
    s = $(str)
)

main() {
    println(tokens)
}

输出结果是：

arr =[1, 2, 3, 4, 5]
x = 1.000000
s = "Hello"

更多插值的用法可以参考 使用 quote 插值语法节点。

语法节点

在仓颉语言的编译过程中，首先通过词法分析将代码转换成 Tokens，然后对 Tokens 进行语法解析，得到一个语法树。每个语法树的节点可能是一个表达式、声明、类型、模式等。仓颉 ast 库提供了每种节点对应的类，它们之间具有适当的继承关系。其中，主要的抽象类如下：

• Node：所有语法节点的父类
• TypeNode：所有类型节点的父类
• Expr：所有表达式节点的父类
• Decl：所有声明节点的父类
• Pattern：所有模式节点的父类

具体节点的类型众多，具体细节请参考 《仓颉编程语言库 API》文档。在下面的案例中，我们主要使用以下节点：

• BinaryExpr：二元运算表达式
• FuncDecl：函数的声明

节点的解析

通过 ast 库，基本上每种节点都可以从 Tokens 解析。有两种调用解析的方法。

使用解析表达式和声明的函数。

以下函数用于从 Tokens 解析任意的表达式或任意的声明：

• parseExpr(input: Tokens): Expr：将输入的 Tokens 解析为表达式
• parseExprFragment(input: Tokens, startFrom!: Int64 = 0): (Expr, Int64)：将输入 Tokens 的一个片段解析为表达式，片段从 startFrom 索引开始，解析可能只消耗从索引 startFrom 开始的片段的一部分，并返回第一个未被消耗的 Token 的索引（如果消耗了整个片段，返回值为 input.size）
• parseDecl(input: Tokens, astKind!: String = "")：将输入的 Tokens 解析为声明，astKind 为额外的设置，具体请见《仓颉编程语言库 API》文档。
• parseDeclFragment(input: Tokens, startFrom!: Int64 = 0): (Decl, Int64)：将输入 Tokens 的一个片段解析为声明，startFrom 参数和返回索引的含义和 parseExpr 相同。

我们通过代码案例展示这些函数的使用：

let tks1 = quote(a + b)
let tks2 = quote(a + b, x + y)
let tks3 = quote(
    func f1(x: Int64) { return x + 1 }
)
let tks4 = quote(
    func f1(x: Int64) { return x + 1 }
    func f2(x: Int64) { return x + 2 }
)

let binExpr1 = parseExpr(tks1)
println("binExpr1 is BinaryExpr: ${binExpr1 is BinaryExpr}")
let (binExpr2, mid) = parseExprFragment(tks2)
let (binExpr3, end) = parseExprFragment(tks2, startFrom: mid + 1) // 跳过逗号
println("size = ${tks2.size}, mid = ${mid}, end = ${end}")
let funcDecl1 = parseDecl(tks3)
println("funcDecl1 is FuncDecl: ${funcDecl1 is FuncDecl}")
let (funcDecl2, mid2) = parseDeclFragment(tks4)
let (funcDecl3, end2) = parseDeclFragment(tks4, startFrom: mid2)
println("size = ${tks4.size}, mid = ${mid2}, end = ${end2}")

输出结果是：

binExpr1 is BinaryExpr: true
size = 7, mid = 3, end = 7
funcDecl1 is FuncDecl: true
size = 29, mid = 15, end = 29

使用构造函数进行解析

大多数节点类型都支持 init(input: Tokens) 构造函数，将输入的 Tokens 解析为相应类型的节点，例如：

import std.ast.*

let binExpr = BinaryExpr(quote(a + b))
let funcDecl = FuncDecl(quote(func f1(x: Int64) { return x + 1 }))

如果解析失败将抛出异常。这种解析方式适用于类型已知的代码片段，解析后不需要再手动转换成具体的子类型。

节点的组成部分

从 Tokens 解析出节点之后，我们可以查看节点的组成部分。作为例子，我们列出 BinaryExpr 和 FuncDecl 的组成部分，关于其他节点的更详细的解释请见《仓颉编程语言库 API》文档。

• BinaryExpr 节点：
  • leftExpr: Expr：运算符左侧的表达式
  • op: Token：运算符
  • rightExpr: Expr：运算符右侧的表达式
• FuncDecl 节点（部分）：
  • identifier: Token：函数名
  • funcParams: ArrayList<FuncParam>：参数列表
  • declType: TypeNode：返回值类型
  • block: Block：函数体
• FuncParam节点（部分）：
  • identifier: Token：参数名
  • paramType: TypeNode：参数类型
• Block节点（部分）：
  • nodes: ArrayList<Node>：块中的表达式和声明

每个组成部分都是 public mut prop，因此可以被查看和更新。我们通过一些例子展示更新的结果。

BinaryExpr 案例

let binExpr = BinaryExpr(quote(x * y))
binExpr.leftExpr = BinaryExpr(quote(a + b))
println(binExpr.toTokens())

binExpr.op = Token(TokenKind.ADD)
println(binExpr.toTokens())

输出结果是：

(a + b) * y
a + b + y

首先，通过解析，获得 binExpr 为节点 x * y，图示如下：

    *
  /   \
 x     y

第二步，我们将左侧的节点（即 x）替换为 a + b，因此，获得的语法树如下：

      *
    /   \
   +     y
  / \
 a   b

当输出这个语法树的时候，我们必须在 a + b 周围添加括号，得到 (a + b) * y（如果输出a + b * y，含义为先做乘法，再做加法，与语法树的含义不同）。ast 库具备在输出语法树时自动添加括号的功能。

第三步，我们将语法树根部的运算符从 * 替换为 +，因此得到语法树如下：

      +
    /   \
   +     y
  / \
 a   b

这个语法树可以输出为 a + b + y，因为加法本身就是左结合的，不需要在左侧添加括号。

FuncDecl 案例

let funcDecl = FuncDecl(quote(func f1(x: Int64) { x + 1 }))
funcDecl.identifier = Token(TokenKind.IDENTIFIER, "foo")
println("Number of parameters: ${funcDecl.funcParams.size}")
funcDecl.funcParams[0].identifier = Token(TokenKind.IDENTIFIER, "a")
println("Number of nodes in body: ${funcDecl.block.nodes.size}")
let binExpr = (funcDecl.block.nodes[0] as BinaryExpr).getOrThrow()
binExpr.leftExpr = parseExpr(quote(a))
println(funcDecl.toTokens())

在这个案例中，我们首先通过解析构造出了一个 FuncDecl 节点，然后分别修改了该节点的函数名、参数名，以及函数体中表达式的一部分。输出结果是：

Number of parameters: 1
Number of nodes in body: 1
func foo(a: Int64) {
    a + 1
}

使用 quote 插值语法节点

任何 AST 节点都可以在 quote 语句中插值，部分 AST 节点的 ArrayList 列表也可以被插值（主要对应实际情况中会出现这类节点列表的情况）。插值直接通过 $(node) 表达即可，其中 node 是任意节点类型的实例。

下面，我们通过一些案例展示节点的插值。

var binExpr = BinaryExpr(quote(1 + 2))
let a = quote($(binExpr))
let b = quote($binExpr)
let c = quote($(binExpr.leftExpr))
let d = quote($binExpr.leftExpr)
println("a: ${a.toTokens()}")
println("b: ${b.toTokens()}")
println("c: ${c.toTokens()}")
println("d: ${d.toTokens()}")

输出结果是：

a: 1 + 2
b: 1 + 2
c: 1
d: 1 + 2.leftExpr

一般来说，插值运算符后面的表达式使用小括号限定作用域，例如 $(binExpr)。但是当后面只跟单个标识符的时候，小括号可省略，即可写为 $binExpr。因此，在案例中 a 和 b 都在 quote 中插入了 binExpr节点，结果为 1 + 2。然而，如果插值运算符后面的表达式更复杂，不加小括号可能造成作用域出错。例如，表达式 binExpr.leftExpr 求值为 1 + 2 的左表达式，即 1，因此 c 正确赋值为 1。但 d 中的插值被解释为 ($binExpr).leftExpr，因此结果是 1 + 2.leftExpr。为了明确插值的作用域，我们推荐在插值运算符中使用小括号。

下面的案例展示节点列表（ArrayList）的插值。

var incrs = ArrayList<Node>()
for (i in 1..=5) {
    incrs.append(parseExpr(quote(x += $(i))))
}
var foo = quote(
    func foo(n: Int64) {
        let x = n
        $(incrs)
        x
    })
println(foo)

输出结果是：

func foo(n: Int64) {
    let x = n
    x += 1
    x += 2
    x += 3
    x += 4
    x += 5
    x
}

在这个案例中，我们创建了一个节点列表 incrs，包含表达式 x += 1，...，x += 5。对 incrs 的插值将节点依次列出，在每个节点后换行。这适用于插入需要依次执行的表达式和声明的情况。

下面的案例展示在某些情况下，需要在插值周围添加括号，以保证正确性。

var binExpr1 = BinaryExpr(quote(x + y))
var binExpr2 = BinaryExpr(quote($(binExpr1) * z))       // 错误：得到 x + y * z
println("binExpr2: ${binExpr2.toTokens()}")
println("binExpr2.leftExpr: ${binExpr2.leftExpr.toTokens()}")
println("binExpr2.rightExpr: ${binExpr2.rightExpr.toTokens()}")
var binExpr3 = BinaryExpr(quote(($(binExpr1)) * z))     // 正确：得到 (x + y) * z
println("binExpr3: ${binExpr3.toTokens()}")

输出结果是：

binExpr2: x + y * z
binExpr2.leftExpr: x
binExpr2.rightExpr: y * z
binExpr3: (x + y) * z

首先，我们构建了表达式 x + y，然后将该表达式插入到模版 $(binExpr1) * z 中。这里的意图是得到一个先计算 x + y，然后再乘 z 的表达式，但是，插值的结果是 x + y * z，先做 y * z，然后再加 x。这是因为插值不会自动添加括号以保证被插入的表达式的原子性（这和前一阶介绍的 leftExpr 的替换不同）。因此，需要在 $(binExpr1) 周围添加小括号，保证得到正确的结果。

宏的实现

本章节介绍仓颉宏的定义和使用，仓颉宏可以分为非属性宏和属性宏。同时本章节还会介绍宏出现嵌套时的行为。

非属性宏

非属性宏只接受被转换的代码，不接受其他参数（属性），其定义格式如下：

import std.ast.*

public macro MacroName(args: Tokens): Tokens {
    ... // Macro body
}

宏的调用格式如下：

@MacroName(...)

宏调用使用 () 括起来。括号里面可以是任意合法 tokens，也可以是空。

当宏作用于声明时，一般可以省略括号。参考下面例子

@MacroName func name() {}        // Before a FuncDecl
@MacroName struct name {}        // Before a StructDecl
@MacroName class name {}         // Before a ClassDecl
@MacroName var a = 1             // Before a VarDecl
@MacroName enum e {}             // Before a Enum
@MacroName interface i {}        // Before a InterfaceDecl
@MacroName extend e <: i {}      // Before a ExtendDecl
@MacroName mut prop i: Int64 {}  // Before a PropDecl
@MacroName @AnotherMacro(input)  // Before a macro call

宏展开过程作用于仓颉语法树，宏展开后，编译器会继续进行后续的编译过程，因此，用户需要保证宏展开后的代码依然是合法的仓颉代码，否则可能引发编译问题。当宏用于声明时，如果省略括号，宏的输入必须是语法合法的声明，IDE 也会提供相应的语法检查和高亮。

下面是几个宏应用的典型示例。

• 示例 1

  宏定义文件 macro_definition.cj

  macro package macro_definition
  
  import std.ast.*
  
  public macro TestDef(input: Tokens): Tokens {
      println("I'm in macro body")
      return input
  }
  

  宏调用文件 macro_call.cj

  package macro_calling
  
  import macro_definition.*
  
  main(): Int64 {
      println("I'm in function body")
      let a: Int64 = @TestDef(1 + 2)
      println("a = ${a}")
      return 0
  }
  

  上述代码的编译过程可以参考宏的编译和使用。

  我们在用例中添加了打印信息，其中宏定义中的 I'm in macro body 将在编译 macro_call.cj 的期间输出，即对宏定义求值。同时，宏调用点被展开，如编译如下代码：

  let a: Int64 = @TestDef(1 + 2)
  

  编译器将宏返回的 Tokens 更新到调用点的语法树上，得到如下代码：

  let a: Int64 = 1 + 2
  

  也就是说，可执行程序中的代码实际变为了：

  main(): Int64 {
      println("I'm in function body")
      let a: Int64 = 1 + 2
      println("a = ${a}")
      return 0
  }
  

  a 经过计算得到的值为 3，在打印 a 的值时插值为 3。至此，上述程序的运行结果为：

  I'm in function body
  a = 3
  

下面看一个更有意义的用宏处理函数的例子，这个宏 ModifyFunc 宏的作用是给 MyFunc 增加 Composer 参数，并在counter++前后插入一段代码。

• 示例 2

  宏定义文件 macro_definition.cj

  // file macro_definition.cj
  macro package macro_definition
  
  import std.ast.*
  
  public macro ModifyFunc(input: Tokens): Tokens {
      println("I'm in macro body")
      let funcDecl = FuncDecl(input)
      return quote(
      func $(funcDecl.identifier)(id: Int64) {
          println("start ${id}")
          $(funcDecl.block.nodes)
          println("end")
      })
  }
  

  宏调用文件 macro_call.cj

  package macro_calling
  
  import macro_definition.*
  
  var counter = 0
  
  @ModifyFunc
  func MyFunc() {
      counter++
  }
  
  func exModifyFunc() {
      println("I'm in function body")
      MyFunc(123)
      println("MyFunc called: ${counter} times")
      return 0
  }
  

  同样的，上述两段代码分别位于不同文件中，先编译宏定义文件 macro_definition.cj，再编译宏调用 macro_call.cj 生成可执行文件。

  这个例子中，ModifyFunc 宏的输入是一个函数声明，因此可以省略括号：

  @ModifyFunc
  func MyFunc() {
      counter++
  }
  

  经过宏展开后，得到如下代码：

  func MyFunc(id: Int64) {
      println("start ${id}")
      counter++
      println("end")
  }
  

  MyFunc 会在 main 中调用，它接受的实参也是在 main 中定义的，从而形成了一段合法的仓颉程序。运行时打印如下：

  I'm in function body
  start 123
  end
  MyFunc called: 1 times
  

属性宏

和非属性宏相比，属性宏的定义会增加一个 Tokens 类型的输入，这个增加的入参可以让开发者输入额外的信息。比如开发者可能希望在不同的调用场景下使用不同的宏展开策略，则可以通过这个属性入参进行标记位设置。同时，这个属性入参也可以传入任意 Tokens，这些 Tokens 可以与被宏修饰的代码进行组合拼接等。下面是一个简单的例子：

// Macro definition with attribute
public macro Foo(attrTokens: Tokens, inputTokens: Tokens): Tokens {
    return attrTokens + inputTokens  // Concatenate attrTokens and inputTokens.
}

如上面的宏定义，属性宏的入参数量为 2，入参类型为 Tokens，在宏定义内，可以对 attrTokens 和 inputTokens 进行一系列的组合、拼接等变换操作，最后返回新的 Tokens。

带属性的宏与不带属性的宏的调用类似，属性宏调用时新增的入参 attrTokens 通过 [] 传入，其调用形式为：

// attribute macro with parentheses
var a: Int64 = @Foo[1+](2+3)

// attribute macro without parentheses
@Foo[public]
struct Data {
    var count: Int64 = 100
}

• 宏 Foo 调用，当参数是 2+3 时，与 [] 内的属性 1+ 进行拼接，经过宏展开后，得到 var a: Int64 = 1+2+3 。

• 宏 Foo 调用，当参数是 struct Data 时，与 [] 内的属性 public 进行拼接，经过宏展开后，得到

  public struct Data {
      var count: Int64 = 100
  }
  

关于属性宏，需要注意以下几点：

• 带属性的宏，与不带属性的宏相比，能修饰的 AST 是相同的，可以理解为带属性的宏对可传入参数做了增强。

• 要求属性宏调用时，[] 内中括号匹配，且可以为空。中括号内只允许对中括号的转义 \[ 或 \]，该转义中括号不计入匹配规则，其他字符会被作为 Token，不能进行转义。

  @Foo[[miss one](2+3) // Illegal
  @Foo[[matched]](2+3) // Legal
  @Foo[](2+3)          // Legal, empty in []
  @Foo[\[](2+3)        // Legal, use escape for [
  @Foo[\(](2+3)        // Illegal, only [ and ] allowed in []
  

• 宏的定义和调用的类型要保持一致：如果宏定义有两个入参，即为属性宏定义，调用时必须加上 []，且内容可以为空；如果宏定义有一个入参，即为非属性宏定义，调用时不能使用 []。

嵌套宏

仓颉语言不支持宏定义的嵌套；有条件地支持在宏定义和宏调用中嵌套宏调用。

宏定义中嵌套宏调用

下面是一个宏定义中包含其他宏调用的例子。

宏包 pkg1 中定义 GetIdent 宏：

macro package pkg1

import std.ast.*

public macro GetIdent(attr:Tokens, input:Tokens):Tokens {
    return quote(
        let decl = (parseDecl(input) as VarDecl).getOrThrow()
        let name = decl.identifier.value
        let size = name.size - 1
        let $(attr) = Token(TokenKind.IDENTIFIER, name[0..size])
    )
}

宏包 pkg2 中定义 Prop 宏，其中嵌套了 GetIdent 宏的调用：

macro package pkg2

import std.ast.*
import pkg1.*

public macro Prop(input:Tokens):Tokens {
    let v = parseDecl(input)
    @GetIdent[ident](input)
    return quote(
        $(input)
        public prop $(ident): $(decl.declType) {
            get() {
                this.$(v.identifier)
            }
        }
    )
}

宏调用包 pkg3 中调用 Prop 宏：

package pkg3

import pkg2.*
class A {
    @Prop
    private let a_: Int64 = 1
}

main() {
    let b = A()
    println("${b.a}")
}

注意，按照宏定义必须比宏调用点先编译的约束，上述 3 个文件的编译顺序必须是：pkg1 -> pkg2 -> pkg3。pkg2 中的 Prop 宏定义：

public macro Prop(input:Tokens):Tokens {
    let v = parseDecl(input)
    @GetIdent[ident](input)
    return quote(
        $(input)
        public prop $(ident): $(decl.declType) {
            get() {
                this.$(v.identifier)
            }
        }
    )
}

会先被展开成如下代码，再进行编译。

public macro Prop(input: Tokens): Tokens {
    let v = parseDecl(input)

    let decl = (parseDecl(input) as VarDecl).getOrThrow()
    let name = decl.identifier.value
    let size = name.size - 1
    let ident = Token(TokenKind.IDENTIFIER, name[0 .. size])

    return quote(
        $(input)
        public prop $(ident): $(decl.declType) {
            get() {
                this.$(v.identifier)
            }
        }
    )
}

宏调用中嵌套宏调用

嵌套宏的常见场景，是宏修饰的代码块中，出现了宏调用。一个具体的例子如下：

pkg1 包中定义 Foo 和 Bar 宏：

macro package pkg1

import std.ast.*

public macro Foo(input: Tokens): Tokens {
    return input
}

public macro Bar(input: Tokens): Tokens {
    return input
}

pkg2 包中定义 AddToMul 宏：

macro package pkg2

import std.ast.*

public macro AddToMul(inputTokens: Tokens): Tokens {
    var expr: BinaryExpr = match (parseExpr(inputTokens) as BinaryExpr) {
        case Some(v) => v
        case None => throw Exception()
    }
    var op0: Expr = expr.leftExpr
    var op1: Expr = expr.rightExpr
    return quote(($(op0)) * ($(op1)))
}

pkg3 包中使用上面定义的三个宏：

package pkg3

import pkg1.*
import pkg2.*
@Foo
struct Data {
    let a = 2
    let b = @AddToMul(2+3)

    @Bar
    public func getA() {
        return a
    }

    public func getB() {
        return b
    }
}

main(): Int64 {
    let data = Data()
    var a = data.getA() // a = 2
    var b = data.getB() // b = 6
    println("a: ${a}, b: ${b}")
    return 0
}

如上代码所示，宏 Foo 修饰了 struct Data，而在 struct Data 内，出现了宏调用 AddToMul 和 Bar。这种嵌套场景下，代码变换的规则是：将嵌套内层的宏 (AddToMul 和 Bar) 展开后，再去展开外层的宏 (Foo)。允许出现多层宏嵌套，代码变换的规则总是由内向外去依次展开宏。

嵌套宏可以出现在带括号和不带括号的宏调用中，二者可以组合，但用户需要保证没有歧义，且明确宏的展开顺序：

var a = @Foo(@Foo1(2 * 3)+@Foo2(1 + 3))  // Foo1, Foo2 have to be defined.

@Foo1 // Foo2 expands first, then Foo1 expands.
@Foo2[attr: struct] // Attribute macro can be used in nested macro.
struct Data{
    @Foo3 @Foo4[123] var a = @Bar1(@Bar2(2 + 3) + 3)  // Bar2, Bar1, Foo4, Foo3 expands in order.
    public func getA() {
        return @Foo(a + 2)
    }
}

嵌套宏之间的消息传递

这里指的是宏调用的嵌套。

内层宏可以调用库函数 assertParentContext 来保证内层宏调用一定嵌套在特定的外层宏调用中。如果内层宏调用这个函数时没有嵌套在给定的外层宏调用中，该函数将抛出一个错误。库函数 InsideParentContext 同样用于检查内层宏调用是否嵌套在特定的外层宏调用中，该函数返回一个布尔值。下面是一个简单的例子。

宏定义如下：

public macro Outer(input: Tokens): Tokens {
    return input
}

public macro Inner(input: Tokens): Tokens {
    assertParentContext("Outer")
    return input
}

宏调用如下：

@Outer var a = 0
@Inner var b = 0 // Error, The macro call 'Inner' should with the surround code contains a call 'Outer'.

如上代码所示，Inner 宏在定义时使用了 assertParentContext 函数用于检查其在调用阶段是否位于 Outer 宏中，在代码示例的宏调用场景下，由于 Outer 和 Inner 在调用时不存在这样的嵌套关系，因此编译器将报告一个错误。

内层宏也可以通过发送键/值对的方式与外层宏通信。当内层宏执行时，通过调用标准库函数 setItem 向外层宏发送信息；随后，当外层宏执行时，调用标准库函数 getChildMessages 接收每一个内层宏发送的信息（一组键/值对映射）。下面是一个简单的例子。

宏定义如下：

macro package define

import std.ast.*

public macro Outer(input: Tokens): Tokens {
    let messages = getChildMessages("Inner")

    let getTotalFunc = quote(public func getCnt() {
                       )
    for (m in messages) {
        let identName = m.getString("identifierName")
        // let value = m.getString("key")            // 接收多组消息
        getTotalFunc.append(Token(TokenKind.IDENTIFIER, identName))
        getTotalFunc.append(quote(+))
    }
    getTotalFunc.append(quote(0))
    getTotalFunc.append(quote(}))
    let funcDecl = parseDecl(getTotalFunc)

    let decl = (parseDecl(input) as ClassDecl).getOrThrow()
    decl.body.decls.append(funcDecl)
    return decl.toTokens()

}

public macro Inner(input: Tokens): Tokens {
    assertParentContext("Outer")
    let decl = parseDecl(input)
    setItem("identifierName", decl.identifier.value)
    // setItem("key", "value")                      // 可以通过不同的key值传递多组消息
    return input
}

宏调用如下：

import define.*

@Outer
class Demo {
    @Inner var state = 1
    @Inner var cnt = 42
}

main(): Int64 {
    let d = Demo()
    println("${d.getCnt()}")
    return 0
}

在上面的代码中，Outer 接收两个 Inner 宏发送来的变量名，自动为类添加如下内容：

public func getCnt() {
    state + cnt + 0
}

具体流程为：内层宏 Inner 通过 setItem 向外层宏发送信息；Outer 宏通过 getChildMessages 函数接收到 Inner 发送的一组信息对象（Outer 中可以调用多次 Inner）；最后通过该信息对象的 getString 函数接收对应的值。

编译、报错与调试

宏的编译和使用

当前编译器约束宏的定义与宏的调用不允许在同一包里。宏包必须首先被编译，然后再编译宏调用的包。在宏调用的包中，不允许出现宏的定义。由于宏需在包中导出给另一个包使用，因此编译器约束宏定义必须使用 public 修饰。

下面介绍一个简单的例子。

源码目录结构如下：

// Directory layout.
src
`-- macros
      |-- m.cj

`-- demo.cj

宏定义放在 _macros_子目录下：

// macros/m.cj
// In this file, we define the macro Inner, Outer.
macro package define
import std.ast.*

public macro Inner(input: Tokens) {
    return input
}

public macro Outer(input: Tokens) {
    return input
}

宏调用代码如下：

// demo.cj
import define.*
@Outer
class Demo {
    @Inner var state = 1
    @Inner var cnt = 42
}

main() {
    println("test macro")
    0
}

以下为 Linux 平台的编译命令（具体编译选项会随着 cjc 更新而演进，以最新 cjc 的编译选项为准）：

# 当前目录: src

# 先编译宏定义文件在当前目录产生默认的动态库文件（允许指定动态库的路径，但不能指定动态库的名字）
cjc macros/m.cj --compile-macro

# 编译使用宏的文件，宏替换完成，产生可执行文件
cjc demo.cj -o demo

# 运行可执行文件
./demo

在 linux 平台上，将生成用于包管理的 macro_define.cjo 和实际的动态库文件。

若在 Windows 平台：

# 当前目录: src

# 先编译宏定义文件在当前目录产生默认的动态库文件（允许指定动态库的路径，但不能指定动态库的名字）
cjc macros/m.cj --compile-macro

# 编译使用宏的文件，宏替换完成，产生可执行文件
cjc demo.cj -o demo.exe

说明：

宏替换过程依赖仓颉 runtime ，宏替换过程中仓颉 runtime 的初始化配置采用宏提供的默认配置，配置参数支持使用仓颉 runtime 运维日志进行查询，其中 cjHeapSize 与 cjStackSize 支持用户修改，其余暂不支持，仓颉 runtime 初始化配置可参见runtime 初始化可选配置章节。

并行宏展开

可以在编译宏调用文件时添加 --parallel-macro-expansion 选项，启用并行宏展开的能力。编译器会自动分析宏调用之间的依赖关系，无依赖关系的宏调用可以并行执行，如上述例子中的两个 @Inner 就可以并行展开，如此可以缩短整体编译时间。

注意：

如果宏函数依赖一些全局变量，使用并行宏展开会存在风险。

macro package define
import std.ast.*
import std.collection.*

var Counts = HashMap<String, Int64>()

public macro Inner(input: Tokens) {
    for (t in input) {
        if (t.value.size == 0) {
            continue
        }
        // 统计所有有效token value的出现次数
        if (!Counts.contains(t.value)) {
            Counts[t.value] = 0
        }
        Counts[t.value] = Counts[t.value] + 1
    }
    return input
}

public macro B(input: Tokens) {
    return input
}

参考上述代码，如果 @Inner 的宏调用出现在多处，并且启用了并行宏展开选项，则访问全局变量 Counts 就可能存在冲突，导致最后获取的结果不正确。

建议不要在宏函数中使用全局变量，如果必须使用，要么关闭并行宏展开选项，或者可以通过仓颉线程锁对全局变量进行保护。

diagReport 报错机制

仓颉 ast 包提供了自定义报错接口 diagReport。方便定义宏的用户，在解析传入 tokens 时，对错误 tokens 内容进行自定义报错。

自定义报错接口提供同原生编译器报错一样的输出格式，允许用户报 warning 和 error 两类错误提示信息。

diagReport 的函数原型如下：

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

其参数含义如下：

• level: 报错信息等级
• tokens: 报错信息中所引用源码内容对应的 tokens
• message: 报错的主信息
• hint: 辅助提示信息

参考如下使用示例。

宏定义文件：

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

编译宏调用文件过程中，会出现如下报错信息：

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.

使用 --debug-macro 输出宏展开结果

借助宏在编译期做代码生成时，如果发生错误，处理起来十分棘手，这是开发者经常遇到但一般很难定位的问题。这是因为，开发者写的源码，经过宏的变换后变成了不同的代码片段。编译器抛出的错误信息是基于宏最终生成的代码进行提示的，但这些代码在开发者的源码中没有体现。

为了解决这个问题，仓颉宏提供 debug 模式，在这个模式下，开发者可以从编译器为宏生成的 debug 文件中看到完整的宏展开后的代码，如下所示。

宏定义文件：

macro package define

import std.ast.*

public macro Outer(input: Tokens): Tokens {
    let messages = getChildMessages("Inner")

    let getTotalFunc = quote(public func getCnt() {
                       )
    for (m in messages) {
        let identName = m.getString("identifierName")
        getTotalFunc.append(Token(TokenKind.IDENTIFIER, identName))
        getTotalFunc.append(quote(+))
    }
    getTotalFunc.append(quote(0))
    getTotalFunc.append(quote(}))
    let funcDecl = parseDecl(getTotalFunc)

    let decl = (parseDecl(input) as ClassDecl).getOrThrow()
    decl.body.decls.append(funcDecl)
    return decl.toTokens()

}

public macro Inner(input: Tokens): Tokens {
    assertParentContext("Outer")
    let decl = parseDecl(input)
    setItem("identifierName", decl.identifier.value)
    return input
}

宏调用文件 demo.cj：

import define.*

@Outer
class Demo {
    @Inner var state = 1
    @Inner var cnt = 42
}

main(): Int64 {
    let d = Demo()
    println("${d.getCnt()}")
    return 0
}

在编译使用宏的文件时，在选项中，增加 --debug-macro，即使用仓颉宏的 debug 模式。

cjc --debug-macro demo.cj

在 debug 模式下，会生成临时文件 demo.cj.macrocall，对应宏展开的部分如下：

// demo.cj.macrocall
/* ===== Emitted by MacroCall @Outer in demo.cj:3:1 ===== */
/* 3.1 */class Demo {
/* 3.2 */    var state = 1
/* 3.3 */    var cnt = 42
/* 3.4 */    public func getCnt() {
/* 3.5 */        state + cnt + 0
/* 3.6 */    }
/* 3.7 */}
/* 3.8 */
/* ===== End of the Emit ===== */

如果宏展开后的代码有语义错误，则编译器的错误信息会溯源到宏展开后代码的具体行列号。仓颉宏的 debug 模式有以下注意事项：

• 宏的 debug 模式会重排源码的行列号信息，不适用于某些特殊的换行场景。比如

  // before expansion
  @M{} - 2 // macro M return 2
  
  // after expansion
  // ===== Emmitted my Macro M at line 1 ===
  2
  // ===== End of the Emit =====
  - 2
  

  这些因换行符导致语义改变的情形，不应使用 debug 模式。

• 不支持宏调用在宏定义内的调试，会编译报错。

  public macro M(input: Tokens) {
      let a = @M2(1+2) // M2 is in macro M, not suitable for debug mode.
      return input + quote($a)
  }
  

• 不支持带括号宏的调试。

  // main.cj
  
  main() {
      // For macro with parenthesis, newline introduced by debug will change the semantics
      // of the expression, so it is not suitable for debug mode.
      let t = @M(1+2)
      0
  }
  

宏包定义和导入

仓颉宏的定义需要放在由 macro package 声明的包中，被 macro package 限定的包仅允许宏定义对外可见，其他声明包内可见。

说明：

重导出的声明也允许对外可见，关于包管理和重导出的相关概念，请参见包的导入章节。

// file define.cj
macro package define         // 编译 define.cjo 携带 macro 属性
import std.ast.*

public func A() {}          // Error, 宏包不允许定义外部可见的非宏定义，此处需报错

public macro M(input: Tokens): Tokens { // macro M 外部可见
    return input
}

需要特殊说明的是，在 macro package 中允许其它 macro package 和非 macro package 符号被重导出，在非 macro package 中仅允许非 macro package 符号被重导出。

参考如下示例：

• 在宏包 A 中定义宏 M1

  macro package A
  import std.ast.*
  
  public macro M1(input: Tokens): Tokens {
      return input
  }
  

  编译命令如下：

  cjc A.cj --compile-macro
  

• 在非宏包 B 中定义一个 public 函数 F1。注意在非 macro package 中无法重导出 macro package 的符号

  package B
  // public import A.* // Error, it is not allowed to re-export a macro package in a package.
  
  public func F1(input: Int64): Int64 {
      return input
  }
  

  编译命令如下，这里选择使用 --output-type 选项将 B 包编译成到动态库，关于 cjc 编译选项介绍可以参考cjc 编译选项章节。

  cjc B.cj --output-type=dylib -o libB.so
  

• 在宏包 C 中定义宏 M2，依赖了 A 包和 B 包的内容。可以看到 macro package 中可以重导出 macro package 和非 macro package 的符号

  macro package C
  public import A.* // correct: macro package is allowed to re-export in a macro package.
  public import B.* // correct: non-macro package is also allowed to re-export in a macro package.
  import std.ast.*
  
  public macro M2(input: Tokens): Tokens {
      return @M1(input) + Token(TokenKind.NL) + quote(F1(1))
  }
  

  编译命令如下，注意这里需要显式链接 B 包动态库：

  cjc C.cj --compile-macro -L. -lB
  

• 在 main.cj 中使用 M2 宏

  import C.*
  
  main() {
      @M2(let a = 1)
  }
  

  编译命令如下：

  cjc main.cj -o main -L. -lB
  

  main.cj中 M2 宏展开后的结果如下：

  import C.*
  
  main() {
      let a = 1
      F1(1)
  }
  

可以看到 main.cj 中出现了来自于 B 包的符号 F1。宏的编写者可以在 C 包中重导出 B 包里的符号，这样宏的使用者仅需导入宏包，就可以正确的编译宏展开后的代码。如果在 main.cj 中仅使用 import C.M2 导入宏符号，则会报 undeclared identifier 'F1' 的错误信息。

内置编译标记

仓颉语言提供了一些预定义的编译标记，可以通过这些编译标记控制仓颉编译器的编译行为。

源码位置

仓颉提供了几个内置编译标记，用于在编译时获取源代码的位置。

• @sourcePackage() 展开后是一个 String 类型的字面量，内容为当前宏所在的源码的包名
• @sourceFile() 展开后是一个 String 类型的字面量，内容为当前宏所在的源码的文件名
• @sourceLine() 展开后是一个 Int64 类型的字面量，内容为当前宏所在的源码的代码行

这几个编译标记可以在任意表达式内部使用，只要能符合类型检查规则即可。示例如下：

func test1() {
    let s: String = @sourceFile()  // The value of `s` is the current source file name
}

func test2(n!: Int64 = @sourceLine()) { /* at line 5 */
    // The default value of `n` is the source file line number of the definition of `test2`
    println(n) // print 5
}

条件编译

条件编译使用 @When 标记，是一种在程序代码中根据特定条件选择性地编译不同代码段的技术。条件编译的作用主要体现在以下几个方面：

• 平台适应：支持根据当前的编译环境选择性地编译代码，用于实现跨平台的兼容性。
• 功能选择：支持根据不同的需求选择性地启用或禁用某些功能，用于实现功能的灵活配置。例如，选择性地编译包含或排除某些功能的代码。
• 调试支持：支持调试模式下编译相关代码，用于提高程序的性能和安全性。例如，在调试模式下编译调试信息或记录日志相关的代码，而在发布版本中将其排除。
• 性能优化：支持根据预定义的条件选择性地编译代码，用于提高程序的性能。

关于条件编译的具体内容，可以参考条件编译章节，这里不再额外展开。

@FastNative

为了提升与 C 语言互操作的性能，仓颉提供 @FastNative 标记用于优化对 C 函数的调用。值得注意的是 @FastNative 只能用于 foreign 声明的函数。

使用示例如下

@FastNative
foreign func strlen(str: CPointer<UInt8>): UIntNative

开发者在使用 @FastNative 修饰 foreign 函数时，应确保对应的 C 函数满足以下两点要求：

1. 函数的整体执行时间不宜太长。例如:不允许函数内部存在很大的循环；不允许函数内部产生阻塞行为，如，调用 sleep、wait 等函数。
2. 函数内部不能调用仓颉方法。

实用案例

快速幂的计算

我们通过一个简单的例子展示使用宏进行编译期求值，生成优化代码的应用。在计算幂 n ^ e 的时候，如果 e 是一个（比较大的）整数，可以通过重复取平方（而不是迭代相乘）的方式加速计算。这个算法可以直接使用 while 循环实现，例如：

func power(n: Int64, e: Int64) {
    var result = 1
    var vn = n
    var ve = e
    while (ve > 0) {
        if (ve % 2 == 1) {
            result *= vn
        }
        ve /= 2
        if (ve > 0) {
            vn *= vn
        }
    }
    result
}

然而，这个实现需要每次对 e 的值进行分析，在循环和条件判断中多次对 ve 进行判断和更新。此外，实现只支持 n 的类型为Int64的情况，如果要支持其他类型的 n，还要处理如何表达 result = 1 的问题。如果我们预先知道 e 的具体值，可以将这个代码写的更简单。例如，如果知道 e 的值为 10，我们可以展开整个循环如下：

func power_10(n: Int64) {
    var vn = n
    vn *= vn         // vn = n ^ 2
    var result = vn  // result = n ^ 2
    vn *= vn         // vn = n ^ 4
    vn *= vn         // vn = n ^ 8
    result *= vn     // result = n ^ 10
    result
}

当然，手动编写这些代码非常繁琐，我们希望在给定 e 的值之后，自动将这些代码生成出来。宏允许我们做到这一点。我们先看使用案例：

public func power_10(n: Int64) {
    @power[10](n)
}

这个宏展开的代码是（根据.macrocall文件）：

public func power_10(n: Int64) {
    /* ===== Emitted by MacroCall @power in main.cj:20:5 ===== */
    /* 20.1 */var _power_vn = n
    /* 20.2 */_power_vn *= _power_vn
    /* 20.3 */var _power_result = _power_vn
    /* 20.4 */_power_vn *= _power_vn
    /* 20.5 */_power_vn *= _power_vn
    /* 20.6 */_power_result *= _power_vn
    /* 20.7 */_power_result
/* ===== End of the Emit ===== */
}

下面，我们看宏 @power 的实现。

macro package define

import std.ast.*
import std.convert.*

public macro power(attrib: Tokens, input: Tokens) {
    let attribExpr = parseExpr(attrib)
    if (let Some(litExpr) <- attribExpr as LitConstExpr) {
        let lit = litExpr.literal
        if (lit.kind != TokenKind.INTEGER_LITERAL) {
            diagReport(DiagReportLevel.ERROR, attrib,
                       "Attribute must be integer literal",
                       "Expected integer literal")
        }
        var n = Int64.parse(lit.value)
        var result = quote(var _power_vn = $(input)
        )
        var flag = false
        while (n > 0) {
            if (n % 2 == 1) {
                if (!flag) {
                    result += quote(var _power_result = _power_vn
                    )
                    flag = true
                } else {
                    result += quote(_power_result *= _power_vn
                    )
                }
            }
            n /= 2
            if (n > 0) {
                result += quote(_power_vn *= _power_vn
                )
            }
        }
        result += quote(_power_result)
        return result
    } else {
        diagReport(DiagReportLevel.ERROR, attrib,
                   "Attribute must be integer literal",
                   "Expected integer literal")
    }
    return input
}

这段代码的解释如下：

• 首先，确认输入的属性 attrib 是一个整数字面量，否则通过 diagReport 报错。将这个字面量解析为整数 n。
• 设 result 为当前积累的输出代码，首先添加 var _power_vn 的声明。这里为了避免变量名冲突，我们使用不易造成冲突的名字 _power_vn。
• 下面进入 while 循环，布尔变量 flag 表示 var _power_result 是否已经被初始化。其余的代码结构和之前展示的 power 函数的实现类似，但区别是我们使用 while 循环和 if 判断在编译时决定生成的代码是什么，而不是在运行时做这些判断。最后生成由 _power_result *= _power_vn 和 _power_vn *= _power_vn 适当组合的代码。
• 最后添加返回 _power_result 的代码。

将这段代码放到 macros/power.cj 文件中，并在 main.cj 添加如下测试：

public func power_10(n: Int64) {
    @power[10](n)
}

main() {
    let a = 3
    println(power_10(a))
}

输出结果为：

59049

Memoize 宏

Memoize（记忆化）是动态规划算法的常用手段。它将已经计算过的子问题的结果存储起来，当同一个子问题再次出现时，可以直接查询表来获取结果，从而避免重复的计算，提高算法的效率。

通常 Memoize 的使用需要开发者手动实现存储和提取的功能。通过宏，我们可以自动化这一过程。首先，让我们先看一下宏使用的效果：

@Memoize[true]
func fib(n: Int64): Int64 {
    if (n == 0 || n == 1) {
        return n
    }
    return fib(n - 1) + fib(n - 2)
}

main() {
    let start = DateTime.now()
    let f35 = fib(35)
    let end = DateTime.now()
    println("fib(35): ${f35}")
    println("execution time: ${(end - start).toMicroseconds()} us")
}

在以上代码中，fib 函数采用简单的递归方式实现。如果没有 @Memoize[true] 标注，这个函数的运行时间将随着 n 指数增长。例如，如果在前面的代码中去掉 @Memoize[true] 这一行，或者把 true 改为 false，则 main 函数的运行结果为：

fib(35): 9227465
execution time: 199500 us

恢复 @Memoize[true]，运行结果为：

fib(35): 9227465
execution time: 78 us

相同的答案和大幅缩短的计算时间表明，@Memoize 的使用确实实现了记忆化。

现在让我们理解 @Memoize 的原理。首先，展示对以上 fib 函数进行宏展开的结果（来自 .macrocall 文件，但是为了提高可读性整理了格式）。

import std.collection.*

var _memoize_fib_map = HashMap<Int64, Int64>()

func fib(n: Int64): Int64 {
    if (_memoize_fib_map.contains(n)) {
        return _memoize_fib_map.get(n).getOrThrow()
    }

    let _memoize_eval_result = { =>
        if (n == 0 || n == 1) {
            return n
        }

        return fib(n - 1) + fib(n - 2)
    }()
    _memoize_fib_map.put(n, _memoize_eval_result)
    return _memoize_eval_result
}

上述代码的执行流程如下：

• 首先，定义 _memoize_fib_map 为一个从 Int64 到 Int64 的哈希表，这里第一个 Int64 对应 fib 的唯一参数的类型，第二个 Int64 对应 fib 返回值的类型。
• 其次，在函数体中，检查入参是否在 _memoize_fib_map 中，如果是则立即反馈哈希表中存储的值。否则，使用 fib 原来的函数体得到计算结果。这里使用了（不带参数的）匿名函数使 fib 的函数体不需要任何改变，并且能够处理任何从 fib 函数退出的方式（包括中间的 return，返回最后一个表达式等）。
• 最后，把计算结果存储到 _memoize_fib_map 中，然后将计算结果返回。

有了这样一个“模版”之后，下面宏的实现就不难理解了。我们给出完整的代码如下。

public macro Memoize(attrib: Tokens, input: Tokens) {
    if (attrib.size != 1 || attrib[0].kind != TokenKind.BOOL_LITERAL) {
        diagReport(DiagReportLevel.ERROR, attrib,
                   "Attribute must be a boolean literal (true or false)",
                   "Expected boolean literal (true or false) here")
    }

    let memoized = (attrib[0].value == "true")
    if (!memoized) {
        return input
    }

    let fd = FuncDecl(input)
    if (fd.funcParams.size != 1) {
        diagReport(DiagReportLevel.ERROR, fd.lParen + fd.funcParams.toTokens() + fd.rParen,
                   "Input function to memoize should take exactly one argument",
                   "Expect only one argument here")
    }

    let memoMap = Token(TokenKind.IDENTIFIER, "_memoize_" + fd.identifier.value + "_map")
    let arg1 = fd.funcParams[0]

    return quote(
        var $(memoMap) = HashMap<$(arg1.paramType), $(fd.declType)>()

        func $(fd.identifier)($(arg1)): $(fd.declType) {
            if ($(memoMap).contains($(arg1.identifier))) {
                return $(memoMap).get($(arg1.identifier)).getOrThrow()
            }

            let _memoize_eval_result = { => $(fd.block.nodes) }()
            $(memoMap).put($(arg1.identifier), _memoize_eval_result)
            return _memoize_eval_result
        }
    )
}

首先，对属性和输入做合法性检查。属性必须是布尔字面量，如果为 false 则直接返回输入。否则，检查输入必须能够解析为函数声明（FuncDecl），并且必须包含正好一个参数。下面，产生哈希表的变量，取不容易造成冲突的变量名。最后，通过 quote 模版生成返回的代码，其中用到哈希表的变量名，以及唯一参数的名称、类型和输入函数的返回类型。

一个 dprint 宏的扩展

本节一开始使用了一个打印表达式的宏作为案例，但这个宏一次只能接受一个表达式。我们希望扩展这个宏，使其能够接受多个表达式，由逗号分开。我们展示如何使用 parseExprFragment 来实现这个功能。

宏的实现如下：

public macro dprint2(input: Tokens) {
    let exprs = ArrayList<Expr>()
    var index: Int64 = 0
    while (true) {
        let (expr, nextIndex) = parseExprFragment(input, startFrom: index)
        exprs.append(expr)
        if (nextIndex == input.size) {
            break
        }
        if (input[nextIndex].kind != TokenKind.COMMA) {
            diagReport(DiagReportLevel.ERROR, input[nextIndex..nextIndex+1],
                       "Input must be a comma-separated list of expressions",
                       "Expected comma")
        }
        index = nextIndex + 1  // 跳过逗号
    }
    let result = quote()
    for (expr in exprs) {
        result.append(quote(
            print($(expr.toTokens().toString()) + " = ")
            println($(expr))
        ))
    }
    return result
}

使用案例：

let x = 3
let y = 2
@dprint2(x, y, x + y)

输出结果为：

x = 3
y = 2
x + y = 5

在宏的实现中，使用 while 循环从索引 0 开始依次解析每个表达式。变量 index 保存当前解析的位置。每次调用 parseExprFragment 时，从当前位置开始，并返回解析后的位置（以及解析得到的表达式）。如果解析后的位置到达了输入的结尾，则退出循环。否则检查到达的位置是一个括号，如果不是括号，报错并退出，如果是括号，跳过这个括号并开始下一轮的解析。在得到表达式的列表后，依次输出每个表达式。

一个简单的 DSL

在这个案例中，我们展示如何使用宏实现一个简单的 DSL（Domain Specific Language，领域特定语言）。LINQ（Language Integrated Query，语言集成查询）是微软 .NET 框架的一个组成部分，它提供了一种统一的数据查询语法，允许开发者使用类似 SQL 的查询语句来操作各种数据源。在这里，我们仅展示一个最简单的 LINQ 语法的支持。

我们希望支持的语法为：

from <variable> in <list> where <condition> select <expression>

其中，variable 是一个标识符，list、condition 和 expression 都是表达式。因此，实现宏的策略是先后提取标识符和表达式，同时检查中间的关键字是正确的。最后，生成由提取部分组成的查询结果。

宏的实现如下：

public macro linq(input: Tokens) {
    let syntaxMsg = "Syntax is \"from <attrib> in <table> where <cond> select <expr>\""
    if (input.size == 0 || input[0].value != "from") {
        diagReport(DiagReportLevel.ERROR, input[0..1], syntaxMsg,
                   "Expected keyword \"from\" here.")
    }
    if (input.size <= 1 || input[1].kind != TokenKind.IDENTIFIER) {
        diagReport(DiagReportLevel.ERROR, input[1..2], syntaxMsg,
                   "Expected identifier here.")
    }
    let attribute = input[1]
    if (input.size <= 2 || input[2].value != "in") {
        diagReport(DiagReportLevel.ERROR, input[2..3], syntaxMsg,
                   "Expected keyword \"in\" here.")
    }
    var index: Int64 = 3
    let (table, nextIndex) = parseExprFragment(input, startFrom: index)
    if (nextIndex == input.size || input[nextIndex].value != "where") {
        diagReport(DiagReportLevel.ERROR, input[nextIndex..nextIndex+1], syntaxMsg,
                   "Expected keyword \"where\" here.")
    }
    index = nextIndex + 1  // 跳过where
    let (cond, nextIndex2) = parseExprFragment(input, startFrom: index)
    if (nextIndex2 == input.size || input[nextIndex2].value != "select") {
        diagReport(DiagReportLevel.ERROR, input[nextIndex2..nextIndex2+1], syntaxMsg,
                   "Expected keyword \"select\" here.")
    }
    index = nextIndex2 + 1  // 跳过select
    let (expr, nextIndex3) = parseExprFragment(input, startFrom: index)

    return quote(
        for ($(attribute) in $(table)) {
            if ($(cond)) {
                println($(expr))
            }
        }
    )
}

使用案例：

@linq(from x in 1..=10 where x % 2 == 1 select x * x)

这个例子从 1, 2, ... 10 列表中筛选出奇数，然后返回所有奇数的平方。输出结果为：

1
9
25
49
81

可以看到，宏的实现的很大部分用于解析并校验输入的 tokens，这对宏的可用性至关重要。实际的 LINQ 语言（以及大多数 DSL）的语法更加复杂，需要一整套解析的机制，通过识别不同的关键字或连接符来决定下一步解析的内容。

动态特性

本章我们来介绍 Cangjie 的动态特性，应用动态特性开发者能够更为优雅的实现一些功能。仓颉的动态特性主要包含反射、动态加载。

仓颉反射基本介绍

反射指程序可以访问、检测和修改它本身状态或行为的一种机制。

反射这一动态特性有以下的优点：

• 提高了程序的灵活性和扩展性。

• 程序能够在运行时获悉各种对象的类型，对其成员进行枚举、调用等操作。

• 允许在运行时创建新类型，无需提前硬编码。

但使用反射调用，其性能通常低于直接调用，因此反射机制主要应用于对灵活性和拓展性要求很高的系统框架上。

如何获得 TypeInfo

对于仓颉的反射特性，我们需要知道 TypeInfo 这一类型，这个核心类型中记录任意类型的类型信息，并且定义了方法用于获取类型信息、设置值等。当然为了便于用户操作我们还提供了 ClassTypeInfo、PrimitiveTypeInfo、ParameterInfo 等一系列的信息类型。

我们可以使用三种静态的 of 方法来生成 TypeInfo 信息类。

public class TypeInfo {
    public static func of(a: Any): TypeInfo
    public static func of(a: Object): ClassTypeInfo
    public static func of<T>(): TypeInfo
}

当采用入参为 Any 和 Object 类型的 of 函数，输出为该实例的运行时类型信息，采用泛型参数的 of 函数则会返回传入参数的静态类型信息。两种方法产生的信息完全相同，但不保证一定对应同一对象。

例如我们可以用反射来获取一个自定义类型的类型信息。

import std.reflect.*

class Foo {}

main() {
    let a: Foo = Foo()
    let info: TypeInfo = TypeInfo.of(a)
    let info2: TypeInfo = TypeInfo.of<Foo>()
    println(info)
    println(info2)
}

编译并执行上面的代码，会输出：

default.Foo
default.Foo

此外，为配合动态加载使用，TypeInfo 还提供了静态函数 get，该接口可通过传入的类型名称获取 TypeInfo。

public class TypeInfo {
    public static func get(qualifiedName: String): TypeInfo
}

请注意，传入参数需要符合 module/package.type 的完全限定模式规则。对于编译器预导入的类型，包含 core 包中的类型和编译器内置类型，例如 primitive type、Option、Iterable 等，查找的字符串需要直接使用其类型名，不能带包名和模块名前缀。当运行时无法查询到对应类型的实例，则会抛出 InfoNotFoundException。

let t1: TypeInfo = TypeInfo.get("Int64")
let t1: TypeInfo = TypeInfo.get("default.Foo")
let t2: TypeInfo = TypeInfo.get("std/socket.TcpSocket")
let t3: TypeInfo = TypeInfo.get("net/http.ServerBuilder")

采用这种方式时无法获取一个未实例化的泛型类型。

import std.collection.*
import std.reflect.*

class A<T> {
    A(public let t: T) {}
}

class B<T> {
    B(public let t: T) {}
}

main() {
    let aInfo: TypeInfo = TypeInfo.get("default.A<Int64>")// Error,`default.A<Int64>` is not instantiated，will throw InfoNotFoundException
    let b: B<Int64> = B<Int64>(1)
    let bInfo: TypeInfo = TypeInfo.get("default.B<Int64>")// Ok `default.B<Int64>` has been instantiated.
}

如何使用反射访问成员

在获取到对应的类型信息类即 TypeInfo，我们便可以通过其相应接口访问对应类的实例成员以及静态成员。此外 TypeInfo 的子类 ClassTypeInfo 还提供了接口用于访问类公开的构造函数以及它的成员变量、属性、函数。仓颉的反射被设计为只能访问到类型内 public 的成员，意味着 private、protected 和 default 修饰的成员在反射中是不可见的。

例如当我们想要在运行时对类的某一实例成员变量进行获取与修改。

import std.reflect.*

public class Foo {
    public static var param1 = 20
    public var param2 = 10
}

main(): Unit{
    let obj = Foo()
    let info = TypeInfo.of(obj)
    let staticVarInfo = info.getStaticVariable("param1")
    let instanceVarInfo = info.getInstanceVariable("param2")
    println("成员变量初始值")
    print("Foo 的静态成员变量 ${staticVarInfo} = ")
    println((staticVarInfo.getValue() as Int64).getOrThrow())
    print("obj 的实例成员变量 ${instanceVarInfo} = ")
    println((instanceVarInfo.getValue(obj) as Int64).getOrThrow())
    println("更改成员变量")
    staticVarInfo.setValue(8)
    instanceVarInfo.setValue(obj, 25)
    print("Foo 的静态成员变量 ${staticVarInfo} = ")
    println((staticVarInfo.getValue() as Int64).getOrThrow())
    print("obj 的实例成员变量 ${instanceVarInfo} = ")
    println((instanceVarInfo.getValue(obj) as Int64).getOrThrow())
    return
}

编译并执行上面的代码，会输出：

成员变量初始值
Foo 的静态成员变量 static param1: Int64 = 20
obj 的实例成员变量 param2: Int64 = 10
更改成员变量
Foo 的静态成员变量 static param1: Int64 = 8
obj 的实例成员变量 param2: Int64 = 25

同时我们也可以通过反射对属性进行检查以及修改。

import std.reflect.*

public class Foo {
    public let _p1: Int64 = 1
    public prop p1: Int64 {
        get() { _p1 }
    }
    public var _p2: Int64 = 2
    public mut prop p2: Int64 {
        get() { _p2 }
        set(v) { _p2 = v }
    }
}

main(): Unit{
    let obj = Foo()
    let info = TypeInfo.of(obj)
    let instanceProps = info.instanceProperties.toArray()
    println("obj的实例成员属性包含${instanceProps}")
    let PropInfo1 = info.getInstanceProperty("p1")
    let PropInfo2 = info.getInstanceProperty("p2")

    println((PropInfo1.getValue(obj) as Int64).getOrThrow())
    println((PropInfo2.getValue(obj) as Int64).getOrThrow())
    if (PropInfo1.isMutable()) {
        PropInfo1.setValue(obj, 10)
    }
    if (PropInfo2.isMutable()) {
        PropInfo2.setValue(obj, 20)
    }
    println((PropInfo1.getValue(obj) as Int64).getOrThrow())
    println((PropInfo2.getValue(obj) as Int64).getOrThrow())
    return
}

编译并执行上面的代码，会输出：

obj 的实例成员属性包含[prop p1: Int64, mut prop p2: Int64]
1
2
1
20

我们还可以通过反射机制进行函数调用。

import std.reflect.*

public class Foo {
    public static func f1(v0: Int64, v1: Int64): Int64 {
        return v0 + v1
    }
}

main(): Unit {
    var num = 0
    let intInfo = TypeInfo.of<Int64>()
    let funcInfo = TypeInfo.of<default.Foo>().getStaticFunction("f1", intInfo, intInfo)
    num = (funcInfo.apply([1, 1]) as Int64).getOrThrow()
    println(num)
}

编译并执行上面的代码，会输出：

2

动态加载

编译时刻加载称之为静态加载，而动态加载指的是仓颉程序可以在运行过程中通过特定函数来访问仓颉动态模块，以此读写全局变量、调用全局函数、获取类型信息的能力。仓颉中主要通过 ModuleInfo 和 PackageInfo 这两个类型来提供动态加载的能力。

例如我们存在一个 module0 模块下的 package0 包含一个公开的类型 Foo，其对应的仓颉动态模块路径为 "./module_package.so" 。应用动态加载我们便可以在运行时得到这个 Foo 的类型信息。

let m = ModuleInfo.load("./module_package")
let p = m.getPackageInfo("package0").getOrThrow()
let at = TypeInfo.get("module0/package0.Foo")

注解

仓颉中提供了一些属性宏用来支持一些特殊情况的处理。

确保正确使用整数运算溢出策略的注解

仓颉中提供三种属性宏来控制整数溢出的处理策略，即 @OverflowThrowing，@OverflowWrapping 和 @OverflowSaturating ，这些属性宏当前只能标记于函数声明之上，作用于函数内的整数运算和整型转换。它们分别对应以下三种溢出处理策略：

(1) 抛出异常（throwing）：当整数运算溢出时，抛出异常。

@OverflowThrowing
main() {
    let res: Int8 = Int8(100) + Int8(29)
    /* 100 + 29 在数学上等于 129，
     * 在 Int8 的表示范围上发生了上溢出，
     * 程序抛出异常
     */
    let con: UInt8 = UInt8(-132)
    /* -132 在 UInt8 的表示范围上发生了下溢出，
     * 程序抛出异常
     */
    0
}

(2) 高位截断（wrapping）：当整数运算的结果超出用于接收它的内存空间所能表示的数据范围时，则截断超出该内存空间的部分。

@OverflowWrapping
main() {
    let res: Int8 = Int8(105) * Int8(4)
    /* 105 * 4 在数学上等于 420，
     * 对应的二进制为 1 1010 0100，
     * 超过了用于接收该结果的 8 位内存空间，
     * 截断后的结果在二进制上表示为 1010 0100，
     * 对应为有符号整数 -92
     */
    let temp: Int16 = Int16(-132)
    let con: UInt8 = UInt8(temp)
    /* -132 对应的二进制为 1111 1111 0111 1100，
     * 超过了用于接收该结果的 8 位内存空间，
     * 截断后的结果在二进制上表示为 0111 1100
     * 对应为有符号整数 124
     */
    0
}

(3) 饱和（saturating）：当整数运算溢出时，选择对应固定精度的极值作为结果。

@OverflowSaturating
main() {
    let res: Int8 = Int8(-100) - Int8(45)
    /* -100 - 45 在数学上等于 -145，
     * 在 Int8 的表示范围上发生了下溢出，
     * 选择 Int8 的最小值 -128 作为结果
     */
    let con: Int8 = Int8(1024)
    /* 1024 在 Int8 的表示范围上发生了上溢出，
     * 选择 Int8 的最大值 127 作为结果
     */
    0
}

默认情况下（即未标注该类属性宏时），采取抛出异常（@OverflowThrowing）的处理策略。

实际情况下需要根据业务场景的需求正确选择溢出策略。例如要在 Int32 上实现某种安全运算，使得计算结果和计算过程在数学上相等，就需要使用抛出异常的策略。

【反例】

// 计算结果被高位截断
@OverflowWrapping
func operation(a: Int32, b: Int32): Int32 {
    a + b // No exception will be thrown when overflow occurs
}

该错误例子使用了高位截断的溢出策略，比如当传入的参数 a 和 b 较大导致结果溢出时，会产生高位截断的情况，导致函数返回结果和计算表达式 a + b 在数学上不是相等关系。

【正例】

// 安全
@OverflowThrowing
func operation(a: Int32, b: Int32): Int32 {
    a + b
}

main() {
    try {
        operation(a, b)
    } catch (e: ArithmeticException) {
        //Handle error
    }
    0
}

该正确例子使用了抛出异常的溢出策略，当传入的参数 a 和 b 较大导致整数溢出时，operation 函数会抛出异常。

下面总结了可能造成整数溢出的数学操作符。