الدالة groupByTo()‎ في لغة Kotlin

تعيد الدالةgroupByTo()‎ قاموسًا يُجمّع عناصر المصفوفة أو المجموعة التي استُدعيت عبرها حيث مفاتيحه تعيدها الدالة المُمرّرة keySelector وقيمه لوائحُ تضم عناصر المصفوفة أو المجموعة (أو ناتج تمرير عناصر المصفوفة أو المجموعة على الدالة valueTransform في حال تمريرها).

القاموس المُعاد يحافظ على على ترتيب التكرار (entry iteration order) للمفاتيح الناتجة عن المصفوفة أو المجموعة الأصلية.

البنية العامة

inline fun <T, K, M : MutableMap<in K, MutableList<T>>> Array<out T>.groupByTo(
    destination: M, 
    keySelector: (T) -> K
): M 
inline fun <K, M : MutableMap<in K, MutableList<Byte>>> ByteArray.groupByTo(
    destination: M, 
    keySelector: (Byte) -> K
): M 
inline fun <K, M : MutableMap<in K, MutableList<Short>>> ShortArray.groupByTo(
    destination: M, 
    keySelector: (Short) -> K
): M 
inline fun <K, M : MutableMap<in K, MutableList<Int>>> IntArray.groupByTo(
    destination: M, 
    keySelector: (Int) -> K
): M 
inline fun <K, M : MutableMap<in K, MutableList<Long>>> LongArray.groupByTo(
    destination: M, 
    keySelector: (Long) -> K
): M 
inline fun <K, M : MutableMap<in K, MutableList<Float>>> FloatArray.groupByTo(
    destination: M, 
    keySelector: (Float) -> K
): M 
inline fun <K, M : MutableMap<in K, MutableList<Double>>> DoubleArray.groupByTo(
    destination: M, 
    keySelector: (Double) -> K
): M 
inline fun <K, M : MutableMap<in K, MutableList<Boolean>>> BooleanArray.groupByTo(
    destination: M, 
    keySelector: (Boolean) -> K
): M 
inline fun <K, M : MutableMap<in K, MutableList<Char>>> CharArray.groupByTo(
    destination: M, 
    keySelector: (Char) -> K
): M

في حال استدعاء الدالةgroupBy()‎ على المصفوفات مع تمرير معاملين destination وkeySelector فإنّها تُجمّع عناصر المصفوفة الأصلية وتضيفها إلى القاموس.المُمرّر destination حيث مفاتيحه تعيدها الدالة الممرّرة keySelector()‎ مُطبّقة على كل عناصر المصفوفة وقيمه لوائح تضم العناصر المقابلة. ثم تعيد القاموسdestination:

inline fun <T, K, V, M : MutableMap<in K, MutableList<V>>> Array<out T>.groupByTo(
    destination: M, 
    keySelector: (T) -> K, 
    valueTransform: (T) -> V
): M 
inline fun <K, V, M : MutableMap<in K, MutableList<V>>> ByteArray.groupByTo(
    destination: M, 
    keySelector: (Byte) -> K, 
    valueTransform: (Byte) -> V
): M
inline fun <K, V, M : MutableMap<in K, MutableList<V>>> ShortArray.groupByTo(
    destination: M, 
    keySelector: (Short) -> K, 
    valueTransform: (Short) -> V
): M 
inline fun <K, V, M : MutableMap<in K, MutableList<V>>> IntArray.groupByTo(
    destination: M, 
    keySelector: (Int) -> K, 
    valueTransform: (Int) -> V
): M 
inline fun <K, V, M : MutableMap<in K, MutableList<V>>> LongArray.groupByTo(
    destination: M, 
    keySelector: (Long) -> K, 
    valueTransform: (Long) -> V
): M 
inline fun <K, V, M : MutableMap<in K, MutableList<V>>> FloatArray.groupByTo(
    destination: M, 
    keySelector: (Float) -> K, 
    valueTransform: (Float) -> V
): M 
inline fun <K, V, M : MutableMap<in K, MutableList<V>>> DoubleArray.groupByTo(
    destination: M, 
    keySelector: (Double) -> K, 
    valueTransform: (Double) -> V
): M 
inline fun <K, V, M : MutableMap<in K, MutableList<V>>> BooleanArray.groupByTo(
    destination: M, 
    keySelector: (Boolean) -> K, 
    valueTransform: (Boolean) -> V
): M 
inline fun <K, V, M : MutableMap<in K, MutableList<V>>> CharArray.groupByTo(
    destination: M, 
    keySelector: (Char) -> K, 
    valueTransform: (Char) -> V
): M

