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