Kotlin/collections/first

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

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

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

يمكن استدعاء الدالة first()‎ بدون تمرير أية معاملات:

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

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

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

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

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

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

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

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

أمثلة

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

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

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

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

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

تعرف الشيفرة الآتية مصفوفة باسم array باستخدام الدالة ()arrayOf، ثمَّ تستخدم الدالة ()first لجلب أول عنصر من تلك المصفوفة شرط أن تكون قيمته أصغر من 3:

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

    println(array.first(predicate)) // 2
}

انظر أيضًا

• الدالة firstOrNull()‎: تجلب أول عنصر من عناصر المصفوفة أو المجموعة التي استُدعيت معها إن لم يُمرَّر إليها أي شيء، أو أول عنصر يحقق شرطًا معيَّنًا في حال تمرير دالة منطقية إليها.
• الدالة find()‎: تبحث على عنصر محدَّد ضمن عناصر المصفوفة أو المجموعة التي استُدعيت معها ثمَّ تعيد أول ظهور له.
• الدالة filter()‎: ترشِّح عناصر المصفوفة أو المجموعة أو أزواج الخرائط المعطاة التي تحقِّق شرطًا معيَّنًا ثمّ تعيدها.
• الدالة filterNot()‎: تعيد قائمةً تحوي عناصر المصفوفة أو المجموعة التي لا تحقق شرطًا منطقيًّا محدَّدًا. إن استدعيت مع خريطة (map)، فستعيد خريطة جديدة تحوي الأزواج التي لم تحقق ذلك الشرط المنطقي.
• الدالة drop()‎: تعيد قائمة تحوي جميع عناصر المصفوفة أو المجموعة التي استُدعيت معها باستثناء آخر n عنصر.

مصادر

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