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
30G_BEGIN_DECLS
31
32/* --- type macros --- */
33/**
34 * G_TYPE_IS_VALUE:
35 * @type: a type
36 *
37 * Checks whether the passed in type ID can be used for
38 * [method@GObject.Value.init].
39 *
40 * That is, this macro checks whether this type provides an implementation
41 * of the [struct@GObject.TypeValueTable] functions required to be able to
42 * create a [struct@GObject.Value] instance.
43 *
44 * Returns: Whether @type is suitable as a [struct@GObject.Value] type.
45 */
46#define G_TYPE_IS_VALUE(type) (g_type_check_is_value_type (type))
47
48/**
49 * G_IS_VALUE:
50 * @value: a [struct@GObject.Value] structure
51 *
52 * Checks if @value is a valid and initialized [struct@GObject.Value] structure.
53 *
54 * Returns: true on success; false otherwise
55 */
56#define G_IS_VALUE(value) (G_TYPE_CHECK_VALUE (value))
57
58/**
59 * G_VALUE_TYPE:
60 * @value: a [struct@GObject.Value] structure
61 *
62 * Get the type identifier of @value.
63 *
64 * Returns: the type ID
65 */
66#define G_VALUE_TYPE(value) (((GValue*) (value))->g_type)
67
68/**
69 * G_VALUE_TYPE_NAME:
70 * @value: a [struct@GObject.Value] structure
71 *
72 * Gets the name of the type of @value.
73 *
74 * Returns: the type name
75 */
76#define G_VALUE_TYPE_NAME(value) (g_type_name (G_VALUE_TYPE (value)))
77
78/**
79 * G_VALUE_HOLDS:
80 * @value: (not nullable): a [struct@GObject.Value] structure
81 * @type: a [type@GObject.Type]
82 *
83 * Checks if @value holds a value of @type.
84 *
85 * This macro will also check for `value != NULL` and issue a
86 * warning if the check fails.
87 *
88 * Returns: true if @value is non-`NULL` and holds a value of the given @type;
89 * false otherwise
90 */
91#define G_VALUE_HOLDS(value,type) (G_TYPE_CHECK_VALUE_TYPE ((value), (type)))
92
93
94/* --- typedefs & structures --- */
95/**
96 * GValueTransform:
97 * @src_value: source value
98 * @dest_value: target value
99 *
100 * The type of value transformation functions which can be registered with
101 * [func@GObject.Value.register_transform_func].
102 *
103 * @dest_value will be initialized to the correct destination type.
104 */
105typedef void (*GValueTransform) (const GValue *src_value,
106 GValue *dest_value);
107
108/**
109 * GValue:
110 *
111 * An opaque structure used to hold different types of values.
112 *
113 * Before it can be used, a `GValue` has to be initialized to a specific type by
114 * calling [method@GObject.Value.init] on it.
115 *
116 * Many types which are stored within a `GValue` need to allocate data on the
117 * heap, so [method@GObject.Value.unset] must always be called on a `GValue` to
118 * free any such data once you’re finished with the `GValue`, even if the
119 * `GValue` itself is stored on the stack.
120 *
121 * The data within the structure has protected scope: it is accessible only
122 * to functions within a [struct@GObject.TypeValueTable] structure, or
123 * implementations of the `g_value_*()` API. That is, code which implements new
124 * fundamental types.
125 *
126 * `GValue` users cannot make any assumptions about how data is stored
127 * within the 2 element @data union, and the @g_type member should
128 * only be accessed through the [func@GObject.VALUE_TYPE] macro and related
129 * macros.
130 */
131struct _GValue
132{
133 /*< private >*/
134 GType g_type;
135
136 /* public for GTypeValueTable methods */
137 union {
138 gint v_int;
139 guint v_uint;
140 glong v_long;
141 gulong v_ulong;
142 gint64 v_int64;
143 guint64 v_uint64;
144 gfloat v_float;
145 gdouble v_double;
146 gpointer v_pointer;
147 } data[2];
148};
149
150
151/* --- prototypes --- */
152GOBJECT_AVAILABLE_IN_ALL
153GValue* g_value_init (GValue *value,
154 GType g_type);
155GOBJECT_AVAILABLE_IN_ALL
156void g_value_copy (const GValue *src_value,
157 GValue *dest_value);
158GOBJECT_AVAILABLE_IN_ALL
159GValue* g_value_reset (GValue *value);
160GOBJECT_AVAILABLE_IN_ALL
161void g_value_unset (GValue *value);
162GOBJECT_AVAILABLE_IN_ALL
163void g_value_set_instance (GValue *value,
164 gpointer instance);
165GOBJECT_AVAILABLE_IN_2_42
166void g_value_init_from_instance (GValue *value,
167 gpointer instance);
168
169
170/* --- private --- */
171GOBJECT_AVAILABLE_IN_ALL
172gboolean g_value_fits_pointer (const GValue *value);
173GOBJECT_AVAILABLE_IN_ALL
174gpointer g_value_peek_pointer (const GValue *value);
175
176
177/* --- implementation details --- */
178GOBJECT_AVAILABLE_IN_ALL
179gboolean g_value_type_compatible (GType src_type,
180 GType dest_type);
181GOBJECT_AVAILABLE_IN_ALL
182gboolean g_value_type_transformable (GType src_type,
183 GType dest_type);
184GOBJECT_AVAILABLE_IN_ALL
185gboolean g_value_transform (const GValue *src_value,
186 GValue *dest_value);
187GOBJECT_AVAILABLE_IN_ALL
188void g_value_register_transform_func (GType src_type,
189 GType dest_type,
190 GValueTransform transform_func);
191
192/**
193 * G_VALUE_NOCOPY_CONTENTS:
194 *
195 * Flag to indicate that allocated data in a [struct@GObject.Value] shouldn’t be
196 * copied.
197 *
198 * If passed to [func@GObject.VALUE_COLLECT], allocated data won’t be copied
199 * but used verbatim. This does not affect ref-counted types like objects.
200 *
201 * This does not affect usage of [method@GObject.Value.copy]: the data will
202 * be copied if it is not ref-counted.
203 *
204 * This flag should be checked by implementations of
205 * [callback@GObject.TypeValueFreeFunc], [callback@GObject.TypeValueCollectFunc]
206 * and [callback@GObject.TypeValueLCopyFunc].
207 */
208#define G_VALUE_NOCOPY_CONTENTS (1 << 27)
209
210/**
211 * G_VALUE_INTERNED_STRING:
212 *
213 * Flag to indicate that a string in a [struct@GObject.Value] is canonical and
214 * will exist for the duration of the process.
215 *
216 * See [method@GObject.Value.set_interned_string].
217 *
218 * This flag should be checked by implementations of
219 * [callback@GObject.TypeValueFreeFunc], [callback@GObject.TypeValueCollectFunc]
220 * and [callback@GObject.TypeValueLCopyFunc].
221 *
222 * Since: 2.66
223 */
224#define G_VALUE_INTERNED_STRING (1 << 28) GOBJECT_AVAILABLE_MACRO_IN_2_66
225
226/**
227 * G_VALUE_INIT:
228 *
229 * Clears a [struct@GObject.Value] to zero at declaration time.
230 *
231 * A [struct@GObject.Value] must be cleared and then initialized before it can
232 * be used. This macro can be assigned to a variable instead of an explicit
233 * `{ 0 }` when declaring it, but it cannot be assigned to a variable after
234 * declaration time.
235 *
236 * After the [struct@GObject.Value] is cleared, it must be initialized by
237 * calling [method@GObject.Value.init] on it before any other methods can be
238 * called on it.
239 *
240 * ```c
241 * GValue value = G_VALUE_INIT;
242 *
243 * g_value_init (&value, SOME_G_TYPE);
244 * …
245 * g_value_unset (&value);
246 * ```
247 *
248 * Since: 2.30
249 */
250#define G_VALUE_INIT { 0, { { 0 } } }
251
252
253G_END_DECLS
254
255#endif /* __G_VALUE_H__ */
256