diff options
Diffstat (limited to 'sord')
| -rw-r--r-- | sord/sord.h | 389 |
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 */ |