Kotlin/collections/single

تتحقَّق الدالة single()‎ من حواية المصفوفة أو المجموعة أو القائمة التي استُدعيت معها عنصرًا واحدًا فقط أو عنصرًا واحدًا محققًا لشرط معيَّن ثمَّ تعيده أو تطلق استثناءً خلاف ذلك.

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

إن استدعيت الدالة single()‎ مع مصفوفة أو مجموعة أو قائمة دون تمرير أي معامل، فستتحقَّق من احتواء تلك المصفوفة أو المجموعة أو القائمة على عنصر واحد فقط ثمَّ تعيده. وفي حال كانت تلك المصفوفة أو المجموعة أو القائمة فارغةً أو تحوي أكثر من عنصر واحد، فستطلق الدالة single()‎ استثناءً:

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

وإن استدعيت مع مصفوفة ومرِّر إليها الشرط predicate كمعامل، فستتحقَّق من تطابق عنصر واحد فقط من عناصر تلك المصفوفة مع ذلك الشرط. وفي حال تطابق أكثر من عنصر مع ذلك الشرط المنطقي أو لم يكن هنالك أي عنصر في المصفوفة، فستطلق الدالة single()‎ استثناءً:

inline fun <T> Array<out T>.single(
    predicate: (T) -> Boolean
): T 
inline fun ByteArray.single(
    predicate: (Byte) -> Boolean
): Byte 
inline fun ShortArray.single(
    predicate: (Short) -> Boolean
): Short 
inline fun IntArray.single(predicate: (Int) -> Boolean): Int (source)
inline fun LongArray.single(
    predicate: (Long) -> Boolean
): Long 
inline fun FloatArray.single(
    predicate: (Float) -> Boolean
): Float 
inline fun DoubleArray.single(
    predicate: (Double) -> Boolean
): Double
inline fun BooleanArray.single(
    predicate: (Boolean) -> Boolean
): Boolean 
inline fun CharArray.single(
    predicate: (Char) -> Boolean
): Char 
inline fun <T> Iterable<T>.single(
    predicate: (T) -> Boolean
): T 

fun <T> Iterable<T>.single(): T 

fun <T> List<T>.single(): T

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

يعاد العنصر الوحيد الموجود في المصفوفة أو المجموعة أو القائمة المعطاة، أو العنصر الوحيد الذي حقق الشرط predicate (إن أعطي)، أو يُطلق استثناءٌ خلاف ذلك.

أمثلة

استعمال الدالة ()single  للتأكد من احتواء مصفوفة على عنصر وحيد وجلبه:

fun main(args: Array<String>) {
    var array = arrayOf(0)

    print(array.single()) // 0
}

استعمال الدالة  ()single للتأكد من احتواء مصفوفة على عنصر وحيد وجلبه إن كان كذلك محقَّقًا:

fun main(args: Array<String>) {
    var array = arrayOf(0, 6)

    print(array.single())
}

نتيجة تنفيذ المثال السابق هي:

Exception in thread "main" java.lang.IllegalArgumentException: Array has more than one element.
	at kotlin.collections.ArraysKt___ArraysKt.single(_Arrays.kt:2059)
	at TestKt.main(test.kt:4)

انظر أيضًا

• الدالة singleOrNull()‎: تتحقَّق من حواية المصفوفة أو المجموعة أو القائمة التي استُدعيت معها عنصرًا واحدًا فقط، أو عنصرًا واحدًا محققًا لشرط معيَّن ثمَّ تعيده، أو تعيد القيمة null خلاف ذلك.
• الدالة find()‎: تبحث على عنصر محدَّد ضمن عناصر المصفوفة أو المجموعة التي استُدعيت معها ثمَّ تعيد أول ظهور له.
• الخاصية ‎‎lastIndex: تجلب الفهرس الأخير لمصفوفة أو قائمة.

مصادر

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