Add SerdNodes for storing a cache of interned nodes

1 files changed, 139 insertions, 0 deletions

diff --git a/include/serd/serd.h b/include/serd/serd.h
index 49cfcee4..bf346a99 100644
--- a/include/serd/serd.h
+++ b/include/serd/serd.h
@@ -827,6 +827,145 @@ serd_node_equals(const SerdNode* SERD_NULLABLE a,
 
 /**
    @}
+   @defgroup serd_nodes Nodes
+   @{
+*/
+
+/// Hashing node container for interning and simplified memory management
+typedef struct SerdNodesImpl SerdNodes;
+
+/// Create a new node set
+SERD_API
+SerdNodes* SERD_ALLOCATED
+serd_nodes_new(void);
+
+/**
+   Free `nodes` and all nodes that are stored in it.
+
+   Note that this invalidates any node pointers previously returned from
+   `nodes`.
+*/
+SERD_API
+void
+serd_nodes_free(SerdNodes* SERD_NULLABLE nodes);
+
+/// Return the number of interned nodes
+SERD_PURE_API
+size_t
+serd_nodes_size(const SerdNodes* SERD_NONNULL nodes);
+
+/**
+   Return the existing interned copy of a node if it exists.
+
+   This either returns an equivalent to the given node, or null if this node
+   has not been interned.
+*/
+SERD_API
+const SerdNode* SERD_NULLABLE
+serd_nodes_get(const SerdNodes* SERD_NONNULL nodes,
+               const SerdNode* SERD_NULLABLE node);
+
+/**
+   Intern `node`.
+
+   Multiple calls with equivalent nodes will return the same pointer.
+
+   @return A node that is different than, but equivalent to, `node`.
+*/
+SERD_API
+const SerdNode* SERD_ALLOCATED
+serd_nodes_intern(SerdNodes* SERD_NONNULL       nodes,
+                  const SerdNode* SERD_NULLABLE node);
+
+/**
+   Manage `node`.
+
+   Like `serd_nodes_intern`, but takes ownership of `node`, freeing it and
+   returning a previously interned/managed equivalent node if necessary.
+
+   @return A node that is equivalent to `node`.
+*/
+SERD_API
+const SerdNode* SERD_ALLOCATED
+serd_nodes_manage(SerdNodes* SERD_NONNULL nodes, SerdNode* SERD_NULLABLE node);
+
+/**
+   Make a string node.
+
+   A new node will be added if an equivalent node is not already in the set.
+*/
+SERD_API
+const SerdNode* SERD_ALLOCATED
+serd_nodes_string(SerdNodes* SERD_NONNULL nodes, SerdStringView string);
+
+/**
+   Return a plain literal node with an optional language.
+
+   If the language is empty, then this is equivalent to serd_nodes_string().
+
+   A new node will be added if an equivalent node is not already in the set.
+*/
+SERD_API
+const SerdNode* SERD_ALLOCATED
+serd_nodes_plain_literal(SerdNodes* SERD_NONNULL nodes,
+                         SerdStringView          string,
+                         SerdStringView          language);
+
+/**
+   Return a typed literal node with an datatype URI.
+
+   If the datatype URI is empty, then this is equivalent to
+   serd_nodes_string().
+
+   A new node will be added if an equivalent node is not already in the set.
+*/
+SERD_API
+const SerdNode* SERD_ALLOCATED
+serd_nodes_typed_literal(SerdNodes* SERD_NONNULL nodes,
+                         SerdStringView          string,
+                         SerdStringView          datatype_uri);
+
+/**
+   Make a URI node.
+
+   A new node will be added if an equivalent node is not already in the set.
+*/
+SERD_API
+const SerdNode* SERD_ALLOCATED
+serd_nodes_uri(SerdNodes* SERD_NONNULL nodes, SerdStringView string);
+
+/**
+   Make a CURIE node.
+
+   A new node will be added if an equivalent node is not already in the set.
+*/
+SERD_API
+const SerdNode* SERD_ALLOCATED
+serd_nodes_curie(SerdNodes* SERD_NONNULL nodes, SerdStringView string);
+
+/**
+   Make a blank node.
+
+   A new node will be added if an equivalent node is not already in the set.
+*/
+SERD_API
+const SerdNode* SERD_ALLOCATED
+serd_nodes_blank(SerdNodes* SERD_NONNULL nodes, SerdStringView string);
+
+/**
+   Dereference `node`.
+
+   Decrements the reference count of `node`, and frees the internally stored
+   equivalent node if this was the last reference.  Does nothing if no node
+   equivalent to `node` is stored in `nodes`.
+*/
+SERD_API
+void
+serd_nodes_deref(SerdNodes* SERD_NONNULL      nodes,
+                 const SerdNode* SERD_NONNULL node);
+
+/**
+   @}
    @defgroup serd_caret Caret
    @{
 */