/src/wrappers/glib/library/data_types/glib_tuples.e
Specman e | 183 lines | 7 code | 46 blank | 130 comment | 0 complexity | ea478dc1823a121173f520df699eaa38 MD5 | raw file
1indexing 2 copyright: "(C) 2005 Paolo Redaelli " 3 license: "LGPL v2 or later" 4 date: "$Date:$" 5 revision: "$REvision:$" 6 7class GLIB_TUPLES 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