collection 包

介绍

Collection 包提供可变的元素集合, 分为有序和无序的集合。

有序集合，可以根据元素的整数索引（在列表中的位置）访问元素, 列表中的元素可以重复。

无序集合，通过使用迭代器上可以遍历集合中的元素。无序集合不允许重复元素。

注意：

如果在迭代器迭代过程中, 通过集合修改、增加、删除了某些元素, 迭代器会抛出 ConcurrentModificationException。

主要接口

class ArrayList

public class ArrayList<T> <: Collection<T> {
    public init()
    public init(capacity: Int64)
    public init(size: Int64, initElement: (Int64) -> T)
    public init(elements: Array<T>)
    public init(elements: Collection<T>)
}

此类主要用于实现 ArrayList 数据结构及相关操作函数。

类的主要函数如下所示:

init

public init()

功能：构造一个初始容量为默认值的空 ArrayList构造一个具有默认初始容量 16 的空 ArrayList。

init

public init(capacity: Int64)

功能：构造具有指定初始容量的空 ArrayList。容量是用于存储 ArrayList 中元素的数组的大小，在向 ArrayList 中添加元素时，其容量会自动增长，可以通过对应实例的 capacity() 函数获取容量大小。

参数：

capacity：初始容量大小

异常：

IllegalArgumentException：如果 capacity 小于 0 则抛出异常

init

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

功能：构造具有指定初始元素个数和指定规则函数的 ArrayList。该构造函数根据参数 size 设置 ArrayList 的容量。

参数：

size：初始化函数元素个数
initElement：传入初始化函数

异常：

IllegalArgumentException：如果 size 小于 0 则抛出异常

init

public init(elements: Array<T>)

功能：使用指定数组构造 ArrayList。该构造函数根据传入数组 elements 的 size 设置 ArrayList 的容量。注意，当 T 的类型是 Int64 时，此构造函数的变长参数语法糖版本可能会和 public init(capacity: Int64) 产生歧义，比如 ArrayList<Int64>(8, 9) 是构造一个包含两个元素的 ArrayList，而 ArrayList<Int64>(8) 是构造一个容量为 8 的 ArrayList。

参数：

elements：传入数组

init

public init(elements: Collection<T>)

功能：使用指定集合构造 ArrayList。该构造函数根据传入集合 elements 的 size 设置 ArrayList 的容量。

参数：

elements：传入集合

func get

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

功能：返回此 ArrayList 中指定位置的元素。

参数：

index：index 表示 get 接口的索引

返回值：返回指定位置的元素

func set

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

功能：将此 ArrayList 中指定位置的元素替换为指定的元素。

参数：

index：要设置的索引值
element：T 类型元素

异常：

IndexOutOfBoundsException：当 index 小于 0 或者大于等于 ArrayList 的 size，抛出异常

func append

public func append(element: T): Unit

功能：将指定的元素附加到此 ArrayList 的末尾。

参数：

element：插入元素，类型为 T

func appendAll

public func appendAll(elements: Collection<T>): Unit

功能：将指定集合中的所有元素附加到此 ArrayList 的末尾，按指定集合的迭代器返回的顺序排列。

参数：

elements：导入元素集合

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

func insert

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

功能：在此 ArrayList 中的指定位置插入指定元素。

参数：

index：插入元素的目标索引
element：要插入的 T 类型元素

异常：

IndexOutOfBoundsException，当 index 超出范围时，抛出异常

func insertAll

public func insertAll(index: Int64, elements: Collection<T>): Unit

功能：从指定位置开始，将指定集合中的所有元素插入此 ArrayList。

参数：

index：插入集合的目标索引
elements：要插入的 T 类型元素集合

异常：

IndexOutOfBoundsException，当 index 超出范围时，抛出异常

func prepend

public func prepend(element: T): Unit

功能：在起始位置，将指定元素插入此 ArrayList。

参数：

element：插入 T 类型元素

func prependAll

public func prependAll(elements: Collection<T>): Unit

功能：从起始位置开始，将指定集合中的所有元素插入此 ArrayList。

参数：

elements：要插入的 T 类型元素集合

func remove

public func remove(index: Int64): T

功能：删除此 ArrayList 中指定位置的元素。

参数：

index：被删除元素的索引

返回值：被移除的元素

异常：

IndexOutOfBoundsException，当 index 超出范围时，抛出异常

func remove

public func remove(range: Range<Int64>): Unit

功能：删除此 ArrayList 中 Range 范围所包含的所有元素。

注意：如果参数 range 是使用 Range 构造函数构造的 Range 实例，hasEnd 为 false 时，该 Range 实例为开区间，不受构造时传入的 isClosed 的值的影响。参数：

range：从 range 的 start 开始，删除到 end 位置

异常：

IllegalArgumentException：当 range 的 step 不等于 1 时抛出异常
IndexOutOfBoundsException：当 range 的 start 或 end 小于 0，或 end 大于 Array 的长度时抛出

func removeIf

public func removeIf(predicate: (T) -> Bool): Unit

功能：删除此 ArrayList 中满足给定 lambda 表达式或函数的所有元素。

参数：

predicate：传递判断删除的条件

func clear

public func clear(): Unit

功能：从此 ArrayList 中删除所有元素。

func reverse

public func reverse(): Unit

功能：反转此 ArrayList 中元素的顺序。

func sortBy

public func sortBy(stable!: Bool = false, comparator!: (T, T) -> Ordering): Unit

功能：通过传入的比较函数，根据其返回值 Ordering 类型的结果，可对数组进行自定义排序comparator: (t1: T, t2: T) -> Ordering，如果 comparator 的返回值为 Ordering.GT，排序后 t1 在 t2后；如果 comparator 的返回值为 Ordering.LT，排序后 t1 在t2 前；如果 comparator 的返回值为 Ordering.EQ，且为稳定排序，那么 t1 在 t2 之前；如果 comparator 的返回值为 Ordering.EQ，且为不稳定排序，那么 t1，t2 顺序不确定。

参数：

stable：是否使用稳定排序
comparator：(T, T) -> Ordering 类型

func reserve

public func reserve(additional: Int64): Unit

功能：将 ArrayList 扩容 additional 大小，当 additional 小于等于零时，不发生扩容，当 ArrayList 剩余容量大于等于 additional 时，不发生扩容，当 ArrayList 剩余容量小于 additional 时，取（原始容量的1.5倍向下取整）与（additional + 已使用容量）两个值中的最大值进行扩容。

参数：

additional：将要扩容的大小

func toArray

public func toArray(): Array<T>

功能：转成数组。

返回值：T 类型数组

func capacity

public func capacity(): Int64

功能：返回此 ArrayList 的容量大小

返回值：此 ArrayList 的容量大小

func iterator

public func iterator(): Iterator<T>

功能：在适当的集合中返回此 ArrayList 中元素的迭代器。

返回值：返回迭代器 Iterator

prop size

public prop size: Int64

功能：返回此 ArrayList 中的元素个数返回值 Int64 - 元素个数

func isEmpty

public func isEmpty(): Bool

功能：判断 ArrayList 是否为空。

返回值：如果为空，则返回 true, 否则，返回 false

func slice

public func slice(range: Range<Int64>): ArrayList<T>

功能：传入参数 range 作为索引，返回索引对应的 ArrayList。

注意：如果参数 range 是使用 Range 构造函数构造的 Range 实例，有如下行为：1）start 的值就是构造函数传入的值本身，不受构造时传入的 hashStart 的值的影响2）hasEnd 为 false 时，该 Range 实例为开区间，不受构造时传入的 isClosed 的值的影响。

参数：

range：传递切片的范围

异常：

IllegalArgumentException：当 range.step 不等于 1 时，抛出异常
IndexOutOfBoundsException：当 range 无效时，抛出异常

func clone

public func clone(): ArrayList<T>

功能：克隆新 ArrayList。

返回值：返回新 ArrayList

operator func []

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

功能：操作符重载 - get。

参数：

index：表示 get 接口的索引

返回值：索引位置的元素的值

异常：

IndexOutOfBoundsException：当 index 超出范围时，抛出异常

operator func []

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

功能：操作符重载 - set。

参数：

index：要设置的索引值
value：要设置的 T 类型的值

异常：

IndexOutOfBoundsException：当 index 超出范围时，抛出异常

operator func []

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

功能：运算符重载 - 切片。

注意：

如果参数 range 是使用 Range 构造函数构造的 Range 实例，有如下行为：1）start 的值就是构造函数传入的值本身，不受构造时传入的 hashStart 的值的影响2）hasEnd 为 false 时，该 Range 实例为开区间，不受构造时传入的 isClosed 的值的影响。
切片操作返回的ArrayList为全新的对象，与原ArrayList无引用关系。

参数：

range：传递切片的范围

异常：

IllegalArgumentException：当 range.step 不等于 1 时，抛出异常
IndexOutOfBoundsException：当 range 无效时，抛出异常

func getRawArray

public unsafe func getRawArray(): Array<T>

功能：返回 ArrayList 的原始数据。

class LinkedList

public class LinkedList<T> <: Collection<T> {
    public init()
    public init(elements: Collection<T>)
    public init(elements: Array<T>)
    public init(size: Int64, initElement: (Int64)-> T)
}

LinkedList 是一个由双向链表实现的集合，它支持在集合的任何地方插入和删除元素，不支持快速随机访问。

LinkedList 不支持并发操作，并且对集合中元素的修改不会使迭代器失效，只有在添加和删除元素的时候会使迭代器失效。

init

public init()

功能：构造一个空的链表

init

public init(elements: Collection<T>)

功能：按照集合迭代器返回元素的顺序构造一个包含指定集合元素的链表。

参数：

elements：将要放入此链表中的元素集合

init

public init(elements: Array<T>)

功能：按照数组的遍历顺序构造一个包含指定集合元素的 LinkedList 实例。

参数：

elements：将要放入此链表中的元素数组

init

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

功能：创建一个包含 size 个元素，且第 n 个元素满足 (Int64)-> T 条件的链表。

参数：

size：要创建的链表元素数量
initElement：元素的初始化参数

prop size

public prop size: Int64

功能：链表中的元素数量。

prop first

public prop first: Option<T>

功能：链表中第一个元素的值，如果是空链表则返回 None。

prop last

public prop last: Option<T>

功能：链表中最后一个元素的值，如果是空链表则返回 None。

func toArray

public func toArray(): Array<T>

功能：返回一个数组，数组包含该链表中的所有元素，并且顺序与链表的顺序相同。

返回值：T 类型数组

func prepend

public func prepend(element: T): LinkedListNode<T>

功能：在链表的头部位置插入一个元素，并且返回该元素的节点。

参数：

element：要添加到链表中的元素

返回值：指向该元素的节点

func append

public func append(element: T): LinkedListNode<T>

功能：在链表的尾部位置添加一个元素，并且返回该元素的节点。

参数：

element：要添加到链表中的元素

返回值：指向该元素的节点

func insertBefore

public func insertBefore(node: LinkedListNode<T>, element: T): LinkedListNode<T>

功能：在链表中指定节点的前面插入一个元素，并且返回该元素的节点。

参数：

node：指定的节点
element：要添加到链表中的元素

返回值：指向被插入元素的节点

异常：

