:right-sidebar: True

Relation
===================================================================

.. currentmodule:: gi.repository.GLib





.. deprecated:: 2.26

   Rarely used API


.. class:: Relation(*args, **kwargs)
   :no-contents-entry:






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 :obj:`~gi.repository.GLib.Relation.new`\.

To specify which fields should be indexed, use :obj:`~gi.repository.GLib.Relation.index`\.
Note that this must be called before any tuples are added to the
``GRelation``\.

To add records to a ``GRelation`` use :obj:`~gi.repository.GLib.Relation.insert`\.

To determine if a given record appears in a ``GRelation``\, use
:obj:`~gi.repository.GLib.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 :obj:`~gi.repository.GLib.Relation.count`\.

To get all the records which have a particular value in a given
field, use :obj:`~gi.repository.GLib.Relation.select`\. To access fields of the resulting
records, use :obj:`~gi.repository.GLib.Tuples.index`\. To free the resulting records use
:obj:`~gi.repository.GLib.Tuples.destroy`\.

To delete all records which have a particular value in a given
field, use :obj:`~gi.repository.GLib.Relation.delete`\.

To destroy the ``GRelation``\, use :obj:`~gi.repository.GLib.Relation.destroy`\.

To help debug ``GRelation`` objects, use :obj:`~gi.repository.GLib.Relation.print`\.

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




Methods
-------

.. rst-class:: interim-class

.. class:: Relation
   :no-index:


   .. method:: count(key: ~typing.Any, field: int) -> int

      Returns the number of tuples in a :obj:`~gi.repository.GLib.Relation` that have the given
      value in the given field.





      .. deprecated:: 2.26

         Rarely used API



      :param key: the value to compare with.

      :param field: the field of each record to match.




   .. method:: delete(key: ~typing.Any, field: int) -> int

      Deletes any records from a :obj:`~gi.repository.GLib.Relation` that have the given key value
      in the given field.





      .. deprecated:: 2.26

         Rarely used API



      :param key: the value to compare with.

      :param field: the field of each record to match.




   .. method:: destroy() -> None

      Destroys the :obj:`~gi.repository.GLib.Relation`\, freeing all memory allocated. However, it
      does not free memory allocated for the tuple data, so you should
      free that first if appropriate.





      .. deprecated:: 2.26

         Rarely used API






   .. method:: print_() -> None