Tweaked tests, docs, and fisherYates

`fisherYates` no longer uses `xorshift32` by default, and the tests now
only use printable ASCII for debugging convenience.

`fisherYates` is not part of the public API, so the change shouldn't
affect users.

Author: haukex

src/__tests__/merge-insertion.test.ts

@@ -273,9 +273,9 @@ describe('fisherYates', () => {
     fisherYates(a, function* () { yield* [5, 1, 5, 0, 2, 2, 0]; throw new Error('no more values') }())
     expect(a).toStrictEqual(['G','E','D','C','A','H','B','F'])
   })
-  test('Using default random generator', () => {
+  test('Using xorshift32', () => {
     const a = ['A','B','C']
-    fisherYates(a)
+    fisherYates(a, xorshift32())
     expect(a).not.toStrictEqual(['A','B','C'])
   })
 })
@@ -307,9 +307,10 @@ describe('mergeInsertionSort', () => {
     ])
   })
 
-  test.each( Array.from({ length: 101 }, (_, i) => ({ len: i })) )('array length $len', async ({len}) => {
-    const array :Readonly<string[]> = Array.from({ length: len }, (_,i) => String.fromCharCode(65 + i))
+  test.each( Array.from({ length: 95 }, (_, i) => ({ len: i })) )('array length $len', async ({len}) => {
+    const array :Readonly<string[]> = Array.from({ length: len }, (_,i) => String.fromCharCode(33 + i))  // printable ASCII
     const a = Array.from(array)
+    const rand = xorshift32()
     try {
       // in order array
       expect( await mergeInsertionSort(a, testComp(comp, mergeInsertionMaxComparisons(len))) ).toStrictEqual(array)
@@ -319,7 +320,7 @@ describe('mergeInsertionSort', () => {
       expect( await mergeInsertionSort(a, testComp(comp, mergeInsertionMaxComparisons(len))) ).toStrictEqual(array)
       // several shuffles
       for (let i=0;i<100;i++) {
-        fisherYates(a)
+        fisherYates(a, rand)
         expect( await mergeInsertionSort(a, testComp(comp, mergeInsertionMaxComparisons(len))) ).toStrictEqual(array)
       }
     } catch (ex) {

src/merge-insertion.ts

@@ -12,7 +12,7 @@
  * ```typescript
  * import { mergeInsertionSort, Comparator } from 'merge-insertion'
  *
- * // A Comparator should return 0 if the first item is larger, or 1 if the second item is larger.
+ * // A Comparator must return 0 if the first item is larger, or 1 if the second item is larger.
  * const comp :Comparator<string> = async ([a, b]) => a > b ? 0 : 1
  *
  * // Sort five items in ascending order with a maximum of only seven comparisons:
@@ -22,7 +22,7 @@
  * ### References
  *
  * 1. Ford, L. R., & Johnson, S. M. (1959). A Tournament Problem.
- *    The American Mathematical Monthly, 66(5), 387–389. <https://doi.org/10.1080/00029890.1959.11989306>
+ *    The American Mathematical Monthly, 66(5), 387-389. <https://doi.org/10.1080/00029890.1959.11989306>
  * 2. Knuth, D. E. (1998). The Art of Computer Programming: Volume 3: Sorting and Searching (2nd ed.).
  *    Addison-Wesley. <https://cs.stanford.edu/~knuth/taocp.html#vol3>
  * 3. <https://en.wikipedia.org/wiki/Merge-insertion_sort>
@@ -289,9 +289,8 @@ export function* xorshift32() :Generator<number, never, never> {
  * 2. Durstenfeld, R. (1964). Algorithm 235: Random permutation. Communications of the ACM, 7(7), 420. doi:10.1145/364520.364540
  *
  * @param random Generator that returns random integers in the range `0` (inclusive) and `>= array.length-1`.
- *  The default is {@link xorshift32} - which may not return integers big enough for very large arrays!
  * @internal */
-export function fisherYates(array :unknown[], random :Generator<number> = xorshift32()) {
+export function fisherYates(array :unknown[], random :Generator<number>) {
   for (let i=array.length-1; i>0; i--) {
     const j = random.next().value % array.length;
     [array[i], array[j]] = [array[j], array[i]]