في حال استدعاء الدالةgroupBy()‎ على المصفوفات مع تمرير ثلاث معاملات destination و valueTransform و keySelector فإنّها تُجمّع العناصر المعادة من قبل الدالة valueTransform()‎ مُطبّقة على كل عناصر المصفوفة وتربطها بالمفتاح الذي تعيده الدالةkeySelector()‎ مطبقة على على عناصر المصفوفة وتضيفها إلى القاموس المُمرّر destination حيث كل مفتاح مرتبط بلائحة العناصر المقابلة. ثم تعيد القاموس destination:

inline fun <T, K> Iterable<T>.groupBy(
    keySelector: (T) -> K
): Map<K, List<T>>

في حال استدعاء الدالةgroupBy()‎ على المجموعات مع تمرير معامل واحد keySelector فإنّها تُجمّع عناصر المصفوفة الأصلية في قاموس.حيث مفاتيحه تعيدها الدالة الممرّرة keySelector()‎ مُطبّقة على كل عناصر المصفوفة وقيمه لائحة تضم العناصر المقابلة.

inline fun <T, K, V> Iterable<T>.groupBy(
    keySelector: (T) -> K, 
    valueTransform: (T) -> V
): Map<K, List<V>>

في حال استدعاء الدالةgroupBy()‎ على المجموعات مع تمرير معاملين valueTransform و keySelector فإنّها تُجمّع العناصر المعادة من قبل الدالة valueTransform()‎ مُطبّقة على كل عناصر المصفوفة وتربطها بالمفتاح الذي تعيده الدالةkeySelector()‎ مطبقة على على عناصر المجموعة وتعيد قاموسًا حيث كل مفتاح مرتبط بلائحة العناصر المقابلة.

يُلاحَظ وجود الكلمة المفتاحية inline للدلالة على أن هذه الدالة مباشرة، وللمزيد من التفاصيل راجع توثيق الدوال المباشرة (inline functions).

القيم المٌعادة

قاموس يُجمّع عناصر المصفوفة أو المجموعة التي استُدعيت عبرها حيث مفاتيحه تعيدها الدالة المُمرّرة keySelector وقيمه لوائحُ تضم عناصر المصفوفة أو المجموعة (أو ناتج تمرير عناصر المصفوفة أو المجموعة على الدالة valueTransform في حال تمريرها).

أمثلة

استخدام الدالة ()groupByTo مع المصفوفات مع تمرير معامل واحد

تعرف الشيفرة الآتية مصفوفة باسم array مكونة من ست سلاسل نصية باستخدام الدالة ()arrayOf، ثم تستخدم الدالة ()groupByTo على array بتمرير الدالة التي تعيد طول السلسلة النصية المُمرّرة، وتجمّع عناصر array التي لها نفس الطول في قاموس، ثم تطبع القاموس:

fun main(args: Array<String>) {
val array = arrayOf("a", "abc", "ab", "def","avde" ,"abcd")
val map: MutableMap<Int, MutableList<String>> = mutableMapOf() // انشاء قاموس فارغ

print(array.groupByTo ( map, { it.length })) // {1=[a], 3=[abc, def], 2=[ab], 4=[avde, abcd]}
}

استخدام الدالة ()groupByTo مع المصفوفات مع تمرير مُعاملين

تعرف الشيفرة الآتية مصفوفة باسم array مكونة من ست سلاسل نصية باستخدام الدالة ()arrayOf، ثم تستخدم الدالة ()groupByTo على array بتمرير دالة تعيد طول السلسلة النصية المُمرّرة ودالة تعيد المصفوفة بالحروف الكبيرة، وتجمّع عناصر array التي لها نفس الطول في قاموس بتحويلها إلى الحروف الكبيرة، ثم تطبع القاموس:

fun main(args: Array<String>) {
    val array = arrayOf("a", "abc", "ab", "def","avde" ,"abcd")

    print(array.groupBy( { it.length }, {it.toUpperCase()} )) // {1=[A], 3=[ABC, DEF], 2=[AB], 
                                                              // 4=[AVDE, ABCD]}
}

انظر أيضًا

groupByTo()‎: تضيف إلى القاموس المُمرّر عناصر المصفوفة أو المجموعة التي استُدعيت عبرها حيث مفاتيحه تعيدها الدالة المُمرّرة keySelector وقيمه لوائحُ تضم عناصر المصفوفة أو المجموعة (أو ناتج تمرير عناصر المصفوفة أو المجموعة على الدالة valueTransform في حال تمريرها). 

مصادر

الدالة groupByTo()‎ في التوثيق الرسمي للمكتبة القياسية في لغة Kotlin