✨ feat: Add rotate_left and rotate_right.

Fixes #44.

Author: make-github-pseudonymous-again

src/_rotate_left.js

@@ -0,0 +1,20 @@
+import assert from 'assert';
+import Node from './Node.js';
+
+/**
+ * Rotate list to the left n steps. The parameter n must be positive.
+ *
+ * @param {Node} x The current first node.
+ * @param {number} n MUST be positive.
+ * @return {Node} The new first node.
+ */
+export default function _rotate_left(x, n) {
+	assert(Number.isInteger(n));
+	assert(n > 0);
+	assert(x instanceof Node);
+	do {
+		x = x.prev;
+	} while (--n);
+
+	return x;
+}

src/_rotate_right.js

@@ -0,0 +1,20 @@
+import assert from 'assert';
+import Node from './Node.js';
+
+/**
+ * Rotate list to the right n steps. The parameter n must be positive.
+ *
+ * @param {Node} x The current first node.
+ * @param {number} n MUST be positive.
+ * @return {Node} The new first node.
+ */
+export default function _rotate_right(x, n) {
+	assert(Number.isInteger(n));
+	assert(n > 0);
+	assert(x instanceof Node);
+	do {
+		x = x.next;
+	} while (--n);
+
+	return x;
+}

src/index.js

@@ -6,6 +6,8 @@ export {default as _iter_fast} from './_iter_fast.js';
 export {default as _len} from './_len.js';
 export {default as _pop} from './_pop.js';
 export {default as _remove} from './_remove.js';
+export {default as _rotate_left} from './_rotate_left.js';
+export {default as _rotate_right} from './_rotate_right.js';
 export {default as _shift} from './_shift.js';
 export {default as concat} from './concat.js';
 export {default as empty} from './empty.js';
@@ -14,6 +16,8 @@ export {default as iter} from './iter.js';
 export {default as len} from './len.js';
 export {default as pop} from './pop.js';
 export {default as push} from './push.js';
+export {default as rotate_left} from './rotate_left.js';
+export {default as rotate_right} from './rotate_right.js';
 export {default as shift} from './shift.js';
 export {default as unshift} from './unshift.js';
 export {default as values} from './values.js';

src/rotate_left.js

@@ -0,0 +1,19 @@
+import assert from 'assert';
+import Node from './Node.js';
+import rotate_right from './rotate_right.js';
+
+/**
+ * Do nothing if x is empty or n is zero.
+ * Rotate left n steps if n is positive.
+ * Rotate right n steps if n is negative.
+ *
+ * @param {Node} x The current first node.
+ * @param {number} n
+ * @return {Node} The new first node.
+ */
+const rotate_left = (x, n) => {
+	assert(x === null || x instanceof Node);
+	return rotate_right(x, -n);
+};
+
+export default rotate_left;

src/rotate_right.js

@@ -0,0 +1,21 @@
+import assert from 'assert';
+import Node from './Node.js';
+import _rotate_left from './_rotate_left.js';
+import _rotate_right from './_rotate_right.js';
+
+/**
+ * Do nothing if x is empty or n is zero.
+ * Rotate right n steps if n is positive.
+ * Rotate left n steps if n is negative.
+ *
+ * @param {Node} x The current first node.
+ * @param {number} n
+ * @return {Node} The new first node.
+ */
+export default function rotate_right(x, n) {
+	assert(Number.isInteger(n));
+	if (x === null) return null;
+	assert(x instanceof Node);
+	if (n === 0) return x;
+	return n > 0 ? _rotate_right(x, n) : _rotate_left(x, -n);
+}

test/src/rotate.js

@@ -0,0 +1,68 @@
+import test from 'ava';
+
+import {list, range} from '@aureooms/js-itertools';
+
+import {str} from './_fixtures.js';
+
+import {from, rotate_left, rotate_right, len, values} from '../../src/index.js';
+
+const toArray = (first) => list(values(first));
+
+const immutability = (t, input, n) => {
+	const x = from(input);
+	const y = rotate_left(x, n);
+	const z = rotate_right(y, n);
+	const w = rotate_left(y, len(x) - n);
+
+	t.is(z, x);
+	t.deepEqual(toArray(z), toArray(x));
+	t.is(w, x);
+	t.deepEqual(toArray(w), toArray(x));
+};
+
+immutability.title = (title, input, n) =>
+	title || `immutability (${str(input)}, ${n})`;
+
+test(immutability, [], 0);
+test(immutability, [], -1);
+test(immutability, [], 1);
+test(immutability, [], -100);
+test(immutability, [], 100);
+test(immutability, 'abc', 0);
+test(immutability, 'abc', -1);
+test(immutability, 'abc', 1);
+test(immutability, 'abc', -100);
+test(immutability, 'abc', 100);
+test(immutability, list(range(1000)), 0);
+test(immutability, list(range(1000)), -1);
+test(immutability, list(range(1000)), 1);
+test(immutability, list(range(1000)), -100);
+test(immutability, list(range(1000)), 100);
+
+const mutability = (t, rotate, input, n, output) => {
+	const expected = list(output);
+	const x = from(input);
+	const y = rotate(x, n);
+	const actual = toArray(y);
+	t.deepEqual(actual, expected);
+};
+
+mutability.title = (title, rotate, input, n, output) =>
+	title || `mutability ${rotate.name}(${str(input)}, ${n}) = ${str(output)}`;
+
+test(mutability, rotate_left, [], 0, []);
+test(mutability, rotate_left, [], -1, []);
+test(mutability, rotate_left, [], 1, []);
+test(mutability, rotate_left, [], -100, []);
+test(mutability, rotate_left, [], 100, []);
+test(mutability, rotate_right, [], 0, []);
+test(mutability, rotate_right, [], -1, []);
+test(mutability, rotate_right, [], 1, []);
+test(mutability, rotate_right, [], -100, []);
+test(mutability, rotate_right, [], 100, []);
+test(mutability, rotate_left, 'abc', 0, 'abc');
+test(mutability, rotate_left, 'abc', -1, 'bca');
+test(mutability, rotate_left, 'abc', 1, 'cab');
+test(mutability, rotate_right, 'abc', 0, 'abc');
+test(mutability, rotate_right, 'abc', -1, 'cab');
+test(mutability, rotate_right, 'abc', 1, 'bca');