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

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

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

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

إن استدعيت الدالة singleOrNull()‎ مع مصفوفة أو مجموعة أو قائمة دون تمرير أي معامل، فستتحقَّق من احتواء تلك المصفوفة أو المجموعة أو القائمة على عنصر واحد فقط ثمَّ تعيده. وفي حال كانت تلك المصفوفة أو المجموعة أو القائمة فارغةً أو تحوي أكثر من عنصر واحد، فستعيد الدالة singleOrNull()‎ القيمة 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?

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

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

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

المعاملات

`predicate`

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

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

يعاد العنصر الوحيد الموجود في المصفوفة أو المجموعة أو القائمة المعطاة، أو العنصر الوحيد الذي حقَّق الشرط predicate (إن أعطي)، أو القيمة null خلاف ذلك.

أمثلة

استعمال الدالة ()singleOrNull للتأكد من احتواء مصفوفة على عنصر وحيد وجلبه:

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

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

استعمال الدالة ()singleOrNull للتأكد من احتواء مصفوفة على عنصر وحيد وجلبه إن كان كذلك محقَّقًا:

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

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

انظر أيضًا

الدالة single()‎: تتحقَّق من حواية المصفوفة أو المجموعة أو القائمة التي استُدعيت معها عنصرًا واحدًا فقط أو عنصرًا واحدًا محققًا لشرط معيَّن ثمَّ تعيده أو تطلق استثناءً خلاف ذلك.
الدالة slice()‎: تقطع جزءًا محدَّدًا من المصفوفة أو القائمة التي استُدعيت معها ثمَّ تعيده في قائمة.

مصادر

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

