diff options
Diffstat (limited to 'doc/c/nodes.rst')
-rw-r--r-- | doc/c/nodes.rst | 66 |
1 files changed, 66 insertions, 0 deletions
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 <SerdNodeType>`, +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. |