Skip to content

5. 常用的 Kotlin 类

这里我们介绍一些常用的类和函数:字符串、数组、集合、文件和正则表达式。为此,Kotlin 提供了两个库:它自己的标准库 (包 [kotlin.text]、[kotlin.collections]、[kotlin.io]……),它为基本类型添加了数百个函数(其中大多数采用扩展函数 的形式,见第 4 章),以及 JDK(Java API SE),Kotlin 直接使用它,无需任何适配。此外还有集合上的函数式操作 ([filter]、[map]、[groupBy]……)和序列,它们是 Kotlin 中搜索、排序、分组或转换集合元素的标准方式:它们的作用与 Java 的 Stream API 相同。前面我们已经展示了如何查找关于数以千计的可用类和函数的信息。这项资源对于 Kotlin 开发者来说不可或缺,即使对于经验丰富的开发者也是如此。

本章的示例(末尾的示例应用程序除外)都是单文件程序,与第 3 章一样组织在课程代码中的 Gradle 项目 [05-classes-kotlin] 中:程序 [Strings01.kt] 位于包 [strings01] 中(文件夹 [src/main/kotlin/strings01]),可以使用命令 [gradlew -q run -Pmain=strings01.Strings01Kt] 运行,或者点击 IntelliJ IDEA 中的绿色三角形运行。与前几章不同,它们在配置为英语(English locale)的机器上运行。请注意,每个 Kotlin 文件都会自动导入包 [kotlin.*]、[kotlin.text.*]、[kotlin.collections.*]、[kotlin.ranges.*]、[kotlin.sequences.*]、[kotlin.io.*]……以及 [java.lang.*]:因此标准库中的函数无需 [import] 语句即可使用。不过,JDK 中其他包的类([java.util]、[java.text]、[java.time]、[java.nio.file]……)必须导入,而在 Java 课程中这是由紧凑源文件处理的。

5.1. 查阅 Kotlin 类的帮助

Kotlin 标准库包含数千个函数,而面向 JVM 的 Kotlin 程序还可以访问 JDK 中 4,000 多个公共类。没有人能记住所有这些:Kotlin 开发者时常查阅它们的文档。这些文档可以免费在线获取,并且针对每个版本保持更新。

5.1.1. 在线文档

起点是 JetBrains 的 kotlinlang.org 网站。在那里你会找到:

  • 标准库参考: https://kotlinlang.org/api/core/kotlin-stdlib/。它按包([kotlin.text]、[kotlin.collections]、[kotlin.io]……)逐个描述库中的所有类、接口和函数(包括扩展函数),并按它们所扩展的类型分类:因此 [String] 的页面既列出了它的成员([length]、[get]……),也列出了适用于它的数十个扩展函数([substringBefore]、[padStart]、[lines]……);
  • 每个页面顶部都有一个搜索框,可以在其中输入类或函数的名称([buildString]、[joinToString]……);
  • 语言文档(Language Guide),其中有关于字符串、集合、序列等的页面,还有一个“What’s New”页面,介绍每个版本中的新特性。语言的变更以提案的形式公开讨论,即 KEEP (Kotlin Evolution and Enhancement Process),可在 github.com/Kotlin/KEEP 查阅;
  • play.kotlinlang.org,Kotlin 的“沙盒”:在这里,你可以在浏览器中输入并运行程序,无需安装任何东西。

对于 Kotlin 程序所使用的 JDK 中的类([java.time.LocalDate]、[java.text.Collator]、[java.nio.file.Files]……),参考资料仍然是 Java SE 25 的 API:https://docs.oracle.com/en/java/javase/25/docs/api/。它使用 Java 语法描述这些类,需要做转换:[int] 对应 [Int],[String[]] 对应 [Array<String>],[getName()] 方法被当作 [name] 属性使用……

类或函数的页面,例如 kotlin.String,提供:

  • 类所在的包以及它所存在的平台(Kotlin 也可以在 JavaScript 和原生代码中运行:有些函数是 JVM 特有的);
  • 它的声明、它的父类型以及它所实现的接口;
  • 一般性的描述,通常附有可执行的示例;
  • 它的构造函数、属性、函数、成员和扩展的列表,随后是每一项的详细信息:参数、返回值、可能的异常,以及引入它的 Kotlin 版本(在“Since Kotlin”部分)。

文档是英文的。使用在函数名前加上 "kotlin" 的方式搜索("kotlin joinToString"),通常会直接带你到正确的页面。

5.1.2. KDoc 与编辑器的帮助

与 Java 的 Javadoc 一样,这些文档是由编写在源代码中的文档注释 生成的,在 Kotlin 中称为 KDoc。这种注释以 [/**] 开头,并紧挨着放在类、属性或函数之前。本章示例应用程序中的税款计算函数可以这样编写文档:

1
2
3
4
5
6
7
8
9
    /**
     * Calculates the tax of a taxpayer.
     *
     * @param married true if the taxpayer is married
     * @param nbChildren number of children
     * @param salary annual salary in euros
     * @return the amount of the tax, in euros
     */
    fun calculate(married: Boolean, nbChildren: Int, salary: Int): Int

注释以一个摘要句开头;[@param] 标签描述参数,[@return] 描述返回值([@throws] 用于描述异常,[@property] 用于描述类的属性)。与使用 HTML 标签的 Javadoc 不同,KDoc 注释的文本使用 Markdown 编写:[*italic*]、[**bold**]、列表,以及用方括号书写的指向代码中其他元素的链接,例如 [[salary]] 或 [[TaxBracket]]。JetBrains 的 Dokka 工具作为 Gradle 插件([id("org.jetbrains.dokka")])添加到项目中,可以生成与 Kotlin 参考文档类似的 HTML 页面。

代码编辑器(IntelliJ IDEA,以及装有 Kotlin 扩展的 Visual Studio Code)会利用这些注释,在不离开代码的情况下提供即时帮助:

  • 自动补全:输入 [aString.] 之后,编辑器会建议适用于该对象的属性和函数列表,包括成员和扩展函数(后者以其所扩展的类型标示,例如 [for String in kotlin.text]),以及它们的参数和返回类型;
  • 快速文档:将鼠标悬停在类或函数名上(或在 IntelliJ IDEA 中按 Ctrl+Q)会显示其 KDoc,对于 JDK 中的类则显示其 Javadoc;
  • 参数帮助:输入调用的左括号时(或在 IntelliJ IDEA 中按 Ctrl+P),编辑器会显示该函数的各个重载、每个参数的名称和作用,以及任何默认值;
  • 转到定义 (IntelliJ IDEA 中为 Ctrl+B,VS Code 中为 F12):显示该类或函数的源代码。Gradle 会下载 Kotlin 标准库的源代码,而 JDK 自带其自身库的源代码(文件 [lib/src.zip]):这使你可以阅读 [joinToString] 或 [java.util.ArrayList] 的代码,非常有教育意义。Kotlin 标准库中的代码往往很短,因为它依赖于 JDK 中的类;
  • 显示 Kotlin 字节码 (Tools > Kotlin > Show Kotlin Bytecode 菜单,然后点击 Decompile 按钮):以等效 Java 代码的形式显示编译器根据 Kotlin 代码生成的内容。这是理解扩展函数、属性或 [when] 会变成什么的方法。

最后,要在不编写程序的情况下测试某个函数,IntelliJ IDEA 提供了草稿文件 (File > New > Scratch File > Kotlin):你在其中输入指令,其结果会显示在每一行旁边。在命令行中,编译器的启动器(第 2 章)可以对表达式求值:[kotlinr -e 'println("abc".repeat(3))'] 会显示 [abcabcabc]。

5.2. 字符串

5.2.1. String 类型

类型 [String] (包 [kotlin])表示字符串。在 JVM 中,Kotlin 字符串就是一个 [java.lang.String] 对象:编译器把这两个类型映射到一起,字符串从 Kotlin 传给 Java(反之亦然)无需任何转换。不过,在 Kotlin 看来,[String] 类型只有四个成员([length]、[get]、[subSequence]、[compareTo])和运算符 [plus]:所有其他操作都是标准库(包 扩展函数 )中的[kotlin.text],它们像方法一样被调用。[java.lang.String] 中那些有 Kotlin 对应物的 Java 方法是被隐藏的:["abc".strip()] 会被编译器拒绝([unresolved reference 'strip' on receiver of type 'String']);应改用 ["abc".trim()]。下面是几个示例:

属性或函数
作用
[length: Int]
属性:字符串中的字符个数
[operator fun get(index: Int): Char]
第 [index] 个字符;第一个字符是第 0 个。写作 [s[index]]
[startsWith(prefix: String, ignoreCase = false)]
如果字符串以 [prefix] 开头,则返回 [true]
[endsWith(suffix: String, ignoreCase = false)]
如果字符串以 [suffix] 结尾,则结果为 [true]
[contains(other: CharSequence, ignoreCase = false)]
如果字符串包含 [other],则结果为 [true];也可以写成 [other in s]
[equals(other: String?, ignoreCase = false)]
如果字符串与 [other] 内容相同,则返回 [true];运算符 [==] 调用 [equals]
[indexOf(string: String, startIndex = 0, ignoreCase = false)]
[string] 在字符串中从位置 [startIndex] 开始的第一次出现位置,或 -1。另一个重载用于搜索字符
[lastIndexOf(char: Char, ...)]
与 [indexOf] 相同,但返回最后一个位置而不是第一个
[joinToString(separator = ", ", prefix = "", postfix = "")]
集合和数组的扩展函数:连接各元素,并用 [separator] 分隔它们
[replace(oldChar: Char, newChar: Char, ignoreCase = false)]
返回字符串的副本,其中字符 [oldChar] 已被替换为 [newChar];一个重载版本用一个字符串替换另一个字符串
[split(vararg delimiters: String, ...): List<String>]
把字符串视为由某个分隔符 [delimiters] 分隔的字段序列,分隔符按字面处理;结果是这些字段的列表。一个重载函数接受正则表达式 [Regex]
[substring(startIndex: Int, endIndex: Int)]
由从位置 [startIndex] (包含)到位置 [endIndex] (不包含)的字符组成的子字符串;[substring(range: IntRange)] 接受一个范围
[substringBefore(delimiter)]、[substringAfter(delimiter)]
分别是在第一次出现 [delimiter] 之前、之后的字符串([substringBeforeLast]、[substringAfterLast]:则针对最后一次出现)
[lowercase()]、[uppercase()]
把字符串转换为小写、大写
[trim()]
去除字符串开头和结尾的空格([trimStart]、[trimEnd]:仅去除一侧)
[repeat(n: Int)]
把字符串重复 [n] 次
[reversed()]
反转字符串
[isEmpty()]、[isBlank()]
如果字符串为空,或者只包含空格,则返回 [true]
[lines(): List<String>]
返回字符串中各行的列表
[format(vararg args: Any?)]
把字符串用作格式,返回其中的占位符 [%s]、[%d]……被参数替换后的字符串

请注意众多的 [ignoreCase] 参数,它们的默认值为 [false]:Kotlin 不像 Java 那样需要单独的 [equals] 和 [equalsIgnoreCase] 方法;我们使用命名参数写成 [s.equals(other, ignoreCase = true)] (第 3 章)。

需要注意的是,[String] 类型的字符串是不可变的;创建之后不能被修改。当函数返回一个字符串时,该字符串不同于函数所作用的字符串。因此,[s1.trim()] 返回字符串 [s2],而 [s1] 和 [s2] 是两个不同的字符串:[s1] 并没有改变。

Kotlin 字符串不是数组,但得益于 [get] 运算符(第 4 章),我们可以使用与数组元素相同的表示法访问它的第 n 个字符,而 Java 则需要另一种表示法。类似地,字符个数是属性 [c.length],数组的大小是属性 [array.size]:Kotlin 不存在 Java 中字符串的 [length()] 方法与数组的 [length] 字段之间的不一致。

程序 [Strings01.kt] 如下:

package strings01

// String 类型的一些属性和函数
fun main() {
    val aString = "the bird flies above the clouds"
    display("aString=$aString")
    display("aString.length=${aString.length}")
    display("aString[10]=${aString[10]}")
    display("aString.indexOf(\"flies\")=${aString.indexOf("flies")}")
    display("aString.indexOf(\"x\")=${aString.indexOf("x")}")
    display("aString.lastIndexOf('a')=${aString.lastIndexOf('a')}")
    display("aString.lastIndexOf('x')=${aString.lastIndexOf('x')}")
    display("aString.substring(4, 11)=${aString.substring(4, 11)}")
    display("aString.substring(4..10)=${aString.substring(4..10)}")
    display("aString.uppercase()=${aString.uppercase()}")
    display("aString.lowercase()=${aString.lowercase()}")
    display("aString.replace('a', 'A')=${aString.replace('a', 'A')}")
    // 没有 insert 函数:我们把两个子字符串重新拼接在一起……
    display("insertion of \"never \" at position 9=" + aString.substring(0, 9) + "never "
            + aString.substring(9))
    // ……或者用要插入的文本替换空范围 9 until 9
    display("aString.replaceRange(9, 9, \"never \")=${aString.replaceRange(9, 9, "never ")}")
    // 将字符串拆分为单词(分隔符:一串空格)
    val fields = aString.split(Regex("""\s+"""))
    for (i in fields.indices) {
        display("fields[$i]=[${fields[i]}]")
    }
    display("fields.joinToString(\":\")=${fields.joinToString(":")}")
    display("\"  abc  \".trim()=[${"  abc  ".trim()}]")
    // 一些在 Java 中没有直接对应的函数
    display("aString.substringBefore(' ')=${aString.substringBefore(' ')}")
    display("aString.substringAfterLast(' ')=${aString.substringAfterLast(' ')}")
    display("aString.reversed()=${aString.reversed()}")
    display("aString.count { it == 'e' }=${aString.count { it == 'e' }}")
    display("\"one\\ntwo\\nthree\".lines()=${"one\ntwo\nthree".lines()}")
    // 原字符串没有被修改
    display("aString=$aString")
}

// 一个显示函数
fun display(msg: String) {
    println(msg)
}

结果:

> gradlew -q run -Pmain=strings01.Strings01Kt
aString=the bird flies above the clouds
aString.length=31
aString[10]=l
aString.indexOf("flies")=9
aString.indexOf("x")=-1
aString.lastIndexOf('a')=15
aString.lastIndexOf('x')=-1
aString.substring(4, 11)=bird fl
aString.substring(4..10)=bird fl
aString.uppercase()=THE BIRD FLIES ABOVE THE CLOUDS
aString.lowercase()=the bird flies above the clouds
aString.replace('a', 'A')=the bird flies Above the clouds
insertion of "never " at position 9=the bird never flies above the clouds
aString.replaceRange(9, 9, "never ")=the bird never flies above the clouds
fields[0]=[the]
fields[1]=[bird]
fields[2]=[flies]
fields[3]=[above]
fields[4]=[the]
fields[5]=[clouds]
fields.joinToString(":")=the:bird:flies:above:the:clouds
"  abc  ".trim()=[abc]
aString.substringBefore(' ')=the
aString.substringAfterLast(' ')=clouds
aString.reversed()=sduolc eht evoba seilf drib eht
aString.count { it == 'e' }=4
"one\ntwo\nthree".lines()=[one, two, three]
aString=the bird flies above the clouds

注释:

  • 第 7–8 行:length 是属性,运算符 [[10]] 返回第 10 个字符,即字符串中的第 11 个字符;
  • 第 10、12 行:搜索不成功时返回 -1;
  • 第 13 行:[substring] 的两个参数分别是要保留的第一个字符和要丢弃的第一个字符的位置:这会返回从位置 4 到 10 的 7 个字符。这是 Kotlin 和 Java 中指定索引范围的通用约定(包含起点,不包含终点):许多函数都使用它;
  • 第 14 行:*[substring] 的一个重载接受区间 *[IntRange]*(第 3 章),其中两个端点都包含在内:[4..10] 所指的字符与参数 [(4, 11)] 相同。我们也可以写成 [4 until 11] 或 [4..<11]*;
  • 第 15 行:[uppercase] 和 [lowercase] (Kotlin 1.5)不依赖于机器的语言(它们使用与语言无关的 Unicode 规则);较早的 Java 风格的 [toUpperCase] 和 [toLowerCase] 依赖于机器语言(在土耳其语中,小写的“i”会变成“İ”),在 Kotlin 中已被弃用;
  • 第 18–22 行:[String] 类型没有插入函数:我们把字符串的开头、插入的文本和字符串的结尾拼接起来,或者使用 [replaceRange],它把某个范围内的字符替换为文本:替换从位置 9 开始的空范围就等同于插入。我们将看到 [StringBuilder] 类有 [insert] 函数;
  • 第 24 行:[split] 把字符串拆分为字段并返回一个列表 ([List<String>],稍后介绍),而不是像 Java 中那样返回数组。请注意,这是与 Java 的一个重要区别:当参数为 [String] 时,[split] 中的分隔符按字面处理;要使它成为正则表达式(我们将在本章末尾介绍),必须传入一个 [Regex] 对象。[\s+] 表示由一个或多个空白字符(空格、制表符、换行符等)组成的序列。它写在以三个引号分隔的原始字符串 中,其中字符 [\] 是普通字符,无需重复书写(我们稍后会再回到这一点);
  • 第 25 行:列表(或数组)的属性 [indices] 是其索引的范围,这里是 [0..5];
  • 第 28 行:[joinToString] 执行 [split] 的逆操作。它是列表和数组的扩展函数,而 Java 提供的是静态方法 [String.join];
  • 第 29 行:[trim] 去除开头和结尾的空格。Kotlin 的 [trim] 识别所有 Unicode 空白字符(它使用函数 [Char.isWhitespace]):因此它对应的是 Java 方法 [strip],而不是 Java 方法 [trim],后者只识别 ASCII 码中的空格;
  • 第 31–35 行:Kotlin 库中的几个函数,它们在 Java 类 [String] 中没有直接对应物:[substringBefore] 和 [substringAfterLast] 分别返回第一个空格之前和最后一个空格之后的内容,无需计算位置;[reversed] 反转字符串;[count] 统计满足条件的字符个数,条件由 lambda 表示:[{ it == 'e' }] 是一个匿名函数,其隐式参数 [it] 是正在检查的字符(lambda 在第 7 章介绍)。由于它的 lambda 是 [count] 的最后一个参数,因此写在函数名之后,不带括号;最后,[lines] 把文本拆分成行,无论使用何种行结束符([\n]、[\r\n] 或 [\r]),并返回行的列表;
  • 第 37 行:前面所有的函数都返回新的字符串:[aString] 没有被修改(结果的最后一行);
  • 第 41–42 行:一个顶层函数,由函数 [main] 调用,与第 3 章中一样。

5.2.2. split 与 joinToString 函数

程序 [Strings02.kt] 更深入地探讨了把字符串拆分为字段。熟悉 Java 的读者会发现它与 Java 的 [split] 方法有两个显著的区别:

package strings02

// split 和 joinToString
fun main() {
    val line = "one:two::three:"
    // 用 ":" 分隔符拆分
    var fields = line.split(":")
    for ((i, field) in fields.withIndex()) {
        println("fields[$i]=[$field]")
    }
    // 反向操作得到初始字符串:保留了最后的空字段
    println("joinToString=[${fields.joinToString(":")}]")

    // 限制:最多 2 个字段,最后一个字段包含字符串的剩余部分
    fields = line.split(":", limit = 2)
    println("split(\":\", limit = 2) : ${fields.size} fields $fields")

    // 分隔符是正则表达式:":+" 表示一串 ':'
    fields = line.split(Regex(":+"))
    println("split(Regex(\":+\")) : ${fields.size} fields [${fields.joinToString("|")}]")

    // 多个分隔符,然后去除字段周围的空格
    val person = " dupont , jean ;  45 "
    fields = person.split(',', ';').map { it.trim() }
    println("split(',', ';') + trim : ${fields.size} fields [${fields.joinToString("|")}]")
    // 用正则表达式做同样的事
    fields = person.trim().split(Regex("""\s*[,;]\s*"""))
    println("""split(Regex("\s*[,;]\s*")) : ${fields.size} fields [${fields.joinToString("|")}]""")

    // 逐个字段去除空格和空字段
    val list = "  red ,, green ,  , blue "
    val colors = mutableListOf<String>()
    for (field in list.split(",")) {
        val color = field.trim()
        if (color.isNotEmpty()) {
            colors.add(color)
        }
    }
    println("trim + isNotEmpty : ${colors.size} fields [${colors.joinToString("|")}]")
    // 用一条语句完成同样的事
    val colors2 = list.split(",").map { it.trim() }.filter { it.isNotEmpty() }
    println("map + filter : ${colors2.size} fields [${colors2.joinToString("|")}]")

    // 包含正则表达式特殊字符的分隔符:没有问题
    val text = "apple | pear | apricot"
    println("split(\" | \") : [${text.split(" | ").joinToString(", ")}]")

    // joinToString 接受任何类型的元素,可带前缀、后缀和转换
    val numbers = intArrayOf(1, 2, 3, 4)
    println("joinToString on integers : ${numbers.joinToString(" + ")}")
    println(numbers.joinToString(", ", prefix = "[", postfix = "]") { "no.$it" })
}

结果:

> gradlew -q run -Pmain=strings02.Strings02Kt
fields[0]=[one]
fields[1]=[two]
fields[2]=[]
fields[3]=[three]
fields[4]=[]
joinToString=[one:two::three:]
split(":", limit = 2) : 2 fields [one, two::three:]
split(Regex(":+")) : 4 fields [one|two|three|]
split(',', ';') + trim : 3 fields [dupont|jean|45]
split(Regex("\s*[,;]\s*")) : 3 fields [dupont|jean|45]
trim + isNotEmpty : 3 fields [red|green|blue]
map + filter : 3 fields [red|green|blue]
split(" | ") : [apple, pear, apricot]
joinToString on integers : 1 + 2 + 3 + 4
[no.1, no.2, no.3, no.4]

注释:

  • 第 7 行:字段由字符 [:] 分隔。两个连续的 [:] 界定出一个空字段(结果的第 3 行),而字符串末尾的 [:] 界定出第五个字段(同样为空),该字段被保留(结果的第 5 行)。这是与 Java 的第一个区别:在 Java 中,*[split] 方法会移除末尾的空字段;而在 Kotlin 中,*[joinToString] 总能重建出原始字符串(结果的第 6 行)。Kotlin 的行为更加一致:包含 n 个分隔符的字符串总是产生 n + 1 个字段。要复现 Java 的行为,可以写成 [line.split(":").dropLastWhile { it.isEmpty() }];
  • 第 8 行:函数 [withIndex] 使你可以同时使用索引和元素来遍历列表,元素通过解构 获取(第 3 章);
  • 第 15 行:[limit] 是 [split] 的可选参数,用于设定字段的最大个数:拆分在第一个分隔符处停止,最后一个字段包含字符串的全部剩余部分。例如,当值本身可能包含分隔符时,就可以用分隔符来分隔 [name=value] 行中参数的名称和值。请注意,当使用模板([$fields])显示列表时,它的元素会显示在方括号中,并以逗号分隔:这就是列表的 [toString] ;
  • 第 19 行:与 Java 的第二个区别:类型为 [String] 的分隔符按字面处理;要用正则表达式描述分隔符,必须传入一个 [Regex] 对象。[":+"] 表示一个或多个连续的 [:] 字符。这两个连续的 [:] 字符 构成一个分隔符,中间的空字段消失;不过最后一个空字段仍然保留;
  • 第 24 行:[split] 接受多个分隔符([vararg],第 3 章),可以是字符或字符串:这里是逗号和分号。然后函数 [map] 对每个字段应用 lambda [{ it.trim() }],并返回结果列表:只需一条语句,我们就得到了三个“清理过”的字段。函数 [map]、[filter] 以及它们的众多同类函数将在本章稍后介绍;
  • 第 27 行:使用正则表达式得到同样的结果:模式 [\s*[,;]\s*] 匹配逗号或分号,其前后可以有任意数量的空格;分隔符周围的空格会随分隔符一起被移除。字符串开头和结尾的空格则预先由 [trim] 去除。该模式写在原始字符串中,无需重复书写 [\];下一行同样使用原始字符串,把模式原样显示出来;
  • 第 32–36 行:要同时去除字段周围的空格和空字段,可以逐个处理字段:位于两个逗号之间、由两个空格组成的字段,在 [trim] 之后变为空,因此不会被保留。用于存储被保留字段的、由 [mutableListOf] 创建的可编辑列表将在稍后介绍;
  • 第 41 行:用一条语句得到同样的结果:[map] 去除每个字段中的空格,然后 [filter] 只保留非空字段。这是在 Kotlin 中编写此类代码的惯用方式;
  • 第 46 行:分隔符 [" | "] 包含字符 [|],它在正则表达式中具有特殊含义(“或”)。由于分隔符按字面处理,无需任何特殊预防措施,而在 Java 中你必须写 [split(Pattern.quote(" | "))]。如果需要由任意文本构造正则表达式,函数 [Regex.escape] 的作用与 [Pattern.quote] 相同;
  • 第 49–51 行:与只接受字符串的 Java [String.join] 不同,[joinToString] 接受任何类型的元素;这里是整数数组 [IntArray]:每个元素由其函数 [toString] 转换。它的可选参数 [prefix] 和 [postfix] 在开头和结尾添加文本,而它的最后一个参数 [transform] 是一个把每个元素转换为文本的 lambda;把它写在圆括号之后,就会生成文本“no.1”、“no.2”等。Java 借助 [StringJoiner] 或 Stream API 完成的事情,在这里只需一次调用即可完成。

5.2.3. 字符串的搜索与比较

字符串比较比看上去要微妙:是否应该区分大写和小写字母?应该如何比较“éclair”和“essay”?还有 [==] 运算符比较的是什么?在最后这一点上,Kotlin 修复了 Java 中一个众所周知的陷阱。程序 [Strings03.kt] 演示了搜索和比较函数:

package strings03

import java.text.Collator
import java.util.Locale

// 搜索和比较字符串
fun main() {
    val title = "Learning the Kotlin language, version 2.4"

    // contains、startsWith、endsWith:默认为精确比较……
    println("contains(\"language\") : ${title.contains("language")}")
    println("contains(\"LANGUAGE\") : ${title.contains("LANGUAGE")}")
    println("startsWith(\"Learning\") : ${title.startsWith("Learning")}")
    println("endsWith(\"2.4\") : ${title.endsWith("2.4")}")
    // ……或者忽略大小写
    println("contains(\"LANGUAGE\", ignoreCase = true) : ${title.contains("LANGUAGE", ignoreCase = true)}")
    // in 运算符调用 contains
    println("\"Kotlin\" in title : ${"Kotlin" in title}")
    // regionMatches(start, other, start in other, length, ignoreCase)
    println("regionMatches(0, \"learning\", 0, 8, true) : "
            + title.regionMatches(0, "learning", 0, 8, ignoreCase = true))

    // 相等性:== 比较内容,=== 比较引用
    val answer = "YES"
    val yes = StringBuilder("ye").append('s').toString()
    println("yes == \"yes\" : ${yes == "yes"}")
    println("yes === \"yes\" : ${yes === "yes"}")
    println("answer == \"yes\" : ${answer == "yes"}")
    println("answer.equals(\"yes\", ignoreCase = true) : ${answer.equals("yes", ignoreCase = true)}")

    // 字母顺序:按字符码或按语言规则
    val a = "éclair"
    val b = "essay"
    println("\"$a\".compareTo(\"$b\") : ${a.compareTo(b)}")
    println("\"$a\" < \"$b\" : ${a < b}")
    val collator = Collator.getInstance(Locale.FRANCE)
    println("collator.compare(\"$a\", \"$b\") : ${collator.compare(a, b)}")

    // 空字符串或空白字符串
    val empty = ""
    val blank = "   "
    val absent: String? = System.getenv("ABSENT_VARIABLE")
    println("\"\".isEmpty() : ${empty.isEmpty()}")
    println("\"   \".isEmpty() : ${blank.isEmpty()}")
    println("\"   \".isBlank() : ${blank.isBlank()}")
    println("absent.isNullOrBlank() : ${absent.isNullOrBlank()}")
    println("absent?.length : ${absent?.length}")
    println("absent.orEmpty().length : ${absent.orEmpty().length}")

    // 填充和重复
    println("[${"abc".padStart(8)}] [${"abc".padEnd(8)}] [${"-".repeat(8)}] [${"42".padStart(5, '0')}]")
}

结果:

> gradlew -q run -Pmain=strings03.Strings03Kt
contains("language") : true
contains("LANGUAGE") : false
startsWith("Learning") : true
endsWith("2.4") : true
contains("LANGUAGE", ignoreCase = true) : true
"Kotlin" in title : true
regionMatches(0, "learning", 0, 8, true) : true
yes == "yes" : true
yes === "yes" : false
answer == "yes" : false
answer.equals("yes", ignoreCase = true) : true
"éclair".compareTo("essay") : 132
"éclair" < "essay" : false
collator.compare("éclair", "essay") : -1
"".isEmpty() : true
"   ".isEmpty() : false
"   ".isBlank() : true
absent.isNullOrBlank() : true
absent?.length : null
absent.orEmpty().length : 0
[     abc] [abc     ] [--------] [00042]

注释:

  • 第 3–4 行:程序所使用的 JDK 中的类必须导入;
  • 第 11–14 行:默认情况下,[contains]、[startsWith] 和 [endsWith] 执行精确的逐字符比较:找不到“LANGUAGE”;
  • 第 16 行:这些函数有一个可选参数 [ignoreCase],它指示程序忽略大小写。Java 没有对应的功能:两个字符串都必须以小写输入;
  • 第 18 行:运算符 [in] 调用函数 [contains] (第 4 章):["Kotlin" in title] 读起来很自然,就是“Kotlin 在标题中”;
  • 第 19–21 行:函数 [regionMatches] 把一个字符串的一部分与另一个字符串的一部分进行比较。它的参数依次是在本字符串中的起始位置、另一个字符串、在另一个字符串中的起始位置,以及要比较的字符个数;最后一个参数是可选的,表示是否忽略大小写(在 Java 的某个重载中,这个参数排在最前面);
  • 第 23–29 行:本程序最重要的部分。类型为 [String] 的变量包含对字符串对象的引用 (第 4 章)。变量 [yes] 引用的是在运行时构造的字符串“yes”:它与程序中的字面量字符串“yes”是不同的对象。在 Kotlin 中,运算符 [] 比较的是内容:它调用函数 [equals],而 [yes == "yes"] 的值为 [true] (结果的第 8 行)。要比较引用,即判断两个变量是否引用同一个对象,Kotlin 有另一个运算符 [=],而 [yes === "yes"] 等于 [false] (结果的第 9 行)。在 Java 中情况正好相反:[] 在那里比较的是引用,把 [answer == "yes"] 误写成 [answer.equals("yes")] 这种常见错误在 Kotlin 中并不存在。不区分大小写的比较写作 [equals(..., ignoreCase = true)],这是验证通过键盘以大写或小写输入的“yes”回答的正确方式。对于字符串,你几乎从不需要 [=] ;
  • 第 32–37 行:函数 [compareTo] 根据字符串排在参数字符串之前、等于它还是排在其之后,返回负整数、零或正整数。它比较的是字符编码:“éclair”排在“essay”之后,因为字符“é”的编码(233)大于字符“e”的编码(101);这里它返回两个编码之差 132。由于 [String] 实现了 [Comparable<String>],运算符 [<]、[>]、[<=] 和 [>=] 可以用于字符串,并调用 [compareTo]:[a < b] 等于 [false]。要按某种语言的规则对单词排序,需要使用 JDK 中的 [java.text.Collator] 对象:对于法语,字符“é”与“e”一起排序,“éclair”排在“essay”之前(结果的第 14 行)。对于面向用户的单词排序,我们将使用由 [Collator] 指定的顺序,而比较技术标识符(文件名、键等)则使用 [compareTo]。函数 [compareTo] 同样有一个参数 [ignoreCase];
  • 第 40–48 行:[isEmpty] 检查字符串是否为空,[isBlank] 检查字符串是否为空或只包含空格。字符串也可能不存在:此时它的变量类型为 [String?] ,值为 [null] (第 3 章)。这里,[System.getenv](一个返回环境变量值的 Java 方法)返回 [null] ,因为所请求的变量不存在。编译器禁止调用 [absent.isBlank()],因为它可能抛出 [NullPointerException] 异常。库为 [String?] 类型提供了接受 [null] 的扩展函数:[isNullOrBlank] (以及 [isNullOrEmpty])检查的内容,在 Java 中要写成 [absent == null || absent.isBlank()],而 [orEmpty] 返回该字符串,如果它是 [null] 则返回空字符串。对 [absent?.length] 的安全调用返回 [null];
  • 第 51 行:[padStart] 从左侧用空格或指定字符([padStart(5, '0')])把字符串填充到 8 个字符的长度,[padEnd] 则从右侧填充;[repeat] 重复字符串。也可以使用下面展示的格式 ["%8s"] 和 ["%-8s"]。

5.2.4. 模板、格式与原始字符串

从第 3 章开始,我们就一直使用字符串模板来构造要显示的字符串:在字符串中,[$name] 会被替换为变量 [name] 的值,而 [${expression}] 会被替换为任意表达式的值。这就是字符串插值,Java 缺少这一特性(一项名为“String Templates”的提案曾在 Java 21 和 22 中预览,但后来被移除),C# 将其写作 [$"{name}"]。编译器把模板转换为字符串连接:没有额外的运行时开销。

要把值对齐成列、设定数字的小数位数,或显示日期,你还需要使用格式,既可以使用 [String.format] 函数,也可以使用作用于格式本身的扩展函数 [format] ,二者作用相同(都会调用 Java 方法 [String.format])。格式是一个文本字符串,其中的 [%[-][width][.precision]conversion] 说明符指明在哪里以及如何插入后面的参数。程序 [Strings04.kt] 提供了这些的示例,同时也展示了 Kotlin 原始字符串:

package strings04

import java.text.NumberFormat
import java.time.LocalDateTime
import java.time.format.DateTimeFormatter
import java.util.Locale

// 模板、格式、原始字符串
fun main() {
    val name = "dupont"
    val age = 45
    val salary = 2345.678
    val rate = 0.0525
    val date = LocalDateTime.of(2026, 10, 3, 14, 5, 9)

    // 字符串模板:$variable 或 ${expression}
    println("$name is $age years old, and ${2026 - age} is his year of birth")
    // %[-]width:width > 0 右对齐,- 号表示左对齐
    println(String.format("[%10s] [%-10s] [%5d]", name, name, age))
    println("[%12.2f] [%-12.1f] [%,.2f]".format(salary, salary, salary))
    println("[%05d] [%X] [%,d] [%e]".format(age, age, 1234567, salary))
    // if 是表达式:它可以提供参数
    println("%s is %s".format(name, if (age >= 18) "an adult" else "a minor"))
    // 模板用 Double 的 toString 函数显示它:小数点,所有小数位
    println("salary=$salary, rounded=${"%.2f".format(salary)}, "
            + "in English=${"%.2f".format(Locale.US, salary)}")

    // 货币和百分比:JDK 的 NumberFormat 类
    val currency = NumberFormat.getCurrencyInstance(Locale.FRANCE)
    val percentage = NumberFormat.getPercentInstance(Locale.FRANCE)
    percentage.minimumFractionDigits = 2
    println("[${currency.format(salary)}] [${percentage.format(rate)}]")

    // 日期:JDK 的 DateTimeFormatter 类
    println("[${date.format(DateTimeFormatter.ofPattern("dd/MM/yyyy"))}] "
            + "[${date.format(DateTimeFormatter.ofPattern("HH:mm:ss"))}] "
            + "[${date.format(DateTimeFormatter.ofPattern("EEEE d MMMM yyyy"))}]")

    // 对齐的表格
    val products = arrayOf("apple", "pear", "apricot")
    val prices = doubleArrayOf(2.5, 3.15, 12.0)
    for (i in products.indices) {
        println("%-10s|%8.2f €".format(products[i], prices[i]))
    }

    // 在普通字符串中,\ 字符必须写两次……
    val path = "C:\\data\\course\\infos.txt"
    println(path)
    // ……但在原始字符串中则不必
    val path2 = """C:\data\course\infos.txt"""
    println("path == path2 : ${path == path2}")

    // 多行原始字符串:trimIndent 去除公共缩进
    val json = """
        {
          "name": "$name",
          "path": "C:\data",
          "price": ${prices[0]},
          "template": "${'$'}name"
        }
        """.trimIndent()
    println(json)
    // trimMargin:每一行在空格之后以 | 字符开头
    val text = """
        |Name: $name
        |Age: $age years
        |Salary: ${"%.2f €".format(salary)}
        """.trimMargin()
    println(text)
}

结果:

> gradlew -q run -Pmain=strings04.Strings04Kt
dupont is 45 years old, and 1981 is his year of birth
[    dupont] [dupont    ] [   45]
[     2345.68] [2345.7      ] [2,345.68]
[00045] [2D] [1,234,567] [2.345678e+03]
dupont is an adult
salary=2345.678, rounded=2345.68, in English=2345.68
[2 345,68 €] [5,25 %]
[03/10/2026] [14:05:09] [Saturday 3 October 2026]
apple     |    2.50 €
pear      |    3.15 €
apricot   |   12.00 €
C:\data\course\infos.txt
path == path2 : true
{
  "name": "dupont",
  "path": "C:\data",
  "price": 2.5,
  "template": "$name"
}
Name: dupont
Age: 45 years
Salary: 2345.68 €

注释:

  • 第 17 行:一个模板:[$name] 和 [$age] 会被替换为变量的值,而 [${2026 - age}] 会被替换为表达式的值。只要 [$] 后面不是简单的变量名,就必须使用花括号:[$person.name] 会插入 [person] 的值 再加上文本“.name”,而 [${person.name}] 插入的是属性 [name];
  • 第 19 行:宽度使值在 10 个字符的字段内右对齐;前面加上符号 [-] 则左对齐;
  • 第 19–21 行:最常见的转换:
说明符
含义
示例(English 区域设置)
[%s]
字符串;任何对象都通过其函数 [toString] 转换
dupont
[%d], [%5d]
整数,长度可为 5 个字符
45
[%05d]
至少 5 位数字的整数,用零填充
00045
[%X]
十六进制整数([%x]:小写)
2D
[%.2f], [%12.2f]
保留 2 位小数的实数,长度可为 12 个字符
2345.68
[%,.2f], [%,d]
与上面相同,并带有千位分隔符
2,345.68
[%e]
科学记数法的实数
2.345678e+03
[%n]
系统换行符
 
[%%]
字符 %
%
  • 数字按当前语言进行格式化,这里是英语:小数点,逗号作为千位分隔符。在法语中([Locale.FRANCE],第 29–32 行),千位分隔符是一个窄的不间断空格(字符 U+202F),它看起来像普通空格,但可以防止在数字中间换行;同样,符号 € 和符号 % 之前也有一个不间断空格(U+00A0)。在把这些文本与使用普通空格书写的字符串比较时,应当考虑到这一点。参数类型仅在运行时检查:向 [Int] 转换 [%f] 传入 [IllegalFormatConversionException] 会抛出异常;
  • 第 23 行:["...".format(...)] 等价于 [String.format("...", ...)] (也等价于 Java 方法 [formatted])。由于 [if] 是 Kotlin 的表达式(第 3 章),它可以提供一个参数,而 Java 使用条件运算符 [? :];
  • 第 25 行:模板不会格式化数字;它对值调用 [toString] 函数,该函数以小数点和全部小数位显示 [Double] ,与机器的语言无关。对于面向用户的显示,需要把模板和格式结合起来:[${"%.2f".format(salary)}]。[format] 的一个重载把要使用的语言作为第一个参数:[Locale.US] 返回小数点;
  • 第 29–32 行:货币金额和百分比使用 JDK 中的 [java.text.NumberFormat] 对象格式化,这些对象是针对给定的语言和国家([Locale.FRANCE])获得的。百分比格式会把值乘以 100。请注意第 31 行:Java 方法 [setMinimumFractionDigits(2)] 在 Kotlin 中以属性赋值的方式使用。Kotlin 把成对的 Java 方法 [getXxx()]/[setXxx(...)] 视为属性 [xxx];
  • 第 34–37 行:JDK 的日期 API 和 [java.time] 由根据模板构造的 [DateTimeFormatter] 对象进行格式化:[dd] 日,[MM] 月,[yyyy] 年,[HH] 时,[mm] 分,[ss] 秒,[EEEE] 完整拼写的星期,[MMMM] 完整拼写的月份。请注意大小写:[MM] 是月,[mm] 是分钟。星期和月份的名称是日常用语中使用的名称。模板可以包含本身又含有字符串的表达式:["[${date.format(DateTimeFormatter.ofPattern("dd/MM/yyyy"))}] "];
  • 第 40–43 行:宽度使数据可以按列显示;
  • 第 47 行:在普通字符串中,字符 [\] 引入一个转义序列 ([\n]、[\t]、[\"]、[\$]……);要得到字符 [\] 本身,必须把它写两次;
  • 第 50 行:原始字符串 由三个引号分隔。原始字符串中不存在转义序列:字符 [\] 被视为普通字符。这是书写 Windows 路径和正则表达式的便捷方式,而 Java 不支持这一点(它的文本块保留转义序列)。不过,在这里你不能写成 [\n] 这样的换行;需要真正的换行;
  • 第 54–61 行:原始字符串可以跨越多行,并且可以包含未转义的引号。它保留引号之间所写的一切,包括代码缩进以及开头和结尾的空行。[trimIndent] 函数在第一行和最后一行为空白时将其移除,然后去除所有行共有的缩进(即缩进最少的那一行的缩进):JSON 文本在显示时没有代码的边距,也没有最后的换行符,结果就是 [println]。这等价于 Java 15 的文本块,但是通过库函数实现的。与 Java 文本块不同,模板在原始字符串中同样有效:["$name"] 和 [${prices[0]}] 会被替换为它们的值,从而无需使用 [format];[\] 在 ["C:\data"] 中无需重复书写;
  • 第 59 行:由于原始字符串中不存在转义序列,你不能写 ***[\\$] 来得到后面跟着名称的 *[$] 而不被解释为模板:我们改写成 [${'$'}],这是一个表达式为字符 [$] 的模板。从 Kotlin 2.2 开始,我们还可以在字符串前加上多个 [$]* ([$$"""..."""]):此时只有两个 [$] 组成的序列才会引入模板,这便于编写包含许多 [$]* 的文本;
  • 第 64–68 行:[trimMargin] 函数提供了另一种指定边距的方式:每一行在(可能有的)空格之后以一个边距字符开头(默认为 [|] ),在该字符之前的所有内容(包括该字符本身)都会被移除。请选择可读性最好的函数:对于原样复制的文本使用 [trimIndent] ,而当文本的第一列需要清晰可见时使用 [trimMargin] 。

还有类 [java.text.MessageFormat],它的格式通过编号来引用参数:[MessageFormat.format("{0} is {1} years old", name, age)]。它用于翻译成多种语言的消息,在这些语言中参数的顺序可能各不相同;它在 Kotlin 中的用法与在 Java 中完全相同。

5.2.5. StringBuilder 类

我们已经指出,对类型为 [String] 的字符串 [s1] 进行操作的函数会返回另一个字符串 [s2]。[StringBuilder] 类使你可以修改字符串,而无需为每次操作创建新的字符串。当通过许多次连续添加来构造字符串时,这样可以避免生存期极短的字符串大量涌现,从而提高性能。在面向 JVM 的 Kotlin 中,[kotlin.text.StringBuilder] 是 JDK 的 类型别名 ([typealias])[java.lang.StringBuilder] 类的别名:它们是同一个类,标准库用少量扩展函数对其进行了扩展([appendLine]、[[]] 运算符……)。使用它无需 [import]。

该类支持多种构造函数:

构造函数
作用
[StringBuilder()]
创建一个空对象,初始容量为 16 个字符
[StringBuilder(str: String)]
用 [str] 构造并初始化;初始容量为 [str] 的长度加 16
[StringBuilder(capacity: Int)]
构造一个空对象,初始容量为 [capacity] 个字符

[StringBuilder] 对象把它的字符存储在一个数组中,该数组的大小(即它的容量)会随着文本的增长而自动调整。程序 [Strings05.kt] 演示了容量这一概念:

package strings05

// StringBuilder 的大小和容量
fun main() {
    val str = StringBuilder("test")
    println("size=${str.length}, capacity=${str.capacity()}")
    repeat(10) {
        str.append("test")
        println("size=${str.length}, capacity=${str.capacity()}")
    }
    // 初始容量为 10 的 StringBuilder
    val str2 = StringBuilder(10).append("test")
    println("size=${str2.length}, capacity=${str2.capacity()}")
    repeat(10) {
        str2.append("test")
        println("size=${str2.length}, capacity=${str2.capacity()}")
    }
}

结果:

> gradlew -q run -Pmain=strings05.Strings05Kt
size=4, capacity=20
size=8, capacity=20
size=12, capacity=20
size=16, capacity=20
size=20, capacity=20
size=24, capacity=42
size=28, capacity=42
size=32, capacity=42
size=36, capacity=42
size=40, capacity=42
size=44, capacity=86
size=4, capacity=10
size=8, capacity=10
size=12, capacity=22
size=16, capacity=22
size=20, capacity=22
size=24, capacity=46
size=28, capacity=46
size=32, capacity=46
size=36, capacity=46
size=40, capacity=46
size=44, capacity=46

注释:

  • 第 5 行:创建一个包含“test”的 [StringBuilder] 对象:它的初始容量是 4 + 16 = 20 个字符。与 Kotlin 中的任何类一样,没有 [new] 运算符;
  • 第 6 行:[length] 是当前的字符个数。Kotlin 把它表示为属性 (不带括号),与 [String] 一样:[length()] 是 [CharSequence] 接口的 Java 方法,在 Kotlin 中被视为属性 [length]。[capacity()] 不属于该接口,也不遵循 [getXxx()] 约定,因此仍然是方法:它表示对象在需要扩展其数组之前可以容纳的字符个数;
  • 第 7 行:标准库中的 [repeat] 函数执行其后的 lambda 10 次(第 3 章);
  • 第 8 行:[append] 把一个字符串追加到文本末尾;
  • 第 12 行:创建一个初始容量为 10 的空 [StringBuilder] 对象,并立即向其中添加“test”。[append] 方法返回对象本身:因此可以直接在构造函数的结果上调用它。

由于是同一个类,其结果与 Java 程序的结果相同,它们表明当容量不足时,容量会略多于翻倍:新容量是旧容量乘以 2 再加 2(第一个对象为 20、42、86;第二个对象为 10、22、46)。每次扩展都会分配一个新数组并把字符复制到其中。如果事先知道文本的大致大小,在构造时设定它就可以避免这些连续的扩展。

该类的部分函数如下:

函数
作用
[append(str: String?): StringBuilder]
将 [str] 添加到文本末尾。已重载以接受类型 [Int]、[Double]、[Char]、[Boolean]、[Any?]……
[appendLine(value)]
Kotlin 扩展:添加 [value] 并在其后加上换行符 [\n];不带参数时,只添加换行符
[insert(offset: Int, str: String?)]
将 [str] 插入到位置 [offset];其重载方式与 [append] 相同
[delete(start: Int, end: Int)]
删除从位置 [start] (含)到 [end] (不含)的字符;[deleteCharAt] 删除单个字符
[replace(start: Int, end: Int, str: String)]
将位置 [start] (含)到 [end] (不含)之间的字符替换为 [str]
[reverse()]
反转字符的顺序
[sb[index]]、[sb[index] = ch]
读取并替换第 [index] 个字符(运算符 [get] 和 [set];[set] 是对 Java 方法 [setCharAt]的 Kotlin 扩展)
[indexOf(str: String)]
[str] 在文本中的位置,若不存在则为 -1
[toString()]
以字符串 [String] 的形式返回文本

程序 [Strings06.kt] 使用了这些函数,以及函数 [buildString],它是在 Kotlin 中构造字符串的惯用方式:

package strings06

// StringBuilder 的函数返回 StringBuilder 对象本身:可以链式调用
fun main() {
    val str3 = StringBuilder("test")
    println(str3.append("abCD").insert(2, "xyZT").delete(0, 2).replace(0, 2, "XY"))
    // [] 运算符读取和修改字符
    str3[0] = 'x'
    println("str3[0]=${str3[0]}, str3=$str3")
    // reverse 反转字符顺序(String 也有 reversed 函数)
    println(StringBuilder("éclair").reverse())

    // 逐段构建字符串
    val lines = StringBuilder()
    for (i in 1..3) {
        lines.append("line ").append(i).append('\n')
    }
    // joinTo 追加以逗号分隔的元素
    listOf("a", "b", "c").joinTo(lines, ", ")
    lines.appendLine()
    // 格式化的字符串
    val total = 42
    lines.append("total=%6.1f".format(total.toDouble()))
    // 最终的字符串
    val result = lines.toString()
    println(result)
    println("${result.length} characters")

    // buildString:创建 StringBuilder,由 lambda 填充,然后转换为 String
    val table = buildString {
        appendLine("+-------+-------+")
        for (i in 1..3) {
            appendLine("| ${i.toString().padStart(5)} | ${(i * i).toString().padStart(5)} |")
        }
        append("+-------+-------+")
    }
    println(table)

    // 分隔符、前缀和后缀:joinToString(或 Java 的 StringJoiner)
    println(listOf("red", "green", "blue").joinToString(", ", "[", "]"))
}

结果:

> gradlew -q run -Pmain=strings06.Strings06Kt
XYZTstabCD
str3[0]=x, str3=xYZTstabCD
rialcé
line 1
line 2
line 3
a, b, c
total=  42.0
41 characters
+-------+-------+
|     1 |     1 |
|     2 |     4 |
|     3 |     9 |
+-------+-------+
[red, green, blue]

说明:

  • 第 6 行:修改方法返回 [StringBuilder] 对象本身,因此可以将它们链式调用。我们来逐步看:“test”变为“testabCD ”([append]),然后是 "texyZTstabCD"([insert] 在位置 2),接着是 "xyZTstabCD "([delete] 删除第 0 和第 1 个字符),最后是 "XYZTstabCD"([replace] 将第 0 和第 1 个字符替换为 "XY")。请注意,与 [replace] 来自 [String]的函数不同,来自 [StringBuilder] 的函数不会搜索文本:它替换的是一段位置范围。[println] 通过调用对象的函数 [toString]来显示对象;
  • 第 8–9 行:[[]] 运算符像数组一样读取和修改字符;[str3[0] = 'x'] 调用 [str3.setCharAt(0, 'x')]。在模板中,[$str3] 调用 [toString];
  • 第 11 行:[reverse] 反转文本。对于字符串 [String],在 [reversed] 函数(见 [Strings01.kt])更简单;
  • 第 14–16 行:通过连续添加来构建多行文本——这是 [StringBuilder] 的典型用法。这些添加操作被链接在同一行代码中;
  • 第 19–20 行:函数 [joinTo] 是 [joinToString] 的对应函数:它不创建新字符串,而是将以分隔符隔开的元素追加到已有的 [StringBuilder](更准确地说,是任何 [Appendable] 对象)中;[appendLine] 随后添加一个换行符;
  • 第 23 行:添加一个格式化字符串。[%f] 转换需要实数:传入整数 [total] 会在运行时抛出 [IllegalFormatConversionException] 异常,因此才有 [total.toDouble()] 转换;
  • 第 25 行:以字符串 [String] 的形式获得最终文本;
  • 第 30–35 行:函数 [buildString] 创建一个 [StringBuilder],执行紧随其后的 lambda,然后将构建好的文本以 [String] 返回。在 lambda 中,[StringBuilder] 是隐式 接收者 ([this]):我们写 [appendLine(...)] 而不是 [sb.appendLine(...)]。这种 lambda 称为 带接收者的 lambda,将在第 7 章介绍;它让你可以写出可读性极高的“积木式”代码。变量 [table] 是一个不可变的 [String],由 [val] 声明,而中间的 [StringBuilder] 甚至不可见。还请注意 [padStart] 如何让数字在列内右对齐;
  • 第 40 行:对于带有前缀和后缀、以分隔符隔开的元素序列,[joinToString] 提供了 Java 类 [java.util.StringJoiner] 的功能,后者仍可使用,但在 Kotlin 中意义不大。

对于少量的拼接,[+] 运算符和模板就足够了:编译器会对它们进行优化。当添加次数很多或未知时,通常是在循环中,首选 [StringBuilder] (或 [buildString]):在 n 次迭代的循环中使用 [s += ...] 拼接,会创建 n 个字符串,并且在每次迭代中复制之前已构建的整个字符串。在较旧的 Java 代码中,你可能会遇到 [StringBuffer] 类,它与 [StringBuilder] 具有相同的方法,但使这些方法可被多个线程同时使用,代价是一些性能开销:如今,相比之下更推荐 [StringBuilder]。

5.2.6. 无需复制地解析字符串

每次调用 [substring] 或 [split] 都会在内存中创建新的字符串。在对性能要求严格的代码中(例如分析大文件或网络请求),你可能希望避免创建新字符串。Kotlin 和 Java 的语言本身都没有内置“子字符串”类型,但有几个函数可以在不复制的情况下操作字符串的一部分。程序 [Strings07.kt] 比较了几种解析“姓:名:年龄”格式行的方法:

package strings07

import java.nio.CharBuffer

// 不创建子字符串而解析字符串
fun main() {
    val line = "dupont:jean:45"

    // 惯用写法:split 和解构;每个字段都是一个新字符串
    val (lastName1, firstName1, age1) = line.split(':')
    println("split : lastName=$lastName1, firstName=$firstName1, age=${age1.toInt()}")

    // 用 substring:每个字段同样是在内存中分配的新字符串
    val p1 = line.indexOf(':')
    val p2 = line.lastIndexOf(':')
    val lastName = line.substring(0, p1)
    var age = line.substring(p2 + 1).toInt()
    println("substring : lastName=$lastName, age=$age")

    // 对字符串的一部分使用 JDK 的 Integer.parseInt:没有中间字符串
    age = Integer.parseInt(line, p2 + 1, line.length, 10)
    // regionMatches 不复制而将字符串的一部分与另一个字符串比较
    val du = line.regionMatches(0, "du", 0, 2)
    println("parseInt(line, start, end, radix) : age=$age, the last name starts with \"du\" : $du")

    // 字符串一部分的视图:CharBuffer.wrap 不复制字符
    val nameView: CharSequence = CharBuffer.wrap(line, 0, p1)
    println("view : lastName=$nameView, length of the view=${nameView.length}, nameView[0]=${nameView[0]}")
    // Kotlin 函数接受 CharSequence
    val nbP = nameView.count { it == 'p' }
    println("nameView.startsWith(\"dup\")=${nameView.startsWith("dup")}, number of 'p' in the view=$nbP")

    // 从某个位置开始的 indexOf:在 p1 之后搜索 ':'
    println("indexOf(':', p1 + 1)=${line.indexOf(':', p1 + 1)}")

    // 只有在确实需要时才创建字符串
    val firstName = line.substring(p1 + 1, p2)
    println("firstName=$firstName")
}

结果:

1
2
3
4
5
6
7
8
> gradlew -q run -Pmain=strings07.Strings07Kt
split : lastName=dupont, firstName=jean, age=45
substring : lastName=dupont, age=45
parseInt(line, start, end, radix) : age=45, the last name starts with "du" : true
view : lastName=dupont, length of the view=6, nameView[0]=d
nameView.startsWith("dup")=true, number of 'p' in the view=1
indexOf(':', p1 + 1)=11
firstName=jean

说明:

  • 第 10 行:这是 Kotlin 中最易读也最常见的方式:[split] 返回一个包含三个字符串的列表,通过 解构 (第 3 章)将其赋给三个变量;[toInt] 然后将年龄转换为整数。不过,这样会创建一个列表和三个字符串;
  • 第 16–17 行:使用 [substring] 时,每次调用都会创建一个新字符串,即使像年龄这样只是临时用一下;
  • 第 21 行:Kotlin 函数 [toInt] 只适用于字符串;但 JDK 的静态方法 [Integer.parseInt] 有一个重载(Java 9),可以从指定的进制(此处为 10)出发,解析字符串中两个位置之间的字符,而无需创建子字符串。Kotlin 程序可以直接调用它:这正是与 Java 互操作的意义所在;
  • 第 23 行:[regionMatches](我们已经见过)无需复制,就能将字符串的一部分与另一个字符串进行比较;
  • 第 27 行:[CharBuffer.wrap] (JDK 的 [java.nio] 包)返回 视图 ,覆盖字符串中第 0 到 [p1] - 1 个字符:这个对象并不包含字符的副本,而是提供了访问它们的途径。它实现了 [CharSequence] 接口,[String] 和 [StringBuilder] 也是如此。请注意,该接口的成员,即 [String] 的 [subSequence] 函数,并不是视图:对于字符串,它会像 [substring] 一样创建字符的副本(而对于 *[CharBuffer] 则返回视图)。Kotlin 将该接口的 Java 方法 ***[charAt] 视为运算符 ***[[]],并将其方法 [length()] 视为属性 *[length];
  • 第 30–31 行:*[kotlin.text] 的许多扩展函数并非定义在 *[String]* 上,而是定义在 [CharSequence] 上:[startsWith]、[count]、[contains]、[indexOf]、[split]、[lines]……因此它们也适用于视图,或适用于 [StringBuilder],而无需先将其转换为 [String]。我们将在本章末尾介绍的正则表达式,也接受 [CharSequence]*;
  • 第 34 行:[indexOf] 的第二个参数是搜索的起始位置;
  • 第 37 行:只有在确实需要时才会创建字符串。

这些技巧属于优化工具:对于普通程序,[split] 和 [substring] 完全够用。此外,虚拟机对仅包含 Latin-1 字符集字符的字符串(法语文本即是如此)每个字符只用一个字节而不是两个字节来存储(“紧凑字符串”,Java 9),这使其占用的内存减半;Kotlin 字符串就是 Java 字符串,因此也能从中受益。我们只会在经测量确认对性能至关重要的代码中才尝试避免复制。

5.3. 数组

5.3.1. 数组扩展函数

我们在第 3 章中看到,Kotlin 有两种类型的数组:对象数组 [Array<T>] (由 [arrayOf]创建),以及基本类型数组 [IntArray]、[DoubleArray]、[CharArray]……(由 [intArrayOf]、[doubleArrayOf]……创建),它们被编译为 Java 基本类型数组([int[]]、[double[]]……)。在 Java 中,数组没有任何有用的方法:除了字段 [length]之外,所有操作都是工具类 [java.util.Arrays] 的静态方法。在 Kotlin 中,数组有属性 [size]、运算符 [[]],最重要的是,还有数十个 扩展函数 来自标准库(包 [kotlin.collections]),它们像方法一样被调用:[array.sort()] 而不是 [Arrays.sort(array)]。它们可以对数组进行排序、在其中搜索元素、复制、填充……它们适用于每种类型的数组([IntArray]、[DoubleArray]……、[Array<T>]),并且大多通过 JVM 调用 [Arrays] 类的方法。

函数
作用
[binarySearch(element, fromIndex = 0, toIndex = size)]
返回 [element] 在数组中的位置(数组必须已排序);如果 [element] 不存在则返回负数
[copyOf(newSize: Int)]
返回一个包含 [newSize] 个元素的新数组,其中包含原数组的前若干个元素,必要时用零填充 (布尔数组用 [false] 填充);对于 [Array<T>],结果是用 [Array<T?>] 填充 [null]。不带参数时,返回相同大小的副本
[copyOfRange(fromIndex: Int, toIndex: Int)]
返回一个新数组,由从 [fromIndex] (含)到 [toIndex] (不含)的元素组成;[sliceArray(range)] 对区间执行相同的操作
[copyInto(destination, destinationOffset = 0, startIndex = 0, endIndex = size)]
将数组的元素复制到另一个已有的数组中(等价于 [System.arraycopy])
[contentEquals(other)]
如果两个数组具有相同顺序的相同元素,则返回 [true]
[fill(element, fromIndex = 0, toIndex = size)]
将 [element] 赋给数组的所有元素或某个索引范围内的元素
[sort()]、[sort(fromIndex, toIndex)]
按元素的自然顺序对数组或某个索引范围进行排序;[sortWith(comparator)] 按 [Comparator] 对对象数组排序(第 4 章);[sortDescending()] 按降序排序
[sorted()]、[sortedWith(comparator)]
返回一个已排序的 列表 ,而不修改数组
[reverse()]、[reversed()]
反转数组;返回一个反转后的列表
[contentToString()]
将数组元素转换为字符串 [[e1, e2, ...]];[contentDeepToString] 对数组的数组执行相同的操作
[indexOf(element)]、[lastIndexOf(element)]、[contains(element)]
线性搜索:[element] 的第一个或最后一个位置,或 -1;[element] 是否存在([element in array])
[asList()]
返回一个作为该数组视图的列表
[toList()]、[toMutableList()]
返回一个包含数组元素的新列表,该列表为只读或可编辑
[plus(element)]
返回一个大一个元素的新数组,由原数组的元素后接 [element] 组成;写作 [array + element]

此外,还有数组和集合通用的函数([sum]、[max]、[count]、[filter]、[map]、[joinToString]……),我们将在后面介绍。

程序 [Arrays01.kt] 演示了其中一些函数的用法:

package arrays01

// 搜索类型
enum class SearchType { LINEAR, BINARY }

// 数组的扩展函数:扩容、排序、搜索
fun main() {
    // 读取键盘输入的数组元素
    val elements = input()
    // 显示未排序的数组
    display("Unsorted array", elements)
    // 在未排序的数组中线性搜索
    search(elements, SearchType.LINEAR)
    // 对数组排序
    elements.sort()
    // 显示已排序的数组
    display("Sorted array", elements)
    // 在已排序的数组中二分搜索
    search(elements, SearchType.BINARY)
}

// 输入数组的值:返回创建的数组
fun input(): DoubleArray {
    // 开始时,数组为空
    var elements = doubleArrayOf()
    // 数组元素的输入循环
    while (true) {
        val answer = read("Element (real) ${elements.size} of the array (nothing to finish): ")
        // 如果是空字符串则输入结束
        if (answer.isEmpty()) break
        // 检查输入:如果字符串不是数字则为 null
        val element = answer.toDoubleOrNull()
        if (element == null) {
            println("Incorrect input, try again")
            continue
        }
        // 多一个元素:我们创建一个大一格的新数组,其中包含该元素
        elements += element
    }
    return elements
}

// 显示数组的元素
fun display(text: String, elements: DoubleArray) {
    println(text + "-".repeat(50 - text.length))
    for (element in elements) {
        println(element)
    }
}

// 在数组中搜索键盘输入的元素
fun search(elements: DoubleArray, type: SearchType) {
    while (true) {
        val answer = read("Element searched for (nothing to stop): ")
        // 结束了吗?
        if (answer.isEmpty()) break
        // 检查
        val element = answer.toDoubleOrNull()
        if (element == null) {
            println("Error, try again...")
            continue
        }
        // 我们在数组中搜索该元素
        val i = when (type) {
            SearchType.BINARY -> elements.binarySearch(element)  // 已排序的数组
            SearchType.LINEAR -> elements.indexOfFirst { it == element }  // 任意数组
        }
        // 显示答案
        println(if (i >= 0) "Found at position $i" else "Not in the array ($i)")
    }
}

// 读取键盘上的一行,去除两侧空格;流结束时为 ""
fun read(prompt: String): String {
    print(prompt)
    return readlnOrNull()?.trim() ?: ""
}

说明:

  • 第 4 行:一个枚举(第 3 章),在文件级别声明;
  • 第 23–40 行:函数 [input] 输入通过键盘键入的数组元素。由于事先不知道元素的数量,该函数从一个空数组开始(第 25 行),并在每次新输入时将数组扩展一个元素(第 38 行)。数组的大小在创建时就已确定:运算符 [+] ([plus])实际上会创建一个大一个元素的新数组,将旧数组的元素复制到其中,并添加新元素;[elements += element] 在这里指的是 [elements = elements + element],因此 [elements] 要用 [var] 声明。这相当于用一条语句完成了以下两条 Java 语句:[elements = Arrays.copyOf(elements, elements.length + 1)] 和 [elements[elements.length - 1] = element]。更高效的算法会按每组 N 个元素来分配空间。数组并非为调整大小而设计:这种场景用可变列表处理更好,我们稍后就会看到;
  • 第 32–35 行:通过 [toDoubleOrNull] 将输入的字符串转换为浮点数,如果字符串不是数字,则返回 [null] (第 3 章)。在 [element == null] 检查之后接着 [continue],编译器就知道 [element] 不是 [null]:它的类型变为 [Double] (智能类型转换),因此可以将它添加到数组中。[toDoubleOrNull] 不依赖于机器的语言设置:它始终要求使用小数点,并拒绝输入“3,6”(结果的第 4 行);
  • 第 52–69 行:函数 [search] 在数组中搜索从键盘输入的值。[when] 函数(第 64 行)根据所请求的类型选择搜索方法;由于它作用于一个枚举并处理了其所有值,因此不需要 [else] 分支。对于未排序的数组,执行线性搜索,逐个检查元素。标准库没有针对实数数组 [indexOf] 的函数 [DoubleArray]:它已被移除,因为比较实数是否相等会对特殊值 [NaN] 和 [-0.0]造成问题;[elements.indexOf(element)] 会被编译器拒绝([unresolved reference 'indexOf'])。因此我们使用 [indexOfFirst],它返回满足 lambda 所表达条件的第一个元素的位置,或 -1;与 Java 不同,无需自己编写搜索函数。对于已排序的数组,我们使用 [binarySearch] 执行二分搜索,它在每一步都将搜索范围减半:在一百万个元素中找到某个元素只需约二十次比较;
  • 第 15 行:对数组进行排序,这里是按数字的自然顺序。[elements] 在 [val] 中由 [main] 声明:该变量始终指向同一个数组,但其内容可以被修改。[val] 使 引用 成为常量,而不是对象;
  • 第 44–47 行:显示数组。[println] 显示 [Double] 时带小数点,与机器的语言设置无关,并且始终至少有一位小数:-7 显示为 -7.0;
  • 第 74–76 行:[print] 显示提示而不换行,然后 [readlnOrNull] 读取键盘键入的一行;如果标准输入已耗尽(例如输入来自文件),它返回 [null] 。安全调用 [?.trim()] 和 Elvis 运算符 [?: ""] 随后返回一个空字符串。

结果:

> gradlew -q run -Pmain=arrays01.Arrays01Kt
Element (real) 0 of the array (nothing to finish): 3.6
Element (real) 1 of the array (nothing to finish): 7.4
Element (real) 2 of the array (nothing to finish): -1.5
Element (real) 3 of the array (nothing to finish): 3,6
Incorrect input, try again
Element (real) 3 of the array (nothing to finish): -7
Element (real) 4 of the array (nothing to finish):
Unsorted array------------------------------------
3.6
7.4
-1.5
-7.0
Element searched for (nothing to stop): 7.4
Found at position 1
Element searched for (nothing to stop): 0
Not in the array (-1)
Element searched for (nothing to stop):
Sorted array--------------------------------------
-7.0
-1.5
3.6
7.4
Element searched for (nothing to stop): 7.4
Found at position 3
Element searched for (nothing to stop): 0
Not in the array (-3)
Element searched for (nothing to stop):

当要搜索的元素不存在时,[indexOfFirst] 返回 -1,而 [binarySearch] 返回一个负数(最后一次搜索):这个数是 [-(p + 1)],其中 p 是为保持数组有序而应插入该元素的位置。这里,-3 = -(2 + 1):数字 0 应插入到位置 2,即 -1.5 和 3.6 之间。注意:在未排序的数组上使用 [binarySearch] 会返回无意义的结果。

5.3.2. 其他数组函数

程序 [Arrays02.kt] 提供了更多的数组扩展函数:

package arrays02

import java.text.Collator
import java.util.Locale

// 数组的其他扩展函数
fun main() {
    val numbers = intArrayOf(40, 10, 30, 20, 50)
    display("numbers", numbers.contentToString())

    // 对数组的一部分排序:索引 1 到 3 的元素(不含 4)
    numbers.sort(1, 4)
    display("after sort(1, 4)", numbers.contentToString())

    // 将 3 个元素复制到另一个数组
    val copy = IntArray(5)
    numbers.copyInto(copy, destinationOffset = 0, startIndex = 0, endIndex = 3)
    display("copyInto", copy.contentToString())
    // copyOf、copyOfRange:副本是一个新数组,被截短或用 0 填充
    display("copyOf(7)", numbers.copyOf(7).contentToString())
    display("copyOfRange(1, 3)", numbers.copyOfRange(1, 3).contentToString())

    // fill:用一个值填充数组或数组的一部分
    copy.fill(7)
    display("after fill(7)", copy.contentToString())
    copy.fill(0, 1, 3)
    display("after fill(0, 1, 3)", copy.contentToString())

    // 两个数组的相等性:=== 比较引用,contentEquals 比较内容
    val other = intArrayOf(7, 0, 0, 7, 7)
    println("copy === other : ${copy === other}, copy contentEquals other : ${copy contentEquals other}")

    // 数组有 indexOf、lastIndexOf、reverse……
    val colors = arrayOf("red", "green", "blue", "green")
    println("indexOf(green)=${colors.indexOf("green")}, lastIndexOf(green)=${colors.lastIndexOf("green")}"
            + ", indexOf(black)=${colors.indexOf("black")}, \"blue\" in colors=${"blue" in colors}")
    // ……以及 asList:作为数组视图的列表
    val view: List<String> = colors.asList()
    colors.reverse()
    display("after reverse, view", view.toString())
    // toList:作为数组副本的列表
    val listCopy = colors.toList()
    colors[0] = "black"
    display("after colors[0] = black", "view=$view, listCopy=$listCopy")

    // 对字符串数组排序:按字符码顺序
    val words = arrayOf("essay", "Zoé", "éclair", "apricot")
    // sorted 返回已排序的列表,不修改数组
    display("words.sorted()", words.sorted().toString())
    // 按法语规则排序
    words.sortWith(Collator.getInstance(Locale.FRANCE))
    display("words sorted (Collator)", words.contentToString())

    // 对数组的一些计算
    println("sum=${numbers.sum()}, average=${numbers.average()}, max=${numbers.max()}, "
            + "count { it > 25 }=${numbers.count { it > 25 }}")

    // 二维数组是数组的数组
    val matrix = Array(2) { IntArray(3) }
    matrix[1][2] = 5
    println("matrix.size=${matrix.size}, matrix[0].size=${matrix[0].size}, "
            + "contentDeepToString=${matrix.contentDeepToString()}")
    // 由接收索引的 lambda 初始化的数组
    val squares = IntArray(5) { i -> i * i }
    display("IntArray(5) { i -> i * i }", squares.contentToString())
}

// 在一行中显示文本和数组
fun display(text: String, array: String) {
    println("%-28s: %s".format(text, array))
}

结果:

> gradlew -q run -Pmain=arrays02.Arrays02Kt
numbers                     : [40, 10, 30, 20, 50]
after sort(1, 4)            : [40, 10, 20, 30, 50]
copyInto                    : [40, 10, 20, 0, 0]
copyOf(7)                   : [40, 10, 20, 30, 50, 0, 0]
copyOfRange(1, 3)           : [10, 20]
after fill(7)               : [7, 7, 7, 7, 7]
after fill(0, 1, 3)         : [7, 0, 0, 7, 7]
copy === other : false, copy contentEquals other : true
indexOf(green)=1, lastIndexOf(green)=3, indexOf(black)=-1, "blue" in colors=true
after reverse, view         : [green, blue, green, red]
after colors[0] = black     : view=[black, blue, green, red], listCopy=[green, blue, green, red]
words.sorted()              : [Zoé, apricot, essay, éclair]
words sorted (Collator)     : [apricot, éclair, essay, Zoé]
sum=150, average=30.0, max=50, count { it > 25 }=3
matrix.size=2, matrix[0].size=3, contentDeepToString=[[0, 0, 0], [0, 0, 5]]
IntArray(5) { i -> i * i }  : [0, 1, 4, 9, 16]

说明:

  • 第 9 行:[contentToString] 在一行中显示数组。如果直接使用 [println(numbers)] 或 ["$numbers"] 显示数组,会得到类似 [[I@1b6d3586]] 的文本:类型([[I]],JVM 中的整数数组)和对象的标识符,而没有其元素。Kotlin 数组就是 Java 数组,具有相同的 [toString];
  • 第 12 行:只对索引 1 到 3 的元素进行排序,不含第二个索引:10、30、20 变为 10、20、30;
  • 第 16–17 行:[IntArray(5)] 创建一个包含 5 个零的整数数组。[copyInto] 将 [numbers] 的前 3 个元素复制到 [copy] 的开头,而其他元素保持其初始值 0。它的参数有默认值,并且在这里使用了命名参数,这使得该调用比 Java 中的 [System.arraycopy(numbers, 0, copy, 0, 3)] 可读得多;
  • 第 20–21 行:[copyOf] 和 [copyOfRange] 创建新数组。比原数组更长的数组会用零填充;
  • 第 24–26 行:[fill] 填充数组,然后将索引 1 和 2(不含索引 3)的元素重置为 0。请注意,参数顺序与 Java 中不同:先是值,然后是索引范围;
  • 第 30–31 行:对于数组——与字符串和集合不同——[] 运算符比较的是 引用:数组没有比较内容的 [equals] 函数。编译器知道这一点,如果你写 [copy == other],它会用警告标出这一可能的错误:**[warning: '' on arrays compares only references. Replace '' with 'contentEquals' to compare the arrays' contents or use '=' to remove the warning.] (由于我们的项目将警告视为错误,编译会失败)。因此,我们用 [===] 比较引用,用 [contentEquals] 比较内容。这里使用 [contentEquals] 的是 中缀* 表示法([copy contentEquals other]*),不带点号和括号,这是其声明中的修饰符 [infix] 所允许的(第 4 章);
  • 第 34–36 行:对象数组直接支持搜索函数 [indexOf] 和 [lastIndexOf],以及运算符 [in]。在 Java 中,必须使用 [Arrays.asList] 才能访问它们;
  • 第 38–40 行:[asList] 返回一个 [List] (将在下一节介绍),它是数组的 视图 :它不复制数组,而是提供使用列表函数访问数组的方式。函数 [reverse] 反转数组本身;由于列表是数组的视图,它的元素也被反转(结果的第 10 行)。与 Java 不同,[reverse] 适用于所有类型的数组,包括 [IntArray];
  • 第 42–44 行:另一方面,[toList], 返回数组元素的一个 副本 ,以列表形式呈现。修改数组的第 0 号元素后,视图会反映该变化,而副本不会(结果的第 11 行)。这一点很重要:视图高效,但会反映对原对象的所有更改;副本则独立于原对象;
  • 第 49 行:字符串数组按照上文所见的 [compareTo] 函数的顺序排序,也就是按字符编码排序:大写字母(编码 65 到 90)排在小写字母(97 到 122)之前,而小写字母又排在带重音的字母(é:233)之前。“Zoé”是第一个单词,“éclair”是最后一个。[sorted] 返回一个已排序的列表,并保持数组不变;
  • 第 51 行:要按照法语规则排序,我们向 [Collator]*(它是一个字符串的 *[Comparator] )传递一个对象给 [sortWith];数组本身会被排序;
  • 第 55–56 行:数组还与集合共享通用的计算函数:求和、平均值、最大值、满足某个条件的元素个数……我们将在讨论集合时介绍这些函数;
  • 第 59–62 行:Kotlin 与 Java 一样,没有二维矩形数组:数组的数组是用 [Array(2) { IntArray(3) }] 创建的,即一个包含 2 个元素的数组,其中每个元素都由 lambda 创建:一个包含 3 个整数的数组。[matrix.size] 是行数,[matrix[0].size] 是 第 0 行的元素个数。[contentDeepToString] 显示数组的数组;
  • 第 64 行:更一般地说,构造函数 [Array]、[IntArray]……接受一个大小和一个 lambda,该 lambda 根据索引计算每个元素:这里是 0 到 4 的整数的平方。

请记住,在 Kotlin 中,数组主要用于性能方面的原因(基本类型数组)、用于 [vararg] 参数,以及与 Java 库交互。对于其他所有情况,更推荐使用 集合——尤其是列表,将在下一节介绍。

5.4. 集合

除了数组之外,Kotlin 还提供了各种用于存储元素集合的集合。在 JVM 上,Kotlin 并没有重写集合类:它使用来自 Java 集合 框架 (包 [java.util]、[ArrayList]、[HashMap]、[LinkedHashMap]、[HashSet]……)的那些类,它们通过 [kotlin.collections] 包中的 类型别名 无需 [import] 即可使用。此外,它通过 自己的接口来呈现它们,这些接口围绕着 Java 在其类型中没有做出的一个区分来组织:只读集合和 可变集合。

接口
作用
实现和构造函数
[List<E>]
[MutableList<E>]
有序的元素序列,可通过位置访问
[ArrayList];[listOf]、[mutableListOf]、[arrayListOf]、[buildList]、[emptyList]
[Set<E>]
[MutableSet<E>]
集:没有重复项
[LinkedHashSet]、[HashSet]、[java.util.TreeSet];[setOf]、[mutableSetOf]、[hashSetOf]、[sortedSetOf]
[Map<K, V>]
[MutableMap<K, V>]
字典:(键,值)对,其中的键是唯一的
[LinkedHashMap]、[HashMap]、[java.util.TreeMap];[mapOf]、[mutableMapOf]、[hashMapOf]、[sortedMapOf]
[ArrayDeque<E>]
双端队列,可用作队列或栈(Kotlin 特有的类)
[ArrayDeque]

接口 [List] 和 [Set] 派生自接口 [Collection<E>] ([size]、[isEmpty]、[contains]……),而它本身又派生自 [Iterable<E>],这是可以用 [for] 循环迭代的对象的接口。这些接口只有 读取函数:[List<String>] 既没有 [add] 函数,也没有 [remove] 函数。修改函数([add]、[remove]、[clear]、[[i] = value]……)由派生接口 [MutableIterable]、[MutableCollection]、[MutableList]、[MutableSet]、和 [MutableMap]声明。[ArrayList] 实现了 [MutableList],因此也实现了 [List]。因此,[val] 和 [var] 的规则同样适用于集合:只要集合不需要修改——例如作为函数参数时——就选择只读类型,编译器会禁止通过该类型进行任何修改。

在 JVM 上,这些接口只在编译时存在:[List] 和 [MutableList] 都被编译为 [java.util.List] 接口。这使得 Kotlin 列表可以不经转换就传递给 Java 方法——反之亦然。从 Java 方法接收到的集合在 Kotlin 中具有 平台类型,在编译器消息中表示为 [(Mutable)List<String!>] :Kotlin 不知道它是否可变,也不知道其元素是否可以为 [null],而是留给程序员来判断。

与 Java 一样,最佳实践是用接口类型声明变量和参数,并在创建时选择实现,最常见的方式是通过 构造函数:[val cities: MutableList<String> = mutableListOf()]。请注意,Kotlin 的构造函数为集和字典选择的实现会 保持 元素 的添加顺序 ([LinkedHashSet]、[LinkedHashMap]):这一点常常是 Kotlin 程序与其 Java 等价程序的区别所在,后者使用的是 [HashSet] 和 [HashMap]。

集合只包含 对象。Kotlin 在语言层面没有可见的基本类型,我们写 [List<Int>];但在 JVM 中,这样的列表的元素是 [java.lang.Integer] 对象,编译器在添加元素时会自动将 [Int] 转换为 [Integer] ,读取时则反过来(“装箱”和“拆箱”)。这种转换在 Kotlin 中是透明的,其开销与 Java 中相同:一个包含一百万个整数的列表包含一百万个 [Integer] 对象。对于大量数字,最好使用 [IntArray] 数组。

[java.util] 包还包含 Java 1.0 的集合:[Vector] (列表)、[Hashtable] (字典)和 [Stack] (栈)。它们已经 过时:由于它们的每个操作都是同步的,所以比其替代品更慢,不应再使用。至于 Java 的 原始类型 (不带类型参数的泛型集合,即用 [List] 代替 [List<String>]),它们在 Kotlin 中并不存在:类型参数是必需的,或者由编译器推断。

5.4.1. 列表与 ArrayList 类

类 [ArrayList<E>] 实现了一个类型为 [E] 的对象的可修改列表,其大小在程序执行期间可变。它将元素存储在一个会自动扩展的内部数组中,类似于 [StringBuilder]。这就是由 [mutableListOf] 和 [arrayListOf] 创建的实现。由 [listOf] 创建的只读列表在 JVM 中是来自 Java 库的固定大小的列表(对参数数组使用 [Arrays.asList] ,或针对单个元素的专用列表,或空列表)。列表 [l] 的第 i 个元素通过 [l[i]] 获取,并(如果列表可修改)通过 [l[i] = value]修改:运算符 [get] 和 [set] (第 4 章)取代了 Java 方法 [get(i)] 和 [set(i, value)]。

下面是 [List<E>] 和 [MutableList<E>] 接口的部分函数:

函数
作用
[size: Int]
属性:列表中的元素个数;[indices] 是索引范围,[lastIndex] 是 最后一个索引
[l[index]]、[getOrNull(index)]、[getOrElse(index) { ... }]
读取第 [index] 个元素;如果索引无效,则抛出异常 [IndexOutOfBoundsException] ,但 [getOrNull] (返回 [null])和 [getOrElse] (返回由 lambda 计算出的值)除外
[first()]、[last()]、[firstOrNull()]、[lastOrNull()]
分别为第一个和最后一个元素;如果列表为空则抛出异常,但变体 [OrNull] 除外
[contains(element)]
如果 [element] 在列表中,则返回 [true] ;写作 [element in list]
[indexOf(element)]、[lastIndexOf(element)]
返回 [element] 在列表中的第一个或最后一个位置,或 -1
[subList(fromIndex, toIndex)]
返回从 [fromIndex] (含)到 [toIndex] (不含)的元素的视图;[slice(range)] 返回一个副本
[sorted()]、[sortedDescending()]、[sortedWith(comparator)]、[reversed()]
返回一个新的列表:已排序、按降序排序、按 [Comparator] 排序、已反转
[binarySearch(element)]
在已排序列表中进行二分搜索
[toTypedArray()]、[toMutableList()]
将列表的元素返回为数组,或一个新的可编辑列表
[add(element)]、[add(index, element)]
([MutableList])将 [element] 添加到列表末尾,或位置 [index];运算符 [+=] 可添加一个元素或一个集合
[addAll(elements)]
([MutableList])将一个集合的元素添加到列表末尾
[l[index] = element]
([MutableList])替换第 [index] 个元素
[remove(element)]、[removeAt(index)]
([MutableList])删除 [element] 的第一次出现(如果操作成功,则结果为 [true] )、第 [index] 个元素(返回被删除的元素)
[removeFirst()]、[removeLast()]、[removeIf { ... }]
([MutableList])分别删除第一个元素、最后一个元素,以及满足某个条件的元素
[clear()]
([MutableList])删除列表中的所有元素
[sort()]、[sortDescending()]、[sortWith(comparator)]、[reverse()]、[shuffle()]
([MutableList])对列表本身进行排序、反转和打乱

请注意库的命名约定,我们在数组中已经见过:动词([sort]、[reverse]、[shuffle])修改集合本身,且只存在于可修改的集合中;过去分词([sorted]、[reversed]、[shuffled])返回一个新集合,并保持原集合不变。Java 工具类 [java.util.Collections] 的函数([Collections.sort(list)]……)仍然可用,但这些扩展函数使它们变得不再必要。

让我们回顾之前用数组处理过的示例,现在用一个由实数组成的可变列表 [MutableList<Double>] 来处理它。由于列表与数组类似,代码改动很小。下面是程序 [Collections01.kt]:

package collections01

// 搜索类型
enum class SearchType { LINEAR, BINARY }

// 列表:用列表重写的 Arrays01.kt 程序
fun main() {
    // 读取键盘输入的列表元素
    val elements = input()
    // 元素数量
    println("The list has ${elements.size} elements")
    // 显示未排序的列表
    display("Unsorted list", elements)
    // 在未排序的列表中线性搜索
    search(elements, SearchType.LINEAR)
    // 按元素的自然顺序对列表排序
    elements.sort()
    // 显示已排序的列表
    display("Sorted list", elements)
    // 在已排序的列表中二分搜索
    search(elements, SearchType.BINARY)
}

// 输入列表的值:返回创建的列表
fun input(): MutableList<Double> {
    // 开始时,列表为空
    val elements = mutableListOf<Double>()
    // 列表元素的输入循环
    while (true) {
        val answer = read("Element (real) ${elements.size} of the list (nothing to finish): ")
        // 如果是空字符串则输入结束
        if (answer.isEmpty()) break
        // 检查输入
        val element = answer.toDoubleOrNull()
        if (element == null) {
            println("Incorrect input, try again")
            continue
        }
        // 列表多一个元素:它会自行增长
        elements.add(element)
    }
    return elements
}

// 显示任意集合元素的泛型函数
fun <T> display(text: String, elements: Iterable<T>) {
    println(text + "-".repeat(50 - text.length))
    for (element in elements) {
        println(element)
    }
}

// 在列表(只读)中搜索键盘输入的元素
fun search(elements: List<Double>, type: SearchType) {
    while (true) {
        val answer = read("Element searched for (nothing to stop): ")
        // 结束了吗?
        if (answer.isEmpty()) break
        // 检查
        val element = answer.toDoubleOrNull()
        if (element == null) {
            println("Error, try again...")
            continue
        }
        // 我们在列表中搜索该元素
        val i = when (type) {
            SearchType.BINARY -> elements.binarySearch(element)  // 已排序的列表
            SearchType.LINEAR -> elements.indexOf(element)  // 任意列表
        }
        // 显示答案
        println(if (i >= 0) "Found at position $i" else "Not in the list ($i)")
    }
}

// 读取键盘上的一行,去除两侧空格;流结束时为 ""
fun read(prompt: String): String {
    print(prompt)
    return readlnOrNull()?.trim() ?: ""
}

说明:

  • 第 27 行:列表由函数 [mutableListOf] 创建为空列表,该函数创建一个 [ArrayList]。元素类型 [Double] 被指定为函数的类型参数,因为无法从空列表中推断出来;我们也可以写成 [val elements: MutableList<Double> = mutableListOf()] 或 [val elements = ArrayList<Double>()];
  • 第 40 行:不再需要管理扩容;列表会自动扩展。我们本可以写成 [elements += element]:对于由 [val] 声明的可变列表,运算符 [+=] 将元素添加到列表中([plusAssign]),而对于 [var] 声明的 [Arrays01.kt] 中的数组,它创建的是一个新数组。变量 [elements] 在这里是一个 [val]:它始终指向同一个列表,只是列表的内容发生变化;
  • 第 25 行:函数 [input] 返回一个可修改的列表,因为主程序必须能够对其排序;
  • 第 11 行:列表中的元素个数是属性 [size],与数组相同。与 [StringBuilder] 不同,[ArrayList] 不允许你查询其容量;[ensureCapacity] 方法只允许你预先设置容量;
  • 第 17、67、68 行:排序和二分搜索由列表的扩展函数 [sort] 和 [binarySearch] 完成,而线性搜索由其函数 [indexOf] 完成。对于 类型 [Double] 的列表,[indexOf] 是存在的,这与数组 [DoubleArray] 不同:它像 Java 一样,使用元素的 [equals] 函数来比较元素;
  • 第 54 行:函数 [search] 不会修改列表:它的参数声明为类型 [List<Double>],这是只读的。你可以向它传递一个 [MutableList<Double>],因为它 是 一个 [List<Double>]。如果它试图修改列表——例如使用 [elements.add(element)]——编译器会拒绝:[unresolved reference 'add' on receiver of type 'List<Double>']。因此,参数类型既说明又保证了该函数不会更改列表;
  • 第 46–49 行:泛型函数 [display] 接受两个参数:
    • 第一个是要写出的文本;
    • 第二个是实现泛型接口 [Iterable<T>] 的对象,该接口唯一的函数是 [operator fun iterator(): Iterator<T>]。

循环 [for (element in elements)] 对任何具有函数 [operator fun iterator()] 的对象都有效,无论它是成员函数还是扩展函数:所有集合都是如此,它们实现了 [Iterable],数组、字符串、区间等也是如此……数组并不实现 [Iterable]:[display] 函数不适合用于数组,除非向它传递 [array.asList()]。我们在讨论序列时会再回到这个接口。

结果(在命令行中;键盘输入出现在提示之后):

> gradlew -q run -Pmain=collections01.Collections01Kt
Element (real) 0 of the list (nothing to finish): 3.6
Element (real) 1 of the list (nothing to finish): 7.4
Element (real) 2 of the list (nothing to finish): -1.5
Element (real) 3 of the list (nothing to finish): -7
Element (real) 4 of the list (nothing to finish):
The list has 4 elements
Unsorted list-------------------------------------
3.6
7.4
-1.5
-7.0
Element searched for (nothing to stop): 7.4
Found at position 1
Element searched for (nothing to stop): 0
Not in the list (-1)
Element searched for (nothing to stop):
Sorted list---------------------------------------
-7.0
-1.5
3.6
7.4
Element searched for (nothing to stop): 7.4
Found at position 3
Element searched for (nothing to stop): 0
Not in the list (-3)
Element searched for (nothing to stop):

结果与使用数组时相同。

5.4.2. 列表函数

程序 [Collections02.kt] 使用了其他列表函数:

package collections02

// 列表的主要函数
fun main() {
    // 用值初始化的可变列表
    val cities = mutableListOf("Paris", "Lyon", "Angers")
    display("start", cities)

    // 添加
    cities.add("Nantes")                        // 在末尾
    cities.add(1, "Brest")                      // 在位置 1
    cities.addAll(listOf("Lille", "Tours"))     // 在末尾添加多个元素
    display("after add, add(1, ...), addAll", cities)
    cities += "Nice"                            // += 运算符添加一个元素……
    cities -= "Nice"                            // ……而 -= 移除它
    display("after += \"Nice\", -= \"Nice\"", cities)

    // 按索引访问,用于写入和读取
    cities[0] = "Marseille"
    println("cities[0]=${cities[0]}, first()=${cities.first()}, last()=${cities.last()}, "
            + "size=${cities.size}, lastIndex=${cities.lastIndex}")
    // 无效的索引:getOrNull 返回 null 而不是抛出异常
    println("getOrNull(10)=${cities.getOrNull(10)}, getOrElse(10) { \"?\" }=${cities.getOrElse(10) { "?" }}")

    // 搜索
    println("\"Lyon\" in cities=${"Lyon" in cities}, indexOf(\"Angers\")=${cities.indexOf("Angers")}, "
            + "indexOf(\"Nice\")=${cities.indexOf("Nice")}")

    // 移除
    val removed = cities.remove("Lyon")         // 按值
    cities.removeAt(0)                          // 按位置
    display("after remove(\"Lyon\") ($removed), removeAt(0)", cities)

    // 排序、反转、子列表:列表本身被修改
    cities.sort()
    display("after sort()", cities)
    cities.reverse()
    display("after reverse()", cities)
    val extract = cities.subList(1, 3)
    display("subList(1, 3)", extract)
    // sorted、reversed:新列表,原列表不变
    display("sorted()", cities.sorted())
    display("sortedBy { it.length }", cities.sortedBy { it.length })
    display("cities (unchanged)", cities)

    // 转换为数组并转换回来
    val array: Array<String> = cities.toTypedArray()
    val other: MutableList<String> = array.toMutableList()
    println("array of ${array.size} elements, new list of ${other.size} elements")

    // 整数列表:remove 按值移除,removeAt 按位置移除
    val numbers = mutableListOf(10, 20, 30, 1)
    numbers.removeAt(1)                         // 移除第 1 个元素(20)
    numbers.remove(1)                           // 移除值 1
    display("numbers", numbers)

    // 只读列表:listOf
    val days: List<String> = listOf("monday", "tuesday", "wednesday")
    // + 创建一个新列表:days 不会被修改
    val days2 = days + "thursday"
    display("days, days + \"thursday\"", "$days, $days2")

    // clear 清空列表
    cities.clear()
    println("after clear : size=${cities.size}, isEmpty()=${cities.isEmpty()}")
}

fun display(text: String, list: Any) {
    println("%-38s: %s".format(text, list))
}

结果:

> gradlew -q run -Pmain=collections02.Collections02Kt
start                                 : [Paris, Lyon, Angers]
after add, add(1, ...), addAll        : [Paris, Brest, Lyon, Angers, Nantes, Lille, Tours]
after += "Nice", -= "Nice"            : [Paris, Brest, Lyon, Angers, Nantes, Lille, Tours]
cities[0]=Marseille, first()=Marseille, last()=Tours, size=7, lastIndex=6
getOrNull(10)=null, getOrElse(10) { "?" }=?
"Lyon" in cities=true, indexOf("Angers")=3, indexOf("Nice")=-1
after remove("Lyon") (true), removeAt(0): [Brest, Angers, Nantes, Lille, Tours]
after sort()                          : [Angers, Brest, Lille, Nantes, Tours]
after reverse()                       : [Tours, Nantes, Lille, Brest, Angers]
subList(1, 3)                         : [Nantes, Lille]
sorted()                              : [Angers, Brest, Lille, Nantes, Tours]
sortedBy { it.length }                : [Tours, Lille, Brest, Nantes, Angers]
cities (unchanged)                    : [Tours, Nantes, Lille, Brest, Angers]
array of 5 elements, new list of 5 elements
numbers                               : [10, 30]
days, days + "thursday"               : [monday, tuesday, wednesday], [monday, tuesday, wednesday, thursday]
after clear : size=0, isEmpty()=true

说明:

  • 第 6 行:[mutableListOf] 创建一个包含给定元素的可变列表;元素的类型 [String] 由参数推断得出。这等价于 Java 代码 [new ArrayList<>(List.of("Paris", "Lyon", "Angers"))];
  • 第 10–12 行:添加元素的三种方式;
  • 第 14–15 行:对于可变列表,运算符 [+=] 和 [-=] 添加和删除一个元素(或集合中的所有元素);
  • 第 19 行:第 0 号元素由运算符 [[]] 替换,它调用函数 [set];
  • 第 20–21 行:运算符 [[]] 读取一个元素;[first] 和 [last] 分别返回第一个和最后一个元素,属性 [lastIndex] 等于 [size - 1];
  • 第 23 行:无效的索引会抛出 [IndexOutOfBoundsException] 异常,与 Java 中一样。函数 [getOrNull] 和 [getOrElse] 可以让你避免这种情况:前者返回 [null],后者返回由以索引为参数的 lambda 计算出的值。在模板中,文本 ***[{ \\"?\\" }] 只是被显示的文本,而表达式 ***[cities.getOrElse(10) { "?" }] 则调用该函数;
  • 第 26–27 行:使用运算符 [in] ([contains])或 [indexOf]搜索元素;
  • 第 30 行:如果找到并删除了该元素,[remove] 返回 [true] ;
  • 第 31 行:[removeAt] 删除给定位置的元素并返回它;
  • 第 35–38 行:[sort] 按照元素的自然顺序(由 [compareTo] 定义)对列表本身排序,而 [reverse] 执行相反的排序;
  • 第 39 行:[subList] 返回第 1 和第 2 号元素(不含第 3 号)的 视图 ,而不是副本:修改该视图会修改列表;
  • 第 42–44 行:[sorted] 返回一个新的已排序列表,而 [sortedBy] 返回 一个按由 lambda 表达式计算出的 键 排序的新列表——在这里是名称的长度。这种排序是 稳定的:长度相同的城市(Tours、Lille、Brest)保持其原有的顺序。列表 [cities] 没有改变。[sortedBy] 使你无需编写 [Comparator];我们也可以写 [cities.sortedWith(compareBy({ it.length }, { it }))] 来先按长度再按字母顺序排序(第 4 章);
  • 第 47–48 行:从列表到数组以及从数组到列表的转换。得益于泛型 [reified](第 4 章),[toTypedArray] 可以创建大小正确的字符串数组,而无需 Java 的 [toArray(String[]::new)] 方法所提供的协助;
  • 第 52–54 行:避开了一个 Java 陷阱。在 Java 中,[List] 接口有两个方法——[remove],一个按位置,另一个按值——并且当 [numbers.remove(1)] 应用于 [List<Integer>] 时,会删除第 1 号元素。Kotlin 为这两种操作赋予了不同的名称:[removeAt] 按位置删除,而 [remove] 按值 删除。[numbers.remove(1)] 因此确实会删除值 1;
  • 第 58–60 行:[listOf] 创建一个 只读列表;[days.add("thursday")] 在编译时会被拒绝。另一方面,运算符 [+] 是可用的:它创建一个 新 列表,由 [days] 的元素后接“thursday”组成,而 [days] 保持不变;
  • 第 64–65 行:[clear] 清空列表;[isEmpty] 检查它是否为空;
  • 第 68 行:函数 [display] 接受任何对象([Any],第 4 章):字符串列表、整数列表或文本字符串。集合可以直接显示:其函数 [toString] 返回用方括号括起来的元素。

5.4.3. 字典:Map 与 MutableMap

字典是一组(键,值)对的集合。可以将其视为一个两列的表:

键
值
key1
value1
key2
value2
...
...

在 [Map<K, V>] 接口中,键的类型为 [K],值的类型为 [V]。键是唯一的:不能有两个相同的键(由函数 [equals] 定义)。如果类型 [K] 和 [V] 代表类,这样的字典可能如下所示:

Image

与列表一样,Kotlin 区分只读接口 *[Map<K, V>] 和可变接口 *[MutableMap<K, V>]。其实现与 Java 相同:

  • [HashMap] 将其键值对存储在 哈希表中:一个键值对在表中的位置是根据其键的哈希码计算出来的(函数 [hashCode],第 4 章)。因此,无论字典有多大,检索与某个键关联的值都非常快。另一方面,表中元组的顺序与它们被添加的顺序毫无关系;
  • [LinkedHashMap] 是一个 [HashMap] ,它另外还按添加顺序链接其元组:速度同样快,占用的内存略多,并按添加顺序枚举其元组。创建函数 ***[mutableMapOf] 和 *[mapOf]* 选择的就是这种实现:因此,Kotlin 字典默认保留其键的添加顺序。要获得 [HashMap],请使用 [hashMapOf]* 或其构造函数。

由 [mapOf] 创建的字典中的键值对写作 [key to value]:[to] 是标准库中的一个中缀函数,用于创建 [Pair(key, value)] 对(第 3 章)。字典的主要函数如下:

函数
作用
[size]
属性:字典中(键,值)对的数量
[dict[key]]
返回与 [key] 关联的值,如果键不存在则返回 [null] (函数 [get]);因此结果类型为 [V?]
[getValue(key)]
返回与 [key] 关联的类型为 [V] 的值;如果键不存在,则抛出 [NoSuchElementException] 异常
[getOrDefault(key, defaultValue)]、[getOrElse(key) { ... }]
返回与 [key] 关联的值,如果键不存在,则返回 [defaultValue],或由 lambda 计算出的值
[containsKey(key)]、[containsValue(value)]
返回 [true] 的条件:[key] 是字典中的键([key in dict]),以及 [value] 是其值之一(分别对应这两个函数)
[keys]、[values]、[entries]
属性:键的集、值的集合、字典中元组的集;一个 [Map.Entry] 对具有属性 [key] 和 [value] ,并且可以被解包:[for ((key, value) in dict)]
[dict[key] = value]
([MutableMap])将 [value] 关联到 [key]:如果键不存在,则添加该键值对;否则替换其值(函数 [set]);[dict += key to value] 作用相同
[put(key, value)]
([MutableMap])作用相同,但返回旧值,或 [null]
[putIfAbsent(key, value)]
([MutableMap])仅当键 不存在时才添加该键值对;返回已有的值,或 [null]
[getOrPut(key) { ... }]
([MutableMap])返回与 [key] 关联的值;如果键不存在,则用 lambda 计算该值,添加该键值对,并返回该值
[remove(key)]
([MutableMap])删除键值对 [key] 并返回其值,或 [null];[dict -= key] 作用相同
[clear()]
([MutableMap])删除字典中的所有条目

来看示例程序 [Collections03.kt]:

package collections03

// 字典:Map、MutableMap、LinkedHashMap、HashMap
fun main() {
    // 由 "name:age" 字符串数组创建 <String, Int> 字典
    val list = arrayOf("jean:20", "paul:18", "mélanie:10", "violette:15")
    val dict = mutableMapOf<String, Int>()
    // 同样的字典,由 HashMap 实现
    val dictHash = HashMap<String, Int>()
    for (element in list) {
        val (name, age) = element.split(":")
        dict[name] = age.toInt()
        dictHash[name] = age.toInt()
    }
    // 键的顺序:mutableMapOf 是插入顺序,HashMap 是哈希表顺序
    println("mutableMapOf : $dict, HashMap : $dictHash")
    // 字典的元素数量
    println("The dictionary has ${dict.size} elements")
    // 键列表
    display("[List of keys]", dict.keys)
    // 值列表
    display("[List of values]", dict.values)
    // 键和值的列表
    println("[List of keys & values]")
    for (key in dict.keys) {
        println("key=$key value=${dict[key]}")
    }
    // 我们移除 "paul" 键
    println("[Removal of a key]")
    dict.remove("paul")
    // 遍历(键, 值)对,并解构
    println("[List of keys & values]")
    for ((key, value) in dict) {
        println("key=$key value=$value")
    }
    // put 替换已有键的值并返回旧值
    println("put(\"jean\", 21) returns ${dict.put("jean", 21)}, put(\"zoé\", 12) returns ${dict.put("zoé", 12)}")
    // putIfAbsent 仅在键不存在时才添加
    println("putIfAbsent(\"jean\", 22) returns ${dict.putIfAbsent("jean", 22)}, dict[\"jean\"]=${dict["jean"]}")
    // 键不存在时 [] 返回 null;getOrDefault、getOrElse 返回默认值
    println("dict[\"x\"]=${dict["x"]}, getOrDefault(\"x\", -1)=${dict.getOrDefault("x", -1)}, "
            + "getOrElse(\"x\") { 0 }=${dict.getOrElse("x") { 0 }}, \"x\" in dict=${"x" in dict}")
    // 计数:给某个键的值加 1,或创建值为 1 的键
    for (name in listOf("zoé", "léa")) {
        dict[name] = (dict[name] ?: 0) + 1
    }
    println("after counting : $dict")
    // getOrPut:返回键的值;如果键不存在,则以计算出的值添加它
    println("getOrPut(\"max\") { 30 }=${dict.getOrPut("max") { 30 }}, getOrPut(\"jean\") { 30 }="
            + dict.getOrPut("jean") { 30 })
    // 只读字典,由 mapOf 和 key to value 对创建
    val capitals: Map<String, String> = mapOf("France" to "Paris", "Italy" to "Rome")
    println("capitals : $capitals, capitals[\"Italy\"]=${capitals["Italy"]}")

    // 在字典中搜索
    while (true) {
        print("Name searched for (nothing to stop): ")
        val searchedName = readlnOrNull()?.trim() ?: ""
        if (searchedName.isEmpty()) break
        // [] 返回与键关联的值,如果键不存在则返回 null
        val age = dict[searchedName]
        if (age != null) {
            println("$searchedName,$age")
        } else {
            println("Name $searchedName unknown")
        }
    }
}

// 显示集合元素的泛型函数
fun <T> display(text: String, elements: Iterable<T>) {
    println(text + "-".repeat(50 - text.length))
    for (element in elements) {
        println(element)
    }
}

说明:

  • 第 6 行:一个字符串数组,将用于初始化字典 [<String, Int>];
  • 第 7 行:由 [mutableMapOf] 创建的空字典:它是一个 [LinkedHashMap];
  • 第 9 行:同样的字典,这次由 [HashMap] 实现,通过其构造函数创建;
  • 第 10–13 行:用字符串数组初始化这两个字典。每个元素由 [split] 拆分,并通过对所得列表的解构将其两个字段赋给变量 [name] 和 [age]。添加键值对写作 [dict[name] = value],就像给数组元素赋值一样;
  • 第 16 行:直接显示字典,其键值对用花括号括起来。[dict] 的元组按添加顺序出现;[dictHash] 的元组按哈希表的顺序出现,这取决于键的哈希码(结果的第 1 行):*[HashMap] 不保证任何特定的顺序。本章中的 Java 程序使用的是 [HashMap]*,它按第二种顺序显示其键;
  • 第 18 行:字典中键值对的数量;
  • 第 20–22 行:字典的键和值。属性 [dict.keys] 和 [dict.values] 是集合,因此也是 [Iterable]:我们已经遇到过的 [display] 函数适用于它们;
  • 第 25–26 行:遍历键,并使用 [[]] 运算符获取每个键的值;
  • 第 30 行:从字典中删除一个键值对;
  • 第 33–34 行:字典本身不是集合,但循环 [for] 知道如何遍历它:标准库为它提供了一个扩展函数 [iterator] ,用来枚举其元组([entries])。类型为 [Map.Entry<String, Int>] 的每个键值对,被解包为 [(key, value)],这借助了 [component1] 和 [component2] 这两个来自 [Map.Entry] 的扩展函数。这种方法比前一种(查找每个键的值)更高效,也比其 Java 等价写法([for (Map.Entry<String, Integer> entry : dict.entrySet())],然后是 [entry.getKey()] 和 [entry.getValue()])更易读;
  • 第 37 行:[put] 添加一个键值对,或替换已有键的值,不会抛出异常,也不会发出警告;返回值——旧值或 [null]——指示了发生的情况。当不需要该值时,请使用 [dict[key] = value];
  • 第 39 行:[putIfAbsent] 不会替换已有键的值;
  • 第 41–42 行:读取不存在的键不会导致错误:运算符 [[]] 返回 [null]。其结果类型为 [Int?],编译器要求在使用该值之前先处理 [null] 的情况。[getOrDefault] 和 [getOrElse] 允许你在这种情况下选择返回的值,而运算符 [in] ([containsKey])则可用于检查某个键是否存在;
  • 第 44–47 行:统计出现次数的标准方法:使用 Elvis 运算符 [?:],将键的值加 1,如果键不存在,则为 0 + 1。键“zoé”从 12 变为 13;键“léa”被创建,值为 1。也可以使用 Java 方法 [merge] :[dict.merge(name, 1, Int::plus)];
  • 第 49–50 行:[getOrPut] 返回与某个键关联的值;如果键不存在,它会用 lambda 计算出一个值,将该键值对添加到字典中,并返回该值。键“max”被创建,值为 30;键“jean”已经存在,返回其值 21,而不会执行 lambda。这是用于缓存或将元素分组到列表中的理想函数:[groups.getOrPut(key) { mutableListOf() }.add(element)];
  • 第 52–53 行:一个只读字典,由 [mapOf] 根据 [key to value] 形式的键值对创建。[capitals["Spain"] = "Madrid"] 在编译时会被拒绝;
  • 第 55–65 行:在字典中搜索键。[dict[searchedName]] 返回一个 [Int?]:在使用该值之前,先检查 [null] 的情况;在分支 [age != null] 中,编译器知道 [age] 是一个 [Int] (智能类型转换)。在 Java 中,[int age = dict.get(searchedName);] 可以通过编译,但对于不存在的键会抛出 [NullPointerException] 异常 ;在 Kotlin 中,[val age: Int = dict[searchedName]] 在编译时就会被拒绝。

结果:

> gradlew -q run -Pmain=collections03.Collections03Kt
mutableMapOf : {jean=20, paul=18, mélanie=10, violette=15}, HashMap : {violette=15, jean=20, mélanie=10, paul=18}
The dictionary has 4 elements
[List of keys]------------------------------------
jean
paul
mélanie
violette
[List of values]----------------------------------
20
18
10
15
[List of keys & values]
key=jean value=20
key=paul value=18
key=mélanie value=10
key=violette value=15
[Removal of a key]
[List of keys & values]
key=jean value=20
key=mélanie value=10
key=violette value=15
put("jean", 21) returns 20, put("zoé", 12) returns null
putIfAbsent("jean", 22) returns 21, dict["jean"]=21
dict["x"]=null, getOrDefault("x", -1)=-1, getOrElse("x") { 0 }=0, "x" in dict=false
after counting : {jean=21, mélanie=10, violette=15, zoé=13, léa=1}
getOrPut("max") { 30 }=30, getOrPut("jean") { 30 }=21
capitals : {France=Paris, Italy=Rome}, capitals["Italy"]=Rome
Name searched for (nothing to stop): violette
violette,15
Name searched for (nothing to stop): x
Name x unknown
Name searched for (nothing to stop): jean
jean,21
Name searched for (nothing to stop):

与 Java 程序不同,在 Java 程序中 [HashMap] 以不可预测的顺序枚举键,而这里的字典键是按添加顺序枚举的:“zoé”和“léa”出现在最后。如果需要键保持有序,请使用 [TreeMap],见下文。

5.4.4. 其他集合

Kotlin 标准库和 [java.util] 包中还有其他集合,每种都适用于特定的用途:

类(构造函数)
作用
[LinkedHashSet<E>] ([setOf]、[mutableSetOf])
集:没有重复项,成员检查非常快;保留其元素的添加顺序。这是 Kotlin 默认的集
[HashSet<E>] ([hashSetOf])
无序的集,内存效率略高
[java.util.TreeSet<E>] ([sortedSetOf]、[toSortedSet])
元素保持有序的集
[ArrayDeque<E>]
Kotlin 特有的类([kotlin.collections.ArrayDeque],不要与 [java.util.ArrayDeque] 混淆):一个双端队列,同时还实现了 [MutableList]。用作队列时,元素按添加的顺序被移除(FIFO,先进先出);用作栈时,最后添加的元素最先被移除(LIFO,后进先出)
[LinkedHashMap<K, V>] ([mapOf]、[mutableMapOf])
保留其键添加顺序的字典。这是 Kotlin 默认的字典
[java.util.TreeMap<K, V>] ([sortedMapOf]、[toSortedMap])
键保持有序的字典
[java.util.PriorityQueue<E>]
优先队列:被移除的元素是按队列的顺序最小的那个
[java.util.LinkedList<E>]
双向链表:在两端以及遍历过程中插入和删除都很快

对于集,只读与可修改之间的区别与列表相同:[Set<E>] 只有读取函数,而 [MutableSet<E>] 增加了 [add]、[remove]……

程序 [Collections04.kt] 快速概览了这些集合:

package collections04

import java.util.PriorityQueue
import java.util.TreeMap

// 一名患者及其护理的优先级
data class Emergency(val patient: String, val priority: Int)

// 其他集合概览
fun main() {
    // mutableSetOf:不含重复项的集合,保持插入顺序(LinkedHashSet)
    val languages = mutableSetOf("C#", "Java", "PHP")
    val added1 = languages.add("Python")
    val added2 = languages.add("Java")              // 已存在:被拒绝
    println("Set : add(Python)=$added1, add(Java)=$added2, size=${languages.size}, "
            + "\"PHP\" in languages=${"PHP" in languages}")
    // 集合运算:intersect、union、subtract 返回新集合
    val web = setOf("PHP", "JavaScript", "Python")
    println("Set : languages intersect web = ${languages intersect web}")
    println("Set : languages union web = ${languages union web}")
    println("Set : languages subtract web = ${languages subtract web}")
    // hashSetOf:无序的 HashSet;sortedSetOf:元素有序的 TreeSet
    println("HashSet : ${hashSetOf("Kotlin", "Java", "Go", "C#")}, "
            + "TreeSet : ${sortedSetOf("Kotlin", "Java", "Go", "C#")}")
    // toSet 移除列表中的重复项
    println("toSet : ${listOf(3, 1, 3, 2, 1).toSet()}")

    // ArrayDeque 用作队列:先进先出
    val queue = ArrayDeque<String>()
    queue.addLast("client1")
    queue.addLast("client2")
    queue.addLast("client3")
    println("queue : first()=${queue.first()}, removeFirst()=${queue.removeFirst()}, "
            + "removeFirst()=${queue.removeFirst()}, ${queue.size} left")

    // ArrayDeque 用作栈:后进先出
    val stack = ArrayDeque<Int>()
    stack.addLast(1)
    stack.addLast(2)
    stack.addLast(3)
    println("stack : last()=${stack.last()}, removeLast()=${stack.removeLast()}, "
            + "removeLast()=${stack.removeLast()}, ${stack.size} left")
    // 对空栈调用 removeLast 会抛出异常,removeLastOrNull 返回 null
    stack.removeLast()
    println("stack : removeLastOrNull() on an empty stack = ${stack.removeLastOrNull()}")
    try {
        stack.removeLast()
    } catch (e: NoSuchElementException) {
        println("stack : removeLast() on an empty stack : ${e::class.simpleName} (${e.message})")
    }

    // TreeMap:键保持有序的字典
    val ages = TreeMap<String, Int>()
    ages["violette"] = 15
    ages["jean"] = 20
    ages["mélanie"] = 10
    ages["paul"] = 18
    println("TreeMap : $ages, firstKey()=${ages.firstKey()}, headMap(\"n\")=${ages.headMap("n")}")
    // sortedMapOf 同样创建 TreeMap;mutableMapOf 保持插入顺序
    println("sortedMapOf : ${sortedMapOf("violette" to 15, "jean" to 20, "mélanie" to 10)}")
    println("mutableMapOf : ${mutableMapOf("violette" to 15, "jean" to 20, "mélanie" to 10)}")

    // PriorityQueue(JDK):优先级最小的元素总是最先出队
    val emergencies = PriorityQueue(compareBy<Emergency> { it.priority })
    emergencies.add(Emergency("sprain", 3))
    emergencies.add(Emergency("cardiac arrest", 1))
    emergencies.add(Emergency("cold", 5))
    emergencies.add(Emergency("fracture", 2))
    print("PriorityQueue :")
    while (true) {
        // 队列为空时 poll 返回 null
        val emergency = emergencies.poll() ?: break
        print(" ${emergency.patient} (${emergency.priority})")
    }
    println()
}

结果:

> gradlew -q run -Pmain=collections04.Collections04Kt
Set : add(Python)=true, add(Java)=false, size=4, "PHP" in languages=true
Set : languages intersect web = [PHP, Python]
Set : languages union web = [C#, Java, PHP, Python, JavaScript]
Set : languages subtract web = [C#, Java]
HashSet : [Go, C#, Java, Kotlin], TreeSet : [C#, Go, Java, Kotlin]
toSet : [3, 1, 2]
queue : first()=client1, removeFirst()=client1, removeFirst()=client2, 1 left
stack : last()=3, removeLast()=3, removeLast()=2, 1 left
stack : removeLastOrNull() on an empty stack = null
stack : removeLast() on an empty stack : NoSuchElementException (ArrayDeque is empty.)
TreeMap : {jean=20, mélanie=10, paul=18, violette=15}, firstKey()=jean, headMap("n")={jean=20, mélanie=10}
sortedMapOf : {jean=20, mélanie=10, violette=15}
mutableMapOf : {violette=15, jean=20, mélanie=10}
PriorityQueue : cardiac arrest (1) fracture (2) sprain (3) cold (5)

说明:

  • 第 3–4 行:JDK 的类 [PriorityQueue] 和 [TreeMap] 在 Kotlin 库中没有别名,必须导入。[ArrayDeque] 不是别名:使用的是 Kotlin 自己的类;
  • 第 7 行:患者由一个数据类(第 4 章)表示,相当于 Java 的 [record];
  • 第 12 行:一个可变的集,用三个元素初始化;
  • 第 14 行:如果元素已在集中,[add] 返回 [false] ,集保持不变;
  • 第 18–21 行:[setOf] 创建一个只读的集。中缀函数 [intersect] (交集)、[union] (并集)和 [subtract] (差集)返回一个 新 的集,并且不修改 [languages]:与 Java 中使用 [retainAll]、[addAll] 和 [removeAll] 不同,这里不必在副本上操作。所创建的集保留元素的顺序:先是来自 [languages] 的元素,然后是来自 [web] 的原本不在其中的元素;
  • 第 23–24 行:[HashSet] 以无意义的顺序(即其哈希表的顺序)呈现其元素;[TreeSet] 则按排序后的顺序呈现;
  • 第 26 行:[toSet] 返回由列表的元素组成的集:这是去除重复项最简单的方法,同时保留它们第一次出现的顺序([distinct] 则会返回列表);
  • 第 29–34 行:[ArrayDeque] 用作队列:[addLast] 在队列末尾插入一个元素,[removeFirst] 移除最早的元素,而 [first] 获取一个元素但不移除它。模板中的表达式按从左到右的顺序求值:[first],然后是两个 [removeFirst],然后是 [size];
  • 第 37–42 行:[ArrayDeque] 用作栈:[addLast] 将一个元素压入栈中,[removeLast] 弹出最近的元素,而 [last] 获取栈顶。Java 1.0 的类 [Stack],甚至 [java.util.ArrayDeque] 及其方法 [push]/[pop]/[offer]/[poll],在 Kotlin 中都无关紧要:名称 [addFirst]、[addLast]、[removeFirst]、[removeLast]、[first]和 [last] 对 [ArrayDeque] 和所有可变列表都是相同的;
  • 第 44–49 行:在空栈上,[removeLast] 会抛出 [NoSuchElementException] 异常,而 [removeLastOrNull] 返回 [null]。这遵循库的命名约定:当函数 [xxx] 无法返回结果时会抛出异常,而其变体 [xxxOrNull] 则返回 [null] ([first]/[firstOrNull]、[removeFirst]/[removeFirstOrNull]、[toInt]/[toIntOrNull]……)。[e::class.simpleName] 是异常类的简单名称(第 4 章);
  • 第 53–58 行:[TreeMap] 的元组按键的顺序列出。它是使用 [[]] 运算符填充的,就像任何可变字典一样。对键排序使得哈希表无法提供的操作成为可能:[firstKey] 返回最小的键,而 [headMap] 返回 键位于给定值之前的那部分字典;
  • 第 60–61 行:[sortedMapOf] 根据按键排序的键值对创建一个 [TreeMap] ;[mutableMapOf] 保留元素的添加顺序;
  • 第 64–75 行:[PriorityQueue] 需要能够比较其元素。这里向它传递了一个比较优先级的 [Comparator] :[compareBy<Emergency> { it.priority }] (第 4 章)读作“根据急诊的 [priority] 属性来比较急诊”。患者按优先级递增的顺序出院,与到达顺序无关。方法 [poll] 返回优先级最低的元素,如果队列为空则返回 [null] :随后 Elvis 运算符 [?: break] 退出循环。这是惯用语法,因为 [break] 在 Kotlin 中是一个表达式。在 Java 中,则会写成 [while ((emergency = emergencies.poll()) != null)];Kotlin 不允许在表达式内部进行赋值。

5.4.5. 只读、不可变、视图与副本

管理集合的类通常需要将其暴露给外部,同时又不允许其被修改。Java 没有与 [List] 区分开的“只读”接口:它使用 不可变集合,这些集合实现了完整的 [List] 接口,但其修改方法会在运行时抛出 [UnsupportedOperationException] 异常。Kotlin 主要通过其 类型来满足这一需求:只需将集合声明为类型 [List],编译器就会阻止任何修改。不过,重要的是要理解这种类型保证了什么——以及没有保证什么。程序 [Collections05.kt] 演示了表示集合的三种方式——只读类型、不可修改的视图和副本:

package collections05

import java.util.Collections

// 保持对其列表控制权的类
class Classroom {
    // 可变列表是私有的:只有该类可以修改它
    private val studentList = mutableListOf<String>()

    // 列表,对外部代码以只读类型呈现
    val students: List<String>
        get() = studentList

    // 列表的不可修改视图(JDK 类)
    val protectedStudents: List<String>
        get() = Collections.unmodifiableList(studentList)

    // 列表的副本
    val studentsCopy: List<String>
        get() = studentList.toList()

    fun enroll(name: String) {
        studentList += name
    }
}

// 只读集合、不可修改视图和副本
fun main() {
    val classroom = Classroom()
    classroom.enroll("dupont")
    classroom.enroll("martin")
    // 外部代码可以读取学生列表……
    val students = classroom.students
    println("${students.size} students : $students, students[0]=${students[0]}")
    // ……但不能修改它:students.add("intruder") 无法编译
    println("class of students : ${students.javaClass.name}")
    // 只读列表反映所属类所做的修改
    classroom.enroll("durand")
    println("${students.size} students : $students")

    // 只读不等于不可变:通过强制转换可以修改列表
    (students as MutableList<String>).add("intruder")
    println("after the cast : ${classroom.students}")
    // 相反,JDK 的不可修改视图在运行时拒绝任何修改
    try {
        (classroom.protectedStudents as MutableList<String>).add("intruder2")
    } catch (e: UnsupportedOperationException) {
        println("add on the unmodifiable view : ${e::class.simpleName}")
    }

    // toList:副本,不再看到原列表的修改
    val copy = classroom.studentsCopy
    classroom.enroll("petit")
    println("copy : $copy, view : $students")

    // listOf、setOf、mapOf:一条语句创建的只读集合
    val grades: Map<String, Int> = mapOf("dupont" to 12, "martin" to 15)
    println("grades[\"martin\"]=${grades["martin"]}, \"durand\" in grades=${"durand" in grades}")
    // grades["durand"] = 9 无法编译
    // Kotlin 集合接受 null……只要元素类型允许
    val list: List<String?> = listOf("a", null)
    println("listOf(\"a\", null) : $list, filterNotNull() : ${list.filterNotNull()}")
    // 防御性复制:小组不受所接收列表的修改影响
    val members = mutableListOf("dupont", "martin")
    val group = Group("TP1", members)
    members += "intruder"
    println("members : $members, group : $group")
}

// 保留所接收列表副本的类
class Group(val name: String, students: List<String>) {
    val students: List<String> = students.toList()

    override fun toString() = "Group(name=$name, students=$students)"
}

结果:

> gradlew -q run -Pmain=collections05.Collections05Kt
2 students : [dupont, martin], students[0]=dupont
class of students : java.util.ArrayList
3 students : [dupont, martin, durand]
after the cast : [dupont, martin, durand, intruder]
add on the unmodifiable view : UnsupportedOperationException
copy : [dupont, martin, durand, intruder], view : [dupont, martin, durand, intruder, petit]
grades["martin"]=15, "durand" in grades=false
listOf("a", null) : [a, null], filterNotNull() : [a]
members : [dupont, martin, intruder], group : Group(name=TP1, students=[dupont, martin])

说明:

  • 第 6–23 行:类 [Classroom] 管理一个学生列表。可变列表本身是私有的;只有函数 [enroll] 允许对其进行修改;
  • 第 11–12 行:属性 [students] 使列表保持私有,但以类型 [List<String>] 暴露时,它是只读的。这是 Kotlin 中的标准做法:私有的可变列表加上公共的只读属性。外部代码可以读取该列表,但 [students.add("intruder")] 会 在编译时 被拒绝([unresolved reference 'add' on receiver of type 'List<String>']),而 Java 只会在运行时拒绝;
  • 第 36 行:属性 [students] 不会创建任何对象;它使私有列表本身——一个 [java.util.ArrayList]——成为可见的。因此它能看到所属类所做的更改(结果的第 3 行);
  • 第 41–43 行:只读并不意味着不可变。类型 *[List] 禁止通过该引用进行修改,但对象本身是一个完全可修改的 *[ArrayList]:将其强制转换为 [MutableList] (或将该列表传递给 Java 方法,对 Java 方法而言它就是普通的 [java.util.List])就可以修改它,于是“intruder”学生被添加到班级的列表中(结果的第 4 行)。只读类型防止的是失误,而不是恶意行为;
  • 第 15–16 行和第 44–48 行:为了完全保护,我们返回一个 只读视图 ,它由 JDK 的 [Collections.unmodifiableList] 方法创建:即使经过类型转换,任何修改它的尝试也会抛出 [UnsupportedOperationException] 异常。与前一种一样,该视图不复制列表,并反映所属类所做的更改;
  • 第 19–20 行和第 52–54 行:另一方面,[toList], 返回列表的一个 副本 :列表 [copy] 看不到“petit”的添加。副本独立于原列表,但这是有代价的:每次读取该属性时,getter 都会创建一个新列表;
  • 第 57–58 行:[mapOf]与 [listOf] 和 [setOf] 一样,用一条语句创建一个已初始化的集合,其类型为只读类型:[grades["durand"] = 9] 无法通过编译([no 'set' operator method providing array access])。这些集合相当于 Java 的 [List.of]、[Set.of] 和 [Map.of],并有与上文相同的注意事项:它们在类型上是只读的,但 [mapOf] 创建的是一个普通的 [LinkedHashMap];
  • 第 61–62 行:Java 中由 ***[List.of] 创建的集合在运行时会拒绝值 *[null] 。在 Kotlin 中,这由类型决定:***[List<String>] 不能包含 [null] (编译器会拒绝),而 ***[List<String?>]*** 则可以。[filterNotNull] 返回一个由 非 [null] 元素组成的列表,其类型为 [List<String>]*;
  • 第 64–67 行和第 71–74 行:一个 防御性副本。类 [Group] 在其构造函数中接收一个列表;如果它原样保留该列表,传递该列表的一方之后就可以修改它——在本例中,是向列表 [members] 中添加“intruder”。因此,构造函数参数 [students] 不是属性(它前面没有 [val]):它用于以一个副本来初始化属性 [students] 。该组不受这次添加的影响(结果的最后一行)。这种方法不能用于数据类主构造函数的属性;如果数据类接收一个集合,调用方应向其传递一个自己此后不再修改的集合——例如由 [listOf] 或 [toList] 创建的集合。

因此,[List<String>] 类型指明的是接收它的代码 能够做什么,而不是列表实际 是什么。对于真正不可变的集合,可以使用 JetBrains 的 [kotlinx.collections.immutable] 库([persistentListOf]、[persistentMapOf]……),也可以使用 Java 的不可变集合([java.util.List.copyOf(list)])。无论在 Kotlin 还是 Java 中,一种常见的最佳实践是将集合设为只读,并在需要修改时创建一个新集合([list + element], [list - element], [list.filter { ... }]……):标准库中的运算符和函数使这种做法显得很自然。

5.4.6. 排序、首尾元素与迭代

程序 [Collections06.kt] 演示了使用集合的三个有用方面:按条件排序、访问集合的两端(Java 21 称之为 有序集合),以及在迭代过程中移除元素:

package collections06

import java.text.Collator
import java.util.Locale
import java.util.TreeMap

// 一名学生及其成绩
data class Student(val name: String, val grade: Int)

// 列表中学生的姓名
fun names(students: List<Student>): List<String> = students.map { it.name }

// 使用 Comparator 排序、首尾元素、迭代和移除
fun main() {
    val students = mutableListOf(
        Student("martin", 15), Student("dupont", 12), Student("Durand", 15),
        Student("élise", 9), Student("petit", 12)
    )

    // 1 - 按键排序、Comparator、多个条件
    students.sortBy { it.name }
    println("by name                  : ${names(students)}")
    students.sortWith(compareBy(Collator.getInstance(Locale.FRANCE)) { it.name })
    println("by name (Collator)       : ${names(students)}")
    students.sortWith(compareByDescending<Student> { it.grade }.thenBy(String.CASE_INSENSITIVE_ORDER) { it.name })
    println("decreasing grade, name   : ${names(students)}")

    // 2 - 第一个、最后一个、逆序
    println("first()=${students.first().name}, last()=${students.last().name}, "
            + "asReversed()=${names(students.asReversed())}")
    println("first { it.grade < 15 }=${students.first { it.grade < 15 }}, "
            + "lastOrNull { it.grade > 18 }=${students.lastOrNull { it.grade > 18 }}")
    val cities = linkedSetOf("Angers", "Paris", "Nantes")
    cities.addFirst("Lyon")
    println("LinkedHashSet : $cities, first()=${cities.first()}, last()=${cities.last()}, "
            + "reversed()=${cities.reversed()}")
    val grades = TreeMap(mapOf("martin" to 15, "dupont" to 12, "petit" to 12))
    println("TreeMap : firstEntry()=${grades.firstEntry()}, lastEntry()=${grades.lastEntry()}, "
            + "descendingMap()=${grades.descendingMap()}")

    // 3 - 在 for 循环中移除元素:异常(在副本上尝试)
    val copy = students.toMutableList()
    try {
        for (student in copy) {
            if (student.grade == 12) {
                copy.remove(student)
            }
        }
    } catch (e: ConcurrentModificationException) {
        println("remove in a for : ${e::class.simpleName}")
    }
    // 正确的方式:显式迭代器及其 remove 函数……
    val iterator = students.iterator()
    while (iterator.hasNext()) {
        val student = iterator.next()
        if (student.grade < 10) {
            iterator.remove()
        }
    }
    println("after iterator.remove() : ${names(students)}")
    // ……或者更简单地,使用带条件的 removeAll
    students.removeAll { it.grade < 15 }
    println("after removeAll { ... } : ${names(students)}")
    // forEach:用 lambda 表达的迭代
    students.forEach { println("  $it") }
}

结果:

> gradlew -q run -Pmain=collections06.Collections06Kt
by name                  : [Durand, dupont, martin, petit, élise]
by name (Collator)       : [dupont, Durand, élise, martin, petit]
decreasing grade, name   : [Durand, martin, dupont, petit, élise]
first()=Durand, last()=élise, asReversed()=[élise, petit, dupont, martin, Durand]
first { it.grade < 15 }=Student(name=dupont, grade=12), lastOrNull { it.grade > 18 }=null
LinkedHashSet : [Lyon, Angers, Paris, Nantes], first()=Lyon, last()=Nantes, reversed()=[Nantes, Paris, Angers, Lyon]
TreeMap : firstEntry()=dupont=12, lastEntry()=petit=12, descendingMap()={petit=12, martin=15, dupont=12}
remove in a for : ConcurrentModificationException
after iterator.remove() : [Durand, martin, dupont, petit]
after removeAll { ... } : [Durand, martin]
  Student(name=Durand, grade=15)
  Student(name=martin, grade=15)

说明:

  • 第 8 行:学生由一个数据类表示;
  • 第 11 行:函数 [names] 返回学生姓名的列表。函数 [map](我们已经在没有介绍的情况下使用过它)对集合的每个元素应用一个 lambda,并返回由结果组成的列表:在 Java 中,这需要循环或 Stream API。该函数被写成一个 表达式体函数 ([= expression],第 3 章);
  • 第 21 行:[sortBy] 根据 lambda 从每个元素中提取的 键 对列表本身排序——在这里是姓名。姓名按字符串的自然顺序比较:以大写字母开头的“Durand”排在最前,而“élise”排在最后;
  • 第 23 行:[sortWith] 按 [Comparator] 排序。函数 [compareBy] (第 4 章)根据提取键的函数构造一个比较器;它的一个重载方法以用于比较键的比较器作为第一个参数,这里是 *[Collator]:其顺序遵循法语词典的顺序。这等价于 Java 中的 ***[Comparator.comparing(Student::name, collator)]** ;
  • 第 25 行:比较器的定义如下:[compareByDescending] 按降序比较成绩,而 [thenBy] 添加了一个次要条件,用于为成绩相同的学生排名:他们的姓名,忽略大小写([String.CASE_INSENSITIVE_ORDER])。Durand 和 Martin 的分数都是 15,因此按姓名排名。这里必须写出 [<Student>] ,即 [compareByDescending] 的类型参数,因为编译器无法在以 [thenBy] 继续的表达式中推断元素的类型;
  • 第 29–32 行:函数 [first] 和 [last] 分别返回第一个和最后一个元素,而 [asReversed] 返回 列表的 反向视图 而不复制它([reversed] 则会返回反转后的副本)。[first] 和 [lastOrNull] 也接受条件:它们返回满足该条件的第一个(或最后一个)元素;如果没有这样的元素,[first] 会抛出 [NoSuchElementException] 异常;[lastOrNull] 则返回 [null]。Kotlin 自第一个版本起就在所有集合上提供这些函数:Java 21 添加到其 [getFirst]、[getLast] 和 [reversed] 这些方法,以及其 有序集合([SequencedCollection]、[SequencedSet]、[SequencedMap])并没有带来多少新东西;
  • 第 33–36 行:[linkedSetOf] 创建一个 [LinkedHashSet],这里用其类类型来声明。然后我们就可以使用 Java 21 添加到这个类中的方法:[addFirst] 将“Lyon”添加到集的开头。请注意一个微妙之处:当 Java 类有一个与扩展函数同名的方法时,成员方法 总是 优先 (第 4 章)。在这里,[cities.reversed()] 调用的是 Java 21 的方法 [reversed]*,它返回集的反向视图,而不是会返回列表的 Kotlin 扩展函数 [reversed]。相比之下,[cities.last()] 调用的是 Kotlin 扩展,它会遍历集直到最后一个元素,因为 Java 方法名为 [getLast];Kotlin 将其暴露为属性 [cities.last]*,它无需遍历即可返回最后一个元素。结果是相同的;只是开销不同;
  • 第 37–39 行:一个用字典中的键值对初始化的 *[TreeMap]*,以及它的方法 [firstEntry]、[lastEntry]、和 *[descendingMap]*(按键的降序查看键值对);
  • 第 42–50 行:在使用 [for] 循环遍历集合时,不得修改该集合:循环使用的迭代器会检测到修改,并在下一个元素处抛出 [ConcurrentModificationException] 异常。测试是在列表的副本上进行的。其行为与 Java 中相同,因为该列表是一个 [ArrayList];
  • 第 53–60 行:一种正确的做法是使用 迭代器 显式编写循环,并使用迭代器的 [remove] 方法删除当前元素。对于可变列表,[iterator] 返回一个 [MutableIterator],它具有这个函数;而普通的 [Iterator] (来自 [List] 的那个)则没有。由于 Kotlin 没有三段式的 [for] 循环,因此该循环使用 [while] 编写;
  • 第 62 行:更简单的做法是,函数 [removeAll] 删除满足条件的元素,该条件由 lambda [{ it.grade < 15 }] 表示,其含义为“给定学生 [it],将其关联到布尔值 [it.grade < 15] 的函数”。也可以使用 Java 方法 [removeIf],而 [retainAll] 则相反,保留满足条件的元素。lambda 将在第 7 章详细讨论;目前,只需知道如何阅读它们就够了。在下一节的每一行中我们都会遇到它们;
  • 第 65 行:函数 [forEach] 对每个元素执行一个 lambda;使用 [for] 的循环同样可行。通过数据类的 [toString] 函数显示数据类,会返回类名和其属性的值:[Student(name=Durand, grade=15)]。

5.5. 集合与序列上的操作

Java 课程在这里介绍了 Stream API([java.util.stream] 包),它允许你像查询数据库一样处理集合的元素:过滤、排序、分组、计算总计……Kotlin 不需要这样做:在其标准库中,这些操作是 扩展函数 ,定义在集合本身之上([Iterable<T>]、[List<T>]、[Map<K, V>]……)。你写 [persons.filter { it.age >= 18 }] ,而 Java 写作 [persons.stream().filter(p -> p.age() >= 18).toList()]:无需经过流,也没有最终的收集器——结果直接就是一个列表。

这些集合操作是 即时的:每个操作都会遍历整个集合并构造一个新的集合。为了实现 Java 流的 惰性求值(元素按需逐个计算,没有中间集合),Kotlin 提供了 序列 ([Sequence<T>]),它支持相同的操作。最后,Java 流仍然可以在 Kotlin 中使用,就像 JDK 包中的任何类一样:我们将在本节末尾简要介绍。

本节中的程序保留了其 Java 对应程序的名称:[Streams01.kt] 到 [Streams05.kt]。

5.5.1. Iterable 与 Iterator 接口

我们先回顾一下 [Iterable<T>] 接口,它定义了可以用 [for] 循环迭代的对象。与 Java 中一样,它只包含一个抽象方法 [iterator],该方法返回一个 迭代器 [Iterator<T>]:这个对象指示是否还有剩余元素([hasNext]),并返回下一个元素([next])。

[Iterable] 对象不需要包含其元素:它的迭代器可以按需逐个 生成它们。程序 [Streams01.kt] 提供了一个示例,介绍了 Kotlin 的 生成器——Java 中没有——以及无限序列:

package streams01

// Iterable 和 Iterator 接口;sequence { yield } 生成器;无限序列
fun main() {
    // 1 - 对按需生成元素的 Iterable 对象使用 for
    println("[for on Evens(6)]")
    for (n in Evens(6)) {
        println("  received $n")
    }

    // 2 - for 所做的事:它向对象请求一个迭代器
    println("[iteration by hand]")
    val iterator: Iterator<Int> = Evens(4).iterator()
    while (iterator.hasNext()) {
        println("  next()=${iterator.next()}")
    }

    // 3 - 生成器:sequence { } 函数用 yield 生成其元素
    println("[sequence { yield } generator]")
    for (n in evens(4)) {
        println("  received $n")
    }

    // 4 - 无限序列:其元素只在需要时才计算
    println("[infinite sequence]")
    val fibonacci = generateSequence(0L to 1L) { (a, b) -> b to a + b }.map { it.first }
    println(fibonacci.takeWhile { it <= 100 }.joinToString(" "))

    // 5 - for 接受任何具有 operator fun iterator() 方法的对象
    println("[other iterable objects]")
    for (c in "abc") print("$c-")
    for (i in Counter(3)) print(" $i")
    println()
}

// 从 0 到 max 的偶数,由迭代器逐个生成
class Evens(private val max: Int) : Iterable<Int> {

    override fun iterator(): Iterator<Int> {
        println("  (start of the iteration)")
        // 实现 Iterator<Int> 接口的匿名对象
        return object : Iterator<Int> {
            // 下一个要生成的数
            private var nextValue = 0

            override fun hasNext(): Boolean {
                val more = nextValue <= max
                if (!more) {
                    println("  (end of the iteration)")
                }
                return more
            }

            override fun next(): Int {
                if (nextValue > max) {
                    throw NoSuchElementException()
                }
                println("  (producing $nextValue)")
                val n = nextValue
                nextValue += 2
                return n
            }
        }
    }
}

// 同样的偶数,由生成器生成
fun evens(max: Int): Sequence<Int> = sequence {
    println("  (start of the generator)")
    var n = 0
    while (n <= max) {
        println("  (producing $n)")
        // yield 将 n 返回给消费者,并挂起生成器直到下一次请求
        yield(n)
        n += 2
    }
    println("  (end of the generator)")
}

// 不实现 Iterable、但有 iterator() 运算符的类
class Counter(private val n: Int) {
    operator fun iterator(): Iterator<Int> = (1..n).iterator()
}

结果:

> gradlew -q run -Pmain=streams01.Streams01Kt
[for on Evens(6)]
  (start of the iteration)
  (producing 0)
  received 0
  (producing 2)
  received 2
  (producing 4)
  received 4
  (producing 6)
  received 6
  (end of the iteration)
[iteration by hand]
  (start of the iteration)
  (producing 0)
  next()=0
  (producing 2)
  next()=2
  (producing 4)
  next()=4
  (end of the iteration)
[sequence { yield } generator]
  (start of the generator)
  (producing 0)
  received 0
  (producing 2)
  received 2
  (producing 4)
  received 4
  (end of the generator)
[infinite sequence]
0 1 1 2 3 5 8 13 21 34 55 89
[other iterable objects]
a-b-c- 1 2 3

说明:

  • 从第 37 行开始:类 [Evens] 实现了接口 *[Iterable<Int>]:它被重写([iterator])的方法 [override] 返回一个生成从 0 到 [max]* 的偶数的迭代器。它不构造任何列表:迭代器只存储下一个要生成的数(第 44 行);
  • 第 42 行:迭代器是一个 匿名对象:一个 对象表达式 [object : Iterator<Int> { ... }],它在单个表达式中声明并实例化一个实现该接口的未命名类。这等价于 Java 匿名类 [new Iterator<>() { ... }]。它可以访问对象 [max] 的属性 [Evens];
  • 第 46–51 行:[hasNext] 指示是否还有要生成的元素;
  • 第 54–61 行:[next] 生成下一个元素。如果在没有更多元素时被调用,它必须抛出 [NoSuchElementException](在 Kotlin 中,[NoSuchElementException] 是 Java 类 [java.util.NoSuchElementException] 的别名,无需 [import] 即可使用);
  • 第 7–8 行:结果(第 2–11 行)表明,迭代器生成元素与 [for] 循环消费该元素是交替进行的;
  • 第 13–15 行:[for] 循环实际所做的事情:它向对象请求一个迭代器,只要 [hasNext] 方法返回 [true] 就调用它,并使用 [next] 获取每个元素;
  • 第 68–77 行:同样的偶数,由 生成器生成。标准库的 [sequence] 函数接受一个代码块(一个 lambda),并返回一个 [Sequence<Int>] 序列。每次调用 [yield(n)] (第 74 行)都会将一个元素传递给消费者,并 挂起 该代码块,当请求下一个元素时,它会紧接在 [yield] 之后恢复执行。这使你可以把迭代器写成一个简单的循环,而无需在对 *[next] 的调用之间自己管理状态。这相当于 C# 的 [yield return],而 Java 没有它:Java 课程要求学生要么编写迭代器类,要么使用 [Stream.iterate]*。这种挂起机制就是协程的机制,我们将在第 9 章学习;
  • 结果(第 22–29 行)表明,生成器与 [for] 循环的交替方式与手写的迭代器完全相同:没有任何内容是提前生成的;
  • 第 26–27 行:一个 无限序列,即斐波那契数列。[generateSequence(seed) { function }] 先生成种子,然后是对种子应用函数的结果,再然后是对该结果应用函数的结果,依此类推。这里的每个元素都是序列中两个连续数字组成的一对([Pair<Long, Long>],由 [to] 创建);lambda 表达式解包收到的对 [(a, b)] 并返回下一对。[map] 只保留第一个数字,[takeWhile] 在第一个大于 100 的数字处停止序列,而 [joinToString] 用分隔符把剩下的数字连接起来。序列从不会被完整计算:只会计算被请求的元素;
  • 第 31 行:与 Java 不同,字符串可以直接用 [for] 逐字符遍历:Kotlin 标准库定义了函数 [operator fun CharSequence.iterator()];
  • 第 81–82 行:这是一般规则:Kotlin 的 [for] 循环接受 任何对象 ,只要它有一个 [operator fun iterator()] 函数(成员函数或扩展函数),该函数返回一个具有 [operator fun hasNext()] 和 [operator fun next()] 函数的对象。类 [Counter] 并不实现 [Iterable];它的函数 [iterator],标记为 [operator],就已足够([(1..n).iterator()] 是区间 [1..n] 的迭代器)。这是一种约定,类似于第 4 章讨论的运算符重载的约定。

总结一下:[Iterable] 使用 [for] 遍历,并且你可以使用 [sequence { ... yield(x) ... }] 或 [generateSequence] 非常轻松地得到一个按需生成其元素的对象。所有序列都使用这种按需生成机制。

5.5.2. 过滤、投影、排序

以下示例处理一个包含少量人员的列表。一个人由一个 数据类 ([data class])表示,它在第 4 章中介绍,相当于 Java 的 [record]:只需一行,你就得到一个带构造函数和只读属性([p.lastName]、[p.age]……)的类、一个显示属性的方法 [toString] 、一个比较其值的相等运算符,以及一个函数 [copy]。

程序 [Streams02.kt] 演示了对集合的基本操作:

package streams02

// 集合上的操作:过滤(filter)、投影(map)、排序(sorted……)
fun main() {
    // 数据:人员列表
    val persons = listOf(
        Person("dupont", "jean", 45, "Angers"),
        Person("martin", "marie", 17, "Paris"),
        Person("durand", "paul", 32, "Angers"),
        Person("leroy", "sophie", 28, "Nantes"),
        Person("moreau", "luc", 15, "Paris"),
        Person("simon", "julie", 52, "Angers"),
        Person("laurent", "marc", 32, "Lyon"),
    )

    // filter:成年人;{ p -> p.age >= 18 } 是匿名函数(lambda)
    val adults: List<Person> = persons.filter { p -> p.age >= 18 }
    display("[filter : the adults]", adults)

    // map:投影,此处每个人变成一个字符串;it = 唯一的参数
    val names: List<String> = persons.map { "${it.firstName} ${it.lastName.uppercase()}" }
    display("[map : firstName LASTNAME]", names)

    // 操作可以链式调用:昂热居民的姓名,按字母顺序排列
    val angevins = persons
        .filter { it.city == "Angers" }
        .map(Person::lastName)
        .sorted()
    display("[filter + map + sorted : the people of Angers]", angevins)

    // sortedBy、sortedByDescending:按键排序
    display("[sortedBy(lastName), first 3]", persons.sortedBy { it.lastName }.take(3).map { it.lastName })

    // 按多个条件排序:年龄递减,然后姓氏递增
    val sorted = persons.sortedWith(compareByDescending<Person> { it.age }.thenBy { it.lastName })
    display("[sortedWith with a Comparator]", sorted)

    // 元素的位置:mapIndexed、withIndex
    display("[mapIndexed : numbering]", persons.take(3).mapIndexed { i, p -> "${i + 1}. ${p.lastName}" })
    for ((i, p) in persons.withIndex().filter { it.value.age < 18 }) {
        println("[withIndex] minor at index $i : ${p.lastName}")
    }

    // 列表可以被迭代任意多次……
    val minors = persons.filter { it.age < 18 }
    println("[a list] ${minors.count()} minors, then again ${minors.count()}")
    // ……但 Java 流(java.util.stream.Stream)不行,它可以在 Kotlin 中使用
    val stream = persons.stream().filter { it.age < 18 }
    println("[a Java stream already consumed] ${stream.count()} minors")
    try {
        stream.count()
    } catch (e: IllegalStateException) {
        println("  ${e.javaClass.simpleName} : ${e.message}")
    }
}

// 显示集合的元素
fun <T> display(title: String, elements: Iterable<T>) {
    println(title)
    elements.forEach { println("  $it") }
}

// 一个人
data class Person(val lastName: String, val firstName: String, val age: Int, val city: String)

结果:

> gradlew -q run -Pmain=streams02.Streams02Kt
[filter : the adults]
  Person(lastName=dupont, firstName=jean, age=45, city=Angers)
  Person(lastName=durand, firstName=paul, age=32, city=Angers)
  Person(lastName=leroy, firstName=sophie, age=28, city=Nantes)
  Person(lastName=simon, firstName=julie, age=52, city=Angers)
  Person(lastName=laurent, firstName=marc, age=32, city=Lyon)
[map : firstName LASTNAME]
  jean DUPONT
  marie MARTIN
  paul DURAND
  sophie LEROY
  luc MOREAU
  julie SIMON
  marc LAURENT
[filter + map + sorted : the people of Angers]
  dupont
  durand
  simon
[sortedBy(lastName), first 3]
  dupont
  durand
  laurent
[sortedWith with a Comparator]
  Person(lastName=simon, firstName=julie, age=52, city=Angers)
  Person(lastName=dupont, firstName=jean, age=45, city=Angers)
  Person(lastName=durand, firstName=paul, age=32, city=Angers)
  Person(lastName=laurent, firstName=marc, age=32, city=Lyon)
  Person(lastName=leroy, firstName=sophie, age=28, city=Nantes)
  Person(lastName=martin, firstName=marie, age=17, city=Paris)
  Person(lastName=moreau, firstName=luc, age=15, city=Paris)
[mapIndexed : numbering]
  1. dupont
  2. martin
  3. durand
[withIndex] minor at index 1 : martin
[withIndex] minor at index 4 : moreau
[a list] 2 minors, then again 2
[a Java stream already consumed] 2 minors
  IllegalStateException : stream has already been operated upon or closed

说明:

  • 第 6–13 行:由 [listOf] 创建的只读人员列表。Kotlin 允许最后一个元素之后带逗号(“尾随逗号”):这使得添加元素更容易;
  • 第 64 行:数据类 [Person],在文件级别声明,与函数并列;
  • 第 17 行:函数 [filter] 对列表进行 过滤:它只保留满足条件的元素。该条件以 lambda [{ p -> p.age >= 18 }] 的形式传递给它,其含义为“给定一个人 p,返回布尔值 [p.age >= 18] 的函数”。[filter] 对每个人调用这个函数。当函数的最后一个参数是函数时,lambda 写在圆括号之后,如果圆括号为空则可以省略:[persons.filter { ... }],而不是 [persons.filter({ ... })];
  • *[filter] 的结果是一个新列表,[List<Person>]:列表 [persons]* 保持不变。本节介绍的所有操作都是如此,它们对只读列表和可变列表都适用;
  • 第 58–60 行:泛型函数 [display] 使用 [forEach] 遍历集合并显示每个元素;一个人通过数据类的 [toString] 方法显示:[Person(lastName=dupont, ...)] (Java 使用方括号的地方这里使用圆括号);
  • 第 21 行:函数 [map] 将 每个元素投影为一个新值,在这里是一个字符串。结果是一个列表 [List<String>]。只有一个参数的 lambda 可以省略参数名;在这种情况下,该参数被称为 [it];
  • 第 25–28 行:这些操作返回集合,可以对其应用其他操作。操作通常一行写一个:这条调用链像菜谱一样自上而下阅读。[Person::lastName] 是一个 属性引用,是 lambda [{ it.lastName }] 的简写记法;
  • 第 28 行:[sorted] 按元素的自然顺序排序,在这里是字符串([sortedDescending] 按相反顺序排序);
  • 第 32 行:[sortedBy] 按由 lambda 计算出的 键 排序([sortedByDescending] 按降序);[take(3)] 保留前三个元素;
  • 第 35 行:对于基于多个条件的排序,[sortedWith] 接受一个 [Comparator],它使用第 4 章介绍的 Kotlin 函数构造:[compareByDescending<Person> { it.age }] (按年龄降序),然后是 [thenBy { it.lastName }] 用于区分年龄相同的人。Durand 和 Laurent 都是 32 岁,因此按姓名排序。类型 [Person] 必须在 [compareByDescending] 中指定,因为编译器无法仅从 lambda 推断它;
  • 第 39 行:对于编号,[mapIndexed] 除了元素本身之外,还会将元素的索引传递给 lambda;类似地,还有 [filterIndexed]、[forEachIndexed]……在 Java 中则必须使用 [IntStream.range] 来遍历索引;
  • 第 40–41 行:[withIndex] 将每个元素转换为一个 [IndexedValue] 对象(属性 [index] 和 [value]),可以对其进行过滤,然后在循环中解包为 [(i, p)] ;
  • 第 45–46 行:列表与任何集合一样,可以按需迭代任意多次:[filter] 的结果是一个真正的列表,而不是待执行的计算;
  • 第 48–53 行:Java 流([java.util.stream.Stream])通过列表上的 [stream] 方法获得(Kotlin 列表在运行时是一个 [java.util.List]),可以在 Kotlin 中使用;Kotlin lambda 会被自动转换为 Java 函数式接口。不过,它仍然是一次性的:一旦被终端 操作(这里是 [count])遍历,它就会抛出 [IllegalStateException]。[e.javaClass.simpleName] 是 [e.getClass().getSimpleName()] 的 Kotlin 写法。

因此,Kotlin 的集合操作并不区分中间操作和终端操作:每个操作都会产生完整的结果。这种简单性是有代价的:一条由 n 个操作组成的链会创建 n 个中间集合。这对小集合来说不是问题,而小集合是迄今为止最常见的;对于大集合,或可能提前终止的操作,则使用序列(程序 [Streams05.kt])。与 Java 一样,与 C#(LINQ)不同,Kotlin 没有类似 SQL 的查询语法:处理过程被写成函数调用链。

5.5.3. 量词、聚合、元素选择

程序 [Streams03.kt] 包含返回单个值的操作和选择集合子集的操作:

package streams03

// 量词、聚合、选择元素、切片
fun main() {
    val persons = listOf(
        Person("dupont", "jean", 45, "Angers"),
        Person("martin", "marie", 17, "Paris"),
        Person("durand", "paul", 32, "Angers"),
        Person("leroy", "sophie", 28, "Nantes"),
        Person("moreau", "luc", 15, "Paris"),
        Person("simon", "julie", 52, "Angers"),
        Person("laurent", "marc", 32, "Lyon"),
    )

    // 量词:any(至少一个)、all(全部)、none(没有)
    println("any(minor)=${persons.any { it.age < 18 }}, all(minor)=${persons.all { it.age < 18 }}, " +
            "none(Brest)=${persons.none { it.city == "Brest" }}")

    // 聚合:count、sumOf;对数字列表使用 sum、average、min、max
    println("count()=${persons.count()}, count(Angers)=${persons.count { it.city == "Angers" }}")
    val ages: List<Int> = persons.map { it.age }
    println("sumOf(age)=${persons.sumOf { it.age }}, sum()=${ages.sum()}, " +
            "average()=${"%.2f".format(ages.average())}")
    println("min()=${ages.min()}, max()=${ages.max()}, minOf(age)=${persons.minOf { it.age }}")
    // minBy、maxBy 返回元素本身
    println("minBy(age)=${persons.minBy { it.age }.lastName}, maxBy(age)=${persons.maxBy { it.age }.lastName}")
    // fold、reduce:由函数计算的聚合
    val totalAges = persons.fold(0) { total, p -> total + p.age }
    val longest = persons.map { it.lastName }.reduce { a, b -> if (b.length > a.length) b else a }
    println("fold(sum of ages)=$totalAges, reduce(longest name)=$longest")

    // 选择元素:first、last、first { condition }
    val parisian = persons.first { it.city == "Paris" }
    println("first()=${persons.first().lastName}, first from Paris=${parisian.lastName}, " +
            "last()=${persons.last().lastName}")
    // 如果没有元素,firstOrNull 返回 null
    val brestResident: Person? = persons.firstOrNull { it.city == "Brest" }
    println("Brest : firstOrNull=$brestResident, ?.lastName ?: : ${brestResident?.lastName ?: "nobody"}")
    try {
        // first 要求存在一个元素
        persons.first { it.city == "Brest" }
    } catch (e: NoSuchElementException) {
        println("Brest : first { } : ${e.javaClass.simpleName} : ${e.message}")
    }
    // single 要求恰好存在一个元素
    println("single(Nantes)=${persons.single { it.city == "Nantes" }.lastName}, " +
            "singleOrNull(Paris)=${persons.singleOrNull { it.city == "Paris" }}")

    // distinct:移除重复项;distinctBy:每个键值保留一个元素
    println("distinct(cities)=${persons.map { it.city }.distinct()}")
    println("one person per city=${persons.distinctBy { it.city }.map { it.lastName }}")

    // 切片:take、drop、takeWhile、dropWhile、takeLast、dropLast
    val names = persons.map { it.lastName }
    println("take(2)=${names.take(2)}, drop(5)=${names.drop(5)}, takeLast(1)=${names.takeLast(1)}")
    println("drop(2).take(2)=${names.drop(2).take(2)}, slice(2..3)=${names.slice(2..3)}")
    println("takeWhile(length 6)=${names.takeWhile { it.length == 6 }}, " +
            "dropWhile(length 6)=${names.dropWhile { it.length == 6 }}")

    // chunked:拆分为固定大小的块(分页);windowed:滑动窗口
    names.chunked(3).forEachIndexed { i, page -> println("page ${i + 1} : ${page.joinToString(", ")}") }
    println("windowed(3)=${ages.windowed(3)}")
    println("windowed(3) { average }=${ages.windowed(3) { it.average() }.map { "%.1f".format(it) }}")
}

data class Person(val lastName: String, val firstName: String, val age: Int, val city: String)

结果:

> gradlew -q run -Pmain=streams03.Streams03Kt
any(minor)=true, all(minor)=false, none(Brest)=true
count()=7, count(Angers)=3
sumOf(age)=221, sum()=221, average()=31.57
min()=15, max()=52, minOf(age)=15
minBy(age)=moreau, maxBy(age)=simon
fold(sum of ages)=221, reduce(longest name)=laurent
first()=dupont, first from Paris=martin, last()=laurent
Brest : firstOrNull=null, ?.lastName ?: : nobody
Brest : first { } : NoSuchElementException : Collection contains no element matching the predicate.
single(Nantes)=leroy, singleOrNull(Paris)=null
distinct(cities)=[Angers, Paris, Nantes, Lyon]
one person per city=[dupont, martin, leroy, laurent]
take(2)=[dupont, martin], drop(5)=[simon, laurent], takeLast(1)=[laurent]
drop(2).take(2)=[durand, leroy], slice(2..3)=[durand, leroy]
takeWhile(length 6)=[dupont, martin, durand], dropWhile(length 6)=[leroy, moreau, simon, laurent]
page 1 : dupont, martin, durand
page 2 : leroy, moreau, simon
page 3 : laurent
windowed(3)=[[45, 17, 32], [17, 32, 28], [32, 28, 15], [28, 15, 52], [15, 52, 32]]
windowed(3) { average }=[31.3, 25.7, 25.0, 31.7, 33.0]

说明:

  • 第 15–17 行:如果至少有一个元素满足条件,[any] 返回 [true] ;如果所有元素都满足,[all] 返回 true;如果没有一个元素满足,[none] 返回 true(对应 Java 流的 [anyMatch]、[allMatch] 和 [noneMatch] )。不带参数时,[any()] 指示集合是否至少有一个元素。在字符串模板中,[${ ... }] 可以包含任何表达式,包括带 lambda 的函数调用;
  • 第 20 行:[count] 统计元素个数;带条件时,它统计满足条件的元素个数,无需先过滤。对于集合,属性 [size] 显然比 [count()] 更可取;
  • 第 21–23 行:[sumOf { it.age }] 对每个元素的计算值求和。在数字集合([List<Int>])上,函数 [sum] 和 [average] 可以直接应用:不必像 Java 中那样经过专门的流([mapToInt(...)] 后接 [IntStream])。[average] 返回一个 [Double],对于空集合,它是 [NaN] (“非数字”)。["%.2f".format(x)] 使用系统语言格式化数字:因此使用小数点;
  • 第 24 行:[min] 和 [max] 返回可比较元素集合中的最小和最大元素;[minOf { it.age }] 返回计算值中的最小值。如果集合为空,这些函数会抛出 [NoSuchElementException] ;它们的变体 [minOrNull]、[maxOrNull]、[minOfOrNull]……则返回 [null];
  • 第 26 行:[minBy] 和 [maxBy] 返回具有最小或最大键的 元素 (在这里是人),而不是键值本身。Java 返回的是必须用 [Optional<Person>] 打开的 [get],而 Kotlin 直接返回这个人(如果集合为空则抛出异常;[minByOrNull] 则返回 [null]);
  • 第 28–30 行:[fold] 计算任意聚合:它从一个初始值(这里是 0)开始,然后对每个元素使用上一次的结果([total])和该元素([p])调用 lambda,并返回最终结果。[reduce] 做同样的事,但使用第一个元素作为初始值:这里每一步都保留两个姓名中较长的那个。[sum]、[count]、[max]……只是这两个函数的特例;
  • 第 32–35 行:[first] 返回第一个元素——带条件时,返回满足该条件的第一个元素。[last] 返回最后一个;
  • 第 37–38 行:布雷斯特没有人。[firstOrNull] 于是返回 [null]:其返回类型为 [Person?]。Java 使用 [Optional] 的地方,Kotlin 使用 可空类型 及其运算符:[brestResident?.lastName ?: "nobody"] 如果有这个人则返回其姓名,否则返回“nobody”。这与 Java 的 [map(Person::lastName).orElse("nobody")] 完全等价;
  • 第 39–43 行:[first] 要求必须存在一个元素;否则,它会抛出 [NoSuchElementException]。当没有值就意味着错误时使用它;当没有值属于正常情况时,则使用 [firstOrNull]。整个库都遵循同样的命名约定:[last]/[lastOrNull]、[single]/[singleOrNull]、[elementAt]/[elementAtOrNull]、[getOrNull] (针对索引)……;
  • 第 45–47 行:[single] 要求有 恰好一个 元素(满足条件的);否则,它会抛出异常。[singleOrNull] 在没有元素或有多个元素时返回 [null] ,就像这里的巴黎那样。Java 流没有对应的操作;
  • 第 50 行:[distinct] 删除重复项(由 [equals] 方法定义);
  • 第 51 行:[distinctBy] 删除键已经出现过的元素:这样,我们就保留了每个城市的第一个实例。Java 课程中本应自己实现这个操作,使用一个存放已见过城市的集;
  • 第 54–58 行:[take(n)] 保留前 n 个元素,而 [drop(n)] 跳过它们(Java 中的 [limit] 和 [skip] );[takeLast] 和 [dropLast] 从末尾开始做同样的事。将 [drop] 和 [take] 组合起来,可以提取结果的一个“页”;对于列表,[slice(2..3)] 直接提取某个索引范围内的元素。[takeWhile] 在条件为真期间保留元素,并在第一个不满足条件的元素处停止;[dropWhile] 则相反:它跳过这些元素,并保留其后的所有元素;
  • 第 61 行:[chunked(3)] 将集合拆分成每个包含 3 个元素的列表,最后一个列表可能更短:这就是分页。Java 24 为此不得不引入“gatherer”([gather(Gatherers.windowFixed(3))]);而 Kotlin 自 1.2 版本起就有 [chunked] ;
  • 第 62–63 行:[windowed(3)] 生成由 3 个连续元素组成的 滑动窗口 :元素 0–2,然后是 1–3,再然后是 2–4……(对应 Java 24 的 [windowSliding(3)] )。与 [chunked] 一样,[windowed] 接受一个转换每个窗口的 lambda 表达式:这里我们计算三个人年龄的移动平均值。

5.5.4. 局部数据类、分组、连接

程序 [Streams04.kt] 包含更复杂的操作。Java 使用终端操作 [collect] 和 收集器 (来自 [Collectors] 类)来完成其中的大部分操作,而 Kotlin 为每一种操作都提供了单独的函数:

package streams04

// 局部数据类、分组、字典、连接
fun main() {
    val persons = listOf(
        Person("dupont", "jean", 45, "Angers"),
        Person("martin", "marie", 17, "Paris"),
        Person("durand", "paul", 32, "Angers"),
        Person("leroy", "sophie", 28, "Nantes"),
        Person("moreau", "luc", 15, "Paris"),
        Person("simon", "julie", 52, "Angers"),
        Person("laurent", "marc", 32, "Lyon"),
    )
    val cities = listOf(
        City("Angers", "Maine-et-Loire"),
        City("Nantes", "Loire-Atlantique"),
        City("Paris", "Paris"),
        City("Brest", "Finistère"),
    )

    // 1 - 局部数据类:在函数中声明的类型,用于中间结果
    data class Summary(val name: String, val decade: Int)
    println("[local data class]")
    persons
        .filter { it.age > 40 }
        .map { Summary(it.lastName, it.age / 10 * 10) }
        .forEach { (name, decade) -> println("  $name is over $decade") }

    // 2 - groupBy:按城市对人员分组,按首次出现的顺序
    println("[groupBy]")
    val byCity: Map<String, List<Person>> = persons.groupBy { it.city }
    for ((city, group) in byCity) {
        println("  %s : %d person(s), average age %.1f (%s)".format(
            city, group.size, group.map { it.age }.average(), group.joinToString(", ") { it.lastName }))
    }
    // 带值投影的 groupBy
    println("[groupBy(city, lastName)] ${persons.groupBy({ it.city }, { it.lastName })}")

    // 3 - 连接:每个人与同名的城市关联
    println("[join with flatMap]")
    persons
        .flatMap { p ->
            cities.filter { it.name == p.city }.map { c -> "${p.lastName} lives in the department ${c.department}" }
        }
        .forEach { println("  $it") }
    // 用城市字典做同样的连接,效率更高:每个人只查找一次
    val citiesByName: Map<String, City> = cities.associateBy { it.name }
    val join = persons
        .filter { it.age >= 18 }
        .mapNotNull { p -> citiesByName[p.city]?.let { c -> "${p.lastName}/${c.department}" } }
        .joinToString(", ")
    println("[join with a dictionary] $join")

    // 4 - 字典和分区:associate、associateWith、partition、zip
    val agesByName: Map<String, Int> = persons.associate { it.lastName to it.age }
    val lengths = listOf("one", "two", "three").associateWith { it.length }
    println("[associate] agesByName[\"leroy\"]=${agesByName["leroy"]} ; [associateWith] $lengths")
    val (adults, minors) = persons.partition { it.age >= 18 }
    println("[partition] adults=${adults.map { it.lastName }}, minors=${minors.map { it.lastName }}")
    val couples = persons.map { it.firstName }.zip(persons.map { it.lastName }) { firstName, lastName -> "$firstName $lastName" }
    println("[zip] ${couples.take(3)} ; ${listOf(1, 2, 3).zip(listOf("a", "b"))}")

    // 5 - 按组计数、求和
    println("[groupingBy + eachCount] ${persons.groupingBy { it.city }.eachCount().toSortedMap()}")
    val sumByCity = persons.groupBy { it.city }.mapValues { (_, group) -> group.sumOf { it.age } }
    println("[groupBy + mapValues + sumOf] ${sumByCity.toSortedMap()}")
    val maxAgeByCity = persons.groupingBy { it.city }.fold(0) { max, p -> maxOf(max, p.age) }
    println("[groupingBy + fold] $maxAgeByCity")

    // 6 - flatMap、flatten:将列表首尾相接
    println("[flatMap] ${cities.take(2).flatMap { listOf(it.name, it.department) }}")
    println("[flatten] ${listOf(listOf(1, 2), listOf(3), emptyList()).flatten()}")

    // 7 - 过滤后列表中每个元素的位置
    println("[position]")
    persons.filter { it.age < 30 }.forEachIndexed { i, p -> println("  $i : ${p.lastName}") }
}

data class Person(val lastName: String, val firstName: String, val age: Int, val city: String)

data class City(val name: String, val department: String)

结果:

> gradlew -q run -Pmain=streams04.Streams04Kt
[local data class]
  dupont is over 40
  simon is over 50
[groupBy]
  Angers : 3 person(s), average age 43.0 (dupont, durand, simon)
  Paris : 2 person(s), average age 16.0 (martin, moreau)
  Nantes : 1 person(s), average age 28.0 (leroy)
  Lyon : 1 person(s), average age 32.0 (laurent)
[groupBy(city, lastName)] {Angers=[dupont, durand, simon], Paris=[martin, moreau], Nantes=[leroy], Lyon=[laurent]}
[join with flatMap]
  dupont lives in the department Maine-et-Loire
  martin lives in the department Paris
  durand lives in the department Maine-et-Loire
  leroy lives in the department Loire-Atlantique
  moreau lives in the department Paris
  simon lives in the department Maine-et-Loire
[join with a dictionary] dupont/Maine-et-Loire, durand/Maine-et-Loire, leroy/Loire-Atlantique, simon/Maine-et-Loire
[associate] agesByName["leroy"]=28 ; [associateWith] {one=3, two=3, three=5}
[partition] adults=[dupont, durand, leroy, simon, laurent], minors=[martin, moreau]
[zip] [jean dupont, marie martin, paul durand] ; [(1, a), (2, b)]
[groupingBy + eachCount] {Angers=3, Lyon=1, Nantes=1, Paris=2}
[groupBy + mapValues + sumOf] {Angers=129, Lyon=32, Nantes=28, Paris=32}
[groupingBy + fold] {Angers=52, Paris=17, Nantes=28, Lyon=32}
[flatMap] [Angers, Maine-et-Loire, Nantes, Loire-Atlantique]
[flatten] [1, 2, 3]
[position]
  0 : martin
  1 : leroy
  2 : moreau

说明:

  • 第 22 行:一个 局部数据类,在使用它的函数内部声明(相当于 Java 16 的局部记录)。它让你无需在文件级别声明类,就能为处理操作的中间结果指定名称和类型:第 26 行:每个年龄超过 40 的人都被转换为一个只保留相关数据的 [Summary] ;
  • 第 27 行:lambda 表达式 解包 收到的 [Summary]:[(name, decade)] 置于圆括号中,声明了两个参数,它们按构造函数指定的顺序接收对象的两个属性。这对任何数据类(第 3 章)都可行,对元组和字典条目也同样可行;
  • 第 31 行:[groupBy] 将具有相同键的元素分组,这里的键是城市。结果是一个字典 [Map<String, List<Person>>]:每个城市都与其居民的列表相关联。Kotlin 标准库创建的字典([groupBy]、[associate]、[mapOf]……)是 [LinkedHashMap]:它们按键首次出现的顺序保存键。Java 默认创建的是顺序不可预测的 [HashMap] ,必须显式请求这一点([LinkedHashMap::new]);
  • 第 32–34 行:[for] 循环遍历字典条目,这些条目被解包为 [(city, group)]。对每个组,显示其大小、平均年龄和姓名;[joinToString(", ") { it.lastName }] 用分隔符把姓名连接起来:它的 lambda 函数将每个元素转换为字符串,这样就无需预先使用 [map];
  • 第 37 行:第二个可选的 lambda 对归入每个组的元素进行转换:这里只保留姓名(这就是 Java 的 [mapping] 收集器);
  • 第 42–45 行:一个 连接。与 Java 流一样,Kotlin 集合没有连接操作;我们用 [flatMap] 来实现,它的 lambda 为每个元素返回一个列表:[flatMap] 将所有这些列表连接起来。这里每个人都被替换为同名城市的列表(一个或没有),并转换为字符串。与 SQL 的内连接一样,只保留匹配的对:住在里昂的 Laurent——里昂不在城市列表中——不会出现,没有居民的布雷斯特也不会出现。这段代码对每个人都会遍历整个城市列表;
  • 第 47–51 行:同样的连接,但更高效。[associateBy { it.name }] 构建一个城市字典,其中键是城市名称,值是城市本身(即 Java 收集器 [toMap(City::name, v -> v)]);然后我们在这个字典中搜索每个成年人所在的城市。[citiesByName[p.city]] 返回一个 [City?] ,如果找不到该城市则返回 [null] ;[?.let { ... }] 仅在找到城市时才构造字符串,而 [mapNotNull] 是一个会剔除 [null] 结果的 [map]:过滤和投影在一次操作中完成。与 Java 中的 [toMap] 不同,[associateBy] 不会对重复的键报错:以最后一个值为准;
  • 第 55–57 行:[associate] 根据一个 lambda 构造字典,该 lambda 为每个元素返回一个键值对,写作 [it.lastName to it.age]。[associateWith] 以元素作为键并计算值:在这里是每个单词的长度;
  • 第 58–59 行:[partition] 根据条件把元素拆分为两个列表:满足条件的和其余的。结果是一对列表,它们被立即解包为 [(adults, minors)];Java 返回的是键为 [true] 和 [false] 的字典([partitioningBy]);
  • 第 60–61 行:[zip] 将两个集合中位置相同的元素配对,并在较短的那个结束时停止。不带 lambda 时,它返回一个由对组成的列表([(1, a)]……);带 lambda 时,它组合每一对元素——这里是组合成名后接姓。Java 流没有对应的操作;
  • 第 64 行:统计每个组中的元素个数。[groupingBy { it.city }] 并不构造这些组:它返回一个能够计算每个元素的键的 [Grouping] 对象;[eachCount] 随后遍历集合一次,统计每个键对应的元素个数(即 Java 收集器 [counting])。[toSortedMap] 将字典复制到一个按键排序的字典([TreeMap])中以便显示;
  • 第 65–66 行:按组对某个值求和:先用 [groupBy] 构造组,然后 [mapValues] 将字典中的每个值(这里是人员列表)转换为另一个值(这里是他们年龄之和),同时保留键。lambda 函数接收字典中的一个条目,由 [(_, group)] 解包:下划线 [_] 表示我们对键不感兴趣;
  • 第 67–68 行:[Grouping] 还有 [fold]、[reduce] 和 [aggregate],它们一次遍历就能计算按组聚合的结果,而无需构造组列表:这里是每个城市的最大年龄;
  • 第 71–72 行:再次使用 [flatMap] ,它将每个城市转换为由两个拼接字符串组成的列表;[flatten] “展平”列表的列表;
  • 第 76 行:每个元素在过滤后列表中的位置:[forEachIndexed] 将索引传递给 lambda。Java 则必须先将流存入列表,再遍历其索引。

下表总结了 Java 收集器与本程序中遇到的 Kotlin 函数之间的对应关系:

Java(流与收集器)
Kotlin(集合)
[collect(toList())]、[toList()]
不需要:结果已经是列表;[toList()]、[toMutableList()] 用于复制
[groupingBy(f)]
[groupBy(f)];[groupBy(f, g)] 对应 [groupingBy(f, mapping(g, toList()))]
[groupingBy(f, counting())]
[groupingBy(f).eachCount()]
[groupingBy(f, summingInt(g))]
[groupBy(f).mapValues { (_, l) -> l.sumOf(g) }]
[toMap(f, v -> v)]
[associateBy(f)]
[toMap(f, g)]
[associate { f(it) to g(it) }]、[associateBy(f, g)]
[partitioningBy(p)]
[partition(p)] (一对列表)
[joining(", ")]
[joinToString(", ")]
[flatMap(e -> stream)]
[flatMap { list }]、[flatten()]

5.5.5. 惰性求值:序列

对集合的操作会立即执行,每个操作都完整地执行。对 序列 ([Sequence<T>])的操作并不在编写时执行,而是在终端操作遍历序列时才执行:这就是 Java 流中所见的惰性求值。程序 [Streams05.kt] 使用会显示自身所做操作的 lambda,对两者进行了比较:

package streams05

import java.util.stream.IntStream
import kotlin.streams.asSequence
import kotlin.streams.asStream

// 惰性求值:序列(Sequence)与集合的比较;Java 流
fun main() {
    val numbers = mutableListOf(1, 2, 3, 4, 5, 6)

    // 1 - 对列表而言,每个操作都完整执行并创建一个新列表
    println("[list: immediate evaluation]")
    val squares = numbers
        .filter { println("  filter examines $it"); it % 2 == 0 }
        .map { println("  map computes $it*$it"); it * it }
    println("  result : $squares")

    // 2 - 定义序列并不会执行它
    println("[definition of the sequence]")
    val evenSquares: Sequence<Int> = numbers.asSequence()
        .filter {
            println("  filter examines $it")
            it % 2 == 0
        }
        .map {
            println("  map computes $it*$it")
            it * it
        }
    println("[the sequence is defined, nothing has been executed yet]")

    // 3 - 它由终端操作逐个元素地执行
    println("[forEach]")
    evenSquares.forEach { println("  forEach receives $it") }

    // 4 - 序列可以再次迭代:在源的当前状态上重新计算
    val large = numbers.asSequence().filter { it > 4 }
    println("[before adding] large=${large.toList()}")
    numbers.add(10)
    println("[after adding 10] large=${large.toList()}")

    // 5 - toList 在某一时刻存储结果
    val snapshot = large.toList()
    numbers.add(20)
    println("[after adding 20] large=${large.toList()}, snapshot=$snapshot")

    // 6 - first 一旦找到元素就停止迭代
    println("[first on a sequence]")
    val first = numbers.asSequence()
        .filter { println("  filter examines $it"); it > 2 }
        .first()
    println("  first=$first")

    // 7 - sorted 必须知道所有元素才能传递出第一个
    println("[sorted]")
    sequenceOf(3, 1, 2)
        .onEach { println("  before sorted : $it") }
        .sorted()
        .forEach { println("  after sorted : $it") }

    // 8 - 无限序列:generateSequence,以及由所有奇数组成的序列
    val powers = generateSequence(1) { it * 2 }
    println("[generateSequence] ${powers.take(10).toList()}")
    val odds = generateSequence(1) { it + 2 }
    println("[first odd number whose square exceeds 200] ${odds.first { it * it > 200 }}")

    // 9 - Java 流仍然可用;asSequence() / asStream() 转换
    val sumOfSquares = IntStream.rangeClosed(1, 10).filter { it % 2 == 0 }.map { it * it }.sum()
    val kotlinSum = (1..10).filter { it % 2 == 0 }.sumOf { it * it }
    println("[IntStream] sum of the squares of the even numbers from 1 to 10 = $sumOfSquares ; " +
            "in Kotlin : $kotlinSum")
    println("[conversions] ${IntStream.of(5, 3, 8).boxed().asSequence().sorted().toList()}, " +
            "${sequenceOf("a", "b").asStream().map { it.uppercase() }.toList()}")
}

结果:

> gradlew -q run -Pmain=streams05.Streams05Kt
[list: immediate evaluation]
  filter examines 1
  filter examines 2
  filter examines 3
  filter examines 4
  filter examines 5
  filter examines 6
  map computes 2*2
  map computes 4*4
  map computes 6*6
  result : [4, 16, 36]
[definition of the sequence]
[the sequence is defined, nothing has been executed yet]
[forEach]
  filter examines 1
  filter examines 2
  map computes 2*2
  forEach receives 4
  filter examines 3
  filter examines 4
  map computes 4*4
  forEach receives 16
  filter examines 5
  filter examines 6
  map computes 6*6
  forEach receives 36
[before adding] large=[5, 6]
[after adding 10] large=[5, 6, 10]
[after adding 20] large=[5, 6, 10, 20], snapshot=[5, 6, 10]
[first on a sequence]
  filter examines 1
  filter examines 2
  filter examines 3
  first=3
[sorted]
  before sorted : 3
  before sorted : 1
  before sorted : 2
  after sorted : 1
  after sorted : 2
  after sorted : 3
[generateSequence] [1, 2, 4, 8, 16, 32, 64, 128, 256, 512]
[first odd number whose square exceeds 200] 15
[IntStream] sum of the squares of the even numbers from 1 to 10 = 220 ; in Kotlin : 220
[conversions] [3, 5, 8], [A, B]

说明:

  • 第 13–16 行:应用于列表的 [filter] + [map] 链 。这些 lambda 在返回值之前会显示一条消息:lambda 的主体可以包含多条语句(这里因为在同一行,所以用分号分隔),而返回的是 最后一个表达式 的值:这里没有 [return];
  • 结果的第 2–10 行:[filter] 检查这六个数,并构造一个中间列表 [[2, 4, 6]];只有这时,[map] 才计算这三个平方数并构造结果列表。每一步都完整执行完毕,然后才执行下一步;
  • 第 20–29 行:对序列进行相同的处理,序列由 [numbers.asSequence()] 获得。这里的 lambda 表达式写成了多行;
  • 结果的第 13 行:序列定义之后,还没有显示任何内容:[filter] 和 [map] 都还没有检查过任何一个元素。[evenSquares] 并不包含结果,而是包含一个计算的 描述 ;
  • 结果的第 15–26 行:计算在终端操作 [forEach] (第 33 行)期间逐个元素地运行:每个数都先经过 [filter],如果是偶数,再经过 [map] ,然后进入 [forEach] ,之后才检查下一个数。不会构造任何中间列表;
  • 第 36–39 行:与 Java 流不同,从集合获得的序列可以被多次遍历:每个终端操作(这里是 [toList] )都会基于集合的当前状态从头重新开始计算。因此,在添加 10 之前创建的序列会把这一点考虑进去。Java 则必须存储一个能重新创建流的 lambda([Supplier<Stream<Integer>>]);这样的序列本身就已经是一种可重用的模式了。不过,有些序列只能被遍历一次:例如基于迭代器或输入流构建的序列;[constrainOnce()] 返回一个在第二次遍历时会抛出 [IllegalStateException] 的序列;
  • 第 42–44 行:[toList] 执行处理并存储其结果:[snapshot] 是一个看不到 20 的添加的列表;
  • 第 48–50 行:[first] 一获得一个元素就停止迭代:3 之后的数字永远不会被检查。[any]、[take]、[takeWhile]、[firstOrNull]……同样会尽早停止迭代;这正是能够处理无限序列的原因。在列表中,[filter { ... }.first()] 会在返回第一个元素之前检查全部八个数;因此我们改为写成 [first { ... }],它在找到第一个元素时就停止;
  • 第 55–58 行:某些中间操作无法逐个处理元素:[sorted] 必须知道所有元素,才能返回最小的那个。[sequenceOf(3, 1, 2)] 根据值创建一个序列;操作 [onEach] 会在每个元素经过时对其执行一个 lambda,而不修改它(相当于 Java 的 [peek]),它表明 [sorted] 在传出任何一个元素之前,就已收到了全部三个元素;
  • 第 61–64 行:由 [generateSequence] 创建的无限序列,我们之前在 [Streams01.kt] 中遇到过:2 的幂,其中前十个用 [take(10)] 保留;以及奇数,我们从中搜索平方首次超过 200 的第一个。必须遍历整个序列的操作([toList]、[count]、[sorted]……)在无限序列上永远不会结束:必须先对其加以限制;
  • 第 67 行:Java 流仍然可以在 Kotlin 中使用,包括基本类型的流([IntStream]、[LongStream]、[DoubleStream]);[IntStream.rangeClosed(1, 10)] 生成从 1 到 10 的整数。第 68 行在区间 [1..10] 上展示了 Kotlin 中的同一计算。在 Kotlin 中,没有针对基本类型的专用集合或序列:[List<Int>] 包含的是 [Integer] 对象。对于非常大量的数字,我们使用 [IntArray] 数组(它本身包含 [filter]、[map]、[sum]……);
  • 第 71–72 行:来自 [asSequence] 和 [asStream] 这两个扩展函数,它们位于 [kotlin.streams] 包(在第 4 行导入)中,用于将 Java 流转换为序列,反之亦然。它们用于与产生或需要流的 Java 库对接。[boxed] 将 [IntStream] 转换为 一个 [Stream<Integer>]。

什么时候应该使用序列而不是集合?

  • 对集合的操作是默认选择:对于中小型集合,它们简单且快速,因为中间集合的开销可以忽略不计;
  • 在以下情况切换到序列([asSequence()]):操作链很长且集合很大时(没有中间集合),或者处理可能提前停止时([first]、[take]、[any]……),或者元素按需生成时(无限序列、生成器、大文件中的行:我们将通过 [useLines] 看到这一点);
  • Java 流([stream()])在 Kotlin 程序中用处不大,除非是为了与 Java 库交互,以及使用其并行版本:集合的 [parallelStream] 方法返回一个流,其元素由多个线程同时处理(第 8 章),这是序列做不到的。它只会加快对大量数据的耗时操作,并且要求 lambda 没有副作用:只有在评估过其收益之后才应使用它。

下表比较了这三种工具:

 
Kotlin 集合
Kotlin 序列
Java 流
求值
立即执行,逐个操作
惰性,逐个元素
惰性,逐个元素
中间集合
每个操作一个
无
无
多次遍历
是
是(单次使用的序列除外)
否:每次遍历一个流
无限元素
否
是([generateSequence]、[sequence])
是([Stream.iterate]、[Stream.generate])
并行处理
否
否
是([parallelStream])
基本类型
否(数组 [IntArray]…… 除外)
否
是([IntStream]……)

我们将在整个课程中遇到这些操作,并且在第 7 章中,我们将看到函数类型及其所使用的高阶函数是如何构造的。

5.6. 文本文件

Kotlin 没有自己的文件 API:它使用 JDK 的文件 API,并用 扩展函数 对其进行补充以简化使用。提醒一下,Java 有两套文件 API:自 Java 1.0 起就可用的 [java.io] 包([File]、[FileReader]、[FileInputStream]……),以及 [java.nio.file] 包,它是 随 Java 7 引入的([Path]、[Files]……),功能更全面,并提供更好的错误报告。Kotlin 标准库为两者都提供了扩展:

  • [kotlin.io] 包(自动导入)扩展了 [java.io.File] 类:[File("infos.txt").readText()]、[readLines()]、[forEachLine { }]、[useLines { }]、[writeText(text)], [appendText(text)]、[bufferedReader()]、[printWriter()]……;
  • [kotlin.io.path] 包(需要导入)用同名函数扩展了 [java.nio.file.Path] 接口,并增加了创建函数 [Path("infos.txt")]、用于构造路径的运算符 [/] 、属性([name]、[extension]……),以及复制 [Files] 类功能的函数([exists]、[createDirectories]、[listDirectoryEntries]、[walk]……)。

与 Java 中一样,[Path] 是如今的首选:我们将使用 [kotlin.io.path]。相对路径,例如 [Path("infos.txt")],会以程序的 当前目录——即启动程序时所在的目录——补全。

所有这些函数默认都使用 UTF-8 编码,与操作系统无关,并且自 Kotlin 的第一个版本起就是如此;可选参数允许你指定其他编码。在 Java 方面,诸如 [java.io] ([FileReader]、[PrintWriter]……)等类的默认编码自 Java 18(JEP 400)起就是 UTF-8;在此之前,它取决于系统(在法语版 Windows 上通常是 Windows-1252)。使用 Kotlin 和 JDK 25,这不再是问题。

最后,请记住 Kotlin 没有 受检异常 (第 3 章):I/O 错误由派生自 [java.io.IOException] 的异常来表示,编译器不要求捕获或声明这些异常。由程序员决定在何处处理它们。

5.6.1. 读取文本文件

类 [java.io.BufferedReader] 允许你逐行读取文本文件的内容。它实际上还能够处理不是文件的流(例如网络连接)。它分块读取文件,并将这些块存储在缓冲区中:大多数读取都在内存中完成,而无需访问磁盘。Kotlin 为 [Path] (以及 [File])添加了函数,用来创建这个读取器或代我们使用它:

函数
作用
[path.bufferedReader(charset = Charsets.UTF_8)]
打开文件 [path] 进行读取,并返回一个 [BufferedReader];可选参数指定编码:[path.bufferedReader(Charsets.ISO_8859_1)]
[reader.readLine(): String?]
返回下一行(不含行尾字符),如果已到流的末尾则返回 [null] (Java 方法)
[reader.lineSequence()], [reader.readLines()], [reader.readText()]
以序列(按需读取,只能遍历一次)或列表的形式返回其余各行;返回其余全部文本(Kotlin 扩展)
[reader.close()]
关闭流并释放为管理它而分配的资源。这必须在流处理完毕之后进行,函数 [use] 会处理这一点
[path.readText()]、[path.readLines()]
打开文件,返回其全部内容(字符串、行的列表),并关闭它
[path.forEachLine { line -> ... }]
打开文件,对每一行调用 lambda,并关闭它
[path.useLines { lines -> ... }]
打开文件,将其各行的序列 [Sequence<String>] (按需读取)传递给 lambda,关闭文件,并返回 lambda 的结果

程序 [Files01.kt] 如下:

package files01

import java.io.IOException
import java.nio.file.NoSuchFileException
import kotlin.io.path.Path
import kotlin.io.path.absolute
import kotlin.io.path.bufferedReader
import kotlin.io.path.forEachLine
import kotlin.io.path.name
import kotlin.io.path.readText
import kotlin.io.path.useLines

// 读取文本文件:bufferedReader、readText、forEachLine、useLines
fun main(args: Array<String>) {
    // 当前文件夹:用相对名称指定的文件在此处查找
    println("Current folder: ${Path("").absolute().name}")
    // 文件名可以作为参数传入;否则使用 infos.txt
    val file = Path(args.firstOrNull() ?: "infos.txt")
    try {
        // 读取 1:用 BufferedReader 逐行读取
        println("Reading 1----------------")
        file.bufferedReader().use { reader ->
            while (true) {
                // 到达文件末尾时 readLine 返回 null
                val line = reader.readLine() ?: break
                println(line)
            }
        } // 此处流已关闭

        // 读取 2:一次读取整个文件
        println("Reading 2----------------")
        print(file.readText())

        // 读取 3:对每一行调用一个函数
        println("Reading 3----------------")
        file.forEachLine { println(it) }

        // 读取 4:按需读取的行序列,在 useLines 结束时关闭
        println("Reading 4----------------")
        val nbLines = file.useLines { lines -> lines.count { it.isNotBlank() } }
        println("$nbLines non-empty lines")
    } catch (e: NoSuchFileException) {
        // e.file 是找不到的文件的路径
        println("${e.javaClass.simpleName} : the file [${e.file}] does not exist")
    } catch (e: IOException) {
        // 其他输入输出错误
        println("${e.javaClass.simpleName} : ${e.message}")
    }
}

说明:

  • 第 5–11 行:[kotlin.io.path] 的扩展函数必须逐个导入(或通过 [import kotlin.io.path.*] 一起导入,我们稍后会这样做);IntelliJ 和 IDEA 会自动添加这些行;
  • 第 14 行:[main] 函数在这里通过 [args] 数组接收命令行参数;
  • 第 16 行:显示当前文件夹(即启动程序时所在的文件夹)的名称。[Path("")] 指向当前文件夹;[absolute()] 将其转换为完整路径,而属性 [name] 只保留其最后一个元素,以免完整路径使结果显得杂乱;
  • 第 18 行:读取的文件是作为参数传入的文件,或者是 [infos.txt]。[args.firstOrNull()] 返回第一个参数,如果没有参数则返回 [null] ;随后由 Elvis 运算符 [?:] 提供默认值。由于这是相对路径,因此会在当前目录中查找该文件;
  • 第 22 行:[bufferedReader()] 打开文件并返回一个 [BufferedReader]。扩展函数 [use] (第 3 章)执行传给它的 lambda,并将该对象([reader])传递给它,然后在退出 lambda 时 关闭 该对象,即使 lambda 内部发生了异常也是如此。这相当于 Java 的带资源的 [try] 语句;它适用于任何实现了 [AutoCloseable] (或 [Closeable])接口的对象,也就是具有释放资源(文件、网络连接、数据库连接等)的 [close] 方法的对象;
  • 第 23–26 行:逐行读取文件。在 Java 中,我们写 [while ((line = reader.readLine()) != null)],但在 Kotlin 中,赋值不是表达式:它不能被求值。因此,我们写一个无限循环,并写 [val line = reader.readLine() ?: break]:[readLine] 返回一个 [String?];如果它返回 [null] (文件结束),Elvis 运算符就会执行 [break],从而退出循环;否则,[line] 就是一个非空的 [String]。另一种更函数式的写法是 [reader.lineSequence().forEach { println(it) }];
  • 第 32 行:[readText] 一次性读取整个文件并关闭它。第 36 行:[forEachLine] 打开文件,对每一行调用 lambda,并关闭它:这是相当于读取 1 的单行写法;
  • 第 40 行:[useLines] 打开文件,并将其各行的 序列 传递给 lambda 函数,lambda 函数在处理文件时按需读取各行;文件在 lambda 函数结束时关闭,而 [useLines] 返回其结果(在这里是非空行的数量)。这使你可以处理几个 GB 大小的文件,对序列执行所有操作,而无需将其加载到内存中。序列不得离开 lambda:文件一旦关闭,就无法再遍历它;
  • 第 42–47 行:输入/输出错误由派生自 [java.io.IOException] 的异常报告。文件不存在会触发 [NoSuchFileException] (派生自 [java.nio.file]),而它又会触发这个异常;因此,必须先捕获它。它的属性 [file] (即 Java 方法 [getFile])返回所查找文件的路径。扩展 [java.io.File] 的函数则通过 [FileNotFoundException] 报告同样的错误。编译器不要求写这些 [catch] 子句:没有它们,错误会终止程序并显示异常。

文件 [infos.txt] 如下:

1
2
3
12620:0:0
13190:0,05:631
15640:0,1:1290,5

它位于 Gradle 项目 [05-classes-kotlin] 的根目录,即命令 [gradlew run] 的当前目录:

> gradlew -q run -Pmain=files01.Files01Kt
Current folder: 05-classes-kotlin
Reading 1----------------
12620:0:0
13190:0,05:631
15640:0,1:1290,5
Reading 2----------------
12620:0:0
13190:0,05:631
15640:0,1:1290,5
Reading 3----------------
12620:0:0
13190:0,05:631
15640:0,1:1290,5
Reading 4----------------
3 non-empty lines

使用一个不存在的文件(程序参数通过 [gradlew run] 的 [--args] 选项传递):

1
2
3
4
> gradlew -q run -Pmain=files01.Files01Kt --args="xx.txt"
Current folder: 05-classes-kotlin
Reading 1----------------
NoSuchFileException : the file [xx.txt] does not exist

当使用文件夹而不是文件时,读取它会导致另一个异常 [IOException],其消息由操作系统提供:

1
2
3
4
> gradlew -q run -Pmain=files01.Files01Kt --args="."
Current folder: 05-classes-kotlin
Reading 1----------------
IOException : Is a directory

这些测试是在 Linux 上运行的;在 Windows 上,最后这个错误的消息会有所不同。因此,我们将把程序的数据文件和示例应用程序放在项目根目录中。从 IntelliJ 和 IDEA 启动时,程序的当前目录同样是项目目录。

5.6.2. 写入文本文件

类 [java.io.BufferedWriter] 允许你写入文本文件。与 [BufferedReader] 一样,它使用缓冲区,并且能够处理不是文件的流。

函数
作用
[path.bufferedWriter(charset = Charsets.UTF_8, vararg options)]
打开文件 [path] 进行写入,并返回一个 [BufferedWriter]。文件会被创建,如果已存在则被清空。可选参数指定编码和打开模式:[path.bufferedWriter(options = arrayOf(StandardOpenOption.APPEND))] 将数据追加到现有文件的末尾
[writer.write(str)]
将 [str] 写入文件
[writer.newLine()]
写入行尾字符:系统默认的行尾字符,在 Windows 上为“\r\n”,在 Linux 和 macOS 上为“\n”
[writer.flush()]
将缓冲区的内容写入文件,而无需等待缓冲区写满
[writer.close()]
在将缓冲区的内容写入文件后关闭流。必须在处理完流之后进行:[use] 会处理这一点
[path.writeText(text)], [path.appendText(text)]
创建(或覆盖)文件并向其写入 [text];将 [text] 添加到文件末尾
[file.printWriter()]
(针对 [java.io.File])打开文件并返回一个 [PrintWriter],它具有方法 [print]、[println], 以及 [printf]

对 [BufferedWriter] 文件的写入不是即时的:文本先写入缓冲区,然后在缓冲区写满时、使用 [flush] 方法显式刷新时,或在流关闭时写入文件。这是对文件最高效的模式,因为它限制了磁盘访问。它并不适用于所有流,尤其是网络流:在两个对话方之间,一方写入的内容必须立即被另一方读取,因此每条消息之后都必须刷新缓冲区。我们稍后将使用的 [java.io.PrintWriter] 类添加了方法 [print]、[println] 和 [printf],并且可以在每次 [println] 之后自动清空其缓冲区([PrintWriter(writer, true)] 构造函数)。

程序 [Files02.kt] 如下:

package files02

import java.io.IOException
import java.nio.charset.Charset
import kotlin.io.path.Path
import kotlin.io.path.bufferedWriter
import kotlin.io.path.fileSize
import kotlin.io.path.readText

// 用 BufferedWriter 写入文本文件
fun main() {
    val file = Path("infos2.txt")
    try {
        // 创建文本文件(如果已存在则覆盖)
        file.bufferedWriter().use { writer ->
            println("default encoding: ${Charset.defaultCharset()}")
            // 只要输入的行不为空就循环
            while (true) {
                print("line (nothing to stop): ")
                val line = readlnOrNull()?.trim() ?: ""
                if (line.isEmpty()) {
                    break
                }
                // 将该行写入文本文件,后跟行尾符
                writer.write(line)
                writer.newLine()
            }
        } // 关闭流:缓冲区被写入文件

        // 检查:我们读回所创建的文件
        println("Content of $file (${file.fileSize()} bytes):")
        print(file.readText())
    } catch (e: IOException) {
        println("The following error occurred: $e")
    }
}

结果(键盘输入的行是在提示之后输入的):

1
2
3
4
5
6
7
8
> gradlew -q run -Pmain=files02.Files02Kt
default encoding: UTF-8
line (nothing to stop): 1st line
line (nothing to stop): 2nd line
line (nothing to stop):
Content of infos2.txt (18 bytes):
1st line
2nd line

说明:

  • 第 15 行:[bufferedWriter()] 创建文件并返回一个 [BufferedWriter];同样,函数 [use] 会在退出 lambda 时自动关闭流(第 28 行的右花括号)。正是这次关闭将缓冲区中剩余的文本写入文件:没有它,文件可能会不完整;
  • 第 16 行:JDK 的默认编码是 UTF-8。另一方面,Kotlin 函数无论 JDK 的编码如何,默认都使用 UTF-8;
  • 第 19–20 行:提示使用 [print] 显示,它不会换行,然后 [readlnOrNull] 从键盘读取一行;如果标准输入已关闭(文件结束),它返回 [null] ,因此有 [?.trim() ?: ""];
  • 第 25–26 行:向文本文件写入一行,后接一个换行符;
  • 第 31 行:函数 [fileSize] (即 Java 方法 [Files.size])返回文件的大小,单位为字节。这 18 个字节的构成如下:16 个字符,再加上两个一字节的换行符(在运行测试的 Linux 上是“\n”;在 Windows 上,每个换行符“\r\n”会占用 2 个字节)。插入字符串模板中的 [Path] 对象会使用其 [toString] 方法显示:即路径;
  • 第 33 行:为什么要用编译器并不要求的 [try / catch]?我们可能会指定形如 [dir1/dir2/file] 的文件名,而目录 [dir1/dir2] 并不存在,导致无法创建文件。这时会抛出一个 [NoSuchFileException] 异常,它派生自 [IOException]。还有其他可能的异常情形(磁盘已满、权限不足等)。写入文件的程序必须预料到这些错误:[try / catch] 在这里将它们转换为清晰的消息,而不是导致程序终止。

5.6.3. 路径与 kotlin.io.path 的函数

对于常见操作,[kotlin.io.path] 的函数让你无需处理流:一个函数就能打开文件,完整地读取或写入它,然后关闭它。它们还允许你创建、复制、移动和删除文件与文件夹。这些函数大多调用 Java 类 [Files] 的方法,使其更便于使用:[path.exists()] 而不是 [Files.exists(path)]。

函数
作用
[Path("data", "cities.txt")], [folder / "cities.txt"]
使用系统分隔符构造路径([/] 运算符调用 Java 方法 [folder.resolve("cities.txt")])
[path.name]、[path.nameWithoutExtension]、[path.extension]、[path.parent]、[path.absolute()]
文件名、不含扩展名的文件名、扩展名、所在文件夹和完整路径
[path.readText()]、[path.readLines()]、[path.useLines { }]
将文件内容返回为字符串、行的列表,或按需读取的行的序列
[path.writeText(text)], [path.appendText(text)]
创建(或覆盖)文件并向其写入 [text];将 [text] 追加到文件末尾
[path.writeLines(lines)], [path.appendLines(lines)]
写入、添加一组行(集合或序列),每行之后都有换行符
[path.readBytes()]、[path.writeBytes(bytes)]
以字节数组的形式读取和写入文件
[path.exists()]、[path.isDirectory()]、[path.fileSize()]、[path.deleteExisting()]、[path.deleteIfExists()]、[path.copyTo(target)], [path.moveTo(target)]
检查文件是否存在、是否为文件夹;返回其大小、删除它、复制它或移动它
[path.createDirectories()]
创建文件夹及其不存在的父文件夹
[folder.listDirectoryEntries(glob)], [folder.walk()]
文件夹的元素(一个列表,可以用诸如 ["*.txt"] 的模式过滤),以及来自其整个树形结构的元素(一个序列)

程序 [Files03.kt] 使用了它们:

package files03

import java.io.File
import java.nio.charset.MalformedInputException
import kotlin.io.path.*

// 路径(Path)和 kotlin.io.path 的扩展函数
fun main() {
    // / 运算符用系统分隔符构建路径(Windows 上为 \,Linux 上为 /)
    val folder = Path("data")
    val path = folder / "cities.txt"
    println("path=$path, name=${path.name}, parent=${path.parent}, " +
            "nameWithoutExtension=${path.nameWithoutExtension}, extension=${path.extension}")

    // 如果文件夹不存在,createDirectories 会创建它(及其父文件夹)
    folder.createDirectories()

    // writeText:用给定文本以 UTF-8 创建(或覆盖)文件
    path.writeText("Angers\nNantes\n")
    // appendLines、appendText:追加到文件末尾
    path.appendLines(listOf("Paris", "Lyon"))
    // readLines:以列表形式返回所有行
    val lines: List<String> = path.readLines()
    println("readLines : ${lines.size} lines $lines")
    // readText:以字符串形式返回整个文件
    println("readText : ${path.readText().length} characters")
    // useLines:按需读取的行序列,在块结束时关闭
    path.useLines { cities ->
        cities.filter { it.startsWith("N") || it.startsWith("L") }
            .forEach { println("useLines + filter : $it") }
    }
    // java.io.File 类具有相同的扩展函数,以及其他一些(printWriter……)
    val squares = File("data", "squares.txt")
    squares.printWriter().use { pw ->
        for (i in 1..3) pw.println("$i;${i * i}")
    }
    println("File.readLines : ${squares.readLines()}, toPath=${squares.toPath()}")

    // 编码:默认为 UTF-8;可以强制使用其他编码
    val text = "café"
    (folder / "utf8.txt").writeText(text)
    (folder / "utf8bom.txt").writeText("\uFEFF" + text)
    (folder / "latin1.txt").writeText(text, Charsets.ISO_8859_1)
    val hex = HexFormat { upperCase = true }
    for (file in listOf("utf8.txt", "utf8bom.txt", "latin1.txt")) {
        val bytes: ByteArray = (folder / file).readBytes()
        println("%-12s: %2d bytes : %s".format(file, bytes.size, bytes.toHexString(hex)))
    }
    // 以 UTF-8 读回的 Latin-1 文件:readLines 拒绝无效字节……
    val latin1 = folder / "latin1.txt"
    try {
        println(latin1.readLines())
    } catch (e: MalformedInputException) {
        println("latin1.txt read as UTF-8 by readLines : ${e.javaClass.simpleName} : ${e.message}")
    }
    // ……readText 将每个无效字节替换为 � 字符
    println("latin1.txt read as UTF-8 by readText : ${latin1.readText()}")
    println("latin1.txt read as Latin-1 : ${latin1.readText(Charsets.ISO_8859_1)}")
    // 读取时不会去除 BOM:它只是多出的一个字符
    println("utf8bom.txt : ${(folder / "utf8bom.txt").readText().length} characters")

    // exists、listDirectoryEntries
    println("exists(cities.txt)=${path.exists()}, exists(xx.txt)=${(folder / "xx.txt").exists()}")
    for (file in folder.listDirectoryEntries("*.txt").sorted()) {
        println("  %-12s %3d bytes".format(file.name, file.fileSize()))
    }

    // 清理:文件夹必须为空才能删除;先删除其内容
    folder.walk(PathWalkOption.INCLUDE_DIRECTORIES)
        .sortedDescending()
        .forEach { it.deleteExisting() }
    println("after deletion : exists(data)=${folder.exists()}")
}

结果:

> gradlew -q run -Pmain=files03.Files03Kt
path=data/cities.txt, name=cities.txt, parent=data, nameWithoutExtension=cities, extension=txt
readLines : 4 lines [Angers, Nantes, Paris, Lyon]
readText : 25 characters
useLines + filter : Nantes
useLines + filter : Lyon
File.readLines : [1;1, 2;4, 3;9], toPath=data/squares.txt
utf8.txt    :  5 bytes : 636166C3A9
utf8bom.txt :  8 bytes : EFBBBF636166C3A9
latin1.txt  :  4 bytes : 636166E9
latin1.txt read as UTF-8 by readLines : MalformedInputException : Input length = 1
latin1.txt read as UTF-8 by readText : caf�
latin1.txt read as Latin-1 : café
utf8bom.txt : 5 characters
exists(cities.txt)=true, exists(xx.txt)=false
  cities.txt    25 bytes
  latin1.txt     4 bytes
  squares.txt   12 bytes
  utf8.txt       5 bytes
  utf8bom.txt    8 bytes
after deletion : exists(data)=false

说明:

  • 第 5 行:导入了 [kotlin.io.path] 中的所有函数;
  • 第 10–13 行:运算符 [/] (函数 [operator fun Path.div(other: String)];参见第 4 章中的运算符重载)使用系统的路径分隔符构造路径 [data/cities.txt] 。课程练习是在 Linux 上运行的:得到的路径是 [data/cities.txt];在 Windows 上,则是 [data\cities.txt]。以这种方式构造路径,而不是拼接字符串,可使代码具有可移植性。属性 [name]、[parent]、[nameWithoutExtension]、和 [extension] 对路径进行拆分;最后两个在 Java 中并不存在,在 Java 中你必须使用 [lastIndexOf] 搜索点号;
  • 第 16 行:如果文件夹 [data] 已存在,创建它不会导致错误;
  • 第 19–26 行:写入、追加和读取,每个都只需一条语句。[appendLines] 写入列表的每个元素,后接一个换行符;
  • 第 28–30 行:[useLines] 以序列的形式提供各行:它们随着循环的推进被逐行读取,并且所有序列操作都可以应用于它们。这使我们能够处理几个 GB 大小的文件而无需将其加载到内存中,而 [readLines] 则会这样做。文件在迭代期间保持打开,而 [useLines] 在 lambda 结束时关闭它:这等价于在带资源的 [Files.lines(path)] 中使用 [try] ;
  • 第 33–37 行:类 [java.io.File] 具有相同的扩展函数([readText]、[readLines]、[writeText]……),以及其他一些函数,例如 [printWriter],它返回一个 [PrintWriter] (方法 [print] 和 [println])。我们通过 [File] 从 [Path] 转换到 [toPath()],反之则通过 [toFile()];
  • 第 40–47 行:同一段文本“café”使用三种编码写入,然后使用 Kotlin 函数 [toHexString] 以十六进制显示文件中的字节,该函数由一个 [HexFormat] 对象配置(使用大写)。请注意,这里使用的 [HexFormat] 类是 Kotlin 的类([kotlin.text.HexFormat],自动导入),而不是 Java 的类([java.util.HexFormat]):
    • UTF-8 是默认编码,带重音的字符占 2 个字节(é = C3 A9),其他字符占 1 个字节:4 个字符共 5 个字节;
    • 带 BOM(字节顺序标记)的 UTF-8,文件以三个字节 EF BB BF 开头,这向软件表明该文件以 UTF-8 编码。Java 和 Kotlin 都不会自己写入 BOM:它是通过在文本开头写入字符 U+FEFF 得到的,表示为 [""];
    • Latin-1(ISO-8859-1)是西欧文本的传统编码,每个字符占一个字节(é = E9)。Kotlin 对象 [Charsets] 提供对常见编码([UTF_8]、[ISO_8859_1]、[UTF_16]……)的访问,就像 Java 类 [StandardCharsets] 一样;
  • 第 50–57 行:以与写入时不同的编码读取文件会损坏带重音的字符:文件末尾的字节 E9 在 UTF-8 中是无效的。[kotlin.io.path] 中并非所有函数的行为都相同,执行结果表明了这一点:[readLines] (它调用 [Files.readAllLines])会通过抛出 [MalformedInputException] 异常(派生自 [IOException])来拒绝这样的文件,而 [readText] 会将每个无效字节替换为字符 �,并且不报告错误。我们已验证,[useLines] 和 [forEachLine] 与 [readLines] 一样严格,而 [bufferedReader] 以及 [java.io.File] 的函数则是宽容的,就像 [readText] 一样;
  • 第 58 行:以正确的编码读取时,文件是正确的;
  • 第 60 行:读取时,Java 和 Kotlin 都不识别 BOM:它被读作文本开头的一个不可见字符,因此文本有 5 个字符而不是 4 个。如果需要读取带有 BOM 的 UTF-8 文件(由某些 Windows 软件生成),你必须自己删除这个字符([text.removePrefix("")])。如今,规则很简单:文本文件以不带 BOM 的 UTF-8 格式写入和读取;
  • 第 63–65 行:[exists] 检查文件是否存在;[listDirectoryEntries("*.txt")] 返回文件夹中名称与模式匹配的条目列表(一个“glob”:[*] 匹配任意字符序列)。该函数不保证名称的顺序:[sorted] 对它们排序。与 [Files.list] 不同,它返回的是列表而不是流:没有什么需要关闭;
  • 第 69–72 行:删除文件夹。[deleteExisting] (即 Java 方法 [Files.delete])拒绝删除非空文件夹:我们使用 [walk] 遍历整个树,它返回一个序列。默认情况下,[walk] 只返回文件;选项 [PathWalkOption.INCLUDE_DIRECTORIES] 会使其同时返回文件夹。路径按相反顺序排序([sortedDescending]),以便先删除文件夹的内容,再删除文件夹本身。Kotlin 还有一个函数 [deleteRecursively()] 可以完成所有这些工作,但它仍是 实验性的:编译器要求你使用 [@OptIn(ExperimentalPathApi::class)] 注解显式启用它。

文件函数会阻塞调用它们的线程,直到操作完成。在介绍协程的第 9 章中,我们将看到如何在长时间的 I/O 操作期间避免阻塞程序。

5.7. 二进制文件

5.7.1. DataOutputStream 和 DataInputStream 类

类 [java.io.DataOutputStream] 和 [java.io.DataInputStream] 用于向二进制文件写入和从中读取。在这样的文件中,数据不是以文本形式写入的,而是以其内部形式写入:[Int] 无论其值是多少,始终占用 4 个字节。它们是 字节流:派生自类 [OutputStream] 和 [InputStream],而文本流则派生自 [Writer] 和 [Reader]。Kotlin 没有自己的对应类:它使用 JDK 的类,以及一些用于创建它们的扩展函数([path.outputStream()]、[path.inputStream()]、[stream.buffered()]……)和用于关闭它们的函数 [use] 。

请考虑以下应用程序:

1
2
3
4
// syntax: gradlew -q run -Pmain=files04.Files04Kt --args="text binary logs"
// we read a text file (text) and store its content in a binary file (binary)
// the text file has lines of the form name : age which are written as (String, Int)
// (logs) is a text log file

位于项目根目录中的文本文件 [persons1.txt] 内容如下:

1
2
3
4
5
6
7
8
9
paul : 10
helene : 15

jacques : 11
sylvain : 12
xx : -1

xx: yy : zz
xx : yy

程序 [Files04.kt] 如下:

package files04

import java.io.DataOutputStream
import java.io.IOException
import java.nio.file.NoSuchFileException
import kotlin.io.path.Path
import kotlin.io.path.bufferedReader
import kotlin.io.path.outputStream
import kotlin.io.path.writer
import kotlin.system.exitProcess

// 语法:gradlew -q run -Pmain=files04.Files04Kt --args="text binary logs"
// 我们读取一个文本文件(text),并将其内容存入一个二进制文件(binary)
// 文本文件的行形如 name : age,写入时为(String, Int)
// (logs)是文本日志文件
fun main(args: Array<String>) {
    // 需要 3 个参数
    if (args.size != 3) {
        println("syntax: Files04 text binary logs")
        exitProcess(1)
    }
    val (text, binary, logFile) = args
    try {
        // 打开三个文件;每个 use 都会关闭其文件,顺序与打开顺序相反
        Path(text).bufferedReader().use { input ->
            DataOutputStream(Path(binary).outputStream().buffered()).use { output ->
                Path(logFile).writer().buffered().use { logs ->
                    // 处理文本文件
                    var lineNumber = 0
                    var nbPersons = 0
                    // 将错误写入日志文件的局部函数
                    fun log(message: String) {
                        logs.appendLine("Line no. [$lineNumber] of the file [$text] $message")
                    }
                    input.forEachLine { line ->
                        // 多一行
                        lineNumber++
                        // 空行?忽略它
                        if (line.isBlank()) return@forEachLine
                        // 形如 name : age 的行
                        val fields = line.trim().split(Regex("""\s*:\s*"""))
                        // 需要 2 个字段
                        if (fields.size != 2) {
                            log("has an incorrect number of fields")
                            return@forEachLine
                        }
                        // 第 1 个字段不能为空
                        var error = false
                        val (name, ageField) = fields
                        if (name.isEmpty()) {
                            log("has an empty name")
                            error = true
                        }
                        // 第二个字段必须是整数 >= 0;否则 toIntOrNull 返回 null
                        val age = ageField.toIntOrNull() ?: -1
                        if (age < 0) {
                            log("has an incorrect age [$ageField]")
                            error = true
                        }
                        // 如果没有错误,数据被写入二进制文件
                        if (!error) {
                            output.writeUTF(name)
                            output.writeInt(age)
                            nbPersons++
                        }
                    }
                    println("$lineNumber lines read, $nbPersons persons written to [$binary], " +
                            "errors in [$logFile]")
                }
            }
        }
    } catch (e: NoSuchFileException) {
        println("The file [${e.file}] does not exist")
        exitProcess(2)
    } catch (e: IOException) {
        println("The following error occurred: $e")
        exitProcess(3)
    }
}

让我们仔细看看涉及 [DataOutputStream] 类的操作:

  • 第 26 行:[DataOutputStream] 对象构建在另一个字节流之上,遵循 嵌套流 (“装饰器”设计模式)的原则:
    • [Path(binary).outputStream()] (Java 方法 [Files.newOutputStream])将字节流写入文件,文件会被创建,如果已存在则被截断;
    • [buffered()] 为其添加缓冲区,这样它就不会在每次写入时都访问磁盘:这是一个 Kotlin 扩展函数,返回一个 [BufferedOutputStream(this)];
    • [DataOutputStream] 添加了用于写入基本数据类型的方法;
  • 第 62–63 行:写入操作。[DataOutputStream] 类为每种简单数据类型提供一个方法:[writeInt]、[writeDouble]、[writeLong]、[writeBoolean]、[writeUTF] 用于字符串……;
  • 第 25–27 行:这三个文件由三个嵌套的 *[use] 调用打开:Kotlin 没有与 Java 的 *[try] 语句等价的写法,后者可以声明用分号分隔的多个资源。每个 [use] 都会在退出其 lambda 时关闭其流:因此,这三个文件会按与打开时相反的顺序关闭,即使发生异常也是如此。关闭最外层的流([DataOutputStream])会关闭它所包含的流。日志文件通过一个 [Writer] ([writer()])写入,该 Writer 配有缓冲区([buffered()],这里它返回一个 [BufferedWriter]);
  • 第 22 行:解构同样适用于数组:*[args]* 的前三个元素被存入三个具有显式名称的变量中;
  • 第 32–33 行:一个 局部函数 (第 3 章),在 lambda 内部声明,用于向日志文件写入一条错误消息。它可以访问周围的变量([logs]、[lineNumber]、[text]),这样就避免了重复消息的开头部分。[appendLine] 是一个 Kotlin 扩展函数,它写入一个字符串,后接一个换行符(["\n"],与系统无关),写入任何 [Appendable] 对象中,因此也适用于任何 *[Writer]*;
  • 第 35 行:文本文件由 [forEachLine] 逐行读取,它是 [BufferedReader] ([Reader])的扩展。循环体是一个 lambda:要转到下一行,我们不写 [continue] 而是写 [return@forEachLine] (第 39 行和第 45 行),这是一个 带标签的 return ,它终止 lambda 对当前行的执行。单独的 [return] 则会终止函数 [main];
  • 第 41 行:分隔符是字符 [:],两侧可有任意空格,这些空格会连同它一起被删除。Kotlin 函数 [split] 在这里接收一个正则表达式([Regex],将在本章后面讨论),写成原始字符串 ["""..."""] ,其中反斜杠不需要双写。注意:与 Java 的 [split(":")] 不同,使用字符串的 [split] 方法会按该字符串的字面意思进行拆分,而不是按正则表达式拆分;
  • 第 49 行:解包列表:它的两个元素被存入两个变量中;
  • 第 55 行:年龄必须是正整数或零。Java 程序必须编写一个捕获 [NumberFormatException] 异常的方法,而 Kotlin 使用 [toIntOrNull],如果字符串不是整数,它会返回 [null] ;随后 Elvis 运算符将其替换为 -1,这是年龄的一个无效值;
  • 第 20、74、77 行:[exitProcess(n)] (包 [kotlin.system])以 退出码 n 终止程序,脚本可以检查这个退出码(0:成功;这是 [main] 函数正常结束的程序的退出码)。它调用 [System.exit(n)] ,并且返回类型为 [Nothing]:编译器知道其后的指令永远不会被执行。

程序的三个参数通过 [--args] 选项传递给 [gradlew run]。结果如下:

> gradlew -q run -Pmain=files04.Files04Kt --args="persons1.txt persons1.bin logs.txt"
9 lines read, 4 persons written to [persons1.bin], errors in [logs.txt]

日志文件 [logs.txt] 包含以下内容:

1
2
3
4
> cat logs.txt
Line no. [6] of the file [persons1.txt] has an incorrect age [-1]
Line no. [8] of the file [persons1.txt] has an incorrect number of fields
Line no. [9] of the file [persons1.txt] has an incorrect age [yy]

不带参数,或使用不存在的文本文件:

1
2
3
4
> gradlew -q run -Pmain=files04.Files04Kt
syntax: Files04 text binary logs
> gradlew -q run -Pmain=files04.Files04Kt --args="xx.txt xx.bin xx.log"
The file [xx.txt] does not exist

二进制文件 [persons1.bin] 的内容可以使用 Linux 命令 [od] 以十六进制显示(在 Windows 上,PowerShell 命令 [Format-Hex] 会产生类似的显示):

1
2
3
4
5
> od -A d -t x1z persons1.bin
0000000 00 04 70 61 75 6c 00 00 00 0a 00 06 68 65 6c 65  >..paul......hele<
0000016 6e 65 00 00 00 0f 00 07 6a 61 63 71 75 65 73 00  >ne......jacques.<
0000032 00 00 0b 00 07 73 79 6c 76 61 69 6e 00 00 00 0c  >.....sylvain....<
0000048

这显示了 [DataOutputStream] 是如何写入数据的:

  • 字符串由 [writeUTF] 写入,前面是用 2 个字节表示的以字节为单位的长度:00 04,后面是“paul”的 4 个字节(70 61 75 6c)。字符使用 UTF-8 的一种变体编码;
  • 整数 [Int] 以 4 个字节写入,最高有效字节在前(称为“大端”顺序,用于网络协议):10 被写成 00 00 00 0a。这种格式在所有机器上都相同:在 Windows 上由 [DataOutputStream] 写入的文件可以在 Linux 上读取;
  • 数据是连续写入的,没有任何分隔符或换行符:文件长 48 个字节(最后一行:使用 [-A d] 选项,[od] 以十进制显示位置)。

因此,要读取这个文件,你必须知道所写入数据的确切顺序和类型。对于 [writeXX] 方法(来自 [DataOutputStream])中的每一个,类 [DataInputStream] 都有一个对应的方法 [readXX]:[readUTF]、[readInt]、[readDouble]……不过,它无法指示还剩多少字节可读:由 [DataInputStream] 读取的文件必须以其所包含的记录数开头,或者一直读取到发生 [EOFException] 异常为止,该异常表示流的结束。然而,异常应当保持其“异常”的性质,而文件结束并非异常情况。

5.7.2. RandomAccessFile 类

类 [java.io.RandomAccessFile] 使用 直接访问对文件进行读写:在读取或写入之前,可以将光标定位到文件中的任意位置。它具有与 [DataInputStream] 和 [DataOutputStream] 相同的读写方法(它实现了相同的接口,[DataInput] 和 [DataOutput]),此外还有:

方法
作用
[RandomAccessFile(name: String, mode: String)]
以读取([mode] "r")或读写("rw")方式打开文件
[length(): Long]
文件大小,以字节为单位
[filePointer: Long]
文件中的当前位置(Java 方法 [getFilePointer],在 Kotlin 中被视为属性)
[seek(pos: Long)]
移动到文件中的位置 [pos]

程序 [Files05.kt] 执行与上一个程序相反的操作:它读取二进制文件来创建文本文件。如果得到的文本文件包含原始文件中的正确数据,我们就知道文本 → 二进制 → 文本的转换成功了。

package files05

import java.io.EOFException
import java.io.FileNotFoundException
import java.io.IOException
import java.io.RandomAccessFile
import kotlin.io.path.Path
import kotlin.io.path.bufferedWriter
import kotlin.system.exitProcess

// 语法:gradlew -q run -Pmain=files05.Files05Kt --args="binary text"
// 我们读取一个二进制文件(binary),并将其内容存入一个文本文件(text)
// 二进制文件包含(String, Int)对
// 文本文件的行形如 name:age
fun main(args: Array<String>) {
    // 需要 2 个参数
    if (args.size != 2) {
        println("syntax: Files05 binary text")
        exitProcess(1)
    }
    val (binary, text) = args
    try {
        // 以读取("r")方式打开二进制文件,以写入方式打开文本文件
        RandomAccessFile(binary, "r").use { input ->
            Path(text).bufferedWriter().use { output ->
                // 处理二进制文件,直到到达文件末尾
                var nbPersons = 0
                while (input.filePointer < input.length()) {
                    // 先读取 name,再读取 age:与写入的顺序一致
                    val name = input.readUTF()
                    val age = input.readInt()
                    // 写入文本文件
                    output.appendLine("$name:$age")
                    nbPersons++
                }
                println("$nbPersons persons read from [$binary] and written to [$text]")
            }
            // 直接访问:回到文件开头并重新读取第一个人
            input.seek(0)
            println("first person: ${input.readUTF()}, ${input.readInt()} years old")
        }
    } catch (_: EOFException) {
        // 文件在一条记录的中间结束
        println("The file [$binary] is truncated")
        exitProcess(2)
    } catch (e: FileNotFoundException) {
        // RandomAccessFile 用 FileNotFoundException 报告文件缺失
        println(e.message)
        exitProcess(3)
    } catch (e: IOException) {
        println("The following error occurred: $e")
        exitProcess(4)
    }
}

让我们仔细看看涉及 [RandomAccessFile] 类的操作:

  • 第 24 行:[RandomAccessFile] 对象以只读模式(“r”模式)打开。它实现了 [Closeable]:[use] 会关闭它。文本文件由第二个 [use] 打开,它嵌套在第一个之内,并会先于第一个被关闭;
  • 第 28 行:读取一直持续到文件中的当前位置到达文件末尾。Kotlin 将形如 [getXxx()] 的 Java 方法表示为属性 [xxx]:我们写 [input.filePointer] 而不是 [input.getFilePointer()]。由于 [length] 不具有 [getXxx] 的形式,所以它仍然是方法;
  • 第 30–31 行:读取操作 [readUTF] 和 [readInt]。它们必须按写入的顺序调用;
  • 第 33 行:向文本文件写入一行;
  • 第 39–40 行:直接访问:[seek] 将位置重置到文件开头,并再次读取第一条记录。如果所有记录的大小都相同,我们就可以通过移动到位置 n × 大小来直接读取第 n 条记录:这就是直接访问文件的原理,它们是数据库的先驱;
  • 第 42 行:异常 [EOFException] 现在表示一个真正的异常情况:文件在一条记录的中间结束。由于没有使用异常本身,因此将其命名为 [_];
  • 第 46 行:[RandomAccessFile]([java.io] 的一个子类)通过 [FileNotFoundException] 报告文件不存在,其消息由系统提供,包含文件名。

让我们在之前生成的 [persons1.bin] 文件上运行该程序:

1
2
3
> gradlew -q run -Pmain=files05.Files05Kt --args="persons1.bin persons2.txt"
4 persons read from [persons1.bin] and written to [persons2.txt]
first person: paul, 10 years old

[persons2.txt] 的内容如下:

1
2
3
4
5
> cat persons2.txt
paul:10
helene:15
jacques:11
sylvain:12

我们找到了文件 [persons1.txt] 中的 4 个有效的人。使用一个名为 [truncated.bin] 的文件,它由 [persons1.bin] 的前 33 个字节组成(Linux 命令 [head -c 33 persons1.bin > truncated.bin]),读取 Jacques 年龄的尝试失败了:

> gradlew -q run -Pmain=files05.Files05Kt --args="truncated.bin truncated.txt"
The file [truncated.bin] is truncated

而对于不存在的文件:

> gradlew -q run -Pmain=files05.Files05Kt --args="xx.bin xx.txt"
xx.bin (No such file or directory)

Java 还有一种对象的 二进制序列化 机制:类 [ObjectOutputStream] 和 [ObjectInputStream] 可以写入和读取整个对象,前提是其类实现了 [java.io.Serializable] 接口。它可以在 Kotlin 中使用,但目前 属于 不推荐的做法:对来自不受信任来源的数据进行反序列化已导致大量攻击,因为反序列化可以执行攻击者选择的代码。应优先使用基于文本的格式,例如 JSON。

5.7.3. 使用 Jackson 进行 JSON 序列化

逐字节地写入和读取二进制文件非常繁琐,写入与读取之间哪怕有最轻微的不一致,也会产生错误的结果。通常更好的做法是 对对象进行序列化:将它们自动转换为字符序列,然后 反序列化 它们以重建对象。

JSON(JavaScript Object Notation)是一种基于文本、人类可读的通用格式:它是 Web 服务的交换格式(第 13 章)和许多配置文件的格式。对象写在花括号内,由“属性”: 值对组成,数组用方括号括起来。

Java 标准库和 Kotlin 标准库都不能读取或写入 JSON。需要使用外部库。Kotlin 程序有三种选择:

  • Jackson,使用最广泛的 Java 库,Spring Boot 默认使用它。它的第 3 版(2025 年)更改了包:[tools.jackson.*] ,而不是第 2 版的 [com.fasterxml.jackson.*] ,后者仍然很常见;它的注解仍位于 [com.fasterxml.jackson.annotation] 包中。与任何 Java 库一样,它可以直接在 Kotlin 中使用:这就是我们在这里使用的库,与 Java 课程一样;
  • Jackson 由 [jackson-module-kotlin] 模块(Jackson 3 对应 [tools.jackson.module:jackson-module-kotlin] )补充,该模块让它了解 Kotlin 的特性:默认参数值、可空类型、[object] 类……在本节末尾,我们将看到没有这个模块时 Jackson 缺少什么;
  • kotlinx.serialization,JetBrains 的序列化库,专为 Kotlin 编写:一个编译器插件([kotlin("plugin.serialization")])为每个带有 [@Serializable] 注解的类生成序列化它的代码,无需运行时反射。它天然支持默认值和可空类型,并且也能在 JVM 之外工作(Kotlin Multiplatform)。对于纯 Kotlin 项目,它是自然的选择;而对于 Spring 项目以及混合使用 Java 和 Kotlin 的项目,Jackson 仍是首选。

外部库在项目的构建文件中声明(第 2 章)。Gradle 项目 [05-classes-kotlin] 在其 [build.gradle.kts] 文件中声明了对 Jackson 的依赖:

// 第 5 章:常用的 Kotlin 类
plugins {
    kotlin("jvm") version "2.4.20"
    application
}

group = "examples"
version = "1.0"

repositories {
    mavenCentral()
}

dependencies {
    // 项目程序所使用的库
    // JSON:Jackson 3
    implementation("tools.jackson.core:jackson-databind:3.1.5")
}

kotlin {
    // 代码使用 JDK 25 编译和运行
    jvmToolchain(25)
    compilerOptions {
        // 编译器警告视为错误
        allWarningsAsErrors = true
        // 函数参数名保留在字节码中
        javaParameters = true
    }
}

application {
    // 由 [gradlew run] 运行的程序由 [main] 属性指定:
    // gradlew -q run -Pmain=strings01.Strings01Kt
    mainClass = providers.gradleProperty("main").orElse("strings01.Strings01Kt")
}

tasks.named<JavaExec>("run") {
    // 运行中的程序可以读取键盘
    standardInput = System.`in`
}

// 在 Windows 上,由 Gradle(run、bootRun 等)启动的程序的屏幕输出以 UTF-8 编码,
// 否则带重音符号的字符在 IntelliJ IDEA 控制台或终端中会出现乱码
tasks.withType<JavaExec>().configureEach {
    jvmArgs("-Dstdout.encoding=UTF-8", "-Dstderr.encoding=UTF-8")
}

说明:

  • 第 14–17 行:对 [jackson-databind] 库的依赖。Gradle 从中央仓库(Maven Central,第 11 行)下载它,同时下载它自身所依赖的库([jackson-core] 和 [jackson-annotations]);
  • 第 27 行:编译器在字节码中保留函数和构造函数参数的名称。这在这里至关重要:没有 Kotlin 模块时,Jackson 通过调用其主构造函数来创建数据类,正是借助其参数的名称,它才能将每个参数与同名的 JSON 属性关联起来。这等价于 Java 编译器的 [-parameters] 选项;
  • 第 31–34 行:由 [gradlew run] 执行的程序由命令行的 [main] 属性([-Pmain=...])指定;
  • 第 42–45 行:由 Gradle 启动的程序以 UTF-8 写出其输出,以便带重音的字符在 Windows 上正确显示(第 2 章)。

Jackson 中的核心对象是 [JsonMapper],它有两个主要方法:

方法
作用
[writeValueAsString(value: Any?): String]
返回表示对象 [value] 的 JSON 文本
[readValue(content: String, valueType: Class<T>): T]
重建一个类型为 [T] 的对象,数据来自 JSON 文本 [content];如果文本不正确,则抛出 [JacksonException] 。有一个重载接收 [TypeReference] 而不是 [Class]

程序 [Files06.kt] 使用了它们:

package files06

import com.fasterxml.jackson.annotation.JsonProperty
import java.math.BigDecimal
import kotlin.io.path.Path
import kotlin.io.path.readText
import kotlin.io.path.writeText
import tools.jackson.core.JacksonException
import tools.jackson.core.json.JsonWriteFeature
import tools.jackson.core.type.TypeReference
import tools.jackson.databind.MapperFeature
import tools.jackson.databind.SerializationFeature
import tools.jackson.databind.json.JsonMapper

// 使用 Jackson 3 进行 JSON 序列化

// 一个人:数据类,其属性成为 JSON 属性
data class Person(val name: String, val age: Int, val hobbies: List<String>)

// 一篇文章:@JsonProperty 注解设置 JSON 属性的名称
data class Article(@JsonProperty("reference") val code: String, val price: BigDecimal)

// 默认值……没有 Kotlin 模块时 Jackson 会忽略它们
data class Subscriber(val name: String, val age: Int = 18, val hobbies: List<String> = listOf("reading"))

// 名称以 is 开头的布尔属性
data class Account(val number: String, val isActive: Boolean)

// 反序列化泛型类型:借助 reified,类型 T 在运行时是已知的
inline fun <reified T> JsonMapper.readJson(json: String): T = readValue(json, object : TypeReference<T>() {})

fun main() {
    val persons = listOf(
        Person("paul", 10, listOf("football")),
        Person("hélène", 15, listOf("piano", "tennis")),
        Person("jacques", 11, listOf()),
    )

    // 1 - 使用默认配置的 JsonMapper:只需一行
    val mapper = JsonMapper.builder().build()
    println("[default] ${mapper.writeValueAsString(persons[1])}")
    // 非 ASCII 字符可以被转义
    val ascii = JsonMapper.builder().enable(JsonWriteFeature.ESCAPE_NON_ASCII).build()
    println("[ESCAPE_NON_ASCII] ${ascii.writeValueAsString(persons[1])}")

    // 2 - 一个选项:缩进
    val indented = JsonMapper.builder().enable(SerializationFeature.INDENT_OUTPUT).build()
    // 写入文本文件
    val file = Path("persons.json")
    file.writeText(indented.writeValueAsString(persons))
    println("[persons.json]")
    println(file.readText())

    // 3 - 反序列化:从 JSON 文本到对象
    val text = file.readText()
    // TypeReference 将完整类型 List<Person> 传给 Jackson
    val readBack: List<Person> = mapper.readValue(text, object : TypeReference<List<Person>>() {})
    println("[read back] ${readBack.size} persons")
    for ((name, age, hobbies) in readBack) {
        println("  $name, $age years old, hobbies: $hobbies")
    }
    // 用 readJson 函数以及数组做同样的事
    val readBack2 = mapper.readJson<List<Person>>(text)
    val array = mapper.readValue(text, Array<Person>::class.java)
    println("[readJson] equal=${readBack2 == readBack}, [Array] ${array.size} persons")

    // 4 - 由注解设置的属性名
    println("[@JsonProperty] ${mapper.writeValueAsString(Article("A12", BigDecimal("12.5")))}")
    // 读取时可以忽略属性名的大小写
    val caseMapper = JsonMapper.builder()
        .enable(MapperFeature.ACCEPT_CASE_INSENSITIVE_PROPERTIES)
        .build()
    val article = caseMapper.readValue("""{ "REFERENCE": "B7", "Price": 3 }""", Article::class.java)
    println("[ACCEPT_CASE_INSENSITIVE_PROPERTIES] $article")

    // 5 - 不正确的 JSON 文档会引发 JacksonException
    try {
        mapper.readValue("""{ "name": "x", "age": "twelve" }""", Person::class.java)
    } catch (e: JacksonException) {
        println("[error] ${e.javaClass.simpleName} : ${e.originalMessage}")
        println("[error] line ${e.location.lineNr}, column ${e.location.columnNr}, " +
                "path : ${e.pathReference}")
    }

    // 6 - Jackson 不了解的 Kotlin 类特性
    // 未知的 JSON 属性会被忽略
    val brestResident = mapper.readJson<Person>("""{"name":"x","age":1,"hobbies":[],"city":"Brest"}""")
    println("[unknown property] $brestResident")
    // 不使用参数的默认值
    for (json in listOf("""{"name":"x","age":20,"hobbies":["cycling"]}""", """{"name":"x","age":20}""",
            """{"name":"x"}""", """{"name":null,"age":20,"hobbies":[]}""")) {
        val result = try {
            mapper.readJson<Subscriber>(json).toString()
        } catch (e: JacksonException) {
            "${e.javaClass.simpleName} : ${e.originalMessage}"
        }
        println("[Subscriber] $json -> $result")
    }
    // isActive 属性以 active 为名写出……并且无法读回
    val jsonAccount = mapper.writeValueAsString(Account("C1", true))
    println("[isActive] $jsonAccount")
    try {
        mapper.readJson<Account>(jsonAccount)
    } catch (e: JacksonException) {
        println("[isActive] ${e.javaClass.simpleName} : ${e.originalMessage}")
    }
}

它在项目文件夹中运行,或从 IDE 中运行:

> gradlew -q run -Pmain=files06.Files06Kt
[default] {"name":"hélène","age":15,"hobbies":["piano","tennis"]}
[ESCAPE_NON_ASCII] {"name":"h\u00E9l\u00E8ne","age":15,"hobbies":["piano","tennis"]}
[persons.json]
[ {
  "name" : "paul",
  "age" : 10,
  "hobbies" : [ "football" ]
}, {
  "name" : "hélène",
  "age" : 15,
  "hobbies" : [ "piano", "tennis" ]
}, {
  "name" : "jacques",
  "age" : 11,
  "hobbies" : [ ]
} ]
[read back] 3 persons
  paul, 10 years old, hobbies: [football]
  hélène, 15 years old, hobbies: [piano, tennis]
  jacques, 11 years old, hobbies: []
[readJson] equal=true, [Array] 3 persons
[@JsonProperty] {"reference":"A12","price":12.5}
[ACCEPT_CASE_INSENSITIVE_PROPERTIES] Article(code=B7, price=3)
[error] InvalidFormatException : Cannot deserialize value of type `int` from String "twelve": not a valid `int` value
[error] line 1, column 23, path : files06.Person["age"]
[unknown property] Person(name=x, age=1, hobbies=[])
[Subscriber] {"name":"x","age":20,"hobbies":["cycling"]} -> Subscriber(name=x, age=20, hobbies=[cycling])
[Subscriber] {"name":"x","age":20} -> ValueInstantiationException : Cannot construct instance of `files06.Subscriber`, problem: Parameter specified as non-null is null: method files06.Subscriber.<init>, parameter hobbies
[Subscriber] {"name":"x"} -> MismatchedInputException : Cannot map `null` into type `int` (set `DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES` to 'false' to allow)
[Subscriber] {"name":null,"age":20,"hobbies":[]} -> ValueInstantiationException : Cannot construct instance of `files06.Subscriber`, problem: Parameter specified as non-null is null: method files06.Subscriber.<init>, parameter name
[isActive] {"number":"C1","active":true}
[isActive] MismatchedInputException : Cannot map `null` into type `boolean` (set `DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES` to 'false' to allow)

说明:

  • 第 3–13 行:所使用的 Jackson 类。与必须是独立 Maven 项目的 Java 程序不同,[Files06.kt] 与其他程序一样,是本章 Gradle 项目的一部分:Jackson 依赖是为整个项目声明的;
  • 第 18 行:要序列化的 [Person] 数据类。Jackson 不认识 Kotlin,但它能看到编译器生成的内容:一个带有访问方法 [getName], [getAge], [getHobbies] 的 Java 类,以及一个带三个参数的构造函数。每个访问方法都返回一个名为 JSON 的属性([getName] → [name]);
  • 第 21 行:注解 [@JsonProperty] 将 JSON 属性的名称设置为 [reference] 而不是 [code]。当它放在声明了属性的主构造函数的参数上时,该注解可以应用于参数、属性、字段或访问方法:Kotlin 2.4 在这里将其应用于构造函数参数和存储该属性的私有字段(我们使用命令 [javap -v] 在编译后的代码中验证了这一点;较旧版本的 Kotlin 只将其应用于参数)。Jackson 会把参数、字段和访问方法 [getCode] 映射到同一个属性,无论写入还是读取都使用名称 [reference] 。你可以指定目标:[@param:JsonProperty]、[@get:JsonProperty]、[@field:JsonProperty];
  • 第 40–41 行:[JsonMapper] 由 对象构建器创建:[JsonMapper.builder()] 返回一个对象,向其传递所需的选项,然后 [build] 创建 [JsonMapper]。使用默认选项时,文本写在单行上,带重音的字符按原样写入(结果的第 1 行)。[persons[1]] 是 [persons.get(1)] 的 Kotlin 写法;
  • 第 43–44 行:[ESCAPE_NON_ASCII] 选项指示程序将非 ASCII 字符写成转义序列:[é] 变为 [é]。文本仍然是正确的,但难以阅读;当 JSON 文本必须经过只识别 ASCII 的系统时,这很有用;
  • 第 47 行:选项 [INDENT_OUTPUT] 生成跨多行的缩进文本。列表被序列化为 JSON 数组;
  • 第 49–52 行:JSON 文本由 [writeText] 写入文本文件,然后读回并显示:如今二进制序列化就是这样被取代的;
  • 第 57 行:反序列化重建该列表。Jackson 通过调用数据类的构造函数来创建 [Person] 对象,构造函数的参数与同名的 JSON 属性相关联。对于列表,你必须向 Jackson 指定其元素的类型。然而,表达式 [List<Person>::class.java] 并不存在:泛型在编译时被 擦除 (“类型擦除”),Kotlin 与 Java 一样,在运行时只有一个 [List] 类,没有任何类型参数。使用 [TypeReference] 的技巧是创建一个派生自 [object : TypeReference<List<Person>>() {}] 的类的匿名对象([TypeReference<List<Person>>]):类的父类型会保留在编译后的代码中,Jackson 可以读取它;
  • 第 59–60 行:循环在读取每个人时将其解包;
  • 第 30 行:Kotlin 允许你一劳永逸地写出这个技巧。[readJson] 是 [JsonMapper] 的扩展函数,并且是 [inline],带有一个 [reified] 类型的参数(第 4 章):每次调用它时,其代码都会被复制,并用实际类型取代 [T]。因此,对 [mapper.readJson<List<Person>>(text)] (第 63 行)的调用会创建一个名为 [TypeReference<List<Person>>] 的对象,而不是 [TypeReference<T>]。[jackson-module-kotlin] 模块提供了类似的函数 [readValue<T>()],以及一个函数 [jacksonTypeRef<T>()];
  • 第 64 行:对于数组,情况更简单,我们直接传递 [Array<Person>::class.java] 类(相当于 Java 的 [Person[].class])。下一行验证读回的两个列表相等,这里的相等是指数据类意义上的相等;
  • 第 68 行:对 [Article] 的序列化:[reference] 属性具有由注解指定的名称。[BigDecimal] 被写成 JSON 数字;
  • 第 70–74 行:使用 [ACCEPT_CASE_INSENSITIVE_PROPERTIES] 选项,Jackson 在解析时忽略属性名的大小写:[REFERENCE] 和 [Price] 都会被接受。JSON 文本写在原始字符串 ["""..."""] 中,其中引号前不需要加反斜杠;
  • 第 76–82 行:无效的 JSON 文档——这里是在需要数字的地方给出了字符串——会导致一个派生自 [JacksonException] 的异常,具体来说是 [InvalidFormatException]。在 Jackson 3 中,这些异常派生自 [RuntimeException],而在 Jackson 2 中它们派生自 [IOException];对于没有受检异常的 Kotlin 来说,这种差异并不明显。[originalMessage] 返回不含定位信息的消息,而定位信息由 [location] 和 [pathReference] 单独提供:第 1 行第 23 列,类 [Person] 的属性 [age] 。Kotlin 将 Java 方法 [getOriginalMessage()]、[getLocation()]、[getLineNr()]……视为属性。

程序的最后一部分展示了在没有 Kotlin 模块时,Jackson 对 Kotlin 类不识别的内容。我们使用 Jackson 3.1.5 验证了这一点:

  • 第 87 行:类的未知 JSON 属性([city])被忽略。这是 Jackson 3 中的一个变化:[DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES] 选项在 Jackson 2 中默认启用,而在 Jackson 3 中默认禁用;如果希望拒绝该文档,可以使用 [JsonMapper.builder().enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)] 重新启用它;
  • 第 24 行:类 [Subscriber] 为 [age] (18)和 [hobbies] (一个包含“reading”的列表)设置了默认值。这些值不是由构造函数本身计算的,而是由编译器添加到类中的第二个 合成 构造函数计算的,用 Kotlin 编写的调用会使用它:Jackson 通过反射直接调用主构造函数,因而 忽略了它们。对于 JSON 文档中缺失的属性,它会向构造函数传递该类型的“空”值:对象为 [null] ,而对于 [Int] 这样的基本类型则是一个错误,因为 Jackson 3 默认启用 [FAIL_ON_NULL_FOR_PRIMITIVES] 选项(在 Jackson 2 中它是禁用的,会传递 0);
  • 第 90–97 行:四个测试文档产生如下结果(结果的第 27–30 行):
    • 完整的文档:对象被正常创建;
    • 没有 [hobbies]:Jackson 向参数 [null] 传递 [hobbies],而该参数是非空类型 [List<String>]。Kotlin 构造函数会检查其非空参数,并抛出 [NullPointerException] (“Parameter specified as non-null is null”),Jackson 将其作为 [ValueInstantiationException] 传播。默认值 [listOf("reading")] 没有被使用;
    • 没有 [age]:[MismatchedInputException],基本类型 [int] 没有值。默认值 18 没有被使用;
    • 使用 ["name": null]:同样的构造函数检查会拒绝 [null] 用于 [name]。这种行为其实是个好消息:Kotlin 关于 [null] 的安全性并没有被 Jackson 绕过;
  • 第 27、100–105 行:名称以 [is] 开头的布尔属性,例如 [isActive],其访问方法为 [isActive()](Kotlin 不会将其命名为 [getIsActive]);Jackson 遵循 JavaBeans 约定,推断出 JSON 属性 [active]。但构造函数参数名为 [isActive]:Jackson 在它自己写出的文档中找不到这个属性,验证因此失败。

[jackson-module-kotlin] 模块纠正了这三个问题(使用默认值、[isXxx] 属性保留其名称、针对 [null] 给出清晰的错误消息);kotlinx.serialization 也能正确处理它们。在没有它们的情况下,请记住以下规则:仅使用 Jackson 时,用于 JSON 的数据类不得依赖其默认值,也不得依赖以 [is] 开头的属性名。这也是我们在本课程其余部分将要遵循的做法,我们的 JSON 类将保持简单。

[JsonMapper] 的创建成本很高,但一旦创建,它就可以重复使用,并且可以在多个线程之间共享:程序通常只创建一个,并将其存放在常量中(顶层属性或 [object] 的属性)。我们将在本章末尾的示例应用程序中使用 JSON,然后在整个课程中继续使用。

5.8. 正则表达式

Kotlin 标准库提供了 [kotlin.text.Regex] 类,它支持使用 正则表达式。这些表达式让你可以验证字符串的格式。例如,你可以验证表示日期的字符串确实是 dd/mm/yy 格式。为此,你使用一个 模式 ,并将字符串与该模式进行比较。在这个例子中,d、m 和 y 必须是数字。因此,有效日期格式的模式是 [\d\d/\d\d/\d\d], 其中符号 [\d] 表示一个数字。在 JVM 中,类 [Regex] 是对 JDK 的类 [java.util.regex.Pattern] 的封装:模板语法和搜索引擎与 Java 中完全相同;只有编程接口有所变化。模板中可以使用的符号如下:

字符
描述
[\]
将后面的字符标记为特殊字符或字面字符。例如,[n] 对应字符 n,[\n] 对应换行符,[\\] 对应 \,而 [\(] 对应 (
[^]
对应字符串的开头
[$]
对应字符串的结尾
[*]
匹配前一个元素零次或多次。因此,[zo*] 匹配 z 或 zoo
[+]
匹配前一个元素一次或多次。因此,[zo+] 匹配“zoo”,但不匹配“z”
[?]
匹配前一个元素零次或一次。例如,[a?ve?] 匹配“lever”中的“ve”
[.]
匹配除换行符之外的任意单个字符
[(pattern)]
搜索该模式并存储匹配项(一个 组)。可以使用 [groupValues] 或 [groups] 属性从结果中提取匹配的子字符串。要匹配圆括号中的字符,请使用 [\(] 或 [\)]
[x|y]
匹配 x 或 y。例如,[z|foot] 匹配 z 或 foot;[(z|f)oo] 匹配 zoo 或 foo
[{n}]
n 是一个非负整数。恰好匹配前一个元素 n 次。例如,[o{2}] 不匹配 Bob 中的 o,但匹配 fooooot 中的前两个 o
[{n,}]
匹配前一个元素至少 n 次。例如,[o{2,}] 不匹配“Bob”中的“o”,但匹配“fooooot”中的所有“o”。[o{1,}] 等价于 [o+],而 [o{0,}] 等价于 [o*]
[{n,m}]
匹配前一个元素至少 n 次且至多 m 次。例如,[o{1,3}] 匹配“foooooot”中的前三个“o”;[o{0,1}] 等价于 [o?]
[[xyz]]
字符集:匹配所列字符之一。例如,[[abc]] 匹配“plat”中的字母“a”
[[^xyz]]
反向字符集:匹配未列出的任意字符。例如,[[^abc]] 匹配“plat”中的“p”
[[a-z]]
字符范围:匹配指定范围内的任意字符,这里是一个不带重音的小写字母
[[^m-z]]
反向字符范围:对应不在 m 和 z 之间的任意字符
[\b]
匹配单词边界,即单词字符与非单词字符之间的位置。例如,[er\b] 匹配“lever”中的“er”,但不匹配 “verb”中的“er”
[\B]
对应不是单词边界的位置。[en*t\B] 对应“entry”中的“ent”
[\d]
匹配一个数字;等价于 [[0-9]]
[\D]
对应不是数字的字符
[\f], [\n], [\r], [\t]
分别对应换页符、换行符、回车符和制表符
[\s]
对应任意空白字符:空格、制表符、换页符、换行符……等价于 [[ \t\n\x0B\f\r]]
[\S]
匹配不是空白字符的任意字符
[\w]
匹配任意单词字符:默认情况下,是不带重音的字母、数字或下划线;等价于 [[a-zA-Z_0-9]]。使用 [(?U)] 选项(见下文)时,它也能识别带重音的字母
[\W]
匹配不是单词字符的任意字符
[\num]
num 是一个正整数:引用编号为 num 的组。例如,[(.)\1] 对应两个连续的相同字符
[\xnn]、[\unnnn]
对应十六进制字符 nn(2 位数字)或 nnnn(4 位数字)。例如,[\x41] 对应 A

模板中的元素可以出现一次或多次。让我们以符号 [\d](它表示单个数字)为例,看几个例子:

模板
含义
[\d]
一个数字
[\d?]
0 个或 1 个数字
[\d*]
0 个或多个数字
[\d+]
1 个或多个数字
[\d{2}]
2 个数字
[\d{3,}]
至少 3 个数字
[\d{5,7}]
5 到 7 个数字

现在让我们设想一个能够描述字符串预期格式的模型:

目标字符串
模式
dd/mm/yy 格式的日期
[\d{2}/\d{2}/\d{2}]
hh:mm:ss 格式的时间
[\d{2}:\d{2}:\d{2}]
无符号整数
[\d+]
一串空格,可以为空
[\s*]
前面或后面可以有空格的无符号整数
[\s*\d+\s*]
可以带符号、前面或后面可以有空格的整数
[\s*[+-]?\s*\d+\s*]
前面或后面可以有空格的无符号实数
[\s*\d+(\.\d*)?\s*]
可以带符号、前面或后面可以有空格的实数
[\s*[+-]?\s*\d+(\.\d*)?\s*]
包含单词“just”的字符串
[\bjust\b]

请注意,在方括号内,字符 [|] 没有特殊含义:有时用于表示符号的 [[+|-]] 模式,也会接受数字前面的字符 |。同样,小数点必须转义,[\.]:未转义的句点匹配任意字符。

你可以指定在字符串中的何处搜索该模式:

模式
含义
[^pattern]
模板位于字符串的开头
[pattern$]
模板位于字符串的结尾
[^pattern$]
模式同时位于字符串的开头和结尾
[pattern]
在字符串的任意位置搜索该模式,从字符串的开头开始
搜索字符串
模式
以感叹号结尾的字符串
[!$]
以句点结尾的字符串
[\.$]
以序列 // 开头的字符串
[^//]
由单个单词组成的字符串,前面或后面可以有空格
[^\s*\w+\s*$]
恰好由两个单词组成的字符串,前面或后面可以有空格
[^\s*\w+\s+\w+\s*$]
包含单词“secret”的字符串
[\bsecret\b]

模式的子集可以被“提取”。因此,我们不仅可以验证字符串是否与特定模式匹配,还可以从该字符串中提取与模式中被圆括号括起来的子集相对应的元素。例如,如果我们解析一个包含 dd/mm/yy 格式日期的字符串,并且还想从该日期中提取元素 dd、mm 和 yy,我们将使用模式 [(\d\d)/(\d\d)/(\d\d)]。

剩下的就是在代码中写出模式。在两侧各用一个引号界定的普通字符串中,字符 [\] 与 Java 中一样是转义字符:模式中的每个 [\] 都必须双写,模式 [\d+] 写作 ["\\d+"]。Kotlin 提供了更好的解决方案:原始字符串,用三重引号括起来(我们已经遇到过),其中 [\] 是普通字符。模式按原样书写:["""\d+"""],而表示字符 \ 的模式 [\\] 写作 ["""\\"""] 而不是 ["\\\\"]。这是 Kotlin 中的标准做法,我们将遵循它。有一点需要注意:在原始字符串中,字符 [$] 后跟标识符或花括号会引入模板。字符串末尾的 [$] 后面跟着引号,不会造成问题;对于其他情况,Kotlin 2.2 引入了“多美元符号”插值字符串,我们将在程序 [Regex03.kt] 中看到。编辑器使阅读更容易:IntelliJ IDEA 能识别传递给 [Regex] 或 [toRegex] 的字符串,将它们高亮显示为正则表达式,并允许你测试它们(Alt+Enter,Check RegExp)。

5.8.1. 检查字符串是否与给定模式匹配

模式首先被 编译 为一个 [Regex] 对象,然后由它提供搜索函数。Java 使用一个中间的 [Matcher] 对象来存储搜索的状态,而 Kotlin 直接返回结果:

函数
作用
[Regex(pattern: String)]
编译模型 [pattern];如果模型不正确,则抛出 [PatternSyntaxException] 异常
[Regex(pattern, option)]、[Regex(pattern, options)]
同上,带有一个 [RegexOption] 选项,或一组 [Set<RegexOption>] 选项(见下文)
[String.toRegex()]
扩展函数:["""\d+""".toRegex()] 等价于 [Regex("""\d+""")]
[containsMatchIn(input)]
返回 [true] 的条件:字符串 [input] 包含 该模式的一次出现
[matches(input)]
返回 [true] 的条件:整个 字符串与该模式匹配
[CharSequence.matches(regex)]
[String] 的中缀扩展函数:["18/05/97" matches date]
[toPattern()]
获取 [java.util.regex.Pattern] 对象,即被 [Regex] 对象封装的那个

程序 [Regex01.kt] 如下:

package regex01

// 检查字符串是否匹配某个模式
fun main() {
    // 原始字符串:模式中的 \ 不必写两次
    val pattern1 = """^\s*\d+\s*$"""
    val regex1 = Regex(pattern1)
    // 将样本与模式进行比较
    for (sample in listOf("  123  ", "  123a  ", "4567")) {
        if (regex1.containsMatchIn(sample)) {
            println("[$sample] matches the pattern [$pattern1]")
        } else {
            println("[$sample] does not match the pattern [$pattern1]")
        }
    }
    // containsMatchIn 在字符串中搜索模式;matches 要求整个字符串匹配
    val number = """\d+""".toRegex()
    println("containsMatchIn(\"abc 123\") : ${number.containsMatchIn("abc 123")}"
            + ", matches(\"abc 123\") : ${number.matches("abc 123")}")
    // String 的中缀函数 matches:整个字符串
    val date = Regex("""\d{2}/\d{2}/\d{2}""")
    println("\"18/05/97\" matches date : ${"18/05/97" matches date}")
    println("\"5/1/01\".matches(date) : ${"5/1/01".matches(date)}")
    // Regex 对象封装了一个 java.util.regex.Pattern 对象
    val pattern: java.util.regex.Pattern = date.toPattern()
    println("date.toPattern().matcher(\"18/05/97\").matches() : ${pattern.matcher("18/05/97").matches()}")
}

结果:

1
2
3
4
5
6
7
8
> gradlew -q run -Pmain=regex01.Regex01Kt
[  123  ] matches the pattern [^\s*\d+\s*$]
[  123a  ] does not match the pattern [^\s*\d+\s*$]
[4567] matches the pattern [^\s*\d+\s*$]
containsMatchIn("abc 123") : true, matches("abc 123") : false
"18/05/97" matches date : true
"5/1/01".matches(date) : false
date.toPattern().matcher("18/05/97").matches() : true

说明:

  • 第 6 行:模式是一个无符号整数,两侧可以有空格,占据整个字符串(锚点 [^] 和 [$])。得益于原始字符串,[\] 无需重复书写:模板的写法与它在结果中出现的形式完全一致;
  • 第 7 行:模板由 [Regex] 类的构造函数编译;
  • 第 10 行:[containsMatchIn] 在字符串中搜索模式。两侧有空格的字符串“123a”与该模式不匹配:字符“a”既不可能是数字,也不可能是空格。如果没有锚点 [^] 和 [$],该字符串就会匹配,因为它 包含 一个数字。这相当于 Java 中的 [regex1.matcher(sample).find()] ;
  • 第 17 行:[String] 的扩展函数 [toRegex] 是编译模式的另一种方式;
  • 第 18–19 行:[containsMatchIn](在字符串 中 搜索模式)与 [matches](要求 整个 字符串与模式匹配,就像它被 [^] 和 [$] 界定一样)之间的区别;
  • 第 21–23 行:[String] 的扩展函数 [matches] 接受一个 [Regex] 对象;它被声明为 [infix] ,因此可以不带点号和圆括号书写(第 22 行)。与 Java 不同,Kotlin 没有提供将模板作为字符串接收并在每次调用时都编译它的 [matches(String)] 函数:调用 ["5/1/01".matches("\\d{2}")] 会被编译器拒绝([argument type mismatch: actual type is 'String', but 'Regex' was expected])。必须显式编译模型,这鼓励只编译一次;
  • 第 25–26 行:对象 [Regex] 封装了一个对象 [java.util.regex.Pattern]*,它由函数 *[toPattern] 返回。因此,API 中的所有 Java 代码仍然可以访问;反过来,[Pattern] 的扩展函数 [toRegex] 将一个 [Pattern] 转换为 一个 [Regex]。我们将在程序 [Regex06.kt] 中使用它。

5.8.2. 在字符串中查找模式的所有出现

函数 [find] 返回模式在字符串中的第一次出现,如果没有则返回 [null] 。函数 [findAll] 将所有出现作为一个 序列 返回([Sequence],惰性求值:每次出现只在被请求时才查找)。一次出现是一个 [MatchResult] 对象,它提供有关所找到元素的信息:

  • [value]:出现的文本,即与模式匹配的元素;
  • [range]:该元素在被搜索字符串中的位置范围 [IntRange] ;[range.first] 是找到该元素的位置,而 [range.last] 是其最后一个字符的位置;
  • [next()]:下一次出现,如果没有更多则为 [null] 。

程序 [Regex02.kt] 如下:

package regex02

// 查找字符串中某个模式的所有出现
fun main() {
    val pattern2 = """\d+"""
    val regex2 = Regex(pattern2)
    val sample3 = "  123  456  789 "
    println("Pattern=[$pattern2], sample=[$sample3]")
    // findAll 返回出现项的序列
    var nbOccurrences = 0
    for (occurrence in regex2.findAll(sample3)) {
        nbOccurrences++
        println("[${occurrence.value}] found at position ${occurrence.range.first}")
    }
    println("There are $nbOccurrences occurrences of the pattern in the sample")
    // find 返回第一个出现项(或 null);next 返回下一个出现项(或 null)
    var result = regex2.find(sample3)
    while (result != null) {
        print("${result.value} : ${result.range}  ")
        result = result.next()
    }
    println()
    // 序列上的操作应用于这些出现项
    val sum = regex2.findAll(sample3).sumOf { it.value.toInt() }
    println("sum of the numbers found: $sum")
    val vowels = Regex("[aeiouy]").findAll("antidisestablishmentarianism").count()
    println("number of vowels of \"antidisestablishmentarianism\": $vowels")
}

结果:

1
2
3
4
5
6
7
8
9
> gradlew -q run -Pmain=regex02.Regex02Kt
Pattern=[\d+], sample=[  123  456  789 ]
[123] found at position 2
[456] found at position 7
[789] found at position 12
There are 3 occurrences of the pattern in the sample
123 : 2..4  456 : 7..9  789 : 12..14
sum of the numbers found: 1368
number of vowels of "antidisestablishmentarianism": 11

说明:

  • 第 5 行:要搜索的模式是一串数字;
  • 第 7 行:搜索该模式所在的字符串;
  • 第 10–15 行:循环 [for] 遍历由 [findAll] 返回的出现序列。显示每一次出现及其位置。这里既没有 [Matcher] 对象,也没有像 Java 中那样反复调用 [find];
  • 第 17–20 行:同样是逐步遍历:[find] 返回第一次出现,类型为 [MatchResult?],而 [next] 返回 下一次出现,直到遇到 [null]。在循环内部,编译器知道 [result] 不是 [null] (智能类型转换,第 4 章)。[range] 的显示给出了位置范围:123 为 2..4;
  • 第 24 行:出现序列适用于所有序列操作;这里,我们使用 [sumOf] 对找到的数字求和。在 Java 中,你必须使用 [results] 方法(属于 [Matcher]),它返回 Stream API 的一个流;
  • 第 26 行:模式 [[aeiouy]](表示元音)的出现次数就是序列中的元素个数,由 [count] 返回。

5.8.3. 获取模式的各个部分

如前所述,模式中被圆括号括起来的部分会被存储:这些就是 组。[MatchResult] 对象以多种方式提供它们:

  • [groups]:组的集合,类型为 [MatchGroupCollection]。它的第 0 号元素是整个出现;后面的元素是第 1、2……组。每个组都是一个 [MatchGroup] 对象,具有 属性 [value] (捕获的文本)和 [range] (其位置);它的类型是 [MatchGroup?],因为可选的组,例如 [(\.\d+)?],可能什么也没有捕获;
  • [groupValues]:捕获文本的列表,类型为 [List<String>];没有捕获任何内容的组在其中用空字符串表示;
  • [destructured]:第 1 组及其后的各组,可直接被 解析:[val (h, m, s) = result.destructured]。

程序 [Regex03.kt] 使用了它们:

package regex03

import java.time.LocalDate
import java.time.format.DateTimeFormatter

// 获取模式的各部分:分组
fun main() {
    val pattern3 = """(\d\d):(\d\d):(\d\d)"""
    val regex3 = Regex(pattern3)
    val sample4 = "It is 18:05:49"
    // find 搜索模式的第一个出现项;没有则为 null
    val result = regex3.find(sample4)
    if (result != null) {
        println("The sample [$sample4] matches the pattern [$pattern3]")
        // 我们显示带括号的分组;分组 0 是整个出现项
        result.groups.forEachIndexed { i, group ->
            println("groups[$i]=[${group?.value}] found at position ${group?.range?.first}")
        }
        // 通过解构得到分组 1、2、3 的值
        val (hours, minutes, seconds) = result.destructured
        println("hours=$hours, minutes=$minutes, seconds=$seconds")
    } else {
        println("The sample [$sample4] does not match the pattern [$pattern3]")
    }

    // 命名分组:(?<name>...)
    val regexDate = Regex("""(?<day>\d{1,2})/(?<month>\d{1,2})/(?<year>\d{4})""")
    val text = "Appointment on 3/10/2026, then on 15/11/2026."
    val format = DateTimeFormatter.ofPattern("EEEE d MMMM yyyy")
    for (m in regexDate.findAll(text)) {
        // 用名称而不是编号来指定分组
        val day = m.groups["day"]!!.value.toInt()
        val month = m.groups["month"]!!.value.toInt()
        val year = m.groups["year"]!!.value.toInt()
        val date = LocalDate.of(year, month, day)
        println("[${m.value}] : day=$day, month=$month, year=$year -> ${date.format(format)}")
    }

    // replace:替换字符串中可以重用分组
    // $$"...":只有 $$ 引入模板,$ 是普通字符
    val reversed = regexDate.replace(text, $$"${year}-${month}-${day}")
    println("replace(string) : $reversed")
    // 带 lambda 的 replace:为每个出现项计算替换内容
    val iso = regexDate.replace(text) { r ->
        val (day, month, year) = r.destructured
        LocalDate.of(year.toInt(), month.toInt(), day.toInt()).toString()
    }
    println("replace(lambda) : $iso")
    // matchEntire:整个字符串必须匹配模式;groupValues:各分组的值
    println("matchEntire(\"25/12/2026\") : ${regexDate.matchEntire("25/12/2026")?.groupValues}")
    println("matchEntire(\"on 25/12/2026\") : ${regexDate.matchEntire("on 25/12/2026")?.groupValues}")
}

结果:

> gradlew -q run -Pmain=regex03.Regex03Kt
The sample [It is 18:05:49] matches the pattern [(\d\d):(\d\d):(\d\d)]
groups[0]=[18:05:49] found at position 6
groups[1]=[18] found at position 6
groups[2]=[05] found at position 9
groups[3]=[49] found at position 12
hours=18, minutes=05, seconds=49
[3/10/2026] : day=3, month=10, year=2026 -> Saturday 3 October 2026
[15/11/2026] : day=15, month=11, year=2026 -> Sunday 15 November 2026
replace(string) : Appointment on 2026-10-3, then on 2026-11-15.
replace(lambda) : Appointment on 2026-10-03, then on 2026-11-15.
matchEntire("25/12/2026") : [25/12/2026, 25, 12, 2026]
matchEntire("on 25/12/2026") : null

说明:

  • 第 12 行:字符串 [sample4] 与模式 [regex3] 进行比较;[find] 搜索模式的第一次出现,如果没有找到则返回 [null] 。随后第 13 行的测试确定,[result] 可以放心使用;
  • 第 16–17 行:集合 [groups] 通过其索引进行遍历:第 0 号元素是整个出现,第 1 到第 3 号元素是圆括号分组。由于这些元素的类型是 [MatchGroup?],因此使用运算符 [?.] 访问它们;这里,所有组都捕获到了一些文本。[range.first] 是这段文本在被检查字符串中的位置;
  • 第 20 行:[destructured] 属性允许你使用解构(第 3 章),用一条语句将第 1、2 和 3 组取到三个变量中。当你知道模板的各个组时,这是处理模板最简洁的方式;
  • 第 27 行:可以使用语法 命名 一个组:[(?<name>...)]。这里,模板识别 d/m/yyyy 格式的日期,日和月可以是一位或两位数字;
  • 第 32–34 行:使用索引运算符 [groups],通过名称而不是编号来引用命名组:代码更易读,并且不依赖于圆括号的顺序。结果的类型是 [MatchGroup?] (未知的名称会导致 [IllegalArgumentException] 异常;没有捕获任何内容的组会得到 [null]);这里,只要找到模板,这三个组总是会捕获文本,而运算符 [!!] 表达的正是这种确定性;
  • 第 35–36 行:类 [java.time.LocalDate] 表示不带时间的日期。它使用模板 [EEEE d MMMM yyyy] 显示:星期几以英文显示。Kotlin 直接使用 [java.time] 和 JDK 的类;
  • 第 41 行:函数 [replace] 将模板的每次出现替换为一个字符串,其中 [${name}] (或 [$1]、[$2]……用于编号的组)表示某个组的值。日期因此被重新格式化为年-月-日格式。但在 Kotlin 中,字符串里的 [${year}] 是一个模板,它会插入变量 [year] 的值!我们本可以写成 ["\${year}-\${month}-\${day}"]。这里的字符串使用了 Kotlin 2.2 的 多美元符号插值编写:在以 [$$] 为前缀的字符串中,模板写作 [$${...}],而孤立的字符 [$] 是普通字符。对于 ***[$$$]***,则需要三个,依此类推;
  • 第 44–46 行:*[replace] 的一个变体接受一个 lambda(第 7 章),该 lambda 根据每次出现(形式为 *[MatchResult])计算替换文本。按照 Kotlin 对函数最后一个参数的惯例,该 lambda 写在圆括号之后,它通过解构获取各个组,构造日期,并返回其规范化的 ISO 8601 形式,该形式由 [toString] 函数(来自 [LocalDate])生成:日和月始终是两位数。这等价于 *[replaceAll] 方法(来自 *[Matcher],它接受一个函数(Java 9));
  • 第 50–51 行:[matchEntire] 函数与 [matches] 一样,要求整个字符串与模式匹配,但它返回比较的结果([MatchResult]),如果比较失败则返回 [null] :这是用于检查字符串 并 提取其部分内容的函数。这里显示的是结果的 [groupValues] 属性:整个出现,后面是每个组的值。

5.8.4. 学习程序

找到用于验证字符串是否与某个模式匹配的正则表达式,有时可能是一个真正的挑战。程序 [Regex04.kt] 让你可以进行练习。它接受一个模式和一个字符串作为输入,并指示该字符串是否与该模式匹配。

package regex04

import java.util.regex.PatternSyntaxException
import kotlin.time.Duration.Companion.seconds
import kotlin.time.TimeSource

// 学习正则表达式的程序
fun main() {
    while (true) {
        // 我们询问模式
        val pattern = read("Type the pattern to test or nothing to stop: ")
        // 结束了吗?
        if (pattern.isBlank()) break
        // 我们编译正则表达式;不正确的模式会引发异常
        val regex = try {
            Regex(pattern)
        } catch (e: PatternSyntaxException) {
            println("Error: ${e.description} (position ${e.index})")
            continue
        }
        // 我们询问要与模式比较的样本
        while (true) {
            val string = read("Type the string to compare with the pattern [$pattern] or nothing to stop: ")
            // 结束了吗?
            if (string.isBlank()) break
            try {
                // 我们进行比较,限时一秒
                val deadline = TimeSource.Monotonic.markNow() + 1.seconds
                var found = false
                for (m in regex.findAll(TimeLimitedString(string, deadline))) {
                    found = true
                    // 我们显示与模式匹配的元素
                    println("I found the match [${m.value}] at position [${m.range.first}]")
                    // 及其子元素(分组 1、2、……)
                    for (group in m.groups.drop(1)) {
                        println("    sub-element [${group?.value}] at position [${group?.range?.first}]")
                    }
                }
                if (!found) println("I did not find any matches")
            } catch (_: TimeoutExceededException) {
                println("The search was abandoned: it lasted more than one second")
            }
        }
    }
}

// 读取键盘上的一行;流结束时为 ""
fun read(prompt: String): String {
    print(prompt)
    return readlnOrNull() ?: ""
}

// 超过截止时间后拒绝被读取的字符串
// CharSequence 中未被重写的成员(length)委托给 [text] 对象
class TimeLimitedString(
    private val text: CharSequence,
    private val deadline: TimeSource.Monotonic.ValueTimeMark
) : CharSequence by text {

    // 正则表达式引擎逐个字符地读取字符串
    override fun get(index: Int): Char {
        if (deadline.hasPassedNow()) throw TimeoutExceededException()
        return text[index]
    }

    override fun subSequence(startIndex: Int, endIndex: Int): CharSequence =
        TimeLimitedString(text.subSequence(startIndex, endIndex), deadline)

    override fun toString() = text.toString()
}

// 超过截止时间时抛出的异常
class TimeoutExceededException : RuntimeException()

说明:

  • 第 15–19 行:编译通过键盘输入的模板。不正确的模板会导致 [java.util.regex.PatternSyntaxException] 异常:[Regex] 类会透传它所封装的 [Pattern] 类抛出的异常。它的属性 [description] 和 [index] (即 Java 方法 [getDescription] 和 [getIndex],在 Kotlin 中被视为属性)提供错误描述及其在模板中的位置。它的完整消息,即属性 [message],跨越多行,并在错误下方用标记显示模型。请注意,[try] 是一个表达式(第 3 章):其值是 [try] 块的值,即对象 [Regex],或 [catch] 块的值。该块以 [continue] 结束,这是一个类型为 [Nothing] 、永远不会返回值的表达式:编译器据此推断 [regex] 的类型为 [Regex];
  • 第 28–30 行:搜索并不直接在输入的字符串上进行,而是在一个 [TimeLimitedString] 对象(第 55–69 行)上进行,该对象将搜索时间限制为一秒:如果搜索耗时更长,就会抛出 [TimeoutExceededException] 异常,并在第 40 行被捕获。稍后我们会看到这样做的用处及其工作原理。时间限制借助标准库中的 [kotlin.time] 类来计算:[TimeSource.Monotonic.markNow()] 是由单调时钟(不受系统时间变化影响)测得的当前时间,[1.seconds] 是一个时长 [Duration],它通过 [Int] 的扩展属性写出;
  • 第 35–36 行:对每个匹配,显示第 1 组及其后的各组(如果有):[drop(1)] 将第 0 号元素从集合 [groups] 中排除,即整个匹配内容;
  • 第 40 行:名称 [_] 表示捕获到的异常不被使用;
  • 第 48–50 行:与前面的程序不同,输入的行不会去除空格;空格可能是模板或待测试字符串的一部分。在输入流结束时,[readlnOrNull] 返回 [null],被替换为空字符串,从而终止程序。

下面是该程序的运行示例(从文件重定向的输入已被重新插入到提示符之后):

> gradlew -q run -Pmain=regex04.Regex04Kt
Type the pattern to test or nothing to stop: \d+
Type the string to compare with the pattern [\d+] or nothing to stop: 123 456 789
I found the match [123] at position [0]
I found the match [456] at position [4]
I found the match [789] at position [8]
Type the string to compare with the pattern [\d+] or nothing to stop:
Type the pattern to test or nothing to stop: (\d{2}):(\d\d)
Type the string to compare with the pattern [(\d{2}):(\d\d)] or nothing to stop: 14:15 abcd 17:18 xyzt
I found the match [14:15] at position [0]
    sub-element [14] at position [0]
    sub-element [15] at position [3]
I found the match [17:18] at position [11]
    sub-element [17] at position [11]
    sub-element [18] at position [14]
Type the string to compare with the pattern [(\d{2}):(\d\d)] or nothing to stop:
Type the pattern to test or nothing to stop: ^\s*\d+\s*$
Type the string to compare with the pattern [^\s*\d+\s*$] or nothing to stop:    1456
I found the match [   1456] at position [0]
Type the string to compare with the pattern [^\s*\d+\s*$] or nothing to stop:
Type the pattern to test or nothing to stop: ^\s*(\d+)\s*$
Type the string to compare with the pattern [^\s*(\d+)\s*$] or nothing to stop: 1456
I found the match [1456] at position [0]
    sub-element [1456] at position [0]
Type the string to compare with the pattern [^\s*(\d+)\s*$] or nothing to stop: abcd 1456
I did not find any matches
Type the string to compare with the pattern [^\s*(\d+)\s*$] or nothing to stop:
Type the pattern to test or nothing to stop: ^(a+)+$
Type the string to compare with the pattern [^(a+)+$] or nothing to stop: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa!
I did not find any matches
Type the string to compare with the pattern [^(a+)+$] or nothing to stop:
Type the pattern to test or nothing to stop: ^(a+)+\1$
Type the string to compare with the pattern [^(a+)+\1$] or nothing to stop: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa!
The search was abandoned: it lasted more than one second
Type the string to compare with the pattern [^(a+)+\1$] or nothing to stop:
Type the pattern to test or nothing to stop: (\d+
Error: Unclosed group (position 4)
Type the pattern to test or nothing to stop:

模板 [^\s*\d+\s*$] 与 [^\s*(\d+)\s*$] 展示了分组的价值:第一个模板能识别前面带有三个空格的字符串“1456”,空格也包含在内;第二个模板还能额外让我们提取不含空格的数字。模式 [^(a+)+$] 与 [^(a+)+\1$] 将在下文中研究。最后一个模式是错误的,因而被拒绝:它缺少右括号(“Unclosed group”),引擎在位置 4,即模式末尾检测到了这一点。该异常消息由 JDK 生成,是英文的。

5.8.5. split 函数

我们已经见过 [split] 函数,它来自 [String] 类。[Regex] 类也有同名函数,它使用已编译好的模板:

函数
作用
[split(input, limit = 0)]
字符串 [input] 被拆分为若干字段,各字段之间由与模板匹配的分隔符隔开;返回列表 [List<String>]。如果 [limit] 为正数,则它设定字段的最大数量
[splitToSequence(input)]
与上面相同,但字段以序列的形式返回,并且是惰性求值的
[CharSequence.split(regex)]
[String] 的扩展函数:[line.split(separator)] 等价于 [separator.split(line)]

例如,假设一个文本文件包含形如 field1, field2, ..., fieldn 的行。字段之间用逗号分隔,但逗号前后可能带有空格。模板 [\s*,\s*] 恰好描述了这种分隔符,如程序 [Regex05.kt] 所示:

package regex05

// split:分隔符由模式定义
fun main() {
    val line = "abc  , def  ,ghi ,   jkl"
    // 前后带有任意数量空格的逗号
    val separator = Regex("""\s*,\s*""")
    val fields = separator.split(line)
    fields.forEachIndexed { i, field -> println("fields[$i]=[$field]") }
    // 多个可能的分隔符:; 或 | 或一串空格
    val words = "one;two|three   four".split(Regex("""[;|]|\s+"""))
    println("words=$words")
    // 注意:参数为 String 时,split 按文本而不是按模式拆分
    println("\"1.5.2\".split(\".\") : ${"1.5.2".split(".")}")
    // 保留末尾的空字段;limit 设置字段的最大数量
    println("\"a,b,,\".split(\",\") : ${"a,b,,".split(",")}")
    println("separator.split(line, 2) : ${separator.split(line, 2)}")
    // splitToSequence:以序列形式返回字段
    println("splitToSequence : ${separator.splitToSequence(line).map { it.uppercase() }.toList()}")
}

结果:

> gradlew -q run -Pmain=regex05.Regex05Kt
fields[0]=[abc]
fields[1]=[def]
fields[2]=[ghi]
fields[3]=[jkl]
words=[one, two, three, four]
"1.5.2".split(".") : [1, 5, 2]
"a,b,,".split(",") : [a, b, , ]
separator.split(line, 2) : [abc, def  ,ghi ,   jkl]
splitToSequence : [ABC, DEF, GHI, JKL]

说明:

  • 第 7 行:分隔符:前后带有任意数量空格的逗号。空格会连同分隔符一起被去除。模板一旦编译,就可以用来拆分任意多行而无需重新编译:这就是拆分文件中所有行的方法;
  • 第 9 行:[split] 的结果是一个列表,由 [forEachIndexed] 按索引遍历;
  • 第 11 行:一个可以有多种形式的分隔符:分号或竖线([[;|]]),或者([|])一串空格([\s+])。该模型以 [Regex] 对象的形式传给 [String] 的 [split] 函数;
  • 第 14 行:请注意,这与 Java 有一个重要区别。当 Kotlin 函数 [split] 接收到字符串([String])时,它被当作 字面分隔符而不是模板:["1.5.2".split(".")] 按句点字符拆分字符串并返回 [[1, 5, 2]]。在 Java 中,[split] 方法(属于 [String] )总是把参数解释为正则表达式,其中句点匹配任意字符:["1.5.2".split(".")] 返回一个空数组——这是个经典陷阱。在 Kotlin 中则不会出错:模板以 [Regex] 对象的形式传入,而字符串始终按字面理解;
  • 第 16 行:与 Java 的另一个区别:字符串末尾的空字段会被保留。字符串“a,b,,”产生四个字段,其中最后两个为空,而 Java 的 [split] 方法只返回两个。因此,格式错误的行的字段数量绝不会被扭曲:以多余分隔符结尾的行会多出一个字段;
  • 第 17 行:[limit] 参数限制字段的数量;此时最后一个字段包含字符串的其余部分;
  • 第 18 行:[splitToSequence] 以序列的形式返回字段,这里对它应用 [map] 操作,然后再将其转换为列表。字段只在需要时才被拆分,这对于只使用前几个字段的超长字符串很有用。它等价于 [splitAsStream] 方法(属于 [Pattern])。

5.8.6. 预编译模板、选项,以及耗时过长的搜索

与其他平台不同,Java 和 Kotlin 都没有在程序编译时生成正则表达式搜索代码的机制:模式始终由 [Regex] 构造函数在运行时解析。这种编译是有代价的;因此,最佳实践是将每个已知的模式 一次性并一劳永逸地提前编译,并将 [Regex] 对象存放在只读属性([val])中,放在顶层或 *[companion object] 内,就像程序 *[Regex06.kt] 所做的那样。尤其要避免在循环内部写 ["""\\d+""".toRegex()] :这样模板会在每次迭代时被重新编译。[Regex] 对象是不可变的,可以被多个线程同时使用:与 Java 的 [Matcher] 对象不同,它不保存搜索的状态,因为每次搜索都会产生自己的结果。

package regex06

import java.util.regex.Pattern
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
import kotlin.time.TimeSource
import kotlin.time.measureTimedValue

// 一次性编译的模式、选项、防止耗时过长的搜索

// 带命名分组的时间 hh:mm:ss
val TIME = Regex("""(?<h>\d\d):(?<m>\d\d):(?<s>\d\d)""")
// 是的,无论大小写
val YES = Regex("""^\s*yes\s*$""", RegexOption.IGNORE_CASE)
// 病态模式:一个重复的分组,后面跟着对该分组的反向引用
val CATASTROPHIC = Regex("""^(a+)+\1$""")

fun main() {
    // 1 - 模式只编译一次,存储在顶层属性中
    println("TIME.containsMatchIn(\"It is 18:05:49\") : ${TIME.containsMatchIn("It is 18:05:49")}")
    TIME.find("departure at 07:45:00")?.let { m ->
        val (h, mn, s) = listOf("h", "m", "s").map { name -> m.groups[name]?.value }
        println("hours=$h, minutes=$mn, seconds=$s")
    }

    // 2 - 选项:此处为 IGNORE_CASE,在编译模式时设置
    for (answer in listOf("yes", "YES", "Yes", "no", "yesss")) {
        print("$answer=${YES.matches(answer)} ")
    }
    println()
    // IGNORE_CASE 同样忽略带重音字母的大小写
    println("Regex(\"éclair\", IGNORE_CASE) on \"ÉCLAIR\" : "
            + Regex("éclair", RegexOption.IGNORE_CASE).matches("ÉCLAIR"))
    // MULTILINE:^ 和 $ 匹配每一行的开头和结尾;\w 只识别 [a-zA-Z0-9_]
    val text = "price: 10\ncafé: 3\ntotal: 30"
    display(Regex("""^(\w+): (\d+)$""", RegexOption.MULTILINE), text)
    // 模式开头的 (?U):\w 也识别带重音的字母
    display(Regex("""(?U)^(\w+): (\d+)$""", RegexOption.MULTILINE), text)
    // java.util.regex 中 RegexOption 所缺少的选项:我们编译一个 Pattern 并进行转换
    val unicode = Pattern.compile("""^(\w+): (\d+)$""", Pattern.MULTILINE or Pattern.UNICODE_CHARACTER_CLASS)
    display(unicode.toRegex(), text)
    // 选项也可以写在模式中:(?i) 表示 IGNORE_CASE,(?m) 表示 MULTILINE
    println("(?i)yes on \"YES\" : ${"YES".matches(Regex("(?i)yes"))}")

    // 3 - 具有灾难性回溯的模式,先不限时,再限时
    for (n in listOf(10, 15, 20)) {
        val string = "a".repeat(n) + "!"
        val (found, duration) = measureTimedValue { CATASTROPHIC.containsMatchIn(string) }
        println("$n a : $found in ${duration.inWholeMilliseconds} ms")
    }
    val string = "a".repeat(30) + "!"
    try {
        val deadline = TimeSource.Monotonic.markNow() + 100.milliseconds
        println(CATASTROPHIC.containsMatchIn(TimeLimitedString(string, deadline)))
    } catch (e: TimeoutExceededException) {
        println("30 a : ${e.javaClass.simpleName} : search abandoned after 100 ms")
    }
    // Java 引擎能识别不带反向引用的模式 (a+)+ 并立即给出答案
    val (found, duration) = measureTimedValue { Regex("""^(a+)+$""").containsMatchIn(string) }
    println("^(a+)+$ on 30 a : $found, answer in less than one second : ${duration < 1.seconds}")
}

// 显示在文本中找到的 name=value 对
fun display(pattern: Regex, text: String) {
    for ((name, value) in pattern.findAll(text).map { it.destructured }) {
        print("[$name=$value] ")
    }
    println()
}

// 超过截止时间后拒绝被读取的字符串
class TimeLimitedString(
    private val text: CharSequence,
    private val deadline: TimeSource.Monotonic.ValueTimeMark
) : CharSequence by text {

    override fun get(index: Int): Char {
        if (deadline.hasPassedNow()) throw TimeoutExceededException()
        return text[index]
    }

    override fun subSequence(startIndex: Int, endIndex: Int): CharSequence =
        TimeLimitedString(text.subSequence(startIndex, endIndex), deadline)

    override fun toString() = text.toString()
}

// 超过截止时间时抛出的异常
class TimeoutExceededException : RuntimeException()

结果:

> gradlew -q run -Pmain=regex06.Regex06Kt
TIME.containsMatchIn("It is 18:05:49") : true
hours=07, minutes=45, seconds=00
yes=true YES=true Yes=true no=false yesss=false
Regex("éclair", IGNORE_CASE) on "ÉCLAIR" : true
[price=10] [total=30]
[price=10] [café=3] [total=30]
[price=10] [café=3] [total=30]
(?i)yes on "YES" : true
10 a : false in 1 ms
15 a : false in 6 ms
20 a : false in 238 ms
30 a : TimeoutExceededException : search abandoned after 100 ms
^(a+)+$ on 30 a : false, answer in less than one second : true

说明:

  • 第 12–16 行:程序的模板只编译一次,并存放在顶层属性中,按照常量的惯例使用大写命名。它们不能被声明为 [const]:只有编译时已知的基本类型值和字符串才能这样声明;[Regex] 对象是在运行时、首次使用该文件时创建的;
  • 第 20–23 行:这些属性的用法与前面程序中的 [Regex] 对象相同。函数 [let] 通过运算符 [?.] 调用,只有在 [find] 找到匹配时才执行它的代码块;第 22 行用一条语句取出三个命名分组,先使用 [map] 投影,再进行解构;
  • 第 14 行:[Regex] 构造函数的第二个参数是来自 [RegexOption] 枚举的选项。[IGNORE_CASE] 表示不区分大小写:“YES”和“Yes”都与该模式匹配(结果的第 3 行)。多个选项以集合的形式指定:[Regex(pattern, setOf(RegexOption.MULTILINE, RegexOption.IGNORE_CASE))],而 Java 使用 [|] 运算符组合整数;
  • 第 31–33 行:在 JVM 上,Kotlin 总是会把 Java 的 [UNICODE_CASE] 选项添加到 [IGNORE_CASE] 选项上;带重音字母的大小写也会被忽略,“ÉCLAIR”与“éclair”匹配(结果的第 4 行)。在 Java 中,单独使用 [CASE_INSENSITIVE] 则做不到这一点;
  • 第 35–36 行:[MULTILINE] 使 [^] 和 [$] 匹配字符串中每一行的开头和结尾,而不只是字符串本身的开头和结尾。然而,在默认选项下,[\w] 只能识别不带重音的字母:行“café: 3”无法被识别(结果的第 5 行);
  • 第 38 行:[RegexOption] 枚举不包含 Java 的 [UNICODE_CHARACTER_CLASS] 选项,该选项使 [\w]、[\d]、[\s] 和 [\b] 具有其 Unicode 含义。要实现这一点,可以在模板开头写上 [(?U)] :这样带重音的字母就会被视为单词字符(结果的第 6 行)。所有法语文本都应当这样处理;
  • 第 40–41 行:另一种解决办法是用 Java 类 [Pattern] 来编译模板,它提供所有可用的选项(这里用运算符 [or] 组合,它是 Kotlin 的按位“或”运算符),然后用扩展函数 [Pattern] 对象转换为 [Regex] ——即 [toRegex] (结果的第 7 行)。[RegexOption] 的其他选项有 [DOT_MATCHES_ALL] ([.] 也匹配换行符)、[COMMENTS] (模板中的空格被忽略,因此可以在原始字符串中跨多行并带注释书写)、[LITERAL](模板是纯文本;另见 [Regex.escape] 和 [Regex.fromLiteral])、[UNIX_LINES],以及 [CANON_EQ];
  • 第 43 行:选项也可以写在模板的开头:[(?i)] 对应 [IGNORE_CASE],[(?m)] 对应 [MULTILINE],[(?s)] 对应 [DOT_MATCHES_ALL],[(?U)]……;
  • 第 64–66 行:函数 [display] 遍历各匹配项的 [destructured] 值序列,并直接在 [for] 循环中解析每一项:[(name, value)] 是第 1 组和第 2 组。

程序的其余部分涉及一个安全问题。有些模式是病态的:当应用于某些字符串时,它们会迫使正则表达式引擎在得出结论之前尝试数量巨大的方式来把字符串与模式匹配。Java 引擎(Kotlin 在 JVM 上使用的就是它)采用一种称为“回溯”的机制:当一次尝试失败时,它会回到最近一次所做的选择并尝试另一种选择。第 16 行的 [^(a+)+\1$] 模式就是一个例子:当它应用于以另一个字符结尾的一串“a”时,它会尝试把这些“a”分配给分组的各次重复及其反向引用 [\1] 的所有可能方式,然后才断定失败,而且每多一个“a”,尝试次数就成倍增加。这称为灾难性回溯。当它应用于用户输入的字符串时,这样的模式就构成一个安全漏洞(称为 ReDoS,即“正则表达式拒绝服务”):只需几个请求就足以使服务器陷入停顿。

  • 第 46–49 行:对 10 个、15 个和 20 个 a 测量搜索耗时。*[measureTimedValue] 函数(来自 *[kotlin.time] )执行接收到的代码块,并同时返回其值和耗时,即一个 [Duration] 对象,二者封装在一个被解包的 [TimedValue] 对象中。耗时增长得非常快(结果的第 9–11 行;耗时因每次执行和每台机器而异)。由于每增加一个 a,执行时间大约翻一倍,因此对于 30 个 a,搜索将需要几分钟;
  • 第 51–56 行:[Regex] 类和 [Pattern] 类都没有超时选项。这里采用一种标准技术:在 [TimeLimitedString] 对象(第 72–85 行)中执行搜索,该对象实现了 [CharSequence] 接口,这是 [Regex] 的各函数所接受的接口。正则表达式引擎通过 Java 接口 [charAt] 的 [CharSequence] 方法逐个字符地读取字符串,该方法对应 Kotlin 中的 [get] 运算符:正是它检查时间,并在截止时间(对象创建时记录)已过时抛出 [TimeoutExceededException] 异常(第 89 行)。搜索在 100 毫秒后被放弃;
  • 第 72–75 行:类 *[TimeLimitedString] 有两个属性,即文本和截止时间,后者是来自 *[kotlin.time] 单调时钟的时间戳([ValueTimeMark]),其函数 [hasPassedNow] 指示该时间是否已被超过。子句 [CharSequence by text] 是一种 委托:该类通过把所有未重写的成员(这里是 [CharSequence] 接口的 [length] 属性)委托给 [text] 对象来实现该接口。编译器会生成转发调用的函数;在 Java 中,这些必须手工编写。唯一被重新定义的成员是监控时间的 [get] 运算符,以及返回受同一截止时间约束的 [subSequence] 函数,它返回一个 [TimeLimitedString] 。函数 [toString] 是 [Any] 的成员但不是该接口的成员,因此不被委托:它同样被重写;
  • 第 89 行:[TimeoutExceededException] 异常派生自 [RuntimeException]。由于 Kotlin 没有受检异常,任何异常都可以由 [get] 抛出;派生自 [RuntimeException] 仍是标准做法,调用该类的 Java 代码会把它当作非受检异常。Java 异常中常见的 [serialVersionUID] 字段在这里是不必要的:Kotlin 编译器不会对其缺失给出警告;
  • 第 59–60 行:Java 运行时能够识别并高效处理嵌套重复的简单情形:在其他运行时中有问题的 [^(a+)+$] 模式在这里会立即得到结果。正是 反向引用 [\1] 阻止了第 16 行模式中的这种优化。类型为 [Duration] 的时长使用运算符 [<] 进行比较。

需要注意的是,必须提防包含嵌套重复的模式([(a+)+],[(\w+\s?)*]……),并且只要模式或被搜索的字符串来自程序外部,就应限制搜索的时长。Java 引擎的占有型量词([a++],[a*+])可以阻止对其所重复元素内部的回溯,只要完全理解其含义,也可以用来编写安全的模式。

5.9. 示例应用程序 - V3

我们将重新回到第 3 章(版本 1)和第 4 章(版本 2)中讨论的应用程序。请记住这只是一个练习:所用的税率表是 2004 年的税率表(基于 2003 年的收入),自原始课程以来一直没有改变。

5.9.1. 文件中的数据

在版本 2 中,税款计算是在抽象类 [AbstractTax]中完成的,我们在这里将其复用到项目的包 [taxv3] 中:与 Java 中一样,版本 3 是自包含的,不依赖第 4 章的类。税率档由一个抽象属性(只读列表)提供,除法按 16 位有效数字执行,这已绰绰有余:

package taxv3

import java.math.BigDecimal
import java.math.MathContext

abstract class AbstractTax : ITax {

    // 计算所需的税率档来自外部来源
    // 只有派生类知道
    protected abstract val taxBrackets: List<TaxBracket>

    // 税款计算
    override fun calculate(married: Boolean, nbChildren: Int, salary: Int): Int {
        // 份数的计算
        var shares = nbChildren.toBigDecimal().divide(BigDecimal.TWO)
        shares += if (married) BigDecimal.TWO else BigDecimal.ONE
        if (nbChildren >= 3) {
            shares += "0.5".toBigDecimal()
        }
        // 应税收入和家庭系数的计算
        val income = "0.72".toBigDecimal() * salary.toBigDecimal()
        val quotient = income.divide(shares, MathContext.DECIMAL64)
        // 查找税率档:如果没有符合的上限,则使用最后一档
        val bracket = taxBrackets.dropLast(1).firstOrNull { quotient <= it.limit } ?: taxBrackets.last()
        // 税款计算
        return (income * bracket.coeffR - shares * bracket.coeffN).toInt()
    }
}

函数 [calculate] 使用抽象属性 [taxBrackets] (第 10 行)返回的税率档。类 [AbstractTax] 并不知道这些税率档来自何处:由派生类通过重新定义该属性来提供它们。在版本 2 中,派生类 [HardwiredTax] 把它们直接硬编码到其 代码中。计算使用精确的十进制数 [java.math.BigDecimal] (第 3 章)进行,Kotlin 标准库使其使用起来很方便:

  • [toBigDecimal] 扩展函数(属于 [Int] 和 [String] )取代了 [BigDecimal.valueOf(...)] 和 [new BigDecimal(...)](["0.72".toBigDecimal()],第 21 行);
  • 运算符 [+]、[-]、[*]和 [+=] 已为 [BigDecimal] 定义(它们是 [plus]、[minus]、[times] 的扩展函数,用 [operator] 声明,见第 4 章):第 26 行读起来就像它所计算的公式;
  • [BigDecimal] 实现了 [Comparable<BigDecimal>]:比较运算符可以直接使用([quotient <= it.limit],第 24 行),并调用 [compareTo];
  • 不过,要小心 运算符 [/]:它调用 [divide(other, RoundingMode.HALF_EVEN)],该方法保留被除数的小数位数。对于两个整数,结果会四舍五入到最接近的整数:[3.toBigDecimal() / 2.toBigDecimal()] 等于 2,而 [1.toBigDecimal() / 2.toBigDecimal()] 等于 0。因此该函数中的两个除法运算都使用 [divide] 方法实现:除以 2 的精确除法(第 15 行),如果结果不是有限小数就会抛出异常;以及 16 位有效数字的除法([MathContext.DECIMAL64],第 22 行);
  • 第 24 行:税率档的查找使用集合操作来编写:[dropLast(1)] 排除最后一个税率档,[firstOrNull] 返回家庭商数未超过其上限的第一个税率档,若没有则返回 [null] ,然后运算符 [?:] 选取最后一个税率档,即 [last()];
  • [toInt] 返回结果的整数部分([BigDecimal] 的 [intValue] 方法)。

税率档由数据类 [TaxBracket] 表示:

1
2
3
4
5
6
package taxv3

import java.math.BigDecimal

// 税率表的一档
data class TaxBracket(val limit: BigDecimal, val coeffR: BigDecimal, val coeffN: BigDecimal)

计算由 [ITax] 接口描述,这里用 KDoc 注释对其进行文档化——它是 Kotlin 中相当于 Javadoc 的机制(标签与 [@param] 和 [@return] 相同):

package taxv3

/**
 * The tax calculation.
 */
interface ITax {

    /**
     * Calculates the tax of a taxpayer.
     *
     * @param married true if the taxpayer is married
     * @param nbChildren number of children
     * @param salary annual salary in euros
     * @return the amount of the tax, in euros
     */
    fun calculate(married: Boolean, nbChildren: Int, salary: Int): Int
}

新版本把数据存放在文件中,这样无需重新编译程序就可以更改税率表。我们编写两个派生自 [AbstractTax] 的新类:

  • [FileTax] 从文本文件 [TaxData.txt] 中读取税率档;
  • [JsonTax] 从 JSON 文件 [TaxData.json] 中读取税率档。

文本文件 [TaxData.txt] 每行包含一个税率档,格式为 limit:coeffR:coeffN:

1
2
3
4
5
6
7
4962:0:0
8382:0.068:291.09
14753:0.191:1322.92
23888:0.283:2668.39
38868:0.374:4846.98
47932:0.426:6883.66
0:0.481:9505.54

文件中的数字使用小数点书写。数据文件不应依赖于读取它的机器所使用的语言:用小数逗号书写并按法语规则([NumberFormat.getInstance(Locale.FRANCE)])解释的文件,在英语环境的机器上会被拒绝,或者更糟,被错误解读。[String] 的 [toBigDecimal] 函数,与 [toDouble] 一样,无论机器使用何种语言,始终要求使用小数点。这也是 JSON 和大多数数据格式的约定。

文件 [TaxData.json] 包含相同的数据,形式为由对象组成的 JSON 数组:

1
2
3
4
5
6
7
8
9
[
  { "limit": 4962, "coeffR": 0, "coeffN": 0 },
  { "limit": 8382, "coeffR": 0.068, "coeffN": 291.09 },
  { "limit": 14753, "coeffR": 0.191, "coeffN": 1322.92 },
  { "limit": 23888, "coeffR": 0.283, "coeffN": 2668.39 },
  { "limit": 38868, "coeffR": 0.374, "coeffN": 4846.98 },
  { "limit": 47932, "coeffR": 0.426, "coeffN": 6883.66 },
  { "limit": 0, "coeffR": 0.481, "coeffN": 9505.54 }
]

5.9.2. 错误

处理这些文件时可能会失败,原因包括文件缺失、行格式错误、数字不正确等。我们创建一个专用的异常类来报告这些错误,即 [TaxException]。它还将用于其他数据源(这里的 JSON 文件,以及后面的数据库)。它携带一个错误代码:

1
2
3
4
5
6
7
package taxv3

// 读取税率档的类所抛出的异常
// code:错误码(ErrorCode 值的组合)
// cause:导致该错误的异常(如果有)
class TaxException(message: String, val code: Int, cause: Throwable? = null) :
    RuntimeException(message, cause)

说明:

  • 第 6 行:整个类都包含在它的头部中。主构造函数接收消息、代码和错误原因;代码成为只读属性([val]),而消息和原因只是普通参数,它们被传给父类 *[RuntimeException]* 的构造函数,从而可通过属性 *[message]* 和 *[cause]* 获取;
  • 参数 [cause],即引起该错误的异常,有一个默认值 [null]:一个构造函数取代了 Java 版本中的两个构造函数;[TaxException(message, code)] 和 [TaxException(message, code, e)] 都是通过同一个构造函数定义的。应用程序的后续版本将采用这个携带整数代码的异常,其构造函数略有不同(第 6 章);
  • 第 7 行:该类继承 [RuntimeException]。由于 Kotlin 没有受检异常(第 3 章),父类的选择在这里不会带来任何限制;不过,对于使用 该类的 Java 代码,[TaxException] 将是一个非受检异常,这正是我们想要的行为,稍后会看到。Java 版本中的 [serialVersionUID] 字段是不必要的:Kotlin 编译器不会对此发出警告。

可能的错误代码由一个枚举定义:

package taxv3

import java.util.EnumSet

// 错误码:2 的幂,可以组合
enum class ErrorCode(val value: Int) {
    ACCESS(1),      // 无法读取文件
    LINE(2),        // 某一行没有三个字段
    FIELD1(4),      // 字段 1(limit)不正确
    FIELD2(8),      // 字段 2(coeffR)不正确
    FIELD3(16),     // 字段 3(coeffN)不正确
    JSON(32);       // JSON 文档不正确

    companion object {
        // 码组合中包含的各个码
        fun decode(code: Int): EnumSet<ErrorCode> =
            entries.filterTo(EnumSet.noneOf(ErrorCode::class.java)) { code and it.value != 0 }
    }
}

说明:

  • 第 7–12 行:可能的错误代码:
    • [ACCESS]:访问数据文件时出错;
    • [LINE]:某一行缺少预期的三个字段,或文件中不包含任何税率档;
    • [FIELD1], [FIELD2], [FIELD3]:某一行中的字段 1、2 或 3 不正确;
    • [JSON]:JSON 文档不正确;
  • 第 6 行:Kotlin 枚举([enum class],第 3 章)可以拥有属性(在其主构造函数中声明)和函数。每个常量都用括号中的整数值来构造;当常量列表后面还有其他成员时,列表以分号结束;
  • 第 14–17 行:有些错误可能同时出现;一行中的三个字段可能全部不正确。因此,代码值是 2 的幂:每个值对应整数的一个二进制位。字段 2 和字段 3 出错将产生代码 [8 or 16] = 24([or] 是 Kotlin 中的按位“或”运算符)。函数 [decode] 放在枚举的 [companion object] 中,以便通过 [ErrorCode.decode(code)] 调用,它执行相反的操作:使用 [and] 运算符测试每一位,把整数转换为所含代码的集合。属性 [entries] (Kotlin 1.9)是枚举中常量的列表,而 [filterTo] 把满足条件的常量放入传给它的集合中,这里是一个空的 [java.util.EnumSet]。这个专门用于枚举常量的集合在内部把它们存储为整数的各个二进制位;其 [toString] 方法以“[FIELD2, FIELD3]”的形式显示一个组合。我们同样可以返回 Kotlin 的 [Set<ErrorCode>] ([entries.filter { ... }.toSet()]),它的显示方式是一样的。

5.9.3. FileTax 类

[FileTax] 类提供从文本文件中读取的税率档:

package taxv3

import java.io.IOException
import kotlin.io.path.Path
import kotlin.io.path.useLines

// 从由 limit:coeffR:coeffN 行组成的文本文件中读取的税率档
class FileTax(fileName: String) : AbstractTax() {

    companion object {
        // 字段分隔符:: 字符,两侧可带可选的空格
        private val SEPARATOR = Regex("""\s*:\s*""")
        // 正数或零:数字,后面可选地跟一个点和数字
        private val NUMBER = Regex("""\d+(\.\d+)?""")
        // 一行中三个字段的错误码
        private val FIELD_CODES = listOf(ErrorCode.FIELD1, ErrorCode.FIELD2, ErrorCode.FIELD3)
    }

    // 从文件中读取的税率档(实现父类的抽象属性)
    override val taxBrackets: List<TaxBracket>

    init {
        // 用于错误消息的文件名,不含路径
        val path = Path(fileName)
        val name = path.fileName.toString()
        val brackets = try {
            // 逐行读取文件;useLines 在任何情况下都会关闭它
            path.useLines { lines ->
                lines.mapIndexed { index, line -> index + 1 to line.trim() }
                    // 空行被忽略
                    .filter { (_, line) -> line.isNotEmpty() }
                    .map { (lineNumber, line) -> bracket(lineNumber, line) }
                    .toList()
            }
        } catch (e: IOException) {
            // 文件访问错误:它被包装在 TaxException 中
            throw TaxException("Error while reading the file $name", ErrorCode.ACCESS.value, e)
        }
        // 至少需要一档
        if (brackets.isEmpty()) {
            throw TaxException("The file $name does not contain any bracket", ErrorCode.LINE.value)
        }
        taxBrackets = brackets
    }

    // 由文件中一行描述的税率档
    private fun bracket(lineNumber: Int, line: String): TaxBracket {
        // 该行必须有三个字段
        val fields = line.split(SEPARATOR)
        if (fields.size != 3) {
            throw TaxException("Line no. $lineNumber is incorrect ($line)", ErrorCode.LINE.value)
        }
        // 三个正的或为零的十进制数,用小数点书写
        val code = FIELD_CODES.zip(fields)
            .filter { (_, field) -> !NUMBER.matches(field) }
            .fold(0) { code, (errorCode, _) -> code or errorCode.value }
        if (code != 0) {
            throw TaxException("Line no. $lineNumber is incorrect ($line)", code)
        }
        // 新的税率档
        val (limit, coeffR, coeffN) = fields.map { it.toBigDecimal() }
        return TaxBracket(limit, coeffR, coeffN)
    }
}

说明:

  • 第 8 行:[FileTax] 类派生自 [AbstractTax] 类,就像版本 2 中的 [HardwiredTax] 类一样。其主构造函数接收包含数据的文本文件的名称。参数 [fileName] 声明时没有使用 [val],因此它不是属性:它只在对象构造期间使用;
  • 第 10–16 行:两个正则表达式,一次性编译好并存放在类的 [companion object] 中,这相当于 Java 的 [private static final] 常量:一个是 limit:coeffR:coeffN 行的字段分隔符(字符 [:],前后带有任意数量的空格),另一个是正数或零,由数字组成,后面可以跟一个句点和更多数字。原始字符串避免了 [\] 的重复书写。列表 [FIELD_CODES] 为每个字段关联一个错误代码;
  • 第 20 行:重新定义 [AbstractTax] 抽象属性的属性。它在声明时没有初始值:它将在 [init] 块中初始化,编译器要求在该块中为它赋值,而且只能赋值一次;
  • 第 22–43 行:[init] 块在对象构造时执行,类似于 Java 构造函数的函数体。它的作用是填充列表 [taxBrackets];
  • 第 25 行:不含路径的文件名,用于错误消息。构造函数确实可能接收完整路径,而这不需要显示给用户。[Path] 函数(来自 [kotlin.io.path] )创建对象 [java.nio.file.Path];[fileName] 是被当作属性处理的 Java 方法 [getFileName];
  • 第 26–33 行:读取文件。[useLines] 扩展函数(属于 [Path] )打开文件(按 UTF-8),把文件各行的序列传给 lambda,然后无论 lambda 以何种方式退出(正常退出还是通过异常),都会关闭文件:这相当于使用 Java 资源的 [try] 。由于读取文本文件是一个顺序过程,直到末尾才知道行数;序列很适合用于字符串处理:
    • [mapIndexed] 把每一行(已由 [trim] 去除空格)与其行号关联起来(索引从 0 开始,行号从 1 开始),形成一个 [number to line] 对;
    • [filter] 去除空行;这个对被解包到 lambda 的参数中,即 [(_, line)],不需要的行号用 [_] 代替;
    • [map] 使用函数 [bracket] 把每一行转换为一个税率档;
    • [toList] 遍历序列并把税率档存放到列表中。这个调用必须在 lambda 内部进行:序列是惰性求值的,如果由 [useLines] 原样返回序列,则它会在文件关闭之后才被遍历;
  • [try] 块是一个表达式:它的值是税率档列表,存放在变量 [brackets] 中;
  • 第 35–37 行:文件访问错误([IOException] 及其变体,例如文件缺失时的 [NoSuchFileException] 、权限不足时的 [AccessDeniedException] ,或文件不是 UTF-8 编码时的 [MalformedInputException] )被封装为代码为 [TaxException] 的 [ACCESS] 异常,原始异常成为其原因。由 [TaxException] 函数 [bracket] 抛出的异常不是 [IOException] 异常:它们不会被这个 [catch] 子句拦截,而是原样退出构造函数,不过文件仍会由 [useLines] 关闭;
  • 第 40–43 行:空文件会被拒绝;否则,该列表成为 [taxBrackets] 属性的值,这正是 [init] 块的目的;
  • 第 49–51 行:函数 [bracket] 解析一行。使用正则表达式把该行拆分为字段;如果不是三个字段,就抛出代码为 [TaxException] 的 [LINE] 异常。请注意,在 Kotlin 中 [split] 会保留末尾的空字段:以多余分隔符结尾的行“4962:0:0: ”有四个字段,因此被拒绝,而会去除末尾空字段的 Java 方法 [split] 则会接受它;
  • 第 54–58 行:验证三个字段。函数 [zip] 以对的形式把每个错误代码与对应的字段关联起来;[filter] 保留与 [NUMBER] 模板不匹配的字段,[fold] 使用 [or] 运算符从 0 开始累积它们的代码。因此错误是被集中报告的。[matches] 函数要求整个字段与 [NUMBER] 模板匹配:不允许有符号、空格或逗号。因此负数会被拒绝,这样在检查数据的同时也完成了数据验证;
  • 第 61–62 行:这些已经验证过的字段通过 [toBigDecimal] 被转换为 [BigDecimal],无论机器使用何种语言都使用小数点;由三个数字组成的列表被解包以构造税率档。

把底层异常([IOException])封装在应用程序专用的异常([TaxException])中,使调用代码无论数据源是什么(文本文件、JSON 文件,以及本课程后面的数据库),都只需处理单一类型的异常。在 Java 中,这也是 [TaxException] 为非受检异常的原因:受检异常需要由它所经过的每个方法声明,这会使调用代码与数据源的细节绑定在一起。Kotlin 没有受检异常,因此不强制这种选择,但封装仍然同样重要:调用代码不需要了解 API 中与文件相关的异常。

5.9.4. JsonTax 类

[JsonTax] 类返回从 JSON 文件中读取的税率档。它使用 Jackson 3 库,该库已在项目的 [build.gradle.kts] 文件中声明:

package taxv3

import java.io.IOException
import java.math.BigDecimal
import kotlin.io.path.Path
import kotlin.io.path.readText
import tools.jackson.core.JacksonException
import tools.jackson.databind.json.JsonMapper

// 从 JSON 文件中读取的税率档
class JsonTax(fileName: String) : AbstractTax() {

    companion object {
        // JsonMapper 可重用,且可被多个线程使用:只创建一个
        private val MAPPER = JsonMapper.builder().build()

        // 负值不正确
        private fun negative(value: BigDecimal) = value.signum() < 0
    }

    // 从文件中读取的税率档
    override val taxBrackets: List<TaxBracket>

    init {
        // 用于错误消息的文件名,不含路径
        val path = Path(fileName)
        val name = path.fileName.toString()
        // 读取文件
        val json = try {
            path.readText()
        } catch (e: IOException) {
            throw TaxException("Error while reading the file $name", ErrorCode.ACCESS.value, e)
        }
        // 反序列化税率档数组;null JSON 文档得到 null 值
        val brackets: Array<TaxBracket>? = try {
            MAPPER.readValue(json, Array<TaxBracket>::class.java)
        } catch (e: JacksonException) {
            val position = "line ${e.location?.lineNr}, column ${e.location?.columnNr}"
            throw TaxException("The file $name is incorrect: ${e.originalMessage} ($position)",
                ErrorCode.JSON.value, e)
        }
        // 至少需要一档,且不含负值
        if (brackets.isNullOrEmpty()) {
            throw TaxException("The file $name does not contain any bracket", ErrorCode.JSON.value)
        }
        if (brackets.any { negative(it.limit) || negative(it.coeffR) || negative(it.coeffN) }) {
            throw TaxException("The file $name contains a negative value", ErrorCode.JSON.value)
        }
        taxBrackets = brackets.toList()
    }
}

说明:

  • 第 15 行:存放在 [JsonMapper] 的 [companion object] 中的唯一一个映射器被用于所有 [JsonTax] 对象。JSON 属性 [limit]、[coeffR] 和 [coeffN] 以数据类 [TaxBracket] 的构造函数的参数命名:无需任何注解,因为编译器会在编译后的代码中保留这些名称(文件 [javaParameters = true] 中的选项 [build.gradle.kts]),Jackson 3 能够读取它们;
  • 第 29–32 行:使用 [readText] 扩展函数(来自 [Path])读取文件;访问错误的处理方式与 [FileTax] 中相同;
  • 第 36 行:一条指令就把 JSON 文本转换为税率档数组;[Array<TaxBracket>::class.java] 是该数组的 Java 类,等价于 [TaxBracket[].class]。Jackson 通过调用数据类的构造函数来构造每个税率档,并把 JSON 数字转换为 [BigDecimal] 而不损失任何精度。由于 Java 方法 [readValue] 可能返回 [null] (对于 JSON 文档 [null]),结果被存放在类型为 [Array<TaxBracket>?] 的变量中:如果没有这个声明,Kotlin 会赋予它一个“平台”类型,并且不知道该类型是否接受 [null];
  • 第 37–40 行:无效的文档会引发 [JacksonException],并被封装在代码为 [TaxException] 的 [JSON] 异常中。消息指出了错误的位置,该位置由 [location] 属性([getLocation] 方法)给出;[?.] 运算符可防范位置未知的情况;
  • 第 43–49 行:反序列化检查的是文档格式,而不是数据的有效性:还需要验证至少有一个税率档(文档 [null] 或 [[]] 都是有效的 JSON),这由 [isNullOrEmpty] 通过一次测试完成;还要验证没有任何负值,这由直接应用于数组的 [any] 操作完成。第一次测试之后,编译器就知道 [brackets] 不是 [null]。最后由 [toList] 把数组转换为列表;
  • 第 18 行:测试某个值的函数,写成表达式的形式。

Java 版本还会检查是否没有缺失的值:JSON 对象缺少某个属性时,会把值 [null] 赋给记录的相应组件。在 Kotlin 中,这个检查是不必要的:[TaxBracket] 的属性类型是 *[BigDecimal]*,而不是 ***[BigDecimal?]。Kotlin 编译器会在类的构造函数开头为每个非空参数添加一个检查:如果 Jackson 传给它 [null],构造函数就会抛出异常,Jackson 将其作为 [JacksonException] 传播。因此,关于 *[null] 的安全性也延伸到由 Java 库创建的对象:不完整的税率档不可能存在。我们稍后会验证这一点。

比较这两个类很有启发性:有了结构化的数据格式和理解它的库,解析文件几乎不需要任何代码。请注意,还有一个专用于 Kotlin 的 Jackson 模块 [jackson-module-kotlin],它会考虑参数默认值和可空类型,并提供诸如 [mapper.readValue<Array<TaxBracket>>(json)] 之类的函数,其中类型由泛型参数指定([reified],第 4 章)。JetBrains 还提供自己的序列化库 [kotlinx.serialization],它使用编译器插件在编译时生成序列化代码。对于像 [TaxBracket] 这样简单的数据类,单独使用 Jackson 就足够了。

5.9.5. 主程序

与属于独立 Maven 项目的 Java 版本不同,版本 3 是本章 Gradle 项目中的一个多文件程序,组织在它自己的包 [taxv3] 中。项目的相关部分具有如下目录结构:

05-classes-kotlin/
  build.gradle.kts
  TaxData.json
  TaxData.txt
  TaxDataIncomplete.json
  TaxDataInvalid.json
  TaxDataInvalid.txt
  src/main/kotlin/taxv3/
    AbstractTax.kt
    ErrorCode.kt
    FileTax.kt
    ITax.kt
    JsonTax.kt
    Main.kt
    TaxBracket.kt
    TaxException.kt

数据文件放在项目根目录中,紧挨着 [build.gradle.kts] 文件:这是使用 [gradlew run] 命令,或在 IntelliJ 或 IDEA 中点击绿色三角形运行程序时的当前目录。Jackson 库在项目的 [build.gradle.kts] 文件中声明,本章的所有程序都使用该文件:

1
2
3
4
5
dependencies {
    // 项目程序所使用的库
    // JSON:Jackson 3
    implementation("tools.jackson.core:jackson-databind:3.1.5")
}

主程序是文件 [Main.kt];它的 JVM 类是 [taxv3.MainKt]:

package taxv3

import kotlin.system.exitProcess

// 税款计算,版本 3:税率档从文件中读取
// 语法:gradlew -q run -Pmain=taxv3.MainKt [--args="file"]
// file:默认为 TaxData.txt,或一个 .json 文件

private val SYNTAX = """
    syntax: Married NbChildren Salary
    Married: y for married, n for not married
    NbChildren: number of children
    Salary: annual salary in euros""".trimIndent()

// 输入循环的提示
private const val PROMPT =
    "Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: "

// 所输入参数的分隔符:一串空格
private val SPACES = Regex("""\s+""")

fun main(args: Array<String>) {
    // 数据文件在当前文件夹中查找
    val fileName = args.firstOrNull() ?: "TaxData.txt"
    println("Tax brackets read from [$fileName]")

    // 创建 ITax 对象;所用的类取决于文件扩展名
    val tax: ITax = try {
        when (fileName.substringAfterLast('.').lowercase()) {
            "json" -> JsonTax(fileName)
            else -> FileTax(fileName)
        }
    } catch (e: TaxException) {
        // 显示错误;错误码显示为一组 ErrorCode
        val origin = e.cause?.let { ", original exception: ${it.javaClass.simpleName}" } ?: ""
        println("The following error occurred: [Code=${ErrorCode.decode(e.code)}, "
                + "Message=${e.message}$origin]")
        // 停止程序
        exitProcess(1)
    }

    // 输入循环
    while (true) {
        // 我们询问税款计算的参数
        print(PROMPT)
        val parameters = readlnOrNull()?.trim() ?: ""
        // 有事要做吗?
        if (parameters.isEmpty()) break
        // 检查所输入行的字段数
        val fields = parameters.split(SPACES)
        if (fields.size != 3) {
            println(SYNTAX)
            continue
        }
        // 检查参数的有效性
        // married
        val married = fields[0].lowercase()
        if (married != "y" && married != "n") {
            println("$SYNTAX\nIncorrect married argument: type y or n")
            continue
        }
        // nbChildren:正整数或零
        val nbChildren = fields[1].toIntOrNull()?.takeIf { it >= 0 }
        if (nbChildren == null) {
            println("$SYNTAX\nIncorrect NbChildren argument: type a positive or zero integer")
            continue
        }
        // salary:正整数或零
        val salary = fields[2].toIntOrNull()?.takeIf { it >= 0 }
        if (salary == null) {
            println("$SYNTAX\nIncorrect salary argument: type a positive or zero integer")
            continue
        }
        // 参数正确:我们计算税款
        println("Tax=${tax.calculate(married == "y", nbChildren, salary)} euros")
    }
}

说明:

  • 第 9–13 行:帮助文本,位于一个原始字符串中,[trimIndent] 会去除其中的公共缩进和第一个空行。由于函数调用的结果不是编译时常量,该属性不能声明为 [const]:[const val SYNTAX = """...""".trimIndent()] 会被编译器拒绝([const 'val' initializer must be a constant value])。而输入循环的提示符是字符串字面量,因此是常量 [const val] (第 16 行);
  • 第 20 行:输入参数的分隔符,一次性编译好;
  • 第 24 行:数据文件的名称作为实参传入;默认值为 [TaxData.txt]。[firstOrNull] 返回第一个实参,如果没有则返回 [null] ,这时通过运算符 [?:] 用默认值替换它。使用 Gradle 时,程序的实参通过 [--args] 选项传递:[gradlew -q run -Pmain=taxv3.MainKt --args="TaxData.json"];
  • 第 28–31 行:[when] 表达式(第 3 章)根据文件扩展名选择要实例化的类,扩展名通过 [substringAfterLast] 从文件名中提取。两个分支返回类型不同的对象,即 [JsonTax] 和 [FileTax],二者都属于 [ITax] 类型,这正是变量 [tax] 的声明类型。程序的其余部分只认识 [ITax] 接口,并不知道数据来自何处;
  • 第 33–39 行:创建对象时可能抛出 [TaxException],它会在程序终止前被显示出来。代码被解码为 [ErrorCode] 集合,以便以纯文本显示;原始异常(如果有)用其类型来表示:[e.cause?.let { ... } ?: ""] 在原因存在时构造文本,否则返回空字符串。标准库中的 [exitProcess] 函数终止程序;它的类型是 [Nothing]:编译器知道它永远不会返回控制权,因此知道变量 [tax] 在 [try] 块之后已被初始化。Java 版本中跟在 [return] 之后、为 Java 编译器所要求的多余指令 [System.exit] 已被删除;
  • 第 43–75 行:对话循环与版本 2 相同。由 [readlnOrNull] 读取的行在流结束时为 [null] ,随后它会被空字符串替换(第 46 行)。子女数量和工资通过 [toIntOrNull] 转换,如果字符串不是整数,它返回 [null] ,而 [takeIf { it >= 0 }] 对负整数同样返回 [null] (第 63、69 行):对 [null] 的一次测试就能检测出这两种错误。该表达式被直接写出,没有使用版本 2 中的 [positiveInteger] 函数(也没有使用 Java 版本中在出错时返回 -1 的 [integer] 函数)。经过这次测试后,编译器知道 [nbChildren] 和 [salary] 的类型为 [Int]。

5.9.6. 运行结果

使用文件 [TaxData.txt](默认情况;从文件重定向的输入已被重新插入到提示符之后):

> gradlew -q run -Pmain=taxv3.MainKt
Tax brackets read from [TaxData.txt]
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: q s d
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Incorrect married argument: type y or n
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 d
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Incorrect salary argument: type a positive or zero integer
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop:

其值与之前的版本相同:已婚且有 2 个孩子的夫妇为 4,282 欧元,已婚且有 3 个孩子的夫妇为 2,959 欧元,年薪 60,000 欧元的无子女单身人士为 11,519 欧元。错误的输入会像版本 2 中那样被标记出来。

使用文件 [TaxData.json]:

1
2
3
4
5
6
7
8
9
> gradlew -q run -Pmain=taxv3.MainKt --args="TaxData.json"
Tax brackets read from [TaxData.json]
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop:

使用不存在的文件 [xx.txt]:

1
2
3
> gradlew -q run -Pmain=taxv3.MainKt --args="xx.txt"
Tax brackets read from [xx.txt]
The following error occurred: [Code=[ACCESS], Message=Error while reading the file xx.txt, original exception: NoSuchFileException]

使用下面的文件 [TaxDataInvalid.txt],其中第三行使用了小数逗号:

1
2
3
4
4962:0:0
8382:0.068:291.09
14753:0,191:1322,92
23888:0.283:2668.39
1
2
3
> gradlew -q run -Pmain=taxv3.MainKt --args="TaxDataInvalid.txt"
Tax brackets read from [TaxDataInvalid.txt]
The following error occurred: [Code=[FIELD2, FIELD3], Message=Line no. 3 is incorrect (14753:0,191:1322,92)]

第 3 行的字段 2 和 3 被拒绝:错误代码是组合 [[FIELD2, FIELD3]]。字段 1(14753)没有小数部分,因此是正确的。

使用下面的文件 [TaxDataInvalid.json],其中一个系数被写成字符串:

1
2
3
4
[
  { "limit": 4962, "coeffR": 0, "coeffN": 0 },
  { "limit": 8382, "coeffR": "0,068", "coeffN": 291.09 }
]
1
2
3
> gradlew -q run -Pmain=taxv3.MainKt --args="TaxDataInvalid.json"
Tax brackets read from [TaxDataInvalid.json]
The following error occurred: [Code=[JSON], Message=The file TaxDataInvalid.json is incorrect: Cannot deserialize value of type `java.math.BigDecimal` from String "0,068": not a valid representation (line 3, column 30), original exception: InvalidFormatException]

Jackson 的消息精确地指出了错误:字符串“0,068”无法转换为 [BigDecimal]。Jackson 在期望数字的地方接受包含有效数字的字符串(“0.068”);被拒绝的是小数逗号。错误位于文档的第 3 行(因为 Jackson 的行号从 1 开始)和第 30 列,即错误值的开头。

最后,使用下面的文件 [TaxDataIncomplete.json],其中第二个税率档缺少 [coeffR] 属性:

1
2
3
4
[
  { "limit": 4962, "coeffR": 0, "coeffN": 0 },
  { "limit": 8382, "coeffN": 291.09 }
]
1
2
3
> gradlew -q run -Pmain=taxv3.MainKt --args="TaxDataIncomplete.json"
Tax brackets read from [TaxDataIncomplete.json]
The following error occurred: [Code=[JSON], Message=The file TaxDataIncomplete.json is incorrect: Cannot construct instance of `taxv3.TaxBracket`, problem: Parameter specified as non-null is null: method taxv3.TaxBracket.<init>, parameter coeffR (line 3, column 37), original exception: ValueInstantiationException]

正是 Kotlin 编译器添加到 [TaxBracket] 数据类构造函数中的检查拒绝了参数 [null] 的值 [coeffR] (“Parameter specified as non-null is null”)。Jackson 把该错误报告为派生自 [ValueInstantiationException] 的 [JacksonException] 异常,位于不完整对象的末尾(第 3 行,第 37 列):这个不完整的税率档从未存在过,也没有为它编写任何测试。

5.10. 结论

本章介绍了几乎所有程序都会用到的 Kotlin 类和函数:

  • 不可变字符串 [String],它们用 [==] (调用 [equals])进行比较,还有它们众多的扩展函数、用于逐段构建字符串的 [buildString] 和 [StringBuilder] 、字符串模板、[format] 函数,以及原始字符串([trimIndent]、[trimMargin]);
  • 数组([Array]、[IntArray]……)及其函数;
  • Kotlin 集合——[List]、[Set]、[Map]——它们要么是只读的,要么是可变的([MutableList]、[MutableSet]、[MutableMap]),通过 [listOf]、[mutableListOf]、[mapOf]…… 创建,并基于 JDK 的集合,以及其他集合([ArrayDeque]、有序集合和字典等);
  • 集合上的函数式操作([filter]、[map]、[sortedBy]、[groupBy]、[associate]、[fold]、[partition]、[zip]……)和序列,包括它们的惰性版本,同时 Java Stream(API)仍然可以使用;
  • 文本文件([File]、[Path], 以及 [kotlin.io] 和 [kotlin.io.path] 的扩展:[readLines]、[useLines]、[writeText]……),默认使用 UTF-8,以及二进制文件([DataOutputStream]、[DataInputStream]、[RandomAccessFile]),以及使用 Jackson 和数据类的 JSON 序列化;
  • [Regex] 类中的正则表达式,写成原始字符串,一次性编译好,并在处理外部数据时受到保护,避免耗时过长的搜索。

特别值得注意的是 Kotlin 如何利用 Java 平台:Kotlin 标准库并不取代 JDK,而是通过扩展函数([readLines]、[toBigDecimal]、[toRegex]……)、运算符([BigDecimal])和只读接口来扩展它,同时 Java 类([Path]、[BigDecimal]、[LocalDate]、[Pattern]、Jackson 等)可以被直接使用。

该示例应用程序现在从文本文件或 JSON 文件读取数据。下一章将把它重新组织为层:读取数据、计算税款和用户交互将成为相互独立的组件。