<!-- ##### SECTION Title ##### --> Relations and Tuples <!-- ##### SECTION Short_Description ##### --> tables of data which can be indexed on any number of fields. <!-- ##### SECTION Long_Description ##### --> <para> A #GRelation is a table of data which can be indexed on any number of fields, rather like simple database tables. A #GRelation contains a number of records, called tuples. Each record contains a number of fields. Records are not ordered, so it is not possible to find the record at a particular index. </para> <para> Note that #GRelation tables are currently limited to 2 fields. </para> <para> To create a GRelation, use g_relation_new(). </para> <para> To specify which fields should be indexed, use g_relation_index(). Note that this must be called before any tuples are added to the #GRelation. </para> <para> To add records to a #GRelation use g_relation_insert(). </para> <para> To determine if a given record appears in a #GRelation, use g_relation_exists(). Note that fields are compared directly, so pointers must point to the exact same position (i.e. different copies of the same string will not match.) </para> <para> To count the number of records which have a particular value in a given field, use g_relation_count(). </para> <para> To get all the records which have a particular value in a given field, use g_relation_select(). To access fields of the resulting records, use g_tuples_index(). To free the resulting records use g_tuples_destroy(). </para> <para> To delete all records which have a particular value in a given field, use g_relation_delete(). </para> <para> To destroy the #GRelation, use g_relation_destroy(). </para> <para> To help debug #GRelation objects, use g_relation_print(). </para> <!-- ##### SECTION See_Also ##### --> <para> </para> <!-- ##### STRUCT GRelation ##### --> <para> The #GRelation struct is an opaque data structure to represent a <link linkend="glib-Relations-and-Tuples">Relation</link>. It should only be accessed via the following functions. </para> <!-- ##### FUNCTION g_relation_new ##### --> <para> Creates a new #GRelation with the given number of fields. Note that currently the number of fields must be 2. </para> @fields: the number of fields. @Returns: a new #GRelation. <!-- ##### FUNCTION g_relation_index ##### --> <para> Creates an index on the given field. Note that this must be called before any records are added to the #GRelation. </para> @relation: a #GRelation. @field: the field to index, counting from 0. @hash_func: a function to produce a hash value from the field data. @key_equal_func: a function to compare two values of the given field. <!-- ##### FUNCTION g_relation_insert ##### --> <para> Inserts a record into a #GRelation. </para> @relation: a #GRelation. @Varargs: the fields of the record to add. This must match the number of fields in the #GRelation. <!-- ##### FUNCTION g_relation_exists ##### --> <para> Returns %TRUE if a record with the given values exists in a #GRelation. Note that the values are compared directly, so that, for example, two copies of the same string will not match. </para> @relation: a #GRelation. @Varargs: the fields of the record to compare. The number must match the number of fields in the #GRelation. @Returns: %TRUE if a record matches. <!-- ##### FUNCTION g_relation_count ##### --> <para> Returns the number of tuples in a #GRelation that have the given value in the given field. </para> @relation: a #GRelation. @key: the value to compare with. @field: the field of each record to match. @Returns: the number of matches. <!-- ##### FUNCTION g_relation_select ##### --> <para> Returns all of the tuples which have the given key in the given field. Use g_tuples_index() to access the returned records. The returned records should be freed with g_tuples_destroy(). </para> @relation: a #GRelation. @key: the value to compare with. @field: the field of each record to match. @Returns: the records (tuples) that matched. <!-- ##### FUNCTION g_relation_delete ##### --> <para> Deletes any records from a #GRelation that have the given key value in the given field. </para> @relation: a #GRelation. @key: the value to compare with. @field: the field of each record to match. @Returns: the number of records deleted. <!-- ##### FUNCTION g_relation_destroy ##### --> <para> Destroys the #GRelation, freeing all memory allocated. However, it does not free memory allocated for the tuple data, so you should free that first if appropriate. </para> @relation: a #GRelation. <!-- ##### FUNCTION g_relation_print ##### --> <para> Outputs information about all records in a #GRelation, as well as the indexes. It is for debugging. </para> @relation: a #GRelation. <!-- ##### STRUCT GTuples ##### --> <para> The #GTuples struct is used to return records (or tuples) from the #GRelation by g_relation_select(). It only contains one public member - the number of records that matched. To access the matched records, you must use g_tuples_index(). </para> @len: the number of records that matched. <!-- ##### FUNCTION g_tuples_destroy ##### --> <para> Frees the records which were returned by g_relation_select(). This should always be called after g_relation_select() when you are finished with the records. The records are not removed from the #GRelation. </para> @tuples: the tuple data to free. <!-- ##### FUNCTION g_tuples_index ##### --> <para> Gets a field from the records returned by g_relation_select(). It returns the given field of the record at the given index. The returned value should not be changed. </para> @tuples: the tuple data, returned by g_relation_select(). @index_: the index of the record. @field: the field to return. @Returns: the field of the record.