الدالة associateBy()‎ في لغة Kotlin

تعيد الدالة associateBy()‎ خريطةً (map) تحتوي على عناصر المصفوفة أو المجموعة (Collection) المعطاة مفهرسةً بقيمة المفتاح المعاد من تمرير تلك العناصر إلى الدالة valueTransform.

إن كان لعنصرين نفس المفتاح (key) بعد تطبيق الدالة keySelector، فإنَّ الأخير هو الذي سيُضاف إلى الخريطة.

تحافظ الخريطة المُعادة على نفس ترتيب التكرار الخاص بالمصفوفة أو المجموعة الأصليَّة.

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

إن استدعيت الدالة associateBy()‎مع مصفوفة، فستعيد خريطةً (map) تحتوي على عناصر المصفوفة مُفهرسة بناتج تمرير هذه العناصر إلى الدالة keySelector:

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

إن استدعيت الدالة associateBy()‎مع مصفوفة، فستعيد خريطةً (map) تحتوي على عناصر المصفوفة مُفهرسة بناتج تمرير هذه العناصر إلى الدالة keySelector:

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

إن استدعيت الدالة associateBy()‎ مع مجموعة (Collection)، فستعيد خريطةً (map) تحتوي على عناصر المجموعة مُفهرسة بالناتج المعاد من تمرير هذه العناصر إلى الدالة keySelector:

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

إن استدعيت الدالة associateBy()‎ مع مجموعة (Collection)، فستعيد خريطةً (map) تحتوي على عناصر المجموعة مُفهرسة بالناتج المعاد من تمرير هذه العناصر إلى الدالة keySelector:

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

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

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

خريطةً (map) تحتوي على عناصر المصفوفة أو المجموعة المعطاة مُفهرسة بناتج تمرير هذه العناصر إلى الدالة keySelector.

أمثلة

استخدام الدالة ()associateBy مع القوائم بتمرير دالة واحدة

تعرف الشيفرة الآتية قائمة باسم list مكونة من ثلاثة أحرف باستخدام الدالة ()listOf، ثمَّ تنشئ خريطةً باسم map بتمرير الدالة ()upper (التي تحول الحروف إلى الحالة الكبيرة [UpperCase]) إلى()associateBy ثم تطبع الناتج:

fun main(args: Array<String>) {
    val list = listOf('a','b','c')
    val upper: (Char) -> Char = {it.toUpperCase()}
    val map = list.associateBy(upper)
    println(map) // {A=a, B=b, C=c}
}

استخدام الدالة ()associateBy مع القوائم بتمرير دالتين

تعرِّف الشيفرة الآتية قائمة باسم list مكوَّنة من ثلاثة أحرف باستخدام الدالة ()listOf ثم تنشئ خريطةً باسم map بتمرير الدالة ()upper (التي تحول الحروف إلى الحالة الكبيرة [UpperCase]) إلى ()associateBy ثمَّ تطبع الناتج:

fun main(args: Array<String>) {
    val list = listOf('a','b','c')
    val upper: (Char) -> Char = {it.toUpperCase()}
    val mult: (Char) -> Int = {it.toInt()}
    val map = list.associateBy(upper, mult)
    println(map) // {A=97, B=98, C=99}
}

انظر أيضًا

• الدالة associate()‎: تعيد خريطةً (map) تحوي أزواجًا من "مفتاح/قيمة" ناتجة عن تمرير عناصر المصفوفة أو المجموعة (Collection) إلى الدالة transform.
• الدالة asList()‎: تعيد لائحة والتي تُغلّف المصفوفة الاصلية.

• الدالة asIterable()‎: تُنشئ نسخة تكرارية (Iterable instance) والتي تُغلّف المصفوفة الاصلية وتعيد عناصرها عندما تُستخدم في حلقات التكرار (مثلfor).

مصادر

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