Cytoplasm/src/include/Graph.h
Jordan Bancino e592cd8e5c Add basic Graph API.
This is going to be useful with state resolution and dependency ordering,
both of which will be crutial components of Telodendria.
2023-07-16 01:12:56 +00:00

175 lines
6.6 KiB
C

/*
* Copyright (C) 2022-2023 Jordan Bancino <@jordan:bancino.net>
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation files
* (the "Software"), to deal in the Software without restriction,
* including without limitation the rights to use, copy, modify, merge,
* publish, distribute, sublicense, and/or sell copies of the Software,
* and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
#ifndef CYTOPLASM_GRAPH_H
#define CYTOPLASM_GRAPH_H
/***
* @Nm Graph
* @Nd Extremely simple graph, implemented as an adjacency matrix.
* @Dd July 15 2023
*
* .Nm
* is a basic graph data structure originally written for a computer
* science class on data structures and algorithms, in which it
* received full credit. This is an adaptation of the original
* implementation that follows the Cytoplasm style and uses Cytoplasm
* APIs when convenient.
* .P
* .Nm
* stores data in an adjacency matrix, which means the storage
* complexity is O(N^2), where N is the number of vertices (called
* Nodes in this implementation) in the graph. However, this makes the
* algorithms fast and efficient.
* .P
* Nodes are identified by index, so the first node is 0, the second
* is 1, and so on. This data structure does not support storing
* arbitrary data as nodes; rather, the intended use case is to add
* all your node data to an Array, thus giving each node an index,
* and then manipulating the graph with that index. This allows access
* to node data in O(1) time in call cases, and is the most memory
* efficient.
* .P
* .Nm
* can be used to store a variety of types of graphs, although it is
* primarily suited to directed and weighted graphs.
*/
#include <stddef.h>
/**
* The functions provided here operate on an opaque graph structure.
* This structure really just stores a matrix in a contiguous block of
* memory, as well as the number of nodes in the graph, but the
* structure is kept opaque so that it remains internally consistent.
* It also maintains the style of the Cytoplasm library.
*/
typedef struct Graph Graph;
/**
* An Edge is really just a weight, which is easily represented by an
* integer. However, it makes sense to alias this to Edge for clarity,
* both in the documentation and in the implementation.
*/
typedef int Edge;
/**
* A Node is really just a row or column in the matrix, which is easily
* represented by an unsigned integer. However, it makes sense to alias
* this to Node for clarity, both in the documentation and the
* implementation.
*/
typedef size_t Node;
/**
* Create a new graph structure with the given number of vertices.
*/
extern Graph *GraphCreate(size_t);
/**
* Create a new graph data structure with the given number of vertices
* and the given adjacency matrix. The adjacency matrix is copied
* verbatim into the graph data structure without any validation.
*/
extern Graph *GraphCreateWithEdges(size_t, Edge *);
/**
* Free all memory associated with the given graph. Since graphs are
* just a collection of numbers, they do not depend on each other in
* any way.
*/
extern void GraphFree(Graph *);
/**
* Get the weight of the edge connecting the node specified first to
* the node specified second. If this is a directed graph, it does not
* necessarily follow that there is an edge from the node specified
* second to the node specified first. It also does not follow that
* such an edge, if it exists, has the same weight.
* .P
* This function will return -1 if the graph is invalid or either node
* is out of bounds. It will return 0 if there is no such edge from the
* node specified first to the node specified second.
*/
extern Edge GraphEdgeGet(Graph *, Node, Node);
/**
* Set the weight of the edge connecting the node specified first to
* the node specified second. If this is not a directed graph, this
* function will have to be called twice, the second time reversing the
* order of the nodes. To remove the edge, specify a weight of 0.
*/
extern Edge GraphEdgeSet(Graph *, Node, Node, Edge);
/**
* Get the number of nodes in the given graph. This operation is a
* simple memory access that happens in O(1) time.
*/
extern size_t GraphCountNodes(Graph *);
/**
* Perform a breadth-first search on the given graph, starting at the
* specified node. This function returns a list of nodes in the order
* they were touched. The size of the list is stored in the unsigned
* integer pointed to by the last argument.
* .P
* If an error occurs, NULL will be returned. Otherwise, the returned
* pointer should be freed with the Memory API when it is no longer
* needed.
*/
extern Node * GraphBreadthFirstSearch(Graph *, Node, size_t *);
/**
* Perform a depth-first search on the given graph, starting at the
* specified node. This function returns a list of nodes in the order
* they were touched. The size of the list is stored in the unsigned
* integer pointed to by the last argument.
* .P
* If an error occurs, NULL will be returned. Otherwise the returned
* pointer should be freed with the Memory API when it is no longer
* needed.
*/
extern Node *GraphDepthFirstSearch(Graph *, Node, size_t *);
/**
* Perform a topological sort on the given graph. This function returns
* a list of nodes in topological ordering, though note that this is
* probably not the only topological ordering that exists for the
* graph. The size of the list is stored in the unsigned integer
* pointed to by the last argument. It should always be the number of
* nodes in the graph, but is provided for consistency and convenience.
* .P
* If an error occurs, NULL will be returned. Otherwise the returned
* pointer should be freed with the Memory API when it is no longer
* needed.
*/
extern Node *GraphTopologicalSort(Graph *, size_t *);
/**
* Transpose the given graph, returning a brand new graph that is the
* result of the transposition.
*/
extern Graph * GraphTranspose(Graph *);
#endif /* CYTOPLASM_GRAPH_H */