الدالة CharSequence.associateByTo()‎ في Kotlin

تشبه الدالة associateByTo()‎ الدالة associateBy()‎ تمامًا باستثناء أنها تضيف الناتج الذي تعيده إلى خريطة موجودة مسبقًا.

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

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

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

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

المعاملات

destination

خريطة متغيرة تمثل الوجهة التي ستوضع فيها الخرائط التي تعيدها الدالة associateByTo()‎.

keySelector

دالةٌ يمرر إليها كل محرف من محارف سلسلة المحارف المعطاة على حدة وتعيد المفتاح المقابل لذلك المحرف المراد وضعه في الخريطة.

valueTransform

دالةٌ يمرر إليها كل محرف من محارف سلسلة المحارف المعطاة على حدة وتعيد القيمة المقابلة لذلك المحرف المراد وضعها في الخريطة.

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

تعاد الخريطة destination بعد إضافة الخرائط التي تنشأ من الأزواج "مفتاح/قيمة" إليها، إذ يكون المفتاح (key) هو الناتج الذي تعيده الدالة keySelector وتكون القيمة (value) المقابلة لذلك المفتاح هي إمَّا محارف سلسلة المحارف المعطاة أو الناتج الذي تعيده الدالة valueTransform.

أمثلة

استعمال ()associateByTo مع تمرير المعامل keySelector فقط:

fun main(args: Array<String>) {
    val str = "hsoub"
    val map = mutableMapOf<Char, Char>()
    val Key: (Char) -> Char = { it.toUpperCase() }

    str.associateByTo(map, Key)
    println(map) // {H=h, S=s, O=o, U=u, B=b}
}

استعمال الدالة ()associateByTo مع تمرير المعامل keySelector والمعامل valueTransform:

fun main(args: Array<String>) {
    val str = "hsoub ACADEMY"
    val map = mutableMapOf<Char, Int>()

    val Key: (Char) -> Char = { it.toUpperCase() }
    val Val: (Char) -> Int = { it.toInt() }

    str.associateByTo(map, Key, Val)

    println(map) // {H=104, S=115, O=111, U=117, B=98,  =32, A=65, C=67, D=68, E=69, M=77, Y=89}
}

انظر أيضًا

• الدالة associateBy()‎: تعيد خريطةً (map) مكونة من الأزواج "مفتاح/قيمة"، إذ يكون المفتاح (key) هو الناتج الذي تعيده الدالة keySelector الممررة إليها وتكون القيمة (value) المقابلة لذلك المفتاح هي إمَّا محارف سلسلة المحارف المعطاة أو الناتج الذي تعيده الدالة valueTransform الممررة. 
• الدالة associate()‎: تعيد خريطة (map) تحوي أزواجًا من "مفتاح/قيمة" ناتجة عن تمرير محارف سلسلة المحارف التي استُدعيت معها إلى الدالة الممررة إليها. 
• الدالة associateTo()‎: تشبه الدالة associate()‎ تمامًا باستثناء أنها تضيف الناتج الذي تعيده إلى خريطة موجودة مسبقًا.  

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

مصادر

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