IllegalArgumentException：如果指定的节点不属于该链表，则抛此异常

func insertAfter

public func insertAfter(node: LinkedListNode<T>, element: T): LinkedListNode<T>

功能：在链表中指定节点的后面插入一个元素，并且返回该元素的节点。

参数：

node：指定的节点
element：要添加到链表中的元素

返回值：指向被插入元素的节点

异常：

IllegalArgumentException：如果指定的节点不属于该链表，则抛此异常

func remove

public func remove(node: LinkedListNode<T>): T

功能：删除链表中指定节点

参数：

node：要被删除的节点

异常：

IllegalArgumentException：如果指定的节点不属于该链表，则抛此异常

func removeIf

public func removeIf(predicate: (T)-> Bool): Unit

功能：删除此链表中满足给定 lambda 表达式或函数的所有元素

参数：

predicate：对于要删除的元素，返回值为 true

func clear

public func clear(): Unit

功能：删除链表中的所有元素

func isEmpty

public func isEmpty(): Bool

功能：返回此链表是否为空链表的判断

返回值：如果此链表中不包含任何元素，返回 true

func iterator

public func iterator(): Iterator<T>

功能：返回当前集合中元素的迭代器，其顺序是从链表的第一个节点到链表的最后一个节点

返回值：当前集合中元素的迭代器

func reverse

public func reverse(): Unit

功能：反转此链表中的元素顺序

func popFirst

public func popFirst() : Option<T>

功能：移除链表的第一个元素，并返回该元素的值

返回值：被删除的元素的值，若链表为空则返回 None

func popLast

public func popLast() : Option<T>

功能：移除链表的最后一个元素，并返回该元素的值

返回值：被删除的元素的值，若链表为空则返回 None

func nodeAt

public func nodeAt(index: Int64): Option<LinkedListNode<T>>

功能：获取链表中的第 index 个元素的节点，编号从 0 开始

参数：

index：指定获取第 index 个元素的节点

返回值：编号为 index 的节点，如果没有则返回 None

func firstNode

public func firstNode(): Option<LinkedListNode<T>>

功能：获取链表中的第一个元素的节点

返回值：第一个元素的节点，如果链表为空链表则返回 None

func lastNode

public func lastNode(): Option<LinkedListNode<T>>

功能：获取链表中的最后一个元素的节点

返回值：最后一个元素的节点，如果链表为空链表则返回 None

func splitOff

public func splitOff(node: LinkedListNode<T>): LinkedList<T>

功能：从指定的节点 node 开始，将链表分割为两个链表，如果分割成功，node 不在当前的链表内，而是作为首个节点存在于新的链表内部。

参数：

node：要分割的位置

返回值：原链表分割后新产生的链表

异常：

IllegalArgumentException：如果指定的节点不属于该链表，则抛此异常

extend LinkedList <: ToString

extend LinkedList<T> <: ToString where T <: ToString

此扩展主要用于实现 LinkedList 的 toString() 函数。

func toString

public func toString(): String

功能：返回此链表的字符串形式，包含了链表中每个元素的字符串形式。

返回值：此链表的字符串形式

extend LinkedList <: Equatable

extend LinkedList<T> <: Equatable<LinkedList<T>> where T <: Equatable<T>

此扩展主要用于实现 LinkedList 的判等函数。

operator func ==

public operator func ==(right: LinkedList<T>): Bool

功能：判断当前链表与目标链表是否相等，如果两个链表中相同位置的元素都相同，则两个链表相等。

参数：

right：与当前链表相比较的链表

返回值：如果两个链表相等，返回 true

operator func !=

public operator func !=(right: LinkedList<T>): Bool

功能：判断当前链表与目标链表是否不相等，如果两个链表中相同位置的元素都相同，则两个链表相等。

参数：

right：与当前链表相比较的链表

返回值：如果两个链表不相等，返回 true

class LinkedListNode

public class LinkedListNode<T>

LinkedListNode 是 LinkedList 上的节点，可以通过 LinkedListNode 对 LinkedList 进行前向后向遍历操作，也可以访问和修改元素的值。

LinkedListNode 只能通过对应 LinkedList 的 'nodeAt'、'firstNode'、'lastNode' 获得，当 LinkedList 删除掉对应的节点时，会造成一个悬空的节点，对悬空的节点进行任何操作都会抛 'IllegalStateException' 异常。

prop value

public mut prop value: T

功能：获取或者修改元素的值。

异常：

IllegalStateException：如果该节点不属于任何链表实例，抛此异常

prop next

public prop next: Option<LinkedListNode<T>>

功能：获取当前节点的下一个节点，如果没有则返回 None。

异常：

IllegalStateException：如果该节点不属于任何链表实例，抛此异常

prop prev

public prop prev: Option<LinkedListNode<T>>

功能：获取当前节点的前一个节点，如果没有则返回 None。

异常：

IllegalStateException：如果该节点不属于任何链表实例，抛此异常

func backward

public func backward(): Iterator<T>

功能：获取一个从当前节点开始，到所对应链表的尾部节点的所有元素的迭代器。

返回值：对应元素的迭代器

异常：

IllegalStateException：如果该节点不属于任何链表实例，抛此异常

func forward

public func forward(): Iterator<T>

功能：获取一个从当前节点开始，到所对应链表的头部节点的所有元素的迭代器。

返回值：对应元素的迭代器

异常：

IllegalStateException：如果该节点不属于任何链表实例，抛此异常

interface Map

该接口是用于 Map 集合中所有 K 和 V 的展示。

public interface Map<K, V> <: Collection<(K, V)> where K <: Equatable<K> {
    func get(key: K): Option<V>
    func contains(key: K): Bool
    func containsAll(keys: Collection<K>): Bool
    mut func put(key: K, value: V): Option<V>
    mut func putAll(elements: Collection<(K, V)>): Unit
    mut func remove(key: K): Option<V>
    mut func removeAll(keys: Collection<K>): Unit
    mut func removeIf(predicate: (K, V) -> Bool): Unit
    mut func clear(): Unit
    func clone(): Map<K, V>
    operator func [](key: K): V
    operator func [](key: K, value!: V): Unit
    func keys(): EquatableCollection<K>
    func values(): Collection<V>
    prop size: Int64
    func isEmpty(): Bool
    func iterator(): Iterator<(K, V)>
}

func get

func get(key: K): Option<V>

功能：根据 key 得到 Map 中映射的值。

参数：

key：传递 key，获取 value

返回值：key 对应的值是用 Option 封装的

func contains

func contains(key: K): Bool

功能：判断是否包含指定键的映射。

参数：

key：传递要判断的 key

返回值：如果存在，则返回 true；否则，返回 false

func containsAll

func containsAll(keys: Collection<K>): Bool

功能：判断是否包含指定集合键的映射。

参数：

keys：传递待判断的 keys

返回值：如果存在，则返回 true；否则，返回 false

func put

mut func put(key: K, value: V): Option<V>

功能：将传入的键值对放入该 Map 中。对于 Map 中已有的键，该键映射的值将被新值替换。

参数：

key：要放置的键
value：要分配的值

返回值：如果赋值之前 key 存在，旧的 value 用 Option 封装；否则，返回 Option.None

func putAll

mut func putAll(elements: Collection<(K, V)>): Unit

功能：将新的键值对放入 Map 中。对于 Map 中已有的键，该键映射的值将被新值替换。

参数：

elements：需要放入到 Map 中的键值对集合

func remove

mut func remove(key: K): Option<V>

功能：从此 Map 中删除指定键的映射（如果存在）。

参数：

key：传入要删除的 key

返回值：从 Map 中移除的键对应的值。用 Option 封装

func removeAll

mut func removeAll(keys: Collection<K>): Unit

功能：从此映射中删除指定集合的映射（如果存在）。

参数：

keys：传入要删除的集合

func removeIf

mut func removeIf(predicate: (K, V) -> Bool): Unit

功能：传入 lambda 表达式，如果满足条件，则删除对应的键值对。

参数：

predicate：传递一个 lambda 表达式进行判断

func clear

mut func clear(): Unit

功能：清除所有键值对。

func clone

func clone(): Map<K, V>

功能：克隆 Map。

返回值：返回一个 Map<K, V>

operator func []

operator func [](key: K): V

功能：运算符重载集合，如果键存在，返回键对应的值，如果不存在，抛出异常。

参数：

key：需要进行查找的键

返回值：与键对应的值

operator func []

operator func [](key: K, value!: V): Unit

功能：运算符重载集合，如果键存在，新 value 覆盖旧 value，如果键不存在，添加此键值对。

参数：

key：需要进行设置的键
value：传递要设置的值

func keys

func keys(): EquatableCollection<K>

功能：返回 Map 中所有的 key，并将所有 key 存储在一个 EquatableCollection 容器中。

返回值：保存所有返回的 key

func values

func values(): Collection<V>

功能：返回 Map 中所有的 value，并将所有 value 存储在一个 Collection 容器中。

返回值：保存所有返回的 value

prop size

prop size: Int64

功能：返回 Map 中所有的键值对的个数

返回值：键值对的个数

func isEmpty

func isEmpty(): Bool

功能：检查 Map 是否为空。

返回值：如果 Map 为空，返回 true; 否则，返回 false

func iterator

func iterator(): Iterator<(K, V)>

功能：返回 Map 的迭代器。

返回值：Map 的迭代器

struct EntryView

public struct EntryView<K, V>  where K <: Hashable & Equatable<K>

此类主要用于插入不存在的键值对时，返回指定的键值在 HashMap 中的引用视图。在使用视图的过程中，如果集合修改、增加、删除了某些元素, 视图会无效并抛出 ConcurrentModificationException。

类的主要函数如下所示:

func isAbsent

public func isAbsent(): Bool

功能：判断视图是否为空。

返回值：如果视图为空，则返回 true；否则，返回 false

func getKey

public func getKey(): K

功能：获取视图中的键，时间复杂度为 O(1)。

返回值：视图的键

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

func getValue

public func getValue(): ?V

功能：获取视图中的值，时间复杂度为 O(1)。如果视图为空，返回 None；否则，返回键对应的值。

返回值：视图的值

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

func setValue

public mut func setValue(v: V): V

功能：设置视图中的值，时间复杂度为 O(1)。如果视图为空，则插入指定的键值对，并返回插入的值；否则，返回设置前的值。

返回值：视图的值

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

class HashMap

public class HashMap<K, V> <: Map<K, V> where K <: Hashable & Equatable<K> {
    public init()
    public init(elements: Collection<(K, V)>)
    public init(elements: Array<(K, V)>)
    public init(capacity: Int64)
    public init(size: Int64, initElement: (Int64) -> (K, V))
}

此类主要用于实现 HashMap 数据结构及相关操作函数。

类的主要函数如下所示:

init

public init()

功能：构造一个具有默认初始容量 (16) 和默认负载因子为空的 HashMap。

init

public init(elements: Collection<(K, V)>)

功能：通过传入的键值对集合构造一个 HashMap。该构造函数根据传入集合 elements 的 size 设置 HashMap 的容量。

参数：

elements：初始化该 HashMap 的键值对集合

异常：

NegativeArraySizeException: 如果内部数组超过了平台允许的大小上限，抛出异常

init

public init(elements: Array<(K, V)>)

