الدالة text.groupBy()‎ في لغة Kotlin

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

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

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

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>>

في حال استدعاء الدالةgroupBy()‎ على المصفوفات مع تمرير معامل واحد keySelector فإنّها تُجمّع عناصر المصفوفة الأصلية في قاموس.حيث مفاتيحه تعيدها الدالة الممرّرة 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>>

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

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 في حال تمريرها).

أمثلة

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

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

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 مع المصفوفات مع تمرير مُعاملين

تعرف الشيفرة الآتية مصفوفة باسم array مكونة من ست سلاسل نصية باستخدام الدالة ()arrayOf، ثم تستخدم الدالة ()groupBy على 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 في حال تمريرها). 

مصادر

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