/src/wrappers/glib/library/data_types/glib_relations.e

  1indexing
  2	copyright: "(C) 2005 Paolo Redaelli "
  3	license: "LGPL v2 or later"
  4	date: "$Date:$"
  5	revision: "$REvision:$"
  6
  7class GLIB_RELATIONS
  8	-- Prev 	Up 	Home 	GLib Reference Manual 	Next
  9-- Top  |  Description
 10-- Relations and Tuples
 11
 12-- Relations and Tuples %G —%@ tables of data which can be indexed on any number of fields.
 13	
 14-- Synopsis
 15
 16-- #include <glib.h>
 17
 18
 19--             GRelation;
 20-- GRelation*  g_relation_new                  (gint fields);
 21-- void        g_relation_index                (GRelation *relation,
 22--                                              gint field,
 23--                                              GHashFunc hash_func,
 24--                                              GEqualFunc key_equal_func);
 25-- void        g_relation_insert               (GRelation *relation,
 26--                                              ...);
 27-- gboolean    g_relation_exists               (GRelation *relation,
 28--                                              ...);
 29-- gint        g_relation_count                (GRelation *relation,
 30--                                              gconstpointer key,
 31--                                              gint field);
 32-- GTuples*    g_relation_select               (GRelation *relation,
 33--                                              gconstpointer key,
 34--                                              gint field);
 35-- gint        g_relation_delete               (GRelation *relation,
 36--                                              gconstpointer key,
 37--                                              gint field);
 38-- void        g_relation_destroy              (GRelation *relation);
 39
 40-- void        g_relation_print                (GRelation *relation);
 41
 42--             GTuples;
 43-- void        g_tuples_destroy                (GTuples *tuples);
 44-- gpointer    g_tuples_index                  (GTuples *tuples,
 45--                                              gint index_,
 46--                                              gint field);
 47
 48-- Description
 49
 50-- 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.
 51
 52-- Note that GRelation tables are currently limited to 2 fields.
 53
 54-- To create a GRelation, use g_relation_new().
 55
 56-- 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.
 57
 58-- To add records to a GRelation use g_relation_insert().
 59
 60-- 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.)
 61
 62-- To count the number of records which have a particular value in a given field, use g_relation_count().
 63
 64-- 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().
 65
 66-- To delete all records which have a particular value in a given field, use g_relation_delete().
 67
 68-- To destroy the GRelation, use g_relation_destroy().
 69
 70-- To help debug GRelation objects, use g_relation_print().
 71-- Details
 72-- GRelation
 73
 74-- typedef struct _GRelation GRelation;
 75
 76-- The GRelation struct is an opaque data structure to represent a Relation. It should only be accessed via the following functions.
 77-- g_relation_new ()
 78
 79-- GRelation*  g_relation_new                  (gint fields);
 80
 81-- Creates a new GRelation with the given number of fields. Note that currently the number of fields must be 2.
 82-- fields : 	the number of fields.
 83-- Returns : 	a new GRelation.
 84-- g_relation_index ()
 85
 86-- void        g_relation_index                (GRelation *relation,
 87--                                              gint field,
 88--                                              GHashFunc hash_func,
 89--                                              GEqualFunc key_equal_func);
 90
 91-- Creates an index on the given field. Note that this must be called before any records are added to the GRelation.
 92-- relation : 	a GRelation.
 93-- field : 	the field to index, counting from 0.
 94-- hash_func : 	a function to produce a hash value from the field data.
 95-- key_equal_func : 	a function to compare two values of the given field.
 96-- g_relation_insert ()
 97
 98-- void        g_relation_insert               (GRelation *relation,
 99--                                              ...);
100
101-- Inserts a record into a GRelation.
102-- relation : 	a GRelation.
103-- ... : 	the fields of the record to add. This must match the number of fields in the GRelation.
104-- g_relation_exists ()
105
106-- gboolean    g_relation_exists               (GRelation *relation,
107--                                              ...);
108
109-- 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.
110-- relation : 	a GRelation.
111-- ... : 	the fields of the record to compare. The number must match the number of fields in the GRelation.
112-- Returns : 	TRUE if a record matches.
113-- g_relation_count ()
114
115-- gint        g_relation_count                (GRelation *relation,
116--                                              gconstpointer key,
117--                                              gint field);
118
119-- Returns the number of tuples in a GRelation that have the given value in the given field.
120-- relation : 	a GRelation.
121-- key : 	the value to compare with.
122-- field : 	the field of each record to match.
123-- Returns : 	the number of matches.
124-- g_relation_select ()
125
126-- GTuples*    g_relation_select               (GRelation *relation,
127--                                              gconstpointer key,
128--                                              gint field);
129
130-- 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().
131-- relation : 	a GRelation.
132-- key : 	the value to compare with.
133-- field : 	the field of each record to match.
134-- Returns : 	the records (tuples) that matched.
135-- g_relation_delete ()
136
137-- gint        g_relation_delete               (GRelation *relation,
138--                                              gconstpointer key,
139--                                              gint field);
140
141-- Deletes any records from a GRelation that have the given key value in the given field.
142-- relation : 	a GRelation.
143-- key : 	the value to compare with.
144-- field : 	the field of each record to match.
145-- Returns : 	the number of records deleted.
146-- g_relation_destroy ()
147
148-- void        g_relation_destroy              (GRelation *relation);
149
150-- 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.
151-- relation : 	a GRelation.
152-- g_relation_print ()
153
154-- void        g_relation_print                (GRelation *relation);
155
156-- Outputs information about all records in a GRelation, as well as the indexes. It is for debugging.
157-- relation : 	a GRelation.
158-- GTuples
159
160-- typedef struct {
161--   guint len;
162-- } GTuples;
163
164-- 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().
165-- guint len; 	the number of records that matched.
166-- g_tuples_destroy ()
167
168-- void        g_tuples_destroy                (GTuples *tuples);
169
170-- 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.
171-- tuples : 	the tuple data to free.
172-- g_tuples_index ()
173
174-- gpointer    g_tuples_index                  (GTuples *tuples,
175--                                              gint index_,
176--                                              gint field);
177
178-- 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.
179-- tuples : 	the tuple data, returned by g_relation_select().
180-- index_ : 	the index of the record.
181-- field : 	the field to return.
182-- Returns : 	the field of the record.
183end