1 | /* GObject - GLib Type, Object, Parameter and Signal Library |
2 | * Copyright (C) 1997-1999, 2000-2001 Tim Janik and Red Hat, Inc. |
3 | * |
4 | * This library is free software; you can redistribute it and/or |
5 | * modify it under the terms of the GNU Lesser General Public |
6 | * License as published by the Free Software Foundation; either |
7 | * version 2.1 of the License, or (at your option) any later version. |
8 | * |
9 | * This library is distributed in the hope that it will be useful, |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | * Lesser General Public License for more details. |
13 | * |
14 | * You should have received a copy of the GNU Lesser General |
15 | * Public License along with this library; if not, see <http://www.gnu.org/licenses/>. |
16 | * |
17 | * gvalue.h: generic GValue functions |
18 | */ |
19 | #ifndef __G_VALUE_H__ |
20 | #define __G_VALUE_H__ |
21 | |
22 | #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION) |
23 | #error "Only <glib-object.h> can be included directly." |
24 | #endif |
25 | |
26 | #include <gobject/gtype.h> |
27 | |
28 | G_BEGIN_DECLS |
29 | |
30 | /* --- type macros --- */ |
31 | /** |
32 | * G_TYPE_IS_VALUE: |
33 | * @type: A #GType value. |
34 | * |
35 | * Checks whether the passed in type ID can be used for g_value_init(). |
36 | * |
37 | * That is, this macro checks whether this type provides an implementation |
38 | * of the #GTypeValueTable functions required for a type to create a #GValue of. |
39 | * |
40 | * Returns: Whether @type is suitable as a #GValue type. |
41 | */ |
42 | #define G_TYPE_IS_VALUE(type) (g_type_check_is_value_type (type)) |
43 | /** |
44 | * G_IS_VALUE: |
45 | * @value: A #GValue structure. |
46 | * |
47 | * Checks if @value is a valid and initialized #GValue structure. |
48 | * |
49 | * Returns: %TRUE on success. |
50 | */ |
51 | #define G_IS_VALUE(value) (G_TYPE_CHECK_VALUE (value)) |
52 | /** |
53 | * G_VALUE_TYPE: |
54 | * @value: A #GValue structure. |
55 | * |
56 | * Get the type identifier of @value. |
57 | * |
58 | * Returns: the #GType. |
59 | */ |
60 | #define G_VALUE_TYPE(value) (((GValue*) (value))->g_type) |
61 | /** |
62 | * G_VALUE_TYPE_NAME: |
63 | * @value: A #GValue structure. |
64 | * |
65 | * Gets the type name of @value. |
66 | * |
67 | * Returns: the type name. |
68 | */ |
69 | #define G_VALUE_TYPE_NAME(value) (g_type_name (G_VALUE_TYPE (value))) |
70 | /** |
71 | * G_VALUE_HOLDS: |
72 | * @value: A #GValue structure. |
73 | * @type: A #GType value. |
74 | * |
75 | * Checks if @value holds (or contains) a value of @type. |
76 | * This macro will also check for @value != %NULL and issue a |
77 | * warning if the check fails. |
78 | * |
79 | * Returns: %TRUE if @value holds the @type. |
80 | */ |
81 | #define G_VALUE_HOLDS(value,type) (G_TYPE_CHECK_VALUE_TYPE ((value), (type))) |
82 | |
83 | |
84 | /* --- typedefs & structures --- */ |
85 | /** |
86 | * GValueTransform: |
87 | * @src_value: Source value. |
88 | * @dest_value: Target value. |
89 | * |
90 | * The type of value transformation functions which can be registered with |
91 | * g_value_register_transform_func(). |
92 | * |
93 | * @dest_value will be initialized to the correct destination type. |
94 | */ |
95 | typedef void (*GValueTransform) (const GValue *src_value, |
96 | GValue *dest_value); |
97 | /** |
98 | * GValue: |
99 | * |
100 | * An opaque structure used to hold different types of values. |
101 | * |
102 | * The data within the structure has protected scope: it is accessible only |
103 | * to functions within a #GTypeValueTable structure, or implementations of |
104 | * the g_value_*() API. That is, code portions which implement new fundamental |
105 | * types. |
106 | * |
107 | * #GValue users cannot make any assumptions about how data is stored |
108 | * within the 2 element @data union, and the @g_type member should |
109 | * only be accessed through the G_VALUE_TYPE() macro. |
110 | */ |
111 | struct _GValue |
112 | { |
113 | /*< private >*/ |
114 | GType g_type; |
115 | |
116 | /* public for GTypeValueTable methods */ |
117 | union { |
118 | gint v_int; |
119 | guint v_uint; |
120 | glong v_long; |
121 | gulong v_ulong; |
122 | gint64 v_int64; |
123 | guint64 v_uint64; |
124 | gfloat v_float; |
125 | gdouble v_double; |
126 | gpointer v_pointer; |
127 | } data[2]; |
128 | }; |
129 | |
130 | |
131 | /* --- prototypes --- */ |
132 | GLIB_AVAILABLE_IN_ALL |
133 | GValue* g_value_init (GValue *value, |
134 | GType g_type); |
135 | GLIB_AVAILABLE_IN_ALL |
136 | void g_value_copy (const GValue *src_value, |
137 | GValue *dest_value); |
138 | GLIB_AVAILABLE_IN_ALL |
139 | GValue* g_value_reset (GValue *value); |
140 | GLIB_AVAILABLE_IN_ALL |
141 | void g_value_unset (GValue *value); |
142 | GLIB_AVAILABLE_IN_ALL |
143 | void g_value_set_instance (GValue *value, |
144 | gpointer instance); |
145 | GLIB_AVAILABLE_IN_2_42 |
146 | void g_value_init_from_instance (GValue *value, |
147 | gpointer instance); |
148 | |
149 | |
150 | /* --- private --- */ |
151 | GLIB_AVAILABLE_IN_ALL |
152 | gboolean g_value_fits_pointer (const GValue *value); |
153 | GLIB_AVAILABLE_IN_ALL |
154 | gpointer g_value_peek_pointer (const GValue *value); |
155 | |
156 | |
157 | /* --- implementation details --- */ |
158 | GLIB_AVAILABLE_IN_ALL |
159 | gboolean g_value_type_compatible (GType src_type, |
160 | GType dest_type); |
161 | GLIB_AVAILABLE_IN_ALL |
162 | gboolean g_value_type_transformable (GType src_type, |
163 | GType dest_type); |
164 | GLIB_AVAILABLE_IN_ALL |
165 | gboolean g_value_transform (const GValue *src_value, |
166 | GValue *dest_value); |
167 | GLIB_AVAILABLE_IN_ALL |
168 | void g_value_register_transform_func (GType src_type, |
169 | GType dest_type, |
170 | GValueTransform transform_func); |
171 | |
172 | /** |
173 | * G_VALUE_NOCOPY_CONTENTS: |
174 | * |
175 | * If passed to G_VALUE_COLLECT(), allocated data won't be copied |
176 | * but used verbatim. This does not affect ref-counted types like |
177 | * objects. This does not affect usage of g_value_copy(), the data will |
178 | * be copied if it is not ref-counted. |
179 | */ |
180 | #define G_VALUE_NOCOPY_CONTENTS (1 << 27) |
181 | |
182 | /** |
183 | * G_VALUE_INTERNED_STRING: |
184 | * |
185 | * For string values, indicates that the string contained is canonical and will |
186 | * exist for the duration of the process. See g_value_set_interned_string(). |
187 | * |
188 | * Since: 2.66 |
189 | */ |
190 | #define G_VALUE_INTERNED_STRING (1 << 28) GLIB_AVAILABLE_MACRO_IN_2_66 |
191 | |
192 | /** |
193 | * G_VALUE_INIT: |
194 | * |
195 | * A #GValue must be initialized before it can be used. This macro can |
196 | * be used as initializer instead of an explicit `{ 0 }` when declaring |
197 | * a variable, but it cannot be assigned to a variable. |
198 | * |
199 | * |[<!-- language="C" --> |
200 | * GValue value = G_VALUE_INIT; |
201 | * ]| |
202 | * |
203 | * Since: 2.30 |
204 | */ |
205 | #define G_VALUE_INIT { 0, { { 0 } } } |
206 | |
207 | |
208 | G_END_DECLS |
209 | |
210 | #endif /* __G_VALUE_H__ */ |
211 | |