vector/relation.h

   1 #ifndef relation_H
   2 #define relation_H
   3
   4 #include <hashvector.h>
   5 #include <tupleitem.h>
   6
   7 /**
   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.
  14  *
  15  * \extends hashvector
  16  */
  17 typedef struct {
  18     /**
  19      * This is the primary content store for the relation. Its type
  20      * should be a tupleschema declaring the "item types" for the
  21      * relation columns.
  22      */
  23     hashvector content;
  24
  25     /**
  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.
  29      */
  30     vector constraints;
  31 } relation;
  32
  33 /**
  34  * \brief Create a relation for the given tupleschema.
  35  *
  36  * \param schema is the column schema
  37  *
  38  * \returns the allocated relation record.
  39  *
  40  * The given tupleschema is set up as the type of the content
  41  * hashvector, which also is initialised as a nibble_index_levels
  42  * variant vector.
  43  *
  44  * \related relation
  45  */
  46 extern relation *relation_create(tupleschema *schema);
  47
  48 /**
  49  * \brief Add a key constraint to a \ref relation.
  50  *
  51  * \param r is the relation concerned.
  52  *
  53  * \param key is the constraint \ref tupleschema.
  54  *
  55  * \returns the index into the constraints \ref vector for the added
  56  * constraint.
  57  *
  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
  64  * their index.
  65  *
  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.
  71  *
  72  * \see tupleschema_mask, relation_add
  73  * \related relation
  74  */
  75 extern int relation_add_contraint(relation *r,tupleschema *key);
  76
  77 /**
  78  * \brief Add the tuple to the relation.
  79  *
  80  * \param r is the \ref relation concerned.
  81  *
  82  * \param t is the \ref tuple to add.
  83  *
  84  * \returns a vector of all knocked out tuples.
  85  *
  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
  91  * returned.
  92  *
  93  * \related relation
  94  */
  95 extern vector *relation_add(relation *r,tuple *t);
  96
  97 /**
  98  * \brief Delete all tuples matching to the query \ref tuple fromt the
  99  * \ref relation.
 100  *
 101  * \param r is the \ref relation concerned.
 102  *
 103  * \param t is the \ref tuple to delete.
 104  *
 105  * \returns a \vector vector of all knocked out tuples, i.e. the
 106  * same-key tuples, if any, contained in the relation
 107  *
 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.
 110  *
 111  * \related relation
 112  */
 113 extern vector *relation_delete(relation *r,tuple *query);
 114
 115 /**
 116  * \brief Return the next \ref tuple in the \ref relation that matches
 117  * to the query \ref tuple, at or after the index.
 118  *
 119  * \param r is the \ref relation concerned.
 120  *
 121  * \param index is a pointer to the \ref vector index to update.
 122  *
 123  * \param query is a query \tuple tuple for selection of certain
 124  * column values.
 125  *
 126  * \returns any such matching \tuple tuple and an updateed *index.
 127  *
 128  * \related relation
 129  */
 130 extern void *relation_next(relation *r,vector_index *index,tuple *query);
 131
 132 #endif