volksdata/include/graph.h

#ifndef _LSUP_GRAPH_H
#define _LSUP_GRAPH_H

#include "store_htable.h"
#include "store_mdb.h"


typedef enum LSUP_store_type {
    LSUP_STORE_MEM,
    LSUP_STORE_MDB
} LSUP_store_type;


/** @brief Graph object.
 */
typedef struct Graph LSUP_Graph;

/** @brief Graph iterator.
 *
 * This opaque handle is generated by #LSUP_graph_lookup and is used to iterate
 * over lookup results with #LSUP_graph_iter_next. It must be freed with
 * #LSUP_graph_iter_free when done.
 */
typedef struct GraphIterator LSUP_GraphIterator;


/** @brief Create an empty graph.
 *
 * The new graph has zero capacity and a random URN. To change either one, use
 * #LSUP_graph_resize and #LSUP_graph_set_uri, respectively.
 *
 * @param store_type[in] TYpe of store for the graph. One of the values of
 *  #LSUP_store_type.
 *
 * @param gr[out] Pointer to a pointer to the new graph. It must be freed with
 *  #LSUP_graph_free when done.
 *
 * @return LSUP_OK if the graph was created, or < 0 if an error occurred.
 */
LSUP_rc
LSUP_graph_new(const LSUP_store_type store_type, LSUP_Graph **gr);


/** @brief copy a graph into a new one.
 *
 * The new graph is compacted to the minimum required size.
 *
 * src[in] Graph to be copied.
 *
 * @param uri URI of the destination graph. If NULL, a UUID4 URN is generated.
 *
 * @param gr[out] Pointer to a pointer to the destination graph. It must be
 *  freed with #LSUP_graph_free when done.
 *
 * @return LSUP_OK if the graph was copied, or < 0 if an error occurred.
 */
LSUP_rc
LSUP_graph_copy(const LSUP_Graph *src, LSUP_Graph **dest);


/** Perform a boolean operation between two graphs.
 *
 * This method yields a new graph as the result of the operation.
 *
 * @param op[in] Operation to perform. One of #LSUP_bool_op.
 *
 * @param gr1[in] First operand.
 *
 * @param gr2[in] Second operand.
 *
 * @param res[out] Result graph. It must be freed with #LSUP_graph_free when
 *  done.
 */
LSUP_rc
LSUP_graph_bool_op(
        const LSUP_bool_op op, const LSUP_Graph *gr1, const LSUP_Graph *gr2,
        LSUP_Graph **res);


/** @brief Free a graph.
 */
void
LSUP_graph_free(LSUP_Graph *gr);


/** @brief Number of triples that can be stored without resizing the graph.
 *
 * @return Dynamic capacity of an in-memory graph or maximum allowed memory for
 *  an MDB graph.
 */
size_t
LSUP_graph_capacity(const LSUP_Graph *gr);


/** @brief Number of triples in a graph.
 */
size_t
LSUP_graph_size(const LSUP_Graph *gr);


/** @brief Change the capacity of an in-memory graph.
 *
 * This is useful ahead of a bulk load to save multiple reallocs. Otherwise,
 * the graph expands automatically on new inserts when capacity is reached.
 *
 * @param gr[in] Graph to be resized.
 *
 * @param size[in] New size. This will never be smaller than the current
 *  occupied space. Therefore setting this value to 0 effectively compacts the
 *  graph storage.
 *
 * @return LSUP_OK if the operation was successful; LSUP_VALUE_ERR if the store
 *  type of the graph is not LSUP_STORE_MEM; <0 if an error occurs while
 *  resizing.
 */
LSUP_rc
LSUP_graph_resize(LSUP_Graph *gr, size_t size);


/** @brief Read-only graph URI.
 *
 * To change the graph URI, use #LSUP_graph_set_uri.
 */
LSUP_Term *
LSUP_graph_uri(const LSUP_Graph *gr);


/** Set the URI of a graph.
 *
 * @param gr[in] Graph whose URI is to be changed.
 *
 * @param uri[in] New URI as a string. If NULL, a UUID4 URN is generated.
 */
LSUP_rc
LSUP_graph_set_uri(LSUP_Graph *gr, const char *uri);

bool
LSUP_graph_contains(const LSUP_Graph *gr, const LSUP_Triple *spo);


/** @brief Add triples and/or serialized triples to a graph.
 *
 * For API users it may be more convenient to use the more specialized
 * #LSUP_graph_add_trp.
 */
LSUP_rc
LSUP_graph_add(
        LSUP_Graph *gr,
        const LSUP_Triple trp[], size_t trp_ct,
        const LSUP_SerTriple strp[], size_t strp_ct);

#define LSUP_graph_add_trp(gr, trp, ct) LSUP_graph_add(gr, trp, ct, NULL, 0)


/** @brief Delete triples by a matching pattern.
 *
 * @param gr[in] Graph to delete triples from.
 *
 * @param ptn[in] Matching pattern. Any and all of s, p, o can be NULL.
 *
 * @param ct[out] If not NULL it is populated with the number of triples
 *  deleted.
 */
LSUP_rc
LSUP_graph_remove(LSUP_Graph *gr, const LSUP_Triple *spo, size_t *ct);


/** Look up triples by a matching pattern and yield an iterator.
 *
 * @param gr[in] Graph to look up.
 *
 * @param spo[in] Triple to look for. Any and all terms can be NULL, which
 *  indicate unbound terms.
 *
 * @param it[out] Pointer to a #LSUP_GraphIterator to be generated. It must be
 *  freed with #LSUP_graph_iter_free after use.
 */
LSUP_rc
LSUP_graph_lookup(
        const LSUP_Graph *gr, const LSUP_Triple *spo,
        LSUP_GraphIterator **it_p);


/** @brief Advance a cursor obtained by a lookup and return a matching triple.
 *
 * @param it[in] Iterator handle obtained through #LSUP_graph_lookup.
 *
 * @param spo[out] Triple to be populated with the next result.
 *
 * @return LSUP_OK if a result was found; LSUP_END if the end of the match list
 *  was reached.
 */
LSUP_rc
LSUP_graph_iter_next(LSUP_GraphIterator *it, LSUP_Triple *spo);


/** @brief Free a graph iterator.
 */
void
LSUP_graph_iter_free(LSUP_GraphIterator *it);


/**
 * Set-theoretical union (gr1 ∪ gr2).
 *
 * The resulting Keyset is initialized beforehand and is not compacted.
 */
int LSUP_graph_join(LSUP_Graph *gr1, LSUP_Graph *gr2, LSUP_Graph *res);

/**
 * Set-theoretical complement (gr1 \ gr2).
 *
 * The resulting Keyset is initialized beforehand and is not compacted.
 */
int LSUP_graph_subtract(LSUP_Graph *gr1, LSUP_Graph *gr2, LSUP_Graph *res);

/**
 * Set-theoretical intersection (gr1 ∩ gr2).
 *
 * The resulting Keyset is initialized beforehand and is not compacted.
 */
int LSUP_graph_intersect(LSUP_Graph *gr1, LSUP_Graph *gr2, LSUP_Graph *res);

/**
 * Disjunctive union (XOR) (gr1 ⊕ gr2).
 *
 * The resulting Keyset is initialized beforehand and is not compacted.
 */
int LSUP_graph_xor(LSUP_Graph *gr1, LSUP_Graph *gr2, LSUP_Graph *res);

#endif