功能：通过传入的键值对数组构造一个 HashMap。该构造函数根据传入数组的 size 设置 HashMap 的容量。

参数：

elements：初始化该 HashMap 的键值对数组

异常：

NegativeArraySizeException: 如果内部数组超过了平台允许的大小上限，抛出异常

init

public init(capacity: Int64)

功能：构造一个带有传入容量大小的 HashMap。

参数：

capacity：初始化容量大小

异常：

IllegalArgumentException：如果 capacity 小于 0 则抛出异常
NegativeArraySizeException: 如果内部数组超过了平台允许的大小上限，抛出异常

init

public init(size: Int64, initElement: (Int64) -> (K, V))

功能：通过传入的元素个数 size 和函数规则来构造 HashMap。构造出的 HashMap 的容量受 size 大小影响。

参数：

size：初始化该 HashMap 的函数规则
initElement：初始化该 HashMap 的函数规则

异常：

IllegalArgumentException：如果 size 小于 0 则抛出异常
NegativeArraySizeException: 如果内部数组超过了平台允许的大小上限，抛出异常

func get

public func get(key: K): Option<V>

功能：返回指定键映射到的值，如果 HashMap 不包含指定键的映射，则返回 Option.None。

参数：

key：传入的键

返回值：键对应的值。用 Option 封装

func contains

public func contains(key: K): Bool

功能：判断是否包含指定键的映射。

参数：

key：传递要判断的 key

返回值：如果存在，则返回 true；否则，返回 false

func containsAll

public func containsAll(keys: Collection<K>): Bool

功能：判断是否包含指定集合中所有键的映射。

参数：

keys：键传递待判断的 keys

返回值：如果都包含，则返回 true；否则，返回 false

func put

public func put(key: K, value: V): Option<V>

功能：将新的键值对放入 HashMap 中。对于 HashMap 中已有的键，该键的值将被新值替换。

参数：

key：要放置的键
value：要分配的值

返回值：如果赋值之前 key 存在，旧的 value 用 Option 封装；否则，返回 Option.None

func putIfAbsent

public func putIfAbsent(key: K, value: V): Bool

功能：当此 HashMap 中不存在键 @p key 时，在 HashMap 中添加指定的值 @p value 与指定的键 @p key 的关联。如果 HashMap 已经包含键 @p key，则不执行赋值操作。

参数：

key：要放置的键
value：要分配的值

返回值：如果赋值之前 @p key 存在，则返回false，且不执行赋值操作；当赋值前 @p key 不存在时，执行插值操作，并返回 true。

func putAll

public func putAll(elements: Collection<(K, V)>): Unit

功能：将新的键值对集合放入 HashMap 中。对于 HashMap 中已有的键，该键的值将被新值替换。

参数：

elements：需要添加进 HashMap 的键值对集合

func remove

public func remove(key: K): Option<V>

功能：从此 HashMap 中删除指定键的映射（如果存在）。

参数：

key：传入要删除的 key

返回值：被从 HashMap 中移除的键对应的值。用 Option 封装

func removeAll

public func removeAll(keys: Collection<K>): Unit

功能：从此 HashMap 中删除指定集合中键的映射（如果存在）。

参数：

keys：传入要删除的键的集合

func removeIf

public func removeIf(predicate: (K, V) -> Bool): Unit

功能：传入 lambda 表达式，如果满足条件，则删除对应的键值对。

参数：

predicate：传递一个 lambda 表达式进行判断

func entryView

public func entryView(key: K): EntryView<K, V>

功能：如果不包含特定键，返回一个空的引用视图。如果包含特定键，则返回该键对应的元素的引用视图。

参数：

key：要添加的键值对的键

返回值：一个引用视图

func clear

public func clear(): Unit

功能：清除所有键值对。

func reserve

public func reserve(additional: Int64): Unit

功能：将 HashMap 扩容 additional 大小当 additional 小于等于零时，不发生扩容；当 HashMap 剩余容量大于等于 additional 时，不发生扩容当 HashMap 剩余容量小于 additional 时，取（原始容量的1.5倍向下取整）与（additional + 已使用容量）中的最大值进行扩容。

参数：

additional：将要扩容的大小

func capacity

public func capacity(): Int64

功能：返回 HashMap 的容量。

返回值：HashMap 的容量

func clone

public func clone(): HashMap<K, V>

功能：克隆 HashMap。

返回值：返回一个 HashMap<K, V>

func toArray

public func toArray(): Array<(K, V)>

功能：构造一个包含 HashMap 内键值对的数组，并返回

返回值：包含容器内所有键值对的数组

func keys

public func keys(): EquatableCollection<K>

功能：返回 HashMap 中所有的 key，并将所有 key 存储在一个 Keys 容器中。

返回值：保存所有返回的 key

func values

public func values(): Collection<V>

功能：返回 HashMap 中包含的值，并将所有的 value 存储在一个 Values 容器中。

返回值：保存所有返回的 value

func iterator

public func iterator(): HashMapIterator<K, V>

功能：返回 Hashmap 的迭代器。

返回值：返回 HashMap 的迭代器

prop size

public prop size: Int64

功能：返回键值对的个数返回值 Int64 - 键值对的个数

func isEmpty

public func isEmpty(): Bool

功能：判断 HashMap 是否为空，如果是，则返回 true；否则，返回 false。

返回值：如果 HashMap 为空，则返回 true；否则，返回 false

operator func []

public operator func [](key: K, value!: V): Unit

功能：运算符重载集合，如果键存在，新 value 覆盖旧 value，如果键不存在，添加此键值对。

参数：

key：传递值进行判断
value：传递要设置的值

operator func []

public operator func [](key: K): V

功能：运算符重载集合，如果键存在，返回键对应的值。

参数：

key：传递值进行判断

返回值：与键对应的值

异常：

NoneValueException：如果该 HashMap 不存在该键

interface Set

public interface Set<T> <: Collection<T> where T <: Equatable<T> {
    func contains(element: T): Bool
    func subsetOf(other: Set<T>): Bool
    func containsAll(elements: Collection<T>): Bool
    mut func put(element: T): Bool
    mut func putAll(elements: Collection<T>): Unit
    mut func remove(element: T): Bool
    mut func removeAll(elements: Collection<T>): Unit
    mut func removeIf(predicate: (T) -> Bool): Unit
    mut func clear(): Unit
    mut func retainAll(elements: Set<T>): Unit
    func clone(): Set<T>
}

该接口是用于 Set 集合中所有元素的展示。

func contains

func contains(element: T): Bool

功能：如果该集合包含指定元素，则返回 true。

参数：

element：需要判断的元素

返回值：如果包含，则返回 true；否则，返回 false

func subsetOf

func subsetOf(other: Set<T>): Bool

功能：检查该集合是否为其他集合的子集。

参数：

other：其他集合

返回值：果该集合是指定集合的子集，则返回 true；否则，返回 false

func containsAll

func containsAll(elements: Collection<T>): Bool

功能：检查该集合是否包含其他集合。

参数：

elements：其他集合

返回值：如果该集合包含指定集合，则返回 true；否则，返回 false

func put

mut func put(element: T): Bool

功能：添加元素操作。如果元素已经存在，则不会添加它。

参数：

element：要添加的元素

返回值：如果添加成功，则返回 true；否则，返回 false

func putAll

mut func putAll(elements: Collection<T>): Unit

功能：添加 Collection 中的所有元素至此 Set 中，如果元素存在，则不添加。

参数：

elements：需要被添加的元素的集合

func remove

mut func remove(element: T): Bool

功能：从该结合中移除指定元素（如果存在）。

参数：

element：要删除的元素

func removeAll

mut func removeAll(elements: Collection<T>): Unit

功能：移除此 Set 中那些也包含在指定 Collection 中的所有元素。

参数：

elements：传入 Collection

func removeIf

mut func removeIf(predicate: (T) -> Bool): Unit

功能：传入 lambda 表达式，如果满足 true 条件，则删除对应的元素。

参数：

predicate：传入一个 lambda 表达式进行判断

func clear

mut func clear(): Unit

功能：清除所有键值对。

func retainAll

mut func retainAll(elements: Set<T>): Unit

功能：仅保留该 Set 与入参 Set 中重复的元素。

参数：

elements：要保存的元素集合

func clone

func clone(): Set<T>

功能：克隆此 Set，并返回克隆出的新的 Set。

class HashSet

public class HashSet<T> <: Set<T> where T <: Hashable & Equatable<T> {
    public init()
    public init(elements: Collection<T>)
    public init(elements: Array<T>)
    public init(capacity: Int64)
    public init(size: Int64, initElement: (Int64) -> T)
}

此类主要用于实现 HashSet 数据结构及相关操作函数。

类的主要函数如下所示:

init

public init()

功能：构造一个具有默认初始容量 (16) 和默认负载因子为 (0.75) 的 HashSet。

init

public init(elements: Collection<T>)

功能：使用传入的集合构造 HashSet。该构造函数根据传入集合 elements 的 size 设置 HashSet 的容量。

参数：

elements：初始化 HashSet 的集合

异常：

NegativeArraySizeException: 如果内部数组超过了平台允许的大小上限，抛出异常

init

public init(elements: Array<T>)

功能：使用传入的数组构造 HashSet。该构造函数根据传入数组 elements 的 size 设置 HashSet 的容量。

参数：

elements：初始化 HashSet 的数组

异常：

NegativeArraySizeException: 如果内部数组超过了平台允许的大小上限，抛出异常

init

public init(capacity: Int64)

功能：使用传入的容量构造一个 HashSet。

参数：

capacity：初始化容量大小

异常：

IllegalArgumentException：如果 capacity 小于 0，抛出异常
NegativeArraySizeException: 如果内部数组超过了平台允许的大小上限，抛出异常

init

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

功能：通过传入的函数元素个数 size 和函数规则来构造 HashSet。构造出的 HashSet 的容量受 size 大小影响。

参数：

size：初始化函数中元素的个数
initElement：初始化函数规则

异常：

IllegalArgumentException：如果 size 小于 0，抛出异常
NegativeArraySizeException: 如果内部数组超过了平台允许的大小上限，抛出异常

func contains

public func contains(element: T): Bool

功能：判断 HashSet 是否包含指定元素。

参数：

element：T

返回值：如果包含指定元素，则返回 true；否则，返回 false

func containsAll

public func containsAll(elements: Collection<T>): Bool

功能：判断 HashSet 是否包含指定 Collection 中的所有元素。

参数：

elements：传入 Collection

返回值：如果此 HashSet 包含 Collection 中的所有元素，则返回 true；否则，返回 false

func put

public func put(element: T): Bool

功能：添加元素, 若添加的元素在 HashSet 中存在, 则添加失败。

参数：

element：T

返回值：如果添加成功，则返回 true；否则，返回 false

func putAll

public func putAll(elements: Collection<T>): Unit

功能：添加 Collection 中的所有元素至此 HashSet 中，如果元素存在，则不添加。

参数：

elements：需要被添加的元素的集合

func subsetOf

public func subsetOf(other: Set<T>): Bool

功能：检查该集合是否为其他集合的子集。

参数：

other：传入集合，此函数将判断当前集合是否为 other 的子集

返回值：如果该 Set 是指定 Set 的子集，则返回 true；否则返回 false

func remove

public func remove(element: T): Bool

