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

يختلف سلوك الدالة plus()‎ حسب نوع الكائنات التي استُدعيت عبرها ونوع الوسائط الممررة (انظر فقرة البنية العامة).

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

في حال استدعاء الدالة plus()‎ عبر المصفوفات فستعيد مصفوفة تضم جميع عناصر المصفوفة التي استدعيت عبرها إضافة إلى العنصر المُمرّر:

operator fun <T> Array<T>.plus(element: T): Array<T> 
operator fun ByteArray.plus(element: Byte): ByteArray 
operator fun ShortArray.plus(element: Short): ShortArray 
operator fun IntArray.plus(element: Int): IntArray 
operator fun LongArray.plus(element: Long): LongArray 
operator fun FloatArray.plus(element: Float): FloatArray 
operator fun DoubleArray.plus(element: Double): DoubleArray 
operator fun BooleanArray.plus(
    element: Boolean
): BooleanArray

في حال استدعاء الدالة plus()‎ عبر المصفوفات مع تمرير مجموعة كوسيط، فستعيد مصفوفة تضم جميع عناصر المصفوفة التي استدعيت عبرها إضافة إلى عناصر المجموعة المُمرّرة:

operator fun <T> Array<T>.plus(
    elements: Collection<T>
): Array<T> 
operator fun ByteArray.plus(
    elements: Collection<Byte>
): ByteArray 
operator fun ShortArray.plus(
    elements: Collection<Short>
): ShortArray 
operator fun IntArray.plus(
    elements: Collection<Int>
): IntArray 
operator fun LongArray.plus(
    elements: Collection<Long>
): LongArray 
operator fun FloatArray.plus(
    elements: Collection<Float>
): FloatArray 
operator fun DoubleArray.plus(
    elements: Collection<Double>
): DoubleArray 
operator fun BooleanArray.plus(
    elements: Collection<Boolean>
): BooleanArray 
operator fun CharArray.plus(
    elements: Collection<Char>
): CharArray

في حال استدعاء الدالة plus()‎ عبر المصفوفات مع تمرير مصفوفة كوسيط، فستعيد مصفوفة تضم جميع عناصر المصفوفة التي استدعيت عبرها إضافة إلى عناصر المصفوفة المُمرّرة:

operator fun <T> Array<T>.plus(
    elements: Array<out T>
): Array<T> 
operator fun ByteArray.plus(elements: ByteArray): ByteArray 
operator fun ShortArray.plus(
    elements: ShortArray
): ShortArray 
operator fun IntArray.plus(elements: IntArray): IntArray 
operator fun LongArray.plus(elements: LongArray): LongArray 
operator fun FloatArray.plus(
    elements: FloatArray
): FloatArray 
operator fun DoubleArray.plus(
    elements: DoubleArray
): DoubleArray 
operator fun BooleanArray.plus(
    elements: BooleanArray
): BooleanArray

في حال استدعاء الدالة plus()‎ عبر المجموعات فستعيد لائحة تضم جميع عناصر المجموعة التي استدعيت عبرها إضافة إلى العنصر المُمرّر:

inline fun <T> Iterable<T>.partition(
    predicate: (T) -> Boolean
): Pair<List<T>, List<T>>

في حال استدعاء الدالة plus()‎ عبر المجموعات مع تمرير مصفوفة كوسيط، فستعيد لائحة تضم جميع عناصر المجموعةالتي استدعيت عبرها إضافة إلى عناصر المصفوفة المُمرّرة:

operator fun <T> Iterable<T>.plus(
    elements: Array<out T>
): List<T> 
operator fun <T> Collection<T>.plus(
    elements: Array<out T>
): List<T>

في حال استدعاء الدالة plus()‎ عبر المجموعات مع تمرير مجموعة كوسيط، فستعيد لائحة تضم جميع عناصر المجموعة التي استدعيت عبرها إضافة إلى عناصر المجموعة المُمرّرة:

operator fun <T> Iterable<T>.plus(
    elements: Iterable<T>
): List<T> 
operator fun <T> Collection<T>.plus(
    elements: Iterable<T>
): List<T>

في حال استدعاء الدالة plus()‎ عبر المجموعات مع تمرير سلسلة كوسيط، فستعيد لائحة تضم جميع عناصر المجموعة التي استدعيت عبرها إضافة إلى عناصر السلسلة المُمرّرة:

operator fun <T> Iterable<T>.plus(
    elements: Sequence<T>
): List<T> 
operator fun <T> Collection<T>.plus(
    elements: Sequence<T>
): List<T>

في حال استدعاء الدالة plus()‎ عبر مجموعة من النوع Set ، فستعيد مجموعة من النوع Set تضم جميع عناصر المجموعة التي استدعيت عبرها إضافة إلى العنصر المُمرّر إن لم يكن موجودًا سلفًا، المجموعة المعادة تحافظ على ترتيب التكرار للمجموعة الأصلية:

operator fun <T> Set<T>.plus(element: T): Set<T>

في حال استدعاء الدالة plus()‎ عبر مجموعة من النوع Set مع تمرير مصفوفة كوسيط، فستعيد مجموعة من النوع Set تضم جميع عناصر المجموعة التي استدعيت عبرها إضافة إلى عناصر المصفوفة المُمرّرة مع تجنب العناصر الموجودة سلفًا، المجموعة المعادة تحافظ على ترتيب التكرار للمجموعة الأصلية:

operator fun <T> Set<T>.plus(elements: Array<out T>): Set<T>

