// Copyright 2018-2026 the Deno authors. MIT license.
// This module is browser compatible.
import type { Prng, RandomOptions } from "./_types.ts";
export type { Prng, RandomOptions };
/**
* Shuffles the provided array, returning a copy and without modifying the original array.
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @typeParam T The type of the items in the array
* @param items The items to shuffle
* @param options The options for the random number generator
* @returns A shuffled copy of the provided items
*
* @example Usage
* ```ts no-assert
* import { shuffle } from "@std/random";
*
* const items = [1, 2, 3, 4, 5];
*
* shuffle(items); // [2, 5, 1, 4, 3]
* shuffle(items); // [3, 4, 5, 1, 2]
* shuffle(items); // [5, 2, 4, 3, 1]
*
* items; // [1, 2, 3, 4, 5] (original array is unchanged)
* ```
*/
export function shuffle<T>(
items: readonly T[],
options?: RandomOptions,
): T[] {
const result = [...items];
const prng = options?.prng ?? Math.random;
// https://en.wikipedia.org/wiki/Fisher–Yates_shuffle#The_modern_algorithm
// -- To shuffle an array a of n elements (indices 0..n-1):
// for i from n−1 down to 1 do
for (let i = result.length - 1; i >= 1; --i) {
// j ← random integer such that 0 ≤ j ≤ i
const j = Math.floor(prng() * (i + 1));
// exchange a[j] and a[i]
const temp = result[i];
result[i] = result[j]!;
result[j] = temp!;
}
return result;
}
|