Kotlin collections 函数表

Types

Grouping

分类集合，T代表element对象，K代表分类标记值

通过groupingBy获取实例对象

• eachCount: Map
  获取每种分类的数量

• eachCountTo(destination: MutableMap): MutableMap
  获取分类数量并将结果加成到已有计算表destination中

• aggregate(operation: (key: K, accumulator: R?, element: T, first: Boolean) -> R): Map
  通过一个函数(operation)混合每种分类中每个元素的结果
  accumulator为当前分类K的历史混合值，初始值为null，element为当前运算中K分类的某个元素项，first显示element是否当前分类K中的第一个元素

• aggregateTo(destination: Map, operation): Map
  同上，混合元素并将结果加成到已有计算表destination中

• fold(initialValueSelector: (key: K, element: T) -> R, operation: (key: K, accumulator: R, element: T) -> R): Map
  同aggregate，但每个分类K的首元素的operation运算中，accumulator初始值将由initialValueSelector函数提供（foldTo方法同理）

• fold(initialValue: R, operation: (accumulator: R, element: T) -> R): Map
  忽略分类K值的fold版本，每个分类的accumulator均为initialValue（foldTo方法同理）

• reduce(operation: (key: K, accumulator: S, element: T) -> S): Map
  同aggregate，但每个分类从第二位元素开始混合，accumulator初始值为当前分类K中的第一个元素值（reduceTo同理）

Functions

增删

• addAll(elements: Iterable): Boolean
  MutableMap.putAll(pairs: Array>)
  添加另一个集合的所有元素
• remove(element: T): Boolean
  remove(key: K): V?
  remove(key: K, value: V): Boolean
  removeAll(elements: Collection): Boolean
  removeAll(predicate: (T) -> Boolean): Boolean
  除去集合中的指定元素（集）
• retainAll(elements: Collection): Boolean
  retainAll(predicate: (T) -> Boolean): Boolean
  当前集合仅保留指定的元素

改

变换

• fill(element: T, fromIndex: Int = 0, toIndex: Int = size)
  使用指定值填充Array或MutableList
• reverse()
  reversed(): List
  reversedArray(): Array
  翻转元素顺序（并作为新对象返回）
• shuffle()
  shuffle(random: Random)
  shuffled(): List
  shuffled(random: Random): List
  混淆元素顺序（并作为新对象返回）
• sort()
  sort(fromIndex: Int = 0, toIndex: Int = size)
  sortDescending()
  排序数值型或Comparable型集合（或倒序排序）
• sort(comparison: (a: T, b: T) -> Int)
  通过comparison函数排序
• sortBy(selector: (T) -> R?)
  sortByDescending(selector: (T) -> R?)
  通过selector函数将集合元素转换为Comparable对象，并进行排序（或倒序排序）
• sortWith(comparator: Comparator, fromIndex: Int = 0, toIndex: Int = size)
  通过comparator对象进行排序
• sorted(): List
  sortedDescending(): List
  sortedArray(): Array
  sortedArrayDescending(): Array
  sortedBy(selector: (T) -> R?): List
  sortedByDescending(selector: (T) -> R?): List
  sortedWith(comparator: Comparator): List
  sortedArrayWith(comparator: Comparator): Array
  排序并返回新结果对象

映射转换

• asIterable / asList / asSequence
  映射为Iterable、List、Sequence对象
• asReversed
  映射为倒序列表（仅用于List、MutableList），原列表数据变动时自动反映到该倒序列表对象
• associate(transform: (T) -> Pair): Map
  associateBy(keySelector: (T) -> K): Map
  通过函数transform或keySelector，将每个元素关联至一个指定Key值，生成Map对象（associateTo、associateByTo同理）
• chunked(size: Int): List>
  chunked(size: Int, transform: (List) -> R): List
  按指定长度切割成多个子列表（仅用于Iterable，可通过transform函数转换结果为特定类型对象（仅用于Iterable）
• flatMap(transform: (T) -> Iterable): List
  flatMap(transform: (Entry) -> Iterable): List
  将集合中每个元素通过transform函数映射成每个子集合，并将所有子集合的所有元素合并成单一List序列（flatMapTo同理）
