dlite-collection#

A DLite Collection.

Collections are a special type of instances that hold a set of instances and relations between them.

A set of pre-defined relations are used to manage the collection itself. In order to not distinguish these relations from user-defined relations, their predicate are prefixed with a single underscore. The pre-defined relations are:

subject	predicate	object
label	“_is-a”	“Instance”
label	“_has-uuid”	uuid
label	“_has-meta”	metadata uri
label	“_has-hash”	hash of instance
label	“_has-dimmap”	relation-id -> (instdim, “_maps-to”, coldim)
instdim	“_maps-to”	colldim
coldim	“_has-size”	size

The “_has-dimmap” relations links an instance label to a “_maps-to” relation that maps a dimension in the instance (instdim) to a common dimension in the collection (colldim).

Note that we compared to SOFT, have added “n-rel-items” as a dimension such that the relations can be treated as an ordinary 2D array of strings.

Typedefs

typedef struct _DLiteCollection DLiteCollection#: A specialised instance for collections

typedef struct _TripleState DLiteCollectionState#: State used by dlite_collection_find().

Functions

int dlite_collection_init(DLiteInstance *inst)#

Initiates a collection instance.

Returns non-zero on error.

int dlite_collection_deinit(DLiteInstance *inst)#

Deinitiates a collection instance.

Returns non-zero on error.

void dlite_collection_reset_state(DLiteCollectionState *state)#: Resets state already initialised with dlite_collection_init_state().

int dlite_collection_gethash(const DLiteInstance *inst, uint8_t *hash, int hashsize)#

Calculate hash of a collection.

Returns non-zero on error.

int dlite_collection_getdim(const DLiteInstance *inst, size_t i)#: Returns size of dimension number i or -1 on error.

int dlite_collection_loadprop(const DLiteInstance *inst, size_t i)#: Loads instance relations to triplestore. Returns -1 on error.

int dlite_collection_saveprop(DLiteInstance *inst, size_t i)#: Saves triplestore to instance relations. Returns non-zero on error.

DLiteCollection *dlite_collection_create(const char *id)#

Returns a new collection with given id. If id is NULL, a new random uuid is generated.

Returns NULL on error.

Note

This is just a simple wrapper around dlite_instance_create().

void dlite_collection_incref(DLiteCollection *coll)#: Increases reference count of collection coll.

void dlite_collection_decref(DLiteCollection *coll)#: Decreases reference count of collection coll.

DLiteCollection *dlite_collection_from_instance(DLiteInstance *inst)#: Safe type casting from instance to collection.

DLiteInstance *dlite_collection_to_instance(DLiteCollection *coll)#: Cast collection to instance - always possible.

DLiteCollection *dlite_collection_load(DLiteStorage *s, const char *id, int lazy)#: Loads collection with given id from storage s. If lazy is zero, all its instances are loaded immediately. Otherwise, instances are first loaded on demand. Returns non-zero on error.

DLiteCollection *dlite_collection_load_url(const char *url, int lazy)#: Convinient function that loads a collection from url, which should be of the form “driver://location?options#id”. The lazy argument has the same meaning as for dlite_collection_load(). Returns non-zero on error.

int dlite_collection_save(DLiteCollection *coll, DLiteStorage *s)#: Saves collection and all its instances to storage s. Returns non-zero on error.

int dlite_collection_save_url(DLiteCollection *coll, const char *url)#: A convinient function that saves instance inst to the storage specified by url, which should be of the form “driver://path?options”. Returns non-zero on error.

int dlite_collection_add_relation(DLiteCollection *coll, const char *s, const char *p, const char *o, const char *d)#: Adds subject-predicate-object relation to collection. d is the datatype of literal object. Returns non-zero on error.

int dlite_collection_remove_relations(DLiteCollection *coll, const char *s, const char *p, const char *o, const char *d)#: Remove matching relations. Any of s, p or o may be NULL, allowing for multiple matches. Returns the number of relations removed, or -1 on error.

