azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve the documentation of binarySearch functions.

Browse Source 
#KT-10198 Fixed
This commit is contained in:
Ilya Gorbunov
2016-02-17 04:15:15 +03:00
parent 103f8300fb
commit 0e0455daeb
3 changed files with 132 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/stdlib/src/generated/_Arrays.kt
+63 -9
View File
@@ -11895,7 +11895,13 @@ public fun CharArray.asList(): List<Char> {
}
/**
* Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted according to the specified [comparator].
* Searches the array or the range of the array for the provided [element] using the binary search algorithm.
* The array is expected to be sorted according to the specified [comparator], otherwise the result is undefined.
* If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
* @return the index of the element, if it is contained in the array within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the array (or the specified subrange of array) still remains sorted according to the specified [comparator].
*/
@kotlin.jvm.JvmVersion
public fun <T> Array<out T>.binarySearch(element: T, comparator: Comparator<in T>, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11903,7 +11909,13 @@ public fun <T> Array<out T>.binarySearch(element: T, comparator: Comparator<in T
}
/**
* Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
* Searches the array or the range of the array for the provided [element] using the binary search algorithm.
* The array is expected to be sorted, otherwise the result is undefined.
* If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
* @return the index of the element, if it is contained in the array within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the array (or the specified subrange of array) still remains sorted.
*/
@kotlin.jvm.JvmVersion
public fun <T> Array<out T>.binarySearch(element: T, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11911,7 +11923,13 @@ public fun <T> Array<out T>.binarySearch(element: T, fromIndex: Int = 0, toIndex
}
/**
* Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
* Searches the array or the range of the array for the provided [element] using the binary search algorithm.
* The array is expected to be sorted, otherwise the result is undefined.
* If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
* @return the index of the element, if it is contained in the array within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the array (or the specified subrange of array) still remains sorted.
*/
@kotlin.jvm.JvmVersion
public fun ByteArray.binarySearch(element: Byte, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11919,7 +11937,13 @@ public fun ByteArray.binarySearch(element: Byte, fromIndex: Int = 0, toIndex: In
}
/**
* Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
* Searches the array or the range of the array for the provided [element] using the binary search algorithm.
* The array is expected to be sorted, otherwise the result is undefined.
* If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
* @return the index of the element, if it is contained in the array within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the array (or the specified subrange of array) still remains sorted.
*/
@kotlin.jvm.JvmVersion
public fun ShortArray.binarySearch(element: Short, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11927,7 +11951,13 @@ public fun ShortArray.binarySearch(element: Short, fromIndex: Int = 0, toIndex:
}
/**
* Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
* Searches the array or the range of the array for the provided [element] using the binary search algorithm.
* The array is expected to be sorted, otherwise the result is undefined.
* If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
* @return the index of the element, if it is contained in the array within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the array (or the specified subrange of array) still remains sorted.
*/
@kotlin.jvm.JvmVersion
public fun IntArray.binarySearch(element: Int, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11935,7 +11965,13 @@ public fun IntArray.binarySearch(element: Int, fromIndex: Int = 0, toIndex: Int
}
/**
* Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
* Searches the array or the range of the array for the provided [element] using the binary search algorithm.
* The array is expected to be sorted, otherwise the result is undefined.
* If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
* @return the index of the element, if it is contained in the array within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the array (or the specified subrange of array) still remains sorted.
*/
@kotlin.jvm.JvmVersion
public fun LongArray.binarySearch(element: Long, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11943,7 +11979,13 @@ public fun LongArray.binarySearch(element: Long, fromIndex: Int = 0, toIndex: In
}
/**
* Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
* Searches the array or the range of the array for the provided [element] using the binary search algorithm.
* The array is expected to be sorted, otherwise the result is undefined.
* If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
* @return the index of the element, if it is contained in the array within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the array (or the specified subrange of array) still remains sorted.
*/
@kotlin.jvm.JvmVersion
public fun FloatArray.binarySearch(element: Float, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11951,7 +11993,13 @@ public fun FloatArray.binarySearch(element: Float, fromIndex: Int = 0, toIndex:
}
/**
* Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
* Searches the array or the range of the array for the provided [element] using the binary search algorithm.
* The array is expected to be sorted, otherwise the result is undefined.
* If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
* @return the index of the element, if it is contained in the array within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the array (or the specified subrange of array) still remains sorted.
*/
@kotlin.jvm.JvmVersion
public fun DoubleArray.binarySearch(element: Double, fromIndex: Int = 0, toIndex: Int = size): Int {
@@ -11959,7 +12007,13 @@ public fun DoubleArray.binarySearch(element: Double, fromIndex: Int = 0, toIndex
}
/**
* Searches array or range of array for provided element index using binary search algorithm. Array is expected to be sorted.
* Searches the array or the range of the array for the provided [element] using the binary search algorithm.
* The array is expected to be sorted, otherwise the result is undefined.
* If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
* @return the index of the element, if it is contained in the array within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the array (or the specified subrange of array) still remains sorted.
*/
@kotlin.jvm.JvmVersion
public fun CharArray.binarySearch(element: Char, fromIndex: Int = 0, toIndex: Int = size): Int {
libraries/stdlib/src/kotlin/collections/Collections.kt
+43 -9
View File
@@ -141,10 +141,18 @@ private fun <T> Array<out T>.copyToArrayOfAny(isVarargs: Boolean): Array<Any?> =
Arrays.copyOf(this, this.size, Array<Any?>::class.java)
/**
* Searches this list or its range for the provided [element] index using binary search algorithm.
* The list is expected to be sorted into ascending order according to the Comparable natural ordering of its elements.
* Searches this list or its range for the provided [element] using the binary search algorithm.
* The list is expected to be sorted into ascending order according to the Comparable natural ordering of its elements,
* otherwise the result is undefined.
*
* If the list contains multiple elements equal to the specified object, there is no guarantee which one will be found.
* If the list contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
*
* `null` value is considered to be less than any non-null value.
*
* @return the index of the element, if it is contained in the list within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the list (or the specified subrange of list) still remains sorted.
*/
public fun <T: Comparable<T>> List<T?>.binarySearch(element: T?, fromIndex: Int = 0, toIndex: Int = size): Int {
rangeCheck(size, fromIndex, toIndex)
@@ -168,10 +176,18 @@ public fun <T: Comparable<T>> List<T?>.binarySearch(element: T?, fromIndex: Int
}
/**
* Searches this list or its range for the provided [element] index using binary search algorithm.
* The list is expected to be sorted into ascending order according to the specified [comparator].
* Searches this list or its range for the provided [element] using the binary search algorithm.
* The list is expected to be sorted into ascending order according to the specified [comparator],
* otherwise the result is undefined.
*
* If the list contains multiple elements equal to the specified object, there is no guarantee which one will be found.
* If the list contains multiple elements equal to the specified [element], there is no guarantee which one will be found.
*
* `null` value is considered to be less than any non-null value.
*
* @return the index of the element, if it is contained in the list within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the list (or the specified subrange of list) still remains sorted according to the specified [comparator].
*/
public fun <T> List<T>.binarySearch(element: T, comparator: Comparator<in T>, fromIndex: Int = 0, toIndex: Int = size): Int {
rangeCheck(size, fromIndex, toIndex)
@@ -195,10 +211,19 @@ public fun <T> List<T>.binarySearch(element: T, comparator: Comparator<in T>, fr
}
/**
* Searches this list or its range for an index of an element with the provided [key] using binary search algorithm.
* Searches this list or its range for an element having the key returned by the specified [selector] function
* equal to the provided [key] value using the binary search algorithm.
* The list is expected to be sorted into ascending order according to the Comparable natural ordering of keys of its elements.
* otherwise the result is undefined.
*
* If the list contains multiple elements with the specified [key], there is no guarantee which one will be found.
*
* `null` value is considered to be less than any non-null value.
*
* @return the index of the element with the specified [key], if it is contained in the list within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the list (or the specified subrange of list) still remains sorted.
*/
public inline fun <T, K : Comparable<K>> List<T>.binarySearchBy(key: K?, fromIndex: Int = 0, toIndex: Int = size, crossinline selector: (T) -> K?): Int =
binarySearch(fromIndex, toIndex) { compareValues(selector(it), key) }
@@ -207,11 +232,20 @@ public inline fun <T, K : Comparable<K>> List<T>.binarySearchBy(key: K?, fromInd
//public fun <T, K> List<T>.binarySearchBy(key: K, comparator: Comparator<K>, fromIndex: Int = 0, toIndex: Int = size(), selector: (T) -> K): Int =
// binarySearch(fromIndex, toIndex) { comparator.compare(selector(it), key) }
/**
* Searches this list or its range for an index of an element for which [comparison] function returns zero.
* The list is expected to be sorted into ascending order according to the provided [comparison].
* Searches this list or its range for an element for which [comparison] function returns zero using the binary search algorithm.
* The list is expected to be sorted into ascending order according to the provided [comparison],
* otherwise the result is undefined.
*
* If the list contains multiple elements for which [comparison] returns zero, there is no guarantee which one will be found.
*
* @param comparison function that compares an element of the list with the element being searched.
*
* @return the index of the found element, if it is contained in the list within the specified range;
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the list (or the specified subrange of list) still remains sorted.
*/
public fun <T> List<T>.binarySearch(fromIndex: Int = 0, toIndex: Int = size, comparison: (T) -> Int): Int {
rangeCheck(size, fromIndex, toIndex)