功能：如果指定元素存在于此 HashSet 中，则将其移除。

参数：

element：需要被移除的元素

返回值：true，表示移除成功；false，表示移除失败

func removeAll

public func removeAll(elements: Collection<T>): Unit

功能：移除此 HashSet 中那些也包含在指定 Collection 中的所有元素。

参数：

elements：需要从此 HashSet 中移除的元素的集合

func removeIf

public func removeIf(predicate: (T) -> Bool): Unit

功能：传入 lambda 表达式，如果满足 true 条件，则删除对应的元素。

参数：

predicate：(T) -> Bool 表达式

func clear

public func clear(): Unit

功能：从此 HashSet 中移除所有元素。

func retainAll

public func retainAll(elements: Set<T>): Unit

功能：从此 HashSet 中保留 Set 中的元素。

参数：

elements：需要保留的 Set

func toArray

public func toArray(): Array<T>

功能：返回一个包含容器内所有元素的数组

返回值：T 类型数组

func clone

public func clone(): HashSet<T>

功能：克隆 HashSet。

返回值：返回克隆到的 HashSet

func reserve

public func reserve(additional: Int64): Unit

功能：将 HashSet 扩容 additional 大小，当 additional 小于等于零时，不发生扩容，当 HashSet 剩余容量大于等于 additional 时，不发生扩容，当 HashSet 剩余容量小于 additional 时，取（原始容量的1.5倍向下取整）与（additional + 已使用容量）中的最大值进行扩容。

参数：

additional：将要扩容的大小

func capacity

public func capacity(): Int64

功能：返回此 HashSet 的内部数组容量大小。

注意: 容量大小不一定等于 HashSet 的 size。

返回值：返回此 HashSet 的内部数组容量大小

func iterator

public func iterator(): Iterator<T>

功能：返回此 HashSet 的迭代器。

返回值：返回此 HashSet 的迭代器

prop size

public prop size: Int64

功能：返回此 HashSet 的元素个数返回值：元素个数

func isEmpty

public func isEmpty(): Bool

功能：判断 HashSet 是否为空。

返回值：如果为空，则返回 true；否则，返回 false

interface EquatableCollection

public interface EquatableCollection<T> <: Collection<T> where T <: Equatable<T> {
    func contains(element: T): Bool
    func containsAll(elements: Collection<T>): Bool
}

该接口用于 HashMap 集合中所有 K 的展示。

func contains

func contains(element: T): Bool

功能：判断 Keys 是否包含指定元素。

参数：

element：指定元素，待判断 Keys 是否包含该元素

返回值：包含返回 true，否则返回 false

func containsAll

func containsAll(elements: Collection<T>): Bool

功能：判断 Keys 是否包含指定集合的所有元素。

参数：

待判断的集合 elements

返回值：包含则返回 true，否则返回 false

class ArrayListIterator

public class ArrayListIterator<T> <: Iterator<T> {
    public init(data: ArrayList<T>)
}

此类主要实现 ArrayList 的迭代器功能。

init

public init(data: ArrayList<T>)

功能：创建 ArrayListIterator 实例。

参数：

date：传入 ArrayList

func next

public func next(): Option<T>

功能：返回迭代中的下一个元素。

返回值：Option 类型

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

func iterator

public func iterator(): Iterator<T>

功能：返回迭代器。

返回值：Iterator 类型

class HashMapIterator

public class HashMapIterator<K, V> <: Iterator<(K, V)> where K <: Hashable & Equatable<K> {
    public init(map: HashMap<K, V>)
}

此类主要实现 HashMap 的迭代器功能。

init

public init(map: HashMap<K, V>)

功能：创建 HashMapIterator<K, V> 实例。

参数：

map：传入 HashMap<K, V>

func next

public func next(): Option<(K, V)>

功能：返回迭代中的下一个元素。

返回值：Option<(K,V)> 类型

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

func iterator

public func iterator(): Iterator<(K, V)>

功能：返回迭代器。

返回值：Iterator<(K,V)> 类型

func remove

public func remove(): Option<(K, V)>

功能：删除此 HashMap 迭代器的 next 函数返回的元素，此函数只能在 next 函数调用时调用一次。

返回值：返回被删除的元素

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

class ConcatIterator

public class ConcatIterator<T> <: Iterator<T> {
    public init(it: Iterable<T>, other: Iterable<T>)
}

这个类 ConcatIterator 用于连接两个 Iterable

init

public init(it: Iterable<T>, other: Iterable<T>)

功能：创建 ConcatIterator 实例。

参数：

it：Iterable
other：Iterable

func next

public func next(): Option<T>

功能：返回迭代中的下一个元素。

返回值：Option 类型

func iterator

public func iterator(): Iterator<T>

功能：返回迭代器。

返回值：Iterator 类型

class FilterIterator

public class FilterIterator<T> <: Iterator<T> {
    public init(it: Iterable<T>, predicate: (T) -> Bool)
}

此类 FilterIterator 使用闭包来确定是否应生成元素，按过滤函数过滤 Iterable。

init

public init(it: Iterable<T>, predicate: (T) -> Bool)

功能：创建 FilterIterator 实例。

参数：

it：Iterable
predicate：过滤函数

func next

public func next(): Option<T>

功能：返回迭代中的下一个元素。

返回值：Option 类型

func iterator

public func iterator(): Iterator<T>

功能：返回迭代器。

返回值：Iterator 类型

class FlatMapIterator

public class FlatMapIterator<T, R> <: Iterator<R> {
    public init(it: Iterable<T>, transform: (T) -> Iterable<R>)
}

这个类 FlatMapIterator 用于转换和扁平化 Iterable，所有元素都通过转换函数转换为 Iterator

init

public init(it: Iterable<T>, transform: (T) -> Iterable<R>)

功能：创建 FlatMapIterator<T, R> 实例。

参数：

it：Iterable
transform：转换函数

func next

public func next(): Option<R>

功能：返回迭代中的下一个元素。

返回值：Option 类型

func iterator

public func iterator(): Iterator<R>

功能：返回迭代器。

返回值：Iterator 类型

class FlattenIterator

public class FlattenIterator<T, R> <: Iterator<R> where T <: Iterable<R> {
    public init(it: Iterable<T>)
}

该类 FlattenIterator 用于扁平化 Iterable

init

public init(it: Iterable<T>)

功能：创建 FlattenIterator<T, R> 实例。

参数：

it：Iterable

func next

public func next(): Option<R>

功能：返回迭代中的下一个元素。

返回值：Option 类型

func iterator

public func iterator(): Iterator<R>

功能：返回迭代器。

返回值：Iterator 类型

class LimitIterator

public class LimitIterator<T> <: Iterator<T> {
    public init(it: Iterable<T>, count: Int64)
}

此限制迭代器类用于生成 Iterable 中的第一个count元素切片 Iterable 类似 array[0..count]，如果计数<0，则抛出异常

init

public init(it: Iterable<T>, count: Int64)

功能：创建 LimitIterator 实例。

参数：

it：Iterable
count：限制计数元素

func next

public func next(): Option<T>

功能：返回迭代中的下一个元素。

返回值：Option 类型

func iterator

public func iterator(): Iterator<T>

功能：返回迭代器。

返回值：Iterator 类型

class MapIterator

public class MapIterator<T, R> <: Iterator<R> {
    public init(it: Iterable<T>, transform: (T) -> R)
}

这个类 MapIterator 用于将 Iterable 转换为另一个 Iterable, 通过转换函数将 Iterable 转换为 Iterator

init

public init(it: Iterable<T>, transform: (T) -> R)

功能：将 Iterator 转换为另一个类型。

参数：

it：Iterable
transform：转换函数

func next

public func next(): Option<R>

功能：返回迭代中的下一个元素。

返回值：Option 类型

func iterator

public func iterator(): Iterator<R>

功能：返回迭代器。

返回值：Iterator 类型

class SkipIterator

public class SkipIterator<T> <: Iterator<T> {
    public init(it: Iterable<T>, count: Int64)
}

此类是一个跳过迭代器类，跳过 Iterable 中的前 n 个元素

init

public init(it: Iterable<T>, count: Int64)

功能：构建 SkipIterator 对象，如果 count 数量大于传入迭代器内元素数量，将跳过所有元素，会没有元素存在于被初始化的迭代器内。

参数：

it：Iterable
count：跳过的元素数量

func next

public func next(): Option<T>

功能：返回迭代中的下一个元素。

返回值：Option 类型

func iterator

public func iterator(): Iterator<T>

功能：返回迭代器。

返回值：Iterator 类型

class StepIterator

public class StepIterator<T> <: Iterator<T> {
    public init(it: Iterable<T>, count: Int64)
}

此类是一个跳跃迭代器类，按照步距为 n 的大小构造 Iterable 中的元素

init

public init(it: Iterable<T>, count: Int64)

功能：构建 SkipIterator 对象，他的 next 元素是当前指针后面第 count 元素，例如 it 内元素为 1，2，3，4，5，指针指向元素 1，那么next 指向的元素是 4。

参数：

it：Iterable
count：步距大小

func next

public func next(): Option<T>

功能：返回迭代中的下一个元素。

返回值：Option 类型

func iterator

public func iterator(): Iterator<T>

功能：返回迭代器。

返回值：Iterator 类型

class WithIndexIterator

public class WithIndexIterator<T> <: Iterator<(Int64, T)> {
    public init(it: Iterable<T>)
}

这个类 WithIndexIterator 是可迭代的索引和元素

init

public init(it: Iterable<T>)

功能：构建 SkipIterator 对象。

参数：

it：Iterable

func next

public func next(): Option<(Int64, T)>

功能：返回迭代中的下一个元素。

返回值：Option<(Int64, T) 类型, 其中 Int64 是迭代元素的索引，T 是内部元素

func iterator

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

功能：返回迭代器。

返回值：Iterator 类型

class ZipIterator

public class ZipIterator<T, R> <: Iterator<(T, R)> {
    public init(itt: Iterable<T>, itr: Iterable<R>)
}

这个类 ZipIterator 用于压缩两个 Iterable，新的 Iterator<T*R> 大小由短 Iterable 控制

init

public init(itt: Iterable<T>, itr: Iterable<R>)

功能：构建 ZipIterator<T, R> 对象。

参数：

itt：Iterable
itr：Iterable

func next

public func next(): Option<(T, R)>

功能：返回迭代中的下一个元素。

返回值：Option<(T, R)> 类型

func iterator

public func iterator(): Iterator<(T, R)>

功能：返回迭代器。

返回值：Iterator<(T, R)> 类型

extend ArrayList <: ToString

extend ArrayList<T> <: ToString where T <: ToString

此扩展主要用于实现 ArrayList 的 toString() 函数。

func toString

public func toString(): String

功能：实现 ArrayList 的 toString() 函数。

返回值：字符串类型

extend ArrayList <: SortExtension

extend ArrayList<T> <: SortExtension where T <: Comparable<T>

此扩展主要用于实现 ArrayList 的排序函数。

func sort

public func sort(stable!: Bool = false): Unit

功能：以升序的方式排序 ArrayList。

参数：

stable：是否使用稳定排序

func sortDescending

public func sortDescending(stable!: Bool = false): Unit

功能：以降序的方式排序 ArrayList。

