4 #include <HashVector.h>
5 #include <TupleSchema.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 ... are the column flags indicating key (1) or value (0)
54 * column for all columns.
56 * \returns the index into the constraints \ref Vector for the added
59 * This function adds a \ref HashVector with a \ref TupleSchema as its
60 * item type cloned from the content type and then modified to
61 * represent the constraint. Namely that the key columns have their
62 * "column type" set while value columsn are reset.
64 * The \b constraint \ref HashVectors are used when \ref tuple
65 * "tuples" are added to the \ref Relation so as to identify the
66 * already contained \ref tuple "tuples" that contradict the addition
67 * by means of having the same constraint key. The already contained
68 * \ref tuple "tuples" are then "knocked out" from the Relation by the
74 extern int Relation_add_constraint(Relation *r,...);
77 * \brief Add the tuple to the Relation.
79 * \param r is the \ref Relation concerned.
81 * \param t is the \ref tuple to add.
83 * \returns a Vector of all knocked out tuples.
85 * This function adds the \ref tuple \b t to the \ref Relation \b r,
86 * and it returns a \ref Vector (single_index_level variant) of all
87 * same-key constraint tuples. The returned Vector is malloc-ed and it
88 * must be free-ed by the caller. If the tuple is already contained or
89 * there are no other same-key tuples knocked out, then \b 0 is
94 extern Vector *Relation_add(Relation *r,Tuple *t);
97 * \brief Delete all tuples matching to the Query \ref tuple fromt the
100 * \param r is the \ref Relation concerned.
102 * \param t is the \ref tuple to delete.
104 * \returns a \Vector Vector of all knocked out tuples, i.e. the
105 * same-key tuples, if any, contained in the Relation
107 * Note that deletion uses a "Query" tuple, which means that some
108 * columns may be null to mark that them match to any value.
112 extern Vector *Relation_delete(Relation *r,Tuple *query);
115 * \brief Return the next \ref tuple in the \ref Relation that matches
116 * to the Query \ref tuple, at or after the index.
118 * \param r is the \ref Relation concerned.
120 * \param index is a pointer to the \ref Vector index to update.
122 * \param Query is a Query \tuple tuple for selection of certain
125 * \returns any such matching \tuple tuple and an updateed *index.
129 extern void *Relation_next(Relation *r,VectorIndex *index,Tuple *query);
132 * \brief Lay out a dynamic \ref Relation initializer for a Relation
133 * wth the given column "types".
135 * This defines a \ref Relation intializer that creates the \ref
136 * TupleSchema for the given columns.
138 * \note The initializer cannot be used statically.
140 * The \b content \ref HashVector is a \ref Nibble_index_level variant
141 * with an initial size of 16 slots.
143 * The constraints \ref Vector is a \ref BitPair_index_level variant
144 * with initial size 0.
146 * The \b content \ref HashVector \b type is set up with an allocated
147 * \ref TupleSchema that has an allocated \ref tuple that declares the
148 * column "types" view the given \ref ItemKeyFun pointers. Any add
149 * constraints will need to clone that \ref TupleSchema and then clear
150 * the column slots for the constraint value columns, typically by
151 * using \ref TupleSchema_mask for this.
155 #define RELATION(...) (Relation) { \
157 .table = { .variant = Nibble_index_levels, .size=16, .entries=0 }, \
158 .fill = 0, .holes = 0, \
159 .type = (ItemKeyFun*) TUPLESCHEMA( __VA_ARGS__ ) \
161 .constraints = { .variant = BitPair_index_levels, .size=0, .entries=0 } \