في حال استدعاء الدالة plus()‎ عبر مجموعة من النوع Set مع تمرير مجموعة كوسيط، فستعيد مجموعة من النوع Set تضم جميع عناصر المجموعة التي استدعيت عبرها إضافة إلى عناصر المجموعة المُمرّرة مع تجنب العناصر الموجودة سلفًا، المجموعة المعادة تحافظ على ترتيب التكرار للمجموعة الأصلية:

operator fun <T> Set<T>.plus(elements: Iterable<T>): Set<T>

في حال استدعاء الدالة plus()‎ عبر مجموعة من النوع Set مع تمرير سلسلة كوسيط، فستعيد مجموعة من النوع Set تضم جميع عناصر المجموعة التي استدعيت عبرها إضافة إلى عناصر السلسلة المُمرّرة مع تجنب العناصر الموجودة سلفًا، المجموعة المعادة تحافظ على ترتيب التكرار للمجموعة الأصلية:

operator fun <T> Set<T>.plus(elements: Iterable<T>): Set<T>

في حال استدعاء الدالة plus()‎ عبر قاموس، فستعيد قاموسًا جديدًا للقراءة فقط (read-only) بتعويض أو إضافة مدخل (entry) جديد انطلاقًا من الزوج المُمرّر pair، القاموسالمعاد يحافظ على ترتيب التكرار للقاموس الأصلي:

operator fun <K, V> Map<out K, V>.plus(
    pair: Pair<K, V>
): Map<K, V>

في حال استدعاء الدالة plus()‎ عبر قاموس مع تمرير مجموعة كوسيط، فستعيد قاموسًا جديدًا للقراءة فقط (read-only) بتعويض أو إضافة مداخلَ (entries) جديدة انطلاقًا من المجموعة المُمرّرة pairs، القاموسالمعاد يحافظ على ترتيب التكرار للقاموس الأصلي، والمداخل المُضافة من pairs ذات المفاتيح الفريدة ستُكرّر في آخر ترتيب pairs:

operator fun <K, V> Map<out K, V>.plus(
    pairs: Iterable<Pair<K, V>>
): Map<K, V>

في حال استدعاء الدالة plus()‎ عبر قاموس مع تمرير مصفوفة كوسيط، فستعيد قاموسًا جديدًا للقراءة فقط (read-only) بتعويض أو إضافة مداخلَ (entries) جديدة انطلاقًا من المصفوفة المُمرّرة pairs، القاموسالمعاد يحافظ على ترتيب التكرار للقاموس الأصلي، والمداخل المُضافة من pairs ذات المفاتيح الفريدة ستُكرّر في آخر ترتيب pairs:

operator fun <K, V> Map<out K, V>.plus(
    pairs: Array<out Pair<K, V>>
): Map<K, V>

في حال استدعاء الدالة plus()‎ عبر قاموس مع تمرير سلسلة كوسيط، فستعيد قاموسًا جديدًا للقراءة فقط (read-only) بتعويض أو إضافة مداخلَ (entries) جديدة انطلاقًا من السلسلة المُمرّرة pairs، القاموسالمعاد يحافظ على ترتيب التكرار للقاموس الأصلي، والمداخل المُضافة من pairs ذات المفاتيح الفريدة ستُكرّر في آخر ترتيب pairs:

operator fun <K, V> Map<out K, V>.plus(
    pairs: Sequence<Pair<K, V>>
): Map<K, V>

في حال استدعاء الدالة plus()‎ عبر قاموس مع تمرير قاموس كوسيط، فستعيد قاموسًا جديدًا للقراءة فقط (read-only) بتعويض أو إضافة مداخلَ (entries) جديدة انطلاقًا من القاموس المُمرّر map، القاموسالمعاد يحافظ على ترتيب التكرار للقاموس الأصلي، المداخل المُضافة من pairs ذات المفاتيح الفريدة تُكرّر في آخر ترتيب map:

operator fun <K, V> Map<out K, V>.plus(
    map: Map<out K, V>
): Map<K, V>

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

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

على حسب إمضاء الدالة (انظر فقرة البنية العامة).

أمثلة

استخدام الدالة ()plus مع اللوائح

تعرف الشيفرة الآتية لائحة باسم iterableمكونة من خمسة أعداد باستخدام الدالة ()listOf، ثم تستدعي الدالة ()plus عبر iterable لإضافة العدد 7 إلى اللائحة iterable، ثم تطبع الناتج:

fun main(args: Array<String>) {
    val iterable = listOf(1, 2, 3, 4, 5)

    println(iterable.plus(7)) // [1, 2, 3, 4, 5, 7]
}

استخدام الدالة ()plus مع اللوائح: الحالة الثانية

تعرف الشيفرة الآتية لائحة باسم iterableمكونة من خمسة أعداد باستخدام الدالة ()listOf، ثم تعرف مصفوفة باسم array مكونة من ثلاثة أعداد باستخدام الدالة  ()arrayOf، ثم تستدعي الدالة ()plus عبر iterable مع تمرير array كوسيط لإضافة عناصرها إلى iterable، ثم تطبع الناتج:

fun main(args: Array<String>) {
    val iterable = listOf(1, 2, 3, 4, 5)
    val array = arrayOf(13,25,6)

    println(iterable.plus(array)) // [1, 2, 3, 4, 5, 13, 25, 6]
}

انظر أيضًا

• partition()‎: تُقسّم المصفوفة أو المجموعة التي استُدعيت عبرها إلى زوج مكوّن من لائحتين، اللائحة الأولى تضم العناصر التي تحقق الشرط المنطقي المُمرّر predicate (أي تعيد true)، بينما تضم الثانية العناصر الأخرى.

مصادر

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