Kotlin/collections/associateByTo

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

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

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

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

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

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

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

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

inline fun <T, K, M : MutableMap<in K, in T>> Iterable<T>.associateByTo(
    destination: M, 
    keySelector: (T) -> K
):

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

inline fun <T, K, V, M : MutableMap<in K, in V>> Iterable<T>.associateByTo(
    destination: M, 
    keySelector: (T) -> K, 
    valueTransform: (T) -> V
): M

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

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

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

أمثلة

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

تعرِّف الشيفرة الآتية قائمة باسم list مكونة من أربعة أعداد باستخدام الدالة ()listOf ثمَّ تنشئ خريطةً متغيرةً باسم map بتمرير الدالة ()func (التي تضرب الأعداد في 4) إلى ()associateByTo ثم تطبع الناتج:

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

    list.associateByTo(map,func)

    println(map) // {4=1, 8=2, 12=3, 16=4}
}

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

تعرف الشيفرة الآتية قائمة باسم list مكونة من ثلاثة أحرف باستخدام الدالة ()listOf ثمَّ تنشئ خريطةً متغيرًةً باسم map بتمرير الدالة ()func (التي تضرب الأعداد في 4) والدالة ()func2 (التي تضيف 4 إلى العدد الممرر إليها) إلى ()associateByTo ثم تطبع الناتج:

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

    list.associateByTo(map, func, func2)
    println(map) // {4=5, 8=6, 12=7, 16=8}
}

انظر أيضًا

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

مصادر

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