Sord: Sord

Sord 0.16.16

Typedefs | Enumerations
Sord

## Detailed Description

A lightweight RDF model library.

Sord stores RDF (subject object predicate context) quads, where the context may be omitted (to represent triples in the default graph).

## Typedefs
typedef struct SordWorldImpl | SordWorld
typedef struct SordModelImpl | SordModel
typedef struct SordInserterImpl | SordInserter
typedef struct SordIterImpl | SordIter
typedef struct SordNodeImpl | SordNode
typedef const SordNode * | SordQuad[4]

## Enumerations
enum | SordQuadIndex { SORD_SUBJECT = 0U , SORD_PREDICATE = 1U , SORD_OBJECT = 2U , SORD_GRAPH = 3U }
enum | SordNodeType { SORD_URI = 1U , SORD_BLANK = 2U , SORD_LITERAL = 3U }
enum | SordIndexOption { SORD_SPO = 1U , SORD_SOP = 1U << 1U , SORD_OPS = 1U << 2U , SORD_OSP = 1U << 3U , SORD_PSO = 1U << 4U , SORD_POS = 1U << 5U }

## World
SORD_API SordWorld * | sord_world_new (void)
SORD_API void | sord_world_free (SordWorld *world)
SORD_API void | sord_world_set_error_sink (SordWorld *world, SerdErrorSink error_sink, void *handle)

## Node
SORD_API SordNode * | sord_new_uri (SordWorld *world, const uint8_t *uri)
SORD_API SordNode * | sord_new_relative_uri (SordWorld *world, const uint8_t *uri, const uint8_t *base_uri)
SORD_API SordNode * | sord_new_blank (SordWorld *world, const uint8_t *str)
SORD_API SordNode * | sord_new_literal (SordWorld *world, SordNode *datatype, const uint8_t *str, const char *lang)
SORD_API SordNode * | sord_node_copy (const SordNode *node)
SORD_API void | sord_node_free (SordWorld *world, SordNode *node)
SORD_API SordNodeType | sord_node_get_type (const SordNode *node)
SORD_API const uint8_t * | sord_node_get_string (const SordNode *node)
SORD_API const uint8_t * | sord_node_get_string_counted (const SordNode *node, size_t *bytes)
SORD_API const uint8_t * | sord_node_get_string_measured (const SordNode *node, size_t *bytes, size_t *chars)
SORD_API const char * | sord_node_get_language (const SordNode *node)
SORD_API SordNode * | sord_node_get_datatype (const SordNode *node)
SORD_API SerdNodeFlags | sord_node_get_flags (const SordNode *node)
SORD_API bool | sord_node_is_inline_object (const SordNode *node)
SORD_API bool | sord_node_equals (const SordNode *a, const SordNode *b)
SORD_API const SerdNode * | sord_node_to_serd_node (const SordNode *node)
SORD_API SordNode * | sord_node_from_serd_node (SordWorld *world, SerdEnv *env, const SerdNode *node, const SerdNode *datatype, const SerdNode *lang)

## Model
SORD_API SordModel * | sord_new (SordWorld *world, unsigned indices, bool graphs)
SORD_API void | sord_free (SordModel *model)
SORD_API SordWorld * | sord_get_world (SordModel *model)
SORD_API size_t | sord_num_nodes (const SordWorld *world)
SORD_API size_t | sord_num_quads (const SordModel *model)
SORD_API SordIter * | sord_begin (const SordModel *model)
SORD_API SordIter * | sord_find (SordModel *model, const SordQuad pat)
SORD_API SordIter * | sord_search (SordModel *model, const SordNode *s, const SordNode *p, const SordNode *o, const SordNode *g)
SORD_API SordNode * | sord_get (SordModel *model, const SordNode *s, const SordNode *p, const SordNode *o, const SordNode *g)
SORD_API bool | sord_ask (SordModel *model, const SordNode *s, const SordNode *p, const SordNode *o, const SordNode *g)
SORD_API uint64_t | sord_count (SordModel *model, const SordNode *s, const SordNode *p, const SordNode *o, const SordNode *g)
SORD_API bool | sord_contains (SordModel *model, const SordQuad pat)
SORD_API bool | sord_add (SordModel *model, const SordQuad tup)
SORD_API void | sord_remove (SordModel *model, const SordQuad tup)
SORD_API SerdStatus | sord_erase (SordModel *model, SordIter *iter)

