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

مراجعة 16:57، 7 أغسطس 2018

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

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

إن استدعيت الدالة single()‎ مع مصفوفة أو مجموعة أو قائمة دون تمرير أي معامل، فستتحقَّق من احتواء تلك المصفوفة أو المجموعة أو القائمة على عنصر واحد فقط ثمَّ تعيده. وفي حال كانت تلك المصفوفة أو المجموعة أو القائمة فارغةً أو تحوي أكثر من عنصر واحد، فستطلق الدالة single()‎ استثناءً:

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

وإن استدعيت مع مصفوفة ومرِّر إليها الشرط predicate كمعامل، فستتحقَّق من تطابق عنصر واحد فقط من عناصر تلك المصفوفة مع ذلك الشرط. وفي حال تطابق أكثر من عنصر مع ذلك الشرط المنطقي أو لم يكن هنالك أي عنصر في المصفوفة، فستطلق الدالة single()‎ استثناءً:

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

fun <T> Iterable<T>.single(): T 

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

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

يعاد العنصر الوحيد الموجود في المصفوفة أو المجموعة أو القائمة المعطاة، أو العنصر الوحيد الذي حقق الشرط predicate (إن أعطي)، أو يُطلق استثناءٌ خلاف ذلك.

أمثلة

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

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

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

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

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

    print(array.single())
}

نتيجة تنفيذ المثال السابق هي:

Exception in thread "main" java.lang.IllegalArgumentException: Array has more than one element.
	at kotlin.collections.ArraysKt___ArraysKt.single(_Arrays.kt:2059)
	at TestKt.main(test.kt:4)

انظر أيضًا

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

مصادر

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

