## Relations and Tuples

Relations and Tuples — tables of data which can be indexed on any number of fields

## Functions

GRelation * | g_relation_new ()
void | g_relation_index ()
void | g_relation_insert ()
gboolean | g_relation_exists ()
gint | g_relation_count ()
GTuples * | g_relation_select ()
gint | g_relation_delete ()
void | g_relation_destroy ()
void | g_relation_print ()
void | g_tuples_destroy ()
gpointer | g_tuples_index ()

## Types and Values

| GRelation
struct | GTuples

## Includes

    #include <gmodule.h>

## Description

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.

Note that GRelation tables are currently limited to 2 fields.

To create a GRelation, use `g_relation_new()`.

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.

To add records to a GRelation use `g_relation_insert()`.

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.)

To count the number of records which have a particular value in a given field, use `g_relation_count()`.

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()`.

To delete all records which have a particular value in a given field, use `g_relation_delete()`.

To destroy the GRelation, use `g_relation_destroy()`.

To help debug GRelation objects, use `g_relation_print()`.

GRelation has been marked as deprecated, since this API has never been fully implemented, is not very actively maintained and rarely used.

## Functions

### g_relation_new ()

    GRelation *
    g_relation_new (gint fields);

`g_relation_new` has been deprecated since version 2.26 and should not be used in newly-written code.

Rarely used API

Creates a new GRelation with the given number of fields. Note that currently the number of fields must be 2.

#### Parameters

fields | the number of fields. |

#### Returns

a new GRelation.

### g_relation_index ()

    void
    g_relation_index (GRelation *relation,
                      gint field,
                      GHashFunc hash_func,
                      GEqualFunc key_equal_func);

`g_relation_index` has been deprecated since version 2.26 and should not be used in newly-written code.

Rarely used API

Creates an index on the given field. Note that this must be called before any records are added to the GRelation.

#### Parameters

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

### g_relation_insert ()

    void
    g_relation_insert (GRelation *relation,
                       ...);

`g_relation_insert` has been deprecated since version 2.26 and should not be used in newly-written code.

Rarely used API

Inserts a record into a GRelation.

#### Parameters

relation | a GRelation. |
... | the fields of the record to add. These must match the number of fields in the GRelation, and of type gpointer or gconstpointer. |

### g_relation_exists ()

    gboolean
    g_relation_exists (GRelation *relation,
                       ...);

`g_relation_exists` has been deprecated since version 2.26 and should not be used in newly-written code.

Rarely used API

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.

#### Parameters

relation | a GRelation. |
... | the fields of the record to compare. The number must match the number of fields in the GRelation. |

#### Returns

`TRUE` if a record matches.

### g_relation_count ()

    gint
    g_relation_count (GRelation *relation,
                      gconstpointer key,
                      gint field);

`g_relation_count` has been deprecated since version 2.26 and should not be used in newly-written code.

Rarely used API

Returns the number of tuples in a GRelation that have the given value in the given field.

#### Parameters

relation | a GRelation. |
key | the value to compare with. |
field | the field of each record to match. |

#### Returns

the number of matches.

### g_relation_select ()

    GTuples *
    g_relation_select (GRelation *relation,
                       gconstpointer key,
                       gint field);

`g_relation_select` has been deprecated since version 2.26 and should not be used in newly-written code.

Rarely used API

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()`.

#### Parameters

relation | a GRelation. |
key | the value to compare with. |
field | the field of each record to match. |

#### Returns

the records (tuples) that matched.

### g_relation_delete ()

    gint
    g_relation_delete (GRelation *relation,
                       gconstpointer key,
                       gint field);

`g_relation_delete` has been deprecated since version 2.26 and should not be used in newly-written code.

Rarely used API

Deletes any records from a GRelation that have the given key value in the given field.

#### Parameters

relation | a GRelation. |
key | the value to compare with. |
field | the field of each record to match. |

#### Returns

the number of records deleted.

### g_relation_destroy ()

    void
    g_relation_destroy (GRelation *relation);

`g_relation_destroy` has been deprecated since version 2.26 and should not be used in newly-written code.

Rarely used API

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.

#### Parameters

relation | a GRelation. |

### g_relation_print ()

    void
    g_relation_print (GRelation *relation);

`g_relation_print` has been deprecated since version 2.26 and should not be used in newly-written code.

Rarely used API

Outputs information about all records in a GRelation, as well as the indexes. It is for debugging.

#### Parameters

relation | a GRelation. |

### g_tuples_destroy ()

    void
    g_tuples_destroy (GTuples *tuples);

`g_tuples_destroy` has been deprecated since version 2.26 and should not be used in newly-written code.

Rarely used API

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.

#### Parameters

tuples | the tuple data to free. |

### g_tuples_index ()

    gpointer
    g_tuples_index (GTuples *tuples,
                    gint index_,
                    gint field);

`g_tuples_index` has been deprecated since version 2.26 and should not be used in newly-written code.

Rarely used API

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.

#### Parameters

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.

## Types and Values

### GRelation

    typedef struct _GRelation GRelation;

The GRelation struct is an opaque data structure to represent a Relation. It should only be accessed via the following functions.

### struct GTuples

    struct GTuples {
      guint len;
    };

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()`.

#### Members

guint `len`; | the number of records that matched. |