✨ feat(api): Add choice and _choice functions.

Fixes #16.

Author: make-github-pseudonymous-again

src/api/choice.js

@@ -0,0 +1,14 @@
+import _choice from '../kernel/_choice.js';
+import randint from './randint.js';
+
+/**
+ * Sample a single element from an array.
+ *
+ * @function
+ * @param {Array} a The input array.
+ * @param {number} i Inclusive left bound.
+ * @param {number} j Non-inclusive right bound.
+ * @return {any} The sampled element.
+ */
+const choice = _choice(randint);
+export default choice;

src/index.js

@@ -1,9 +1,11 @@
+export {default as choice} from './api/choice.js';
 export {default as randfloat} from './api/randfloat.js';
 export {default as randint} from './api/randint.js';
 export {default as random} from './api/random.js';
 export {default as randrange} from './api/randrange.js';
 export {default as sample} from './api/sample.js';
 export {default as shuffle} from './api/shuffle.js';
+export {default as _choice} from './kernel/_choice.js';
 export {default as _fisheryates} from './kernel/_fisheryates.js';
 export {default as _randfloat} from './kernel/_randfloat.js';
 export {default as _randint} from './kernel/_randint.js';

src/kernel/_choice.js

@@ -0,0 +1,24 @@
+/**
+ * Builds a choice function given a randint function.
+ *
+ * @param {Function} randint The randint function.
+ * @return {Function} The choice function.
+ */
+const _choice = (randint) => {
+	/**
+	 * Sample a single element from an array.
+	 *
+	 * @param {Array} a The input array.
+	 * @param {number} i Inclusive left bound.
+	 * @param {number} j Non-inclusive right bound.
+	 * @return {any} The sampled element.
+	 */
+	const choice = (a, i, j) => {
+		const x = randint(i, j);
+		return a[x];
+	};
+
+	return choice;
+};
+
+export default _choice;

test/src/choice.js

@@ -0,0 +1,56 @@
+import test from 'ava';
+import {choice, _choice, randint} from '../../src/index.js';
+
+import {_calloc} from '@aureooms/js-memory';
+import {iota, copy} from '@aureooms/js-array';
+
+const macro = (t, type, _, choice, n, i, j) => {
+	const calloc = _calloc(type);
+	const a = calloc(n);
+	const b = calloc(n);
+
+	iota(a, 0, n, 0);
+	copy(a, 0, n, b, 0);
+
+	const x = choice(b, i, j);
+
+	t.deepEqual(b, a);
+	t.true(a.slice(i, j).includes(x));
+};
+
+macro.title = (title, type, choice_name, _, n, i, j) =>
+	title || `[${n}] choice ( ${type.name}, ${choice_name}, ${i}, ${j} )`;
+
+const n = 100;
+const params = [
+	[n, 0, n],
+	[n, 20, n],
+	[n, 0, n - 20],
+	[n, 10, n - 10],
+];
+
+const types = [
+	Array,
+	Int8Array,
+	Int16Array,
+	Int32Array,
+	Uint8Array,
+	Uint16Array,
+	Uint32Array,
+	Uint8ClampedArray,
+	Float32Array,
+	Float64Array,
+];
+
+const algorithms = [
+	['kernel', _choice(randint)],
+	['API', choice],
+];
+
+for (const type of types) {
+	for (const [name, algorithm] of algorithms) {
+		for (const [n, i, j] of params) {
+			test(macro, type, name, algorithm, n, i, j);
+		}
+	}
+}