@@ سطر 1: / سطر 1: @@
-<noinclude>{{DISPLAYTITLE: الدالة <code>single()‎</code> في لغة Kotlin}}</noinclude>
+<noinclude>{{DISPLAYTITLE: الدالة <code>single()‎</code> في Kotlin}}</noinclude>
-تعيد الدالة<code>single()‎</code>العنصر الوحيد الموجود في [[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] أو [[Kotlin/List|اللائحة]] التي استُدعيت عبرها، وفي حال تمرير شرط منطقي <code>predicate</code> كمعامل (parameter) فستعيد العنصر الوحيد الذي يحقق ذلك الشرط المنطقي. أمّا في حال كان الكائن الذي استُدعيت عبره يحتوي أكثر من عنصر واحد (يحقق <code>predicate</code>  في حال تمريرها) أو لا يحتوي أي واحد (يحقق <code>predicate</code>  في حال تمريرها) فستطلق الدالة  <code>single()‎</code>[[Kotlin/exceptions|استثناءً]].
+تتحقَّق الدالة <code>single()‎</code> من حواية [[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] أو [[Kotlin/List|القائمة]] التي استُدعيت معها عنصرًا واحدًا فقط أو عنصرًا واحدًا محققًا لشرط معيَّن ثمَّ تعيده أو تطلق [[Kotlin/exceptions|استثناءً]] خلاف ذلك.
 ==البنية العامة==
-في حال استدعاء الدالة <code>single()‎</code> عبر <nowiki/>[[Kotlin/Array|مصفوفة]] دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك <nowiki/>[[Kotlin/Array|المصفوفة]]. وفي حال كانت تلك [[Kotlin/Array|المصفوفة]] فارغة أو تحتوي أكثر من عنصر واحد فستطلق الدالة  <code>single()‎</code>[[Kotlin/exceptions|استثناءً]]:<syntaxhighlight lang="kotlin">
+إن استدعيت الدالة <code>single()‎</code> مع <nowiki/>[[Kotlin/Array|مصفوفة]] أو [[Kotlin/collections|مجموعة]] أو قائمة دون تمرير أي معامل، فستتحقَّق من احتواء تلك <nowiki/>[[Kotlin/Array|المصفوفة]] أو المجموعة أو القائمة على عنصر واحد فقط ثمَّ تعيده. وفي حال كانت تلك [[Kotlin/Array|المصفوفة]] أو المجموعة أو القائمة فارغةً أو تحوي أكثر من عنصر واحد، فستطلق الدالة <code>single()‎</code> [[Kotlin/exceptions|استثناءً]]:<syntaxhighlight lang="kotlin">
 fun <T> Array<out T>.single(): T
 fun ByteArray.single(): Byte
@@ سطر 12: / سطر 12: @@
 fun BooleanArray.single(): Boolean
 fun CharArray.single(): Char
-</syntaxhighlight>في حال استدعاء الدالة <code>single()‎</code> عبر <nowiki/>[[Kotlin/Array|مصفوفة]] مع تمرير شرط منطقي <code>predicate</code> كمعامل (parameter) فستعيد العنصر الوحيد الذي يحقق ذلك الشرط المنطقي في تلك <nowiki/>[[Kotlin/Array|المصفوفة]]. وفي حال كانت تلك [[Kotlin/Array|المصفوفة]] تحتوي أكثر من عنصر واحد يحقق ذلك الشرط المنطقي أو لا تحتوي أي واحد فستطلق الدالة  <code>single()‎</code>[[Kotlin/exceptions|استثناءً]]:<syntaxhighlight lang="kotlin">
+</syntaxhighlight>وإن استدعيت مع <nowiki/>[[Kotlin/Array|مصفوفة]] ومرِّر إليها الشرط <code>predicate</code> كمعامل، فستتحقَّق من تطابق عنصر واحد فقط من عناصر تلك المصفوفة مع ذلك الشرط<nowiki/>. وفي حال تطابق أكثر من عنصر مع ذلك الشرط المنطقي أو لم يكن هنالك أي عنصر في المصفوفة، فستطلق الدالة <code>single()‎</code> [[Kotlin/exceptions|استثناءً]]:<syntaxhighlight lang="kotlin">
 inline fun <T> Array<out T>.single(
      predicate: (T) -> Boolean
@@ سطر 42: / سطر 42: @@
 ): T
-</syntaxhighlight>في حال استدعاء الدالة <code>single()‎</code> عبر <nowiki/>[[Kotlin/collections|مجموعة]] دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك <nowiki/>[[Kotlin/collections|المجموعة]]. وفي حال كانت تلك [[Kotlin/collections|المجموعة]] فارغة أو تحتوي أكثر من عنصر واحد فستطلق الدالة <code>single()‎</code>[[Kotlin/exceptions|استثناءً]]:<syntaxhighlight lang="kotlin">
 fun <T> Iterable<T>.single(): T
-</syntaxhighlight>في حال استدعاء الدالة <code>single()‎</code> عبر  [[Kotlin/List|لائحة]] دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك <nowiki/>[[Kotlin/List|اللائحة]]. وفي حال كانت تلك [[Kotlin/List|اللائحة]] فارغة أو تحتوي أكثر من عنصر واحد فستطلق الدالة <code>single()‎</code>[[Kotlin/exceptions|استثناءً]]:<syntaxhighlight lang="kotlin">
 fun <T> List<T>.single(): T
 </syntaxhighlight>
-==القيم المٌعادة==
+==القيم المعادة==
-العنصر الوحيد الموجود في [[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> (إن أعطي)، أو يُطلق [[Kotlin/exceptions|استثناءٌ]] خلاف ذلك.
 ==أمثلة==
-===استخدام الدالة <code>()single</code> مع المصفوفات===
+استعمال الدالة <code>()single</code>  للتأكد من احتواء مصفوفة على عنصر وحيد وجلبه:<syntaxhighlight lang="kotlin">
-تعرف الشيفرة الآتية  لائحة باسم <code>array</code> مكونة من عنصر واحد باستخدام الدالة <code>()arrayOf‎</code>، ثم تستخدم الدالة  <code>()single</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.single()) // 0
 }
 </syntaxhighlight>
-===استخدام الدالة <code>()single</code> مع المصفوفات: الحالة الثانية===
+استعمال الدالة  <code>()single</code> للتأكد من احتواء مصفوفة على عنصر وحيد وجلبه إن كان كذلك محقَّقًا:<syntaxhighlight lang="kotlin">
-تعرف الشيفرة الآتية  لائحة باسم <code>array</code> مكونة من عنصرين باستخدام الدالة <code>()arrayOf‎</code>، ثم تستخدم الدالة  <code>()single</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.single())
 }
+</syntaxhighlight>نتيجة تنفيذ المثال السابق هي:<syntaxhighlight lang="text">
+Exception in thread "main" java.lang.IllegalArgumentException: Array has more than one element.
+	at kotlin.collections.ArraysKt___ArraysKt.single(_Arrays.kt:2059)
+	at TestKt.main(test.kt:4)
 </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/singleOrNull|singleOrNull()]]</code>‎: تتحقَّق من حواية [[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] أو [[Kotlin/List|القائمة]] التي استُدعيت معها عنصرًا واحدًا فقط، أو عنصرًا واحدًا محققًا لشرط معيَّن ثمَّ تعيده، أو تعيد القيمة <code>null</code> خلاف ذلك.
+* الخاصية <code>[[Kotlin/collections/lastIndex|‎‎lastIndex]]</code>: تجلب الفهرس الأخير لمصفوفة أو قائمة.
+* الدالة <code>[[Kotlin/collections/find|find()]]</code>‎: تبحث على عنصر محدَّد ضمن عناصر <nowiki/>[[Kotlin/Array|المصفوفة]] أو <nowiki/>[[Kotlin/collections|المجموعة]] التي استُدعيت معها ثمَّ تعيد أول ظهور له.
 ==مصادر==
-*[https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/single.html الدالة  single()‎ في التوثيق الرسميّ للمكتبة القياسيّة في لغة Kotlin.]
+*[https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/single.html صفحة الدالة single()‎ في التوثيق الرسميّ للمكتبة القياسيّة في لغة Kotlin.]
 [[تصنيف:Kotlin]]
 [[تصنيف:Kotlin Functions]]