+shiffle

+List.binarySearch

docs/Array.md

@@ -0,0 +1,37 @@
+# Array
+
+It's an interface if the [Collection] that provides indexing access, like `array[3] = 0`.
+Array therefore implements [Iterable] too. The well known implementatino of the `Array` is
+[List].
+
+Array adds the following methods:
+
+## Binary search
+
+When applied to sorted arrays, binary search allow to quicly find an index of the element in the array, or where to insert it to keep order:
+
+    val coll = [1,2,3,4,5]
+    assertEquals( 2, coll.binarySearch(3) )
+    assertEquals( 0, coll.binarySearch(1) )
+    assertEquals( 4, coll.binarySearch(5) )
+
+    val src = (1..50).toList().shuffled()
+    val result = []
+    for( x in src ) {
+        val i = result.binarySearch(x)
+        assert( i < 0 )
+        result.insertAt(-i-1, x)
+    }
+    assertEquals( src.sorted(), result )
+    >>> void
+
+So `binarySearch(x)` returns:
+
+- index of `x`, a non-negative number
+- negative: `x` not found, but if inserted at position `-returnedValue-1` will leave array sorted.
+
+To pre-sort and array use `Iterable.sorted*` or in-place `List.sort*` families, see [List] and [Iterable] docs.
+
+[Collection]: Collection.md
+[Iterable]: Iterable.md
+[List]: List.md

docs/Iterable.md

@@ -95,6 +95,7 @@ These, again, does the thing:
 | sortedBy(predicate)    | sort by comparing results of the predicate function                             |
 | joinToString(s,t)      | convert iterable to string, see (2)                                             |
 | reversed()             | create a list containing items from this in reverse order                       |
+| shuffled()             | create a listof shiffled elements                                               |
 
 (1)
 : throws `NoSuchElementException` if there is no such element

docs/List.md

@@ -128,8 +128,9 @@ List could be sorted in place, just like [Collection] provide sorted copies, in
 | `[Range]`                     | get slice of the array (copy)                | Range       |
 | `+=`                          | append element(s) (2)                        | List or Obj |
 | `sort()`                      | in-place sort, natural order                 | void        |
-| 'sortBy(predicate)`           | in place sort bu `predicate` call result (3) | void        |
-| `SortWith(comparator)         | in place sort using `comarator` function (4) | void        |
+| `sortBy(predicate)`           | in-place sort bu `predicate` call result (3) | void        |
+| `sortWith(comparator)`        | in-place sort using `comarator` function (4) | void        |
+| `shiffle()`                   | in-place shiffle contents                    |             |
 
 (1)
 : optimized implementation that override `Array` one
@@ -143,7 +144,7 @@ instance is appended. If you want to append an Iterable object itself, use `add`
 order, e.g. is same as `list.sortWith { a,b -> predicate(a) <=> predicate(b) }`
 
 (4)
-: comparator callable takes tho arguments and must return: negative value when first is less, 
+: comparator callable takes tho arguments and must return: negative value when first is less,
 positive if first is greater, and zero if they are equal. For example, the equvalent comparator
 for `sort()` will be `sort { a, b -> a <=> b }