volksdata/src/term.c

#include "tpl.h"

#include "volksdata/term.h"

/** @brief tpl packing format for a term.
 *
 * The pack elements are: 1. term type (char); 2. data (string); 3. void* type
 * metadata, cast to 8-byte unsigned.
 */
#define TERM_PACK_FMT "csU"

#define MAX_VALID_TERM_TYPE     VOLK_TERM_BNODE /* For type validation. */


/*
 * Data structures.
 */

/// Sub-match coordinates in IRI parsing results.
typedef struct match_coord_t {
    size_t              offset;     ///< Offset of match from start of string.
    size_t              size;       ///< Length of match.
} MatchCoord;


/// Matching sub-patterns for IRI parts.
struct iri_info_t {
    MatchCoord          prefix;     ///< URI prefix (scheme + authority).
    MatchCoord          path;       ///< URI path (including fragment).
    MatchCoord          frag;       ///< URI fragment.
};


/// Key-term pair in term set.
typedef struct keyed_term {
    VOLK_Key            key;        ///< Key (hash) of the term.
    VOLK_Term *         term;       ///< Term handle.
} KeyedTerm;


/** @brief Single link between a term and a term set.
 *
 * This link is not qualified and must not be used by itself. It belongs
 * in a #VOLK_LinkMap which qualifies all links of the same type.
 */
typedef struct link {
    KeyedTerm *         term;       ///< Linked term.
    VOLK_TermSet *      tset;       ///< Term set linked to the term.
} Link;


/// Opaque link map iterator.
struct link_map_iter {
    const VOLK_LinkMap *map;        ///< Link map to iterate.
    size_t              i;          ///< Linking term loop cursor.
    size_t              j;          ///< Term set loop cursor.
    const Link *        link;       ///< Current link being retrieved.
};


/*
 * A link map is thus nested:
 *
 * - A link map contains a hash map of Link instances (link).
 * - It also contains the single term that the other terms are related to
 *    (linked_t).
 * - Each Link contains a KeyedTerm (term) and a TermSet (tset).
 * - Each term set is a hash map of KeyedTerm instances.
 * - Each KeyedTerm contains a Term and its hash.
 */
typedef struct link_map {
    VOLK_LinkType       type;       ///< Link type.
    VOLK_Term          *linked_t;   ///< Linked term.
    struct hashmap     *links;      ///< Map of #Link instances.
} VOLK_LinkMap;


/*
 * External variables.
 */

uint32_t VOLK_default_dtype_key = 0;
VOLK_Term *VOLK_default_datatype = NULL;
VOLK_TermSet *VOLK_term_cache = NULL;


/*
 * Static variables.
 */

// Characters not allowed in a URI string.
static const char *invalid_uri_chars = "<>\" {}|\\^`";

/// Minimum valid type code.
static const VOLK_TermType MIN_VALID_TYPE = VOLK_TERM_IRIREF;
/// Maximum valid type code. Change this if adding to enum VOLK_TermType.
static const VOLK_TermType MAX_VALID_TYPE = VOLK_TERM_BNODE;

/*
 * Static prototypes.
 */

static VOLK_rc
term_init (
        VOLK_Term *term, VOLK_TermType type, const char *data, void *metadata);


/*
 * Term set callbacks.
 */

static uint64_t
tset_hash_fn (
        const void *item, uint64_t seed0, uint64_t seed1)
{ return ((const KeyedTerm *) item)->key; }


static int
tset_cmp_fn (const void *a, const void *b, void *udata)
{
    return 
            ((const KeyedTerm *) a)->key -
            ((const KeyedTerm *) b)->key;
}


static void
tset_free_fn (void *item)
{ VOLK_term_free (((KeyedTerm *) item)->term); }


/*
 * Link map callbacks.
 */

static uint64_t
link_map_hash_fn (
        const void *item, uint64_t seed0, uint64_t seed1)
{ return ((const Link *)item)->term->key; }


