الفرق بين المراجعتين لصفحة: «Kotlin/collections/joinToString»

المراجعة الحالية بتاريخ 09:19، 8 سبتمبر 2018

تضيف الدالة joinToString()‎ بادئة ولاحقة إلى جميع عناصر المصفوفة أو المجموعة التي استُدعيت معها (أو جزءٍ منها) بعد فصل عناصرها بفاصلة معينة ثمَّ تضع الناتج في سلسة نصية جديدة تنشئها آنذاك.

إن كانت المجموعة كبيرة، فيمكن تحديد جزءٍ أولي معين منها فقط لإضافته إلى السلسلة النصية؛ في هذه الحالة، تضاف سلسلة نصية معيَّنة، مثل "..." أو "...إلخ" إلى السلسلة النصية الناتجة للدلالة على وجود جزءٍ مقتطعٍ.

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

fun <T> Array<out T>.joinToString(
    separator: CharSequence = ", ", 
    prefix: CharSequence = "", 
    postfix: CharSequence = "", 
    limit: Int = -1, 
    truncated: CharSequence = "...", 
    transform: (T) -> CharSequence = null
): String 
fun ByteArray.joinToString(
    separator: CharSequence = ", ", 
    prefix: CharSequence = "", 
    postfix: CharSequence = "", 
    limit: Int = -1, 
    truncated: CharSequence = "...", 
    transform: (Byte) -> CharSequence = null
): String 
fun ShortArray.joinToString(
    separator: CharSequence = ", ", 
    prefix: CharSequence = "", 
    postfix: CharSequence = "", 
    limit: Int = -1, 
    truncated: CharSequence = "...", 
    transform: (Short) -> CharSequence = null
): String 
fun IntArray.joinToString(
    separator: CharSequence = ", ", 
    prefix: CharSequence = "", 
    postfix: CharSequence = "", 
    limit: Int = -1, 
    truncated: CharSequence = "...", 
    transform: (Int) -> CharSequence = null
): String 
fun LongArray.joinToString(
    separator: CharSequence = ", ", 
    prefix: CharSequence = "", 
    postfix: CharSequence = "", 
    limit: Int = -1, 
    truncated: CharSequence = "...", 
    transform: (Long) -> CharSequence = null
): String 
fun FloatArray.joinToString(
    separator: CharSequence = ", ", 
    prefix: CharSequence = "", 
    postfix: CharSequence = "", 
    limit: Int = -1, 
    truncated: CharSequence = "...", 
    transform: (Float) -> CharSequence = null
): String 
fun DoubleArray.joinToString(
    separator: CharSequence = ", ", 
    prefix: CharSequence = "", 
    postfix: CharSequence = "", 
    limit: Int = -1, 
    truncated: CharSequence = "...", 
    transform: (Double) -> CharSequence = null
): String 
fun BooleanArray.joinToString(
    separator: CharSequence = ", ", 
    prefix: CharSequence = "", 
    postfix: CharSequence = "", 
    limit: Int = -1, 
    truncated: CharSequence = "...", 
    transform: (Boolean) -> CharSequence = null
): String 
fun CharArray.joinToString(
    separator: CharSequence = ", ", 
    prefix: CharSequence = "", 
    postfix: CharSequence = "", 
    limit: Int = -1, 
    truncated: CharSequence = "...", 
    transform: (Char) -> CharSequence = null
): String 
fun <T> Iterable<T>.joinToString(
    separator: CharSequence = ", ", 
    prefix: CharSequence = "", 
    postfix: CharSequence = "", 
    limit: Int = -1, 
    truncated: CharSequence = "...", 
    transform: (T) -> CharSequence = null
): String

المعاملات

`separator`

الفاصل المستعمل في فصل العناصر. القيمة الافتراضية هي: " ,".

`prefix`

البادئة المراد إضافتها إلى بداية العناصر. القيمة الافتراضية هي: "".

`postfix`

اللاحقة المراد إضافتها إلى نهاية العناصر. القيمة الافتراضية هي: "".

`limit`

عدد صحيح يمثل العدد الأقصى للعناصر المراد تطبيق العملية عليها. القيمة الافتراضية هي: 1-.

`truncated`

سلسلة نصية تمثل الجزء الذي سيحل مكان الجزء المقتطع من العناصر. القيمة الافتراضية هي: "...".

`transform`

دالة تطبق على كل عنصر من عناصر المصفوفة أو المجموعة المعطاة، إذ يمرر إليها العنصر وتعيد السلسلة النصية المقابلة له.

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

