From f8a59da9c492b7df38f53ba96505313e931d76cc Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 28 Mar 2021 13:42:35 -0400 Subject: Add high-level documentation --- doc/c/nodes.rst | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 doc/c/nodes.rst (limited to 'doc/c/nodes.rst') diff --git a/doc/c/nodes.rst b/doc/c/nodes.rst new file mode 100644 index 00000000..c55dcedb --- /dev/null +++ b/doc/c/nodes.rst @@ -0,0 +1,66 @@ +Nodes +===== + +.. default-domain:: c +.. highlight:: c + +Nodes are the basic building blocks of data. +Nodes are essentially strings, +but also have a :enum:`type `, +and optionally either a datatype or a language. + +In the abstract, a node is either a literal, a URI, or blank. +Literals are essentially strings, +but may have a datatype or a language tag. +URIs are used to identify resources, +as are blank nodes, +except blank nodes only have labels with a limited scope and may be written anonymously. + +Serd also has a type for variable nodes, +which are used for some features but not present in RDF data. + +Fundamental Constructors +------------------------ + +To allow the application to manage node memory, +node constructors are provided that construct nodes in existing memory buffers. +The universal constructor :func:`serd_node_construct` can construct any type of node, +but is somewhat verbose and tricky to use. + +Several constructors for more specific types of node are also available: + +- :func:`serd_node_construct_token` +- :func:`serd_node_construct_uri` +- :func:`serd_node_construct_file_uri` +- :func:`serd_node_construct_literal` +- :func:`serd_node_construct_value` +- :func:`serd_node_construct_decimal` +- :func:`serd_node_construct_integer` +- :func:`serd_node_construct_base64` + +If explicit memory management is not required, +high-level constructors that allocate nodes on the heap can be used instead: + +- :func:`serd_new_token` +- :func:`serd_new_uri` +- :func:`serd_new_file_uri` +- :func:`serd_new_literal` +- :func:`serd_new_value` +- :func:`serd_new_decimal` +- :func:`serd_new_integer` +- :func:`serd_new_base64` + +Accessors +--------- + +The basic attributes of a node can be accessed with :func:`serd_node_type`, +:func:`serd_node_string`, +and :func:`serd_node_length`. + +A measured view of the string can be accessed with :func:`serd_node_string_view`. +This can be passed to functions that take a string view, +to avoid redundant measurement of the node string. + +The datatype or language can be retrieved with :func:`serd_node_datatype` or :func:`serd_node_language`, respectively. +Note that only literals can have a datatype or language, +but never both at once. -- cgit v1.2.1