• Array>.flatten(): List
  将元素数组的数组（二维数组）平铺成一维列表
• fold(initial: R, operation: (acc: R, T) -> R): R
  foldIndexed(initial: R, operation: (index: Int, acc: R, T) -> R): R
  通过operation函数混合（加成）集合中每个元素T，生成中间及返回最终结果R，初始值由initial提供
• foldRight(initial: R, operation: (T, acc: R) -> R): R
  foldRightIndexed(initial: R, operation: (index: Int, T, acc: R) -> R): R
  逆序混合
• groupBy(keySelector: (T) -> K): Map>
  groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map>
  groupingBy(keySelector: (T) -> K): Grouping
  以keySelector指定的条件分类出集合中同类元素 T，分类标识为 K，可通过valueTransform函数计算元素 T 的映射值（groupByTo同理）
• joinTo(buffer: Appendable, separator: CharSequence = ", ", prefix: CharSequence = "", postfix: CharSequence = "", limit: Int = -1, truncated: CharSequence = "...", transform: (T) -> CharSequence = null): Appendable
  将集合内每个元素通过transform函数转换为字符串，append到buffer对象，字符串分隔符通过separator定义，buffer分别追加prefix和postfix作为元素集合的起始、结束标记，使用limit限制元素数量时，超出限制的部分将以单独一个truncated标记取代，作为最终的集合元素，最后返回buffer对象本身（joinToString相似，使用内建buffer并直接返回String类型）
• map(transform: (T) -> R): List
  mapTo(destination: C, transform: (T) -> R): C
  mapNotNull(transform: (T) -> R?): List
  mapNotNullTo(destination: C, transform: (T) -> R?): C
  mapIndexed(transform: (index: Int, T) -> R): List
  mapIndexedTo(destination: C, transform: (index: Int, T) -> R): C
  mapIndexedNotNull(transform: (index: Int, T) -> R?): List
  mapIndexedNotNullTo(destination: C, transform: (index: Int, T) -> R?): C
  集合内每个元素通过transform函数计算转换，返回结果列表
• Map.mapKeys(transform: (Entry) -> R): Map
  Map.mapKeysTo(destination: M, transform: (Entry) -> R): M
  Map.mapValues(transform: (Entry) -> R): Map
  Map.mapValuesTo(destination: M, transform: (Entry) -> R): M
  Map对象内每个键值对通过transform函数计算转换其Key或Value值，重新组合并返回结果Map
• partition(predicate: (T) -> Boolean): Pair, List>
  通过predicate函数，根据集合内每个元素的布尔返回值，切分集合为两个列表对象
• reduce(operation: (accumulator: S, T) -> S): S
  reduceIndexed(operation: (index: Int, acc: S, T) -> S): S
  通过operation函数，从集合第二个元素T开始混合加成结果S，accumulator初始值为第一个元素值
• reduceRight(operation: (T, acc: S) -> S): S
  reduceRightIndexed(operation: (index: Int, T, acc: S) -> S): S
  逆序混合（集合元素从右侧开始向左侧混合）
• toCollection(destination: C): C
  集合所有元素添加到指定collection对象并返回
• Entry.toPair(): Pair
  Entry转换至Pair类型
• Map.toProperties(): Properties
  Map转换至Properties类型
• ByteArray.toString(charset: Charset): String
  ByteArray根据指定charset转换为String类型
• toTypedArray(): Array
  从某种原始类型Array转换为装箱类型Array
• windowed(size: Int, step: Int = 1, partialWindows: Boolean = false): List>
  windowed(size: Int, step: Int = 1, partialWindows: Boolean = false, transform: (List) -> R): List
  返回一个集合的一系列快照组成的列表，每个快照尺寸为size，起始位置为上个快照的起始元素加上step步进数，partialWindows指定最后的快照元素不足于指定size时，是否继续生成小尺寸快照对象，可通过transform函数转换成指定的快照对象类型
