الفرق بين المراجعتين لصفحة: «Kotlin/collections/groupBy»

المراجعة الحالية بتاريخ 08:12، 8 سبتمبر 2018

تجمِّع الدالة 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

@@ سطر 1: / سطر 1: @@
-<noinclude>{{DISPLAYTITLE: الدالة <code>groupBy()‎</code> في لغة Kotlin}}</noinclude>
+تجمِّع الدالة <code>groupBy()‎</code> عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت معها في مجموعات، إذ تطبق دالة محدَّدة على كل عنصر ثمَّ تعاد خريطة تحوي مجموعاتٍ مفتاحُ كلِّ واحدةٍ منها مرتبطٌ بقائمة من العناصر المقابلة.
-تُراكِم الدالة<code>groupBy()‎</code> القيم بدءًا من القيمة المُمرّرة <code>initial</code> وتطبّق العملية <code>operation</code> من اليسار إلى اليمين على القيمة المُتراكمة الراهنة وعلى العنصر التالي من [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت عبرها وكذلك فهرسه. وتُعيد القيمة النهائية.
+تحافظ الخريطة المُعادة على على ترتيب التكرار (entry iteration order) للمفاتيح الناتجة عن [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] الأصلية.
 ==البنية العامة==
-يمكن استدعاء الدالة<code>foldIndexed()‎</code> على [[Kotlin/Array|المصفوفات]].<syntaxhighlight lang="kotlin">
+إن مُرِّر إلى الدالة <code>groupBy()‎</code> المعامل <code>keySelector</code> فقط، فستُجمّع عناصر [[Kotlin/Array|المصفوفة]] أو المجموعة المعطاة بحسب المفتاح الذي تعيده الدالة <code>keySelector()‎</code> المطبقة على كل عنصر من تلك العناصر ثمَّ تعاد خريطة تحوي مجموعاتٍ مفتاحُ كلِّ واحدةٍ منها مرتبطٌ بقائمة من العناصر المقابلة.<syntaxhighlight lang="kotlin">
-inline fun <T, R> Array<out T>.foldIndexed(
+inline fun <T, K> Array<out T>.groupBy(
-     initial: R,
+     keySelector: (T) -> K
-     operation: (index: Int, acc: R, T) -> R
+): Map<K, List<T>>
-): R
+inline fun <K> ByteArray.groupBy(
-inline fun <R> ByteArray.foldIndexed(
+     keySelector: (Byte) -> K
-     initial: R,
+): Map<K, List<Byte>>
-     operation: (index: Int, acc: R, Byte) -> R
+inline fun <K> ShortArray.groupBy(
-): R
+    keySelector: (Short) -> K
-inline fun <R> ShortArray.foldIndexed(
+): Map<K, List<Short>>
-     initial: R,
+inline fun <K> IntArray.groupBy(
-     operation: (index: Int, acc: R, Short) -> R
+    keySelector: (Int) -> K
-): R
+): Map<K, List<Int>>
-inline fun <R> IntArray.foldIndexed(
+inline fun <K> LongArray.groupBy(
-     initial: R,
+     keySelector: (Long) -> K
-     operation: (index: Int, acc: R, Int) -> R
+): Map<K, List<Long>>
-): R
+inline fun <K> FloatArray.groupBy(
-inline fun <R> LongArray.foldIndexed(
+     keySelector: (Float) -> K
-     initial: R,
+): Map<K, List<Float>>
-     operation: (index: Int, acc: R, Long) -> R
+inline fun <K> DoubleArray.groupBy(
-): R
+    keySelector: (Double) -> K
-inline fun <R> FloatArray.foldIndexed(
+): Map<K, List<Double>>
-     initial: R,
+inline fun <K> BooleanArray.groupBy(
-     operation: (index: Int, acc: R, Float) -> R
+    keySelector: (Boolean) -> K
-): R
+): Map<K, List<Boolean>>
-inline fun <R> DoubleArray.foldIndexed(
+inline fun <K> CharArray.groupBy(
-     initial: R,
+     keySelector: (Char) -> K
-     operation: (index: Int, acc: R, Double) -> R
+): Map<K, List<Char>>
-): R
-inline fun <R> BooleanArray.foldIndexed(
+inline fun <T, K> Iterable<T>.groupBy(
-     initial: R,
+     keySelector: (T) -> K
-     operation: (index: Int, acc: R, Boolean) -> R
+): Map<K, List<T>>
-): R
+</syntaxhighlight>أمَّا إن مرِّر إلى الدالة <code>groupBy()‎</code> المعاملين <code>valueTransform</code> و <code>keySelector</code>، فستُجمّع عناصر المصفوفة أو المجموعة المعطاة بحسب القيم التي تعيدها الدالة <code>valueTransform()‎</code> المطبقة على كل عنصر من تلك العناصر وبحسب المفتاح الذي تعيده الدالة <code>keySelector()‎</code> المطبقة على العنصر ثمَّ تعاد خريطة تحوي مجموعاتٍ مفتاحُ كلِّ واحدةٍ منها مرتبطٌ بقائمة من العناصر المقابلة.<syntaxhighlight lang="kotlin">
-inline fun <R> CharArray.foldIndexed(
+inline fun <T, K, V> Array<out T>.groupBy(
-     initial: R,
+    keySelector: (T) -> K,
-     operation: (index: Int, acc: R, Char) -> R
+    valueTransform: (T) -> V
-): R
+): 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>>
+</syntaxhighlight>وجود الكلمة المفتاحية <code>inline</code> يدل على أنَّ هذه الدالة مباشرة (للمزيد من التفاصيل، راجع صفحة <nowiki/>[[Kotlin/inline functions|الدوال المباشرة (inline functions)]]).
+== المعاملات ==
-</syntaxhighlight>يمكن استدعاء غلدالة<code>foldIndexed()‎</code> على [[Kotlin/collections|المجموعات]].<syntaxhighlight lang="kotlin">
+=== <code>keySelector</code> ===
-inline fun <T, R> Iterable<T>.foldIndexed(
+دالةٌ تطبق على كل محرف من محارف السلسلة المعطاة، وتعيد المفتاح المقابل لكل محرف.
-    initial: R,
-    operation: (index: Int, acc: R, T) -> R
+=== <code>valueTransform</code> ===
-): R
+دالة تطبق على كل عنصر من عناصر المصفوفة أو المجموعة المعطاة، وتعيد القيمة المقابلة لكل محرف.
-</syntaxhighlight>يُلاحَظ وجود الكلمة المفتاحية <code>inline</code> للدلالة على أن هذه الدالة مباشرة، وللمزيد من التفاصيل راجع <nowiki/>[[Kotlin/inline functions|توثيق الدوال المباشرة (inline functions)]].
-==القيم المٌعادة==
+==القيم المعادة==
-ناتج تطبيق العملية المُمرّرة <code>operation</code> تراكميًا على عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت عبرها وكذلك فهارسها.
+إن مُرِّر إلى الدالة <code>groupBy()‎</code> المعامل <code>keySelector</code> فقط، فستُجمّع عناصر [[Kotlin/Array|المصفوفة]] أو المجموعة المعطاة بحسب المفتاح الذي تعيده الدالة <code>keySelector()‎</code> المطبقة على كل عنصر من تلك العناصر ثمَّ تعاد خريطة تحوي مجموعاتٍ مفتاحُ كلِّ واحدةٍ منها مرتبطٌ بقائمة من العناصر المقابلة.
+أمَّا إن مرِّر إلى الدالة <code>groupBy()‎</code> المعاملين <code>valueTransform</code> و <code>keySelector</code>، فستُجمّع عناصر المصفوفة أو المجموعة المعطاة بحسب القيم التي تعيدها الدالة <code>valueTransform()‎</code> المطبقة على كل عنصر من تلك العناصر وبحسب المفتاح الذي تعيده الدالة <code>keySelector()‎</code> المطبقة على العنصر ثمَّ تعاد خريطة تحوي مجموعاتٍ مفتاحُ كلِّ واحدةٍ منها مرتبطٌ بقائمة من العناصر المقابلة.
 ==أمثلة==
-===استخدام الدالة <code>()groupBy</code> مع المصفوفات===
+===استخدام الدالة <code>()groupBy</code> مع تمرير معامل واحد===
-تعرف الشيفرة الآتية <nowiki/>[[Kotlin/Array|مصفوفة]] باسم <code>array</code> مكونة من ستة أعداد باستخدام الدالة <code>()arrayOf</code>، ثم تستخدم الدالة <code>()foldIndexed</code> على <code>array</code> بتمرير القيمة الأوّلية <code>0</code> إضافة إلى عملية تُضيف القيمة المتراكمة الراهنة إلى حاصل ضرب عناصر <code>array</code> في فهارسها، ثم تطبع الناتج:<syntaxhighlight lang="kotlin">
+تعرف الشيفرة الآتية <nowiki/>[[Kotlin/Array|مصفوفة]] باسم <code>array</code> باستخدام الدالة <code>()arrayOf</code> ثم تستخدم الدالة <code>()groupBy</code> لتجميع عناصر تلك المصفوفة بحسب طول (عدد محارف) كل عنصر:<syntaxhighlight lang="kotlin">
 fun main(args: Array<String>) {
-val array = arrayOf(1,2,3,4,5,6)
+    val array = arrayOf("a", "abc", "ab", "def", "avde", "abcd")
-val acc = array.foldIndexed(0) { acc , element , index -> acc + element*index }
+    print(array.groupBy { it.length }) // {1=[a], 3=[abc, def], 2=[ab], 4=[avde, abcd]}
-print(acc) // 719
+}
+</syntaxhighlight>
+===استخدام الدالة <code>()groupBy</code> مع تمرير مُعاملين===
+تعرف الشيفرة الآتية قائمة باسم <code>nameToTeam</code> باستخدام الدالة <code>()listOf</code>، ثم تستخدم الدالة <code>()groupBy</code> لتجميع عناصر تلك القائمة بحسب اسم ووظيفة كل شخص كما موضح:<syntaxhighlight lang="kotlin">
+fun main(args: Array<String>) {
+    val nameToTeam = listOf("جميل" to "تسويق", ‎"أحمد" to "مبيعات", ‎"محمد" to "تسويق")
+    val namesByTeam = nameToTeam.groupBy({ it.second }, { it.first })
+    println(namesByTeam) // {تسويق=[جميل, محمد], مبيعات=[أحمد]}
 }
 </syntaxhighlight>
 ==انظر أيضًا==
-<code>[[Kotlin/collections/foldRight|foldRight()]]</code>‎:تُراكِم  القيم بدءًا من القيمة المُمرّرة <code>initial</code> وتطبّق العملية <code>operation</code> من اليمين إلى اليسار على القيمة المُتراكمة الراهنة وعلى العنصر التالي من [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت عبرها. وتُعيد القيمة النهائية.
+* الدالة <code>[[Kotlin/collections/groupByTo|groupByTo()]]</code>‎: تشبه هذه الدالة في جميع النواحي باستثناء أنَّها تضيف الناتج المعاد إلى المعامل الممرَّر إليها.
+* الدالة <code>[[Kotlin/collections/groupingBy|groupingBy()‎]]</code>: تُنشئ موردًا (source) من النوع <code>Grouping</code> من [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت معها لاستخدامه لاحقًا مع عمليات التجميع (group-and-fold operations) وذلك باستخدام دالة معيَّنة لاستخلاص مفتاح من كل عنصر.
-<code>[[Kotlin/collections/foldIndexed|foldIndexed()]]</code>‎:تُراكِم  القيم بدءًا من القيمة المُمرّرة <code>initial</code> وتطبّق العملية <code>operation</code> من اليمين إلى اليسار  على القيمة المُتراكمة الراهنة وعلى العنصر التالي من [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت عبرها وكذلك فهرسه. وتُعيد القيمة النهائية.
+* الدالة <code>[[Kotlin/collections/foldIndexed|foldIndexed()]]</code>‎: تجمع ناتج تطبيق عملية معينة على قيمة كل عنصر من عناصر المصفوفة أو المجموعة (بدءًا من اليسار إلى اليمين) المستدعاة معها وفهرس ذلك العنصر بشكل تراكمي بالإضافة إلى القيمة الأولية إن أعطيت.
+* الدالة <code>[[Kotlin/collections/foldRight|foldRight()]]</code>‎: تجمع بشكل تراكمي ناتج تطبيق عملية معيَّنة على قيمة كل عنصر من عناصر المصفوفة أو المجموعة (بدءًا من اليمين إلى اليسار) المستدعاة معها والقيمة التراكمية الحالية بالإضافة إلى القيمة الأولية إن أعطيت.
 ==مصادر==
-*[https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/fold-indexed.html الدالة  groupBy()‎ في التوثيق الرسميّ للمكتبة القياسيّة في لغة Kotlin.]
+*[https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/group-by.html صفحة الدالة groupBy()‎ في التوثيق الرسمي للمكتبة القياسية في لغة Kotlin]<noinclude>{{DISPLAYTITLE: الدالة <code>groupBy()‎</code> في Kotlin}}</noinclude>
 [[تصنيف:Kotlin]]
-[[تصنيف:Kotlin Functions]]
+[[تصنيف:Kotlin Function]]
+[[تصنيف:Kotlin Collection]]