glib/docs/reference/glib/tmpl/relations.sgml

<!-- ##### 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. These must match the number of
fields in the #GRelation, and of type #gpointer or #gconstpointer.


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