Kotlin/collections/filter

ترشِّح الدالة filter()‎ عناصر المصفوفة أو المجموعة أو أزواج الخرائط المعطاة التي تحقِّق شرطًا معيَّنًا ثمّ تعيدها.

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

يمكن استدعاء الدالة filter()‎ مع المصفوفات والمجموعات:

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

ومع الخرائط أيضًا:

inline fun <K, V> Map<out K, V>.filter(
    predicate: (Entry<K, V>) -> Boolean
): Map<K, V>

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

المعاملات

predicate

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

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

إن أعطيت مصفوفة أو مجموعة، فستُعاد قائمة تحوي العناصر التي أعيدت القيمة true معها عند تطبيق الدالة predicate()‎ المُمرَّرة عليها. أمَّا إن أعطيت خريطة، فستُعاد خريطة جديدة تحوي الأزواج (قيمة/مفتاح) التي أعيدت القيمة true معها عند تطبيق الدالة predicate()‎ المعطاة عليها؛ ترتَّب الأزواج المعادة في هذه الخريطة بنفس ترتيبها في الخريطة الأصليَّة.

أمثلة

استعمال الدالة ()filter مع مصفوفة لترشيح العناصر التي تقل قيمتها عن القيمة 3:

fun main(args: Array<String>) {
    val array = arrayOf(1, 2, 3, 4, 5, 6)
    println(array.filter { it < 3 }) // [1, 2]
}

استعمال الدالة ()filter مع خريطة لترشيح الأزواج (قيمة/مفتاح) التي تكون فيها القيمة أقل من 2:

fun main(args: Array<String>) {
    val map = mapOf("key1" to 1, "key2" to 2, "key3" to 3)
    val filteredMap = map.filter { it.value < 2 }

    println(filteredMap) // {key1=1}
}

استعمال الدالة ()filter مع خريطة لترشيح الأزواج (قيمة/مفتاح) التي تكون فيها القيمة مساوية إلى القيمة 0 (لاحظ في هذه الحالة أنَّنا سنحصل على خريطة فارغة لعدم تطابق الأزواج مع الشرط المعطى):

fun main(args: Array<String>) {
    val map = mapOf("key1" to 1, "key2" to 2, "key3" to 3)
    val filteredMap = map.filter { it.value == 0 }

    println(filteredMap) // {}
}

انظر أيضًا

• الدالة filterTo()‎: تشبه هذه الدالة في جميع النواحي باستثناء أنها تضيف الناتج إلى المعامل الممرر إليها.
• الدالة filterIndexed()‎: ترشِّح ترشِّح عناصر المصفوفة أو المجموعة المعطاة التي تُعاد القيمة true معها عند تطبيق الدالة predicate()‎ المُمرّر عليها، إذ يمرَّر فهرس كل عنصر وقيمته إلى الدالة predicate()‎ ثم تعيد بدورها قيمة منطقيَّة.
• الدالة fill()‎: تبدِّل قيمة جديدة معطاة مكان عناصر محدَّدة في المصفوفة أو القائمة التي تستدعى معها.
• الدالة elementAtOrElse()‎: تجلب عنصرًا ذي فهرس معيَّن من المصفوفة أو المجموعة التي استُدعيت معها. إن كان الفهرس المعطى خارج حدود المصفوفة أو المجموعة، فستُعيد الدالة ناتج استدعاء دالة معينة.
• الدالة drop()‎: تعيد قائمة تحوي جميع عناصر المصفوفة أو المجموعة التي استُدعيت معها باستثناء آخر n عنصر.

مصادر

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