Kotlin/collections/singleOrNull

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

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

في حال استدعاء الدالة singleOrNull()‎ عبر مصفوفة دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك المصفوفة. وفي حال كانت تلك المصفوفة فارغة أو تحتوي أكثر من عنصر واحد فستعيد القيمة المعدومة 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?

في حال استدعاء الدالة singleOrNull()‎ عبر مصفوفة مع تمرير شرط منطقي predicate كمعامل (parameter) فستعيد العنصر الوحيد الذي يحقق ذلك الشرط المنطقي في تلك المصفوفة. وفي حال كانت تلك المصفوفة تحتوي أكثر من عنصر واحد يحقق ذلك الشرط المنطقي أو لا تحتوي أي واحد فستعيد القيمة المعدومة 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?

في حال استدعاء الدالة singleOrNull()‎ عبر مجموعة دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك المجموعة. وفي حال كانت تلك المجموعة فارغة أو تحتوي أكثر من عنصر واحد فستعيد القيمة المعدومة null:

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

في حال استدعاء الدالة singleOrNull()‎ عبر  لائحة دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك اللائحة. وفي حال كانت تلك اللائحة فارغة أو تحتوي أكثر من عنصر واحد فستعيد القيمة المعدومة null:

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

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

العنصر الوحيد الموجود في المصفوفة أو المجموعة أو اللائحة التي استُدعيت عبرها، وفي حال تمرير شرط منطقي predicate كمعامل (parameter) فستعيد العنصر الوحيد الذي يحقق ذلك الشرط المنطقي. أما في حال كانت تلك المصفوفة تحتوي أكثر من عنصر واحد (يحقق predicate في حال تمريرها) أو لا تحتوي أي واحد (يحقق predicate في حال تمريرها) فستعيد القيمة المعدومة null:

أمثلة

استخدام الدالة ()singleOrNull مع المصفوفات

تعرف الشيفرة الآتية  مصفوفة باسم array مكونة من عنصر واحد باستخدام الدالة ()arrayOf‎، ثم تستخدم الدالة  ()singleOrNull  على arrayوتطبع الناتج:

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

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

استخدام الدالة ()singleOrNull مع المصفوفات: الحالة الثانية

تعرف الشيفرة الآتية  لائحة باسم array مكونة من عنصرين باستخدام الدالة ()arrayOf‎، ثم تستخدم الدالة  ()singleOrNull  على array،ولمّا كانت array تحتوي أكثر من عنصر واحد، فستعيد القيمة المعدومة null:

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

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

أنظر أيضًا

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

مصادر

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