تُعاد سلسلة نصية تحوي عناصر المصفوفة أو المجموعة المعطاة (أو الجزء limit الأولي منها فقط) بعد فصلها بالفاصل separator وإضافة البادئة prefix واللاحقة postfix إليها إن أعطيت هذه المعاملات. عند تحديد المعامل limit، ستضاف السلسلة النصية truncated (قيمتها الافتراضية هي "...") إلى نهاية السلسلة النصية المعادة لتشير إلى وجود جزء مقتطع.

أمثلة

توضح الشيفرة التالية كيفية إضافة بادئة ولاحقة إلى عناصر قائمةٍ بعد فصلها بفاصل معين:

fun main(args: Array<String>) {
    val numbers = listOf(1, 2, 3, 4, 5, 6)
    println(numbers.joinToString()) // 1, 2, 3, 4, 5, 6
    println(numbers.joinToString(prefix = "[", postfix = "]")) // [1, 2, 3, 4, 5, 6]
    println(numbers.joinToString(prefix = "<", postfix = ">", separator = "•")) // <1•2•3•4•5•6>
}

أما الشيفرة التالية، فتوضح كيفية إضافة بادئة ولاحقة إلى أول خمسة عناصر من قائمةٍ بعد فصلها بفاصل معين وإضافة سلسلة نصية معينة تدل على وجود جزء مقتطع:

fun main(args: Array<String>) {
    val chars = charArrayOf('a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q')
    println(chars.joinToString(limit = 5, truncated = "...!") { it.toUpperCase().toString() }) // A, B, C, D, E, ...!
}

انظر أيضًا

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

مصادر

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

@@ سطر 1: / سطر 1: @@
-<noinclude>{{DISPLAYTITLE: الدالة <code>joinToString()‎</code> في لغة Kotlin}}</noinclude>
+<noinclude>{{DISPLAYTITLE: الدالة <code>joinToString()‎</code> في Kotlin}}</noinclude>
-تنشئ الدالة<code>joinToString()‎</code> [[Kotlin/String|سلسة نصية]] من عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت عبرها مفصولة بالمعامل المُمرّر  <code>separator</code> وباستخدام البادئة <code>prefix</code> واللاحقة <code>postfix</code> في حال تمريرهما،
+تضيف الدالة <code>joinToString()‎</code> بادئة ولاحقة إلى جميع عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت معها (أو جزءٍ منها) بعد فصل عناصرها بفاصلة معينة ثمَّ تضع الناتج في [[Kotlin/String|سلسة نصية]] جديدة تنشئها آنذاك.
-إن كانت [[Kotlin/collections|المجموعة]] كبيرة فيمكن تمرير عدد موجب <code>limit</code>، وفي تلك الحالة سيكون عدد العناصر التي تضيفها الدالة <code>joinToString()‎</code> هو <code>limit</code> إضافة إلى [[Kotlin/String|السلسلة النصية]] <code>truncated</code> التي قيمتها الابتدائية <code>"..."</code>.
+إن كانت [[Kotlin/collections|المجموعة]] كبيرة، فيمكن تحديد جزءٍ أولي معين منها فقط لإضافته إلى السلسلة النصية؛ في هذه الحالة، تضاف سلسلة نصية معيَّنة، مثل "..." أو "...إلخ" إلى السلسلة النصية الناتجة للدلالة على وجود جزءٍ مقتطعٍ.
 ==البنية العامة==
 <syntaxhighlight lang="kotlin">
@@ سطر 87: / سطر 87: @@
 </syntaxhighlight>