@@ سطر 1: / سطر 1: @@
-<noinclude>{{DISPLAYTITLE: الدالة <code>singleOrNull()‎</code> في لغة Kotlin}}</noinclude>
+<noinclude>{{DISPLAYTITLE: الدالة <code>singleOrNull()‎</code> في Kotlin}}</noinclude>
-تعيد الدالة<code>singleOrNull()‎</code>العنصر الوحيد الموجود في [[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] أو [[Kotlin/List|اللائحة]] التي استُدعيت عبرها، وفي حال تمرير شرط منطقي <code>predicate</code> كمعامل (parameter) فستعيد العنصر الوحيد الذي يحقق ذلك الشرط المنطقي. أمّا في حال كانت الكائن الذي استُدعيت عبره يحتوي أكثر من عنصر واحد (يحقق <code>predicate</code>  في حال تمريرها) أو لا يحتوي أي واحد (يحقق <code>predicate</code>  في حال تمريرها) فستطلق الدالة  <code>singleOrNull()‎</code>[[Kotlin/exceptions|استثناءً]].
+تتحقَّق الدالة <code>singleOrNull()‎</code> من حواية [[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] أو [[Kotlin/List|القائمة]] التي استُدعيت معها عنصرًا واحدًا فقط، أو عنصرًا واحدًا محققًا لشرط معيَّن ثمَّ تعيده، أو تعيد القيمة <code>null</code> خلاف ذلك.
 ==البنية العامة==
-في حال استدعاء الدالة <code>singleOrNull()‎</code> عبر <nowiki/>[[Kotlin/Array|مصفوفة]] دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك <nowiki/>[[Kotlin/Array|المصفوفة]]. وفي حال كانت تلك [[Kotlin/Array|المصفوفة]] فارغة أو تحتوي أكثر من عنصر واحد فستطلق الدالة  <code>singleOrNull()‎</code>[[Kotlin/exceptions|استثناءً]]:<syntaxhighlight lang="kotlin">
+إن استدعيت الدالة <code>singleOrNull()‎</code> مع <nowiki/>[[Kotlin/Array|مصفوفة]] أو [[Kotlin/collections|مجموعة]] أو قائمة دون تمرير أي معامل، فستتحقَّق من احتواء تلك [[Kotlin/Array|المصفوفة]] أو المجموعة أو القائمة على عنصر واحد فقط ثمَّ تعيده. وفي حال كانت تلك [[Kotlin/Array|المصفوفة]] أو المجموعة أو القائمة فارغةً أو تحوي أكثر من عنصر واحد، فستعيد الدالة <code>singleOrNull()‎</code> القيمة <code>null</code>:<syntaxhighlight lang="kotlin">
-fun <T> Array<out T>.single(): T
+fun <T> Array<out T>.singleOrNull(): T?
-fun ByteArray.single(): Byte
+fun ByteArray.singleOrNull(): Byte?
-fun ShortArray.single(): Short
+fun ShortArray.singleOrNull(): Short?
-fun IntArray.single(): Int
+fun IntArray.singleOrNull(): Int?
-fun LongArray.single(): Long
+fun LongArray.singleOrNull(): Long?
-fun FloatArray.single(): Float
+fun FloatArray.singleOrNull(): Float?
-fun DoubleArray.single(): Double
+fun DoubleArray.singleOrNull(): Double?
-fun BooleanArray.single(): Boolean
+fun BooleanArray.singleOrNull(): Boolean?
-fun CharArray.single(): Char
+fun CharArray.singleOrNull(): Char?
-</syntaxhighlight>في حال استدعاء الدالة <code>singleOrNull()‎</code> عبر <nowiki/>[[Kotlin/Array|مصفوفة]] مع تمرير شرط منطقي <code>predicate</code> كمعامل (parameter) فستعيد العنصر الوحيد الذي يحقق ذلك الشرط المنطقي في تلك <nowiki/>[[Kotlin/Array|المصفوفة]]. وفي حال كانت تلك [[Kotlin/Array|المصفوفة]] تحتوي أكثر من عنصر واحد يحقق ذلك الشرط المنطقي أو لا تحتوي أي واحد فستطلق الدالة  <code>single()‎</code>[[Kotlin/exceptions|استثناءً]]:<syntaxhighlight lang="kotlin">
-inline fun <T> Array<out T>.single(
+fun <T> Iterable<T>.singleOrNull(): T?
+fun <T> List<T>.singleOrNull(): T?
+</syntaxhighlight>وإن استدعيت مع [[Kotlin/Array|مصفوفة]] ومرِّر إليها الشرط <code>predicate</code> كمعامل، فستتحقَّق من تطابق عنصر واحد فقط من عناصر تلك المصفوفة مع ذلك الشرط. وفي حال تطابق أكثر من عنصر مع ذلك الشرط المنطقي أو لم يكن هنالك أي عنصر في المصفوفة، فستعيد الدالة <code>singleOrNull()‎</code> القيمة <code>null</code>:<syntaxhighlight lang="kotlin">
+inline fun <T> Array<out T>.singleOrNull(
      predicate: (T) -> Boolean
-): T
+): T?
-inline fun ByteArray.single(
+inline fun ByteArray.singleOrNull(
      predicate: (Byte) -> Boolean
-): Byte
+): Byte?
-inline fun ShortArray.single(
+inline fun ShortArray.singleOrNull(
      predicate: (Short) -> Boolean
-): Short
+): Short?
-inline fun IntArray.single(predicate: (Int) -> Boolean): Int (source)
+inline fun IntArray.singleOrNull(
-inline fun LongArray.single(
+    predicate: (Int) -> Boolean
+): Int?
+inline fun LongArray.singleOrNull(
      predicate: (Long) -> Boolean
-): Long
+): Long?
-inline fun FloatArray.single(
+inline fun FloatArray.singleOrNull(
      predicate: (Float) -> Boolean
-): Float
+): Float?
-inline fun DoubleArray.single(
+inline fun DoubleArray.singleOrNull(
      predicate: (Double) -> Boolean
-): Double
+): Double?
-inline fun BooleanArray.single(
+inline fun BooleanArray.singleOrNull(
      predicate: (Boolean) -> Boolean
-): Boolean
+): Boolean?
-inline fun CharArray.single(
+inline fun CharArray.singleOrNull(
      predicate: (Char) -> Boolean
-): Char
+): Char?
-inline fun <T> Iterable<T>.single(
+inline fun <T> Iterable<T>.singleOrNull(
      predicate: (T) -> Boolean
-): T
+): T?
-</syntaxhighlight>في حال استدعاء الدالة <code>singleOrNull()‎</code> عبر <nowiki/>[[Kotlin/collections|مجموعة]] دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك <nowiki/>[[Kotlin/collections|المجموعة]]. وفي حال كانت تلك [[Kotlin/collections|المجموعة]] فارغة أو تحتوي أكثر من عنصر واحد فستطلق الدالة <code>singleOrNull()‎</code>[[Kotlin/exceptions|استثناءً]]:<syntaxhighlight lang="kotlin">
+</syntaxhighlight>
-fun <T> Iterable<T>.single(): T
-</syntaxhighlight>في حال استدعاء الدالة <code>singleOrNull()‎</code> عبر  [[Kotlin/List|لائحة]] دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك <nowiki/>[[Kotlin/List|اللائحة]]. وفي حال كانت تلك [[Kotlin/List|اللائحة]] فارغة أو تحتوي أكثر من عنصر واحد فستطلق الدالة <code>singleOrNull()‎</code>[[Kotlin/exceptions|استثناءً]]:<syntaxhighlight lang="kotlin">
+== المعاملات ==
-fun <T> List<T>.single(): T
-</syntaxhighlight>
+=== <code>predicate</code> ===
-==القيم المٌعادة==
+دالة تطبق على كل عنصر من عناصر المصفوفة أو المجموعة أو القائمة المعطاة، إذ يمرر إليها العنصر ثم تعيد القيمة المنطقية المقابلة له.
-العنصر الوحيد الموجود في [[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] أو [[Kotlin/List|اللائحة]] التي استُدعيت عبرها، وفي حال تمرير شرط منطقي <code>predicate</code> كمعامل (parameter) فستعيد العنصر الوحيد الذي يحقق ذلك الشرط المنطقي. أما في حال كانت تلك [[Kotlin/Array|المصفوفة]] تحتوي أكثر من عنصر واحد (يحقق <code>predicate</code>  في حال تمريرها) أو لا تحتوي أي واحد (يحقق <code>predicate</code>  في حال تمريرها) فستطلق الدالة <code>single()‎</code>[[Kotlin/exceptions|استثناءً]].
+==القيم المعادة==
+يعاد العنصر الوحيد الموجود في [[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] أو [[Kotlin/List|القائمة]] المعطاة، أو العنصر الوحيد الذي حقَّق الشرط <code>predicate</code> (إن أعطي)، أو القيمة <code>null</code> خلاف ذلك.
 ==أمثلة==
-===استخدام الدالة <code>()singleOrNull</code> مع المصفوفات===
+استعمال الدالة <code>()singleOrNull</code>  للتأكد من احتواء مصفوفة على عنصر وحيد وجلبه:<nowiki/><syntaxhighlight lang="kotlin">
-تعرف الشيفرة الآتية  لائحة باسم <code>array</code> مكونة من عنصر واحد باستخدام الدالة <code>()arrayOf‎</code>، ثم تستخدم الدالة  <code>()singleOrNull</code>  على <code>array</code>وتطبع الناتج:<syntaxhighlight lang="kotlin">
 fun main(args: Array<String>) {
-var array = arrayOf(0)
+    var array = arrayOf(0)
-print(array.single()) // 0
+    print(array.singleOrNull()) // 0
 }
 </syntaxhighlight>
-===استخدام الدالة <code>()singleOrNull</code> مع المصفوفات===
+استعمال الدالة  <code>()singleOrNull</code> للتأكد من احتواء مصفوفة على عنصر وحيد وجلبه إن كان كذلك محقَّقًا:<syntaxhighlight lang="kotlin">
-تعرف الشيفرة الآتية  لائحة باسم <code>array</code> مكونة من عنصرين باستخدام الدالة <code>()arrayOf‎</code>، ثم تستخدم الدالة  <code>()singleOrNull</code>  على <code>array</code>،ولمّا كانت <code>array</code> تحتوي أكثر من عنصر واحد، فستطلق [[Kotlin/exceptions|استثناءً]]:<syntaxhighlight lang="kotlin">
 fun main(args: Array<String>) {
-var array = arrayOf(0, 6)
+    var array = arrayOf(0, 6)
-print(array.single()) // إطلاق استثناء
+    print(array.singleOrNull()) // null
 }
 </syntaxhighlight>
-==أنظر أيضًا==
+==انظر أيضًا==
-*<code>[[Kotlin/collections/singleOrNull|singleOrNull()]]</code>‎: تعيد العنصر الوحيد الموجود في [[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] أو [[Kotlin/List|اللائحة]] التي استُدعيت عبرها، وفي حال تمرير شرط منطقي <code>predicate</code> كمعامل (parameter) فستعيد العنصر الوحيد الذي يحقق ذلك الشرط المنطقي. وفي حال كان الكائن الذي استُدعيت عبره يحتوي أكثر من عنصر واحد (يحقق <code>predicate</code>  في حال تمريرها) أو لا يحتوي أي واحد (يحقق <code>predicate</code>  في حال تمريرها) فستعيد الدالة  <code>single()‎</code> القيمة <code>null</code>.
+*الدالة <code>[[Kotlin/collections/single|single()]]</code>‎: تتحقَّق من حواية [[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] أو [[Kotlin/List|القائمة]] التي استُدعيت معها عنصرًا واحدًا فقط أو عنصرًا واحدًا محققًا لشرط معيَّن ثمَّ تعيده أو تطلق [[Kotlin/exceptions|استثناءً]] خلاف ذلك.
+* الدالة <code>[[Kotlin/collections/slice|slice()]]</code>‎: تقطع جزءًا محدَّدًا من <nowiki/>[[Kotlin/Array|المصفوفة]] أو القائمة التي استُدعيت معها ثمَّ تعيده في قائمة.
 ==مصادر==
-*[https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/single.html الدالة  singleOrNull()‎ في التوثيق الرسميّ للمكتبة القياسيّة في لغة Kotlin.]
+*[https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/single-or-null.html صفحة الدالة singleOrNull()‎ في التوثيق الرسميّ للمكتبة القياسيّة في لغة Kotlin.]
 [[تصنيف:Kotlin]]
-[[تصنيف:Kotlin Functions]]
+[[تصنيف:Kotlin Function]]
+[[تصنيف:Kotlin Collection]]