4.4 Statements

A SerdStatement is a tuple of either 3 or 4 nodes: the subject, predicate, object, and optional graph. Statements declare that a subject has some property. The predicate identifies the property, and the object is its value.

A statement can be thought of as a very simple machine-readable sentence. The subject and object are as in natural language, and the predicate is something like a verb, but more general. For example, we could make a statement in English about your intrepid author:

drobilla has the first name “David”

We can break this statement into 3 pieces like so:

Subject	Predicate	Object
drobilla	has the first name	“David”

To make a SerdStatement out of this, we need to define some URIs. In RDF, the subject and predicate must be resources with an identifier (for example, neither can be a string). Conventionally, predicate names do not start with “has” or similar words, since that would be redundant in this context. So, we assume that http://example.org/drobilla is the URI for drobilla, and that http://example.org/firstName has been defined somewhere to be a property with the appropriate meaning, and can make an equivalent SerdStatement:

SerdStatement* statement = serd_statement_new(
  NULL,
  serd_nodes_uri(nodes, SERD_STRING("http://example.org/drobilla")),
  serd_nodes_uri(nodes, SERD_STRING("http://example.org/firstName")),
  serd_nodes_string(nodes, SERD_STRING("David")),
  NULL,
  NULL);

The last two fields are the graph and the cursor. The graph is another node that can be used to group statements, for example by the URI of the document they were loaded from. The cursor represents the location in a document where the statement was loaded from, if applicable.

4.4.1 Accessing Fields

Statement fields can be accessed with serd_statement_node(), for example:

const SerdNode* s = serd_statement_node(statement, SERD_SUBJECT);

Alternatively, an accessor function is provided for each field:

const SerdNode* p = serd_statement_predicate(statement);
const SerdNode* o = serd_statement_object(statement);
const SerdNode* g = serd_statement_graph(statement);

Every statement has a subject, predicate, and object, but the graph may be null. The cursor may also be null (as it would be in this case), but if available it can be accessed with serd_statement_caret():

const SerdCaret* c = serd_statement_caret(statement);

4.4.2 Comparison

Two statements can be compared with serd_statement_equals():

if (serd_statement_equals(statement1, statement2)) {
  printf("Match\n");
}

Statements are equal if all four corresponding pairs of nodes are equal. The cursor is considered metadata, and is ignored for comparison.

It is also possible to match statements against a pattern using NULL as a wildcard, with serd_statement_matches():

SerdNode* eg_name =
  serd_new_uri(NULL, SERD_STRING("http://example.org/name"));

if (serd_statement_matches(statement, NULL, eg_name, NULL, NULL)) {
  printf("%s has name %s\n",
         serd_node_string(serd_statement_subject(statement)),
         serd_node_string(serd_statement_object(statement)));
}

4.4.3 Lifetime

A statement only contains const references to nodes, it does not own nodes or manage their lifetimes internally. The cursor, however, is owned by the statement. A statement can be copied with serd_statement_copy():

SerdStatement* copy = serd_statement_copy(NULL, statement);

The copied statement will refer to exactly the same nodes, though the cursor will be deep copied.

In most cases, statements come from a reader or model which manages them internally, but a statement owned by the application must be freed with serd_statement_free():

serd_statement_free(NULL, copy);