void dlite_collection_init_state(const DLiteCollection *coll, DLiteCollectionState *state)#: Initiates a DLiteCollectionState for dlite_collection_find() and dlite_collection_next(). The state must be deinitialised with dlite_collection_deinit_state().

void dlite_collection_deinit_state(DLiteCollectionState *state)#: Deinitiates a TripleState initialised with dlite_collection_init_state().

const DLiteRelation *dlite_collection_find(const DLiteCollection *coll, DLiteCollectionState *state, const char *s, const char *p, const char *o, const char *d)#

Finds matching relations.

If state is NULL, only the first match will be returned.

Otherwise, this function should be called iteratively. Before the first call it should be provided a state initialised with dlite_collection_init_state().

For each call it will return a pointer to triplet matching s, p and o. Any of these may be NULL, allowing for multiple matches. When no more matches can be found, NULL is returned.

No other calls to dlite_collection_add(), dlite_collection_find() or dlite_collection_add_relation() should be done while searching.

const DLiteRelation *dlite_collection_find_first(const DLiteCollection *coll, const char *s, const char *p, const char *o, const char *d)#: Like dlite_collection_find(), but returns only a pointer to the first matching relation, or NULL if there are no matching relations.

int dlite_collection_add_new(DLiteCollection *coll, const char *label, DLiteInstance *inst)#

Adds instance inst to collection, making coll the owner of the instance.

Returns non-zero on error.

int dlite_collection_add(DLiteCollection *coll, const char *label, DLiteInstance *inst)#: Adds (reference to) instance inst to collection. Returns non-zero on error.

int dlite_collection_remove(DLiteCollection *coll, const char *label)#: Removes instance with given label from collection. Returns non-zero on error.

const DLiteInstance *dlite_collection_get(const DLiteCollection *coll, const char *label)#: Returns borrowed reference to instance with given label or NULL on error.

const DLiteInstance *dlite_collection_get_id(const DLiteCollection *coll, const char *id)#: Returns borrowed reference to instance with given id or NULL on error.

DLiteInstance *dlite_collection_get_new(const DLiteCollection *coll, const char *label, const char *metaid)#

Returns a new reference to instance with given label. If metaid is given, the returned instance is casted to this metadata.

Returns NULL on error.

int dlite_collection_has(const DLiteCollection *coll, const char *label)#: Returns non-zero if collection coll contains an instance with the given label.

int dlite_collection_has_id(const DLiteCollection *coll, const char *id)#: Returns non-zero if collection coll contains a reference to an instance with UUID or uri that matches id.

DLiteInstance *dlite_collection_next(DLiteCollection *coll, DLiteCollectionState *state)#

Iterates over a collection.

Returns a borrowed reference to the next instance or NULL if all instances have been visited.

DLiteInstance *dlite_collection_next_new(DLiteCollection *coll, DLiteCollectionState *state)#

Iterates over a collection.

Returns a new reference to the next instance or NULL if all instances have been visited.

int dlite_collection_count(DLiteCollection *coll)#: Returns the number of instances that are stored in the collection or -1 on error.

const char *dlite_collection_value(DLiteCollection *coll, const char *s, const char *p, const char *o, const char *d, const char *fallback, int any)#

Return pointer to the value for a pair of two criteria.

Useful if one knows that there may only be one value. The returned value is held by the collection and should be copied by the user since it may be overwritten by later calls to the collection.

Parameters: s, p, o: Criteria to match. Two of these must be non-NULL. d: If not NULL, the required datatype of literal objects. fallback: Value to return if no matches are found. any: If non-zero, return first matching value.

Returns a pointer to the value of the s, p or o that is NULL. On error NULL is returned.

struct _DLiteCollection#

#include <dlite-collection.h>

A specialised instance for collections

Public Members

TripleStore *rstore#: TripleStore managing the relations.

size_t nrelations#: Number of relations.

DLiteRelation *relations#: Pointer to array of relations. This can safely be cast to char *relations[4], which is an 2D array of strings. Note that this pointer may change if relations is reallocated.

size_t __propdims[1]#