• Map.withDefault(defaultValue: (key: K) -> V): Map
  生成一个内含指定默认值计算函数的Map对象
• withIndex(): Iterable>
  withIndex(): Iterator>
  从集合返回一个包含元素下标索引的Iterable对象，通常用于for循环中：for ((index, value) in list.withIndex())
• Iterable zip Iterable: List>
  Iterable.zip(other: Iterable, transform: (a: T, b: R) -> V): List
  返回一个以Iterable元素为key，以Iterable元素为value组成的Pair列表，或通过transform函数转换为V类型结果对象的列表
• zipWithNext(): List>
  zipWithNext(transform: (a: T, b: T) -> R): List
  集合中每个元素均与下一个元素结合（不消耗该元素），组成Pair或R对象，生成结果列表（列表大小与原列表相同）
• Iterable>.unzip(): Pair, List>
  从Pair列表解析出Key列表和Value列表组成的Pair对象

过滤

• copyOf(): Array
  copyOf(newSize: Int): Array
  copyOfRange(fromIndex: Int, toIndex: Int): Array
  拷贝Array内容到新Array对象，newSize可用于限定拷贝原Array的内容最大数量（小于Array长度）
• distinct(): List
  过滤掉重复元素
• distinctBy(selector: (T) -> K): List
  根据selector函数的返回值过滤重复元素
• drop(n: Int): List、dropLast(n: Int): List
  删除集合头、尾的n个元素
• dropWhile(predicate: (T) -> Boolean): List
  dropLastWhile(predicate: (T) -> Boolean): List
  删除集合头、尾中符合predicate函数指定条件的连续片段（直到遍历到第一个判定为false的元素）
• filter(predicate: (T) -> Boolean): List
  filterIndexed(predicate: (index: Int, T) -> Boolean): List
  过滤集合元素（仅提取predicate函数计算值为true的元素，filterTo、filterIndexedTo同理）
• filterIsInstance(): List
  filterIsInstance(klass: Class): List
  从无类型集合中过滤出对象为返回值R类型的元素（filterIsInstanceTo同理）
• filterKeys(predicate: (K) -> Boolean): Map
  filterValues(predicate: (V) -> Boolean): Map
  通过Key值、Value值过滤Map元素
• filterNot(predicate: (T) -> Boolean): List
  过滤集合元素（仅提取predicate函数计算值为false的元素，filterNotTo同理）
• filterNotNull(): List
  过滤出非null元素（filterNotNullTo同理）
• minusElement(element: T): List
  plusElement(element: T): List
  返回除去（第一个）指定元素、或增加一个指定元素的列表
• slice(indices: IntRange): List
  slice(indices: Iterable): List
  sliceArray(indices: IntRange): Array
  sliceArray(indices: Collection): Array
  裁剪出指定范围的子集并返回

集合操作

通常可通过运算符 + - += -= 直接操作集合运算

• Iterable1 intersect Iterable2: Set
  两集合相交，取其中共同的对象子集
• Iterable1 subtract Iterable2: Set
  返回一个从Iterable1除去Iterable2子集的Set类型结果
• Iterable1 union Iterable2: Set
  返回一个Iterable1加上Iterable2的Set类型超集结果

查

判断

• all(predicate: (T) -> Boolean): Boolean
  判断一个集合中是否每个元素都符合函数predicate限定的条件
• any(): Boolean
  any(predicate: (T) -> Boolean): Boolean
  判断一个集合中是否存在至少一个元素（符合函数predicate限定的条件）
• contains、containsAll(elements: Collection): Boolean
  判断指定集合是否包含特定元素（集）
• containsKey、containsValue
  判断Map对象中是否包含特定Key、Value
• contentDeepEquals、contentDeepHashCode、contentDeepToString
  通过Array内容进行迭代比较、计算哈希值或字符串（包括嵌套Array内容）
• contentEquals、contentHashCode、contentToString
  通过Array内容进行比较、计算哈希值或字符串（不包括嵌套Array内容）
• isEmpty / isNotEmpty
  判断集合是否为空
• max / min
  返回数值型或Comparable型集合的最大、最小元素，不存在时返回null
