From fe4eb96daed13a30d9c7f328fa49d2daefe9a2f5 Mon Sep 17 00:00:00 2001 From: Gleb Minaev <43728100+lounres@users.noreply.github.com> Date: Wed, 20 Jul 2022 19:09:20 +0300 Subject: [PATCH] Add docs. --- .../kmath/functions/collectionUtils.kt | 451 ++++++++++++++++-- 1 file changed, 412 insertions(+), 39 deletions(-) diff --git a/kmath-polynomial/src/commonMain/kotlin/space/kscience/kmath/functions/collectionUtils.kt b/kmath-polynomial/src/commonMain/kotlin/space/kscience/kmath/functions/collectionUtils.kt index ee32aa9a7..0d2ea3653 100644 --- a/kmath-polynomial/src/commonMain/kotlin/space/kscience/kmath/functions/collectionUtils.kt +++ b/kmath-polynomial/src/commonMain/kotlin/space/kscience/kmath/functions/collectionUtils.kt @@ -9,7 +9,13 @@ import kotlin.contracts.InvocationKind.* import kotlin.contracts.contract -// TODO: Docs +/** + * Computes the given lambda [compute] on value corresponding to the provided [key] or `null` if the key is not present. + * + * @param key key which corresponding value will be used if it's present. + * @param compute lambda that is computed on the received value. + * @return result of the computation of the lambda. + */ internal inline fun Map.computeOn(key: K, compute: (V?) -> R): R { contract { callsInPlace(compute, EXACTLY_ONCE) @@ -17,7 +23,15 @@ internal inline fun Map.computeOn(key: K, compute: (V?) -> R) return compute(get(key)) } -// TODO: Docs +/** + * Computes the given lambda [compute] on value corresponding to the provided [key] or computes the given lambda + * [defaultResult] if the key is not present. + * + * @param key key which corresponding value will be used if it's present. + * @param compute lambda that is computed on the value corresponding to the [key]. + * @param defaultResult lambda that is computed if the [key] is not present. + * @return result of [compute] lambda if the [key] is present or result of [defaultResult] otherwise. + */ internal inline fun Map.computeOnOrElse(key: K, defaultResult: () -> R, compute: (value: V) -> R): R { contract { callsInPlace(defaultResult, AT_MOST_ONCE) @@ -27,7 +41,15 @@ internal inline fun Map.computeOnOrElse(key: K, defaultResult: ( return (if (key !in this) defaultResult() else compute(get(key) as V)) } -// TODO: Docs +/** + * Computes the given lambda [compute] on value corresponding to the provided [key] or computes the given lambda + * [defaultResult] if the key is not present. + * + * @param key key which corresponding value will be used if it's present. + * @param compute lambda that is computed on the value corresponding to the [key]. + * @param defaultResult default result that is returned in case of the [key]'s absence. + * @return result of [compute] lambda if the [key] is present or [defaultResult] otherwise. + */ internal inline fun Map.computeOnOrElse(key: K, defaultResult: R, compute: (value: V) -> R): R { contract { callsInPlace(compute, AT_MOST_ONCE) @@ -35,7 +57,15 @@ internal inline fun Map.computeOnOrElse(key: K, defaultResult: R return computeOnOrElse(key, { defaultResult }, compute) } -// TODO: Docs +/** + * Computes the given lambda [compute] on value corresponding to the provided [key] or computes the given lambda + * [defaultResult] if the key is not present. + * + * @param key key which corresponding value will be used if it's present. + * @param compute lambda that is computed on the value corresponding to the [key]. + * @param defaultResult default result that is returned in case of the [key]'s absence. + * @return result of [compute] lambda if the [key] is present or [defaultResult] otherwise. + */ internal inline fun Map.computeOnOrElse(key: K, defaultResult: R, compute: (key: K, value: V) -> R): R { contract { callsInPlace(compute, AT_MOST_ONCE) @@ -374,8 +404,20 @@ internal inline fun > Map.copyMapToBy(des internal inline fun > Map.copyMapToBy(destination: D, transform: (key: K, value: V) -> W, resolve: (currentValue: W, newValue: V) -> W): D = copyMapToBy(destination, { (key, value) -> transform(key, value) }, { _, currentValue, newValue -> resolve(currentValue, newValue) }) -// TODO: Docs -internal fun > mergeTo(map1: Map, map2: Map, destination: D): D { +/** + * Merges [the first map][map1] and [the second map][map2] prioritising the second one, puts result to the [destination] + * and returns the [destination]. + * + * Precisely, corresponding keys and values of the received maps are put into the destination overriding existing values + * in the [destination] if needed. For every key appearing in both maps corresponding value from the second map is + * chosen. + * + * @param map1 the first (less prioritised) map to merge. + * @param map2 the second (more prioritised) map to merge. + * @param destination the map where result of the merge is put. + * @return the destination. + */ +internal fun > mergeTo(map1: Map, map2: Map, destination: D): D { for ((key, value) in map1) { destination.put(key, value) } @@ -385,7 +427,20 @@ internal fun > mergeTo(map1: Map, map2: Map< return destination } -// TODO: Docs +/** + * Merges [the first map][map1] and [the second map][map2] resolving conflicts with [resolve] lambda, puts result to the + * [destination] and returns the [destination]. + * + * Precisely, corresponding keys and values of the received maps are put into the destination overriding existing values + * in the [destination] if needed. For every key appearing in both maps corresponding value is a result of the [resolve] + * lambda calculated on the key and its corresponding values from the merged maps. + * + * @param map1 the first (less prioritised) map to merge. + * @param map2 the second (more prioritised) map to merge. + * @param resolve lambda function that resolves merge conflicts. + * @param destination the map where result of the merge is put. + * @return the destination. + */ internal inline fun > mergeToBy(map1: Map, map2: Map, destination: D, resolve: (key: K, value1: V1, value2: V2) -> W): D { for (key in map2.keys) { destination.remove(key) @@ -400,27 +455,82 @@ internal inline fun > mergeToBy(map1: Ma return destination } -// TODO: Docs +/** + * Merges [the first map][map1] and [the second map][map2] resolving conflicts with [resolve] lambda, puts result to the + * [destination] and returns the [destination]. + * + * Precisely, corresponding keys and values of the received maps are put into the destination overriding existing values + * in the [destination] if needed. For every key appearing in both maps corresponding value is a result of the [resolve] + * lambda calculated on the key's corresponding values from the merged maps. + * + * @param map1 the first (less prioritised) map to merge. + * @param map2 the second (more prioritised) map to merge. + * @param resolve lambda function that resolves merge conflicts. + * @param destination the map where result of the merge is put. + * @return the destination. + */ internal inline fun > mergeToBy(map1: Map, map2: Map, destination: D, resolve: (value1: V1, value2: V2) -> W): D = mergeToBy(map1, map2, destination) { _, value1, value2 -> resolve(value1, value2) } -// TODO: Docs +/** + * Merges [the first map][map1] and [the second map][map2] prioritising the second one. + * + * Precisely, corresponding keys and values of the received maps are put into a new empty map which is returned after + * afterwards. For every key appearing in both maps corresponding value from the second map is chosen. + * + * @param map1 the first (less prioritised) map to merge. + * @param map2 the second (more prioritised) map to merge. + * @return the result of the merge. + */ internal fun merge(map1: Map, map2: Map): Map { val result = LinkedHashMap(map1.size + map2.size) return mergeTo(map1, map2, result) } -// TODO: Docs -internal inline fun mergeBy(map1: Map, map2: Map, transform: (key: K, value1: V1, value2: V2) -> W): Map { +/** + * Merges [the first map][map1] and [the second map][map2] resolving conflicts with [resolve] lambda. + * + * Precisely, corresponding keys and values of the received maps are put into a new empty map which is returned after + * afterwards. For every key appearing in both maps corresponding value is a result of the [resolve] lambda calculated + * on the key and its corresponding values from the merged maps. + * + * @param map1 the first (less prioritised) map to merge. + * @param map2 the second (more prioritised) map to merge. + * @param resolve lambda function that resolves merge conflicts. + * @return the result of the merge. + */ +internal inline fun mergeBy(map1: Map, map2: Map, resolve: (key: K, value1: V1, value2: V2) -> W): Map { val result = LinkedHashMap(map1.size + map2.size) - return mergeToBy(map1, map2, result, transform) + return mergeToBy(map1, map2, result, resolve) } -// TODO: Docs -internal inline fun mergeBy(map1: Map, map2: Map, transform: (value1: V1, value2: V2) -> W): Map = - mergeBy(map1, map2) { _, value1, value2 -> transform(value1, value2) } +/** + * Merges [the first map][map1] and [the second map][map2] resolving conflicts with [resolve] lambda. + * + * Precisely, corresponding keys and values of the received maps are put into a new empty map which is returned after + * afterwards. For every key appearing in both maps corresponding value is a result of the [resolve] lambda calculated + * on the key's corresponding values from the merged maps. + * + * @param map1 the first (less prioritised) map to merge. + * @param map2 the second (more prioritised) map to merge. + * @param resolve lambda function that resolves merge conflicts. + * @return the result of the merge. + */ +internal inline fun mergeBy(map1: Map, map2: Map, resolve: (value1: V1, value2: V2) -> W): Map = + mergeBy(map1, map2) { _, value1, value2 -> resolve(value1, value2) } -// TODO: Docs +/** + * Populates the [destination] map with key-value pairs provided by [transform] function applied to each element of the + * given collection resolving conflicts with [resolve] function and returns the [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param transform function which transforms each element to key-value. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the [destination]. + */ internal inline fun > Iterable.associateTo(destination: D, transform: (T) -> Pair, resolve: (key: K, currentValue: V, newValue: V) -> V): D { for (element in this) { val (key, value) = transform(element) @@ -429,7 +539,20 @@ internal inline fun > Iterable.associateTo(dest return destination } -// TODO: Docs +/** + * Populates the [destination] map with key-value pairs, where key is provided by [keySelector] function and value is + * provided by [valueTransform] applied to each element of the given collection, resolving conflicts with [resolve] + * function and returns the [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param keySelector lambda functions that generates keys for the key-value pairs. + * @param valueTransform lambda functions that generates value for the key-value pairs. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the [destination]. + */ internal inline fun > Iterable.associateByTo(destination: D, keySelector: (T) -> K, valueTransform: (T) -> V, resolve: (key: K, currentValue: V, newValue: V) -> V): D { for (element in this) { val key = keySelector(element) @@ -439,7 +562,19 @@ internal inline fun > Iterable.associateByTo(de return destination } -// TODO: Docs +/** + * Populates the [destination] map with key-value pairs, where key is provided by [keySelector] function applied to each + * element of the given collection and value is the element itself, resolving conflicts with [resolve] function and + * returns the [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param keySelector lambda functions that generates keys for the key-value pairs. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the [destination]. + */ internal inline fun > Iterable.associateByTo(destination: D, keySelector: (T) -> K, resolve: (key: K, currentValue: T, newValue: T) -> T): D { for (element in this) { val key = keySelector(element) @@ -448,86 +583,324 @@ internal inline fun > Iterable.associateByTo(desti return destination } -// TODO: Docs +/** + * Populates the [destination] map with key-value pairs provided by [transform] function applied to each element of the + * given collection resolving conflicts with [resolve] function and returns the [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param transform function which transforms each element to key-value pair. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the [destination]. + */ internal inline fun > Iterable.associateTo(destination: D, transform: (T) -> Pair, resolve: (currentValue: V, newValue: V) -> V): D = associateTo(destination, transform) { _, currentValue, newValue -> resolve(currentValue, newValue) } -// TODO: Docs +/** + * Populates the [destination] map with key-value pairs, where key is provided by [keySelector] function and value is + * provided by [valueTransform] applied to each element of the given collection, resolving conflicts with [resolve] + * function and returns the [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param keySelector lambda functions that generates keys for the key-value pairs. + * @param valueTransform lambda functions that generates value for the key-value pairs. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the [destination]. + */ internal inline fun > Iterable.associateByTo(destination: D, keySelector: (T) -> K, valueTransform: (T) -> V, resolve: (currentValue: V, newValue: V) -> V): D = associateByTo(destination, keySelector, valueTransform) { _, currentValue, newValue -> resolve(currentValue, newValue) } -// TODO: Docs +/** + * Populates the [destination] map with key-value pairs, where key is provided by [keySelector] function applied to each + * element of the given collection and value is the element itself, resolving conflicts with [resolve] function and + * returns the [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param keySelector lambda functions that generates keys for the key-value pairs. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the [destination]. + */ internal inline fun > Iterable.associateByTo(destination: D, keySelector: (T) -> K, resolve: (currentValue: T, newValue: T) -> T): D = associateByTo(destination, keySelector) { _, currentValue, newValue -> resolve(currentValue, newValue) } -// TODO: Docs +/** + * Returns a map containing key-value pairs provided by [transform] function applied to elements of the given collection. + * + * All pairs are added in order of iteration. If some key is already added to the map, adding new key-value pair with the + * key is resolved with [resolve] function which takes the key, current value corresponding to the key, and new value + * from the pair. + * + * @param transform function which transforms each element to key-value pair. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the result map. + */ internal inline fun Iterable.associate(transform: (T) -> Pair, resolve: (key: K, currentValue: V, newValue: V) -> V): Map = associateTo(LinkedHashMap(), transform, resolve) -// TODO: Docs +/** + * Returns a map containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to + * elements of the given collection. + * + * All pairs are added in order of iteration. If some key is already added to the map, adding new key-value pair with + * the key is resolved with [resolve] function which takes the key, current value corresponding to the key, and new + * value from the pair. + * + * @param keySelector lambda functions that generates keys for the key-value pairs. + * @param valueTransform lambda functions that generates value for the key-value pairs. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the result map. + */ internal inline fun Iterable.associateBy(keySelector: (T) -> K, valueTransform: (T) -> V, resolve: (key: K, currentValue: V, newValue: V) -> V): Map = associateByTo(LinkedHashMap(), keySelector, valueTransform, resolve) -// TODO: Docs +/** + * Returns a map containing the elements from the given collection indexed by the key returned from [keySelector] + * function applied to each element. + * + * All pairs are added in order of iteration. If some key is already added to the map, adding new key-value pair with + * the key is resolved with [resolve] function which takes the key, current value corresponding to the key, and new + * value from the pair. + * + * @param keySelector lambda functions that generates keys for the key-value pairs. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the result map. + */ internal inline fun Iterable.associateBy(keySelector: (T) -> K, resolve: (key: K, currentValue: T, newValue: T) -> T): Map = associateByTo(LinkedHashMap(), keySelector, resolve) -// TODO: Docs +/** + * Returns a map containing key-value pairs provided by [transform] function applied to elements of the given collection. + * + * All pairs are added in order of iteration. If some key is already added to the map, adding new key-value pair with + * the key is resolved with [resolve] function which takes current value corresponding to the key and new value from the + * pair. + * + * @param transform function which transforms each element to key-value pair. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the result map. + */ internal inline fun Iterable.associate(transform: (T) -> Pair, resolve: (currentValue: V, newValue: V) -> V): Map = associateTo(LinkedHashMap(), transform, resolve) -// TODO: Docs +/** + * Returns a map containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to + * elements of the given collection. + * + * All pairs are added in order of iteration. If some key is already added to the map, adding new key-value pair with + * the key is resolved with [resolve] function which takes current value corresponding to the key and new value from the + * pair. + * + * @param keySelector lambda functions that generates keys for the key-value pairs. + * @param valueTransform lambda functions that generates value for the key-value pairs. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the result map. + */ internal inline fun Iterable.associateBy(keySelector: (T) -> K, valueTransform: (T) -> V, resolve: (currentValue: V, newValue: V) -> V): Map = associateByTo(LinkedHashMap(), keySelector, valueTransform, resolve) -// TODO: Docs +/** + * Returns a map containing the elements from the given collection indexed by the key returned from [keySelector] + * function applied to each element. + * + * All pairs are added in order of iteration. If some key is already added to the map, adding new key-value pair with + * the key is resolved with [resolve] function which takes current value corresponding to the key and new value from the + * pair. + * + * @param keySelector lambda functions that generates keys for the key-value pairs. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the result map. + */ internal inline fun Iterable.associateBy(keySelector: (T) -> K, resolve: (currentValue: T, newValue: T) -> T): Map = associateByTo(LinkedHashMap(), keySelector, resolve) -// TODO: Docs +/** + * Populates the given [destination] map with entries having the keys of this map and the values obtained + * by applying the [transform] function to each entry in this map resolving conflicts with [resolve] function and + * returns the [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param transform function which transforms each key-value pair to new value. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the [destination]. + */ internal inline fun > Map.mapValuesTo(destination: D, transform: (Map.Entry) -> W, resolve: (key: K, currentValue: W, newValue: W) -> W): D = entries.associateByTo(destination, { it.key }, transform, resolve) -// TODO: Docs +/** + * Populates the given [destination] map with entries having the keys of this map and the values obtained + * by applying the [transform] function to each entry in this map resolving conflicts with [resolve] function and + * returns the [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param transform function which transforms each key-value pair to new value. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the [destination]. + */ internal inline fun > Map.mapValuesTo(destination: D, transform: (key: K, value: V) -> W, resolve: (key: K, currentValue: W, newValue: W) -> W): D = entries.associateByTo(destination, { it.key }, { (key, value) -> transform(key, value) }, resolve) -// TODO: Docs +/** + * Populates the given [destination] map with entries having the keys of this map and the values obtained + * by applying the [transform] function to each entry in this map resolving conflicts with [resolve] function and + * returns the [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param transform function which transforms each key-value pair to new value. + * @param resolve lambda function that resolves merge conflicts which current and new values corresponding to some key. + * @return the [destination]. + */ internal inline fun > Map.mapValuesTo(destination: D, transform: (Map.Entry) -> W, resolve: (currentValue: W, newValue: W) -> W): D = entries.associateByTo(destination, { it.key }, transform, resolve) -// TODO: Docs +/** + * Populates the given [destination] map with entries having the keys of this map and the values obtained + * by applying the [transform] function to each entry in this map resolving conflicts with [resolve] function and + * returns the [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param transform function which transforms each key-value pair to new value. + * @param resolve lambda function that resolves merge conflicts which current and new values corresponding to some key. + * @return the [destination]. + */ internal inline fun > Map.mapValuesTo(destination: D, transform: (key: K, value: V) -> W, resolve: (currentValue: W, newValue: W) -> W): D = entries.associateByTo(destination, { it.key }, { (key, value) -> transform(key, value) }, resolve) -// TODO: Docs +/** + * Populates the given [destination] map with entries having the keys obtained by applying the [transform] function to + * each entry in this map and the values of this map, resolving conflicts with [resolve] function and returns the + * [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param transform function which transforms each key-value pair to new key. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the [destination]. + */ internal inline fun > Map.mapKeysTo(destination: D, transform: (Map.Entry) -> L, resolve: (key: L, currentValue: V, newValue: V) -> V): D = entries.associateByTo(destination, transform, { it.value }, resolve) -// TODO: Docs +/** + * Populates the given [destination] map with entries having the keys obtained by applying the [transform] function to + * each entry in this map and the values of this map, resolving conflicts with [resolve] function and returns the + * [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param transform function which transforms each key-value pair to new key. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the [destination]. + */ internal inline fun > Map.mapKeysTo(destination: D, transform: (key: K, value: V) -> L, resolve: (key: L, currentValue: V, newValue: V) -> V): D = entries.associateByTo(destination, { (key, value) -> transform(key, value) }, { it.value }, resolve) -// TODO: Docs +/** + * Populates the given [destination] map with entries having the keys obtained by applying the [transform] function to + * each entry in this map and the values of this map, resolving conflicts with [resolve] function and returns the + * [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param transform function which transforms each key-value pair to new key. + * @param resolve lambda function that resolves merge conflicts which current and new values corresponding to some key. + * @return the [destination]. + */ internal inline fun > Map.mapKeysTo(destination: D, transform: (Map.Entry) -> L, resolve: (currentValue: V, newValue: V) -> V): D = entries.associateByTo(destination, transform, { it.value }, resolve) -// TODO: Docs +/** + * Populates the given [destination] map with entries having the keys obtained by applying the [transform] function to + * each entry in this map and the values of this map, resolving conflicts with [resolve] function and returns the + * [destination]. + * + * All pairs are added and resolved in order of iteration. + * + * @param destination the destination of the generated key-value pairs. + * @param transform function which transforms each key-value pair to new key. + * @param resolve lambda function that resolves merge conflicts which current and new values corresponding to some key. + * @return the [destination]. + */ internal inline fun > Map.mapKeysTo(destination: D, transform: (key: K, value: V) -> L, resolve: (currentValue: V, newValue: V) -> V): D = entries.associateByTo(destination, { (key, value) -> transform(key, value) }, { it.value }, resolve) -// TODO: Docs +/** + * Returns a new map with entries having the keys obtained by applying the [transform] function to each entry in this + * map and the values of this map and resolving conflicts with [resolve] function. + * + * All pairs are added and resolved in order of iteration. + * + * @param transform function which transforms each key-value pair to new key. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the result map. + */ internal inline fun Map.mapKeys(transform: (Map.Entry) -> L, resolve: (key: L, currentValue: V, newValue: V) -> V): Map = mapKeysTo(LinkedHashMap(size), transform, resolve) -// TODO: Docs +/** + * Returns a new map with entries having the keys obtained by applying the [transform] function to each entry in this + * map and the values of this map and resolving conflicts with [resolve] function. + * + * All pairs are added and resolved in order of iteration. + * + * @param transform function which transforms each key-value pair to new key. + * @param resolve lambda function that resolves merge conflicts which receives some key, its current, and new + * corresponding values. + * @return the result map. + */ internal inline fun Map.mapKeys(transform: (key: K, value: V) -> L, resolve: (key: L, currentValue: V, newValue: V) -> V): Map = mapKeysTo(LinkedHashMap(size), transform, resolve) -// TODO: Docs +/** + * Returns a new map with entries having the keys obtained by applying the [transform] function to each entry in this + * map and the values of this map and resolving conflicts with [resolve] function. + * + * All pairs are added and resolved in order of iteration. + * + * @param transform function which transforms each key-value pair to new key. + * @param resolve lambda function that resolves merge conflicts which current and new values corresponding to some key. + * @return the result map. + */ internal inline fun Map.mapKeys(transform: (Map.Entry) -> L, resolve: (currentValue: V, newValue: V) -> V): Map = mapKeysTo(LinkedHashMap(size), transform, resolve) -// TODO: Docs +/** + * Returns a new map with entries having the keys obtained by applying the [transform] function to each entry in this + * map and the values of this map and resolving conflicts with [resolve] function.. + * + * All pairs are added and resolved in order of iteration. + * + * @param transform function which transforms each key-value pair to new key. + * @param resolve lambda function that resolves merge conflicts which current and new values corresponding to some key. + * @return the result map. + */ internal inline fun Map.mapKeys(transform: (key: K, value: V) -> L, resolve: (currentValue: V, newValue: V) -> V): Map = mapKeysTo(LinkedHashMap(size), transform, resolve) \ No newline at end of file