diff options
Diffstat (limited to 'include/serd/serd.h')
| -rw-r--r-- | include/serd/serd.h | 387 |
1 files changed, 322 insertions, 65 deletions
diff --git a/include/serd/serd.h b/include/serd/serd.h index 2bda9829..fe610fc5 100644 --- a/include/serd/serd.h +++ b/include/serd/serd.h @@ -600,81 +600,337 @@ typedef enum { } SerdNodeType; /** - Create a new "token" node that is just a string. + @defgroup serd_node_construction 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(). + + @{ +*/ + +/** + 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, + SERD_HAS_DATATYPE or SERD_HAS_LANGUAGE (but not both) may only be given if + `type` is `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. + + @param buf_size The size of `buf` in bytes, or zero to only measure. + + @param buf Buffer where the node will be written, or null to only measure. + + @param type The type of the node to construct. + + @param string The string body of the node. + + @param flags Flags that describe the details of the node. + + @param meta The string value of the literal's metadata. If + #SERD_HAS_DATATYPE is set, then this must be an absolute datatype URI. If + #SERD_HAS_LANGUAGE is set, then this must be a language tag like "en-ca". + Otherwise, it is ignored. + + @return A result with a `status` and a `count` of bytes written. If the + buffer is too small for the node, then `status` will be #SERD_ERR_OVERFLOW, + and `count` will be set to the number of bytes required to successfully + construct the node. +*/ +SERD_API +SerdWriteResult +serd_node_construct(size_t buf_size, + void* SERD_NULLABLE buf, + SerdNodeType type, + SerdStringView string, + SerdNodeFlags flags, + SerdStringView meta); + +/** + 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. This can be used to create URIs, blank nodes, - variables, and simple string literals. + 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_new_literal() with - #SERD_IS_LONG. + construct long literals, use the more advanced serd_construct_literal() with + the #SERD_IS_LONG flag. + + See the serd_node_construct() documentation for details on buffer usage and + the return value. */ SERD_API -SerdNode* SERD_ALLOCATED -serd_new_token(SerdNodeType type, SerdStringView string); +SerdWriteResult +serd_node_construct_token(size_t buf_size, + void* SERD_NULLABLE buf, + SerdNodeType type, + SerdStringView string); + +/** + 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_uri(size_t buf_size, + void* SERD_NULLABLE buf, + SerdURIView uri); + +/** + Construct a file URI node from a path and optional hostname. -/// Create a new plain literal string node from `str` + 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_file_uri(size_t buf_size, + void* SERD_NULLABLE buf, + SerdStringView path, + SerdStringView hostname); + +/** + 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. +*/ SERD_API -SerdNode* SERD_ALLOCATED -serd_new_string(SerdStringView string); +SerdWriteResult +serd_node_construct_literal(size_t buf_size, + void* SERD_NULLABLE buf, + SerdStringView string, + SerdNodeFlags flags, + SerdStringView meta); /** - Create a new literal node with optional datatype or language. + Construct a canonical xsd:boolean literal. - This can create more complex literals than serd_new_string() with an - associated datatype URI or language tag, as well as control whether a - literal should be written as a short or long (triple-quoted) string. + The constructed node will be either "true" or "false", with datatype + xsd:boolean. - @param string The string value of the literal. + This is a convenience wrapper for serd_node_construct_literal() that + constructs a node directly from a `bool`. +*/ +SerdWriteResult +serd_node_construct_boolean(size_t buf_size, + void* SERD_NULLABLE buf, + bool value); - @param flags Flags to describe the literal and its metadata. This must be a - valid combination of flags, in particular, at most one of #SERD_HAS_DATATYPE - and #SERD_HAS_LANGUAGE may be set. +/** + Construct a canonical xsd:decimal literal. - @param meta The string value of the literal's metadata. If - #SERD_HAS_DATATYPE is set, then this must be an absolute datatype URI. If - #SERD_HAS_LANGUAGE is set, then this must be a language tag like "en-ca". - Otherwise, it is ignored. + The constructed node will be an xsd:decimal literal, like "12.34", with + datatype xsd:decimal. - @return A newly allocated literal node that must be freed with - serd_node_free(), or null if the arguments are invalid or allocation failed. + 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_decimal(size_t buf_size, + void* SERD_NULLABLE 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_double(size_t buf_size, + void* SERD_NULLABLE buf, + double 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_float(size_t buf_size, + void* SERD_NULLABLE buf, + float value); + +/** + 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_integer(size_t buf_size, + void* SERD_NULLABLE buf, + int64_t value, + SerdStringView datatype); + +/** + Construct a canonical xsd:base64Binary literal. + + The constructed node will be an xsd:base64Binary literal like "Zm9vYmFy", + with datatype xsd:base64Binary. +*/ +SerdWriteResult +serd_node_construct_base64(size_t buf_size, + void* SERD_NULLABLE buf, + size_t value_size, + const void* SERD_NONNULL value, + SerdStringView datatype); + +/** + @} + @defgroup serd_node_allocation Dynamic Allocation + + This is a convenient higher-level node construction API which allocates + nodes on the heap. The returned nodes must be freed with serd_node_free(). + + Note that in most cases it is better to use a #SerdNodes instead of managing + individual node allocations. + + @{ +*/ + +/** + Create a new node of any type. + + This is a wrapper for serd_node_construct() that allocates a new node on the + heap. + + @return A newly allocated node that must be freed with serd_node_free(), or + null. */ SERD_API SerdNode* SERD_ALLOCATED -serd_new_literal(SerdStringView string, - SerdNodeFlags flags, - SerdStringView meta); +serd_node_new(SerdNodeType type, + SerdStringView string, + SerdNodeFlags flags, + SerdStringView meta); + +/** + Create a new simple "token" node. + + This is a wrapper for serd_node_construct_token() that allocates a new node + on the heap. + + @return A newly allocated node that must be freed with serd_node_free(), or + null. +*/ +SERD_API +SerdNode* SERD_ALLOCATED +serd_new_token(SerdNodeType type, SerdStringView string); + +/** + Create a new string literal node. + + This is a trivial wrapper for serd_new_token() that passes `SERD_LITERAL` + for the type. -/// Create a new blank node + @return A newly allocated node that must be freed with serd_node_free(), or + null. +*/ SERD_API SerdNode* SERD_ALLOCATED -serd_new_blank(SerdStringView string); +serd_new_string(SerdStringView string); -/// Create a new URI node +/** + Create a new URI node from a string. + + This is a wrapper for serd_node_construct_uri() that allocates a new + node on the heap. + + @return A newly allocated node that must be freed with serd_node_free(), or + null. +*/ SERD_API SerdNode* SERD_ALLOCATED serd_new_uri(SerdStringView string); -/// Create a new URI from a URI view +/** + Create a new URI node from a parsed URI. + + This is a wrapper for serd_node_construct_uri() that allocates a new + node on the heap. + + @return A newly allocated node that must be freed with serd_node_free(), or + null. +*/ SERD_API SerdNode* SERD_ALLOCATED serd_new_parsed_uri(SerdURIView uri); /** - Create a new file URI node from a file system path and optional hostname. + Create a new file URI node from a path and optional hostname. - Backslashes in Windows paths will be converted, and other characters will be - percent encoded as necessary. + This is a wrapper for serd_node_construct_file_uri() that allocates a new + node on the heap. - If `path` is relative, `hostname` is ignored. + @return A newly allocated node that must be freed with serd_node_free(), or + null. */ SERD_API SerdNode* SERD_ALLOCATED serd_new_file_uri(SerdStringView path, SerdStringView hostname); -/// Create a new node by serialising `b` into an xsd:boolean string +/** + Create a new literal node. + + This is a wrapper for serd_node_construct_literal() that allocates a new + node on the heap. + + @return A newly allocated node that must be freed with serd_node_free(), or + null. +*/ +SERD_API +SerdNode* SERD_ALLOCATED +serd_new_literal(SerdStringView string, + SerdNodeFlags flags, + SerdStringView meta); + +/** + Create a new canonical xsd:boolean node. + + This is a wrapper for serd_node_construct_boolean() that allocates a new + node on the heap. + + @return A newly allocated node that must be freed with serd_node_free(), or + null. +*/ SERD_API SerdNode* SERD_ALLOCATED serd_new_boolean(bool b); @@ -682,29 +938,24 @@ serd_new_boolean(bool b); /** Create a new canonical xsd:decimal literal. - The resulting 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 wrapper for serd_node_construct_decimal() that allocates a new + node on the heap. - @param d The value for the new node. - @param datatype Datatype of node, or NULL for xsd:decimal. + @return A newly allocated node that must be freed with serd_node_free(), or + null. */ SERD_API SerdNode* SERD_ALLOCATED -serd_new_decimal(double d, const SerdNode* SERD_NULLABLE datatype); +serd_new_decimal(double d); /** Create a new canonical xsd:double literal. - The returned node will always be in scientific notation, like "1.23E4", - except for NaN and negative/positive infinity, which are "NaN", "-INF", and - "INF", respectively. + This is a wrapper for serd_node_construct_double() that allocates a new + node on the heap. - Uses the shortest possible representation that precisely describes `d`, - which has at most 17 significant digits (under 24 characters total). - - @param d Double value to write. - @return A literal node with datatype xsd:double. + @return A newly allocated node that must be freed with serd_node_free(), or + null. */ SERD_API SerdNode* SERD_ALLOCATED @@ -713,11 +964,11 @@ serd_new_double(double d); /** Create a new canonical xsd:float literal. - Uses identical formatting to serd_new_double(), except with at most 9 - significant digits (under 14 characters total). + This is a wrapper for serd_node_construct_float() that allocates a new + node on the heap. - @param f Float value of literal. - @return A literal node with datatype xsd:float. + @return A newly allocated node that must be freed with serd_node_free(), or + null. */ SERD_API SerdNode* SERD_ALLOCATED @@ -726,28 +977,34 @@ serd_new_float(float f); /** Create a new canonical xsd:integer literal. - @param i Integer value of literal. - @param datatype Datatype of node, or NULL for xsd:integer. + This is a wrapper for serd_node_construct_integer() that allocates a new + node on the heap. + + @return A newly allocated node that must be freed with serd_node_free(), or + null. */ SERD_API SerdNode* SERD_ALLOCATED -serd_new_integer(int64_t i, const SerdNode* SERD_NULLABLE datatype); +serd_new_integer(int64_t i, SerdStringView datatype); /** Create a new canonical xsd:base64Binary literal. - This function can be used to make a node out of arbitrary binary data, which - can be decoded using serd_base64_decode(). + This is a wrapper for serd_node_construct_base64() that allocates a new + node on the heap. - @param buf Raw binary data to encode in node. - @param size Size of `buf` in bytes. - @param datatype Datatype of node, or null for xsd:base64Binary. + @return A newly allocated node that must be freed with serd_node_free(), or + null. */ SERD_API SerdNode* SERD_ALLOCATED -serd_new_base64(const void* SERD_NONNULL buf, - size_t size, - const SerdNode* SERD_NULLABLE datatype); +serd_new_base64(const void* SERD_NONNULL buf, + size_t size, + SerdStringView datatype); + +/** + @} +*/ /** Return the value of `node` as a boolean. |