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
  88
  89 <!-- ##### FUNCTION g_relation_insert ##### -->
  90 <para>
  91 Inserts a record into a #GRelation.
  92 </para>
  93
  94 @relation: a #GRelation.
  95 @Varargs: the fields of the record to add. This must match the number of
  96 fields in the #GRelation.
  97
  98
  99 <!-- ##### FUNCTION g_relation_exists ##### -->
 100 <para>
 101 Returns %TRUE if a record with the given values exists in a #GRelation.
 102 Note that the values are compared directly, so that, for example, two
 103 copies of the same string will not match.
 104 </para>
 105
 106 @relation: a #GRelation.
 107 @Varargs: the fields of the record to compare. The number must match the
 108 number of fields in the #GRelation.
 109 @Returns: %TRUE if a record matches.
 110
 111
 112 <!-- ##### FUNCTION g_relation_count ##### -->
 113 <para>
 114 Returns the number of tuples in a #GRelation that have the given value
 115 in the given field.
 116 </para>
 117
 118 @relation: a #GRelation.
 119 @key: the value to compare with.
 120 @field: the field of each record to match.
 121 @Returns: the number of matches.
 122
 123
 124 <!-- ##### FUNCTION g_relation_select ##### -->
 125 <para>
 126 Returns all of the tuples which have the given key in the given field.
 127 Use g_tuples_index() to access the returned records.
 128 The returned records should be freed with g_tuples_destroy().
 129 </para>
 130
 131 @relation: a #GRelation.
 132 @key: the value to compare with.
 133 @field: the field of each record to match.
 134 @Returns: the records (tuples) that matched.
 135
 136
 137 <!-- ##### FUNCTION g_relation_delete ##### -->
 138 <para>
 139 Deletes any records from a #GRelation that have the given key value in
 140 the given field.
 141 </para>
 142
 143 @relation: a #GRelation.
 144 @key: the value to compare with.
 145 @field: the field of each record to match.
 146 @Returns: the number of records deleted.
 147
 148
 149 <!-- ##### FUNCTION g_relation_destroy ##### -->
 150 <para>
 151 Destroys the #GRelation, freeing all memory allocated.
 152 However, it does not free memory allocated for the
 153 tuple data, so you should free that first if appropriate.
 154 </para>
 155
 156 @relation: a #GRelation.
 157
 158
 159 <!-- ##### FUNCTION g_relation_print ##### -->
 160 <para>
 161 Outputs information about all records in a #GRelation, as well as the indexes.
 162 It is for debugging.
 163 </para>
 164
 165 @relation: a #GRelation.
 166
 167
 168 <!-- ##### STRUCT GTuples ##### -->
 169 <para>
 170 The #GTuples struct is used to return records (or tuples) from the
 171 #GRelation by g_relation_select().
 172 It only contains one public member - the number of records that matched.
 173 To access the matched records, you must use g_tuples_index().
 174 </para>
 175
 176 @len: the number of records that matched.
 177
 178 <!-- ##### FUNCTION g_tuples_destroy ##### -->
 179 <para>
 180 Frees the records which were returned by g_relation_select().
 181 This should always be called after g_relation_select() when you are
 182 finished with the records.
 183 The records are not removed from the #GRelation.
 184 </para>
 185
 186 @tuples: the tuple data to free.
 187
 188
 189 <!-- ##### FUNCTION g_tuples_index ##### -->
 190 <para>
 191 Gets a field from the records returned by g_relation_select().
 192 It returns the given field of the record at the given index.
 193 The returned value should not be changed.
 194 </para>
 195
 196 @tuples: the tuple data, returned by g_relation_select().
 197 @index_: the index of the record.
 198 @field: the field to return.
 199 @Returns: the field of the record.
 200
 201