Kotlin/collections/groupBy

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

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

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

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

inline fun <T, K> Array<out T>.groupBy(
    keySelector: (T) -> K
): Map<K, List<T>>
inline fun <K> ByteArray.groupBy(
    keySelector: (Byte) -> K
): Map<K, List<Byte>> 
inline fun <K> ShortArray.groupBy(
    keySelector: (Short) -> K
): Map<K, List<Short>> 
inline fun <K> IntArray.groupBy(
    keySelector: (Int) -> K
): Map<K, List<Int>> 
inline fun <K> LongArray.groupBy(
    keySelector: (Long) -> K
): Map<K, List<Long>> 
inline fun <K> FloatArray.groupBy(
    keySelector: (Float) -> K
): Map<K, List<Float>> 
inline fun <K> DoubleArray.groupBy(
    keySelector: (Double) -> K
): Map<K, List<Double>> 
inline fun <K> BooleanArray.groupBy(
    keySelector: (Boolean) -> K
): Map<K, List<Boolean>> 
inline fun <K> CharArray.groupBy(
    keySelector: (Char) -> K
): Map<K, List<Char>> 

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

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

inline fun <T, K, V> Array<out T>.groupBy(
    keySelector: (T) -> K, 
    valueTransform: (T) -> V
): Map<K, List<V>> 
inline fun <K, V> ByteArray.groupBy(
    keySelector: (Byte) -> K, 
    valueTransform: (Byte) -> V
): Map<K, List<V>> 
inline fun <K, V> ShortArray.groupBy(
    keySelector: (Short) -> K, 
    valueTransform: (Short) -> V
): Map<K, List<V>> 
inline fun <K, V> IntArray.groupBy(
    keySelector: (Int) -> K, 
    valueTransform: (Int) -> V
): Map<K, List<V>> 
inline fun <K, V> LongArray.groupBy(
    keySelector: (Long) -> K, 
    valueTransform: (Long) -> V
): Map<K, List<V>> 
inline fun <K, V> FloatArray.groupBy(
    keySelector: (Float) -> K, 
    valueTransform: (Float) -> V
): Map<K, List<V>> 
inline fun <K, V> DoubleArray.groupBy(
    keySelector: (Double) -> K, 
    valueTransform: (Double) -> V
): Map<K, List<V>> 
inline fun <K, V> BooleanArray.groupBy(
    keySelector: (Boolean) -> K, 
    valueTransform: (Boolean) -> V
): Map<K, List<V>> 
inline fun <K, V> CharArray.groupBy(
    keySelector: (Char) -> K, 
    valueTransform: (Char) -> V
): Map<K, List<V>> 

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

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

المعاملات

keySelector

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

valueTransform

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

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

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

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

أمثلة

استخدام الدالة ()groupBy مع تمرير معامل واحد

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

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

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

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

تعرف الشيفرة الآتية قائمة باسم nameToTeam باستخدام الدالة ()listOf، ثم تستخدم الدالة ()groupBy لتجميع عناصر تلك القائمة بحسب اسم ووظيفة كل شخص كما موضح:

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

انظر أيضًا

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

مصادر

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