Kotlin/collections/binarySearch

تبحث الدالة binarySearch()‎ عن عنصر معين في المجموعة أو مجال من المجموعة (Collection) باستخدام خوارزميَّة البحث الثنائي (binary search algorithm) وتعيد فهرس موقعه. ويجب أن تكون المجموعة مرتبَّةً وفق المُقارِن comparator وإلا فستكون النتيجة المعادة غير مُحدّدة.

إن احتوت المصفوفة على عناصر متساوية، فلا يمكن التوقع أيها سيُعاد.

تُعيد الدالة فهرس العنصر المبحوث عنه إن كان موجودًا في المجال المحدَّد؛ خلاف ذلك، فستعيد القيمة السالبة لنقطة الإدراج (‎-insertion point - 1‎)، وهي الفهرس حيث يجب أن يُدرج العنصر حتى تبقى المصفوفة (أو المجال المحدَّد) مرتبة وفقا للمُقارن المحدَّد comparator.

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

fun <T> Array<out T>.binarySearch(
    element: T, 
    comparator: Comparator<in T>, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int

بيئة التشغيل: JVM

تبحث الدالة binarySearch()‎ عن العنصر element في كامل المصفوفة التي استُدعيت معها أو في مجال محدِّد ضمنها باستخدام خوارزميَّة البحث الثنائي (binary search algorithm) وتعيد فهرس موقعه. يجب أن تكون المصفوفة مرتبة وفق المُقارِن comparator وإلا فستكون النتيجة غير مُحدّدة.

إن احتوت المصفوفة على عناصر متساوية، فلا يمكن التوقع أيها سيُعاد.

تُعيد الدالة فهرس العنصر المبحوث عنه إن كان موجودًا في المجال المحدد؛ خلا ذلك، ستعيد القيمة السالبة لنقطة الإدراج (‎-insertion point - 1‎)، وهي الفهرس حيث يجب أن يُدرج العنصر حتى تبقى المصفوفة (أو المجال المحدَّد) مرتبة وفقا للمُقارن المحدَّد comparator.

fun <T> Array<out T>.binarySearch(
    element: T, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int
fun ByteArray.binarySearch(
    element: Byte, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int
fun ShortArray.binarySearch(
    element: Short, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int
fun IntArray.binarySearch(
    element: Int, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int
fun LongArray.binarySearch(
    element: Long, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int
fun FloatArray.binarySearch(
    element: Float, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int
fun DoubleArray.binarySearch(
    element: Double, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int
fun CharArray.binarySearch(
    element: Char, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int

fun <T : Comparable<T>> List<T?>.binarySearch(
    element: T?, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int

تبحث الدالة binarySearch()‎ عن العنصر element في المجموعة (Collection) التي استُدعيت معها أو في مجال محدِّد ضمنها باستخدام خوارزمية البحث الثنائي (binary search algorithm) وتعيد فهرس موقعه. ينبغي أن تكون المجموعة مرتبة ترتيبًا تصاعديًّا وفق المُقارِن comparator وإلا فستكون النتيجة غير مُحدّدة.

إن احتوت المجموعة على عناصر متساوية، فلا يمكن التوقع أيها سيُعاد.

تُعدُّ القيمة العدميَّة null أصغر من أي عنصر آخر غير معدوم.

تُعيد الدالة فهرس العنصر المبحوث عنه إن كان موجودًا في المجال المحدَّد؛ خلا ذلك، ستعيد القيمة السالبة لنقطة الإدراج (‎-insertion point - 1‎)، وهي الفهرس حيث يجب أن يُدرج العنصر حتى تبقى المصفوفة (أو المجال المحدَّد) مرتبة وفقا للمُقارن المحدد comparator.

fun <T> List<T>.binarySearch(
    element: T, 
    comparator: Comparator<in T>, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int

fun <T> List<T>.binarySearch(
    element: T, 
    comparator: Comparator<in T>, 
    fromIndex: Int = 0, 
    toIndex: Int = size
): Int

بيئة التشغيل: JS

تبحث الدالة binarySearch()‎ عن العنصر element في المجموعة (Collection) التي استُدعيت معها أو في مجال محدِّد ضمنها باستخدام خوارزمية البحث الثنائي (binary search algorithm) وتعيد فهرس موقعه. ينبغي أن تكون المجموعة مرتبة ترتيبًا تصاعديًّا وفق المُقارِن comparator وإلا فستكون النتيجة غير مُحدّدة.

إن احتوت المجموعة على عناصر متساوية، فلا يمكن التوقع أيها سيُعاد.

تُعدُّ القيمة العدميَّة null أصغر من أي عنصر آخر غير معدوم.

تُعيد الدالة فهرس العنصر المبحوث عنه إن كان موجودًا في المجال المحدَّد؛ خلا ذلك، ستعيد القيمة السالبة لنقطة الإدراج (‎-insertion point - 1‎)، وهي الفهرس حيث يجب أن يُدرج العنصر حتى تبقى المصفوفة (أو المجال المحدَّد) مرتبة وفقا للمُقارن المحدَّد comparator.

المعاملات

element

العنصر المراد البحث عنه.

comparator

المقارن المستعمل في عملية الترتيب.

fromIndex

عدد صحيح يشير إلى العنصر الذي يمثل بداية المجال المراد البحث ضمنه. القيمة الافتراضية هي: 0.

toIndex

عدد صحيح يشير إلى العنصر الذي يمثل نهاية المجال المراد البحث ضمنه (لا يدخل هذا العنصر ضمن المجال). القيمة الافتراضية هي: size.

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

تُعيد الدالة فهرس العنصر المبحوث عنه إن كان موجودًا في المجال المحدَّد؛ خلا ذلك، ستعيد القيمة السالبة لنقطة الإدراج (‎-insertion point - 1‎)، وهي الفهرس حيث يجب أن يُدرج العنصر حتى تبقى المصفوفة (أو المجال المحدَّد) مرتبة وفقا للمُقارن المحدَّد comparator.

أمثلة

استعمال الدالة ()binarySearch البحث عن عنصر في قائمة:

fun main(args: Array<String>) {
    val list = listOf('a', 'b', 'c', 'd', 'e')

    println(list.binarySearch('d')) // 3
}

استعمال الدالة ()binarySearch البحث عن عنصر في مجال محدد في قائمة:

fun main(args: Array<String>) {
    val list = listOf('a', 'b', 'c', 'd', 'e')

    println(list.binarySearch('d', fromIndex = 1, toIndex = 3)) // -4
}

انظر أيضًا

• الدالة contains()‎: تعيد القيمة true إن كان العنصر المراد البحث عنه موجودًا في المصفوفة أو المجموعة التي استُدعيت معها.

مصادر

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