src/utils.mjs: Add first(), rest(), butlast() and last()

2 files changed, 83 insertions, 0 deletions

diff --git a/src/utils.mjs b/src/utils.mjs
index 7d27c0d..1080219 100644
--- a/src/utils.mjs
+++ b/src/utils.mjs
@@ -47,3 +47,8 @@ export const partial = (fn, ...startArgs) =>
 export const strSortFn = (a, b) => a.localeCompare(b, "POSIX");
 
 export const undefinedAsNull = x => x === undefined ? null : x;
+
+export const first   = a => a[0];
+export const rest    = a => a.slice(1);
+export const butlast = a => a.slice(a, a.length - 1);
+export const last    = a => a[a.length - 1];
diff --git a/tests/js/utils.mjs b/tests/js/utils.mjs
index 425a09f..d8a8ded 100644
--- a/tests/js/utils.mjs
+++ b/tests/js/utils.mjs
@@ -10,6 +10,10 @@ import {
 	partial,
 	strSortFn,
 	undefinedAsNull,
+	first,
+	rest,
+	butlast,
+	last,
 } from "../../src/utils.mjs";
 
 
@@ -268,6 +272,76 @@ const test_undefinedAsNull = async t => {
 	});
 };
 
+const test_first = async t => {
+	t.start("first()");
+
+	await t.test("undefined for an empty array", () => {
+		assert.equal(undefined, first([]));
+		assert.equal(undefined, first(""));
+	});
+
+	await t.test("the first element otherwise", () => {
+		assert.equal(1, first([1, 2, 3]));
+		assert.equal("a", first("abc"));
+	});
+};
+
+const test_rest = async t => {
+	t.start("rest()");
+
+	await t.test("an empty array when no more elements are available", () => {
+		assert.deepEqual([], rest([]));
+		assert.deepEqual([], rest([1]));
+		assert.equal("", rest(""));
+		assert.equal("bc", rest("abc"));
+	});
+
+	await t.test("the rest of the collection otherwise", () => {
+		assert.deepEqual([2, 3], rest([1, 2, 3]));
+		assert.equal("bc", rest("abc"));
+	});
+
+	await t.test("combines with first() well", () => {
+		const arr = ["anything", "can", "go", "here"];
+		assert.deepEqual(arr, [ first(arr), ...rest(arr) ]);
+	});
+};
+
+const test_butlast = async t => {
+	t.start("butlast()");
+
+	await t.test("empty array when ther are no more elements", () => {
+		assert.deepEqual([], butlast([]));
+		assert.deepEqual([], butlast([1]));
+		assert.equal("", butlast(""));
+		assert.equal("", butlast("c"));
+	});
+
+	await t.test("the beginning of the array otherwise", () => {
+		assert.deepEqual([1, 2], butlast([1, 2, 3]));
+		assert.equal("ab", butlast("abc"));
+	});
+};
+
+const test_last = async t => {
+	t.start("last()");
+
+	await t.test("undefined for an empty array", () => {
+		assert.equal(undefined, last([]));
+		assert.equal(undefined, last(""));
+	});
+
+	await t.test("the last element otherwise", () => {
+		assert.equal(3, last([1, 2, 3]));
+		assert.equal("c", last("abc"));
+	});
+
+	await t.test("combines with butlast() well", () => {
+		const arr = ["anything", "goes", "here", "too"];
+		assert.deepEqual(arr, [ ...butlast(arr), last(arr) ]);
+	});
+};
+
 
 await runner.runTests([
 	test_keys,
@@ -278,4 +352,8 @@ await runner.runTests([
 	test_partial,
 	test_strSortFn,
 	test_undefinedAsNull,
+	test_first,
+	test_rest,
+	test_butlast,
+	test_last,
 ]);