🎨 improve(knuth-shuffle): support to shuffle sub-range of array

Author: guanghechen

Diff for: packages/knuth-shuffle/README.md

@@ -101,6 +101,15 @@ If you are interested in this algorithm, you can check [here][knuth-shuffle].
   knuthShuffle(nodes)
   ```
 
+* Shuffle a contiguous range of the original array.
+
+  ```typescript
+  import knuthShuffle from '@algorithm.ts/knuth-shuffle'
+
+  // shuffle { a[2], a[3], a[4], a[5], a[6] }
+  knuthShuffle([1, 2, 3, 4, 5, 6, 7, 8, 9], 2, 7)
+  ```
+
 ## Related
 
 * [洗牌问题和 knuth-shuffle 算法][knuth-shuffle]

Diff for: packages/knuth-shuffle/__test__/knuth-shuffle.spec.ts

@@ -1,7 +1,7 @@
 import { knuthShuffle } from '../src'
 
 describe('knuth-shuffle', function () {
-  const ebs = 5
+  const ebs = 2
   const size = 1e2
   const shuffleTimes = 1e4
 
@@ -21,10 +21,39 @@ describe('knuth-shuffle', function () {
   })
 
   test('uniformly distribute', function () {
+    const mean: number = count[0] / shuffleTimes
     for (let i = 1; i < size; ++i) {
-      expect(
-        Math.abs(count[i] - count[i - 1]) / shuffleTimes,
-      ).toBeLessThanOrEqual(ebs)
+      expect(Math.abs(count[i] / shuffleTimes - mean)).toBeLessThanOrEqual(ebs)
     }
   })
+
+  test('sub-array', function () {
+    const nums: number[] = new Array(size)
+    for (let i = 0; i < size; ++i) nums[i] = i
+
+    const start = 10
+    const end = 70
+    knuthShuffle(nums, start, end)
+    for (let i = 0; i < start; ++i) expect(nums[i]).toBe(i)
+    for (let i = end; i < size; ++i) expect(nums[i]).toBe(i)
+
+    let diff = 0
+    for (let i = start; i < end; ++i) diff = nums[i] === i ? 0 : 1
+    expect(diff).toBeGreaterThan(0)
+  })
+
+  test('out of boundary', function () {
+    const nums: number[] = new Array(size)
+    for (let i = 0; i < size; ++i) nums[i] = i
+
+    knuthShuffle(nums, 200, 1)
+    expect(nums.every((x, i) => x === i)).toBe(true)
+
+    knuthShuffle(nums, -2, 50)
+    for (let i = 50; i < size; ++i) expect(nums[i]).toBe(i)
+
+    let diff = 0
+    for (let i = 0; i < 50; ++i) diff = nums[i] === i ? 0 : 1
+    expect(diff).toBeGreaterThan(0)
+  })
 })

Diff for: packages/knuth-shuffle/src/index.ts

@@ -2,10 +2,18 @@
  * Shuffle array.
  * @param nodes
  */
-export function knuthShuffle<T extends unknown = unknown>(nodes: T[]): void {
-  const N = nodes.length
-  for (let i = N - 1, j: number, x: T; i > 0; --i) {
-    j = Math.floor(Math.random() * (i + 1))
+export function knuthShuffle<T extends unknown = unknown>(
+  nodes: T[],
+  _start = 0,
+  _end: number = nodes.length,
+): void {
+  const start = Math.max(0, _start)
+  const end = Math.min(nodes.length, _end)
+  if (start + 1 >= end) return
+
+  const N = end - start
+  for (let n = N - 1, i: number, j = end - 1, x: T; n > 0; --n, --j) {
+    i = ((Math.random() * n) >> 0) + start
     x = nodes[i]
     // eslint-disable-next-line no-param-reassign
     nodes[i] = nodes[j]