Code cleanup of Linked Lists (#5241)

* made private methods limited to module scope
* moved private methods to file bottom
* changed tests to run comperable array functions in parallel
* added comments

editions/test/tiddlers/tests/test-linked-list.js

@@ -8,6 +8,10 @@ Tests the utils.LinkedList class.
 LinkedList was built to behave exactly as $tw.utils.pushTop and
 Array.prototype.push would behave with an array.
 
+Many of these tests function by performing operations on a LinkedList while
+performing the equivalent actions on an array with the old utility methods.
+Then we confirm that the two come out functionally identical.
+
 \*/
 (function(){
 
@@ -17,66 +21,88 @@ Array.prototype.push would behave with an array.
 
 describe("LinkedList class tests", function() {
 
+	// pushTops a value or array of values into both the array and linked list.
+	function pushTop(array, linkedList, valueOrValues) {
+		$tw.utils.pushTop(array, valueOrValues);
+		linkedList.pushTop(valueOrValues);
+	};
+
+	// pushes values into both the array and the linked list.
+	function push(array, linkedList/*, other values */) {
+		var values = Array.prototype.slice(arguments, 2);
+		array.push.apply(array, values);
+		linkedList.push.apply(linkedList, values);
+	};
+
+	// operates a remove action on an array and a linked list in parallel.
+	function remove(array, linkedList, valueOrValues) {
+		$tw.utils.removeArrayEntries(array, valueOrValues);
+		linkedList.remove(valueOrValues);
+	};
+
+	// compares an array and a linked list to make sure they match up
+	function compare(array, linkedList) {
+		expect(linkedList.toArray()).toEqual(array);
+		expect(linkedList.length).toBe(array.length);
+	};
+
 	it("can pushTop", function() {
+		var array = [];
 		var list = new $tw.utils.LinkedList();
-		list.push('A', 'B', 'C');
+		push(array, list, 'A', 'B', 'C');
 		// singles
-		list.pushTop('X');
-		list.pushTop('B');
-		expect(list.toArray()).toEqual(['A', 'C', 'X', 'B']);
-		expect(list.length).toBe(4);
+		pushTop(array, list, 'X');
+		pushTop(array, list, 'B');
+		compare(array, list); // A C X B
 		//arrays
-		list.pushTop(['X', 'A', 'G', 'A']);
+		pushTop(array, list, ['X', 'A', 'G', 'A']);
 		// If the pushedTopped list has duplicates, they go in unempeded.
-		expect(list.toArray()).toEqual(['C', 'B', 'X', 'A', 'G', 'A']);
-		expect(list.length).toBe(6);
+		compare(array, list); // C B X A G A
 	});
 
 	it("can pushTop with tricky duplicates", function() {
+		var array = [];
 		var list = new $tw.utils.LinkedList();
-		list.push('A', 'B', 'A', 'C', 'A', 'end');
+		push(array, list, 'A', 'B', 'A', 'C', 'A', 'end');
 		// If the original list contains duplicates, only one instance is cut
-		list.pushTop('A');
-		expect(list.toArray()).toEqual(['B', 'A', 'C', 'A', 'end', 'A']);
-		expect(list.length).toBe(6);
+		pushTop(array, list, 'A');
+		compare(array, list); // B A C A end A
 
 		// And the Llist properly knows the next 'A' to cut if pushed again
-		list.pushTop(['X', 'A']);
-		expect(list.toArray()).toEqual(['B', 'C', 'A', 'end', 'A', 'X', 'A']);
-		expect(list.length).toBe(7);
+		pushTop(array, list, ['X', 'A']);
+		compare(array, list); // B C A end A X A
 
 		// One last time, to make sure we maintain the linked chain of copies
-		list.pushTop('A');
-		expect(list.toArray()).toEqual(['B', 'C', 'end', 'A', 'X', 'A', 'A']);
-		expect(list.length).toBe(7);
+		pushTop(array, list, 'A');
+		compare(array, list); // B C end A X A A
 	});
 
 	it("can handle particularly nasty pushTop pitfall", function() {
+		var array = [];
 		var list = new $tw.utils.LinkedList();
-		list.push('A', 'B', 'A', 'C');
-		list.pushTop('A'); // BACA
-		list.pushTop('X'); // BACAX
-		list.remove('A');  // BCAX
-		list.pushTop('A'); // BCXA
-		list.remove('A');  // BCX
+		push(array, list, 'A', 'B', 'A', 'C');
+		pushTop(array, list, 'A'); // BACA
+		pushTop(array, list, 'X'); // BACAX
+		remove(array, list, 'A');  // BCAX
+		pushTop(array, list, 'A'); // BCXA
+		remove(array, list, 'A');  // BCX
+
 		// But! The way I initially coded the copy chains, a mystery A could
 		// hang around.
-		expect(list.toArray()).toEqual(['B', 'C', 'X']);
-		expect(list.length).toBe(3);
+		compare(array, list); // B C X
 	});
 
 	it("can push", function() {
+		var array = [];
 		var list = new $tw.utils.LinkedList();
-		list.push('A', 'B', 'C');
+		push(array, list, 'A', 'B', 'C');
 		// singles
-		list.push('B');
-		expect(list.toArray()).toEqual(['A', 'B', 'C', 'B']);
-		expect(list.length).toBe(4);
+		push(array, list, 'B');
+		compare(array, list); // A B C B
 
 		// multiple args
-		list.push('A', 'B', 'C');
-		expect(list.toArray()).toEqual(['A', 'B', 'C', 'B', 'A', 'B', 'C']);
-		expect(list.length).toBe(7);
+		push(array, list, 'A', 'B', 'C');
+		compare(array, list); // A B C B A B C
 	});
 
 	it("can clear", function() {
@@ -88,31 +114,29 @@ describe("LinkedList class tests", function() {
 	});
 
 	it("can remove", function() {
+		var array = [];
 		var list = new $tw.utils.LinkedList();
-		list.push('A', 'x', 'C', 'x', 'D', 'x', 'E', 'x');
+		push(array, list, 'A', 'x', 'C', 'x', 'D', 'x', 'E', 'x');
 		// single
-		list.remove('x');
-		expect(list.toArray()).toEqual(['A', 'C', 'x', 'D', 'x', 'E', 'x']);
-		expect(list.length).toBe(7);
+		remove(array, list, 'x');
+		compare(array, list); // A C x D x E x
 
 		// arrays
-		list.remove(['x', 'A', 'x']);
-		expect(list.toArray()).toEqual(['C', 'D', 'E', 'x']);
-		expect(list.length).toBe(4);
+		remove(array, list, ['x', 'A', 'x']);
+		compare(array, list); // C D E x
 	});
 
 	it('can ignore removal of nonexistent items', function() {
+		var array = [];
 		var list = new $tw.utils.LinkedList();
-		list.push('A', 'B', 'C', 'D');
+		push(array, list, 'A', 'B', 'C', 'D');
 		// single
-		list.remove('Z');
-		expect(list.toArray()).toEqual(['A', 'B', 'C', 'D']);
-		expect(list.length).toBe(4);
+		remove(array, list, 'Z');
+		compare(array, list); // A B C D
 
 		// array
-		list.remove(['Z', 'B', 'X']);
-		expect(list.toArray()).toEqual(['A', 'C', 'D']);
-		expect(list.length).toBe(3);
+		remove(array, list, ['Z', 'B', 'X']);
+		compare(array, list); // A C D
 	});
 
 	it('can iterate with each', function() {