graph docs

Author: amejiarosario

book/chapters/graph.adoc

@@ -212,29 +212,122 @@ If we want to add a new node to the list, we can do it by adding one element to
 
 Since, adjacency lists are more efficient (than adjacency matrix), we are going to use to implement a graph data structure.
 
+Let's start by creating the constructor of the Graph calss.
+
+.Graph's constructor
+[source, javascript]
+----
+include::{codedir}/data-structures/graphs/graph.js[tag=constructor]
+----
+
+We want to make it as generic as possible, so can pass if the the graph is directed or undirected.
+
 == Adding a vertex
 
-Body text
+For addding a vertex, we first need to check if the node already exists. If it exists we return the node and we are done.
+
+.Graphs's `addVertex` method
+[source, javascript]
+----
+include::{codedir}/data-structures/graphs/graph.js[tag=addVertex, indent=0]
+----
+<1> Check if value is already on the graph. If it is, then return it.
+<2> Create new `Node` with the given value.
+<3> Set `hashMap` with value and node pair.
+
+If the node doesn't exist, then we create the new node and add it to a `HashMap`.
+
+TIP: <<Map>> stores key/pair value very efficiently. Lookup is `O(1)`.
+
+The `key` is node's value, while the `value` is the newly created node.
+
+The `Node` class is constructed as follows:
+
+.Node's class (for Graph data structure)
+[source, javascript]
+----
+include::{codedir}/data-structures/graphs/node.js[tag=constructor, indent=0]
+----
+
+
+== Deleting a vertex
+
+.Graphs's `removeVertex` method
+[source, javascript]
+----
+include::{codedir}/data-structures/graphs/graph.js[tag=removeVertex, indent=0]
+----
+<1> Try to find if node exists.
+<2> Remove related edges. See `removeAdjacent` below.
+<3> Remove node with the given value.
+
+Notice on the callout 2, that we visit every edge on the graph and remove the ones that contains the node to remove.
+
+For removing adjacent nodes, we use Node's method called `removeAdjacent` that can be implemented as follows:
+
+.Node's `removeAdjacent`
+[source, javascript]
+----
+include::{codedir}/data-structures/graphs/node.js[tag=removeAdjacent, indent=0]
+----
+
+All adjacecies are stored as a HashSet for to provide constant time deletion.
 
 == Adding an edge
 
-Body text
+An edge is a connection between two nodes (vertices). If the graph is undirected means that every edge is a two-way street so we create the edge from node 1 to node 2 and the other way arround.
+
+If we are dealing with a digraph (directed graph), then we just create one edge.
+
+.Graphs's `addEdge` method
+[source, javascript]
+----
+include::{codedir}/data-structures/graphs/graph.js[tag=addEdge, indent=0]
+----
+<1> Find or create nodes if they don't exists yet.
+<2> Create edge from source to destination. 
+<3> If us a undirected graph, create the edge on the other direction.
+
+We can add adjacencies using the `addAdjacent` mehtod from the Node class
+
+.Node's `addAdjacent`
+[source, javascript]
+----
+include::{codedir}/data-structures/graphs/node.js[tag=addAdjacent, indent=0]
+----
 
 == Querying Adjacency
 
-Body text
+.Graphs's `areAdjacents` method
+[source, javascript]
+----
+include::{codedir}/data-structures/graphs/graph.js[tag=areAdjacents, indent=0]
+----
 
-== Deleting a vertex
+.Node's `isAdjacent`
+[source, javascript]
+----
+include::{codedir}/data-structures/graphs/node.js[tag=isAdjacent, indent=0]
+----
 
-Body text
 
 == Deleting an edge
 
-Body text
+.Graphs's `removeEdge` method
+[source, javascript]
+----
+include::{codedir}/data-structures/graphs/graph.js[tag=removeEdge, indent=0]
+----
+
+.Node's `removeAdjacent`
+[source, javascript]
+----
+include::{codedir}/data-structures/graphs/node.js[tag=removeAdjacent, indent=0]
+----
 
 == Graph Complexity
 
-Graph search has its own chapter
+
 
 = Summary
 

src/data-structures/graphs/graph.js

@@ -4,23 +4,10 @@ const Stack = require('../stacks/stack');
 const Queue = require('../queues/queue');
 const HashMap = require('../maps/hash-maps/hash-map');
 
+// tag::constructor[]
 /**
- * Graph that uses an adjacent list
- *
- * Most common operations:
- * - Add vertex
- * - Add edge
- * - Remove vertex
- * - Remove edge
- * - Query (query if two vertices are connected)
- *
- *  - Graph search (BFS, DFS)
- *
- * - Find path (between two vertices)
- * - Find all paths (between two vertices)
- * - Find shortest paths (between two vertices)
+ * Graph data structure implemented with an adjacent list
  */