## Inserter
SORD_API SordInserter * | sord_inserter_new (SordModel *model, SerdEnv *env)
SORD_API void | sord_inserter_free (SordInserter *inserter)
SORD_API SerdStatus | sord_inserter_set_base_uri (SordInserter *inserter, const SerdNode *uri)
SORD_API SerdStatus | sord_inserter_set_prefix (SordInserter *inserter, const SerdNode *name, const SerdNode *uri)
SORD_API SerdStatus | sord_inserter_write_statement (SordInserter *inserter, SerdStatementFlags flags, const SerdNode *graph, const SerdNode *subject, const SerdNode *predicate, const SerdNode *object, const SerdNode *object_datatype, const SerdNode *object_lang)

## Iteration
SORD_API void | sord_iter_get (const SordIter *iter, SordQuad tup)
SORD_API const SordNode * | sord_iter_get_node (const SordIter *iter, SordQuadIndex index)
SORD_API const SordModel * | sord_iter_get_model (SordIter *iter)
SORD_API bool | sord_iter_next (SordIter *iter)
SORD_API bool | sord_iter_end (const SordIter *iter)
SORD_API void | sord_iter_free (SordIter *iter)

## Utilities
SORD_API bool | sord_quad_match (const SordQuad x, const SordQuad y)

## Serialisation
SORD_API SerdReader * | sord_new_reader (SordModel *model, SerdEnv *env, SerdSyntax syntax, SordNode *graph)
SORD_API bool | sord_write (SordModel *model, SerdWriter *writer, SordNode *graph)
SORD_API bool | sord_write_iter (SordIter *iter, SerdWriter *writer)

## Typedef Documentation

## ◆ SordWorld

typedef struct SordWorldImpl SordWorld

Sord World.

The World represents all library state, including interned strings.

## ◆ SordModel

typedef struct SordModelImpl SordModel

Sord Model.

A model is an indexed set of Quads (i.e. it can contain several RDF graphs). It may be searched using various patterns depending on which indices are enabled.

## ◆ SordInserter

typedef struct SordInserterImpl SordInserter

Model Inserter.

An inserter is used for writing statements to a model using the Serd sink interface. This makes it simple to write to a model directly using a SerdReader, or any other code that writes statements to a SerdStatementSink.

## ◆ SordIter

typedef struct SordIterImpl SordIter

Model Iterator.

## ◆ SordNode

typedef struct SordNodeImpl SordNode

RDF Node.

A Node is a component of a Quad. Nodes may be URIs, blank nodes, or (in the case of quad objects only) string literals. Literal nodes may have an associate language or datatype (but not both).

## ◆ SordQuad

typedef const SordNode* SordQuad[4]

Quad of nodes (a statement), or a quad pattern.

Nodes are ordered (S P O G). The ID of the default graph is 0.

## Enumeration Type Documentation

## ◆ SordQuadIndex

enum SordQuadIndex

Index into a SordQuad.

Enumerator
SORD_SUBJECT | Subject.
SORD_PREDICATE | Predicate ("key")
SORD_OBJECT | Object ("value")
SORD_GRAPH | Graph ("context")

## ◆ SordNodeType

enum SordNodeType

Type of a node.

Enumerator
SORD_URI | URI.
SORD_BLANK | Blank node identifier.
SORD_LITERAL | Literal (string with optional lang or datatype)

## ◆ SordIndexOption

enum SordIndexOption

Indexing option.

Enumerator
SORD_SPO | Subject, Predicate, Object.
SORD_SOP | Subject, Object, Predicate.
SORD_OPS | Object, Predicate, Subject.
SORD_OSP | Object, Subject, Predicate.
SORD_PSO | Predicate, Subject, Object.
SORD_POS | Predicate, Object, Subject.

## Function Documentation

## ◆ sord_world_new()

SORD_API SordWorld * sord_world_new | ( | void |  | ) |

Create a new Sord World.