static int
link_map_cmp_fn (const void *a, const void *b, void *udata)
{
    return 
            ((const Link *)a)->term->key -
            ((const Link *)b)->term->key;
}


static void
link_map_free_fn (void *item)
{
    Link *link = item;
    VOLK_term_free (link->term->term);
    free (link->term);
    VOLK_term_set_free (link->tset);
}


static VOLK_rc parse_iri (char *iri, MatchCoord coords[]);


 /*
 * Term API.
 */

VOLK_Term *
VOLK_term_new (
        VOLK_TermType type, const char *data, void *metadata)
{
    VOLK_Term *term;
    CALLOC_GUARD (term, NULL);

    if (UNLIKELY (term_init (
                    term, type, data, metadata) != VOLK_OK)) {
        free (term);
        return NULL;
    }

    return term;
}


VOLK_Term *
VOLK_term_copy (const VOLK_Term *src)
{
    void *metadata = NULL;

    if (src->type == VOLK_TERM_LITERAL)
        metadata = (void *) src->datatype;
    else if (src->type == VOLK_TERM_LT_LITERAL)
        metadata = (void *) src->lang;

    return VOLK_term_new (src->type, src->data, metadata);
}


VOLK_Term *
VOLK_term_new_from_buffer (const VOLK_Buffer *sterm)
{
    if (UNLIKELY (!sterm)) return NULL;

    VOLK_Term *term = NULL;
    VOLK_TermType type = VOLK_TERM_UNDEFINED;
    char *data = NULL;
    void *metadata;

    tpl_node *tn;

    tn = tpl_map (TERM_PACK_FMT, &type, &data, &metadata);
    if (UNLIKELY (!tn)) goto finally;

    if (UNLIKELY (tpl_load (tn, TPL_MEM, sterm->addr, sterm->size) < 0)) {
        log_error ("Error loading serialized term.");
        goto finally;
    }
    if (UNLIKELY (tpl_unpack (tn, 0) < 0)) {
        log_error ("Error unpacking serialized term.");
        goto finally;
    }

    if (type == VOLK_TERM_LT_LITERAL)
        term = VOLK_lt_literal_new (data, (char *)&metadata);
    else term = VOLK_term_new (type, data, metadata);

finally:
    tpl_free (tn);
    free (data);

    return term;
}


VOLK_Term *
VOLK_iriref_new_abs (const VOLK_Term *root, const VOLK_Term *iri)
{
    if (iri->type != VOLK_TERM_IRIREF) {
        log_error ("Provided path is not an IRI.");
        return NULL;
    }
    if (root->type != VOLK_TERM_IRIREF) {
        log_error ("Provided root is not an IRI.");
        return NULL;
    }

    char
        *data,
        *pfx = VOLK_iriref_prefix (iri);

    if (strlen (pfx) > 0) data = iri->data;

    else if (iri->data[0] == '/') {
        free (pfx);

        pfx = VOLK_iriref_prefix (root);
        data = malloc (strlen (iri->data) + strlen (pfx) + 1);
        if (!data) return NULL;

        sprintf (data, "%s%s", pfx, iri->data);

    } else {
        data = malloc (strlen (iri->data) + strlen (root->data) + 1);
        if (!data) return NULL;

        sprintf (data, "%s%s", root->data, iri->data);
    }
    free (pfx);

    VOLK_Term *ret = VOLK_iriref_new (data);
    if (data != iri->data) free (data);

    return ret;
}


VOLK_Term *
VOLK_iriref_new_rel (const VOLK_Term *root, const VOLK_Term *iri)
{
    if (iri->type != VOLK_TERM_IRIREF) {
        log_error ("Provided path is not an IRI.");
        return NULL;
    }
    if (root->type != VOLK_TERM_IRIREF) {
        log_error ("Provided root is not an IRI.");
        return NULL;
    }

    size_t offset = (
            strstr (iri->data, root->data) == iri->data ?
            strlen (root->data) : 0);

    return VOLK_iriref_new (iri->data + offset);
}