-// tag::constructor[]
 class Graph {
   /**
    * Initialize the nodes map
@@ -32,21 +19,24 @@ class Graph {
   }
 // end::constructor[]
 
+// tag::addVertex[]
   /**
    * Add a node to the graph.
    * Runtime: O(1)
    * @param {any} value node's value
    * @returns {Node} the new node or the existing one if it already exits.
    */
   addVertex(value) {
-    if (this.nodes.has(value)) {
+    if (this.nodes.has(value)) { // <1>
       return this.nodes.get(value);
     }
-    const vertex = new Node(value);
-    this.nodes.set(value, vertex);
+    const vertex = new Node(value); // <2>
+    this.nodes.set(value, vertex); // <3>
     return vertex;
   }
+// end::addVertex[]
 
+// tag::removeVertex[]
   /**
    * Removes node from graph
    * It also removes the reference of the deleted node from
@@ -55,13 +45,15 @@ class Graph {
    * @param {any} value node's value
    */
   removeVertex(value) {
-    const current = this.nodes.get(value);
+    const current = this.nodes.get(value); // <1>
     if (current) {
-      Array.from(this.nodes.values()).forEach(node => node.removeAdjacent(current));
+      Array.from(this.nodes.values()).forEach(node => node.removeAdjacent(current)); // <2>
     }
-    return this.nodes.delete(value);
+    return this.nodes.delete(value); // <3>
   }
+// end::removeVertex[]
 
+// tag::addEdge[]
   /**
    * Create a connection between source node and destination node.
    * If the graph is undirected it will also create the conneciton from destination to destination.
@@ -72,18 +64,20 @@ class Graph {
    * @returns {[Node, Node]} source/destination node pair
    */
   addEdge(source, destination) {
-    const sourceNode = this.addVertex(source);
-    const destinationNode = this.addVertex(destination);
+    const sourceNode = this.addVertex(source); // <1>
+    const destinationNode = this.addVertex(destination); // <1>
 
-    sourceNode.addAdjacent(destinationNode);
+    sourceNode.addAdjacent(destinationNode); // <2>
 
     if (this.edgeDirection === Graph.UNDIRECTED) {
-      destinationNode.addAdjacent(sourceNode);
+      destinationNode.addAdjacent(sourceNode); // <3>
     }
 
     return [sourceNode, destinationNode];
   }
+// end::addEdge[]
 
+// tag::removeEdge[]
   /**
    * Remove connection between source node and destination.
    * If the graph is undirected it will also remove the conneciton from destination to destination.
@@ -107,7 +101,9 @@ class Graph {
 
     return [sourceNode, destinationNode];
   }
+// end::removeEdge[]
 
+// tag::areAdjacents[]
   /**
    * True if two nodes are adjacent to each other
    * @param {any} source node's value
@@ -123,6 +119,7 @@ class Graph {
 
     return false;
   }
+// end::areAdjacents[]
 
   /**
    * Depth-first search
@@ -249,14 +246,16 @@ class Graph {
     });
     return paths;
   }
+// tag::constructor[]
 }
 
 Graph.UNDIRECTED = Symbol('directed graph'); // one-way edges
 Graph.DIRECTED = Symbol('undirected graph'); // two-ways edges
+// end::constructor[]
 
 module.exports = Graph;
 
 /*
  * https://repl.it/@amejiarosario/graphpy
  * http://www.pythontutor.com/visualize.html#mode=edit - https://goo.gl/Xp7Zpm
- */
+ */

src/data-structures/graphs/node.js

@@ -10,8 +10,9 @@ class Node {
       this.value = value;
       this.adjacents = new HashSet(); // adjacency list
     }
-  // end::constructor[]
+    // end::constructor[]
 
+    // tag::addAdjacent[]
     /**
      * Add node to adjacency list
      * Runtime: O(1)
@@ -20,7 +21,9 @@ class Node {
     addAdjacent(node) {
       this.adjacents.add(node);
     }
-  
+    // end::addAdjacent[]
+
+    // tag::removeAdjacent[]
     /**
      * Remove node from adjacency list
      * Runtime: O(1)
@@ -30,7 +33,9 @@ class Node {
     removeAdjacent(node) {
       return this.adjacents.delete(node);
     }
-  
+    // end::removeAdjacent[]
+
+    // tag::isAdjacent[]
     /**
      * Check if a Node is adjacent to other
      * Runtime: O(1)
@@ -39,14 +44,17 @@ class Node {
     isAdjacent(node) {
       return this.adjacents.has(node);
     }
-  
+    // end::isAdjacent[]
+
     /**
      * Get all adjacent nodes
      */
     getAdjacents() {
       return Array.from(this.adjacents);
     }
+  // tag::constructor[]
   }
+  // end::constructor[]
 
   module.exports = Node;