graph.h 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232
  1. #ifndef _LSUP_GRAPH_H
  2. #define _LSUP_GRAPH_H
  3. #include "store_htable.h"
  4. #include "store_mdb.h"
  5. typedef enum LSUP_store_type {
  6. LSUP_STORE_MEM,
  7. LSUP_STORE_MDB
  8. } LSUP_store_type;
  9. /** @brief Graph object.
  10. */
  11. typedef struct Graph LSUP_Graph;
  12. /** @brief Graph iterator.
  13. *
  14. * This opaque handle is generated by #LSUP_graph_lookup and is used to iterate
  15. * over lookup results with #LSUP_graph_iter_next. It must be freed with
  16. * #LSUP_graph_iter_free when done.
  17. */
  18. typedef struct GraphIterator LSUP_GraphIterator;
  19. /** @brief Create an empty graph.
  20. *
  21. * The new graph has zero capacity and a random URN. To change either one, use
  22. * #LSUP_graph_resize and #LSUP_graph_set_uri, respectively.
  23. *
  24. * @param store_type[in] TYpe of store for the graph. One of the values of
  25. * #LSUP_store_type.
  26. *
  27. * @param gr[out] Pointer to a pointer to the new graph. It must be freed with
  28. * #LSUP_graph_free when done.
  29. *
  30. * @return LSUP_OK if the graph was created, or < 0 if an error occurred.
  31. */
  32. LSUP_rc
  33. LSUP_graph_new(const LSUP_store_type store_type, LSUP_Graph **gr);
  34. /** @brief copy a graph into a new one.
  35. *
  36. * The new graph is compacted to the minimum required size.
  37. *
  38. * src[in] Graph to be copied.
  39. *
  40. * @param uri URI of the destination graph. If NULL, a UUID4 URN is generated.
  41. *
  42. * @param gr[out] Pointer to a pointer to the destination graph. It must be
  43. * freed with #LSUP_graph_free when done.
  44. *
  45. * @return LSUP_OK if the graph was copied, or < 0 if an error occurred.
  46. */
  47. LSUP_rc
  48. LSUP_graph_copy(const LSUP_Graph *src, LSUP_Graph **dest);
  49. /** Perform a boolean operation between two graphs.
  50. *
  51. * This method yields a new graph as the result of the operation.
  52. *
  53. * @param op[in] Operation to perform. One of #LSUP_bool_op.
  54. *
  55. * @param gr1[in] First operand.
  56. *
  57. * @param gr2[in] Second operand.
  58. *
  59. * @param res[out] Result graph. It must be freed with #LSUP_graph_free when
  60. * done.
  61. */
  62. LSUP_rc
  63. LSUP_graph_bool_op(
  64. const LSUP_bool_op op, const LSUP_Graph *gr1, const LSUP_Graph *gr2,
  65. LSUP_Graph **res);
  66. /** @brief Free a graph.
  67. */
  68. void
  69. LSUP_graph_free(LSUP_Graph *gr);
  70. /** @brief Number of triples that can be stored without resizing the graph.
  71. *
  72. * @return Dynamic capacity of an in-memory graph or maximum allowed memory for
  73. * an MDB graph.
  74. */
  75. size_t
  76. LSUP_graph_capacity(const LSUP_Graph *gr);
  77. /** @brief Number of triples in a graph.
  78. */
  79. size_t
  80. LSUP_graph_size(const LSUP_Graph *gr);
  81. /** @brief Change the capacity of an in-memory graph.
  82. *
  83. * This is useful ahead of a bulk load to save multiple reallocs. Otherwise,
  84. * the graph expands automatically on new inserts when capacity is reached.
  85. *
  86. * @param gr[in] Graph to be resized.
  87. *
  88. * @param size[in] New size. This will never be smaller than the current
  89. * occupied space. Therefore setting this value to 0 effectively compacts the
  90. * graph storage.
  91. *
  92. * @return LSUP_OK if the operation was successful; LSUP_VALUE_ERR if the store
  93. * type of the graph is not LSUP_STORE_MEM; <0 if an error occurs while
  94. * resizing.
  95. */
  96. LSUP_rc
  97. LSUP_graph_resize(LSUP_Graph *gr, size_t size);
  98. /** @brief Read-only graph URI.
  99. *
  100. * To change the graph URI, use #LSUP_graph_set_uri.
  101. */
  102. LSUP_Term *
  103. LSUP_graph_uri(const LSUP_Graph *gr);
  104. /** Set the URI of a graph.
  105. *
  106. * @param gr[in] Graph whose URI is to be changed.
  107. *
  108. * @param uri[in] New URI as a string. If NULL, a UUID4 URN is generated.
  109. */
  110. LSUP_rc
  111. LSUP_graph_set_uri(LSUP_Graph *gr, const char *uri);
  112. bool
  113. LSUP_graph_contains(const LSUP_Graph *gr, const LSUP_Triple *spo);
  114. /** @brief Add triples and/or serialized triples to a graph.
  115. *
  116. * For API users it may be more convenient to use the more specialized
  117. * #LSUP_graph_add_trp.
  118. */
  119. LSUP_rc
  120. LSUP_graph_add(
  121. LSUP_Graph *gr,
  122. const LSUP_Triple trp[], size_t trp_ct,
  123. const LSUP_SerTriple strp[], size_t strp_ct, size_t *inserted);
  124. #define LSUP_graph_add_trp(gr, trp, ct, ins) \
  125. LSUP_graph_add(gr, trp, ct, NULL, 0, ins)
  126. /** @brief Delete triples by a matching pattern.
  127. *
  128. * @param gr[in] Graph to delete triples from.
  129. *
  130. * @param ptn[in] Matching pattern. Any and all of s, p, o can be NULL.
  131. *
  132. * @param ct[out] If not NULL it is populated with the number of triples
  133. * deleted.
  134. */
  135. LSUP_rc
  136. LSUP_graph_remove(LSUP_Graph *gr, const LSUP_Triple *spo, size_t *ct);
  137. /** Look up triples by a matching pattern and yield an iterator.
  138. *
  139. * @param gr[in] Graph to look up.
  140. *
  141. * @param spo[in] Triple to look for. Any and all terms can be NULL, which
  142. * indicate unbound terms.
  143. *
  144. * @param it[out] Pointer to a #LSUP_GraphIterator to be generated. It must be
  145. * freed with #LSUP_graph_iter_free after use.
  146. */
  147. LSUP_rc
  148. LSUP_graph_lookup(
  149. const LSUP_Graph *gr, const LSUP_Triple *spo,
  150. LSUP_GraphIterator **it_p);
  151. /** @brief Advance a cursor obtained by a lookup and return a matching triple.
  152. *
  153. * @param it[in] Iterator handle obtained through #LSUP_graph_lookup.
  154. *
  155. * @param spo[out] Triple to be populated with the next result.
  156. *
  157. * @return LSUP_OK if a result was found; LSUP_END if the end of the match list
  158. * was reached.
  159. */
  160. LSUP_rc
  161. LSUP_graph_iter_next(LSUP_GraphIterator *it, LSUP_Triple *spo);
  162. /** @brief Free a graph iterator.
  163. */
  164. void
  165. LSUP_graph_iter_free(LSUP_GraphIterator *it);
  166. /**
  167. * Set-theoretical union (gr1 ∪ gr2).
  168. *
  169. * The resulting Keyset is initialized beforehand and is not compacted.
  170. */
  171. int LSUP_graph_join(LSUP_Graph *gr1, LSUP_Graph *gr2, LSUP_Graph *res);
  172. /**
  173. * Set-theoretical complement (gr1 \ gr2).
  174. *
  175. * The resulting Keyset is initialized beforehand and is not compacted.
  176. */
  177. int LSUP_graph_subtract(LSUP_Graph *gr1, LSUP_Graph *gr2, LSUP_Graph *res);
  178. /**
  179. * Set-theoretical intersection (gr1 ∩ gr2).
  180. *
  181. * The resulting Keyset is initialized beforehand and is not compacted.
  182. */
  183. int LSUP_graph_intersect(LSUP_Graph *gr1, LSUP_Graph *gr2, LSUP_Graph *res);
  184. /**
  185. * Disjunctive union (XOR) (gr1 ⊕ gr2).
  186. *
  187. * The resulting Keyset is initialized beforehand and is not compacted.
  188. */
  189. int LSUP_graph_xor(LSUP_Graph *gr1, LSUP_Graph *gr2, LSUP_Graph *res);
  190. #endif