VOLK_Buffer *
VOLK_term_serialize (const VOLK_Term *term)
{
    /*
     * In serializing a term, the fact that two terms of different types may
     * be semantically identical must be taken into account. Specifically, a
     * namespace-prefixed IRI ref is identical to its fully qualified version,
     * and a VOLK_TERM_LT_LITERAL with no language tag is identical to a
     * VOLK_TERM_LITERAL of xsd:string type, made up of the same string. Such
     * terms must have identical serializations.
     */

    if (UNLIKELY (!term)) return NULL;

    VOLK_Term *tmp_term;
    void *metadata = NULL;

    if (term->type == VOLK_TERM_LT_LITERAL) {
        // For LT literals with empty lang tag, convert to a normal xsd:string.
        if (strlen (term->lang) == 0)
            tmp_term = VOLK_literal_new (term->data, NULL);
        else {
            tmp_term = VOLK_lt_literal_new (term->data, (char *) term->lang);
            memcpy (&metadata, tmp_term->lang, sizeof (metadata));
        }
    } else if (term->type == VOLK_TERM_LITERAL) {
        tmp_term = VOLK_term_new (term->type, term->data, term->datatype);
        metadata = tmp_term->datatype;
    } else tmp_term = VOLK_term_copy (term);

    VOLK_Buffer *sterm;
    CALLOC_GUARD (sterm, NULL);

    //LOG_TRACE("Effective term being serialized: %s", tmp_term->data);
    int rc = tpl_jot (
            TPL_MEM, &sterm->addr, &sterm->size, TERM_PACK_FMT,
            &tmp_term->type, &tmp_term->data, &metadata);
    VOLK_term_free (tmp_term);

    if (rc != 0) {
        VOLK_buffer_free (sterm);
        return NULL;
    }

    return sterm;
}


VOLK_Key
VOLK_term_hash (const VOLK_Term *term)
{
    VOLK_Buffer *buf;

    if (UNLIKELY (!term)) buf = BUF_DUMMY;
    else buf = VOLK_term_serialize (term);

    VOLK_Key key = VOLK_buffer_hash (buf);

    VOLK_buffer_free (buf);

    return key;
}


void
VOLK_term_free (VOLK_Term *term)
{
    if (UNLIKELY (!term)) return;

    if (term->type == VOLK_TERM_IRIREF) free (term->iri_info);
    free (term->data);
    free (term);
}


char *
VOLK_iriref_prefix (const VOLK_Term *iri)
{
    if (iri->type != VOLK_TERM_IRIREF) {
        log_error ("Term is not a IRI ref type.");
        return NULL;
    }

    // if (iri->iri_info->prefix.size == 0) return NULL;

    return strndup (
            iri->data + iri->iri_info->prefix.offset,
            iri->iri_info->prefix.size);
}


char *
VOLK_iriref_path (const VOLK_Term *iri)
{
    if (iri->type != VOLK_TERM_IRIREF) {
        log_error ("Term is not a IRI ref type.");
        return NULL;
    }

    // if (iri->iri_info->path.size == 0) return NULL;

    return strndup (
            iri->data + iri->iri_info->path.offset,
            iri->iri_info->path.size);
}


char *
VOLK_iriref_frag (const VOLK_Term *iri)
{
    if (iri->type != VOLK_TERM_IRIREF) {
        log_error ("Term is not a IRI ref type.");
        return NULL;
    }

    // if (iri->iri_info->frag.size == 0) return NULL;

    return strndup (
            iri->data + iri->iri_info->frag.offset,
            iri->iri_info->frag.size);
}


/*
 * Triple API.
 */

