mirror of
https://github.com/denoland/std.git
synced 2024-11-21 20:50:22 +00:00
149839b60c
Co-authored-by: Yoshiya Hinosawa <stibium121@gmail.com> Co-authored-by: Asher Gomez <ashersaupingomez@gmail.com>
48 lines
1.5 KiB
TypeScript
48 lines
1.5 KiB
TypeScript
// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
|
||
// This module is browser compatible.
|
||
import type { Prng, RandomOptions } from "./_types.ts";
|
||
import { randomIntegerBetween } from "./integer_between.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];
|
||
|
||
// 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 = randomIntegerBetween(0, i, options);
|
||
// exchange a[j] and a[i]
|
||
[result[i], result[j]] = [result[j]!, result[i]!];
|
||
}
|
||
|
||
return result;
|
||
}
|