🌱 initial: First implementation based on existing circular.

Author: make-github-pseudonymous-again

README.md

@@ -1,16 +1,19 @@
 :left_right_arrow: [@data-structure-algebra/doubly-linked-list](https://data-structure-algebra.github.io/doubly-linked-list)
 ==
 
-Doubly linked list for JavaScript.
+Doubly linked lists for JavaScript.
 See [docs](https://data-structure-algebra.github.io/doubly-linked-list/index.html).
-
-> :building_construction: Caveat emptor! This is work in progress. Code may be
-> working. Documentation may be present. Coherence may be. Maybe.
+Parent is [js-data-structures](https://github.com/make-github-pseudonymous-again/js-data-structures).
 
 > :warning: Depending on your environment, the code may require
 > `regeneratorRuntime` to be defined, for instance by importing
 > [regenerator-runtime/runtime](https://www.npmjs.com/package/regenerator-runtime).
 
+```js
+import {from} from '@data-structure-algebra/doubly-linked-list';
+let list = from('abc');
+```
+
 [![License](https://img.shields.io/github/license/data-structure-algebra/doubly-linked-list.svg)](https://raw.githubusercontent.com/data-structure-algebra/doubly-linked-list/main/LICENSE)
 [![Version](https://img.shields.io/npm/v/@data-structure-algebra/doubly-linked-list.svg)](https://www.npmjs.org/package/@data-structure-algebra/doubly-linked-list)
 [![Tests](https://img.shields.io/github/workflow/status/data-structure-algebra/doubly-linked-list/ci?event=push&label=tests)](https://github.com/data-structure-algebra/doubly-linked-list/actions/workflows/ci.yml?query=branch:main)

doc/scripts/header.js

@@ -17,7 +17,8 @@ domReady(() => {
 	header.insertBefore(projectname, header.firstChild);
 
 	const testlink = document.querySelector('header > a[data-ice="testLink"]');
-	testlink.href = 'https://app.codecov.io/gh/data-structure-algebra/doubly-linked-list';
+	testlink.href =
+		'https://app.codecov.io/gh/data-structure-algebra/doubly-linked-list';
 	testlink.target = '_BLANK';
 
 	const searchBox = document.querySelector('.search-box');

package.json

@@ -66,7 +66,7 @@
     "test:dist": "npm run test:modern && npm run test:module && npm run test:cjs",
     "test:modern": "IMPORT_MAP_PATH=test/import-maps/dist/index.modern.json npm run test-cmd",
     "test:module": "IMPORT_MAP_PATH=test/import-maps/dist/index.module.json npm run test-cmd",
-    "test:src": "IMPORT_MAP_PATH=test/import-maps/src/index.json npm run test-cmd"
+    "test:src": "IMPORT_MAP_PATH=test/import-maps/src/index.json npm run test-cmd --"
   },
   "dependencies": {},
   "devDependencies": {
@@ -75,6 +75,9 @@
     "@babel/plugin-transform-for-of": "7.18.8",
     "@babel/preset-env": "7.19.4",
     "@commitlint/cli": "17.1.2",
+    "@iterable-iterator/list": "^1.0.1",
+    "@iterable-iterator/map": "^1.0.1",
+    "@iterable-iterator/range": "^2.1.0",
     "@js-library/commitlint-config": "0.0.4",
     "@node-loader/babel": "2.0.1",
     "@node-loader/core": "2.0.0",
@@ -208,16 +211,9 @@
       "unicorn"
     ],
     "rules": {
+      "camelcase": "off",
       "unicorn/prefer-node-protocol": "off",
-      "unicorn/filename-case": [
-        "error",
-        {
-          "cases": {
-            "camelCase": true,
-            "pascalCase": true
-          }
-        }
-      ]
+      "unicorn/filename-case": "off"
     },
     "overrides": [
       {

src/Node.js

@@ -0,0 +1,14 @@
+/**
+ * Base node class.
+ *
+ * @class
+ * @param {any} value The value to hold.
+ */
+export default function Node(value) {
+	/** @member {any} The value/key held by this node. */
+	this.value = value;
+	/** @member {Node} Pointer to previous (left) sibling */
+	this.prev = null;
+	/** @member {Node} Pointer to next (right) sibling */
+	this.next = null;
+}

src/_concat.js

@@ -0,0 +1,15 @@
+import assert from 'assert';
+import Node from './Node.js';
+
+/**
+ * Concatenate two input lists.
+ *
+ * @param {Node} z Last node of first input list.
+ * @param {Node} y First node of second input list.
+ */
+export default function _concat(z, y) {
+	assert(z instanceof Node && z.next === null);
+	assert(y instanceof Node && y.prev === null);
+	z.next = y;
+	y.prev = z;
+}

src/_iter.js

@@ -0,0 +1,23 @@
+import assert from 'assert';
+import Node from './Node.js';
+
+/**
+ * Generator of nodes in list in order. You are allowed to edit the current
+ * node.
+ *
+ * /!\ Modifying the next pointer of the current node will NOT change which
+ * node comes next in the iteration.
+ *
+ * @param {Node} first First node of the list.
+ * @return {IterableIterator<Node>} Yields nodes of a list in order.
+ */
+export default function* _iter(first) {
+	assert(first instanceof Node);
+	let next = first;
+
+	do {
+		const x = next;
+		next = x.next; // Compute next before yielding.
+		yield x; // Necessary ?
+	} while (next !== null);
+}

src/_iter_fast.js

@@ -0,0 +1,23 @@
+import assert from 'assert';
+import Node from './Node.js';
+
+/**
+ * Generator of nodes in list in order. The list cannot be empty. You should
+ * not modify the current node's next pointer unless you know what you are
+ * doing.
+ *
+ * /!\ Modifying the next pointer of the current node will change which node
+ * comes next in the iteration.
+ *
+ * @param {Node} first First node of the list.
+ * @return {IterableIterator<Node>} Yields nodes of a list in order.
+ */
+export default function* _iter_fast(first) {
+	assert(first instanceof Node);
+	let next = first;
+
+	do {
+		yield next;
+		next = next.next;
+	} while (next !== null);
+}

src/_last.js

@@ -0,0 +1,19 @@
+import assert from 'assert';
+import Node from './Node.js';
+
+/**
+ * Returns the last node of a list. The list cannot be empty.
+ *
+ * @param {Node} first First node of the list.
+ * @return {Node} Last node of the list.
+ */
+export default function _last(first) {
+	assert(first instanceof Node);
+	let next = first;
+
+	while (next.next !== null) {
+		next = next.next;
+	}
+
+	return next;
+}

src/_len.js

@@ -0,0 +1,21 @@
+import assert from 'assert';
+import Node from './Node.js';
+
+/**
+ * Compute the length of a non-empty list.
+ *
+ * @param {Node} x First node of the input list.
+ * @return {number} The length of the input list.
+ */
+// eslint-disable-next-line unicorn/prevent-abbreviations
+export default function _len(x) {
+	assert(x instanceof Node);
+	let n = 1;
+	let y = x.next;
+	while (y !== null) {
+		++n;
+		y = y.next;
+	}
+
+	return n;
+}

src/_pop.js

@@ -0,0 +1,17 @@
+import assert from 'assert';
+import Node from './Node.js';
+
+/**
+ * Removes last {@link Node} from a non-empty list.
+ *
+ * @param {Node} x Last node (not null). Cannot be the first node.
+ * @return {Node} Last node of new list (not null).
+ */
+export default function _pop(x) {
+	assert(x instanceof Node);
+	assert(x.next === null);
+	const prev = x.prev; // eslint-disable-line unicorn/prevent-abbreviations
+	assert(prev !== null);
+	prev.next = null;
+	return prev;
+}

src/_remove.js

@@ -0,0 +1,17 @@
+import assert from 'assert';
+import Node from './Node.js';
+
+/**
+ * Removes input {@link Node} from its list. Cannot be first or last, use
+ * _shift or _pop instead.
+ *
+ * /!\ Pointers in the extracted node are left unchanged.
+ * /!\ <code>x</code> will have dangling pointers after removal if not single element.
+ *
+ * @param {Node} x Node to remove.
+ */
+export default function _remove(x) {
+	assert(x instanceof Node);
+	x.prev.next = x.next;
+	x.next.prev = x.prev;
+}

src/_rotate_left.js

@@ -0,0 +1,31 @@
+import assert from 'assert';
+import Node from './Node.js';
+import _rotate_to from './_rotate_to.js';
+
+/**
+ * Rotate list to the left k steps. The parameter k must be positive and
+ * smaller than the length of the list.
+ *
+ * @param {Node} x The current first node.
+ * @param {Node} z The current last node.
+ * @param {number} k MUST be positive and smaller than the length of the list.
+ * @return {[Node, Node]} The new first and last nodes.
+ */
+export default function _rotate_left(x, z, k) {
+	assert(Number.isInteger(k));
+	assert(k > 0);
+	assert(x instanceof Node);
+	assert(x.prev === null);
+	assert(z instanceof Node);
+	assert(z.next === null);
+	assert(x !== z);
+	let y = z;
+	while (--k) {
+		y = y.prev;
+		assert(y instanceof Node);
+	}
+
+	const w = y.prev;
+	_rotate_to(x, y, z);
+	return [y, w];
+}

src/_rotate_left_modulo.js

@@ -0,0 +1,26 @@
+import assert from 'assert';
+import Node from './Node.js';
+import _rotate_left from './_rotate_left.js';
+
+/**
+ * Rotate non-empty list to the left n steps. The parameter n must be positive.
+ *
+ * @param {Node} x The current first node.
+ * @param {Node} z The current last node.
+ * @param {number} n List length, MUST be positive.
+ * @param {number} k MUST be positive.
+ * @return {[Node, Node]} The new first and last nodes.
+ */
+export default function _rotate_left_modulo(x, z, n, k) {
+	assert(Number.isInteger(n));
+	assert(n > 0);
+	assert(Number.isInteger(k));
+	assert(k > 0);
+	assert(x instanceof Node);
+	assert(x.prev === null);
+	assert(z instanceof Node);
+	assert(z.next === null);
+	assert(x !== z);
+	const m = k % n;
+	return m === 0 ? [x, z] : _rotate_left(x, z, m);
+}

src/_rotate_left_unknown_length.js

@@ -0,0 +1,35 @@
+import assert from 'assert';
+import Node from './Node.js';
+import _rotate_to from './_rotate_to.js';
+import _rotate_left_modulo from './_rotate_left_modulo.js';
+
+/**
+ * Rotate list to the right n steps. The parameter n must be positive.
+ *
+ * @param {Node} x The current first node.
+ * @param {Node} z The current last node.
+ * @param {number} k MUST be positive.
+ * @return {[Node, Node]} The new first and last nodes.
+ */
+export default function _rotate_left_unknown_length(x, z, k) {
+	assert(Number.isInteger(k));
+	assert(k > 0);
+	assert(x instanceof Node);
+	assert(x.prev === null);
+	assert(z instanceof Node);
+	assert(z.next === null);
+	assert(x !== z);
+	let y = z;
+	let l = k;
+	while (--l) {
+		if (y === x) {
+			return _rotate_left_modulo(x, z, k - l, k);
+		}
+
+		y = y.prev;
+	}
+
+	const w = y.prev;
+	_rotate_to(x, y, z);
+	return [y, w];
+}

src/_rotate_right.js

@@ -0,0 +1,31 @@
+import assert from 'assert';
+import Node from './Node.js';
+import _rotate_to from './_rotate_to.js';
+
+/**
+ * Rotate list to the right k steps. The parameter k must be positive and
+ * smaller than the length of the list.
+ *
+ * @param {Node} x The current first node.
+ * @param {Node} z The current last node.
+ * @param {number} k MUST be positive and smaller than the length of the list.
+ * @return {[Node, Node]} The new first and last nodes.
+ */
+export default function _rotate_right(x, z, k) {
+	assert(Number.isInteger(k));
+	assert(k > 0);
+	assert(x instanceof Node);
+	assert(x.prev === null);
+	assert(z instanceof Node);
+	assert(z.next === null);
+	assert(x !== z);
+	let y = x;
+	do {
+		y = y.next;
+		assert(y instanceof Node);
+	} while (--k);
+
+	const w = y.prev;
+	_rotate_to(x, y, z);
+	return [y, w];
+}

src/_rotate_right_modulo.js

@@ -0,0 +1,26 @@
+import assert from 'assert';
+import Node from './Node.js';
+import _rotate_right from './_rotate_right.js';
+
+/**
+ * Rotate non-empty list to the right n steps. The parameter n must be positive.
+ *
+ * @param {Node} x The current first node.
+ * @param {Node} z The current last node.
+ * @param {number} n List length, MUST be positive.
+ * @param {number} k MUST be positive.
+ * @return {[Node, Node]} The new first and last nodes.
+ */
+export default function _rotate_right_modulo(x, z, n, k) {
+	assert(Number.isInteger(n));
+	assert(n > 0);
+	assert(Number.isInteger(k));
+	assert(k > 0);
+	assert(x instanceof Node);
+	assert(x.prev === null);
+	assert(z instanceof Node);
+	assert(z.next === null);
+	assert(x !== z);
+	const m = k % n;
+	return m === 0 ? [x, z] : _rotate_right(x, z, m);
+}