VOLK_Triple *
VOLK_triple_new(VOLK_Term *s, VOLK_Term *p, VOLK_Term *o)
{
    VOLK_Triple *spo = malloc (sizeof (*spo));
    if (!spo) return NULL;

    if (UNLIKELY (VOLK_triple_init (spo, s, p, o))) {
        free (spo);
        return NULL;
    }

    return spo;
}


VOLK_Triple *
VOLK_triple_new_from_btriple (const VOLK_BufferTriple *sspo)
{
    VOLK_Triple *spo = malloc (sizeof (*spo));
    if (!spo) return NULL;

    spo->s = VOLK_term_new_from_buffer (sspo->s);
    spo->p = VOLK_term_new_from_buffer (sspo->p);
    spo->o = VOLK_term_new_from_buffer (sspo->o);

    return spo;
}


VOLK_BufferTriple *
VOLK_triple_serialize (const VOLK_Triple *spo)
{
    VOLK_BufferTriple *sspo = malloc (sizeof (*sspo));
    if (!sspo) return NULL;

    sspo->s = VOLK_term_serialize (spo->s);
    sspo->p = VOLK_term_serialize (spo->p);
    sspo->o = VOLK_term_serialize (spo->o);

    return sspo;
}


VOLK_rc
VOLK_triple_init (VOLK_Triple *spo, VOLK_Term *s, VOLK_Term *p, VOLK_Term *o)
{
    /* FIXME TRP_DUMMY is a problem here.
    if (! VOLK_IS_IRI (s) && s->type != VOLK_TERM_BNODE) {
        log_error ("Subject is not of a valid term type: %d", s->type);
        return VOLK_VALUE_ERR;
    }
    if (! VOLK_IS_IRI (p)) {
        log_error ("Predicate is not of a valid term type: %d", p->type);
        return VOLK_VALUE_ERR;
    }
    */

    spo->s = s;
    spo->p = p;
    spo->o = o;

    return VOLK_OK;
}


void
VOLK_triple_done (VOLK_Triple *spo)
{
    if (UNLIKELY (!spo)) return;

    VOLK_term_free (spo->s);
    VOLK_term_free (spo->p);
    VOLK_term_free (spo->o);
}


void
VOLK_triple_free (VOLK_Triple *spo)
{
    if (UNLIKELY (!spo)) return;

    VOLK_term_free (spo->s);
    VOLK_term_free (spo->p);
    VOLK_term_free (spo->o);

    free (spo);
}


/*
 * Multi-add functions.
 */

VOLK_TermSet *
VOLK_term_set_new ()
{
    // Capacity of 4 is an arbitrary guess.
    VOLK_TermSet *ts = hashmap_new (
            sizeof (KeyedTerm), 4, VOLK_HASH_SEED, 0,
            tset_hash_fn, tset_cmp_fn, tset_free_fn, NULL);
    if (UNLIKELY (hashmap_oom (ts))) return NULL;

    return ts;
}


VOLK_rc
VOLK_term_set_add (VOLK_TermSet *ts, VOLK_Term *term, VOLK_Term **existing)
{
    VOLK_Hash key = VOLK_term_hash (term);
    KeyedTerm entry_s = {.key=key, .term=term};

    const KeyedTerm *ex = hashmap_get (ts, &entry_s);
    if (ex) {
        if (existing) *existing = ex->term;
        return VOLK_NOACTION;
    }

    hashmap_set (ts, &entry_s);
    if (hashmap_oom (ts)) return VOLK_MEM_ERR;

    return VOLK_OK;
}


const VOLK_Term *
VOLK_term_set_get (VOLK_TermSet *ts, VOLK_Key key)
{
    const KeyedTerm *entry = hashmap_get (ts, &(KeyedTerm){.key=key});
    if (entry) LOG_TRACE("ID found for key %lx: %s", key, entry->term->data);
    else LOG_TRACE("No ID found for key %lx.", key);

    return (entry) ? entry->term : NULL;
}


