1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
<!-- ##### 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.
|
