From 4f61f89eb776330730c72b0d599631c02068435c Mon Sep 17 00:00:00 2001
From: Andrew <andrewgallasch@gmail.com>
Date: Fri, 7 Jun 2024 00:25:58 +0930
Subject: [PATCH] Comment group and associate functions

---
 .../org/session/libsession/utilities/Util.kt  | 49 ++++++++++++++-----
 1 file changed, 36 insertions(+), 13 deletions(-)

diff --git a/libsession/src/main/java/org/session/libsession/utilities/Util.kt b/libsession/src/main/java/org/session/libsession/utilities/Util.kt
index cc13142220..6e254b9fab 100644
--- a/libsession/src/main/java/org/session/libsession/utilities/Util.kt
+++ b/libsession/src/main/java/org/session/libsession/utilities/Util.kt
@@ -22,6 +22,7 @@ import java.util.concurrent.CountDownLatch
 import java.util.concurrent.ExecutorService
 import java.util.concurrent.ThreadPoolExecutor
 import java.util.concurrent.TimeUnit
+import kotlin.collections.LinkedHashMap
 import kotlin.math.min
 
 object Util {
@@ -369,23 +370,45 @@ object Util {
 
 fun <T, R> T.runIf(condition: Boolean, block: T.() -> R): R where T: R = if (condition) block() else this
 
+/**
+ * Returns a [Map] containing the elements from the given array indexed by the key
+ * returned from [keySelector] function applied to each element.
+ *
+ * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ *
+ * If any element is null or the key is null, it will not be added to the [Map].
+ *
+ * @see associateBy
+ */
 fun <T, K: Any> Iterable<T>.associateByNotNull(
     keySelector: (T) -> K?
 ) = associateByNotNull(keySelector) { it }
 
-fun <T, K: Any, V: Any> Iterable<T>.associateByNotNull(
-    keySelector: (T) -> K?,
-    valueTransform: (T) -> V?,
-): Map<K, V> = buildMap {
-    for (item in this@associateByNotNull) {
-        val key = keySelector(item) ?: continue
-        val value = valueTransform(item) ?: continue
-        this[key] = value
-    }
+/**
+ * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector]
+ * functions applied to elements of the given collection.
+ *
+ * If any two elements would have the same key returned by [keySelector] the last one gets added to
+ * the map.
+ *
+ * If any element produces a null key or value it will not be added to the [Map].
+ *
+ * @see associateBy
+ */
+fun <E, K: Any, V: Any> Iterable<E>.associateByNotNull(
+    keySelector: (E) -> K?,
+    valueTransform: (E) -> V?,
+): Map<K, V> = mutableMapOf<K, V>().also {
+    for(e in this) { it[keySelector(e) ?: continue] = valueTransform(e) ?: continue }
 }
 
-inline fun <T, K> Iterable<T>.groupByNotNull(keySelector: (T) -> K?): Map<K, List<T>> {
-    val map = mutableMapOf<K, MutableList<T>>()
-    forEach { e -> keySelector(e)?.let { k -> map.getOrPut(k) { mutableListOf() }.add(e) } }
-    return map
+/**
+ * Groups elements of the original collection by the key returned by the given [keySelector] function
+ * applied to each element and returns a map where each group key is associated with a list of
+ * corresponding elements, omitting elements with a null key.
+ *
+ * @see groupBy
+ */
+inline fun <E, K> Iterable<E>.groupByNotNull(keySelector: (E) -> K?): Map<K, List<E>> = LinkedHashMap<K, MutableList<E>>().also {
+    forEach { e -> keySelector(e)?.let { k -> it.getOrPut(k) { mutableListOf() } += e } }
 }