It is safe to use multiple worlds in one process, though no data (e.g. nodes) can be shared between worlds, and this should be avoided if possible for performance reasons.

## ◆ sord_world_free()

SORD_API void sord_world_free | ( | SordWorld * | world | ) |

Free `world`.

## ◆ sord_world_set_error_sink()

SORD_API void sord_world_set_error_sink | ( | SordWorld * | world,
|  | SerdErrorSink | error_sink,
|  | void * | handle
| ) |  |

Set a function to be called when errors occur.

The `error_sink` will be called with `handle` as its first argument. If no error function is set, errors are printed to stderr.

## ◆ sord_new_uri()

SORD_API SordNode * sord_new_uri | ( | SordWorld * | world,
|  | const uint8_t * | uri
| ) |  |

Get a URI node from a string.

Note this function measures `str`, which is a common bottleneck. Use sord_node_from_serd_node() instead if `str` is already measured.

## ◆ sord_new_relative_uri()

SORD_API SordNode * sord_new_relative_uri | ( | SordWorld * | world,
|  | const uint8_t * | uri,
|  | const uint8_t * | base_uri
| ) |  |

Get a URI node from a relative URI string.

## ◆ sord_new_blank()

SORD_API SordNode * sord_new_blank | ( | SordWorld * | world,
|  | const uint8_t * | str
| ) |  |

Get a blank node from a string.

Note this function measures `str`, which is a common bottleneck. Use sord_node_from_serd_node() instead if `str` is already measured.

## ◆ sord_new_literal()

SORD_API SordNode * sord_new_literal | ( | SordWorld * | world,
|  | SordNode * | datatype,
|  | const uint8_t * | str,
|  | const char * | lang
| ) |  |

Get a literal node from a string.

Note this function measures `str`, which is a common bottleneck. Use sord_node_from_serd_node() instead if `str` is already measured.

## ◆ sord_node_copy()

SORD_API SordNode * sord_node_copy | ( | const SordNode * | node | ) |

Copy a node (obtain a reference).

Node that since nodes are interned and reference counted, this does not actually create a deep copy of `node`.

## ◆ sord_node_free()

SORD_API void sord_node_free | ( | SordWorld * | world,
|  | SordNode * | node
| ) |  |

Free a node (drop a reference).

## ◆ sord_node_get_type()

SORD_API SordNodeType sord_node_get_type | ( | const SordNode * | node | ) |

Return the type of a node (SORD_URI, SORD_BLANK, or SORD_LITERAL).

## ◆ sord_node_get_string()

SORD_API const uint8_t * sord_node_get_string | ( | const SordNode * | node | ) |

Return the string value of a node.

## ◆ sord_node_get_string_counted()

SORD_API const uint8_t * sord_node_get_string_counted | ( | const SordNode * | node,
|  | size_t * | bytes
| ) |  |

Return the string value of a node, and set `bytes` to its length in bytes.

## ◆ sord_node_get_string_measured()

SORD_API const uint8_t * sord_node_get_string_measured | ( | const SordNode * | node,
|  | size_t * | bytes,
|  | size_t * | chars
| ) |  |

Return the string value of a node, and set `bytes` to its length in bytes, and `count` to its length in characters.

## ◆ sord_node_get_language()

SORD_API const char * sord_node_get_language | ( | const SordNode * | node | ) |

Return the language of a literal node (or NULL).

## ◆ sord_node_get_datatype()

SORD_API SordNode * sord_node_get_datatype | ( | const SordNode * | node | ) |

Return the datatype URI of a literal node (or NULL).

## ◆ sord_node_get_flags()

SORD_API SerdNodeFlags sord_node_get_flags | ( | const SordNode * | node | ) |

Return the flags (string attributes) of a node.

## ◆ sord_node_is_inline_object()

SORD_API bool sord_node_is_inline_object | ( | const SordNode * | node | ) |

Return true iff node can be serialised as an inline object.

More specifically, this returns true iff the node is the object field of exactly one statement, and therefore can be inlined since it needn't be referred to by name.

## ◆ sord_node_equals()

SORD_API bool sord_node_equals | ( | const SordNode * | a,
|  | const SordNode * | b
| ) |  |

