5.8.2.1 Construction

This is the low-level node construction API, which can be used to construct nodes into existing buffers.

Advanced applications can use this to specially manage node memory, for example by allocating nodes on the stack, or with a special allocator.

Note that nodes are “plain old data”, so there is no need to destroy a constructed node, and nodes may be trivially copied, for example with memcpy().

SerdWriteResult serd_node_construct(size_t buf_size, void *buf, SerdNodeType type, SerdStringView string, SerdNodeFlags flags, SerdStringView meta)

Construct a node into an existing buffer.

This is the universal node constructor which can construct any node. An error will be returned if the parameters do not make sense. In particular, SerdNodeFlag.SERD_HAS_DATATYPE or SerdNodeFlag.SERD_HAS_LANGUAGE (but not both) may only be given if type is SerdNodeType.SERD_LITERAL, and meta must be syntactically valid based on that flag.

This function may also be used to determine the size of buffer required by passing a null buffer with zero size.

Parameters

  • buf_size – The size of buf in bytes, or zero to only measure.

  • buf – Buffer where the node will be written, or null to only measure.

  • type – The type of the node to construct.

  • string – The string body of the node.

  • flags – Flags that describe the details of the node.

  • meta – The string value of the literal’s metadata. If SerdNodeFlag.SERD_HAS_DATATYPE is set, then this must be an absolute datatype URI. If SerdNodeFlag.SERD_HAS_LANGUAGE is set, then this must be a language tag like “en-ca”. Otherwise, it is ignored.

Returns

A result with a status and a count of bytes written. If the buffer is too small for the node, then status will be SerdStatus.SERD_OVERFLOW, and count will be set to the number of bytes required to successfully construct the node.

SerdWriteResult serd_node_construct_token(size_t buf_size, void *buf, SerdNodeType type, SerdStringView string)

Construct a simple “token” node.

“Token” is just a shorthand used in this API to refer to a node that is not a typed or tagged literal, that is, a node that is just one string. This can be used to create URIs, blank nodes, variables, and simple string literals.

Note that string literals constructed with this function will have no flags set, and so will be written as “short” literals (not triple-quoted). To construct long literals, use the more advanced serd_construct_literal() with the SerdNodeFlag.SERD_IS_LONG flag.

See the serd_node_construct() documentation for details on buffer usage and the return value.

SerdWriteResult serd_node_construct_uri(size_t buf_size, void *buf, SerdURIView uri)

Construct a URI node from a parsed URI.

This is similar to serd_node_construct_token(), but will serialise a parsed URI into the new node. This can be used to resolve a relative URI reference or expand a CURIE directly into a node without needing to allocate the URI string separately.

SerdWriteResult serd_node_construct_file_uri(size_t buf_size, void *buf, SerdStringView path, SerdStringView hostname)

Construct a file URI node from a path and optional hostname.

This is similar to serd_node_construct_token(), but will create a new file URI from a file path and optional hostname, performing any necessary escaping.

SerdWriteResult serd_node_construct_literal(size_t buf_size, void *buf, SerdStringView string, SerdNodeFlags flags, SerdStringView meta)

Construct a literal node with an optional datatype or language.

Either a datatype (which must be an absolute URI) or a language (which must be an RFC5646 language tag) may be given, but not both.

This is the most general literal constructor, which can be used to construct any literal node. This works like serd_node_construct(), see its documentation for details.

SerdWriteResult serd_node_construct_boolean(size_t buf_size, void *buf, bool value)

Construct a canonical xsd:boolean literal.

The constructed node will be either “true” or “false”, with datatype xsd:boolean.

This is a convenience wrapper for serd_node_construct_literal() that constructs a node directly from a bool.

SerdWriteResult serd_node_construct_decimal(size_t buf_size, void *buf, double value)

Construct a canonical xsd:decimal literal.

The constructed node will be an xsd:decimal literal, like “12.34”, with datatype xsd:decimal.

The node will always contain a ‘.’, start with a digit, and end with a digit (a leading and/or trailing ‘0’ will be added if necessary), for example, “1.0”. It will never be in scientific notation.

This is a convenience wrapper for serd_node_construct_literal() that constructs a node directly from a double.

SerdWriteResult serd_node_construct_double(size_t buf_size, void *buf, double value)

Construct a canonical xsd:double literal.

The constructed node will be an xsd:double literal, like “1.23E45”, with datatype xsd:double. A canonical xsd:double is always in scientific notation.

This is a convenience wrapper for serd_node_construct_literal() that constructs a node directly from a double.

SerdWriteResult serd_node_construct_float(size_t buf_size, void *buf, float value)

Construct a canonical xsd:float literal.

The constructed node will be an xsd:float literal, like “1.23E45”, with datatype xsd:float. A canonical xsd:float is always in scientific notation.

Uses identical formatting to serd_node_construct_double(), except with at most 9 significant digits (under 14 characters total).

This is a convenience wrapper for serd_node_construct_literal() that constructs a node directly from a float.

SerdWriteResult serd_node_construct_integer(size_t buf_size, void *buf, int64_t value, SerdStringView datatype)

Construct a canonical xsd:integer literal.

The constructed node will be an xsd:integer literal like “1234”, with the given datatype, or datatype xsd:integer if none is given. It is the caller’s responsibility to ensure that the value is within the range of the given datatype.

SerdWriteResult serd_node_construct_base64(size_t buf_size, void *buf, size_t value_size, const void *value, SerdStringView datatype)

Construct a canonical xsd:base64 literal.

The constructed node will be an xsd:integer literal like “Zm9vYmFy”, with the given datatype, or datatype xsd:base64Binary if none is given.