4 #include <hashvector.h>
8 * A relation is an implementation of a tuple set with (optional) key
9 * constraints. The store is a \ref hashvector whose \b type is a \ref
10 * tupleschema that defines the columns. The key constraints are
11 * represented as additional \ref hashvector "hashvectors" whose \ref
12 * tupleschema "tupleschemas" are clones of the column schema with
13 * some columns excluded.
19 * This is the primary content store for the relation. Its type
20 * should be a tupleschema declaring the "item types" for the
26 * This is a collection of relational constraints, if any, which
27 * are represented as hashvectors whose tupleschemas are clones of
28 * the content tupleschema with some columns excluded.
34 * \brief Create a relation for the given tupleschema.
36 * \param schema is the column schema
38 * \returns the allocated relation record.
40 * The given tupleschema is set up as the type of the content
41 * hashvector, which also is initialised as a nibble_index_levels
46 extern relation *relation_create(tupleschema *schema);
49 * \brief Add a key constraint to a \ref relation.
51 * \param r is the relation concerned.
53 * \param key is the constraint \ref tupleschema.
55 * \returns the index into the constraints \ref vector for the added
58 * This function adds a \ref hashvector with the provided \ref
59 * tupleschema as its item type. The \b key \ref tupleschema must be a
60 * clone of the \ref relation column schema with some (or all) value
61 * columns marked as \b 0. Such a \ref tupleschema may be obtained via
62 * the function \ref tupleschema_mask to clone the \ref relation
63 * content type (casted as \ref tupleschema*) and clear columns by
66 * The constraint \ref hashvectors are used when tuples are added to
67 * the \ref relation so as to identify the already contained tuples
68 * that contradict the addition by means of having the same constraint
69 * key. The already contained tuples are then "knocked out" from the
70 * relation by the new addition.
72 * \see tupleschema_mask, relation_add
75 extern int relation_add_constraint(relation *r,tupleschema *key);
78 * \brief Add the tuple to the relation.
80 * \param r is the \ref relation concerned.
82 * \param t is the \ref tuple to add.
84 * \returns a vector of all knocked out tuples.
86 * This function adds the \ref tuple \b t to the \ref relation \b r,
87 * and it returns a \ref vector (single_index_level variant) of all
88 * same-key constraint tuples. The returned vector is malloc-ed and it
89 * must be free-ed by the caller. If the tuple is already contained or
90 * there are no other same-key tuples knocked out, then \b 0 is
95 extern vector *relation_add(relation *r,tuple *t);
98 * \brief Delete all tuples matching to the query \ref tuple fromt the
101 * \param r is the \ref relation concerned.
103 * \param t is the \ref tuple to delete.
105 * \returns a \vector vector of all knocked out tuples, i.e. the
106 * same-key tuples, if any, contained in the relation
108 * Note that deletion uses a "query" tuple, which means that some
109 * columns may be null to mark that them match to any value.
113 extern vector *relation_delete(relation *r,tuple *query);
116 * \brief Return the next \ref tuple in the \ref relation that matches
117 * to the query \ref tuple, at or after the index.
119 * \param r is the \ref relation concerned.
121 * \param index is a pointer to the \ref vector index to update.
123 * \param query is a query \tuple tuple for selection of certain
126 * \returns any such matching \tuple tuple and an updateed *index.
130 extern void *relation_next(relation *r,vector_index *index,tuple *query);