Return true iff `a` is equal to `b`.

Note this is much faster than comparing the node's strings.

## ◆ sord_node_to_serd_node()

SORD_API const SerdNode * sord_node_to_serd_node | ( | const SordNode * | node | ) |

Return a SordNode as a SerdNode.

The returned node is shared and must not be freed or modified.

## ◆ sord_node_from_serd_node()

SORD_API SordNode * sord_node_from_serd_node | ( | SordWorld * | world,
|  | SerdEnv * | env,
|  | const SerdNode * | node,
|  | const SerdNode * | datatype,
|  | const SerdNode * | lang
| ) |  |

Create a new SordNode from a SerdNode.

The returned node must be freed using sord_node_free().

## ◆ sord_new()

SORD_API SordModel * sord_new | ( | SordWorld * | world,
|  | unsigned | indices,
|  | bool | graphs
| ) |  |

Create a new model.

Parameters

  world | The world in which to make this model.
  indices | SordIndexOption flags (e.g. SORD_SPO|SORD_OPS). Be sure to enable an index where the most significant node(s) are not variables in your queries (e.g. to make (? P O) queries, enable either SORD_OPS or SORD_POS).
  graphs | If true, store (and index) graph contexts.

## ◆ sord_free()

SORD_API void sord_free | ( | SordModel * | model | ) |

Close and free `model`.

## ◆ sord_get_world()

SORD_API SordWorld * sord_get_world | ( | SordModel * | model | ) |

Get the world associated with `model`.

## ◆ sord_num_nodes()

SORD_API size_t sord_num_nodes | ( | const SordWorld * | world | ) |

Return the number of nodes stored in `world`.

Nodes are included in this count iff they are a part of a quad in `world`.

## ◆ sord_num_quads()

SORD_API size_t sord_num_quads | ( | const SordModel * | model | ) |

Return the number of quads stored in `model`.

## ◆ sord_begin()

SORD_API SordIter * sord_begin | ( | const SordModel * | model | ) |

Return an iterator to the start of `model`.

## ◆ sord_find()

SORD_API SordIter * sord_find | ( | SordModel * | model,
|  | const SordQuad | pat
| ) |  |

Search for statements by a quad pattern.

Returns
  an iterator to the first match, or NULL if no matches found.

## ◆ sord_search()

SORD_API SordIter * sord_search | ( | SordModel * | model,
|  | const SordNode * | s,
|  | const SordNode * | p,
|  | const SordNode * | o,
|  | const SordNode * | g
| ) |  |

Search for statements by nodes.

Returns
  an iterator to the first match, or NULL if no matches found.

## ◆ sord_get()