参数：

stable：是否使用稳定排序

extend ArrayList <: Equatable

extend ArrayList<T> <: Equatable<ArrayList<T>> where T <: Equatable<T>

此扩展主要用于实现 ArrayList 的判等和 contains() 函数。

operator func ==

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

功能：判断 ArrayList 是否相等。

参数：

that：传入 ArrayList

返回值：如果相等，则返回 true；否则，返回 false

operator func !=

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

功能：判断 ArrayList 是否不相等。

参数：

that：传入 ArrayList

返回值：如果不相等，则返回 true；否则，返回 false

func contains

public func contains(element: T): Bool

功能：判断 ArrayList 是否包含指定元素。

参数：

element：T

返回值：如果存在，则返回 true；否则，返回 false

extend HashMap <: ToString

extend HashMap<K, V> <: ToString where V <: ToString, K <: ToString & Hashable & Equatable<K>

此扩展主要用于实现 HashMap 的 toString() 函数。

func toString

public func toString(): String

功能：实现 HashMap 的 toString() 函数。

返回值：字符串类型

extend HashMap <: Equatable

extend HashMap<K, V> <: Equatable<HashMap<K, V>> where V <: Equatable<V>

此扩展主要用于实现 HashMap 的 Equatable 函数。

operator func ==

public operator func ==(right: HashMap<K, V>): Bool

功能：判断 HashMap 是否相等。

参数：

right：传入 HashMap<K, V>

返回值：如果相等，则返回 true；否则，返回 false

operator func !=

public operator func !=(right: HashMap<K, V>): Bool

功能：判断 HashMap 是否不相等。

参数：

right：传入 HashMap<K, V>

返回值：如果不相等，则返回 true；否则，返回 false

extend HashSet <: ToString

extend HashSet<T> <: ToString where T <: Hashable & Equatable<T> & ToString

此扩展主要用于实现 HashSet 的 toString() 函数。

func toString

public func toString(): String

功能：实现 HashSet 的 toString() 函数。

返回值：字符串类型

extend HashSet <: Equatable

extend HashSet<T> <: Equatable<HashSet<T>> where T <: Hashable & Equatable<T>

此扩展主要用于实现 HashSet 的判等功能。

operator func ==

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

功能：判断 HashSet 是否相等。

参数：

that：传入 HashSet

返回值：如果相等，则返回 true；否则，返回 false

operator func !=

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

功能：判断 HashSet 是否不相等。

参数：

that：传入 HashSet

返回值：如果不相等，则返回 true；否则，返回 false

class TreeMap

public class TreeMap<K, V> <: Map<K, V> where K <: Comparable<K> {
    public init()
    public init(elements: Collection<(K, V)>)
    public init(elements: Array<(K,V)>)
    public init(size: Int64, initElement: (Int64) -> (K, V))
}

此类主要用于实现 TreeMap 数据结构及相关操作函数。TreeMap 提供有序的 map 实现，它的顺序由 Comparable 接口保证：小的元素总是在左边，大的元素总是在右边。

init

public init()

功能：构造一个空的 TreeMap。

init

public init(elements: Collection<(K, V)>)

功能：通过传入的键值对集合构造一个 TreeMap。

参数：

elements：初始化该 TreeMap 的键值对集合

init

public init(elements: Array<(K,V)>)

功能：通过传入的键值对数组构造一个 TreeMap。

参数：

elements：初始化该 TreeMap 的键值对数组

init

public init(size: Int64, initElement: (Int64) -> (K, V))

功能：通过传入的元素个数 size 和函数规则来构造 TreeMap。

参数：

size：传入的元素个数
initElement：初始化该 TreeMap 的函数规则

异常：

IllegalArgumentException：如果 size 小于 0 则抛出异常

func firstEntry

public func firstEntry(): Option<(K, V)>

功能：获取 TreeMap 的第一个元素。

返回值：如果存在第一个元素，用 Option 封装该元素并返回；否则返回 Option<(K, V)>.None

func popFirstEntry

public func popFirstEntry(): Option<(K, V)>

功能：删除 TreeMap 的第一个元素。

返回值：如果存在第一个元素，那么删除该元素，用 Option 封装该元素并返回；否则返回 Option<(K, V)>.None

func lastEntry

public func lastEntry(): Option<(K, V)>

功能：获取 TreeMap 的最后一个元素。

返回值：如果存在最后一个元素，用 Option 封装该元素并返回；否则返回 Option<(K, V)>.None

func popLastEntry

public func popLastEntry(): Option<(K, V)>

功能：删除 TreeMap 的最后一个元素。

返回值：如果存在最后一个元素，那么删除该元素，用 Option 封装该元素并返回；否则返回 Option<(K, V)>.None

func findUpper

public func findUpper(bound: K, inclusive!: Bool = false): Option<TreeMapNode<K, V>>

功能：返回比传入的键大的最小元素。

参数：

bound：传入的键
inclusive：是否包含传入的键本身，默认为 false ，即不包含

返回值：如果存在这样一个元素，用 Option<TreeMapNode<K, V>> 封装该元素并返回；否则，返回 Option<TreeMapNode<K, V>>.None

func findLower

public func findLower(bound: K, inclusive!: Bool = false): Option<TreeMapNode<K, V>>

功能：返回比传入的键小的最大元素。

参数：

bound：传入的键
inclusive：是否包含传入的键本身，默认为 false ，即不包含

返回值：如果存在这样一个元素，用 Option<TreeMapNode<K, V>> 封装该元素并返回；否则，返回 Option<TreeMapNode<K, V>>.None

func get

public func get(key: K): Option<V>

功能：返回指定键映射的值。

参数：

key：传递键，获取值

返回值：如果存在这样一个值，用 Option 封装该值并返回；否则，返回 Option.None

func contains

public func contains(key: K): Bool

功能：判断是否包含指定键的映射。

参数：

key：传递要判断的 key

返回值：如果存在，则返回 true；否则，返回 false

func containsAll

public func containsAll(keys: Collection<K>): Bool

功能：判断是否包含指定集合键的映射。

参数：

keys：键的集合 keys

返回值：如果存在，则返回 true；否则，返回 false

func put

public func put(key: K, value: V): Option<V>

功能：将新的键值对放入 TreeMap 中。对于 TreeMap 中已有的键，该键的值将被新值替换。

参数：

key：要放置的键
value：要分配的值

返回值：如果赋值之前 key 存在，旧的 value 用 Option 封装并返回；否则，返回 Option.None

func putAll

public func putAll(elements: Collection<(K, V)>): Unit

功能：将新的键值对集合放入 TreeMap 中。对于 TreeMap 中已有的键，该键的值将被新值替换。

参数：

elements：需要添加进 TreeMap 的键值对集合

func remove

public func remove(key: K): Option<V>

功能：从此映射中删除指定键的映射（如果存在）。

参数：

key：传入要删除的 key

返回值：被移除映射的值用 Option 封装

func removeAll

public func removeAll(keys: Collection<K>): Unit

功能：从此映射中删除指定集合的映射（如果存在）。

参数：

keys：传入要删除的键的集合

func removeIf

public func removeIf(predicate: (K, V) -> Bool): Unit

功能：传入 lambda 表达式，如果满足条件，则删除对应的键值。

参数：

predicate：传递一个 lambda 表达式进行判断

func clear

public func clear(): Unit

功能：清除所有键值对。

func clone

public func clone(): TreeMap<K, V>

功能：克隆 TreeMap。

返回值：返回一个 TreeMap 实例

operator func []

public operator func [](key: K): V

功能：运算符重载集合，如果键存在，返回键对应的值。

参数：

key：传递值进行判断

返回值：与键对应的值

异常：

NoneValueException：如果该 HashMap 不存在该键

operator func []

public operator func [](key: K, value!: V): Unit

功能：运算符重载集合，如果键存在，新 value 覆盖旧 value，如果键不存在，添加此键值对。

参数：

key：传递值进行判断
value：传递要设置的值

func keys

public func keys(): EquatableCollection<K>

功能：返回 TreeMap 中所有的 key，并将所有 key 存储在一个容器中。

返回值：保存所有返回的 key

func values

public func values(): Collection<V>

功能：返回 TreeMap 中包含的值，并将所有的 value 存储在一个容器中。

返回值：保存所有返回的 value

prop size

public prop size: Int64

功能：返回键值的个数

返回值：键值的个数

func isEmpty

public func isEmpty(): Bool

功能：判断 TreeMap 是否为空。

返回值：如果为空，返回 true，否则返回 false

func iterator

public func iterator(): Iterator<(K, V)> {}

功能：返回 TreeMap 的迭代器，迭代器按 Key 值从小到大的顺序迭代。

返回值：TreeMap 的迭代器

extend TreeMap <: ToString

extend TreeMap<K, V> <: ToString where V <: ToString, K <: ToString & Comparable<K>

此扩展主要用于实现 TreeMap 的 toString() 函数。

func toString

public func toString(): String

功能：获取当前 TreeMap 实例的字符串值。

返回值：当前 TreeMap 实例的字符串值

extend TreeMap <: Equatable

此扩展主要用于实现 TreeMap 的 Equatable 接口。

extend TreeMap<K, V> <: Equatable<TreeMap<K, V>> where V <: Equatable<V>, K <: Comparable<K>

operator func ==

public operator func ==(right: TreeMap<K, V>): Bool

功能：判断 TreeMap 是否相等。

参数：

right：传入 TreeMap<K, V>

返回值：如果相等，则返回 true；否则，返回 false

operator func !=

public operator func !=(right: TreeMap<K, V>): Bool

功能：判断 TreeMap 是否不相等。

参数：

right：传入 TreeMap<K, V>

返回值：如果不相等，则返回 true；否则，返回 false

struct TreeMapNode

public struct TreeMapNode<K, V> where K <: Comparable<K>

此类主要用于实现 TreeMap 的节点操作。在使用 TreeMapNode 进行节点操作时，如果此时对 TreeMap 进行插入或删除操作，将会导致 TreeMapNode 的方法抛出异常。

prop key

public prop key: K

功能：获取当前节点的键。

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

prop value

public mut prop value: V

功能：获取或设置当前节点的值。

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

func next

public func next(): Option<TreeMapNode<K, V>>

功能：访问后继节点。

返回值：如果存在后继节点，用 Option<TreeMapNode<K, V>> 封装并返回；否则，返回 Option<TreeMapNode<K, V>>.None

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

func prev

public func prev(): Option<TreeMapNode<K, V>>

功能：访问前继节点。

返回值：如果存在前继节点，用 Option<TreeMapNode<K, V>> 封装并返回；否则，返回 Option<TreeMapNode<K, V>>.None

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

func backward

public func backward(bound: K, inclusive!:Bool = true): Iterator<(K, V)>

功能：从当前节点开始，到 bound 结束，生成一个正序的迭代器。

参数：

bound：传入的键
inclusive：是否包含传入的键本身，默认为 true ，即包含传入的键本身

返回值：返回从当前节点开始，到 bound 结束的一个正序的迭代器

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

func forward

public func forward(bound: K, inclusive!:Bool = true): Iterator<(K, V)>

功能：从当前节点开始，到 bound 结束，生成一个逆序的迭代器。

参数：

bound：传入的键
inclusive：是否包含传入的键本身，默认为 true ，即包含传入的键本身

