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.

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

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

أمثلة

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

تعرِّف الشيفرة الآتية قائمة باسم list مكوَّنة من خمسة حروف باستعمال ()listOf ثم تبحث فيها عن الحرف 'd' باستخدام الدالة ()binarySearch وتطبع الناتج:

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

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

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

تعرِّف الشيفرة الآتية قائمة باسم list مكونة من خمسة حروف ()listOf ثمَّ تبحث في مجال محدَّد يبدأ من العنصر ذي الفهرس 1 (أي fromIndex = 1) وينتهي عند العنصر ذي الفهرس 3 (أي toIndex = 3) عن الحرف 'd' باستخدام الدالة ()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 إن كان العنصر المراد البحث عنه موجودًا في المصفوفة أو المجموعة التي استُدعيت معها.
• صفحة المجموعة (Collection).

مصادر

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