summaryrefslogtreecommitdiffstats
path: root/sord/sord.h
diff options
context:
space:
mode:
Diffstat (limited to 'sord/sord.h')
-rw-r--r--sord/sord.h389
1 files changed, 246 insertions, 143 deletions
diff --git a/sord/sord.h b/sord/sord.h
index c632815..f496811 100644
--- a/sord/sord.h
+++ b/sord/sord.h
@@ -1,72 +1,87 @@
-/* Sord, a lightweight RDF model library.
- * Copyright 2010-2011 David Robillard <d@drobilla.net>
- *
- * Sord is free software: you can redistribute it and/or modify it under
- * the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * Sord is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
- * License for details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program. If not, see <http://www.gnu.org/licenses/>.
- */
-
-/** @file sord.h
- * Public Sord API.
- */
+/*
+ Copyright 2011 David Robillard <http://drobilla.net>
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+
+ 1. Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+ INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+ AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+ OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+/**
+ @file sord.h API for Sord, a lightweight RDF model library.
+*/
#ifndef SORD_SORD_H
#define SORD_SORD_H
-#ifdef __cplusplus
-extern "C" {
-#endif
-
#include <stdbool.h>
+#include <stddef.h>
#include <stdint.h>
+#include <stdio.h>
#include "serd/serd.h"
-#if defined _WIN32 || defined __CYGWIN__
- #define SORD_LIB_IMPORT __declspec(dllimport)
- #define SORD_LIB_EXPORT __declspec(dllexport)
-#else
- #define SORD_LIB_IMPORT __attribute__ ((visibility("default")))
- #define SORD_LIB_EXPORT __attribute__ ((visibility("default")))
-#endif
-
-#ifdef SORD_SHARED // Building a shared library
- #ifdef SORD_INTERNAL // Building SORD (not using it)
+#ifdef SORD_SHARED
+ #if defined _WIN32 || defined __CYGWIN__
+ #define SORD_LIB_IMPORT __declspec(dllimport)
+ #define SORD_LIB_EXPORT __declspec(dllexport)
+ #else
+ #define SORD_LIB_IMPORT __attribute__ ((visibility("default")))
+ #define SORD_LIB_EXPORT __attribute__ ((visibility("default")))
+ #endif
+ #ifdef SORD_INTERNAL
#define SORD_API SORD_LIB_EXPORT
#else
#define SORD_API SORD_LIB_IMPORT
#endif
-#else // Building a static library
+#else
#define SORD_API
#endif
-/** @defgroup sord Sord
- * A lightweight RDF model library.
- * Sord stores RDF (subject object predicate) triples, where triples may
- * have an added "context" field, i.e. (subject object predicate context).
- * @{
- */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ @defgroup sord Sord
+ A lightweight RDF model library.
+
+ Sord stores RDF (subject object predicate context) quads, where the context
+ may be omitted (to represent triples in the default graph).
+ @{
+*/
typedef struct _SordWorld* SordWorld; ///< Sord world (library state)
typedef struct _SordModel* SordModel; ///< Quad store
typedef struct _SordIter* SordIter; ///< Store iterator
typedef struct _SordNode* SordNode; ///< Node
-/** Quad of IDs (statement), or a quad pattern.
- * Nodes are ordered (S P O G). The ID of the default graph is 0.
- */
+/**
+ Quad of IDs (statement), or a quad pattern.
+
+ Nodes are ordered (S P O G). The ID of the default graph is 0.
+*/
typedef SordNode SordQuad[4];
-/** Index into a SordQuad. */
+/**
+ Index into a SordQuad.
+*/
typedef enum {
SORD_SUBJECT = 0, ///< Subject
SORD_PREDICATE = 1, ///< Predicate (a.k.a. "key")
@@ -74,14 +89,18 @@ typedef enum {
SORD_GRAPH = 3 ///< Graph (a.k.a. "context")
} SordQuadIndex;
-/** Type of a node. */
+/**
+ Type of a node.
+*/
typedef enum {
SORD_URI = 1, ///< URI
SORD_BLANK = 2, ///< Blank node identifier
- SORD_LITERAL = 3 ///< Literal (string with optional lang and/or type)
+ SORD_LITERAL = 3 ///< Literal (string with optional lang or datatype)
} SordNodeType;
-/** Indexing option. */
+/**
+ Indexing option.
+*/
typedef enum {
SORD_SPO = 1, ///< Subject, Predicate, Object
SORD_SOP = 1 << 1, ///< Subject, Object, Predicate
@@ -91,9 +110,10 @@ typedef enum {
SORD_POS = 1 << 5 ///< Predicate, Object, Subject
} SordIndexOption;
-/** @name World
- * @{
- */
+/**
+ @name World
+ @{
+*/
SORD_API
SordWorld
@@ -103,223 +123,305 @@ SORD_API
void
sord_world_free(SordWorld world);
-/** @} */
-/** @name Nodes
- * A Node is a component of a Quad. Nodes may be URIs, blank nodes, or
- * (in the case of quad objects only) string literals. Literal nodes may
- * have an associate language or datatype (but not both).
- * @{
- */
+/**
+ @}
+ @name Nodes
+ A Node is a component of a Quad. Nodes may be URIs, blank nodes, or
+ (in the case of quad objects only) string literals. Literal nodes may
+ have an associate language or datatype (but not both).
+ @{
+*/
-/** Find a URI, creating a new one if necessary iff @a create is true.
- * Use sord_get_uri_counted instead if the length of @a str is known.
- */
+/**
+ Find a URI, creating a new one if necessary iff @a create is true.
+
+ Use sord_get_uri_counted instead if the length of @a str is known.
+*/
SORD_API
SordNode
sord_new_uri(SordWorld world, const uint8_t* str);
-/** Find a URI, creating a new one if necessary iff @a create is true. */
+/**
+ Find a URI, creating a new one if necessary iff @a create is true.
+*/
SORD_API
SordNode
-sord_new_uri_counted(SordWorld world, const uint8_t* str, int str_len);
+sord_new_uri_counted(SordWorld world,
+ const uint8_t* str,
+ int str_len);
-/** Find a blank, creating a new one if necessary iff @a create is true
- * Use sord_get_blank_counted instead if the length of @a str is known.
- */
+/**
+ Find a blank, creating a new one if necessary iff @a create is true.
+
+ Use sord_get_blank_counted instead if the length of @a str is known.
+*/
SORD_API
SordNode
sord_new_blank(SordWorld world, const uint8_t* str);
-/** Find a blank, creating a new one if necessary iff @a create is true. */
+/**
+ Find a blank, creating a new one if necessary iff @a create is true.
+*/
SORD_API
SordNode
-sord_new_blank_counted(SordWorld world, const uint8_t* str, int str_len);
+sord_new_blank_counted(SordWorld world,
+ const uint8_t* str,
+ int str_len);
-/** Find a literal, creating a new one if necessary iff @a create is true.
- * Use sord_get_literal_counted instead if the length of @a str is known.
- */
+/**
+ Find a literal, creating a new one if necessary iff @a create is true.
+
+ Use sord_get_literal_counted instead if the length of @a str is known.
+*/
SORD_API
SordNode
-sord_new_literal(SordWorld world, SordNode datatype,
- const uint8_t* str, const char* lang);
+sord_new_literal(SordWorld world,
+ SordNode datatype,
+ const uint8_t* str,
+ const char* lang);
-/** Find a literal, creating a new one if necessary iff @a create is true. */
+/**
+ Find a literal, creating a new one if necessary iff @a create is true.
+*/
SORD_API
SordNode
-sord_new_literal_counted(SordWorld world, SordNode datatype,
- const uint8_t* str, int str_len,
- const char* lang, uint8_t lang_len);
+sord_new_literal_counted(SordWorld world,
+ SordNode datatype,
+ const uint8_t* str,
+ int str_len,
+ const char* lang,
+ uint8_t lang_len);
-/** Copy a node. */
+/**
+ Copy a node.
+*/
SORD_API
SordNode
sord_node_copy(SordNode node);
-/** Free a node. */
+/**
+ Free a node.
+*/
SORD_API
void
sord_node_free(SordNode node);
-/** Return the type of a node (SORD_URI, SORD_BLANK, or SORD_LITERAL). */
+/**
+ Return the type of a node (SORD_URI, SORD_BLANK, or SORD_LITERAL).
+*/
SORD_API
SordNodeType
sord_node_get_type(SordNode node);
-/** Return the string value of a node. */
+/**
+ Return the string value of a node.
+*/
SORD_API
const uint8_t*
sord_node_get_string(SordNode node);
-/** Return the string value of a node, and set @a len to its length. */
+/**
+ Return the string value of a node, and set @a len to its length.
+*/
SORD_API
const uint8_t*
sord_node_get_string_counted(SordNode node, size_t* len);
-/** Return the language of a literal node (or NULL). */
+/**
+ Return the language of a literal node (or NULL).
+*/
SORD_API
const char*
sord_node_get_language(SordNode node);
-/** Return the datatype URI of a literal node (or NULL). */
+/**
+ Return the datatype URI of a literal node (or NULL).
+*/
SORD_API
SordNode
sord_node_get_datatype(SordNode node);
-/** Return true iff @a a is equal to @a b.
- * Note this is much faster than comparing the node's strings.
- */
+/**
+ Return true iff @a a is equal to @a b.
+
+ Note this is much faster than comparing the node's strings.
+*/
SORD_API
bool
-sord_node_equals(const SordNode a, const SordNode b);
+sord_node_equals(const SordNode a,
+ const SordNode b);
/** @} */
/** @name Model
* @{
*/
-/** Create a new store.
- * @param indices SordIndexOption flags (e.g. SORD_SPO|SORD_OPS).
- * Be sure to choose indices such that there is an index where the most
- * significant node(s) are not variables for your queries. For example,
- * if you are going to make (? P O) queries, you should enable either
- * SORD_OPS or SORD_POS.
- * @param graphs If true, store (and index) graph contexts.
- */
+/**
+ Create a new store.
+
+ @param world The world in which to make this store.
+
+ @param indices SordIndexOption flags (e.g. SORD_SPO|SORD_OPS). Be sure to
+ choose indices such that there is an index where the most significant
+ node(s) are not variables for your queries. For example, if you are going
+ to make (? P O) queries, you should enable either SORD_OPS or SORD_POS.
+
+ @param graphs If true, store (and index) graph contexts.
+*/
SORD_API
SordModel
-sord_new(SordWorld world, unsigned indices, bool graphs);
+sord_new(SordWorld world,
+ unsigned indices,
+ bool graphs);
-/** Close and free @a sord. */
+/**
+ Close and free @a sord.
+*/
SORD_API
void
sord_free(SordModel model);
+/**
+ Get the world associated with @a model.
+*/
SORD_API
SordWorld
sord_get_world(SordModel model);
-/** Return the number of nodes stored in @a sord.
- * Nodes are included in this count iff they are a part of a quad in @a sord.
- */
+/**
+ Return the number of nodes stored in @a sord.
+
+ Nodes are included in this count iff they are a part of a quad in @a sord.
+*/
SORD_API
int
sord_num_nodes(SordWorld world);
-/** Return the number of quads stored in @a sord. */
+/**
+ Return the number of quads stored in @a sord.
+*/
SORD_API
int
sord_num_quads(SordModel model);
-/** Return an iterator to the start of the store. */
+/**
+ Return an iterator to the start of the store.
+*/
SORD_API
SordIter
sord_begin(SordModel model);
-/** Return an iterator that will iterate over each graph URI. */
+/**
+ Return an iterator that will iterate over each graph URI.
+*/
SORD_API
SordIter
sord_graphs_begin(SordModel model);
-/** Search for a triple pattern.
- * @return an iterator to the first match, or NULL if no matches found
- */
+/**
+ Search for a triple pattern.
+ @return an iterator to the first match, or NULL if no matches found.
+*/
SORD_API
SordIter
sord_find(SordModel model, const SordQuad pat);
-/** Add a quad to the store. */
+/**
+ Add a quad to the store.
+*/
SORD_API
void
sord_add(SordModel model, const SordQuad quad);
-/** Remove a quad from the store.
- * This function invalidates all iterators to @a sord (use sord_remove_iter
- * if this is undesirable)
- */
+/**
+ Remove a quad from the store.
+
+ This function invalidates all iterators to @a sord (use sord_remove_iter
+ if this is undesirable)
+*/
SORD_API
void
sord_remove(SordModel model, const SordQuad quad);
-/** Remove a quad from the store by iterator.
- * @a iter will be incremented to point at the next value.
- */
+/**
+ Remove a quad from the store by iterator.
+
+ @a iter will be incremented to point at the next value.
+*/
SORD_API
void
sord_remove_iter(SordModel model, SordIter iter);
-/** Remove a graph from the store. */
+/**
+ Remove a graph from the store.
+*/
SORD_API
void
sord_remove_graph(SordModel model, SordNode graph);
-/** @} */
-/** @name Iteration
- * @{
- */
+/**
+ @}
+ @name Iteration
+ @{
+*/
-/** Set @a id to the quad pointed to by @a iter. */
+/**
+ Set @a id to the quad pointed to by @a iter.
+*/
SORD_API
void
sord_iter_get(SordIter iter, SordQuad quad);
-/** Return the store pointed to by @a iter. */
+/**
+ Return the store pointed to by @a iter.
+*/
SORD_API
SordModel
sord_iter_get_model(SordIter iter);
-/** Increment @a iter to point to the next statement. */
+/**
+ Increment @a iter to point to the next statement.
+*/
SORD_API
bool
sord_iter_next(SordIter iter);
-/** Return true iff @a iter is at the end of its range. */
+/**
+ Return true iff @a iter is at the end of its range.
+*/
SORD_API
bool
sord_iter_end(SordIter iter);
-/** Free @a iter. */
+/**
+ Free @a iter.
+*/
SORD_API
void
sord_iter_free(SordIter iter);
-/** @} */
-/** @name Utilities
- * @{
- */
+/**
+ @}
+ @name Utilities
+ @{
+*/
-/** Match two quads (using ID comparison only).
- * This function is a straightforward and fast equivalence match with wildcard
- * support (ID 0 is a wildcard). It never performs any database access.
- * @return true iff @a x and @a y match.
- */
+/**
+ Match two quads (using ID comparison only).
+
+ This function is a straightforward and fast equivalence match with wildcard
+ support (ID 0 is a wildcard). It does not actually read node data.
+ @return true iff @a x and @a y match.
+*/
SORD_API
bool
sord_quad_match(const SordQuad x, const SordQuad y);
-/** @} */
-/** @name Serialisation
- * @{
- */
+/**
+ @}
+ @name Serialisation
+ @{
+*/
SORD_API
bool
@@ -366,12 +468,13 @@ sord_write_string(SordModel model,
const uint8_t* base_uri);
-/** @} */
-
-/** @} */
+/**
+ @}
+ @}
+*/
#ifdef __cplusplus
-} /* extern "C" */
+} /* extern "C" */
#endif
-#endif // SORD_SORD_H
+#endif /** SORD_SORD_H */