VOLK_rc
VOLK_term_set_next (VOLK_TermSet *ts, size_t *i, VOLK_Term **term)
{
    KeyedTerm *kt = NULL;
    if (!hashmap_iter (ts, i, (void **)&kt)) return VOLK_END;

    if (term) *term = kt->term;

    return VOLK_OK;
}


void
VOLK_term_set_free (VOLK_TermSet *ts)
{
    if (UNLIKELY (!ts)) return;
    hashmap_free (ts);
}


size_t
VOLK_term_set_size (VOLK_TermSet *ts)
{ return hashmap_count (ts); }


VOLK_LinkMap *
VOLK_link_map_new (const VOLK_Term *linked_term, VOLK_LinkType type)
{
    VOLK_LinkMap *lm;
    MALLOC_GUARD (lm, NULL);
    lm->type = type;
    lm->links = hashmap_new (
            sizeof (Link), 0, VOLK_HASH_SEED, 0,
            link_map_hash_fn, link_map_cmp_fn, link_map_free_fn, NULL);
    if (!linked_term) {
        log_error ("term must not be NULL.");
        free (lm);
        return NULL;
    }
    lm->linked_t = VOLK_term_copy (linked_term);

    return lm;
}


void
VOLK_link_map_free (VOLK_LinkMap *lm)
{
    hashmap_free (lm->links);
    VOLK_term_free (lm->linked_t);
    free (lm);
}


VOLK_LinkType
VOLK_link_map_type (const VOLK_LinkMap *map)
{ return map->type; }


// TODO Memory error handling.
VOLK_rc
VOLK_link_map_add (
        VOLK_LinkMap *lmap, VOLK_Term *term, VOLK_TermSet *tset)
{
    // Keyed term to look up the link term and insert it, if necessary.
    KeyedTerm entry_s = {.key=VOLK_term_hash (term), .term=term};

    const Link *ex = hashmap_get (lmap->links, &(Link){.term=&entry_s});
    if (ex) {
        // Add terms one by one to the existing term set.
        LOG_TRACE(
                "Linking term %s exists. Adding individual terms.",
                ex->term->term->data);
        size_t i = 0;
        KeyedTerm *kt;
        while (hashmap_iter (tset, &i, (void **)&kt)) {
            LOG_TRACE(
                    "Adding term %s to link %s",
                    kt->term->data, ex->term->term->data);
            if (hashmap_get (ex->tset, kt))
                // Term already exist, free the new one and move on.
                VOLK_term_free (kt->term);
            else
                // Insert KeyedTerm, the term set now owns the underlying term.
                hashmap_set (ex->tset, kt);
        }
        // Free link term that hasn't been used.
        VOLK_term_free (term);
    } else {
        // Add the new term and the termset wholesale.
        LOG_TRACE("Adding new linking term %s.", term->data);
        // Allocate inserted member on heap, it will be owned by the map.
        KeyedTerm *ins;
        MALLOC_GUARD (ins, VOLK_MEM_ERR);
        memcpy (ins, &entry_s, sizeof (entry_s));
        Link link = {.term=ins, .tset=tset};
        hashmap_set (lmap->links, &link);
    }

    return VOLK_OK;
}


VOLK_LinkMapIterator *
VOLK_link_map_iter_new (const VOLK_LinkMap *lmap)
{
    VOLK_LinkMapIterator *it;
    CALLOC_GUARD (it, NULL);
    it->map = lmap;

    return it;
}


// This leaves the link and link map references intact.
void
VOLK_link_map_iter_free (VOLK_LinkMapIterator *it) { free (it); }


VOLK_rc
VOLK_link_map_next (
        VOLK_LinkMapIterator *it, VOLK_Term **lt, VOLK_TermSet **ts)
{
    if (!hashmap_iter (it->map->links, &it->i, (void **)&it->link))
        return VOLK_END;

    *lt = it->link->term->term;
    *ts = it->link->tset;

    return VOLK_OK;
}


