结构体

struct Array<T>

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

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

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

init()

public const init()

功能：构造一个空数组。

init(Collection<T>)

public init(elements: Collection<T>)

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

参数：

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

init(Int64, (Int64) -> T)

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

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

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

参数：

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

异常：

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

init(Int64, T)

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

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

注意：

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

参数：

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

异常：

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

func clone()

public func clone(): Array<T>

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

返回值：

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

func clone(Range<Int64>)

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

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

注意：

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

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

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

range 的步长只能为 1。

参数：

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

返回值：

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

异常：

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

示例：

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

运行结果：

[1, 2, 3]

func concat(Array<T>)

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

功能：该函数将创建一个新的数组，数组内容是当前数组后面串联 other 指向的数组。

参数：

other: Array<T> - 串联到当前数组末尾的数组。

返回值：

Array<T> - 串联得到的新数组。

示例：

main() {
    let arr = [0, 1, 2, 3, 4, 5]
    let new = arr.concat([6, 7, 8, 9, 10])
    println(new)
}

运行结果：

[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

func copyTo(Array<T>, Int64, Int64, Int64)

public func copyTo(dst: Array<T>, srcStart: Int64, dstStart: Int64, copyLen: Int64): Unit

功能：将当前数组中的一段数据拷贝到目标数组中。

参数：

dst: Array<T> - 目标数组。
srcStart: Int64 - 从 this 数组的 srcStart 下标开始拷贝，取值范围为 [0, this.size)。
dstStart: Int64 - 从目标数组的 dstStart 下标开始写入，取值范围为 [0, dst.size)。
copyLen: Int64 - 拷贝数组的长度，取值要求为 copyLen + srcStart < this.size，copyLen + dstStart < dst.size。

异常：

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

示例：

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

运行结果：

[0, 0, 2, 3, 4, 5]

func get(Int64)

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

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

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

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

参数：

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

返回值：

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

func reverse()

public func reverse(): Unit

功能：反转数组，将数组中元素的顺序进行反转。

示例：

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

运行结果：

[5, 4, 3, 2, 1, 0]

func set(Int64, T)

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

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

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

参数：

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

异常：

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

func slice(Int64, Int64)

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

功能：获取数组切片。

注意：

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

参数：

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

返回值：

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

异常：

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

operator func [](Int64)

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

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

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

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

参数：

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

返回值：

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

异常：

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

operator func [](Int64, T)

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

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

参数：

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

异常：

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

operator func [](Range<Int64>)

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

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

注意：

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

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

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

range 的步长只能为 1。

参数：

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

返回值：

Array<T> - 数组切片。

异常：

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

示例：

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

运行结果：

[1, 2, 10]

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

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

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

range 表示的区见的长度和目标数组 value 的大小需相等。

注意：

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

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

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

range 的步长只能为 1。

参数：

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

异常：

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

示例：

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

运行结果：

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

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

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

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

注意：

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

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

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

range 的步长只能为 1。

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

参数：

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

异常：

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

示例：

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

运行结果：

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

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

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

prop size

public prop size: Int64

功能：获取元素数量。

类型：Int64

func isEmpty()

public func isEmpty(): Bool

功能：判断数组是否为空。

返回值：

Bool - 如果数组为空，返回 true，否则，返回 false。

func iterator()

public func iterator(): Iterator<T>

功能：获取当前数组的迭代器，用于遍历数组。

返回值：

Iterator<T> - 当前数组的迭代器。

func toArray()

public func toArray(): Array<T>

功能：根据当前 Array 实例拷贝一个新的 Array 实例。

返回值：

Array<T> - 拷贝得到的新的 Array 实例。

extend<T> Array<T> <: Equatable<Array<T>> where T <: Equatable<T>

extend<T> Array<T> <: Equatable<Array<T>> where T <: Equatable<T>

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

func contains(T)

public func contains(element: T): Bool

功能：查找当前数组是否包含指定元素。

参数：

element: T - 需要查找的目标元素。

返回值：

Bool - 如果存在，则返回 true，否则返回 false。

func indexOf(Array<T>)

public func indexOf(elements: Array<T>): Option<Int64>

功能：返回数组中子数组 elements 出现的第一个位置，如果数组中不包含此数组，返回 None。

注意：

当 T 的类型是 Int64 时，此函数的变长参数语法糖版本可能会和 public func indexOf(element: T, fromIndex: Int64): Option<Int64> 产生歧义，根据优先级，当参数数量是 2 个时，会优先调用 public func indexOf(element: T, fromIndex: Int64): Option<Int64>。

参数：

elements: Array<T> - 需要定位的目标数组。

返回值：

Option<Int64> - 数组中子数组 elements 出现的第一个位置，如果数组中不包含此数组，返回 None。

func indexOf(Array<T>, Int64)

public func indexOf(elements: Array<T>, fromIndex: Int64): Option<Int64>

功能：返回数组中在 fromIndex之后，子数组elements 出现的第一个位置，未找到返回 None。

函数会对 fromIndex 范围进行检查，fromIndex 小于 0 时，将会从第 0 位开始搜索，当 fromIndex 大于等于本数组的大小时，结果为 None。

参数：

elements: Array<T> - 需要定位的元素。
fromIndex: Int64 - 开始搜索的起始位置。

返回值：

Option<Int64> - 数组中在 fromIndex之后，子数组 elements 出现的第一个位置，未找到返回 None。

func indexOf(T)

public func indexOf(element: T): Option<Int64>

功能：获取数组中 element 出现的第一个位置，如果数组中不包含此元素，返回 None。

参数：

element: T - 需要定位的元素。

返回值：

Option<Int64> - 数组中 element 出现的第一个位置，如果数组中不包含此元素，返回 None。

func indexOf(T, Int64)

public func indexOf(element: T, fromIndex: Int64): Option<Int64>

功能：返回数组中在 fromIndex之后， element 出现的第一个位置，未找到返回 None。

函数会从下标 fromIndex 开始查找，fromIndex 小于 0 时，将会从第 0 位开始搜索，当 fromIndex 大于等于本数组的大小时，结果为 None。

参数：

element: T - 需要定位的元素。
fromIndex: Int64 - 查找的起始位置。

返回值：

Option<Int64> - 返回数组中在 fromIndex之后， element 出现的第一个位置，未找到返回 None。

func lastIndexOf(Array<T>)

public func lastIndexOf(elements: Array<T>): Option<Int64>

功能：返回数组中子数组 elements 出现的最后一个位置，如果数组中不存在此子数组，返回 None。

参数：

elements: Array<T> - 需要定位的目标数组。

返回值：

Option<Int64> - 数组中 elements 出现的最后一个位置，如果数组中不存在此子数组，返回 None。

func lastIndexOf(Array<T>, Int64)

public func lastIndexOf(elements: Array<T>, fromIndex: Int64): Option<Int64>

功能：从 fromIndex 开始向后搜索，返回数组中子数组 elements 出现的最后一个位置，如果数组中不存在此子数组，返回 None。

函数会对 fromIndex 范围进行检查，fromIndex 小于 0 时，将会从第 0 位开始搜索，当 fromIndex 大于等于本数组的大小时，结果为 None。

参数：

elements: Array<T> - 需要定位的目标数组。
fromIndex: Int64 - 搜索开始的位置。

返回值：

Option<Int64> - 从 fromIndex 开始向后搜索，数组中子数组 elements 出现的最后一个位置，如果数组中不存在此子数组，返回 None。

func lastIndexOf(T)

public func lastIndexOf(element: T): Option<Int64>

功能：返回数组中 element 出现的最后一个位置，如果数组中不存在此元素，返回 None。

参数：

element: T - 需要定位的目标元素。

返回值：

Option<Int64> - 数组中 element 出现的最后一个位置，如果数组中不存在此元素，返回 None

func lastIndexOf(T, Int64)

public func lastIndexOf(element: T, fromIndex: Int64): Option<Int64>

功能：从 fromIndex 开始向后搜索，返回数组中 element 出现的最后一个位置，如果数组中不存在此元素，返回 None。

函数会对 fromIndex 范围进行检查，fromIndex 小于 0 时，将会从第 0 位开始搜索，当 fromIndex 大于等于本数组的大小时，结果为 None。

参数：

element: T - 需要定位的目标元素。
fromIndex: Int64 - 搜索开始的位置。

返回值：

Option<Int64> - 从 fromIndex 开始向后搜索，返回数组中 element 出现的最后一个位置，如果数组中不存在此元素，返回 None。

func trimLeft(Array<T>)

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

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

参数：

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

返回值：

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

func trimRight(Array<T>)

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

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

参数：

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

返回值：

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

operator func !=(Array<T>)

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

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

参数：

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

返回值：

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

operator func ==(Array<T>)

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

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

两个 Array<T> 相等指的是其中的每个元素都相等。

参数：

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

返回值：

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

extend<T> Array<T> where T <: ToString

extend<T> Array<T> <: ToString where T <: ToString

功能：为 Array<T> 类型扩展 ToString 接口，支持转字符串操作。

func toString()

public func toString(): String

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

字符串形如 "[1, 2, 3, 4, 5]"

返回值：

String - 转化后的字符串。

struct CPointerHandle<T> where T <: CType

public struct CPointerHandle<T> where T <: CType {
    public let array: Array<T>
    public let pointer: CPointer<T>
    public init()
    public init(ptr: CPointer<T>, arr: Array<T>)
}

功能：表示 Array 数组的原始指针，该类型中的泛型参数应该满足 CType 约束。

let array

public let array: Array<T>

功能：原始指针对应的 Array 数组实例。

类型：Array<T>

let pointer

public let pointer: CPointer<T>

功能：获取指定 Array 数组对应的原始指针。

类型：CPointer<T>

init()

public init()

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

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

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

功能：通过传入的 CPointer 和 Array 初始化一个 CPointerHandle。

参数：

ptr: CPointer<T> - 数组原始指针。
arr: Array<T> - 指针对应的仓颉数组。

struct CPointerResource<T> where T <: CType

public struct CPointerResource<T> <: Resource where T <: CType {
    public let value: CPointer<T>
}

功能：该结构体表示 CPointer 对应的资源管理类型，其实例可以通过 CPointer 的成员函数 asResource 获取。

let value

public let value: CPointer<T>

功能：表示当前实例管理的 CPointer<T> 类型实例。

类型：CPointer<T>

func close()

public func close(): Unit

功能：释放其管理的 CPointer<T> 实例指向的内容。

func isClosed()

public func isClosed(): Bool

功能：判断该指针内容是否已被释放。

返回值：

Bool - 返回 true 为已释放。

struct CStringResource

public struct CStringResource <: Resource {
 public let value: CString
}

功能：该结构体表示 CString 对应的资源管理类型，其实例可以通过 CString 的成员函数 asResource 获取。

let value

public let value: CString

功能：表示当前实例管理的 CString 资源。

类型：CString

func close()

public func close(): Unit

功能：释放当前实例管理的 CString 类型实例指向的内容。

func isClosed()

public func isClosed(): Bool

功能：判断该字符串是否被释放。

返回值：

Bool - 返回 true 为已释放。

struct DefaultHasher

public struct DefaultHasher <: Hasher {
 public init(res!: Int64 = 0)
}

功能：该结构体提供了默认哈希算法实现。

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

init(Int64)

public init(res!: Int64 = 0)

功能：构造函数，创建一个 DefaultHasher。

参数：

res!: Int64 - 初始哈希值，默认为 0。

func finish()

public func finish(): Int64

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

返回值：

Int64 - 哈希运算的结果。

func reset()

public mut func reset(): Unit

功能：重置哈希值为 0。

func write(Bool)

public mut func write(value: Bool): Unit

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

参数：

value: Bool - 待运算的值。

func write(Float16)

public mut func write(value: Float16): Unit

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

参数：

value: Float16 - 待运算的值。

func write(Float32)

public mut func write(value: Float32): Unit

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

参数：

value: Float32 - 待运算的值。

func write(Float64)

public mut func write(value: Float64): Unit

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

参数：

value: Float64 - 待运算的值。

func write(Int16)

public mut func write(value: Int16): Unit

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

参数：

value: Int16 - 待运算的值。

func write(Int32)

public mut func write(value: Int32): Unit

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

参数：

value: Int32 - 待运算的值。

func write(Int64)

public mut func write(value: Int64): Unit

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

参数：

value: Int64 - 待运算的值。

func write(Int8)

public mut func write(value: Int8): Unit

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

参数：

value: Int8 - 待运算的值。

func write(Rune)

public mut func write(value: Rune): Unit

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

参数：

value: Rune - 待运算的值。

func write(String)

public mut func write(value: String): Unit

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

参数：

value: String - 待运算的值。

func write(UInt16)

public mut func write(value: UInt16): Unit

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

参数：

value: UInt16 - 待运算的值。

func write(UInt32)

public mut func write(value: UInt32): Unit

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

参数：

value: UInt32 - 待运算的值。

func write(UInt64)

public mut func write(value: UInt64): Unit

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

参数：

value: UInt64 - 待运算的值。

func write(UInt8)

public mut func write(value: UInt8): Unit

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

参数：

value: UInt8 - 待运算的值。

struct LibC

public struct LibC

功能：提供了仓颉中较为高频使用的 C 接口，如申请、释放堆上 CType 实例。

static func free<T>(CPointer<T>) where T <: CType

public static unsafe func free<T>(p: CPointer<T>): Unit where T <: CType

功能：释放指针 p 指向的堆内存。

参数：

p: CPointer<T> - 表示需要被释放的内存地址。

static func free(CString)

public static unsafe func free(cstr: CString): Unit

功能：释放 C 风格字符串。

参数：

cstr: CString - 需要释放的 C 风格字符串。

static func mallocCString(String)

public static unsafe func mallocCString(str: String): CString

功能：通过 String 申请与之字符内容相同的 C 风格字符串。

构造的 C 风格字符串将已 '\0' 结束。

参数：

str: String - 根据该仓颉字符串构造 C 字符串。

返回值：

CString - 新构造的 C 风格字符串。

static func malloc<T>(Int64) where T <: CType

public static func malloc<T>(count!: Int64 = 1): CPointer<T> where T <: CType

功能：在堆中申请指定个数的 T 实例，并返回其起始指针。

申请内存长度为 sizeOf<T>() * count。

参数：

count!: Int64 - 为可选参数，默认为1，表示申请 T 类型的个数。

返回值：

CPointer<T> - 申请的 T 类型指针。

struct Range<T> where T <: Countable<T> & Comparable<T> & Equatable<T>

public struct Range<T> <: Iterable<T> where T <: Countable<T> & Comparable<T> & Equatable<T> {
    public let end: T
    public let hasEnd: Bool
    public let hasStart: Bool
    public let isClosed: Bool
    public let start: T
    public let step: Int64
    public const init(start: T, end: T, step: Int64, hasStart: Bool, hasEnd: Bool, isClosed: Bool)
}

功能：该类是区间类型，用于表示一个拥有固定范围和步长的 T 的序列，要求 T 是可数的，有序的。

区间类型有对应的字面量表示，其格式为：

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

注意：

当 step > 0 且 start >= end，或者 step < 0 且 start <= end 时，该 Range 实例将是一个空区间。

当 step > 0 且 start > end，或者 step < 0 且 start < end 时，该 Range 实例将是一个空区间。

let end

public let end: T

功能：表示结束值。

类型：T

let hasEnd

public let hasEnd: Bool

功能：表示是否包含结束值。

类型：Bool

let hasStart

public let hasStart: Bool

功能：表示是否包含开始值。

类型：Bool

let isClosed

public let isClosed: Bool

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

类型：Bool

let start

public let start: T

功能：表示开始值。

类型：T

let step

public let step: Int64

功能：表示步长。

类型：Int64

init(T, T, Int64, Bool, Bool, Bool)

public const init(start: T, end: T, step: Int64, hasStart: Bool, hasEnd: Bool, isClosed: Bool)

功能：使用该构造函数创建 Range 序列。

参数：

start: T - 开始值。
end: T - 结束值。
step: Int64 - 步长，取值不能为 0。
hasStart: Bool - 是否有开始值。
hasEnd: Bool - 是否有结束值。
isClosed: Bool - true 代表左闭右闭，false 代表左闭右开。

异常：

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

func isEmpty()

public const func isEmpty(): Bool

功能：判断该区间是否为空。

返回值：

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

func iterator()

public func iterator(): Iterator<T>

功能：获取当前区间的迭代器。

返回值：

Iterator<T> - 当前区间的迭代器。

extend<T> Range<T> <: Equatable<Range<T>> where T <: Countable<T> & Comparable<T> & Equatable<T>

extend<T> Range<T> <: Equatable<Range<T>> where T <: Countable<T> & Comparable<T> & Equatable<T>

功能：为 Range<T> 类型扩展 Equatable<Range<T>> 接口。

operator func !=(Range<T>)

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

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

参数：

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

返回值：

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

operator func ==(Range<T>)

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

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

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

参数：

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

返回值：

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

extend<T> Range<T> <: Hashable where T <: Hashable & Countable<T> & Comparable<T> & Equatable<T>

extend<T> Range<T> <: Hashable where T <: Hashable & Countable<T> & Comparable<T> & Equatable<T>

功能：为 Range 类型扩展 Hashable 接口，支持计算哈希值。

func hashCode()

public func hashCode(): Int64

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

返回值：

Int64 - 哈希值。

struct String

public struct String <: Collection<Byte> & Equatable<String> & Comparable<String> & Hashable & ToString {
    public static const empty: String
    public const init()
    public init(value: Array<Rune>)
    public init(value: Collection<Rune>)
}

功能：该结构体表示仓颉字符串，提供了构造、查找、拼接等一系列字符串操作。

注意：

String 类型仅支持 UTF-8 编码。

static const empty

public static const empty: String = String()

功能：创建一个空的字符串并返回。

类型：String

prop size

public prop size: Int64

功能：获取字符串 UTF-8 编码后的字节长度。

类型：Int64

init()

public const init()

功能：构造一个空的字符串。

init(Array<Rune>)

public init(value: Array<Rune>)

功能：根据字符数组构造一个字符串，字符串内容为数组中的所有字符。

参数：

value: Array<Rune> - 根据该字符数组构造字符串。

init(Collection<Rune>)

public init(value: Collection<Rune>)

功能：据字符集合构造一个字符串，字符串内容为集合中的所有字符。

参数：

value: Collection<Rune> - 根据该字符集合构造字符串。

static func fromUtf8(Array<UInt8>)

public static func fromUtf8(utf8Data: Array<UInt8>): String

功能：根据 UTF-8 编码的字节数组构造一个字符串。

参数：

utf8Data: Array<UInt8> - 根据该字节数组构造字符串。

返回值：

String - 构造的字符串。

异常：

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

static func fromUtf8Unchecked(Array<UInt8>)

public static unsafe func fromUtf8Unchecked(utf8Data: Array<UInt8>): String

功能：根据字节数组构造一个字符串。

相较于 fromUtf8 函数，它并没有针对于字节数组进行 UTF-8 相关规则的检查，所以它所构建的字符串并不一定保证是合法的，甚至出现非预期的异常，如果不是某些场景下的性能考虑，请优先使用安全的 fromUtf8 函数。

参数：

utf8Data: Array<UInt8> - 根据该字节数组构造字符串。

返回值：

String - 构造的字符串。

static func join(Array<String>, String)

public static func join(strArray: Array<String>, delimiter!: String = String.empty): String

功能：连接字符串列表中的所有字符串，以指定分隔符分隔。

参数：

strArray: Array<String> - 需要被连接的字符串数组，当数组为空时，返回空字符串。
delimiter!: String - 用于连接的中间字符串，其默认值为 String.empty。

返回值：

String - 连接后的新字符串。

func clone()

public func clone(): String

功能：返回原字符串的拷贝。

返回值：

String - 拷贝得到的新字符串。

func compare(String)

public func compare(str: String): Ordering

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

参数：

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

返回值：

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

异常：

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

func contains(String)

public func contains(str: String): Bool

功能：判断原字符串中是否包含字符串 str。

参数：

str: String - 待搜索的字符串。

返回值：

Bool - 如果字符串 str 在原字符串中，返回 true，否则返回 false。特别地，如果 str 字符串长度为 0，返回 true。

func count(String)

public func count(str: String): Int64

功能：返回子字符串 str 在原字符串中出现的次数。

参数：

str: String - 被搜索的子字符串。

返回值：

Int64 - 出现的次数，当 str 为空字符串时，返回原字符串中 Rune 的数量加一。

func endsWith(String)

public func endsWith(suffix: String): Bool

功能：判断原字符串是否以 suffix 字符串为后缀结尾。

参数：

suffix: String - 被判断的后缀字符串。

返回值：

Bool - 如果字符串 str 是原字符串的后缀，返回 true，否则返回 false，特别地，如果 str 字符串长度为 0，返回 true。

func getRaw()

public unsafe func getRaw(): CPointerHandle<UInt8>

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

注意：

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

返回值：

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

func hashCode()

public func hashCode(): Int64

功能：获取字符串的哈希值。

返回值：

Int64 - 返回字符串的哈希值。

func indexOf(Byte)

public func indexOf(b: Byte): Option<Int64>

功能：获取指定字节 b 第一次出现的在原字符串内的索引。

参数：

b: Byte - 待搜索的字节。

返回值：

Option<Int64> - 如果原字符串中包含指定字节，返回其第一次出现的索引，如果原字符串中没有此字节，返回 None。

func indexOf(Byte, Int64)

public func indexOf(b: Byte, fromIndex: Int64): Option<Int64>

功能：从原字符串指定索引开始搜索，获取指定字节第一次出现的在原字符串内的索引。

参数：

b: Byte - 待搜索的字节。
fromIndex: Int64 - 以指定的索引 fromIndex 开始搜索。

返回值：

Option<Int64> - 如果搜索成功，返回指定字节第一次出现的索引，否则返回 None。特别地，当 fromIndex 小于零，效果同 0，当 fromIndex 大于等于原字符串长度，返回 None。

func indexOf(String)

public func indexOf(str: String): Option<Int64>

功能：返回指定字符串 str 在原字符串中第一次出现的起始索引。

参数：

str: String - 待搜索的字符串。

返回值：

Option<Int64> - 如果原字符串包含 str 字符串，返回其第一次出现的索引，如果原字符串中没有 str 字符串，返回 None。

func indexOf(String, Int64)

public func indexOf(str: String, fromIndex: Int64): Option<Int64>

功能：从原字符串 fromIndex 索引开始搜索，获取指定字符串 str 第一次出现的在原字符串的起始索引。

参数：

str: String - 待搜索的字符串。
fromIndex: Int64 - 以指定的索引 fromIndex 开始搜索。

返回值：

Option<Int64> - 如果搜索成功，返回 str 第一次出现的索引，否则返回 None。特别地，当 str 是空字符串时，如果fromIndex 大于 0，返回 None，否则返回 Some(0)。当 fromIndex 小于零，效果同 0，当 fromIndex 大于等于原字符串长度返回 None。

func isAscii()

public func isAscii(): Bool

功能：判断字符串是否是一个 Ascii 字符串，如果字符串为空或没有 Ascii 以外的字符，则返回 true。

返回值：

Bool - 是则返回 true，不是则返回 false。

func isAsciiBlank()

public func isAsciiBlank(): Bool

功能：判断字符串是否为空或者字符串中的所有 Rune 都是 ascii 码的空白字符（包括：0x09、0x10、0x11、0x12、0x13、0x20）。

返回值：

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

func isEmpty()

public func isEmpty(): Bool

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

返回值：

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

func iterator()

public func iterator(): Iterator<Byte>

功能：获取字符串的 UTF-8 编码字节迭代器，可用于支持 for-in 循环。

返回值：

Iterator<Byte> - 字符串的 UTF-8 编码字节迭代器。

func lastIndexOf(Byte)

public func lastIndexOf(b: Byte): Option<Int64>

功能：返回指定字节 b 最后一次出现的在原字符串内的索引。

参数：

b: Byte - 待搜索的字节。

返回值：

Option<Int64> - 如果原字符串中包含此字节，返回其最后一次出现的索引，否则返回 None。

func lastIndexOf(Byte, Int64)

public func lastIndexOf(b: Byte, fromIndex: Int64): Option<Int64>

功能：从原字符串 fromIndex 索引开始搜索，返回指定 UTF-8 编码字节 b 最后一次出现的在原字符串内的索引。

参数：

b: Byte - 待搜索的字节。
fromIndex: Int64 - 以指定的索引 fromIndex 开始搜索。

返回值：

Option<Int64> - 如果搜索成功，返回指定字节最后一次出现的索引，否则返回 None。特别地，当 fromIndex 小于零，效果同 0，当 fromIndex 大于等于原字符串长度，返回 None。

func lastIndexOf(String)

public func lastIndexOf(str: String): Option<Int64>

功能：返回指定字符串 str 最后一次出现的在原字符串的起始索引。

参数：

str: String - 待搜索的字符串。

返回值：

Option<Int64> - 如果原字符串中包含 str 字符串，返回其最后一次出现的索引，否则返回 None。

func lastIndexOf(String, Int64)

public func lastIndexOf(str: String, fromIndex: Int64): Option<Int64>

功能：从原字符串指定索引开始搜索，获取指定字符串 str 最后一次出现的在原字符串的起始索引。

参数：

str: String - 待搜索的字符串。
fromIndex: Int64 - 以指定的索引 fromIndex 开始搜索。

返回值：

Option<Int64> - 如果这个字符串在位置 fromIndex 及其之后没有出现，则返回 None。特别地，当 str 是空字符串时，如果 fromIndex 大于 0，返回 None，否则返回 Some(0)，当 fromIndex 小于零，效果同 0，当 fromIndex 大于等于原字符串长度返回 None。

func lazySplit(String, Bool)

public func lazySplit(str: String, removeEmpty!: Bool = false): Iterator<String>

功能：对原字符串按照字符串 str 分隔符分割，该函数不立即对字符串进行分割，而是返回迭代器，使用迭代器进行遍历时再实际执行分隔操作。

当 str 未出现在原字符串中，返回大小为 1 的字符串迭代器，唯一的元素为原字符串。

参数：

str: String - 字符串分隔符。
removeEmpty!: Bool - 移除分割结果中的空字符串，默认值为 false。

返回值：

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

func lazySplit(String, Int64, Bool)

public func lazySplit(str: String, maxSplits: Int64, removeEmpty!: Bool = false): Iterator<String>

功能：对原字符串按照字符串 str 分隔符分割，该函数不立即对字符串进行分割，而是返回迭代器，使用迭代器进行遍历时再实际执行分隔操作。

当 maxSplit 为 0 时，返回空的字符串迭代器；
当 maxSplit 为 1 时，返回大小为 1 的字符串迭代器，唯一的元素为原字符串；
当 maxSplit 为负数时，直接返回分割后的字符串迭代器；
当 maxSplit 大于完整分割出来的子字符串数量时，返回完整分割的字符串迭代器；
当 str 未出现在原字符串中，返回大小为 1 的字符串迭代器，唯一的元素为原字符串；
当 str 为空时，对每个字符进行分割；当原字符串和分隔符都为空时，返回空字符串迭代器。

参数：

str: String - 字符串分隔符。
maxSplits: Int64 - 最多分割为 maxSplit 个子字符串。
removeEmpty!: Bool - 移除分割结果中的空字符串，默认值为 false。

返回值：

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

func lines()

public func lines(): Iterator<String>

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

返回值：

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

func padLeft(Int64, String)

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

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

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

参数：

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

返回值：

String - 填充后的字符串。

异常：

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

func padRight(Int64, String)

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

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

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

参数：

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

返回值：

String - 填充后的字符串。

异常：

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

func rawData()

public unsafe func rawData(): Array<Byte>

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

注意：

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

返回值：

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

func releaseRaw(CPointerHandle<UInt8>)

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

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

注意：

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

参数：

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

func replace(String, String)

public func replace(old: String, new: String): String

功能：使用新字符串替换原字符串中旧字符串。

参数：

old: String - 旧字符串。
new: String - 新字符串。

返回值：

String - 替换后的新字符串。

异常：

OutOfMemoryError - 如果此函数分配内存时产生错误，抛出异常。

func runes()

public func runes(): Iterator<Rune>

功能：获取字符串的 Rune 迭代器。

返回值：

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

异常：

IllegalArgumentException - 使用 for-in 或者 next() 方法遍历迭代器时，如果读取到非法字符，抛出异常。

func split(String, Bool)

public func split(str: String, removeEmpty!: Bool = false): Array<String>

功能：对原字符串按照字符串 str 分隔符分割，指定是否删除空串。

当 str 未出现在原字符串中，返回长度为 1 的字符串数组，唯一的元素为原字符串。

参数：

str: String - 字符串分隔符。
removeEmpty!: Bool - 移除分割结果中的空字符串，默认值为 false。

返回值：

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

func split(String, Int64, Bool)

public func split(str: String, maxSplits: Int64, removeEmpty!: Bool = false): Array<String>

功能：对原字符串按照字符串 str 分隔符分割，指定最多分隔子串数，以及是否删除空串。

当 maxSplit 为 0 时，返回空的字符串数组；
当 maxSplit 为 1 时，返回长度为 1 的字符串数组，唯一的元素为原字符串；
当 maxSplit 为负数时，返回完整分割后的字符串数组；
当 maxSplit 大于完整分割出来的子字符串数量时，返回完整分割的字符串数组；
当 str 未出现在原字符串中，返回长度为 1 的字符串数组，唯一的元素为原字符串；
当 str 为空时，对每个字符进行分割；当原字符串和分隔符都为空时，返回空字符串数组。

参数：

str: String - 字符串分隔符。
maxSplits: Int64 - 最多分割为 maxSplit 个子字符串。
removeEmpty!: Bool - 移除分割结果中的空字符串，默认值为 false。

返回值：

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

func startsWith(String)

public func startsWith(prefix: String): Bool

功能：判断原字符串是否以 prefix 字符串为前缀。

参数：

prefix: String - 被判断的前缀字符串。

返回值：

Bool - 如果字符串 str 是原字符串的前缀，返回 true，否则返回 false，特别地，如果 str 字符串长度为 0，返回 true。

func toArray()

public func toArray(): Array<Byte>

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

返回值：

Array<Byte> - 字符串的 UTF-8 编码的字节数组。

func toAsciiLower()

public func toAsciiLower(): String

功能：将该字符串中所有 Ascii 大写字母转化为 Ascii 小写字母。

返回值：

String - 转换后的新字符串。

func toAsciiTitle()

public func toAsciiTitle(): String

功能：将该字符串标题化。

该函数只转换 Ascii 英文字符，当该英文字符是字符串中第一个字符或者该字符的前一个字符不是英文字符，则该字符大写，其他英文字符小写。

返回值：

String - 转换后的新字符串。

func toAsciiUpper()

public func toAsciiUpper(): String

功能：将该字符串中所有 Ascii 小写字母转化为 Ascii 大写字母。

返回值：

String - 转换后的新字符串。

func toRuneArray()

public func toRuneArray(): Array<Rune>

功能：获取字符串的 Rune 数组。如果原字符串为空字符串，则返回空数组。

返回值：

Array<Rune> - 字符串的 Rune 数组。

func toString()

public func toString(): String

功能：获得字符串本身。

返回值：

String - 返回字符串本身。

func trimAscii()

public func trimAscii(): String

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

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

返回值：

String - 转换后的新字符串。

func trimAsciiLeft()

public func trimAsciiLeft(): String

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

返回值：

String - 转换后的新字符串。

func trimAsciiRight()

public func trimAsciiRight(): String

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

返回值：

String - 转换后的新字符串。

func trimLeft(String)

public func trimLeft(prefix: String): String

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

参数：

prefix: String - 待去除的前缀。

返回值：

String - 转换后的新字符串。

func trimRight(String)

public func trimRight(suffix: String): String

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

参数：

suffix: String - 待去除的后缀。

返回值：

String - 转换后的新字符串。

func tryGet(Int64)

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

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

参数：

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

返回值：

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

operator func !=(String)

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

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

参数：

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

返回值：

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

operator func *(Int64)

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

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

参数：

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

返回值：

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

operator func +(String)

public const operator func +(right: String): String

功能：两个字符串相加，将 right 字符串拼接在原字符串的末尾。

参数：

right: String - 待追加的字符串。

返回值：

String - 返回拼接后的字符串。

operator func <(String)

public const operator func <(right: String): Bool

功能：判断两个字符串大小。

参数：

right: String - 待比较的字符串。

返回值：

Bool - 原字符串字典序小于 right 时，返回 true，否则返回 false。

operator func <=(String)

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

功能：判断两个字符串大小。

参数：

right: String - 待比较的字符串。

返回值：

Bool - 原字符串字典序小于或等于 right 时，返回 true，否则返回 false。

operator func ==(String)

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

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

参数：

right: String - 待比较的字符串。

返回值：

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

operator func >(String)

public const operator func >(right: String): Bool

功能：判断两个字符串大小。

参数：

right: String - 待比较的字符串。

返回值：

Bool - 原字符串字典序大于 right 时，返回 true，否则返回 false。

operator func >=(String)

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

功能：判断两个字符串大小。

参数：

right: String - 待比较的字符串。

返回值：

Bool - 原字符串字典序大于或等于 right 时，返回 true，否则返回 false。

operator func [](Int64)

public const operator func [](index: Int64): Byte

功能：返回指定索引 index 处的 UTF-8 编码字节。

参数：

index: Int64 - 要获取 UTF-8 编码字节的下标。

返回值：

Byte - 获取得到下标对应的 UTF-8 编码字节。

异常：

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

operator func [](Range<Int64>)

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

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

注意：

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

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

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

range 的步长只能为 1。

参数：

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

返回值：

String - 字符串切片。

异常：

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

仓颉语言库 API