| <!-- ##### 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> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### 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. |
| |
| |