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

المراجعة الحالية بتاريخ 08:05، 8 سبتمبر 2018

تجلب الدالة 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)).

المعاملات

`predicate`

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

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

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

أمثلة

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

مصادر

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

@@ سطر 1: / سطر 1: @@
-<noinclude>{{DISPLAYTITLE: الدالة <code>first()‎</code> في لغة Kotlin}}</noinclude>
+<noinclude>{{DISPLAYTITLE: الدالة <code>first()‎</code> في Kotlin}}</noinclude>
-تعيد الدالة<code>first()‎</code> العنصر الأول من [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت عبرها، وفي حال تمرير دالة منطقية كمعامل فستعيد أول عنصر يحقق تلك الدالة.
+تجلب الدالة <code>first()‎</code> أول عنصر من عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت معها إن لم يمرر إليها أي شيء، أو أول عنصر يحق شرطًا معيَّنًا في حال تمرير دالة منطقية إليها.
-إن كانت  [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت  الدالة<code>first()‎</code>عبرها فارغة أو لم يكن هناك أي عنصر يحقق الدالة المنطقية الممررة إليها فستطلق الدالة الاستثناء <code>NoSuchElementException</code>.
+إن كانت [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت  الدالة <code>first()‎</code> عبرها فارغة أو لم يكن هناك أي عنصر يحقق الدالة المنطقية الممرَّرة إليها، فستُطلِق الدالة الاستثناء <code>NoSuchElementException</code>.
 ==البنية العامة==
-في حال استدعاء الدالة<code>first()‎</code> بدون معامل فستعيد العنصر الأول.<syntaxhighlight lang="kotlin">
+يمكن استدعاء الدالة <code>first()‎</code> بدون تمرير أية معاملات:<syntaxhighlight lang="kotlin">
 fun <T> Array<out T>.first(): T
 fun ByteArray.first(): Byte
@@ سطر 15: / سطر 15: @@
 fun CharArray.first(): Char
-</syntaxhighlight>في حال استدعاء الدالة<code>first()‎</code> مع دالة منطقية كمعامل فستعيد العنصر الأول الذي يحقق تلك الدالة.<syntaxhighlight lang="kotlin">
+</syntaxhighlight>ويمكن أيضًا استدعاء هذه الدالة مع تمرير دالة تمثِّل شرطًا منطقيًّا إليها:<syntaxhighlight lang="kotlin">
 inline fun <T> Array<out T>.first(
      predicate: (T) -> Boolean
@@ سطر 45: / سطر 45: @@
 ): T
-</syntaxhighlight>في حال استدعاء الدالة<code>first()‎</code> بدون معامل على<nowiki/>[[Kotlin/collections|مجموعة]] أو [[Kotlin/collections/List|لائحة]] فستعيد العنصر الأول الأول:<syntaxhighlight lang="kotlin">
+</syntaxhighlight>و<nowiki/>يمكن استعمال الدالة أيضًا مع القوائم:<syntaxhighlight lang="kotlin">
 fun <T> List<T>.first(): T
-</syntaxhighlight>يُلاحَظ وجود الكلمة المفتاحية <code>inline</code> للدلالة على أن هذه الدالة مباشرة، وللمزيد من التفاصيل راجع <nowiki/>[[Kotlin/inline functions|توثيق الدوال المباشرة (inline functions)]].
+</syntaxhighlight>وجود الكلمة المفتاحية <code>inline</code> يدل على أنَّ هذه الدالة مباشرة (للمزيد من التفاصيل، راجع صفحة [[Kotlin/inline functions|الدوال المباشرة (inline functions)]]).
-==القيم المٌعادة==
-العنصر الأول من [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت عبرها، وفي حال تمرير دالة منطقية كمعامل فستعيد أول عنصر يحقق تلك الدالة.
+== المعاملات ==
+=== <code>predicate</code> ===
+دالةٌ تمثل الشرط المراد تطبيقه على كل عنصر من عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] المعطاة. يمرر إلى هذه الدالة قيمة العنصر وتعيد قيمةً منطقيةً.
+==القيم المعادة==
+يُعاد أول عنصر من عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] المعطاة إن لم يُمرَّر إلى الدالة أي معامل، أو أول عنصر يحق الشرط المحدد في المعامل <code>predicate</code> إن أعطي.
 ==أمثلة==
-===استخدام الدالة <code>()first</code> مع المصفوفات: الحالة الأولى===
+===استخدام الدالة <code>()first</code> مع المصفوفات: عدم تمرير أي معامل===
-تعرف الشيفرة الآتية <nowiki/>[[Kotlin/Array|مصفوفة]] باسم <code>array</code>مكونة من ستة أعداد باستخدام الدالة <code>()arrayOf</code>، ثم تستخدم الدالة <code>()first</code> لإيجاد العنصر  الأول في [[Kotlin/Array|المصفوفة]]<code>array</code>، ثم تطبع الناتج:<syntaxhighlight lang="kotlin">
+تعرف الشيفرة الآتية <nowiki/>[[Kotlin/Array|مصفوفة]] باسم <code>array</code> باستخدام الدالة <code>()arrayOf</code>، ثمَّ تستخدم الدالة <code>()first</code> لجلب العنصر الأول من تلك المصفوفة:<syntaxhighlight lang="kotlin">
 fun main(args: Array<String>) {
-val array = arrayOf(9, 2, 3, 0,6)
+    val array = arrayOf(9, 2, 3, 0, 6)
-println(array.first()) // 9
+    println(array.first()) // 9
 }
 </syntaxhighlight>
-===استخدام الدالة <code>()first</code> مع المصفوفات: الحالة الثانية===
+===استخدام الدالة <code>()first</code> مع المصفوفات: تمرير معامل===
-تعرف الشيفرة الآتية <nowiki/>[[Kotlin/Array|مصفوفة]] باسم <code>array</code>مكونة من ستة أعداد باستخدام الدالة <code>()arrayOf</code>، ثم تُعرّف الدالة المنطقية <code>()predicate</code> التي تحدد ما إذا كان العدد المُمرّر إليها أصغر من <code>3</code> ، ثم تستخدم الدالة <code>()first</code> لإيجاد العنصر الأول في [[Kotlin/Array|المصفوفة]]<code>array</code> الذي يحقق الدالة <code>()predicate</code>، ثم تطبع الناتج:<syntaxhighlight lang="kotlin">
+تعرف الشيفرة الآتية <nowiki/>[[Kotlin/Array|مصفوفة]] باسم <code>array</code> باستخدام الدالة <code>()arrayOf</code>، ثمَّ تستخدم الدالة <code>()first</code> لجلب أول عنصر من تلك المصفوفة شرط أن تكون قيمته أصغر من 3:<syntaxhighlight lang="kotlin">
 fun main(args: Array<String>) {
-val array = arrayOf(9, 2, 3, 0,6)
+    val array = arrayOf(9, 2, 3, 0, 6)
-val predicate  : (Int) -> Boolean = { it < 3 }
+    val predicate: (Int) -> Boolean = { it < 3 }
-println(array.first(predicate)) // 2
+    println(array.first(predicate)) // 2
 }
 </syntaxhighlight>
 ==انظر أيضًا==
-*<code>[[Kotlin/collections/find|find()]]</code>‎: تعيد العنصر الأول من [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت عبرها والذي يحقق الشرط المنطقي <code>predicate</code> المُمرّر إليها. وإن لم يكن هناك  أي عنصر يحقق ذلك فستعيد <code>null.</code>
+*الدالة <code>[[Kotlin/collections/firstOrNull|firstOrNull()‎]]</code>: تجلب أول عنصر من عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت معها إن لم يُمرَّر إليها أي شيء، أو أول عنصر يحقق شرطًا معيَّنًا في حال تمرير دالة منطقية إليها.
-*<code>[[Kotlin/collections/findLast|findLast()]]</code>‎: تعيد العنصر الأخير من [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت عبرها والذي يحقق الشرط المنطقي <code>predicate</code> المُمرّر إليها. وإن لم يكن هناك  أي عنصر يحقق ذلك فستعيد <code>null.</code>
+*الدالة <code>[[Kotlin/collections/last|last()]]</code>‎: تجلب آخر عنصر من عناصر <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] التي استُدعيت معها إن لم يمرر إليها أي شيء، أو آخر عنصر يحق شرطًا معيَّنًا في حال تمرير دالة منطقية إليها.
+*الدالة <code>[[Kotlin/collections/find|find()]]</code>‎: تبحث على عنصر محدَّد ضمن عناصر [[Kotlin/Array|المصفوفة]] أو [[Kotlin/collections|المجموعة]] التي استُدعيت معها ثمَّ تعيد أول ظهور له.
+*الدالة <code>[[Kotlin/collections/filter|filter()‎]]</code>: ترشِّح عناصر <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] أو أزواج الخرائط المعطاة التي تحقِّق شرطًا معيَّنًا ثمّ تعيدها.
+* الدالة <code>[[Kotlin/collections/filterNot|filterNot()]]</code>‎: تعيد قائمةً تحوي عناصر <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] التي لا تحقق شرطًا منطقيًّا محدَّدًا. إن استدعيت مع خريطة (map)، فستعيد خريطة جديدة تحوي الأزواج التي لم تحقق ذلك الشرط المنطقي.
+*الدالة <code>[[Kotlin/collections/drop|drop()]]</code>‎: تعيد قائمة تحوي جميع عناصر <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/Array|المجموعة]] التي استُدعيت معها باستثناء آخر <code>n</code> عنصر.
 ==مصادر==
-*[https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/first.html الدالة  first()‎ في التوثيق الرسميّ للمكتبة القياسيّة في لغة Kotlin.]
+*[https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/first.html صفحة الدالة first()‎ في التوثيق الرسميّ للمكتبة القياسيّة في لغة Kotlin.]
 [[تصنيف:Kotlin]]
-[[تصنيف:Kotlin Functions]]
+[[تصنيف:Kotlin Function]]
+[[تصنيف:Kotlin Collection]]