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

مراجعة 08:58، 3 سبتمبر 2018

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

إن كانت المصفوفة أو المجموعة التي استُدعيت الدالة 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?

ويمكن أيضًا استدعاء هذه الدالة مع تمرير دالة تمثِّل شرطًا منطقيًّا إليها:

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?

ويمكن استعمال الدالة أيضًا مع القوائم:

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

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

المعاملات

`predicate`

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

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

يُعاد أول عنصر من عناصر المصفوفة أو المجموعة المعطاة إن لم يُمرَّر إلى الدالة أي معامل، أو أول عنصر يحقق شرطً المحدد في المعامل predicate إن أعطي، أو القيمة nulll إن كانت المصفوفة أو المجموعة المعطاة فارغة أو لم يكن هناك أي عنصر يحقق ذلك الشرط المعطى.

أمثلة

استخدام الدالة `()firstOrNull` مع المصفوفات: عدم تمرير أي معامل

مثالٌ على استعمال الدالة ()firstOrNull لجلب العنصر الأول وأول عنصر سالب من تلك مصفوفة:

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

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

انظر أيضًا

الدالة lastOrNull()‎: تجلب آخر عنصر من عناصر المصفوفة أو المجموعة التي استُدعيت معها إن لم يُمرَّر إليها أي شيء، أو آخر عنصر يحقق شرطًا معيَّنًا في حال تمرير دالة منطقية إليها.
الدالة first()‎: أول عنصر من عناصر المصفوفة أو المجموعة التي استُدعيت معها إن لم يمرر إليها أي شيء، أو أول عنصر يحق شرطًا معيَّنًا في حال تمرير دالة منطقية إليها.
الدالة findLast()‎: تبحث على عنصر محدَّد ضمن عناصر المصفوفة أو المجموعة التي استُدعيت معها ثمَّ تعيد آخر ظهور له.
الدالة filterTo()‎: تشبه الدالة filter()‎ في جميع النواحي باستثناء أنها تضيف الناتج إلى المعامل المُمرَّر إليها.
الدالة filterNotNull()‎: تعيد جميع عناصر المصفوفة أو المجموعة المعطاة باستثناء تلك ذات القيمة null.

مصادر

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

@@ سطر 51: / سطر 51: @@
 fun <T> List<T>.firstOrNull(): T?
 </syntaxhighlight>وجود الكلمة المفتاحية <code>inline</code> يدل على أنَّ هذه الدالة مباشرة (للمزيد من التفاصيل، راجع صفحة [[Kotlin/inline functions|الدوال المباشرة (inline functions)]]).
+== المعاملات==
+===<code>predicate</code>===
+دالةٌ تمثل الشرط المراد تطبيقه على كل عنصر من عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] المعطاة. يمرر إلى هذه الدالة قيمة العنصر وتعيد قيمةً منطقيةً.
 ==القيم المعادة==
-يُعاد أول عنصر من عناصر <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] المعطاة إن لم يُمرَّر إلى الدالة أي معامل، أو أول عنصر يحقق شرطًا معيَّنًا في حال تمرير دالة منطقية كمعامل، أو القيمة <code>nulll</code> إن كانت <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] المعطاة فارغة أو لم يكن هناك أي عنصر يحقق ذلك الشرط المعطى.
+يُعاد أول عنصر من عناصر <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] المعطاة إن لم يُمرَّر إلى الدالة أي معامل، أو أول عنصر يحقق شرطً المحدد في المعامل <code>predicate</code> إن أعطي، أو القيمة <code>nulll</code> إن كانت <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] المعطاة فارغة أو لم يكن هناك أي عنصر يحقق ذلك الشرط المعطى.
 ==أمثلة==
 ===استخدام الدالة <code>()firstOrNull</code> مع المصفوفات: عدم تمرير أي معامل===
-تعرف الشيفرة الآتية <nowiki/>[[Kotlin/Array|مصفوفة]] باسم <code>array</code> باستخدام الدالة <code>()arrayOf</code>، ثمَّ تستخدم الدالة <code>()firstOrNull</code> لجلب العنصر الأول من تلك المصفوفة:<nowiki/><syntaxhighlight lang="kotlin">
+<nowiki/>مثالٌ على استعمال الدالة <code>()firstOrNull</code> لجلب العنصر الأول وأول عنصر سالب من تلك مصفوفة:<nowiki/><syntaxhighlight lang="kotlin">
 fun main(args: Array<String>) {
      val array = arrayOf(9, 2, 3, 5, 0, 6)
+    val predicate: (Int) -> Boolean = { it < 0 }
      println(array.firstOrNull()) // 9
-}
-</syntaxhighlight>
-===استخدام الدالة <code>()firstOrNull</code> مع المصفوفات: تمرير معامل===
-تعرف الشيفرة الآتية <nowiki/>[[Kotlin/Array|مصفوفة]] باسم <code>array</code> باستخدام الدالة <code>()arrayOf</code>، ثمَّ تستخدم الدالة <code>()first</code> لجلب أول عنصر من تلك المصفوفة شرط أن تكون قيمته سالبة:<nowiki/><syntaxhighlight lang="kotlin">
-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
 }