aboutsummaryrefslogtreecommitdiffstats
path: root/include/serd
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2021-04-11 22:07:39 -0400
committerDavid Robillard <d@drobilla.net>2022-01-14 19:37:51 -0500
commite9b773bf452f0df0ea69e363bcb5899fea124b28 (patch)
tree6cec0e4c4d93e2fbb56576fc6992169bd985fd52 /include/serd
parent37b14ad8b07f7e8d647e15a05339d31f2ee4dd58 (diff)
downloadserd-e9b773bf452f0df0ea69e363bcb5899fea124b28.tar.gz
serd-e9b773bf452f0df0ea69e363bcb5899fea124b28.tar.bz2
serd-e9b773bf452f0df0ea69e363bcb5899fea124b28.zip
Add model
Diffstat (limited to 'include/serd')
-rw-r--r--include/serd/serd.h409
1 files changed, 408 insertions, 1 deletions
diff --git a/include/serd/serd.h b/include/serd/serd.h
index 77986150..efa48543 100644
--- a/include/serd/serd.h
+++ b/include/serd/serd.h
@@ -205,6 +205,7 @@ typedef enum {
SERD_ERR_UNKNOWN, ///< Unknown error
SERD_ERR_BAD_SYNTAX, ///< Invalid syntax
SERD_ERR_BAD_ARG, ///< Invalid argument
+ SERD_ERR_BAD_CURSOR, ///< Use of invalidated cursor
SERD_ERR_NOT_FOUND, ///< Not found
SERD_ERR_ID_CLASH, ///< Encountered clashing blank node IDs
SERD_ERR_BAD_CURIE, ///< Invalid CURIE or unknown namespace prefix
@@ -215,6 +216,7 @@ typedef enum {
SERD_ERR_NO_DATA, ///< Unexpected end of input
SERD_ERR_BAD_CALL, ///< Invalid call
SERD_ERR_BAD_URI, ///< Invalid or unresolved URI
+ SERD_ERR_BAD_INDEX, ///< No optimal model index available
} SerdStatus;
/**
@@ -547,7 +549,7 @@ serd_write_file_uri(SerdStringView path,
@{
*/
-/// A syntactic RDF node
+/// An RDF node
typedef struct SerdNodeImpl SerdNode;
/**
@@ -2432,6 +2434,411 @@ serd_writer_finish(SerdWriter* SERD_NONNULL writer);
/**
@}
+ @defgroup serd_cursor Cursor
+ @{
+*/
+
+/**
+ A cursor that iterates over statements in a model.
+
+ A cursor is a smart iterator that visits all statements that match a
+ pattern.
+*/
+typedef struct SerdCursorImpl SerdCursor;
+
+/// Return a new copy of `cursor`
+SERD_API
+SerdCursor* SERD_ALLOCATED
+serd_cursor_copy(const SerdCursor* SERD_NULLABLE cursor);
+
+/// Return the statement pointed to by `cursor`
+SERD_API
+const SerdStatement* SERD_NULLABLE
+serd_cursor_get(const SerdCursor* SERD_NONNULL cursor);
+
+/**
+ Increment cursor to point to the next statement.
+
+ @return Failure if `cursor` was already at the end.
+*/
+SERD_API
+SerdStatus
+serd_cursor_advance(SerdCursor* SERD_NONNULL cursor);
+
+/// Return true if the cursor has reached its end
+SERD_PURE_API
+bool
+serd_cursor_is_end(const SerdCursor* SERD_NULLABLE cursor);
+
+/**
+ Return true iff `lhs` equals `rhs`.
+
+ Two cursors are equivalent if they point to the same statement in the same
+ index in the same model, or are both the end of the same model. Note that
+ two cursors can point to the same statement but not be equivalent, since
+ they may have reached the statement via different indices.
+*/
+SERD_PURE_API
+bool
+serd_cursor_equals(const SerdCursor* SERD_NULLABLE lhs,
+ const SerdCursor* SERD_NULLABLE rhs);
+
+/// Free `cursor`
+SERD_API
+void
+serd_cursor_free(SerdCursor* SERD_NULLABLE cursor);
+
+/**
+ @}
+ @defgroup serd_range Range
+ @{
+*/
+
+/// Flags that control the style of a model serialisation
+typedef enum {
+ SERD_NO_INLINE_OBJECTS = 1u << 0u ///< Disable object inlining
+} SerdDescribeFlag;
+
+/// Bitwise OR of SerdDescribeFlag values
+typedef uint32_t SerdDescribeFlags;
+
+/**
+ Describe a range of statements by writing to a sink.
+
+ This will consume the given cursor, and emit at least every statement it
+ visits. More statements from the model may be written in order to describe
+ anonymous blank nodes that are associated with a subject in the range.
+
+ The default is to write statements in an order suited for pretty-printing
+ with Turtle or TriG with as many anonymous nodes as possible. If
+ `SERD_NO_INLINE_OBJECTS` is given, a simple sorted stream is written
+ instead, which is faster since no searching is required, but can result in
+ ugly output for Turtle or Trig.
+*/
+SERD_API
+SerdStatus
+serd_describe_range(const SerdCursor* SERD_NULLABLE range,
+ const SerdSink* SERD_NONNULL sink,
+ SerdDescribeFlags flags);
+
+/**
+ @}
+ @defgroup serd_model Model
+ @{
+*/
+
+/// An indexed set of statements
+typedef struct SerdModelImpl SerdModel;
+
+/**
+ Statement ordering.
+
+ Statements themselves always have the same fields in the same order
+ (subject, predicate, object, graph), but a model can keep indices for
+ different orderings to provide good performance for different kinds of
+ queries.
+*/
+typedef enum {
+ SERD_ORDER_SPO, ///< Subject, Predicate, Object
+ SERD_ORDER_SOP, ///< Subject, Object, Predicate
+ SERD_ORDER_OPS, ///< Object, Predicate, Subject
+ SERD_ORDER_OSP, ///< Object, Subject, Predicate
+ SERD_ORDER_PSO, ///< Predicate, Subject, Object
+ SERD_ORDER_POS, ///< Predicate, Object, Subject
+ SERD_ORDER_GSPO, ///< Graph, Subject, Predicate, Object
+ SERD_ORDER_GSOP, ///< Graph, Subject, Object, Predicate
+ SERD_ORDER_GOPS, ///< Graph, Object, Predicate, Subject
+ SERD_ORDER_GOSP, ///< Graph, Object, Subject, Predicate
+ SERD_ORDER_GPSO, ///< Graph, Predicate, Subject, Object
+ SERD_ORDER_GPOS ///< Graph, Predicate, Object, Subject
+} SerdStatementOrder;
+
+/// Flags that control model storage and indexing
+typedef enum {
+ SERD_STORE_GRAPHS = 1u << 0u, ///< Store and index the graph of statements
+ SERD_STORE_CARETS = 1u << 1u, ///< Store original caret of statements
+} SerdModelFlag;
+
+/// Bitwise OR of SerdModelFlag values
+typedef uint32_t SerdModelFlags;
+
+/**
+ Create a new model.
+
+ @param world The world in which to make this model.
+
+ @param default_order The order for the default index, which is always
+ present and responsible for owning all the statements in the model. This
+ should almost always be #SERD_ORDER_SPO or #SERD_ORDER_GSPO (which
+ support writing pretty documents), but advanced applications that do not want
+ either of these indices can use a different order. Additional indices can
+ be added with serd_model_add_index().
+
+ @param flags Options that control what data is stored in the model.
+*/
+SERD_API
+SerdModel* SERD_ALLOCATED
+serd_model_new(SerdWorld* SERD_NONNULL world,
+ SerdStatementOrder default_order,
+ SerdModelFlags flags);
+
+/// Return a deep copy of `model`
+SERD_API
+SerdModel* SERD_ALLOCATED
+serd_model_copy(const SerdModel* SERD_NONNULL model);
+
+/// Return true iff `a` is equal to `b`, ignoring statement cursor metadata
+SERD_API
+bool
+serd_model_equals(const SerdModel* SERD_NULLABLE a,
+ const SerdModel* SERD_NULLABLE b);
+
+/// Close and free `model`
+SERD_API
+void
+serd_model_free(SerdModel* SERD_NULLABLE model);
+
+/**
+ Add an index for a particular statement order to the model.
+
+ @return Failure if this index already exists.
+*/
+SERD_API
+SerdStatus
+serd_model_add_index(SerdModel* SERD_NONNULL model, SerdStatementOrder order);
+
+/**
+ Add an index for a particular statement order to the model.
+
+ @return Failure if this index does not exist.
+*/
+SERD_API
+SerdStatus
+serd_model_drop_index(SerdModel* SERD_NONNULL model, SerdStatementOrder order);
+
+/// Get the world associated with `model`
+SERD_PURE_API
+SerdWorld* SERD_NONNULL
+serd_model_world(SerdModel* SERD_NONNULL model);
+
+/// Get all nodes interned in `model`
+SERD_PURE_API
+const SerdNodes* SERD_NONNULL
+serd_model_nodes(const SerdModel* SERD_NONNULL model);
+
+/// Get the default statement order of `model`
+SERD_PURE_API
+SerdStatementOrder
+serd_model_default_order(const SerdModel* SERD_NONNULL model);
+
+/// Get the flags enabled on `model`
+SERD_PURE_API
+SerdModelFlags
+serd_model_flags(const SerdModel* SERD_NONNULL model);
+
+/// Return the number of statements stored in `model`
+SERD_PURE_API
+size_t
+serd_model_size(const SerdModel* SERD_NONNULL model);
+
+/// Return true iff there are no statements stored in `model`
+SERD_PURE_API
+bool
+serd_model_empty(const SerdModel* SERD_NONNULL model);
+
+/**
+ Return a cursor at the start of every statement in the model.
+
+ The returned cursor will advance over every statement in the model's default
+ order.
+*/
+SERD_API
+SerdCursor* SERD_ALLOCATED
+serd_model_begin(const SerdModel* SERD_NONNULL model);
+
+/**
+ Return a cursor past the end of the model.
+
+ This returns the "universal" end cursor, which is equivalent to any cursor
+ for this model that has reached its end.
+*/
+SERD_CONST_API
+const SerdCursor* SERD_NONNULL
+serd_model_end(const SerdModel* SERD_NONNULL model);
+
+/// Return a cursor over all statements in the model in a specific order
+SERD_API
+SerdCursor* SERD_ALLOCATED
+serd_model_begin_ordered(const SerdModel* SERD_NONNULL model,
+ SerdStatementOrder order);
+
+/**
+ Search for statements that match a pattern.
+
+ @return An iterator to the first match, or NULL if no matches found.
+*/
+SERD_API
+SerdCursor* SERD_ALLOCATED
+serd_model_find(const SerdModel* SERD_NONNULL model,
+ const SerdNode* SERD_NULLABLE s,
+ const SerdNode* SERD_NULLABLE p,
+ const SerdNode* SERD_NULLABLE o,
+ const SerdNode* SERD_NULLABLE g);
+
+/**
+ Search for a single node that matches a pattern.
+
+ Exactly one of `s`, `p`, `o` must be NULL.
+ This function is mainly useful for predicates that only have one value.
+
+ @return The first matching node, or NULL if no matches are found.
+*/
+SERD_API
+const SerdNode* SERD_NULLABLE
+serd_model_get(const SerdModel* SERD_NONNULL model,
+ const SerdNode* SERD_NULLABLE s,
+ const SerdNode* SERD_NULLABLE p,
+ const SerdNode* SERD_NULLABLE o,
+ const SerdNode* SERD_NULLABLE g);
+
+/**
+ Search for a single statement that matches a pattern.
+
+ This function is mainly useful for predicates that only have one value.
+
+ @return The first matching statement, or NULL if none are found.
+*/
+SERD_API
+const SerdStatement* SERD_NULLABLE
+serd_model_get_statement(const SerdModel* SERD_NONNULL model,
+ const SerdNode* SERD_NULLABLE s,
+ const SerdNode* SERD_NULLABLE p,
+ const SerdNode* SERD_NULLABLE o,
+ const SerdNode* SERD_NULLABLE g);
+
+/// Return true iff a statement exists
+SERD_API
+bool
+serd_model_ask(const SerdModel* SERD_NONNULL model,
+ const SerdNode* SERD_NULLABLE s,
+ const SerdNode* SERD_NULLABLE p,
+ const SerdNode* SERD_NULLABLE o,
+ const SerdNode* SERD_NULLABLE g);
+
+/// Return the number of matching statements
+SERD_API
+size_t
+serd_model_count(const SerdModel* SERD_NONNULL model,
+ const SerdNode* SERD_NULLABLE s,
+ const SerdNode* SERD_NULLABLE p,
+ const SerdNode* SERD_NULLABLE o,
+ const SerdNode* SERD_NULLABLE g);
+
+/**
+ Add a statement to a model from nodes.
+
+ This function fails if there are any active iterators on `model`.
+*/
+SERD_API
+SerdStatus
+serd_model_add(SerdModel* SERD_NONNULL model,
+ const SerdNode* SERD_NONNULL s,
+ const SerdNode* SERD_NONNULL p,
+ const SerdNode* SERD_NONNULL o,
+ const SerdNode* SERD_NULLABLE g);
+
+/**
+ Add a statement to a model from nodes with a caret
+
+ This function fails if there are any active iterators on `model`.
+*/
+SERD_API
+SerdStatus
+serd_model_add_with_caret(SerdModel* SERD_NONNULL model,
+ const SerdNode* SERD_NONNULL s,
+ const SerdNode* SERD_NONNULL p,
+ const SerdNode* SERD_NONNULL o,
+ const SerdNode* SERD_NULLABLE g,
+ const SerdCaret* SERD_NULLABLE caret);
+
+/**
+ Add a statement to a model.
+
+ This function fails if there are any active iterators on `model`.
+ If statement is null, then SERD_FAILURE is returned.
+*/
+SERD_API
+SerdStatus
+serd_model_insert(SerdModel* SERD_NONNULL model,
+ const SerdStatement* SERD_NONNULL statement);
+
+/**
+ Add a range of statements to a model.
+
+ This function fails if there are any active iterators on `model`.
+*/
+SERD_API
+SerdStatus
+serd_model_insert_statements(SerdModel* SERD_NONNULL model,
+ SerdCursor* SERD_NONNULL range);
+
+/**
+ Remove a statement from a model via an iterator.
+
+ Calling this function invalidates all other iterators on this model.
+
+ @param model The model which `iter` points to.
+
+ @param cursor Cursor pointing to the element to erase. This cursor is
+ advanced to the next statement on return.
+*/
+SERD_API
+SerdStatus
+serd_model_erase(SerdModel* SERD_NONNULL model,
+ SerdCursor* SERD_NONNULL cursor);
+
+/**
+ Remove a range of statements from a model.
+
+ This can be used with serd_model_find() to erase all statements in a model
+ that match a pattern.
+
+ Calling this function invalidates all iterators on `model`.
+
+ @param model The model which `range` points to.
+
+ @param range Range to erase, which will be empty on return.
+*/
+SERD_API
+SerdStatus
+serd_model_erase_statements(SerdModel* SERD_NONNULL model,
+ SerdCursor* SERD_NONNULL range);
+
+/**
+ Remove everything from a model.
+
+ Calling this function invalidates all iterators on `model`.
+
+ @param model The model to clear.
+*/
+SERD_API
+SerdStatus
+serd_model_clear(SerdModel* SERD_NONNULL model);
+
+/**
+ @}
+ @defgroup serd_inserter Inserter
+ @{
+*/
+
+/// Create an inserter for writing statements to a model
+SERD_API
+SerdSink* SERD_ALLOCATED
+serd_inserter_new(SerdModel* SERD_NONNULL model,
+ const SerdNode* SERD_NULLABLE default_graph);
+
+/**
+ @}
@}
*/