Update: Add find() method to DoublyLinkedList

Author: nzakas

src/data-structures/doubly-linked-list/README.md

@@ -11,6 +11,7 @@ A JavaScript implementation of a doubly linked list. This class uses the convent
 1. There is a `[Symbol.iterator]` method so each instance is iterable.
 1. The `size` getter property instead of a `length` data property to indicate that the size of the list is dynamically counted rather than stored.
 1. Defining a `values()` generator method.
+1. Defining a `find()` method for searching the list.
 1. Returning `undefined` from `get()` when no such index exists.
 
 Read the [blog post](https://humanwhocodes.com/blog/2019/02/computer-science-in-javascript-doubly-linked-lists/) about the design of this class.
@@ -44,6 +45,9 @@ let count = list.size;
 // get the index of a value
 let index = list.indexOf("foo");
 
+// search for a value
+let result = list.find(value => value.length > 3);
+
 // convert to an array using iterators
 let array1 = [...list.values()];
 let array2 = [...list];

src/data-structures/doubly-linked-list/doubly-linked-list.js

@@ -392,6 +392,55 @@ class DoublyLinkedList {
          */
         return -1;
     }
+
+    /**
+     * Returns the first item that matches a given function.
+     * @param {Function} matcher A function returning true when an item matches
+     *      and false when an item doesn't match.
+     * @returns {*} The first item that returns true from the matcher, undefined
+     *      if no items match.
+     */
+    find(matcher) {
+    
+        /*
+         * The `current` variable is used to iterate over the list nodes.
+         * It starts out pointing to the head and is overwritten inside
+         * of the loop below.
+         */
+        let current = this[head];
+
+        /*
+         * The `index` variable is used to track how deep into the list we've
+         * gone. This is important because this is the value that is returned
+         * from this method.
+         */
+        let index = 0;
+        
+        /*
+         * This loop checks each node in the list to see if it matches.
+         * If a match is found, it returns the data immediately, exiting the
+         * loop because there's no reason to keep searching. The search
+         * continues until there are no more nodes to search (when `current` is `null`).
+         */
+        while (current !== null) {
+            if (matcher(current.data)) {
+                return current.data;
+            }
+
+            // traverse to the next node in the list
+            current = current.next;
+
+            // keep track of where we are
+            index++;
+        }
+
+        /*
+         * If execution gets to this point, it means we reached the end of the
+         * list and didn't find `data`. Just return `undefined` as the 
+         * "not found" value.
+         */
+        return undefined;
+    }
 
     /**
      * Removes the node from the given location in the list.

src/data-structures/doubly-linked-list/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanwhocodes/doubly-linked-list",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A doubly linked list implementation in JavaScript",
   "main": "doubly-linked-list.js",
   "scripts": {

tests/data-structures/doubly-linked-list/doubly-linked-list.js

@@ -336,6 +336,31 @@ describe("DoublyLinkedList", () => {
 
     });
 
+    describe("find()", () => {
+        
+        it("should return undefined when the list is empty", () => {
+            assert.isUndefined(list.find(() => true));
+        });
+        
+        it("should return 1 when the matching value is found", () => {
+            list.add(1);
+            assert.strictEqual(list.find(value => (value > 0)), 1);
+        });
+        
+        it("should return 2 when the matching value is second", () => {
+            list.add(1);
+            list.add(2);
+            assert.strictEqual(list.find(value => (value > 1)), 2);
+        });
+
+        it("should return undefined when the list doesn't contain a match", () => {
+            list.add(1);
+            list.add(2);
+            assert.isUndefined(list.find((value) => value > 2));
+        });
+
+    });
+
     ["values", Symbol.iterator].forEach(method => {
 
         describe(String(method) + "()", () => {