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

تشبه الدالة groupByTo()‎ الدالة groupBy()‎ في جميع النواحي باستثناء أنَّها تضيف الناتج المعاد إلى المعامل الممرَّر إليها.

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

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

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 

inline fun <T, K, M : MutableMap<in K, MutableList<T>>> Iterable<T>.groupByTo(
    destination: M, 
    keySelector: (T) -> K
): M

أمَّا إن مرِّر إلى الدالة groupBy()‎ المعاملات destination و valueTransform و keySelector، فستُجمّع عناصر المصفوفة أو المجموعة المعطاة بحسب القيم التي تعيدها الدالة valueTransform()‎ المطبقة على كل عنصر من تلك العناصر وبحسب المفتاح الذي تعيده الدالة 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 

inline fun <T, K, V, M : MutableMap<in K, MutableList<V>>> Iterable<T>.groupByTo(
    destination: M, 
    keySelector: (T) -> K, 
    valueTransform: (T) -> V
): M (source)

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

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

يُعاد المعامل destination المعطى بعد إضافة الخريطة الناتجة عن تجميع عناصر المصفوفة أو المجموعة المعطاة في مجموعاتٍ مفتاحُ كلِّ واحدةٍ منها مرتبطٌ بقائمة من العناصر المقابلة.

أمثلة

استخدام الدالة ()groupByTo مع تمرير معاملين

تنشئ الشيفرة الآتية مصفوفة باسم array باستخدام الدالة ()arrayOf، وخريطة فارغة باسم map باستخدام الدالة ()mutableMapOf ثم تستخدم الدالة ()groupByTo لتجميع عناصر تلك المصفوفة بحسب طول (عدد محارف) كل عنصر:

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

    array.groupByTo(map) { it.length }

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

استخدام الدالة ()groupByTo مع تمرير ثلاثة معاملات

تنشئ الشيفرة الآتية قائمة باسم nameToTeam باستخدام الدالة ()listOf ثمَّ تستعمل الدالة ()groupByTo لتجميع عناصر تلك القائمة بحسب اسم ووظيفة كل شخص وإضافتة الناتج إلى الخريطة المنشأة آنذاك:

fun main(args: Array<String>) {
    val nameToTeam = listOf("جميل" to "تسويق", ‎"أحمد" to "مبيعات", ‎"محمد" to "تسويق")
    val namesByTeam = nameToTeam.groupBy({ it.second }, { it.first })
    println(namesByTeam) // {تسويق=[جميل, محمد], مبيعات=[أحمد]}

    val mutableNamesByTeam = nameToTeam.groupByTo(HashMap(), { it.second }, { it.first })
    // تضيف الناتج groupByTo نجد استعمال الدالتين يعطي نفس النتجية باستثناء أن الدالة  
    // mutable map إلى خريطة متغيرة 
    println("${mutableNamesByTeam == namesByTeam}") // true
}

انظر أيضًا

• الدالة groupBy()‎: تجمِّع عناصر المصفوفة أو المجموعة التي استُدعيت معها في مجموعات، إذ تطبق دالة محدَّدة على كل عنصر ثمَّ تعاد خريطة تحوي مجموعاتٍ مفتاحُ كلِّ واحدةٍ منها مرتبطٌ بقائمة من العناصر المقابلة.
• الدالة groupingBy()‎: تُنشئ موردًا (source) من النوع Grouping من المصفوفة أو المجموعة التي استُدعيت معها لاستخدامه لاحقًا مع عمليات التجميع (group-and-fold operations) وذلك باستخدام دالة معيَّنة لاستخلاص مفتاح من كل عنصر.
• الدالة foldRight()‎: تجمع بشكل تراكمي ناتج تطبيق عملية معيَّنة على قيمة كل عنصر من عناصر المصفوفة أو المجموعة (بدءًا من اليمين إلى اليسار) المستدعاة معها والقيمة التراكمية الحالية بالإضافة إلى القيمة الأولية إن أعطيت. 
• الدالة foldRightIndexed()‎: تجمع ناتج تطبيق عملية معينة على قيمة كل عنصر من عناصر المصفوفة أو المجموعة (بدءًا من اليمين إلى اليسار) المستدعاة معها وفهرس ذلك العنصر بشكل تراكمي بالإضافة إلى القيمة الأولية إن أعطيت.  

مصادر

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