docs/reference/glib/tmpl/relations.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Relations and Tuples
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 tables of data which can be indexed on any number of fields
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A #GRelation is a table of data which can be indexed on any number of fields,
  10 rather like simple database tables. A #GRelation contains a number of
  11 records, called tuples. Each record contains a number of fields.
  12 Records are not ordered, so it is not possible to find the record at a
  13 particular index.
  14 </para>
  15 <para>
  16 Note that #GRelation tables are currently limited to 2 fields.
  17 </para>
  18 <para>
  19 To create a GRelation, use g_relation_new().
  20 </para>
  21 <para>
  22 To specify which fields should be indexed, use g_relation_index().
  23 Note that this must be called before any tuples are added to the #GRelation.
  24 </para>
  25 <para>
  26 To add records to a #GRelation use g_relation_insert().
  27 </para>
  28 <para>
  29 To determine if a given record appears in a #GRelation, use
  30 g_relation_exists(). Note that fields are compared directly, so pointers
  31 must point to the exact same position (i.e. different copies of the same
  32 string will not match.)
  33 </para>
  34 <para>
  35 To count the number of records which have a particular value in a given
  36 field, use g_relation_count().
  37 </para>
  38 <para>
  39 To get all the records which have a particular value in a given field,
  40 use g_relation_select(). To access fields of the resulting records,
  41 use g_tuples_index(). To free the resulting records use g_tuples_destroy().
  42 </para>
  43 <para>
  44 To delete all records which have a particular value in a given field,
  45 use g_relation_delete().
  46 </para>
  47 <para>
  48 To destroy the #GRelation, use g_relation_destroy().
  49 </para>
  50 <para>
  51 To help debug #GRelation objects, use g_relation_print().
  52 </para>
  53
  54 <!-- ##### SECTION See_Also ##### -->
  55 <para>
  56
  57 </para>
  58
  59 <!-- ##### SECTION Stability_Level ##### -->
  60
  61
  62 <!-- ##### STRUCT GRelation ##### -->
  63 <para>
  64 The #GRelation struct is an opaque data structure to represent a
  65 <link linkend="glib-Relations-and-Tuples">Relation</link>.
  66 It should only be accessed via the following functions.
  67 </para>
  68
  69
  70 <!-- ##### FUNCTION g_relation_new ##### -->
  71 <para>
  72 Creates a new #GRelation with the given number of fields.
  73 Note that currently the number of fields must be 2.
  74 </para>
  75
  76 @fields: the number of fields.
  77 @Returns: a new #GRelation.
  78
  79
  80 <!-- ##### FUNCTION g_relation_index ##### -->
  81 <para>
  82 Creates an index on the given field.
  83 Note that this must be called before any records are added to the #GRelation.
  84 </para>
  85
  86 @relation: a #GRelation.
  87 @field: the field to index, counting from 0.
  88 @hash_func: a function to produce a hash value from the field data.
  89 @key_equal_func: a function to compare two values of the given field.
  90
  91
  92 <!-- ##### FUNCTION g_relation_insert ##### -->
  93 <para>
  94 Inserts a record into a #GRelation.
  95 </para>
  96
  97 @relation: a #GRelation.
  98 @Varargs: the fields of the record to add. These must match the number of
  99 fields in the #GRelation, and of type #gpointer or #gconstpointer.
 100
 101
 102 <!-- ##### FUNCTION g_relation_exists ##### -->
 103 <para>
 104 Returns %TRUE if a record with the given values exists in a #GRelation.
 105 Note that the values are compared directly, so that, for example, two
 106 copies of the same string will not match.
 107 </para>
 108
 109 @relation: a #GRelation.
 110 @Varargs: the fields of the record to compare. The number must match the
 111 number of fields in the #GRelation.
 112 @Returns: %TRUE if a record matches.
 113
 114
 115 <!-- ##### FUNCTION g_relation_count ##### -->
 116 <para>
 117 Returns the number of tuples in a #GRelation that have the given value
 118 in the given field.
 119 </para>
 120
 121 @relation: a #GRelation.
 122 @key: the value to compare with.
 123 @field: the field of each record to match.
 124 @Returns: the number of matches.
 125
 126
 127 <!-- ##### FUNCTION g_relation_select ##### -->
 128 <para>
 129 Returns all of the tuples which have the given key in the given field.
 130 Use g_tuples_index() to access the returned records.
 131 The returned records should be freed with g_tuples_destroy().
 132 </para>
 133
 134 @relation: a #GRelation.
 135 @key: the value to compare with.
 136 @field: the field of each record to match.
 137 @Returns: the records (tuples) that matched.
 138
 139
 140 <!-- ##### FUNCTION g_relation_delete ##### -->
 141 <para>
 142 Deletes any records from a #GRelation that have the given key value in
 143 the given field.
 144 </para>
 145
 146 @relation: a #GRelation.
 147 @key: the value to compare with.
 148 @field: the field of each record to match.
 149 @Returns: the number of records deleted.
 150
 151
 152 <!-- ##### FUNCTION g_relation_destroy ##### -->
 153 <para>
 154 Destroys the #GRelation, freeing all memory allocated.
 155 However, it does not free memory allocated for the
 156 tuple data, so you should free that first if appropriate.
 157 </para>
 158
 159 @relation: a #GRelation.
 160
 161
 162 <!-- ##### FUNCTION g_relation_print ##### -->
 163 <para>
 164 Outputs information about all records in a #GRelation, as well as the indexes.
 165 It is for debugging.
 166 </para>
 167
 168 @relation: a #GRelation.
 169
 170
 171 <!-- ##### STRUCT GTuples ##### -->
 172 <para>
 173 The #GTuples struct is used to return records (or tuples) from the
 174 #GRelation by g_relation_select().
 175 It only contains one public member - the number of records that matched.
 176 To access the matched records, you must use g_tuples_index().
 177 </para>
 178
 179 @len: the number of records that matched.
 180
 181 <!-- ##### FUNCTION g_tuples_destroy ##### -->
 182 <para>
 183 Frees the records which were returned by g_relation_select().
 184 This should always be called after g_relation_select() when you are
 185 finished with the records.
 186 The records are not removed from the #GRelation.
 187 </para>
 188
 189 @tuples: the tuple data to free.
 190
 191
 192 <!-- ##### FUNCTION g_tuples_index ##### -->
 193 <para>
 194 Gets a field from the records returned by g_relation_select().
 195 It returns the given field of the record at the given index.
 196 The returned value should not be changed.
 197 </para>
 198
 199 @tuples: the tuple data, returned by g_relation_select().
 200 @index_: the index of the record.
 201 @field: the field to return.
 202 @Returns: the field of the record.
 203
 204