الدالة 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

وإن استدعيت هذه الدالة مع المصفوفات مع تمرير مجموعة كمعامل، فستعيد مصفوفة تضم جميع عناصر المصفوفة التي استدعيت معها إضافةً إلى عناصر تلك المجموعة المعطاة:

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

وإن استدعيت هذه الدالة مع المصفوفات مع تمرير مصفوفة كمعامل، فستعيد مصفوفة تضم جميع عناصر المصفوفة التي استدعيت معها إضافةً إلى جميع عناصر المصفوفة المُمرّرة:

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

وإن استدعيت هذه الدالة مع المجموعات، فستعيد قائمةً تضم جميع عناصر المجموعة التي استدعيت معها إضافة إلى العنصر المُمرّر:

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

وإن استدعيت هذه الدالة مع المجموعات مع تمرير مصفوفة كمعامل، فستعيد قائمة تضم جميع عناصر المجموعة التي استدعيت معها إضافةً إلى عناصر المصفوفة المُمرّرة:

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

وإن استدعيت هذه الدالة مع المجموعات مع تمرير مجموعة كمعامل، فستعيد قائمة تضم جميع عناصر المجموعة التي استدعيت معها إضافةً إلى عناصر المجموعة المُمرّرة:

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

وإن استدعيت هذه الدالة مع المجموعات مع تمرير سلسلة كمعامل، فستعيد قائمة تضم جميع عناصر المجموعة التي استدعيت معها إضافةً إلى عناصر السلسلة المُمرّرة:

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

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

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

وإن استدعيت هذه الدالة مع مجموعة من النوع Set مع تمرير مصفوفة كوسيط، فستعيد مجموعة من النوع Set تضم جميع عناصر المجموعة التي استدعيت معها إضافةً إلى عناصر المصفوفة المُمرّرة الغير موجودة مسبقًا؛ تحافظ المجموعة المعادة على ترتيب التكرار للمجموعة الأصلية:

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

وإن استدعيت هذه الدالة مع مجموعة من النوع Set مع تمرير مجموعة كوسيط، فستعيد مجموعة من النوع Set تضم جميع عناصر المجموعة التي استدعيت معها إضافةً إلى عناصر المجموعة المُمرّرة الغير موجودة مسبقًا؛ تحافظ المجموعة المعادة على ترتيب التكرار للمجموعة الأصلية:

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

وإن استدعيت هذه الدالة مع مجموعة من النوع Set مع تمرير سلسلة كوسيط، فستعيد مجموعةً من النوع Set تضم جميع عناصر المجموعة التي استدعيت معها إضافةً إلى عناصر السلسلة المُمرّرة الغير موجودة مسبقًا؛ تحافظ المجموعة المعادة على ترتيب التكرار للمجموعة الأصلية:

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

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

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

وإن استدعيت هذه الدالة مع خريطة مع تمرير مجموعة كوسيط، فستعيد خريطة جديدة للقراءة فقط (read-only) تحوي جميع عناصر تلك الخريطة مع استبدال أو إضافة الأزواج pairs المعطاة من تلك المجموعة إليها؛ تحافظ الخريطة المعادة على ترتيب التكرار للخريطة الأصلية، وستضاف الأزواج pairs ذات المفاتيح الفريدة في النهاية وبنفس الترتيب الذي أعطيت به:

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

وإن استدعيت هذه الدالة مع خريطة مع تمرير مصفوفة كوسيط، فستعيد خريطة جديدة للقراءة فقط (read-only) تحوي جميع عناصر تلك الخريطة مع استبدال أو إضافة الأزواج pairs المعطاة من تلك المصفوفة إليها؛ تحافظ الخريطة المعادة على ترتيب التكرار للخريطة الأصلية، وستضاف الأزواج pairs ذات المفاتيح الفريدة في النهاية وبنفس الترتيب الذي أعطيت به:

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

وإن استدعيت هذه الدالة مع خريطة مع تمرير سلسلة كوسيط، فستعيد خريطة جديدة للقراءة فقط (read-only) تحوي جميع عناصر تلك الخريطة مع استبدال أو إضافة الأزواج pairs المعطاة من تلك السلسلة إليها؛ تحافظ الخريطة المعادة على ترتيب التكرار للخريطة الأصلية، وستضاف الأزواج pairs ذات المفاتيح الفريدة في النهاية وبنفس الترتيب الذي أعطيت به:

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

وإن استدعيت هذه الدالة مع خريطة مع تمرير خريطة أخرى كوسيط، فستعيد خريطة جديدة للقراءة فقط (read-only) تحوي جميع عناصر تلك الخريطة مع استبدال أو إضافة الأزواج pairs من تلك الخريطة المعطاة إليها؛ وستضاف أزواج الخريطة map المعطاة ذات المفاتيح الفريدة في النهاية وبنفس الترتيب الذي أعطيت به:

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

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

المعاملات

element

العنصر المراد إضافته.

elements

العناصر المراد إضافتها.

pair

الزوج المراد إضافته إلى الخريطة المعطاة.

pairs

الأزواج المراد إضافتها إلى الخريطة المعطاة.

map

الخريطة التي يراد إضافة محتواها إلى الخريطة المعطاة.

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

يُعاد كائن جديد يحوي جميع عناصر الكائن المعطى (ومن النوع نفسه) بالإضافة إلى العناصر أو الكائنات الممرَّرة.

أمثلة

استعمال الدالة ()plus لإضافة عنصر واحد إلى قائمة:

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

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

استعمال الدالة ()plus لإضافة جميع عناصر مصفوفة إلى قائمة:

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]
}

انظر أيضًا

• الدالة plusElement()‎: تضيف العنصر المُمرّر إليها إلى المصفوفة أو المجموعة التي استُدعيت معها.
• الدالة fill()‎: تبدِّل قيمة جديدة معطاة مكان عناصر محدَّدة في المصفوفة أو القائمة التي تستدعى معها.
• الدالة joinTo()‎: تضيف بادئة ولاحقة إلى جميع عناصر المصفوفة أو المجموعة التي استُدعيت معها (أو جزءٍ منها) وتفصلها بفاصلة معينة ثمَّ تضيفها إلى سلسة نصية موجودة مسبقًا.

مصادر

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