返回值：返回从当前节点开始，到 bound 结束的一个逆序的迭代器

异常：

ConcurrentModificationException：当函数检测到不同步的并发修改，抛出异常

class ConcurrentModificationException

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

此类为并发修改异常类。当函数检测到不同步的并发修改，抛出异常。

init

public init()

功能：无参构造函数。

init

public init(message: String)

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

参数：

message：预定义消息

func withIndex

public func withIndex<T>(it: Iterable<T>): Iterator<(Int64, T)>

功能：以下是以柯里化函数形式提供一系列迭代器操作函数，此函数用于获取带索引的迭代器。

参数：

it：给定的迭代器

返回值：返回一个带索引的迭代器

func filter

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

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

参数：

predicate：给定的条件

返回值：返回一个筛选函数

func map

public func map<T, R>(transform: (T) -> R): (Iterable<T>) -> Iterator<R>

功能：创建一个映射。

参数：

transform：给定的映射函数

返回值：返回一个映射函数

func flatten

public func flatten<T, R>(it: Iterable<T>): Iterator<R> where T <: Iterable<R>

功能：将嵌套的迭代器展开一层。

参数：

it：给定的迭代器

返回值：返回展开一层后的迭代器

func flatMap

public func flatMap<T, R>(transform: (T) -> Iterable<R>): (Iterable<T>) -> Iterator<R>

功能：创建一个带 flatten 功能的映射。

参数：

transform：给定的映射函数

返回值：返回一个带 flatten 功能的映射函数

func zip

public func zip<T, R>(other: Iterable<R>): (Iterable<T>) -> Iterator<(T, R)>

功能：将两个迭代器合并成一个（以短的为主）。

参数：

other：要合并的其中一个迭代器

返回值：返回一个合并函数

func concat

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

功能：串联两个迭代器。

参数：

other：要串联在后面的迭代器

返回值：返回一个串联函数

func skip

public func skip<T>(count: Int64): (Iterable<T>) -> Iterator<T>

功能：从迭代器跳过特定个数当 count < 0 时，抛异常当 count == 0 时，相当没有跳过任何元素，返回原迭代器当 0 < count < size 时，跳过 count 个元素后，返回含有剩下的元素的新迭代器当 count >= size 时，跳过所有元素，返回空迭代器。

参数：

count：要跳过的个数

返回值：返回一个跳过指定数量元素的函数，执行逻辑如下：

异常：

IllegalArgumentException：当 count < 0 时，抛出异常

func limit

public func limit<T>(count: Int64): (Iterable<T>) -> Iterator<T>

功能：从迭代器取出特定个数当 count < 0 时，抛异常当 count == 0 时，不取元素，返回空迭代器当 0 < count < size 时，取前 count 个元素，返回新迭代器当 count >= size 时，取所有元素，返回原迭代器。

参数：

count：要取出的个数

返回值：> Iterator - 返回一个取出指定数量元素的函数，执行逻辑如下：

异常：

IllegalArgumentException：当 count < 0 时，抛出异常

func step

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

功能：迭代器每次调用 next() 跳过特定个数当 count <= 0 时，抛异常当 count > 0 时，每次调用 next() 跳过 count 次，直到迭代器为空。

参数：

count：每次调用 next() 要跳过的个数

返回值：> Iterator - 返回改变迭代器每次调用 next() 跳过特定个数的函数，执行逻辑如下：

异常：

IllegalArgumentException：当 count < 0 时，抛出异常

func forEach

public func forEach<T>(action: (T) -> Unit): (Iterable<T>) -> Unit

功能：遍历所有元素，指定给定的操作。

参数：

action：给定的操作函数

返回值：返回一个执行遍历操作的函数

func isEmpty

public func isEmpty<T>(it: Iterable<T>): Bool

功能：判断迭代器是否为空。

参数：

it：给定的迭代器

返回值：返回迭代器是否为空

func count

public func count<T>(it: Iterable<T>): Int64

功能：统计迭代器包含元素数量。

参数：

it：给定的迭代器

返回值：返回迭代器包含元素数量

func contains

public func contains<T>(element: T): (Iterable<T>) -> Bool where T <: Equatable<T>

功能：遍历所有元素，判断是否包含指定元素并返回该元素。

参数：

element：要查找的元素

返回值：返回一个查找函数

func max

public func max<T>(it: Iterable<T>): Option<T> where T <: Comparable<T>

功能：筛选最大的元素。

参数：

it：给定的迭代器

返回值：返回最大的元素，若为空则返回 None

func min

public func min<T>(it: Iterable<T>): Option<T> where T <: Comparable<T>

功能：筛选最小的元素。

参数：

it：给定的迭代器

返回值：返回最小的元素，若为空则返回 None

func all

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

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

参数：

predicate：给定的条件

返回值：返回一个判断全部满足条件的函数

func any

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

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

参数：

predicate：给定的条件

返回值：返回一个判断存在任意一个满足条件的函数

func none

public func none<T>(predicate: (T) -> Bool): (Iterable<T>) -> Bool

功能：判断迭代器是否都不满足条件。

参数：

predicate：给定的条件

返回值：返回一个判断都不满足条件的函数

func first

public func first<T>(it: Iterable<T>): Option<T>

功能：获取头部元素。

参数：

it：给定的迭代器

返回值：返回头部元素，若为空则返回 None

func last

public func last<T>(it: Iterable<T>): Option<T>

功能：获取尾部元素。

参数：

it：给定的迭代器

返回值：返回尾部元素，若为空则返回 None

func at

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

功能：获取第 n 个元素。

参数：

n：给定的个数

返回值：返回获取对应位置元素的函数，若迭代器为空则该函数返回 None

func reduce

public func reduce<T, R>(initial: R, operation: (T, R) -> R): (Iterable<T>) -> R

功能：使用指定初始值，从左向右计算。

参数：

initial：给定的 R 类型的初始值

返回值：返回一个规并函数

func fold

public func fold<T, R>(initial: R, operation: (T, R) -> R): (Iterable<T>) -> R

功能：使用指定初始值，从右向左计算。

参数：

initial：给定的 R 类型的初始值

返回值：返回一个折叠函数

func collectString

public func collectString<T>(delimiter!: String = ""): (Iterable<T>) -> String where T <: ToString

功能：将一个对应元素实现了 ToString 接口的迭代器转换成 String 类型。

参数：

delimiter：字符串拼接分隔符

返回值：返回一个转换函数

func collectArray

public func collectArray<T>(it: Iterable<T>): Array<T>

功能：将一个迭代器转换成 Array 类型。

参数：

it：给定的迭代器

返回值：返回一个数组

func collectArrayList

public func collectArrayList<T>(it: Iterable<T>): ArrayList<T>

功能：将一个迭代器转换成 ArrayList 类型。

参数：

it：给定的迭代器

返回值：返回一个 ArrayList

func collectHashSet

public func collectHashSet<T>(it: Iterable<T>): HashSet<T> where T <: Hashable & Equatable<T>

功能：将一个迭代器转换成 HashSet 类型。

参数：

it：给定的迭代器

返回值：返回一个 HashSet

func collectHashMap

public func collectHashMap<K, V>(it: Iterable<(K, V)>): HashMap<K, V> where K <: Hashable & Equatable<K>

功能：将一个迭代器转换成 HashMap 类型。

参数：

it：给定的迭代器

返回值：返回一个 HashMap

示例

ArrayList 的 get/set 函数

下面是 ArrayList 的 get/set 函数示例。

代码如下：

from std import collection.*
main() {
    var a: ArrayList<Int64> = ArrayList<Int64>(10)
    a.append(97)
    a.append(100)
    a.set(1, 120)
    var b = a.get(1)
    print("b=${b.getOrThrow()}")
    return 0
}

运行结果如下：

b=120

ArrayList 的 append/insert 函数

下面是 ArrayList 的 append/insert 函数示例。

代码如下：

from std import collection.*
main() {
    var a: ArrayList<Int64> = ArrayList<Int64>(10)
    var arr: Array<Int64> = [1,2,3]
    a.appendAll(arr)
    a.set(1, 120)
    var b = a.get(2)
    print("b=${b.getOrThrow()},")
    a.insert(1, 12)
    var c = a.get(2)
    print("c=${c.getOrThrow()},")
    var arr1: Array<Int64> = [1,2,3]
    a.insertAll(1, arr1)
    var d = a.get(2)
    print("d=${d.getOrThrow()}")
    return 0
}

运行结果如下:

b=3,c=120,d=2

ArrayList 的 remove/clear/slice 函数

下面是 ArrayList 的 remove/clear/slice 函数示例。

代码如下：

from std import collection.*
main() {
    var a: ArrayList<Int64> = ArrayList<Int64>(97, 100, 99) // Function call syntactic sugar of variable-length
    a.remove(1)
    var b = a.get(1)
    print("b=${b.getOrThrow()}")
    a.clear()
    a.append(11)
    var arr: Array<Int64> = [1,2,3]
    a.insertAll(0, arr)
    var g = a.get(0)
    print("g=${g.getOrThrow()}")
    let r: Range<Int64> = 1..=2 : 1
    var mu: ArrayList<Int64> = a.slice(r)
    var m = mu.get(0)
    print("m=${m.getOrThrow()}")
    return 0
}

运行结果如下:

b=99g=1m=2

Hashmap 的 get/put/contains 函数

下面是 Hashmap 的 get/put/contains 函数示例。

代码如下：

from std import collection.*
main() {
    var m: HashMap<String, Int64> = HashMap<String, Int64>()
    m.put("a", 99)
    m.put("b", 100)
    var a = m.get("a")
    var bool = m.contains("a")
    print("a=${a.getOrThrow()} ")
    print("bool=${bool.toString()}")
    return 0
}

运行结果如下:

a=99 bool=true

HashMap 的 putAll/remove/clear 函数

下面是 HashMap 的 putAll/remove/clear 函数示例。

代码如下：

from std import collection.*
main() {
    var m: HashMap<String, Int64> = HashMap<String, Int64>()
    var arr: Array<(String, Int64)> = [("d", 11), ("e", 12)]
    m.putAll(arr)
    var d = m.get("d")
    print("d=${d.getOrThrow()} ")
    m.remove("d")
    var bool = m.contains("d")
    print("bool=${bool.toString()} ")
    m.clear()
    var bool1 = m.contains("e")
    print("bool1=${bool1.toString()}")
    return 0
}

运行结果如下:

d=11 bool=false bool1=false

HashSet 的 put/iterator/remove 函数

下面是 HashSet 的 put/iterator/remove 函数示例。

代码如下：

from std import collection.*
/* 测试 */
main() {
    var set: HashSet<String> = HashSet<String>()
    set.put("apple")
    set.put("banana")
    set.put("orange")
    set.put("peach")
    var itset = set.iterator()
    while(true) {
        var value = itset.next()
        match(value) {
            case Some(v) =>
                if (!set.contains(v)) {
                    print("Operation failed")
                    return 1
                } else { println(v) }
            case None => break
        }
    }
    set.remove("apple")
    println(set)
    println("Successful operation")
    return 0
}

运行结果如下：

apple
banana
orange
peach
[banana, orange, peach]
Successful operation

迭代器操作函数