// TODO dismantle if the only triple generator is for the graph.
VOLK_rc
VOLK_link_map_triples (
        VOLK_LinkMapIterator *it, VOLK_Triple *spo)
{
    // Assign external (related) term.
    if (it->map->type == VOLK_LINK_INBOUND)
        spo->o = it->map->linked_t;
    else if (it->map->type == VOLK_LINK_OUTBOUND)
        spo->s = it->map->linked_t;
    else spo->p = it->map->linked_t;

    KeyedTerm *kt;

    // If we are already handling a link, continue the internal loop.
    if (it->link) goto int_loop;
ext_loop:
    // Advance external counter and start new internal loop.
    it->j = 0;
    if (!hashmap_iter (it->map->links, &it->i, (void **)&it->link))
        return VOLK_END;
int_loop:
    // If end of the term set is reached, start with a new linking term.
    if (!hashmap_iter (it->link->tset, &it->j, (void **)&kt)) goto ext_loop;

    // Continue pulling from term set.
    // Assign linking term.
    if (it->map->type == VOLK_LINK_EDGE) spo->s = it->link->term->term;
    else spo->p = it->link->term->term;

    // Assign term in term set.
    if (it->map->type == VOLK_LINK_INBOUND) spo->s = kt->term;
    else spo->o = kt->term;

    return VOLK_OK;
}


/*
 * Static functions.
 */

static VOLK_rc
term_init (
        VOLK_Term *term, VOLK_TermType type,
        const char *data, void *metadata)
{
    // Exit early if environment is not initialized.
    // EXCEPT for IRIRef which is used inside of VOLK_init().
    if (!VOLK_IS_INIT && type != VOLK_TERM_IRIREF)
        return VOLK_ENV_ERR;

    // Undefined type. Make quick work of it.
    if (type == VOLK_TERM_UNDEFINED) {
        term->type = type;
        if (data) {
            term->data = malloc (strlen (data) + 1);
            if (UNLIKELY (!term->data)) return VOLK_MEM_ERR;
            strcpy (term->data, data);
        }
        return VOLK_OK;
    }

    if (type < MIN_VALID_TYPE || type > MAX_VALID_TYPE) {
        log_error ("%d is not a valid term type.", type);
        return VOLK_VALUE_ERR;
    }

    term->type = type;

    if (data) {
        // Validate IRI.
        if (term->type == VOLK_TERM_IRIREF) {
            char *fquri = (char *) data;

            if (strpbrk (fquri, invalid_uri_chars) != NULL) {
                log_warn (
                        "Characters %s are not valid in a URI. Got: %s\n",
                        invalid_uri_chars, fquri);
#if 0
                // TODO This causes W3C TTL test #29 to fail. Remove?
                return VOLK_VALUE_ERR;
#endif
            }

            // Capture interesting IRI parts.
            MatchCoord matches[7] = {};  // Initialize all to 0.
            if (UNLIKELY (parse_iri (fquri, matches) != VOLK_OK)) {
                log_error ("Error matching URI pattern.");

                return VOLK_VALUE_ERR;
            }
            MALLOC_GUARD (term->iri_info, VOLK_MEM_ERR);

            term->iri_info->prefix = matches[1];
            term->iri_info->path = matches[4];
            term->iri_info->frag = matches[6];
        }

        term->data = strdup (data);

    } else {
        // No data. Make up a random UUID or URI if allowed.
        if (type == VOLK_TERM_IRIREF || type == VOLK_TERM_BNODE) {
            uuid_t uuid;
            uuid_generate_random (uuid);

            uuid_str_t uuid_str;
            uuid_unparse_lower (uuid, uuid_str);

            if (type == VOLK_TERM_IRIREF) {
                term->data = malloc (UUID4_URN_SIZE);
                snprintf (
                        term->data, UUID4_URN_SIZE, "urn:uuid4:%s", uuid_str);

                MALLOC_GUARD (term->iri_info, VOLK_MEM_ERR);

                // Allocate IRI match patterns manually.
                term->iri_info->prefix.offset = 0;
                term->iri_info->prefix.size = 4;
                term->iri_info->path.offset = 4;
                term->iri_info->path.size = UUIDSTR_SIZE + 6;
                term->iri_info->frag.offset = 0;
                term->iri_info->frag.size = 0;

            } else term->data = strdup (uuid_str);
        } else {
            log_error ("No data provided for term.");
            return VOLK_VALUE_ERR;
        }
    }

    if (term->type == VOLK_TERM_LT_LITERAL) {
        if (!metadata) {
            log_warn ("Lang tag is NULL. Creating a non-tagged literal.");
            term->type = VOLK_TERM_LITERAL;
        } else {
            // FIXME metadata should be const all across.
            char *lang_str = (char *) metadata;
            LOG_TRACE("Lang string: '%s'", lang_str);
            // Lang tags longer than 7 characters will be truncated.
            strncpy(term->lang, lang_str, sizeof (term->lang) - 1);
            if (strlen (term->lang) < 1) {
                log_error ("Lang tag cannot be an empty string.");
                return VOLK_VALUE_ERR;
            }
            term->lang[7] = '\0';
        }
    }

    if (term->type == VOLK_TERM_LITERAL) {
        term->datatype = metadata;
        if (! term->datatype) term->datatype = VOLK_default_datatype;
        LOG_TRACE("Storing data type: %s", term->datatype->data);

        if (term->datatype->type != VOLK_TERM_IRIREF) {
            log_error (
                    "Literal data type is not an IRI: %s",
                    term->datatype->data);

            return VOLK_VALUE_ERR;
        }

        VOLK_Term *ex = NULL;
        VOLK_term_set_add (VOLK_term_cache, term->datatype, &ex);
        if (ex && ex != term->datatype) {
            // Replace datatype handle with the one in term cache, and free
            // the new one.
            if (term->datatype != VOLK_default_datatype)
                VOLK_term_free (term->datatype);
            term->datatype = ex;
        }

        //LOG_TRACE("Datatype address: %p", term->datatype);
        LOG_TRACE("Datatype hash: %lx", VOLK_term_hash (term->datatype));

    } else if (term->type == VOLK_TERM_BNODE) {
        // TODO This is not usable for global skolemization.
        term->bnode_id = VOLK_HASH (
                term->data, strlen (term->data) + 1, VOLK_HASH_SEED);
    }

    return VOLK_OK;
}


