الدالة singleOrNull()‎ في Kotlin

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

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

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

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

fun <T> Iterable<T>.singleOrNull(): T? 

fun <T> List<T>.singleOrNull(): T?

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

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

المعاملات

predicate

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

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

يعاد العنصر الوحيد الموجود في المصفوفة أو المجموعة أو القائمة المعطاة، أو العنصر الوحيد الذي حقَّق الشرط predicate (إن أعطي)، أو القيمة null خلاف ذلك.

أمثلة

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

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

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

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

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

    print(array.singleOrNull()) // null
}

انظر أيضًا

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

مصادر

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