Home | History | Annotate | Download | only in tmpl 
      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 
    205