Kotlin/collections/single

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

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

في حال استدعاء الدالة single()‎ عبر مصفوفة دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك المصفوفة. وفي حال كانت تلك المصفوفة فارغة أو تحتوي أكثر من عنصر واحد فستطلق الدالة  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

في حال استدعاء الدالة single()‎ عبر مصفوفة مع تمرير شرط منطقي predicate كمعامل (parameter) فستعيد العنصر الوحيد الذي يحقق ذلك الشرط المنطقي في تلك المصفوفة. وفي حال كانت تلك المصفوفة تحتوي أكثر من عنصر واحد يحقق ذلك الشرط المنطقي أو لا تحتوي أي واحد فستطلق الدالة  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

في حال استدعاء الدالة single()‎ عبر مجموعة دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك المجموعة. وفي حال كانت تلك المجموعة فارغة أو تحتوي أكثر من عنصر واحد فستطلق الدالة single()‎استثناءً:

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

في حال استدعاء الدالة single()‎ عبر  لائحة دون تمرير أي معامل (parameter) فستعيد العنصر الوحيد الموجود في تلك اللائحة. وفي حال كانت تلك اللائحة فارغة أو تحتوي أكثر من عنصر واحد فستطلق الدالة single()‎استثناءً:

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

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

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

أمثلة

استخدام الدالة ()single مع المصفوفات

تعرف الشيفرة الآتية  لائحة باسم array مكونة من عنصر واحد باستخدام الدالة ()arrayOf‎، ثم تستخدم الدالة  ()single  على arrayوتطبع الناتج:

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

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

استخدام الدالة ()single مع المصفوفات

تعرف الشيفرة الآتية  لائحة باسم array مكونة من عنصرين باستخدام الدالة ()arrayOf‎، ثم تستخدم الدالة  ()single  على array،ولمّا كانت array تحتوي أكثر من عنصر واحد، فستطلق استثناءً:

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

print(array.single()) // إطلاق استثناء
}

أنظر أيضًا

• singleOrNull()‎: تعيد العنصر الوحيد الموجود في المصفوفة أو المجموعة أو اللائحة التي استُدعيت عبرها، وفي حال تمرير شرط منطقي predicate كمعامل (parameter) فستعيد العنصر الوحيد الذي يحقق ذلك الشرط المنطقي. وفي حال كان الكائن الذي استُدعيت عبره يحتوي أكثر من عنصر واحد (يحقق predicate في حال تمريرها) أو لا يحتوي أي واحد (يحقق predicate في حال تمريرها) فستعيد الدالة  single()‎ القيمة null.

مصادر

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