SORD_API SordNode * sord_get | ( | SordModel * | model,
|  | const SordNode * | s,
|  | const SordNode * | p,
|  | const SordNode * | o,
|  | const SordNode * | 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. The returned node must be freed using sord_node_free().

Returns
  the first matching node, or NULL if no matches are found.

## ◆ sord_ask()

SORD_API bool sord_ask | ( | SordModel * | model,
|  | const SordNode * | s,
|  | const SordNode * | p,
|  | const SordNode * | o,
|  | const SordNode * | g
| ) |  |

Return true iff a statement exists.

## ◆ sord_count()

SORD_API uint64_t sord_count | ( | SordModel * | model,
|  | const SordNode * | s,
|  | const SordNode * | p,
|  | const SordNode * | o,
|  | const SordNode * | g
| ) |  |

Return the number of matching statements.

## ◆ sord_contains()

SORD_API bool sord_contains | ( | SordModel * | model,
|  | const SordQuad | pat
| ) |  |

Check if `model` contains a triple pattern.

Returns
  true if `model` contains a match for `pat`, otherwise false.

## ◆ sord_add()

SORD_API bool sord_add | ( | SordModel * | model,
|  | const SordQuad | tup
| ) |  |

Add a quad to a model.

Calling this function invalidates all iterators on `model`.

Returns
  true on success, false, on error.

## ◆ sord_remove()

SORD_API void sord_remove | ( | SordModel * | model,
|  | const SordQuad | tup
| ) |  |

Remove a quad from a model.

Calling this function invalidates all iterators on `model`. To remove quads while iterating, use sord_erase() instead.

## ◆ sord_erase()

SORD_API SerdStatus sord_erase | ( | SordModel * | model,
|  | SordIter * | iter
| ) |  |

Remove a quad from a model via an iterator.

Calling this function invalidates all iterators on `model` except `iter`.

Parameters

  model | The model which `iter` points to.
  iter | Iterator to the element to erase, which is incremented to the next value on return.

## ◆ sord_inserter_new()

SORD_API SordInserter * sord_inserter_new | ( | SordModel * | model,
|  | SerdEnv * | env
| ) |  |

Create an inserter for writing statements to a model.

## ◆ sord_inserter_free()

SORD_API void sord_inserter_free | ( | SordInserter * | inserter | ) |

Free an inserter.

## ◆ sord_inserter_set_base_uri()

SORD_API SerdStatus sord_inserter_set_base_uri | ( | SordInserter * | inserter,
|  | const SerdNode * | uri
| ) |  |

Set the current base URI for writing to the model.

Note this function can be safely casted to SerdBaseSink.

## ◆ sord_inserter_set_prefix()

SORD_API SerdStatus sord_inserter_set_prefix | ( | SordInserter * | inserter,
|  | const SerdNode * | name,
|  | const SerdNode * | uri
| ) |  |

Set a namespace prefix for writing to the model.

Note this function can be safely casted to SerdPrefixSink.

## ◆ sord_inserter_write_statement()

SORD_API SerdStatus sord_inserter_write_statement | ( | SordInserter * | inserter,
|  | SerdStatementFlags | flags,
|  | const SerdNode * | graph,
|  | const SerdNode * | subject,
|  | const SerdNode * | predicate,
|  | const SerdNode * | object,
|  | const SerdNode * | object_datatype,
|  | const SerdNode * | object_lang
| ) |  |

Write a statement to the model.

Note this function can be safely casted to SerdStatementSink.

## ◆ sord_iter_get()

SORD_API void sord_iter_get | ( | const SordIter * | iter,
|  | SordQuad | tup
| ) |  |

Set `quad` to the quad pointed to by `iter`.

## ◆ sord_iter_get_node()

SORD_API const SordNode * sord_iter_get_node | ( | const SordIter * | iter,
|  | SordQuadIndex | index
| ) |  |

Return a field of the quad pointed to by `iter`.

Returns NULL if `iter` is NULL or is at the end.

## ◆ sord_iter_get_model()

SORD_API const SordModel * sord_iter_get_model | ( | SordIter * | iter | ) |

Return the store pointed to by `iter`.

## ◆ sord_iter_next()

SORD_API bool sord_iter_next | ( | SordIter * | iter | ) |

Increment `iter` to point to the next statement.

## ◆ sord_iter_end()

SORD_API bool sord_iter_end | ( | const SordIter * | iter | ) |

Return true iff `iter` is at the end of its range.

## ◆ sord_iter_free()

SORD_API void sord_iter_free | ( | SordIter * | iter | ) |

Free `iter`.

## ◆ sord_quad_match()

SORD_API bool sord_quad_match | ( | const SordQuad | x,
|  | const SordQuad | y
| ) |  |

Match two quads (using ID comparison only).

This function is a straightforward and fast equivalence match with wildcard support (ID 0 is a wildcard). It does not actually read node data.

Returns
  true iff `x` and `y` match.

## ◆ sord_new_reader()

SORD_API SerdReader * sord_new_reader | ( | SordModel * | model,
|  | SerdEnv * | env,
|  | SerdSyntax | syntax,
|  | SordNode * | graph
| ) |  |

Return a reader that will read into `model`.

## ◆ sord_write()

SORD_API bool sord_write | ( | SordModel * | model,
|  | SerdWriter * | writer,
|  | SordNode * | graph
| ) |  |

Write a model to a writer.

## ◆ sord_write_iter()

SORD_API bool sord_write_iter | ( | SordIter * | iter,
|  | SerdWriter * | writer
| ) |  |

Write a range to a writer.

This increments `iter` to its end, then frees it.