Kotlin/collections/firstOrNull

تعيد الدالةfirstOrNull()‎ العنصر الأول من المصفوفة أو المجموعة التي استُدعيت عبرها، وفي حال تمرير دالة منطقية كمعامل فستعيد أول عنصر يحقق تلك الدالة.

إن كانت المصفوفة أو المجموعة التي استُدعيت الدالةfirst()‎عبرها فارغة أو لم يكن هناك أي عنصر يحقق الدالة المنطقية الممررة إليها فستعيد الدالة first()‎ القيمة المعدومة null.

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

في حال استدعاء الدالةfirstOrNull()‎ بدون معامل فستعيد العنصر الأول.

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

في حال استدعاء الدالةfirstOrNull()‎ مع دالة منطقية كمعامل فستعيد العنصر الأول الذي يحقق تلك الدالة.

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

في حال استدعاء الدالةfirstOrNull()‎ بدون معامل علىمجموعة أو لائحة فستعيد العنصر الأول:

fun <T> Iterable<T>.firstOrNull(): T? 
fun <T> List<T>.firstOrNull(): T?

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

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

العنصر الأول من المصفوفة أو المجموعة التي استُدعيت عبرها، وفي حال تمرير دالة منطقية كمعامل فستعيد أول عنصر يحقق تلك الدالة. إن كانت المصفوفة أو المجموعة التي استُدعيت الدالةfirst()‎عبرها فارغة أو لم يكن هناك أي عنصر يحقق الدالة المنطقية الممررة إليها فستعيد الدالة first()‎ القيمة المعدومة null.

أمثلة

استخدام الدالة ()firstOrNull مع المصفوفات: الحالة الأولى

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

fun main(args: Array<String>) {
val array = arrayOf(9, 2, 3, 5,0,6)

println(array.firstOrNull()) // 9
}

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

تعرف الشيفرة الآتية مصفوفة باسم arrayمكونة من ستة أعداد باستخدام الدالة ()arrayOf، ثم تُعرّف الدالة المنطقية ()predicate التي تحدد ما إذا كان العدد المُمرّر إليها أصغر من 0 ، ثم تستخدم الدالة ()firstOrNull لإيجاد العنصر الأول في المصفوفةarray الذي يحقق الدالة ()predicate، ولما كانت كل عناصر array لا تحقق هذه الدالة فستعيد null، ثم تطبع الناتج:

fun main(args: Array<String>) {
val array = arrayOf(9, 2, 3, 8, 5,6)
val predicate  : (Int) -> Boolean = { it < 0 }

println(array.firstOrNull(predicate)) // null
}

انظر أيضًا

• first()‎: تعيد العنصر الأول من المصفوفة أو المجموعة التي استُدعيت عبرها، وفي حال تمرير دالة منطقية كمعامل فستعيد أول عنصر يحقق تلك الدالة.
• find()‎: تعيد العنصر الأول من المصفوفة أو المجموعة التي استُدعيت عبرها والذي يحقق الشرط المنطقي predicate المُمرّر إليها. وإن لم يكن هناك أي عنصر يحقق ذلك فستعيد null.
• findLast()‎: تعيد العنصر الأخير من المصفوفة أو المجموعة التي استُدعيت عبرها والذي يحقق الشرط المنطقي predicate المُمرّر إليها. وإن لم يكن هناك أي عنصر يحقق ذلك فستعيد null.

مصادر

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