-==القيم المٌعادة==
-[[Kotlin/String|سلسة نصية]] مكونة من عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت عبرها مفصولة بالمعامل المُمرّر  <code>separator</code> وباستخدام البادئة <code>prefix</code> واللاحقة <code>postfix</code> في حال تمريرهما،
-إن كانت [[Kotlin/collections|المجموعة]] كبيرة فيمكن تمرير عدد موجب <code>limit</code>، وفي تلك الحالة سيكون عدد العناصر التي تضمّها الدالة <code>joinToString()‎</code> هو <code>limit</code> إضافة إلى [[Kotlin/String|السلسلة النصية]] <code>truncated</code> التي قيمتها الابتدائية <code>"..."</code>.
+== المعاملات ==
+=== <code>separator</code> ===
+الفاصل المستعمل في فصل العناصر. القيمة الافتراضية هي: <code>" ,"</code>.
+=== <code>prefix</code> ===
+البادئة المراد إضافتها إلى بداية العناصر. القيمة الافتراضية هي: <code>""</code>.
+=== <code>postfix</code> ===
+اللاحقة المراد إضافتها إلى نهاية العناصر. القيمة الافتراضية هي: <code>""</code>.
+=== <code>limit</code> ===
+عدد صحيح يمثل العدد الأقصى للعناصر المراد تطبيق العملية عليها. القيمة الافتراضية هي: 1-.
+=== <code>truncated</code> ===
+سلسلة نصية تمثل الجزء الذي سيحل مكان الجزء المقتطع من العناصر. القيمة الافتراضية هي: <code>"..."</code>.
+=== <code>transform</code> ===
+دالة تطبق على كل عنصر من عناصر <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] المعطاة، إذ يمرر إليها العنصر وتعيد السلسلة النصية المقابلة له.
+==القيم المعادة==
+تُعاد سلسلة نصية تحوي عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] المعطاة (أو الجزء <code>limit</code> الأولي منها فقط) بعد فصلها بالفاصل <code>separator</code> وإضافة البادئة <code>prefix</code> واللاحقة <code>postfix</code> إليها إن أعطيت هذه المعاملات. عند تحديد المعامل <code>limit</code>، ستضاف السلسلة النصية <code>truncated</code> (قيمتها الافتراضية هي "...") إلى نهاية السلسلة النصية المعادة لتشير إلى وجود جزء مقتطع.
 ==أمثلة==
-===استخدام الدالة <code>()joinToString</code> مع اللوائح===
+توضح الشيفرة التالية كيفية إضافة بادئة ولاحقة إلى عناصر قائمةٍ بعد فصلها بفاصل معين:<syntaxhighlight lang="kotlin">
-تعرّف الشيفرة الآتية  [[Kotlin/List|لائحة]]<nowiki/> باسم <code>numbers</code> باستخدام الدالة <code>()listOf</code>، ثم تستخدم الدالة <code>()joinToString</code> على <code>numbers</code> بتمرير بادئة ولاحقة وفاصلة، ثم تطبع الناتج:<syntaxhighlight lang="kotlin">
 fun main(args: Array<String>) {
-val numbers = listOf(1, 2, 3, 4, 5, 6)
+    val numbers = listOf(1, 2, 3, 4, 5, 6)
+     println(numbers.joinToString()) // 1, 2, 3, 4, 5, 6
-println(numbers.joinToString(prefix = "<", postfix = ">", separator = "•")) // <1•2•3•4•5•6>
+    println(numbers.joinToString(prefix = "[", postfix = "]")) // [1, 2, 3, 4, 5, 6]
+    println(numbers.joinToString(prefix = "<", postfix = ">", separator = "•")) // <1•2•3•4•5•6>
+}
+</syntaxhighlight>أما الشيفرة التالية، فتوضح كيفية إضافة بادئة ولاحقة إلى أول خمسة عناصر من قائمةٍ بعد فصلها بفاصل معين وإضافة سلسلة نصية معينة تدل على وجود جزء مقتطع:<syntaxhighlight lang="kotlin">
+fun main(args: Array<String>) {
+    val chars = charArrayOf('a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q')
+    println(chars.joinToString(limit = 5, truncated = "...!") { it.toUpperCase().toString() }) // A, B, C, D, E, ...!
 }
 </syntaxhighlight>
 ==انظر أيضًا==
-<code>[[Kotlin/collections/joinTo|joinTo()]]</code>‎: تجمّع الدالة سلسة نصية من عناصر <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] التي استُدعيت عبرها مفصولة بالمعامل المُمرّر <code>separator</code> وباستخدام البادئة<code>prefix</code> واللاحقة <code>postfix</code> في حال تمريرهما،
+* الدالة <code>[[Kotlin/collections/joinTo|joinTo()]]</code>‎: تضيف بادئة ولاحقة إلى جميع عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت معها (أو جزءٍ منها) وتفصلها بفاصلة معينة ثمَّ تضيفها إلى [[Kotlin/String|سلسة نصية]] موجودة مسبقًا.
+* الدالة <code>[[Kotlin/collections/getOrElse|getOrElse()‎]]</code>: تجلب عنصرًا ذي فهرس مُحدَّد من <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] التي استُدعيت معها أو القيمة المقابلة لمفتاح محدَّد إن استدعيت مع خريطة.
 ==مصادر==
-[https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/join-to-string.html الدالة joinToString()‎ في التوثيق الرسمي للمكتبة القياسية في لغة Kotlin]
+* [https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/join-to-string.html صفحة الدالة joinToString()‎ في التوثيق الرسمي للمكتبة القياسية في لغة Kotlin]
 [[تصنيف:Kotlin]]
-[[تصنيف:Kotlin Functions]]
+[[تصنيف:Kotlin Function]]
+[[تصنيف:Kotlin Collection]]