下面是 HashSet 的 put/iterator/remove 函数示例。

代码如下：

from std import collection.*

main() {
    let arr = [-1, 2, 3, 4, 5, 6, 7, 8, 9]
    arr |> filter{a: Int64 => a > 0} // filter -1
        |> step<Int64>(2) // [2, 4, 6, 8]
        |> skip<Int64>(2) // [6, 8]
        |> forEach<Int64>(println)

    let str = arr |> filter{a: Int64 => a % 2 == 1} |> collectString<Int64>(delimiter: ">")
    println(str)
    println(arr |> contains(6_i64))
    return 0
}

运行结果如下：

6
8
3>5>7>9
true

collection.concurrent 包

介绍

仓颉 collection.concurrent 包中提供了并发场景下线程安全的数据结构。

主要接口

interface ConcurrentMap

public interface ConcurrentMap<K, V> where K <: Hashable & Equatable<K> {
    func get(key: K): Option<V>
    func contains(key: K): Bool
    mut func put(key: K, value: V): Option<V>
    mut func putIfAbsent(key: K, value: V): Option<V>
    mut func remove(key: K): Option<V>
    mut func remove(key: K, predicate: (V) -> Bool): Option<V>
    mut func replace(key: K, value: V): Option<V>
    mut func replace(key: K, eval: (V) -> V): Option<V>
    mut func replace(key: K, predicate: (V) -> Bool, eval: (V) -> V): Option<V>
}

ConcurrentMap 接口中声明了并发场景下线程安全的 Map 必须保证原子性的方法，我们希望定义的线程安全 Map 类都能实现 ConcurrentMap 接口。例如我们在该包中定义的 ConcurrentHashMap 就实现了 ConcurrentMap 接口，并提供了 ConcurrentMap 中所声明方法的保证原子性的实现。

ConcurrentMap 接口中声明了并发 Map 在并发场景下需要保证原子性的方法。

并发 Map 为“键”到“值”的映射，其中 K 为键的类型，V 为值的类型。

func get

func get(key: K): Option<V>

功能：返回 Map 中键 @p key 所关联的值。

参数：

key：传递 key，获取 value。

返回值：当 @p key 存在时，返回其关联的值 Some(v)；当 @p key 不存在时，返回 None

func contains

func contains(key: K): Bool

功能：判断 Map 中是否包含指定键 @p key 的关联。

参数：

key：传递要判断的 key。

返回值：当 @p key 存在时返回 true；当 @p key 不存在时返回 false

func put

mut func put(key: K, value: V): Option<V>

功能：将指定的值 @p value 与此 Map 中指定的键 @p key 关联。如果 Map 中已经包含键 @p key 的关联，则旧值将被替换；如果 Map 中不包含键 @p key 的关联，则添加键 @p key 与值 @p value 的关联。

参数：

key：要放置的键；
value：要关联的值。

返回值：如果赋值之前 @p key 存在，则返回旧的值 Some(v)；当赋值前 @p key 不存在时，返回 None。

func putIfAbsent

mut func putIfAbsent(key: K, value: V): Option<V>

功能：当此 Map 中不存在键 @p key 时，在 Map 中添加指定的值 @p value 与指定的键 @p key 的关联。如果 Map 已经包含键 @p key，则不执行赋值操作。

参数：

key：要放置的键；
value：要分配的值。

返回值：如果赋值之前 @p key 存在，则返回当前 @p key 对应的值 Some(v)，且不执行赋值操作；当赋值前 @p key 不存在时，返回 None。

func remove

mut func remove(key: K): Option<V>

功能：从此映射中删除指定键 @p key 的映射（如果存在）。

参数：

key：传入要删除的 key

返回值：如果移除之前 @p key 存在，则返回 @p key 对应的值 Some(v)；当移除时 @p key 不存在时，返回 None。

func remove

mut func remove(key: K, predicate: (V) -> Bool): Option<V>

功能：如果 Map 中存在键 @p key 且 @p key 所关联的值 v 满足条件 @p predicate，则从 Map 中删除 @p key 的关联。

参数：

key：传入要删除的 key；
predicate：传递一个 lambda 表达式进行判断。

返回值：如果 Map 中存在 @p key，则返回 @p key 对应的旧值 Some(v)；当 Map 中不存在 @p key 时，或者 @p key 关联的值不满足 @p predicate 时，返回 None。

func replace

mut func replace(key: K, value: V): Option<V>

功能：如果 Map 中存在 @p key，则将 Map 中键 @p key 关联的值替换为 @p value；如果 Map 中不存在 @p key，则不对 Map 做任何修改。

参数：

key：传入要替换所关联值的键；
value：传入要替换成的新值。

返回值：如果 @p key 存在，则返回 @p key 对应的旧值 Some(v)；当 @p key 不存在时，返回 None。

func replace

mut func replace(key: K, eval: (V) -> V): Option<V>

功能：如果 Map 中存在键 @p key（假设其关联的值为 v），则将 Map 中键 @p key 关联的值替换为 @p eval(v) 的计算结果；如果 Map 中不存在键 @p key，则不对 Map 做任何修改。

参数：

key：传入要替换所关联值的键；
eval：传入计算用于替换的新值的函数。

返回值：如果 @p key 存在，则返回 @p key 对应的旧值 Some(v)；当 @p key 不存在时，返回 None。

func replace

mut func replace(key: K, predicate: (V) -> Bool, eval: (V) -> V): Option<V>

功能：如果 Map 中存在键 @p key（假设其关联的值为 v），且 v 满足条件 @p predicate，则将 Map 中键 @p key 关联的值替换为 @p eval(v) 的计算结果；如果 Map 中不存在键 @p key，或者存在键 @p key 但关联的值不满足 @p predicate，则不对 Map 做任何修改。

参数：

key：传入要替换所关联值的键；
predicate：传递一个 lambda 表达式进行判断；
eval：传入计算用于替换的新值的函数。

返回值：如果 @p key 存在，则返回 @p key 对应的旧值 Some(v)；None：当 @p key 不存在时，或者 @p key 关联的值不满足 @p predicate 时，返回 None。

class ConcurrentHashMap

public class ConcurrentHashMap<K, V> <: ConcurrentMap<K, V> & Collection<(K, V)> where K <: Hashable & Equatable<K> {
    public init(concurrencyLevel!: Int64 = DEFAULT_CONCUR_LEVEL)
    public init(capacity: Int64, concurrencyLevel!: Int64 = DEFAULT_CONCUR_LEVEL)
    public init(elements: Collection<(K, V)>, concurrencyLevel!: Int64 = DEFAULT_CONCUR_LEVEL)
    public init(size: Int64, initElement: (Int64) -> (K, V), concurrencyLevel!: Int64 = DEFAULT_CONCUR_LEVEL)
}

此类用于实现并发场景下线程安全的哈希表 ConcurrentHashMap 数据结构及相关操作函数。当 ConcurrentHashMap 中出现键值对数量大于“桶”数量的情况时，会进行“扩容”。

构造函数中的参数 concurrencyLevel 表示“并发度”，即：最多允许多少个线程并发修改 ConcurrentHashMap。查询键值对的操作是非阻塞的，不受所指定的并发度 concurrencyLevel 的限制。参数 concurrencyLevel 默认等于 16，即：DEFAULT_CONCUR_LEVEL 的值。它只影响 ConcurrentHashMap 在并发场景下的性能，不影响功能。

注意：concurrencyLevel 并非越大越好，更大的 concurrencyLevel 会导致更大的内存开销（甚至可能导致 out of memory 异常），用户需要在内存开销和运行效率之间进行平衡。

init

public init(concurrencyLevel!: Int64 = DEFAULT_CONCUR_LEVEL)

功能：构造一个具有默认初始容量（16）和指定并发度（默认等于 16）的 ConcurrentHashMap。

参数：

concurrencyLevel：用户指定的并发度

注意：

如果用户传入的 concurrencyLevel 小于 16，则并发度会被设置为 16。

init

public init(capacity: Int64, concurrencyLevel!: Int64 = DEFAULT_CONCUR_LEVEL)

功能：构造一个带有传入容量大小和指定并发度（默认等于 16）的 ConcurrentHashMap。

参数：

capacity：初始化容量大小
concurrencyLevel：用户指定的并发度

异常：

IllegalArgumentException：如果 capacity 小于 0 则抛出异常

注意：

如果用户传入的 concurrencyLevel 小于 16，则并发度会被设置为 16。

init

public init(elements: Collection<(K, V)>, concurrencyLevel!: Int64 = DEFAULT_CONCUR_LEVEL)

功能：构造一个带有传入迭代器和指定并发度的 ConcurrentHashMap。该构造函数根据传入迭代器元素 elements 的 size 设置 ConcurrentHashMap 的容量。

参数：

elements：初始化迭代器元素
concurrencyLevel：用户指定的并发度

注意：

如果用户传入的 concurrencyLevel 小于 16，则并发度会被设置为 16。

init

public init(size: Int64, initElement: (Int64) -> (K, V), concurrencyLevel!: Int64 = DEFAULT_CONCUR_LEVEL)

功能：构造具有传入大小和初始化函数元素以及指定并发度的 ConcurrentHashMap。该构造函数根据参数 size 设置 ConcurrentHashMap 的容量。

参数：

size：初始化函数元素的大小
initElement：初始化函数元素
concurrencyLevel：用户指定并发度

异常：

IllegalArgumentException：如果 size 小于 0 则抛出异常

注意：

如果用户传入的 concurrencyLevel 小于 16，则并发度会被设置为 16。

func get

public func get(key: K): Option<V>

功能：返回此映射中键 @p key 所关联的值。

参数：

key：传递 key，获取 value

返回值：Option: Some(v): 当 @p key 存在时，返回其关联的值；None: 当 @p key 不存在时

func contains

public func contains(key: K): Bool

功能：判断此映射中是否包含指定键 @p key 的映射。

参数：

key：传递要判断的 key

返回值：Bool: true: 当 @p key 存在时； false: 当 @p key 不存在时

func put

public func put(key: K, value: V): Option<V>

参数：

key：要放置的键
value：要关联的值

返回值：如果赋值之前 @p key 存在，则返回旧的值 Some(v)；当赋值前 @p key 不存在时，返回 None

func putIfAbsent

public func putIfAbsent(key: K, value: V): Option<V>

功能：当此 Map 中不存在键 @p key 时，在 Map 中添加指定的值 @p value 与指定的键 @p key 的关联。如果 Map 已经包含键 @p key，则不执行赋值操作。

参数：

key：要放置的键
value：要分配的值

返回值：如果赋值之前 @p key 存在，则返回当前 @p key 对应的值 Some(v)，且不执行赋值操作；当赋值前 @p key 不存在时，返回 None

func remove

public func remove(key: K): Option<V>

功能：从此映射中删除指定键 @p key 的映射（如果存在）。

参数：

key：传入要删除的 key

返回值：如果移除之前 @p key 存在，则返回 @p key 对应的值 Some(v)；None：当移除时 @p key 不存在时，返回 None

func remove

public func remove(key: K, predicate: (V) -> Bool): Option<V>

功能：如果此映射中存在键 @p key 且 @p key 所映射的值 v 满足条件 @p predicate，则从此映射中删除 @p key 的映射。

参数：

