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

تعيد الدالة associateTo()‎ خريطةً متغيرةً (mutable map) تحتوي على أزواج من "قيمة/مفتاح"، إذ القيمة هي عناصر المصفوفة أو المجموعة (Collection) المعطاة، والمفتاح هو الناتج المعاد من تمرير تلك العناصر إلى الدالة transform.

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

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

إن استدعيت الدالة associateTo()‎ مع مصفوفة، فستعيد الخريطة المتغيرة destination التي تحتوي على أزواج من "قيمة/مفتاح"، إذ القيمة هي عناصر تلك المصفوفة المعطاة، والمفتاح هو الناتج المعاد من تمرير هذه العناصر إلى الدالة transform:

inline fun <T, K, V, M : MutableMap<in K, in V>> Array<out T>.associateTo(
    destination: M, 
    transform: (T) -> Pair<K, V>
): M 
inline fun <K, V, M : MutableMap<in K, in V>> ByteArray.associateTo(
    destination: M, 
    transform: (Byte) -> Pair<K, V>
): M 
inline fun <K, V, M : MutableMap<in K, in V>> ShortArray.associateTo(
    destination: M, 
    transform: (Short) -> Pair<K, V>
): M 
inline fun <K, V, M : MutableMap<in K, in V>> IntArray.associateTo(
    destination: M, 
    transform: (Int) -> Pair<K, V>
): M 
inline fun <K, V, M : MutableMap<in K, in V>> LongArray.associateTo(
    destination: M, 
    transform: (Long) -> Pair<K, V>
): M 
inline fun <K, V, M : MutableMap<in K, in V>> FloatArray.associateTo(
    destination: M, 
    transform: (Float) -> Pair<K, V>
): M 
inline fun <K, V, M : MutableMap<in K, in V>> DoubleArray.associateTo(
    destination: M, 
    transform: (Double) -> Pair<K, V>
): M 
inline fun <K, V, M : MutableMap<in K, in V>> BooleanArray.associateTo(
    destination: M, 
    transform: (Boolean) -> Pair<K, V>
): M 
inline fun <K, V, M : MutableMap<in K, in V>> CharArray.associateTo(
    destination: M, 
    transform: (Char) -> Pair<K, V>
): M

إن استدعيت الدالة associateTo()‎ مع مجموعة، فستعيد الخريطة المتغيرة destination التي تحتوي على أزواج من "قيمة/مفتاح"، إذ القيمة هي عناصر تلك المجموعة المعطاة، والمفتاح هو الناتج المعاد من تمرير هذه العناصر إلى الدالة transform:

inline fun <T, K, V, M : MutableMap<in K, in V>> Iterable<T>.associateTo(
    destination: M, 
    transform: (T) -> Pair<K, V>
): M

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

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

خريطةً متغيرةً (mutable map) تحتوي على أزواج من "قيمة/مفتاح"، إذ القيمة هي عناصر المصفوفة أو المجموعة (Collection) المعطاة، والمفتاح هو الناتج المعاد من تمرير تلك العناصر إلى الدالة transform.

أمثلة

استخدام الدالة ()associateTo مع القوائم

تعرِّف الشيفرة الآتية قائمة باسم list مكونة من أربعة أعداد باستخدام الدالة ()listOf، ثم تنشئ خريطةً متغيرةً باسم map بتمرير الدالة ()func (التي تحول عددًا إلى زوج) إلى ()associateTo ثم تطبع الناتج بعدئذٍ:

fun main(args: Array<String>) {
    val list = listOf(1, 2, 3, 4)
    val map = mutableMapOf<Int, Int>()
    val func: (Int) -> Pair<Int, Int> = {
        Pair(it + 10, it * 4)
    }
    list.associateTo(map, func)

    println(map) // {11=4, 12=8, 13=12, 14=16}
}

انظر أيضًا

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

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

مصادر

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