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 <!-- ##### STRUCT GRelation ##### -->
  60 <para>
  61 The #GRelation struct is an opaque data structure to represent a
  62 <link linkend="glib-Relations-and-Tuples">Relation</link>.
  63 It should only be accessed via the following functions.
  64 </para>
  65
  66
  67 <!-- ##### FUNCTION g_relation_new ##### -->
  68 <para>
  69 Creates a new #GRelation with the given number of fields.
  70 Note that currently the number of fields must be 2.
  71 </para>
  72
  73 @fields: the number of fields.
  74 @Returns: a new #GRelation.
  75
  76
  77 <!-- ##### FUNCTION g_relation_index ##### -->
  78 <para>
  79 Creates an index on the given field.
  80 Note that this must be called before any records are added to the #GRelation.
  81 </para>
  82
  83 @relation: a #GRelation.
  84 @field: the field to index, counting from 0.
  85 @hash_func: a function to produce a hash value from the field data.
  86 @key_equal_func: a function to compare two values of the given field.
  87 <!-- # Unused Parameters # -->
  88 @key_compare_func:
  89
  90
  91 <!-- ##### FUNCTION g_relation_insert ##### -->
  92 <para>
  93 Inserts a record into a #GRelation.
  94 </para>
  95
  96 @relation: a #GRelation.
  97 @Varargs: the fields of the record to add. This must match the number of
  98 fields in the #GRelation.
  99
 100
 101 <!-- ##### FUNCTION g_relation_exists ##### -->
 102 <para>
 103 Returns TRUE if a record with the given values exists in a #GRelation.
 104 Note that the values are compared directly, so that, for example, two
 105 copies of the same string will not match.
 106 </para>
 107
 108 @relation: a #GRelation.
 109 @Varargs: the fields of the record to compare. The number must match the
 110 number of fields in the #GRelation.
 111 @Returns: TRUE if a record matches.
 112
 113
 114 <!-- ##### FUNCTION g_relation_count ##### -->
 115 <para>
 116 Returns the number of tuples in a #GRelation that have the given value
 117 in the given field.
 118 </para>
 119
 120 @relation: a #GRelation.
 121 @key: the value to compare with.
 122 @field: the field of each record to match.
 123 @Returns: the number of matches.
 124
 125
 126 <!-- ##### FUNCTION g_relation_select ##### -->
 127 <para>
 128 Returns all of the tuples which have the given key in the given field.
 129 Use g_tuples_index() to access the returned records.
 130 The returned records should be freed with g_tuples_destroy().
 131 </para>
 132
 133 @relation: a #GRelation.
 134 @key: the value to compare with.
 135 @field: the field of each record to match.
 136 @Returns: the records (tuples) that matched.
 137
 138
 139 <!-- ##### FUNCTION g_relation_delete ##### -->
 140 <para>
 141 Deletes any records from a GRelation that have the given key value in
 142 the given field.
 143 </para>
 144
 145 @relation: a #GRelation.
 146 @key: the value to compare with.
 147 @field: the field of each record to match.
 148 @Returns: the number of records deleted.
 149
 150
 151 <!-- ##### FUNCTION g_relation_destroy ##### -->
 152 <para>
 153 Destroys the #GRelation, freeing all memory allocated.
 154 However, it does not free memory allocated for the
 155 tuple data, so you should free that first if appropriate.
 156 </para>
 157
 158 @relation: a #GRelation.
 159
 160
 161 <!-- ##### FUNCTION g_relation_print ##### -->
 162 <para>
 163 Outputs information about all records in a #GRelation, as well as the indexes.
 164 It is for debugging.
 165 </para>
 166
 167 @relation: a #GRelation.
 168
 169
 170 <!-- ##### STRUCT GTuples ##### -->
 171 <para>
 172 The #GTuples struct is used to return records (or tuples) from the
 173 #GRelation by g_relation_select().
 174 It only contains one public member - the number of records that matched.
 175 To access the matched records, you must use g_tuples_index().
 176 </para>
 177
 178 @len:
 179
 180 <!-- ##### FUNCTION g_tuples_destroy ##### -->
 181 <para>
 182 Frees the records which were returned by g_relation_select().
 183 This should always be called after g_relation_select() when you are
 184 finished with the records.
 185 The records are not removed from the #GRelation.
 186 </para>
 187
 188 @tuples: the tuple data to free.
 189
 190
 191 <!-- ##### FUNCTION g_tuples_index ##### -->
 192 <para>
 193 Gets a field from the records returned by g_relation_select().
 194 It returns the given field of the record at the given index.
 195 The returned value should not be changed.
 196 </para>
 197
 198 @tuples: the tuple data, returned by g_relation_select().
 199 @index: the index of the record.
 200 @field: the field to return.
 201 @Returns: the field of the record.
 202
 203