key：传入要删除的 key
predicate：传递一个 lambda 表达式进行判断

返回值：如果映射中存在 @p key，则返回 @p key 对应的旧值；当映射中不存在 @p key 时，或者 @p key 关联的值不满足 @p predicate 时，返回 None

func replace

public func replace(key: K, value: V): Option<V>

功能：如果 Map 中存在 @p key，则将 Map 中键 @p key 关联的值替换为 @p value；如果 Map 中不存在 @p key，则不对 Map 做任何修改。

参数：

key：传入要替换所关联值的键
value：传入要替换成的新值

返回值：如果 @p key 存在，则返回 @p key 对应的旧值 Some(v)；None：当 @p key 不存在时，返回 None

func replace

public func replace(key: K, eval: (V) -> V): Option<V>

参数：

key：传入要替换所关联值的键
eval：传入计算用于替换的新值的函数

返回值：如果 @p key 存在，则返回 @p key 对应的旧值 Some(V)；None：当 @p key 不存在时，返回 None

func replace

public func replace(key: K, predicate: (V) -> Bool, eval: (V) -> V): Option<V>

功能：如果 Map 中存在键 @p key（假设其关联的值为 v），且 v 满足条件 @p predicate，则将 Map 中键 @p key 关联的值替换为 @p eval(v) 的计算结果；如果 Map 中不存在键 @p key，或者存在键 @p key 但关联的值不满足 @p predicate，则不对 Map 做任何修改。参数：

key：传入要替换所关联值的键
predicate：传递一个 lambda 表达式进行判断
eval：传入计算用于替换的新值的函数

返回值：如果 @p key 存在，则返回 @p key 对应的旧值 Some(V)；当 @p key 不存在时，或者 @p key 关联的值不满足 @p predicate 时，返回 None

operator func []

public operator func [](key: K, value!: V): Unit

功能：运算符重载集合，如果键 @p key 存在，新 value 覆盖旧 value；如果键不存在，添加此键值对。

参数：

key：传递值进行判断
value：传递要设置的值

operator func []

public operator func [](key: K): V

功能：运算符重载集合，如果键存在，返回键对应的值；如果不存在，抛出异常。参数：

key：传递值进行判断

返回值：与键对应的值

异常：

NoneValueException：关联中不存在键 @p key

prop size

public prop size: Int64

功能：返回键值的个数。

注意：此方法不保证并发场景下的原子性，建议在环境中没有其它线程并发地修改 Concurrent HashMap 时调用。

func isEmpty

public func isEmpty(): Bool

功能：判断 Concurrent HashMap 是否为空；如果是，则返回 true；否则，返回 false。

注意：此方法不保证并发场景下的原子性，建议在环境中没有其它线程并发地修改 Concurrent HashMap 时调用。

返回值：如果是，则返回 true，否则，返回 false

func iterator

public func iterator(): ConcurrentHashMapIterator<K, V>

功能：获取 Concurrent HashMap 的迭代器。

返回值：Concurrent HashMap 的迭代器

class ConcurrentHashMapIterator

public class ConcurrentHashMapIterator<K, V> <: Iterator<(K, V)> where K <: Hashable & Equatable<K> {
    public init(cmap: ConcurrentHashMap<K, V>)
}

此类主要实现 Concurrent HashMap 的迭代器功能。

注意，这里定义的 Concurrent HashMap 迭代器：

不保证迭代结果为并发 HashMap 某一时刻的 “快照”，建议在环境中没有其它线程并发地修改 Concurrent HashMap 时调用；
迭代器在迭代过程中，不保证可以感知环境线程对目标 Concurrent HashMap 的修改。

init

public init(cmap: ConcurrentHashMap<K, V>)

功能：创建 ConcurrentHashMapIterator<K, V> 实例。

参数：

cmap：待获取其迭代器的 ConcurrentHashMap<K, V> 实例

func next

public func next(): Option<(K, V)>

功能：返回迭代中的下一个元素。

返回值：Option<(K,V)> 类型

func iterator

public func iterator(): Iterator<(K, V)>

功能：获取 ConcurrentHashMap<K, V> 实例的迭代器。

返回值：ConcurrentHashMap<K, V> 实例的迭代器

class BlockingQueue

public class BlockingQueue<E> {
    public init()
    public init(capacity: Int64)
    public init(capacity: Int64, elements: Array<E>)
    public init(capacity: Int64, elements: Collection<E>)
}

此类用于实现 BlockingQueue 数据结构及相关操作函数。 BlockingQueue 是带阻塞机制并支持用户指定容量上界的并发队列。

类的主要函数如下所示：

init

public init()

功能：构造一个具有默认初始容量 (Int64.Max) 的 BlockingQueue。

init

public init(capacity: Int64)

功能：构造一个带有传入容量大小的 BlockingQueue。

参数：

capacity：初始化容量大小

异常：

IllegalArgumentException：如果 capacity 小于等于 0 则抛出异常

init

public init(capacity: Int64, elements: Array<E>)

功能：构造一个带有传入容量大小，并带有传入数组元素的 BlockingQueue。

参数：

capacity：初始化容量大小
elements：初始化数组元素

异常：

IllegalArgumentException：如果 capacity 小于等于 0 或小于数组元素elements 的 size 则抛出异常

init

public init(capacity: Int64, elements: Collection<E>)

功能：构造一个带有传入容量大小，并带有传入迭代器的 BlockingQueue。

参数：

capacity：初始化容量大小
elements：初始化迭代器元素

异常：

IllegalArgumentException：如果 capacity 小于等于 0 或小于迭代器元素elements 的 size 则抛出异常

capacity

public let capacity: Int64

功能：返回此 BlockingQueue 的容量。

prop size

public prop size: Int64

功能：返回此 BlockingQueue 的元素个数。

注意：此方法不保证并发场景下的原子性，建议在环境中没有其它线程并发地修改 BlockingQueue 时调用。

func enqueue

public func enqueue(element: E): Unit

功能：阻塞的入队操作，将元素添加到队列尾部

参数：

element：要添加的元素

func enqueue

public func enqueue(element: E, timeout: Duration): Bool

功能：阻塞的入队操作，将元素添加到队列尾部，如果队列满了，将等待指定的时间。

参数：

element：要添加的元素
timeout：等待时间

返回值：成功添加元素返回 true。超出等待时间还未成功添加元素返回 false

func dequeue

public func dequeue(): E

功能：阻塞的出队操作，获得队首元素并删除。

返回值：返回队首元素

func dequeue

public func dequeue(timeout: Duration): Option<E>

功能：阻塞的出队操作，获得队首元素并删除。如果队列为空，将等待指定的时间。

参数：

timeout：等待时间

返回值：返回队首元素。如果超出等待时间还未成功获取队首元素，则返回 None

func head

public func head(): Option<E>

功能：获取队首元素。

注意：该函数是非阻塞的。

返回值：返回队首元素，队列为空时返回 None

func tryEnqueue

public func tryEnqueue(element: E): Bool

功能：非阻塞的入队操作，将元素添加到队列尾部。

参数：

element：要添加的元素

返回值：成功添加返回 true；如果队列满了，添加失败返回 false

func tryDequeue

public func tryDequeue(): Option<E>

功能：非阻塞的出队操作，获得队首元素并删除。

返回值：返回队首元素，队列为空时返回 None

class NonBlockingQueue

public class NonBlockingQueue<E> {
    public init()
    public init(elements: Collection<E>)
}

此类用于实现 NonBlockingQueue 数据结构及相关操作函数。

NonBlockingQueue 是无界非阻塞并发队列。

init

public init()

功能：构造一个默认的 NonBlockingQueue 实例。

init

public init(elements: Collection<E>)

功能：根据 Collection 实例构造一个 NonBlockingQueue 实例。

参数：

elements：将该容器中元素放入新构造的 NonBlockingQueue 实例中

prop size

public prop size: Int64

功能：获取此 NonBlockingQueue 的元素个数。

注意：此方法不保证并发场景下的原子性，建议在环境中没有其它线程并发地修改 NonBlockingQueue 时调用。

func enqueue

public func enqueue(element: E): Bool

功能：非阻塞的入队操作，将元素添加到队列尾部。

注意：该函数不会返回 false。

参数：

element：要添加的元素

返回值：成功添加元素则返回 true

func dequeue

public func dequeue(): Option<E>

功能：获取并删除队首元素。

返回值：成功删除则返回队首元素，队列为空则返回 None

func head

public func head(): Option<E>

功能：获取队首元素，不会删除该元素。

返回值：成功获取则返回队首元素，队列为空则返回 None

class ArrayBlockingQueue

public class ArrayBlockingQueue<E> {
    public init(capacity: Int64)
    public init(capacity: Int64, elements: Collection<E>)
}

此类为基于数组实现的 Blocking Queue 数据结构及相关操作函数。 ArrayBlockingQueue 是带阻塞机制且需要用户指定容量上界的并发队列。

类的主要函数如下所示：

init

public init(capacity: Int64)

功能：构造一个带有传入容量大小的 ArrayBlockingQueue。

参数：

capacity：初始化容量大小

异常：

IllegalArgumentException：如果 capacity 小于等于 0 则抛出异常

init

public init(capacity: Int64, elements: Collection<E>)

功能：构造一个带有传入容量大小，并带有传入迭代器的 ArrayBlockingQueue。

参数：

capacity：初始化容量大小
elements：初始化迭代器元素

异常：

IllegalArgumentException：如果 capacity 小于等于 0 或小于迭代器元素 elements 的 size 则抛出异常

capacity

public let capacity: Int64

功能：返回此 ArrayBlockingQueue 的容量。

prop size

public prop size: Int64

功能：返回此 ArrayBlockingQueue 的元素个数。

注意：此方法不保证并发场景下的原子性，建议在环境中没有其它线程并发地修改 ArrayBlockingQueue 时调用。

func enqueue

public func enqueue(element: E): Unit

功能：阻塞的入队操作，将元素添加到队列尾部。

参数：

element：要添加的元素

func enqueue

public func enqueue(element: E, timeout: Duration): Bool

功能：阻塞的入队操作，将元素添加到队列尾部，如果队列满了，将等待指定的时间。

参数：

element：要添加的元素
timeout：等待时间

返回值：成功添加元素返回 true，超出等待时间还未成功添加元素返回 false

func dequeue

public func dequeue(): E

功能：阻塞的出队操作，获得队首元素并删除。

返回值：返回队首元素

func dequeue

public func dequeue(timeout: Duration): Option<E>

功能：阻塞的出队操作，获得队首元素并删除，如果队列为空，将等待指定的时间。

参数：

timeout：等待时间

返回值：返回队首元素。如果超出等待时间还未成功获取队首元素，则返回 None

func head

public func head(): Option<E>

功能：获取队首元素。

注意：该函数是非阻塞的。

返回值：返回队首元素，队列为空时返回 None

func tryEnqueue

public func tryEnqueue(element: E): Bool

功能：非阻塞的入队操作，将元素添加到队列尾部。

参数：

element：要添加的元素

返回值：成功添加返回 true；如果队列满了，添加失败返回 false

func tryDequeue

public func tryDequeue(): Option<E>

功能：非阻塞的出队操作，获得队首元素并删除。

返回值：返回队首元素，队列为空时返回 None

仓颉用户手册