Initial Commit

OU4/include/graph.h

@@ -0,0 +1,200 @@
+#ifndef __GRAPH_H
+#define __GRAPH_H
+
+#include <stdbool.h>
+#include "util.h"
+#include "dlist.h"
+
+/*
+ * Declaration of a generic graph for the "Datastructures and
+ * algorithms" courses at the Department of Computing Science, Umea
+ * University. The graph stores nodes and edges of a directed or
+ * undirected graph. After use, the function graph_kill() must
+ * be called to de-allocate the dynamic memory used by the graph
+ * itself. The de-allocation of any dynamic memory allocated for the
+ * node names is the responsibility of the user of the graph.
+ *
+ * Author: Niclas Borlin (niclas.borlin@cs.umu.se)
+ *
+ * Version information:
+ *   v1.0  2019-02-21: First public version.
+
+ *   v1.01 2019-02-26: Modified include directives for header files
+ *                     from the codebase to use "" to handle case when
+ *                     student stores all header files in the current
+ *                     directory. See
+ *                     https://stackoverflow.com/questions/21593/what-is-the-difference-between-include-filename-and-include-filename.
+ *   v1.02 2019-03-01: Doc update in graph_node_is_seen().
+ *   v1.1  2019-03-06: Changed several const node * to node *.
+ *                     Fixed doc bug to state that any dynamic memory allocated
+ *                     to the node NAMES is the resposibility of the user.
+ */
+
+// ====================== PUBLIC DATA TYPES ==========================
+
+// Anonymous declarations of node and graph.
+typedef struct node node;
+typedef struct graph graph;
+
+// =================== NODE COMPARISON FUNCTION ======================
+
+/**
+ * nodes_are_equal() - Check whether two nodes are equal.
+ * @n1: Pointer to node 1.
+ * @n2: Pointer to node 2.
+ *
+ * Returns: true if the nodes are considered equal, otherwise false.
+ *
+ */
+bool nodes_are_equal(const node *n1,const node *n2);
+
+// =================== GRAPH STRUCTURE INTERFACE ======================
+
+/**
+ * graph_empty() - Create an empty graph.
+ * @max_nodes: The maximum number of nodes the graph can hold.
+ *
+ * Returns: A pointer to the new graph.
+ */
+graph *graph_empty(int max_nodes);
+
+/**
+ * graph_is_empty() - Check if a graph is empty, i.e. has no nodes.
+ * @g: Graph to check.
+ *
+ * Returns: True if graph is empty, otherwise false.
+ */
+bool graph_is_empty(const graph *g);
+
+/**
+ * graph_has_edges() - Check if a graph has any edges.
+ * @g: Graph to check.
+ *
+ * Returns: True if graph has any edges, otherwise false.
+ */
+bool graph_has_edges(const graph *g);
+
+/**
+ * graph_insert_node() - Inserts a node with the given name into the graph.
+ * @g: Graph to manipulate.
+ * @s: Node name.
+ *
+ * Creates a new node with a copy of the given name and puts it into
+ * the graph.
+ *
+ * Returns: The modified graph.
+ */
+graph *graph_insert_node(graph *g, const char *s);
+
+/**
+ * graph_find_node() - Find a node stored in the graph.
+ * @g: Graph to manipulate.
+ * @s: Node identifier, e.g. a char *.
+ *
+ * Returns: A pointer to the found node, or NULL.
+ */
+node *graph_find_node(const graph *g, const char *s);
+
+/**
+ * graph_node_is_seen() - Return the seen status for a node.
+ * @g: Graph storing the node.
+ * @n: Node in the graph to return seen status for.
+ *
+ * Returns: The seen status for the node.
+ */
+bool graph_node_is_seen(const graph *g, const node *n);
+
+/**
+ * graph_node_set_seen() - Set the seen status for a node.
+ * @g: Graph storing the node.
+ * @n: Node in the graph to set seen status for.
+ * @s: Status to set.
+ *
+ * Returns: The modified graph.
+ */
+graph *graph_node_set_seen(graph *g, node *n, bool seen);
+
+/**
+ * graph_reset_seen() - Reset the seen status on all nodes in the graph.
+ * @g: Graph to modify.
+ *
+ * Returns: The modified graph.
+ */
+graph *graph_reset_seen(graph *g);
+
+/**
+ * graph_insert_edge() - Insert an edge into the graph.
+ * @g: Graph to manipulate.
+ * @n1: Source node (pointer) for the edge.
+ * @n2: Destination node (pointer) for the edge.
+ *
+ * NOTE: Undefined unless both nodes are already in the graph.
+ *
+ * Returns: The modified graph.
+ */
+graph *graph_insert_edge(graph *g, node *n1, node *n2);
+
+/**
+ * graph_delete_node() - Remove a node from the graph.
+ * @g: Graph to manipulate.
+ * @n: Node to remove from the graph.
+ *
+ * Returns: The modified graph.
+ *
+ * NOTE: Undefined if the node is not in the graph.
+ */
+graph *graph_delete_node(graph *g, node *n);
+
+/**
+ * graph_delete_edge() - Remove an edge from the graph.
+ * @g: Graph to manipulate.
+ * @n1: Source node (pointer) for the edge.
+ * @n2: Destination node (pointer) for the edge.
+ *
+ * Returns: The modified graph.
+ *
+ * NOTE: Undefined if the edge is not in the graph.
+ */
+graph *graph_delete_edge(graph *g, node *n1, node *n2);
+
+/**
+ * graph_choose_node() - Return an arbitrary node from the graph.
+ * @g: Graph to inspect.
+ *
+ * Returns: A pointer to an arbitrayry node.
+ *
+ * NOTE: The return value is undefined for an empty graph.
+ */
+node *graph_choose_node(const graph *g);
+
+/**
+ * graph_neighbours() - Return a list of neighbour nodes.
+ * @g: Graph to inspect.
+ * @n: Node to get neighbours for.
+ *
+ * Returns: A pointer to a list of nodes. Note: The list must be
+ * dlist_kill()-ed after use.
+ */
+dlist *graph_neighbours(const graph *g,const node *n);
+
+/**
+ * graph_kill() - Destroy a given graph.
+ * @g: Graph to destroy.
+ *
+ * Return all dynamic memory used by the graph.
+ *
+ * Returns: Nothing.
+ */
+void graph_kill(graph *g);
+
+/**
+ * graph_print() - Iterate over the graph elements and print their values.
+ * @g: Graph to inspect.
+ *
+ * Iterates over the graph and prints its contents.
+ *
+ * Returns: Nothing.
+ */
+void graph_print(const graph *g);
+
+#endif