/**
 * @brief scan an IRI string and parse IRI parts.
 *
 * Experimental replacement of a regex engine for better performance.
 *
 * Slightly adapted from regex on
 * https://datatracker.ietf.org/doc/html/rfc3986#appendix-B to capture relevant
 * parts of the IRI.
 *
 * Reference regex and group numbering:
 * ^((?([^:/?#]+):)?(?//([^/?#]*))?)((?[^?#]*)(?\?([^#]*))?(?#(.*))?)
 *  1  2                3           4             5           6
 *
 * Capturing groups:
 *
 * #0: Full parsed URI (http://example.org/123/456/?query=blah#frag)
 * #1: Prefix (http://example.org)
 * #2: Scheme (http)
 * #3: Authority (example.org)
 * #4: Path, including query and fragment (/123/456/?query=blah#frag)
 * #5: Query (query=blah)
 * #6: Fragment (frag)
 *
 *
 * @param iri_str[in] IRI string to parse.
 *
 * @param match_coord_t[out] coord Coordinates to be stored. This must be a
 * pre-allocated array of at least 7 elements.
 *
 * The first size_t of each element stores the relative position of a match,
 * and the second one stores the length of the match. A length of 0 indicates
 * no match.
 */
static VOLK_rc
parse_iri (char *iri_str, MatchCoord coord[]) {
    char *cur = iri_str;
    size_t iri_len = strlen (iri_str);
    MatchCoord tmp = {};  // Temporary storage for capture groups

    // Redundant if only called by term_init.
    // memset (coord, 0, sizeof(*coord));

    //LOG_DEBUG("Parsing IRI: %s", iri_str);
    // #2: ([^:/?#]+)
    while (
            *cur != ':' && *cur != '/' && *cur != '?'
            && *cur != '#' && *cur != '\0') {
        tmp.size++;
        cur++;
    }

    // Non-capturing: (?([^:/?#]+):)?
    if (tmp.size > 0 && *cur == ':') {
        // Got capture groups #2 and #3. Store them.
        coord[2].offset = 0;
        coord[2].size = tmp.size;
        cur++;
        //LOG_DEBUG("Group #2: %lu, %lu", coord[2].offset, coord[2].size);
    } else cur = iri_str;  // Backtrack if no match.

    // Non-capturing: (?//([^/?#]*))?
    if (*cur == '/' && *(cur + 1) == '/') {
        cur += 2;
        tmp.offset = cur - iri_str;
        tmp.size = 0;

        // #3: ([^/?#]*)
        while (*cur != '/' && *cur != '?' && *cur != '#' && *cur != '\0') {
            tmp.size++;
            cur++;
        }
        coord[3].offset = tmp.offset;
        coord[3].size = tmp.size;
        //LOG_DEBUG("Group #3: %lu, %lu", coord[3].offset, coord[3].size);
    }

    // Capture group 1.
    coord[1].offset = 0;
    coord[1].size = cur - iri_str;
    //LOG_DEBUG("Group #1: %lu, %lu", coord[1].offset, coord[1].size);

    tmp.offset = cur - iri_str;
    tmp.size = 0;

    coord[4].offset = tmp.offset;
    coord[4].size = iri_len - tmp.offset;
    //LOG_DEBUG("Group #4: %lu, %lu", coord[4].offset, coord[4].size);

    // Non-capturing: (?[^?#]*)
    while (*cur != '?' && *cur != '#' && *cur != '\0') {
        tmp.size++;
        cur++;
    }

    // Non-capturing: (?\?([^#]*))
    if (*cur == '?') {
        // 5: ([^#]*)
        tmp.offset = ++cur - iri_str;
        tmp.size = 0;
        while (*cur != '#' && *cur != '\0') {
            tmp.size++;
            cur++;
        }

        if (tmp.size > 0) {
            // Got capture group #5.
            coord[5].offset = tmp.offset;
            coord[5].size = tmp.size;
            //LOG_DEBUG("Group #5: %lu, %lu", coord[5].offset, coord[5].size);
        }
    }

    // Non-capturing: (?#(.*))?
    if (*cur == '#') {
        // #6: (.*)
        coord[6].offset = ++cur - iri_str;
        coord[6].size = iri_str + iri_len - cur;
        //LOG_DEBUG("Group #6: %lu, %lu", coord[6].offset, coord[6].size);
    }

    coord[0].offset = 0;
    coord[0].size = iri_len;
    //LOG_DEBUG("Full match: %lu, %lu", coord[0].offset, coord[0].size);

    return VOLK_OK;
}


/*
 * Extern inline functions.
 */

VOLK_Key VOLK_term_hash (const VOLK_Term *term);
VOLK_Term *VOLK_iriref_new (const char *data);
VOLK_Term *VOLK_iriref_new_ns (const char *data);
VOLK_Term *VOLK_literal_new (const char *data, VOLK_Term *datatype);
VOLK_Term *VOLK_lt_literal_new (const char *data, char *lang);
VOLK_Term *VOLK_bnode_new (const char *data);
bool VOLK_term_equals (const VOLK_Term *term1, const VOLK_Term *term2);
VOLK_Term *VOLK_triple_pos (const VOLK_Triple *trp, VOLK_TriplePos n);
VOLK_Key VOLK_triple_hash (const VOLK_Triple *trp);