Graph Help

A graph is a collection of nodes (or vertices), and the connections between them, called edges. A node that is the end-point of an edge is called a neighbour of the node that is its starting-point. An edge can be directed or undirected. When it is directed, the edge goes only from one node to another (or the same). When it is undirected, it goes in the opposite direction as well. You'll want to use a graph data structure if you want to connect data in a particular way. You can easily use it to store relations between certain things, to draw a graph or even as a gps to find the shortest path between two points.

Functions:

ds_graph_create() Creates a new graph. The function returns an integer as an id that must be used in almost all other functions to access the particular graph.
ds_graph_destroy(id) Destroys the graph with the given id, freeing the memory used. Don't forget to call this function when you are ready with the structure.
ds_graph_clear(id) Clears the graph with the given id, removing all nodes from it but not destroying it.
ds_graph_copy(id,source) Copies the graph source into the graph with the given id.

ds_graph_node_add(id,value) Adds a new node to the graph with a given value. The function returns an integer as an id that must be used to refer to the particular node.
ds_graph_node_delete(id,node) Deletes the given node from the graph.
ds_graph_node_set(id,node,value) Replaces the value associated with the given node in the graph.
ds_graph_node_get(id,node) Returns the value associated with the given node in the graph.
ds_graph_node_clear(node) Deletes all edges starting from the given node. So all its neighbours are removed.

ds_graph_edge_add(id,from,to,value,directed) Adds a new edge from a given node to a given node in the graph and associates a value with it. directed indicates whether the same shouldn't happen in the opposite direction (from to to from).
ds_graph_edge_delete(from,to,directed) Deletes the edge from a given node to a given node.
ds_graph_edge_set(from,to,value) Replaces the value associated with the edge from a given node to a given node.
ds_graph_edge_get(from,to) Returns the value associated with the edge from a given node to a given node.
ds_graph_edge_clear(id) Deletes all edges in the given graph.

ds_graph_complete(id) Makes the graph complete. The function adds an undirected edge between every node in the given graph, including between the node itself.
ds_graph_traversal(start,kind) Traverses the graph in a particular way. start indicates the node to start from, and kind indicates the traversal type:

• tr_breadth Uses a breadth-first search.
• tr_depth Uses a depth-first search.

ds_graph_path(id,start,end,weighted,list) Returns the smallest distance between the start node and the end node in the graph. -1 if no connection exists. weighted indicates whether the graph should be treated as a weighted graph. If true, the value of each edge is the weight and must be a positive number, otherwise it's zero. The distance in a weighted graph is the sum of the weights of each edge in the shortest path between two nodes. If false (unweighted), the value of the edge doesn't matter. The distance is the number of edges in the shortest path between two nodes. The last argument list indicates whether the nodes of the calculated path should be stored in the given ds_list. This is useful when you want to do something with the path. Use -1 if you don't want to store it into a list.
ds_graph_write(id) Turns the data structure into a string and returns this string. The string can then be used to e.g. save it to a file.
ds_graph_read(id,str) Reads the data structure from the given string (as created by the previous call).

Some functions can be used for the graph as well as each node separately.
(id can refer to a graph as well as a node, and node can refer to a node itself as well as a particular neighbour of the node).

Graph:
ds_graph_size(id) Returns the number of nodes in the given graph.
ds_graph_empty(id) Returns whether the graph is empty. This is the same as testing whether the size is 0.
ds_graph_exists(id,node) Returns whether the given node exists in the graph.
ds_graph_list(id) Returns a ds_list containing all nodes in the graph. This is useful when you want to iterate all the nodes separately.
ds_graph_find_previous(id,node) Returns the node with the largest id in the graph smaller than the indicated node. (Note that the node is returned, not the value).
ds_graph_find_next(id,node) Returns the node with the smallest id in the graph larger than the indicated node.
ds_graph_find_first(id) Returns the node with the smallest id in the graph.
ds_graph_find_last(id) Returns the node with the largest id in the graph.

Node:
ds_graph_size(node) Returns the number of neighbours of the node.
ds_graph_empty(node) Returns whether the node has no neighbours. This is the same as testing whether the size is 0.
ds_graph_exists(node,neighbour) Returns whether the given node (neighbour) is a neighbour of the node.
ds_graph_list(node) Returns a ds_list containing all neighbours of the node. This is useful when you want to iterate all the neighbours separately.
ds_graph_find_previous(node,neighbour) Returns the neighbour of the node with the largest id smaller than the indicated neighbour.
ds_graph_find_next(node,neighbour) Returns the neighbour of the node with the smallest id larger than the indicated neighbour.
ds_graph_find_first(id) Returns the neighbour of the node with the smallest id.
ds_graph_find_last(id) Returns the neighbour of the node with the largest id.