1
1
<refentry id="gobject-Generic-values">
3
<refentrytitle role="top_of_page">Generic Values</refentrytitle>
3
<refentrytitle role="top_of_page" id="gobject-Generic-values.top_of_page">Generic Values</refentrytitle>
4
4
<manvolnum>3</manvolnum>
5
5
<refmiscinfo>GOBJECT Library</refmiscinfo>
11
11
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
14
<refsynopsisdiv role="synopsis">
14
<refsynopsisdiv id="gobject-Generic-values.synopsis" role="synopsis">
15
15
<title role="synopsis.title">Synopsis</title>
19
19
#include <glib-object.h>
22
21
#define <link linkend="G-VALUE-HOLDS:CAPS">G_VALUE_HOLDS</link> (value,type)
23
22
#define <link linkend="G-VALUE-TYPE:CAPS">G_VALUE_TYPE</link> (value)
24
23
#define <link linkend="G-VALUE-TYPE-NAME:CAPS">G_VALUE_TYPE_NAME</link> (value)
82
<refsect1 role="details">
80
<refsect1 id="gobject-Generic-values.details" role="details">
83
81
<title role="details.title">Details</title>
85
<title><anchor id="G-VALUE-HOLDS:CAPS" role="macro"/>G_VALUE_HOLDS()</title>
86
<indexterm><primary>G_VALUE_HOLDS</primary></indexterm><programlisting>#define G_VALUE_HOLDS(value,type) (G_TYPE_CHECK_VALUE_TYPE ((value), (type)))
82
<refsect2 id="G-VALUE-HOLDS:CAPS" role="macro">
83
<title>G_VALUE_HOLDS()</title>
84
<indexterm zone="G-VALUE-HOLDS:CAPS"><primary>G_VALUE_HOLDS</primary></indexterm><programlisting>#define G_VALUE_HOLDS(value,type) (G_TYPE_CHECK_VALUE_TYPE ((value), (type)))
89
87
Returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>value</parameter> holds (or contains) a value of <parameter>type</parameter>.
100
98
</simpara></listitem></varlistentry>
101
99
</variablelist></refsect2>
103
<title><anchor id="G-VALUE-TYPE:CAPS" role="macro"/>G_VALUE_TYPE()</title>
104
<indexterm><primary>G_VALUE_TYPE</primary></indexterm><programlisting>#define G_VALUE_TYPE(value) (((GValue*) (value))->g_type)
100
<refsect2 id="G-VALUE-TYPE:CAPS" role="macro">
101
<title>G_VALUE_TYPE()</title>
102
<indexterm zone="G-VALUE-TYPE:CAPS"><primary>G_VALUE_TYPE</primary></indexterm><programlisting>#define G_VALUE_TYPE(value) (((GValue*) (value))->g_type)
105
103
</programlisting>
107
105
Returns the type identifier of <parameter>value</parameter>.
113
111
</simpara></listitem></varlistentry>
114
112
</variablelist></refsect2>
116
<title><anchor id="G-VALUE-TYPE-NAME:CAPS" role="macro"/>G_VALUE_TYPE_NAME()</title>
117
<indexterm><primary>G_VALUE_TYPE_NAME</primary></indexterm><programlisting>#define G_VALUE_TYPE_NAME(value) (g_type_name (G_VALUE_TYPE (value)))
113
<refsect2 id="G-VALUE-TYPE-NAME:CAPS" role="macro">
114
<title>G_VALUE_TYPE_NAME()</title>
115
<indexterm zone="G-VALUE-TYPE-NAME:CAPS"><primary>G_VALUE_TYPE_NAME</primary></indexterm><programlisting>#define G_VALUE_TYPE_NAME(value) (g_type_name (G_VALUE_TYPE (value)))
118
116
</programlisting>
120
118
Returns the type name of <parameter>value</parameter>.
126
124
</simpara></listitem></varlistentry>
127
125
</variablelist></refsect2>
129
<title><anchor id="G-TYPE-IS-VALUE:CAPS" role="macro"/>G_TYPE_IS_VALUE()</title>
130
<indexterm><primary>G_TYPE_IS_VALUE</primary></indexterm><programlisting>#define G_TYPE_IS_VALUE(type) (g_type_check_is_value_type (type))
126
<refsect2 id="G-TYPE-IS-VALUE:CAPS" role="macro">
127
<title>G_TYPE_IS_VALUE()</title>
128
<indexterm zone="G-TYPE-IS-VALUE:CAPS"><primary>G_TYPE_IS_VALUE</primary></indexterm><programlisting>#define G_TYPE_IS_VALUE(type) (g_type_check_is_value_type (type))
131
129
</programlisting>
133
131
Return whether the passed in type ID can be used for <link linkend="g-value-init"><function>g_value_init()</function></link>.
143
141
</simpara></listitem></varlistentry>
144
142
</variablelist></refsect2>
146
<title><anchor id="G-TYPE-IS-VALUE-ABSTRACT:CAPS" role="macro"/>G_TYPE_IS_VALUE_ABSTRACT()</title>
147
<indexterm><primary>G_TYPE_IS_VALUE_ABSTRACT</primary></indexterm><programlisting>#define G_TYPE_IS_VALUE_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
143
<refsect2 id="G-TYPE-IS-VALUE-ABSTRACT:CAPS" role="macro">
144
<title>G_TYPE_IS_VALUE_ABSTRACT()</title>
145
<indexterm zone="G-TYPE-IS-VALUE-ABSTRACT:CAPS"><primary>G_TYPE_IS_VALUE_ABSTRACT</primary></indexterm><programlisting>#define G_TYPE_IS_VALUE_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
148
146
</programlisting>
150
148
Returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>type</parameter> is an abstract value type. An abstract value type
158
156
</simpara></listitem></varlistentry>
159
157
</variablelist></refsect2>
161
<title><anchor id="G-IS-VALUE:CAPS" role="macro"/>G_IS_VALUE()</title>
162
<indexterm><primary>G_IS_VALUE</primary></indexterm><programlisting>#define G_IS_VALUE(value) (G_TYPE_CHECK_VALUE (value))
158
<refsect2 id="G-IS-VALUE:CAPS" role="macro">
159
<title>G_IS_VALUE()</title>
160
<indexterm zone="G-IS-VALUE:CAPS"><primary>G_IS_VALUE</primary></indexterm><programlisting>#define G_IS_VALUE(value) (G_TYPE_CHECK_VALUE (value))
163
161
</programlisting>
165
163
Returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>value</parameter> is a valid and initialized <link linkend="GValue"><type>GValue</type></link> structure.
171
169
</simpara></listitem></varlistentry>
172
170
</variablelist></refsect2>
174
<title><anchor id="GValue" role="struct"/>GValue</title>
175
<indexterm><primary>GValue</primary></indexterm><programlisting>typedef struct {
171
<refsect2 id="GValue" role="struct">
172
<title>GValue</title>
173
<indexterm zone="GValue"><primary>GValue</primary></indexterm><programlisting>typedef struct {
177
175
</programlisting>
185
183
within the 2 element <parameter>data</parameter> union, and the <parameter>g_type</parameter> member should
186
184
only be accessed through the <link linkend="G-VALUE-TYPE:CAPS"><function>G_VALUE_TYPE()</function></link> macro.
187
185
</para></refsect2>
189
<title><anchor id="G-TYPE-VALUE:CAPS" role="macro"/>G_TYPE_VALUE</title>
190
<indexterm><primary>G_TYPE_VALUE</primary></indexterm><programlisting>#define G_TYPE_VALUE (g_value_get_type ())
186
<refsect2 id="G-TYPE-VALUE:CAPS" role="macro">
187
<title>G_TYPE_VALUE</title>
188
<indexterm zone="G-TYPE-VALUE:CAPS"><primary>G_TYPE_VALUE</primary></indexterm><programlisting>#define G_TYPE_VALUE (g_value_get_type ())
191
189
</programlisting>
193
191
Returns the type ID of the "GValue" type which is a boxed type,
194
192
used to pass around pointers to GValues.
195
193
</para></refsect2>
197
<title><anchor id="G-TYPE-VALUE-ARRAY:CAPS" role="macro"/>G_TYPE_VALUE_ARRAY</title>
198
<indexterm><primary>G_TYPE_VALUE_ARRAY</primary></indexterm><programlisting>#define G_TYPE_VALUE_ARRAY (g_value_array_get_type ())
194
<refsect2 id="G-TYPE-VALUE-ARRAY:CAPS" role="macro">
195
<title>G_TYPE_VALUE_ARRAY</title>
196
<indexterm zone="G-TYPE-VALUE-ARRAY:CAPS"><primary>G_TYPE_VALUE_ARRAY</primary></indexterm><programlisting>#define G_TYPE_VALUE_ARRAY (g_value_array_get_type ())
199
197
</programlisting>
201
199
Returns the type ID of the "GValueArray" type which is a boxed type,
202
200
used to pass around pointers to GValueArrays.
203
201
</para></refsect2>
205
<title><anchor id="g-value-init" role="function"/>g_value_init ()</title>
206
<indexterm><primary>g_value_init</primary></indexterm><programlisting><link linkend="GValue">GValue</link>* g_value_init (<link linkend="GValue">GValue</link> *value,
202
<refsect2 id="g-value-init" role="function">
203
<title>g_value_init ()</title>
204
<indexterm zone="g-value-init"><primary>g_value_init</primary></indexterm><programlisting><link linkend="GValue">GValue</link>* g_value_init (<link linkend="GValue">GValue</link> *value,
207
205
<link linkend="GType">GType</link> g_type);</programlisting>
209
207
Initializes <parameter>value</parameter> with the default value of <parameter>type</parameter>.
220
218
</simpara></listitem></varlistentry>
221
219
</variablelist></refsect2>
223
<title><anchor id="g-value-copy" role="function"/>g_value_copy ()</title>
224
<indexterm><primary>g_value_copy</primary></indexterm><programlisting><link linkend="void">void</link> g_value_copy (const <link linkend="GValue">GValue</link> *src_value,
220
<refsect2 id="g-value-copy" role="function">
221
<title>g_value_copy ()</title>
222
<indexterm zone="g-value-copy"><primary>g_value_copy</primary></indexterm><programlisting><link linkend="void">void</link> g_value_copy (const <link linkend="GValue">GValue</link> *src_value,
225
223
<link linkend="GValue">GValue</link> *dest_value);</programlisting>
227
225
Copies the value of <parameter>src_value</parameter> into <parameter>dest_value</parameter>.
236
234
</simpara></listitem></varlistentry>
237
235
</variablelist></refsect2>
239
<title><anchor id="g-value-reset" role="function"/>g_value_reset ()</title>
240
<indexterm><primary>g_value_reset</primary></indexterm><programlisting><link linkend="GValue">GValue</link>* g_value_reset (<link linkend="GValue">GValue</link> *value);</programlisting>
236
<refsect2 id="g-value-reset" role="function">
237
<title>g_value_reset ()</title>
238
<indexterm zone="g-value-reset"><primary>g_value_reset</primary></indexterm><programlisting><link linkend="GValue">GValue</link>* g_value_reset (<link linkend="GValue">GValue</link> *value);</programlisting>
242
240
Clears the current value in <parameter>value</parameter> and resets it to the default value
243
241
(as if the value had just been initialized).
251
249
</simpara></listitem></varlistentry>
252
250
</variablelist></refsect2>
254
<title><anchor id="g-value-unset" role="function"/>g_value_unset ()</title>
255
<indexterm><primary>g_value_unset</primary></indexterm><programlisting><link linkend="void">void</link> g_value_unset (<link linkend="GValue">GValue</link> *value);</programlisting>
251
<refsect2 id="g-value-unset" role="function">
252
<title>g_value_unset ()</title>
253
<indexterm zone="g-value-unset"><primary>g_value_unset</primary></indexterm><programlisting><link linkend="void">void</link> g_value_unset (<link linkend="GValue">GValue</link> *value);</programlisting>
257
255
Clears the current value in <parameter>value</parameter> and "unsets" the type,
258
256
this releases all resources associated with this GValue.
266
264
</simpara></listitem></varlistentry>
267
265
</variablelist></refsect2>
269
<title><anchor id="g-value-set-instance" role="function"/>g_value_set_instance ()</title>
270
<indexterm><primary>g_value_set_instance</primary></indexterm><programlisting><link linkend="void">void</link> g_value_set_instance (<link linkend="GValue">GValue</link> *value,
266
<refsect2 id="g-value-set-instance" role="function">
267
<title>g_value_set_instance ()</title>
268
<indexterm zone="g-value-set-instance"><primary>g_value_set_instance</primary></indexterm><programlisting><link linkend="void">void</link> g_value_set_instance (<link linkend="GValue">GValue</link> *value,
271
269
<link linkend="gpointer">gpointer</link> instance);</programlisting>
273
271
Sets <parameter>value</parameter> from an instantiatable type via the
283
281
</simpara></listitem></varlistentry>
284
282
</variablelist></refsect2>
286
<title><anchor id="g-value-fits-pointer" role="function"/>g_value_fits_pointer ()</title>
287
<indexterm><primary>g_value_fits_pointer</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_value_fits_pointer (const <link linkend="GValue">GValue</link> *value);</programlisting>
283
<refsect2 id="g-value-fits-pointer" role="function">
284
<title>g_value_fits_pointer ()</title>
285
<indexterm zone="g-value-fits-pointer"><primary>g_value_fits_pointer</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_value_fits_pointer (const <link linkend="GValue">GValue</link> *value);</programlisting>
289
287
Determines if <parameter>value</parameter> will fit inside the size of a pointer value.
290
288
This is an internal function introduced mainly for C marshallers.
298
296
</simpara></listitem></varlistentry>
299
297
</variablelist></refsect2>
301
<title><anchor id="g-value-peek-pointer" role="function"/>g_value_peek_pointer ()</title>
302
<indexterm><primary>g_value_peek_pointer</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_value_peek_pointer (const <link linkend="GValue">GValue</link> *value);</programlisting>
298
<refsect2 id="g-value-peek-pointer" role="function">
299
<title>g_value_peek_pointer ()</title>
300
<indexterm zone="g-value-peek-pointer"><primary>g_value_peek_pointer</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_value_peek_pointer (const <link linkend="GValue">GValue</link> *value);</programlisting>
304
302
Return the value contents as pointer. This function asserts that
305
303
<link linkend="g-value-fits-pointer"><function>g_value_fits_pointer()</function></link> returned <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> for the passed in value.
314
312
</simpara></listitem></varlistentry>
315
313
</variablelist></refsect2>
317
<title><anchor id="g-value-type-compatible" role="function"/>g_value_type_compatible ()</title>
318
<indexterm><primary>g_value_type_compatible</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_value_type_compatible (<link linkend="GType">GType</link> src_type,
314
<refsect2 id="g-value-type-compatible" role="function">
315
<title>g_value_type_compatible ()</title>
316
<indexterm zone="g-value-type-compatible"><primary>g_value_type_compatible</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_value_type_compatible (<link linkend="GType">GType</link> src_type,
319
317
<link linkend="GType">GType</link> dest_type);</programlisting>
321
319
Returns whether a <link linkend="GValue"><type>GValue</type></link> of type <parameter>src_type</parameter> can be copied into
333
331
</simpara></listitem></varlistentry>
334
332
</variablelist></refsect2>
336
<title><anchor id="g-value-type-transformable" role="function"/>g_value_type_transformable ()</title>
337
<indexterm><primary>g_value_type_transformable</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_value_type_transformable (<link linkend="GType">GType</link> src_type,
333
<refsect2 id="g-value-type-transformable" role="function">
334
<title>g_value_type_transformable ()</title>
335
<indexterm zone="g-value-type-transformable"><primary>g_value_type_transformable</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_value_type_transformable (<link linkend="GType">GType</link> src_type,
338
336
<link linkend="GType">GType</link> dest_type);</programlisting>
340
338
Check whether <link linkend="g-value-transform"><function>g_value_transform()</function></link> is able to transform values
352
350
</simpara></listitem></varlistentry>
353
351
</variablelist></refsect2>
355
<title><anchor id="g-value-transform" role="function"/>g_value_transform ()</title>
356
<indexterm><primary>g_value_transform</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_value_transform (const <link linkend="GValue">GValue</link> *src_value,
352
<refsect2 id="g-value-transform" role="function">
353
<title>g_value_transform ()</title>
354
<indexterm zone="g-value-transform"><primary>g_value_transform</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_value_transform (const <link linkend="GValue">GValue</link> *src_value,
357
355
<link linkend="GValue">GValue</link> *dest_value);</programlisting>
359
357
Tries to cast the contents of <parameter>src_value</parameter> into a type appropriate
377
375
</simpara></listitem></varlistentry>
378
376
</variablelist></refsect2>
380
<title><anchor id="GValueTransform" role="function"/>GValueTransform ()</title>
381
<indexterm><primary>GValueTransform</primary></indexterm><programlisting><link linkend="void">void</link> (*GValueTransform) (const <link linkend="GValue">GValue</link> *src_value,
377
<refsect2 id="GValueTransform" role="function">
378
<title>GValueTransform ()</title>
379
<indexterm zone="GValueTransform"><primary>GValueTransform</primary></indexterm><programlisting><link linkend="void">void</link> (*GValueTransform) (const <link linkend="GValue">GValue</link> *src_value,
382
380
<link linkend="GValue">GValue</link> *dest_value);</programlisting>
384
382
The type of value transformation functions which can be registered with
394
392
</simpara></listitem></varlistentry>
395
393
</variablelist></refsect2>
397
<title><anchor id="g-value-register-transform-func" role="function"/>g_value_register_transform_func ()</title>
398
<indexterm><primary>g_value_register_transform_func</primary></indexterm><programlisting><link linkend="void">void</link> g_value_register_transform_func (<link linkend="GType">GType</link> src_type,
394
<refsect2 id="g-value-register-transform-func" role="function">
395
<title>g_value_register_transform_func ()</title>
396
<indexterm zone="g-value-register-transform-func"><primary>g_value_register_transform_func</primary></indexterm><programlisting><link linkend="void">void</link> g_value_register_transform_func (<link linkend="GType">GType</link> src_type,
399
397
<link linkend="GType">GType</link> dest_type,
400
398
<link linkend="GValueTransform">GValueTransform</link> transform_func);</programlisting>
417
415
</simpara></listitem></varlistentry>
418
416
</variablelist></refsect2>
420
<title><anchor id="g-strdup-value-contents" role="function"/>g_strdup_value_contents ()</title>
421
<indexterm><primary>g_strdup_value_contents</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strdup_value_contents (const <link linkend="GValue">GValue</link> *value);</programlisting>
417
<refsect2 id="g-strdup-value-contents" role="function">
418
<title>g_strdup_value_contents ()</title>
419
<indexterm zone="g-strdup-value-contents"><primary>g_strdup_value_contents</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* g_strdup_value_contents (const <link linkend="GValue">GValue</link> *value);</programlisting>
423
421
Return a newly allocated string, which describes the contents of a <link linkend="GValue"><type>GValue</type></link>.
424
422
The main purpose of this function is to describe <link linkend="GValue"><type>GValue</type></link> contents for