الدالة 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

خريطة من النوع MutableMap تمثل الوجهة التي سيُضَاف الناتج فيها.

keySelector

دالةٌ تطبق على كل عنصر من عناصر المصفوفة أو المجموعة المعطاة، وتعيد المفتاح المقابل لكل محرف.

valueTransform

دالة تطبق على كل عنصر من عناصر المصفوفة أو المجموعة المعطاة، وتعيد القيمة المقابلة لكل محرف.

أمثلة

مثالٌ على استخدام الدالة ()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 مع تمرير ثلاثة معاملات:

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