• maxBy(selector: (T) -> R): T?
  minBy(selector: (T) -> R): T?
  通过selector函数将集合或Map元素转换为Comparable对象，比较并返回最大、最小元素
• maxWith(comparator: Comparator): T?
  minWith(comparator: Comparator): T?
  通过comparator对象比较并返回最大、最小元素
• none(): Boolean
  none(predicate: (T) -> Boolean): Boolean
  判断一个集合是否为空（或没有一个元素符合函数predicate限定的条件）
• Collection?.orEmpty(): Collection
  返回非null的调用对象，或返回一个新建的空集合对象
• requireNoNulls()
  判断集合是否包含null元素，返回集合本身，或抛出异常

计算

• average(): Double
  计算出集合元素的平均值（仅用于数值型Array、Iterable）
• count(): Int
  count(predicate: (T) -> Boolean): Int
  计算出集合的元素数量，predicate函数可用于指定过滤条件
• sum()
  计算出集合元素的总和值（仅用于数值型Array、Iterable）
• sumBy(selector: (T) -> Int): Int
  sumByDouble(selector: (T) -> Double): Double
  通过selector函数计算集合元素的总和值

查找提取

• binarySearch(element: T, comparator: Comparator, fromIndex: Int = 0, toIndex: Int = size): Int
  通过二分查找算法寻找特定对象element的下标索引位置（要求集合已经过comparator函数排序）
• elementAt(index: Int)
  elementAtOrElse(index: Int, defaultValue: (Int) -> T)
  elementAtOrNull(index: Int)
  提取指定下标的元素，超出下标范围时分别抛出异常、返回默认值、返回null
• find(predicate: (T) -> Boolean)
  findLast(predicate: (T) -> Boolean)
  从集合首、尾开始搜索第一个符合predicate条件的元素，不存在时返回null
• first() / first(predicate: (T) -> Boolean)
  firstOrNull() / firstOrNull(predicate: (T) -> Boolean)
  last() / last(predicate: (T) -> Boolean)
  lastOrNull() / lastOrNull(predicate: (T) -> Boolean)
  从集合中提取第一个或最后一个（符合predicate条件的）元素，不存在时抛出异常，或返回null
• getValue(key: K): V
  get(key: K): V?
  getOrDefault(key: K, defaultValue: V): V
  getOrElse(key: K, defaultValue: () -> V): V
  getOrPut(key: K, defaultValue: () -> V): V
  从Map中获取指定元素值，不存在时分别抛出异常、返回null或defaultValue（或存储该defaultValue值）
• getOrNull(index: Int): T?
  getOrElse(index: Int, defaultValue: (Int) -> T): T
  从集合中获取指定下标的元素值，不存在时分别返回null或defaultValue
• indexOf(element: T): Int
  lastIndexOf(element: T): Int
  indexOfFirst(predicate: (T) -> Boolean): Int
  indexOfLast(predicate: (T) -> Boolean): Int
  从集合中获取指定元素或首个、最后一个符合predicate条件的元素下标索引，不存在时返回-1
• single(): T
  single(predicate: (T) -> Boolean): T
  singleOrNull(): T?
  singleOrNull(predicate: (T) -> Boolean): T?
  返回集合的唯一（符合指定条件的）元素，空集合或存在多于两个元素时抛出异常，或返回null
• take(n: Int): List
  takeLast(n: Int): List
  提取前、后n个元素作为新列表对象返回
• takeWhile(predicate: (T) -> Boolean): List
  takeLastWhile(predicate: (T) -> Boolean): List
  提取符合predicate函数指定条件的第一个、最后一个元素并作为新列表对象返回

遍历

• forEach(action: (T) -> Unit): Unit
• forEachIndexed(action: (index: Int, T) -> Unit): Unit
• onEach(action: (T) -> Unit): self
• onEachIndexed(action: (index: Int, T) -> Unit): self
• 对每个元素执行action函数运算（并返回对用对象本身）

参考

Package kotlin.collections

kotlin.collections.Collections

kotlin.collections._Collections.kt

kotlin.collections._Arrays