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

تعيد الدالة associate()‎ خريطة (map) تحوي أزواجًا من "مفتاح/قيمة" ناتجة عن تمرير محارف سلسلة المحارف التي استُدعيت معها إلى الدالة الممررة إليها.

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

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

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

inline fun <K, V> CharSequence.associate(
    transform: (Char) -> Pair<K, V>
): Map<K, V>

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

المعاملات

transform

دالةٌ يمرر إليها كل محرف من محارف سلسلة المحارف المعطاة وتعيد خريطة تحتوي أزواجًا من "مفتاح/قيمة".

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

تعاد خريطةً تحوي أزواجًا من "مفتاح/قيمة" ناتجة عن تمرير محارف سلسلة المحارف المعطاة إلى الدالة ()transform.

أمثلة

تعرِّف الشيفرة التالية سلسلة من المحارف باسم str ثمَّ تنشأ خريطةً باسم map بتمرير الدالة ()toMap إلى ()associate التي تحول محارف تلك السلسلة إلى زوج مكون من المحرف في الحالة الكبيرة (UpperCase) ومن قيمته العددية المقابلة له:

fun main(args: Array<String>) {
    val str = "hsoub"
    val toMap: (Char) -> Pair<Char, Int> = {
        Pair(it.toUpperCase(), it.toInt())
    }
    val map = str.associate(toMap)

    println(map) // {H=104, S=115, O=111, U=117, B=98}
}

انظر أيضًا

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

مصادر

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