1 /*
2 * Copyright © 2007, 2008 Ryan Lortie
3 * Copyright © 2009, 2010 Codethink Limited
4 *
5 * SPDX-License-Identifier: LGPL-2.1-or-later
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 *
20 * Author: Ryan Lortie <desrt@desrt.ca>
21 */
22
23 #include "config.h"
24
25 #include "gvarianttype.h"
26
27 #include <glib/gtestutils.h>
28 #include <glib/gstrfuncs.h>
29 #include <glib/gvariant-internal.h>
30
31 #include <string.h>
32
33
34 /**
35 * GVariantType:
36 *
37 * A type in the [type@GLib.Variant] type system.
38 *
39 * This section introduces the [type@GLib.Variant] type system. It is based, in
40 * large part, on the D-Bus type system, with two major changes and
41 * some minor lifting of restrictions. The
42 * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html),
43 * therefore, provides a significant amount of
44 * information that is useful when working with [type@GLib.Variant].
45 *
46 * The first major change with respect to the D-Bus type system is the
47 * introduction of maybe (or ‘nullable’) types. Any type in [type@GLib.Variant]
48 * can be converted to a maybe type, in which case, `nothing` (or `null`)
49 * becomes a valid value. Maybe types have been added by introducing the
50 * character `m` to type strings.
51 *
52 * The second major change is that the [type@GLib.Variant] type system supports
53 * the concept of ‘indefinite types’ — types that are less specific than
54 * the normal types found in D-Bus. For example, it is possible to speak
55 * of ‘an array of any type’ in [type@GLib.Variant], where the D-Bus type system
56 * would require you to speak of ‘an array of integers’ or ‘an array of
57 * strings’. Indefinite types have been added by introducing the
58 * characters `*`, `?` and `r` to type strings.
59 *
60 * Finally, all arbitrary restrictions relating to the complexity of
61 * types are lifted along with the restriction that dictionary entries
62 * may only appear nested inside of arrays.
63 *
64 * Just as in D-Bus, [type@GLib.Variant] types are described with strings (‘type
65 * strings’). Subject to the differences mentioned above, these strings
66 * are of the same form as those found in D-Bus. Note, however: D-Bus
67 * always works in terms of messages and therefore individual type
68 * strings appear nowhere in its interface. Instead, ‘signatures’
69 * are a concatenation of the strings of the type of each argument in a
70 * message. [type@GLib.Variant] deals with single values directly so
71 * [type@GLib.Variant] type strings always describe the type of exactly one
72 * value. This means that a D-Bus signature string is generally not a valid
73 * [type@GLib.Variant] type string — except in the case that it is the signature
74 * of a message containing exactly one argument.
75 *
76 * An indefinite type is similar in spirit to what may be called an
77 * abstract type in other type systems. No value can exist that has an
78 * indefinite type as its type, but values can exist that have types
79 * that are subtypes of indefinite types. That is to say,
80 * [method@GLib.Variant.get_type] will never return an indefinite type, but
81 * calling [method@GLib.Variant.is_of_type] with an indefinite type may return
82 * true. For example, you cannot have a value that represents ‘an
83 * array of no particular type’, but you can have an ‘array of integers’
84 * which certainly matches the type of ‘an array of no particular type’,
85 * since ‘array of integers’ is a subtype of ‘array of no particular
86 * type’.
87 *
88 * This is similar to how instances of abstract classes may not
89 * directly exist in other type systems, but instances of their
90 * non-abstract subtypes may. For example, in GTK, no object that has
91 * the type of [class@Gtk.Widget] can exist (since [class@Gtk.Widget] is an
92 * abstract class), but a [class@Gtk.Window] can certainly be instantiated, and
93 * you would say that the [class@Gtk.Window] is a [class@Gtk.Widget] (since
94 * [class@Gtk.Window] is a subclass of [class@Gtk.Widget]).
95 *
96 * Two types may not be compared by value; use [method@GLib.VariantType.equal]
97 * or [method@GLib.VariantType.is_subtype_of] May be copied using
98 * [method@GLib.VariantType.copy] and freed using [method@GLib.VariantType.free].
99 *
100 * ## GVariant Type Strings
101 *
102 * A [type@GLib.Variant] type string can be any of the following:
103 *
104 * - any basic type string (listed below)
105 * - `v`, `r` or `*`
106 * - one of the characters `a` or `m`, followed by another type string
107 * - the character `(`, followed by a concatenation of zero or more other
108 * type strings, followed by the character `)`
109 * - the character `{`, followed by a basic type string (see below),
110 * followed by another type string, followed by the character `}`
111 *
112 * A basic type string describes a basic type (as per
113 * [method@GLib.VariantType.is_basic]) and is always a single character in
114 * length. The valid basic type strings are `b`, `y`, `n`, `q`, `i`, `u`, `x`,
115 * `t`, `h`, `d`, `s`, `o`, `g` and `?`.
116 *
117 * The above definition is recursive to arbitrary depth. `aaaaai` and
118 * `(ui(nq((y)))s)` are both valid type strings, as is
119 * `a(aa(ui)(qna{ya(yd)}))`. In order to not hit memory limits,
120 * [type@GLib.Variant] imposes a limit on recursion depth of 65 nested
121 * containers. This is the limit in the D-Bus specification (64) plus one to
122 * allow a [class@Gio.DBusMessage] to be nested in a top-level tuple.
123 *
124 * The meaning of each of the characters is as follows:
125 *
126 * - `b`: the type string of `G_VARIANT_TYPE_BOOLEAN`; a boolean value.
127 * - `y`: the type string of `G_VARIANT_TYPE_BYTE`; a byte.
128 * - `n`: the type string of `G_VARIANT_TYPE_INT16`; a signed 16 bit integer.
129 * - `q`: the type string of `G_VARIANT_TYPE_UINT16`; an unsigned 16 bit integer.
130 * - `i`: the type string of `G_VARIANT_TYPE_INT32`; a signed 32 bit integer.
131 * - `u`: the type string of `G_VARIANT_TYPE_UINT32`; an unsigned 32 bit integer.
132 * - `x`: the type string of `G_VARIANT_TYPE_INT64`; a signed 64 bit integer.
133 * - `t`: the type string of `G_VARIANT_TYPE_UINT64`; an unsigned 64 bit integer.
134 * - `h`: the type string of `G_VARIANT_TYPE_HANDLE`; a signed 32 bit value
135 * that, by convention, is used as an index into an array of file
136 * descriptors that are sent alongside a D-Bus message.
137 * - `d`: the type string of `G_VARIANT_TYPE_DOUBLE`; a double precision
138 * floating point value.
139 * - `s`: the type string of `G_VARIANT_TYPE_STRING`; a string.
140 * - `o`: the type string of `G_VARIANT_TYPE_OBJECT_PATH`; a string in the form
141 * of a D-Bus object path.
142 * - `g`: the type string of `G_VARIANT_TYPE_SIGNATURE`; a string in the form of
143 * a D-Bus type signature.
144 * - `?`: the type string of `G_VARIANT_TYPE_BASIC`; an indefinite type that
145 * is a supertype of any of the basic types.
146 * - `v`: the type string of `G_VARIANT_TYPE_VARIANT`; a container type that
147 * contain any other type of value.
148 * - `a`: used as a prefix on another type string to mean an array of that
149 * type; the type string `ai`, for example, is the type of an array of
150 * signed 32-bit integers.
151 * - `m`: used as a prefix on another type string to mean a ‘maybe’, or
152 * ‘nullable’, version of that type; the type string `ms`, for example,
153 * is the type of a value that maybe contains a string, or maybe contains
154 * nothing.
155 * - `()`: used to enclose zero or more other concatenated type strings to
156 * create a tuple type; the type string `(is)`, for example, is the type of
157 * a pair of an integer and a string.
158 * - `r`: the type string of `G_VARIANT_TYPE_TUPLE`; an indefinite type that is
159 * a supertype of any tuple type, regardless of the number of items.
160 * - `{}`: used to enclose a basic type string concatenated with another type
161 * string to create a dictionary entry type, which usually appears inside of
162 * an array to form a dictionary; the type string `a{sd}`, for example, is
163 * the type of a dictionary that maps strings to double precision floating
164 * point values.
165 *
166 * The first type (the basic type) is the key type and the second type is
167 * the value type. The reason that the first type is restricted to being a
168 * basic type is so that it can easily be hashed.
169 * - `*`: the type string of `G_VARIANT_TYPE_ANY`; the indefinite type that is
170 * a supertype of all types. Note that, as with all type strings, this
171 * character represents exactly one type. It cannot be used inside of tuples
172 * to mean ‘any number of items’.
173 *
174 * Any type string of a container that contains an indefinite type is,
175 * itself, an indefinite type. For example, the type string `a*`
176 * (corresponding to `G_VARIANT_TYPE_ARRAY`) is an indefinite type
177 * that is a supertype of every array type. `(*s)` is a supertype
178 * of all tuples that contain exactly two items where the second
179 * item is a string.
180 *
181 * `a{?*}` is an indefinite type that is a supertype of all arrays
182 * containing dictionary entries where the key is any basic type and
183 * the value is any type at all. This is, by definition, a dictionary,
184 * so this type string corresponds to `G_VARIANT_TYPE_DICTIONARY`. Note
185 * that, due to the restriction that the key of a dictionary entry must
186 * be a basic type, `{**}` is not a valid type string.
187 *
188 * Since: 2.24
189 */
190
191
192 static gboolean
193 g_variant_type_check (const GVariantType *type)
194 {
195 if (type == NULL)
196 return FALSE;
197
198 #if 0
199 return g_variant_type_string_scan ((const gchar *) type, NULL, NULL);
200 #else
201 return TRUE;
202 #endif
203 }
204
205 static gboolean
206 variant_type_string_scan_internal (const gchar *string,
207 const gchar *limit,
208 const gchar **endptr,
209 gsize *depth,
210 gsize depth_limit)
211 {
212 gsize max_depth = 0, child_depth;
213
214 g_return_val_if_fail (string != NULL, FALSE);
215
216 if (string == limit || *string == '\0')
217 return FALSE;
218
219 switch (*string++)
220 {
221 case '(':
222 while (string == limit || *string != ')')
223 {
224 if (depth_limit == 0 ||
225 !variant_type_string_scan_internal (string, limit, &string,
226 &child_depth,
227 depth_limit - 1))
228 return FALSE;
229
230 max_depth = MAX (max_depth, child_depth + 1);
231 }
232
233 string++;
234 break;
235
236 case '{':
237 if (depth_limit == 0 ||
238 string == limit || *string == '\0' || /* { */
239 !strchr ("bynqihuxtdsog?", *string++) || /* key */
240 !variant_type_string_scan_internal (string, limit, &string,
241 &child_depth, depth_limit - 1) || /* value */
242 string == limit || *string++ != '}') /* } */
243 return FALSE;
244
245 max_depth = MAX (max_depth, child_depth + 1);
246 break;
247
248 case 'm': case 'a':
249 if (depth_limit == 0 ||
250 !variant_type_string_scan_internal (string, limit, &string,
251 &child_depth, depth_limit - 1))
252 return FALSE;
253
254 max_depth = MAX (max_depth, child_depth + 1);
255 break;
256
257 case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
258 case 'x': case 't': case 'd': case 's': case 'o': case 'g':
259 case 'v': case 'r': case '*': case '?': case 'h':
260 max_depth = MAX (max_depth, 1);
261 break;
262
263 default:
264 return FALSE;
265 }
266
267 if (endptr != NULL)
268 *endptr = string;
269 if (depth != NULL)
270 *depth = max_depth;
271
272 return TRUE;
273 }
274
275 /**
276 * g_variant_type_string_scan:
277 * @string: a pointer to any string
278 * @limit: (nullable): the end of @string, or %NULL
279 * @endptr: (out) (optional): location to store the end pointer, or %NULL
280 *
281 * Scan for a single complete and valid GVariant type string in @string.
282 * The memory pointed to by @limit (or bytes beyond it) is never
283 * accessed.
284 *
285 * If a valid type string is found, @endptr is updated to point to the
286 * first character past the end of the string that was found and %TRUE
287 * is returned.
288 *
289 * If there is no valid type string starting at @string, or if the type
290 * string does not end before @limit then %FALSE is returned.
291 *
292 * For the simple case of checking if a string is a valid type string,
293 * see g_variant_type_string_is_valid().
294 *
295 * Returns: %TRUE if a valid type string was found
296 *
297 * Since: 2.24
298 **/
299 gboolean
300 g_variant_type_string_scan (const gchar *string,
301 const gchar *limit,
302 const gchar **endptr)
303 {
304 return variant_type_string_scan_internal (string, limit, endptr, NULL,
305 G_VARIANT_MAX_RECURSION_DEPTH);
306 }
307
308 /* < private >
309 * g_variant_type_string_get_depth_:
310 * @type_string: a pointer to any string
311 *
312 * Get the maximum depth of the nested types in @type_string. A basic type will
313 * return depth 1, and a container type will return a greater value. The depth
314 * of a tuple is 1 plus the depth of its deepest child type.
315 *
316 * If @type_string is not a valid #GVariant type string, 0 will be returned.
317 *
318 * Returns: depth of @type_string, or 0 on error
319 * Since: 2.60
320 */
321 gsize
322 g_variant_type_string_get_depth_ (const gchar *type_string)
323 {
324 const gchar *endptr;
325 gsize depth = 0;
326
327 g_return_val_if_fail (type_string != NULL, 0);
328
329 if (!variant_type_string_scan_internal (type_string, NULL, &endptr, &depth,
330 G_VARIANT_MAX_RECURSION_DEPTH) ||
331 *endptr != '\0')
332 return 0;
333
334 return depth;
335 }
336
337 /**
338 * g_variant_type_string_is_valid:
339 * @type_string: a pointer to any string
340 *
341 * Checks if @type_string is a valid GVariant type string. This call is
342 * equivalent to calling g_variant_type_string_scan() and confirming
343 * that the following character is a nul terminator.
344 *
345 * Returns: %TRUE if @type_string is exactly one valid type string
346 *
347 * Since 2.24
348 **/
349 gboolean
350 g_variant_type_string_is_valid (const gchar *type_string)
351 {
352 const gchar *endptr;
353
354 g_return_val_if_fail (type_string != NULL, FALSE);
355
356 if (!g_variant_type_string_scan (type_string, NULL, &endptr))
357 return FALSE;
358
359 return *endptr == '\0';
360 }
361
362 /**
363 * g_variant_type_free:
364 * @type: (nullable): a #GVariantType, or %NULL
365 *
366 * Frees a #GVariantType that was allocated with
367 * g_variant_type_copy(), g_variant_type_new() or one of the container
368 * type constructor functions.
369 *
370 * In the case that @type is %NULL, this function does nothing.
371 *
372 * Since 2.24
373 **/
374 void
375 g_variant_type_free (GVariantType *type)
376 {
377 g_return_if_fail (type == NULL || g_variant_type_check (type));
378
379 g_free (type);
380 }
381
382 /**
383 * g_variant_type_copy:
384 * @type: a #GVariantType
385 *
386 * Makes a copy of a #GVariantType. It is appropriate to call
387 * g_variant_type_free() on the return value. @type may not be %NULL.
388 *
389 * Returns: (transfer full): a new #GVariantType
390 *
391 * Since 2.24
392 **/
393 GVariantType *
394 g_variant_type_copy (const GVariantType *type)
395 {
396 gsize length;
397 gchar *new;
398
399 g_return_val_if_fail (g_variant_type_check (type), NULL);
400
401 length = g_variant_type_get_string_length (type);
402 new = g_malloc (length + 1);
403
404 memcpy (new, type, length);
405 new[length] = '\0';
406
407 return (GVariantType *) new;
408 }
409
410 /**
411 * g_variant_type_new:
412 * @type_string: a valid GVariant type string
413 *
414 * Creates a new #GVariantType corresponding to the type string given
415 * by @type_string. It is appropriate to call g_variant_type_free() on
416 * the return value.
417 *
418 * It is a programmer error to call this function with an invalid type
419 * string. Use g_variant_type_string_is_valid() if you are unsure.
420 *
421 * Returns: (transfer full): a new #GVariantType
422 *
423 * Since: 2.24
424 */
425 GVariantType *
426 g_variant_type_new (const gchar *type_string)
427 {
428 g_return_val_if_fail (type_string != NULL, NULL);
429
430 return g_variant_type_copy (G_VARIANT_TYPE (type_string));
431 }
432
433 /**
434 * g_variant_type_get_string_length:
435 * @type: a #GVariantType
436 *
437 * Returns the length of the type string corresponding to the given
438 * @type. This function must be used to determine the valid extent of
439 * the memory region returned by g_variant_type_peek_string().
440 *
441 * Returns: the length of the corresponding type string
442 *
443 * Since 2.24
444 **/
445 gsize
446 g_variant_type_get_string_length (const GVariantType *type)
447 {
448 const gchar *type_string = (const gchar *) type;
449 gint brackets = 0;
450 gsize index = 0;
451
452 g_return_val_if_fail (g_variant_type_check (type), 0);
453
454 do
455 {
456 while (type_string[index] == 'a' || type_string[index] == 'm')
457 index++;
458
459 if (type_string[index] == '(' || type_string[index] == '{')
460 brackets++;
461
462 else if (type_string[index] == ')' || type_string[index] == '}')
463 brackets--;
464
465 index++;
466 }
467 while (brackets);
468
469 return index;
470 }
471
472 /*
473 This function is not introspectable, it returns something that
474 is not an array and neither a string
475 */
476 /**
477 * g_variant_type_peek_string: (skip)
478 * @type: a #GVariantType
479 *
480 * Returns the type string corresponding to the given @type. The
481 * result is not nul-terminated; in order to determine its length you
482 * must call g_variant_type_get_string_length().
483 *
484 * To get a nul-terminated string, see g_variant_type_dup_string().
485 *
486 * Returns: the corresponding type string (not nul-terminated)
487 *
488 * Since 2.24
489 **/
490 const gchar *
491 g_variant_type_peek_string (const GVariantType *type)
492 {
493 g_return_val_if_fail (g_variant_type_check (type), NULL);
494
495 return (const gchar *) type;
496 }
497
498 /**
499 * g_variant_type_dup_string:
500 * @type: a #GVariantType
501 *
502 * Returns a newly-allocated copy of the type string corresponding to
503 * @type. The returned string is nul-terminated. It is appropriate to
504 * call g_free() on the return value.
505 *
506 * Returns: (transfer full): the corresponding type string
507 *
508 * Since 2.24
509 **/
510 gchar *
511 g_variant_type_dup_string (const GVariantType *type)
512 {
513 g_return_val_if_fail (g_variant_type_check (type), NULL);
514
515 return g_strndup (g_variant_type_peek_string (type),
516 g_variant_type_get_string_length (type));
517 }
518
519 /**
520 * g_variant_type_is_definite:
521 * @type: a #GVariantType
522 *
523 * Determines if the given @type is definite (ie: not indefinite).
524 *
525 * A type is definite if its type string does not contain any indefinite
526 * type characters ('*', '?', or 'r').
527 *
528 * A #GVariant instance may not have an indefinite type, so calling
529 * this function on the result of g_variant_get_type() will always
530 * result in %TRUE being returned. Calling this function on an
531 * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
532 * %FALSE being returned.
533 *
534 * Returns: %TRUE if @type is definite
535 *
536 * Since 2.24
537 **/
538 gboolean
539 g_variant_type_is_definite (const GVariantType *type)
540 {
541 const gchar *type_string;
542 gsize type_length;
543 gsize i;
544
545 g_return_val_if_fail (g_variant_type_check (type), FALSE);
546
547 type_length = g_variant_type_get_string_length (type);
548 type_string = g_variant_type_peek_string (type);
549
550 for (i = 0; i < type_length; i++)
551 if (type_string[i] == '*' ||
552 type_string[i] == '?' ||
553 type_string[i] == 'r')
554 return FALSE;
555
556 return TRUE;
557 }
558
559 /**
560 * g_variant_type_is_container:
561 * @type: a #GVariantType
562 *
563 * Determines if the given @type is a container type.
564 *
565 * Container types are any array, maybe, tuple, or dictionary
566 * entry types plus the variant type.
567 *
568 * This function returns %TRUE for any indefinite type for which every
569 * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
570 * example.
571 *
572 * Returns: %TRUE if @type is a container type
573 *
574 * Since 2.24
575 **/
576 gboolean
577 g_variant_type_is_container (const GVariantType *type)
578 {
579 gchar first_char;
580
581 g_return_val_if_fail (g_variant_type_check (type), FALSE);
582
583 first_char = g_variant_type_peek_string (type)[0];
584 switch (first_char)
585 {
586 case 'a':
587 case 'm':
588 case 'r':
589 case '(':
590 case '{':
591 case 'v':
592 return TRUE;
593
594 default:
595 return FALSE;
596 }
597 }
598
599 /**
600 * g_variant_type_is_basic:
601 * @type: a #GVariantType
602 *
603 * Determines if the given @type is a basic type.
604 *
605 * Basic types are booleans, bytes, integers, doubles, strings, object
606 * paths and signatures.
607 *
608 * Only a basic type may be used as the key of a dictionary entry.
609 *
610 * This function returns %FALSE for all indefinite types except
611 * %G_VARIANT_TYPE_BASIC.
612 *
613 * Returns: %TRUE if @type is a basic type
614 *
615 * Since 2.24
616 **/
617 gboolean
618 g_variant_type_is_basic (const GVariantType *type)
619 {
620 gchar first_char;
621
622 g_return_val_if_fail (g_variant_type_check (type), FALSE);
623
624 first_char = g_variant_type_peek_string (type)[0];
625 switch (first_char)
626 {
627 case 'b':
628 case 'y':
629 case 'n':
630 case 'q':
631 case 'i':
632 case 'h':
633 case 'u':
634 case 't':
635 case 'x':
636 case 'd':
637 case 's':
638 case 'o':
639 case 'g':
640 case '?':
641 return TRUE;
642
643 default:
644 return FALSE;
645 }
646 }
647
648 /**
649 * g_variant_type_is_maybe:
650 * @type: a #GVariantType
651 *
652 * Determines if the given @type is a maybe type. This is true if the
653 * type string for @type starts with an 'm'.
654 *
655 * This function returns %TRUE for any indefinite type for which every
656 * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
657 * example.
658 *
659 * Returns: %TRUE if @type is a maybe type
660 *
661 * Since 2.24
662 **/
663 gboolean
664 g_variant_type_is_maybe (const GVariantType *type)
665 {
666 g_return_val_if_fail (g_variant_type_check (type), FALSE);
667
668 return g_variant_type_peek_string (type)[0] == 'm';
669 }
670
671 /**
672 * g_variant_type_is_array:
673 * @type: a #GVariantType
674 *
675 * Determines if the given @type is an array type. This is true if the
676 * type string for @type starts with an 'a'.
677 *
678 * This function returns %TRUE for any indefinite type for which every
679 * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
680 * example.
681 *
682 * Returns: %TRUE if @type is an array type
683 *
684 * Since 2.24
685 **/
686 gboolean
687 g_variant_type_is_array (const GVariantType *type)
688 {
689 g_return_val_if_fail (g_variant_type_check (type), FALSE);
690
691 return g_variant_type_peek_string (type)[0] == 'a';
692 }
693
694 /**
695 * g_variant_type_is_tuple:
696 * @type: a #GVariantType
697 *
698 * Determines if the given @type is a tuple type. This is true if the
699 * type string for @type starts with a '(' or if @type is
700 * %G_VARIANT_TYPE_TUPLE.
701 *
702 * This function returns %TRUE for any indefinite type for which every
703 * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
704 * example.
705 *
706 * Returns: %TRUE if @type is a tuple type
707 *
708 * Since 2.24
709 **/
710 gboolean
711 g_variant_type_is_tuple (const GVariantType *type)
712 {
713 gchar type_char;
714
715 g_return_val_if_fail (g_variant_type_check (type), FALSE);
716
717 type_char = g_variant_type_peek_string (type)[0];
718 return type_char == 'r' || type_char == '(';
719 }
720
721 /**
722 * g_variant_type_is_dict_entry:
723 * @type: a #GVariantType
724 *
725 * Determines if the given @type is a dictionary entry type. This is
726 * true if the type string for @type starts with a '{'.
727 *
728 * This function returns %TRUE for any indefinite type for which every
729 * definite subtype is a dictionary entry type --
730 * %G_VARIANT_TYPE_DICT_ENTRY, for example.
731 *
732 * Returns: %TRUE if @type is a dictionary entry type
733 *
734 * Since 2.24
735 **/
736 gboolean
737 g_variant_type_is_dict_entry (const GVariantType *type)
738 {
739 g_return_val_if_fail (g_variant_type_check (type), FALSE);
740
741 return g_variant_type_peek_string (type)[0] == '{';
742 }
743
744 /**
745 * g_variant_type_is_variant:
746 * @type: a #GVariantType
747 *
748 * Determines if the given @type is the variant type.
749 *
750 * Returns: %TRUE if @type is the variant type
751 *
752 * Since 2.24
753 **/
754 gboolean
755 g_variant_type_is_variant (const GVariantType *type)
756 {
757 g_return_val_if_fail (g_variant_type_check (type), FALSE);
758
759 return g_variant_type_peek_string (type)[0] == 'v';
760 }
761
762 /**
763 * g_variant_type_hash:
764 * @type: (type GVariantType): a #GVariantType
765 *
766 * Hashes @type.
767 *
768 * The argument type of @type is only #gconstpointer to allow use with
769 * #GHashTable without function pointer casting. A valid
770 * #GVariantType must be provided.
771 *
772 * Returns: the hash value
773 *
774 * Since 2.24
775 **/
776 guint
777 g_variant_type_hash (gconstpointer type)
778 {
779 const gchar *type_string;
780 guint value = 0;
781 gsize length;
782 gsize i;
783
784 g_return_val_if_fail (g_variant_type_check (type), 0);
785
786 type_string = g_variant_type_peek_string (type);
787 length = g_variant_type_get_string_length (type);
788
789 for (i = 0; i < length; i++)
790 value = (value << 5) - value + type_string[i];
791
792 return value;
793 }
794
795 /**
796 * g_variant_type_equal:
797 * @type1: (type GVariantType): a #GVariantType
798 * @type2: (type GVariantType): a #GVariantType
799 *
800 * Compares @type1 and @type2 for equality.
801 *
802 * Only returns %TRUE if the types are exactly equal. Even if one type
803 * is an indefinite type and the other is a subtype of it, %FALSE will
804 * be returned if they are not exactly equal. If you want to check for
805 * subtypes, use g_variant_type_is_subtype_of().
806 *
807 * The argument types of @type1 and @type2 are only #gconstpointer to
808 * allow use with #GHashTable without function pointer casting. For
809 * both arguments, a valid #GVariantType must be provided.
810 *
811 * Returns: %TRUE if @type1 and @type2 are exactly equal
812 *
813 * Since 2.24
814 **/
815 gboolean
816 g_variant_type_equal (gconstpointer type1,
817 gconstpointer type2)
818 {
819 const gchar *string1, *string2;
820 gsize size1, size2;
821
822 g_return_val_if_fail (g_variant_type_check (type1), FALSE);
823 g_return_val_if_fail (g_variant_type_check (type2), FALSE);
824
825 if (type1 == type2)
826 return TRUE;
827
828 size1 = g_variant_type_get_string_length (type1);
829 size2 = g_variant_type_get_string_length (type2);
830
831 if (size1 != size2)
832 return FALSE;
833
834 string1 = g_variant_type_peek_string (type1);
835 string2 = g_variant_type_peek_string (type2);
836
837 return memcmp (string1, string2, size1) == 0;
838 }
839
840 /**
841 * g_variant_type_is_subtype_of:
842 * @type: a #GVariantType
843 * @supertype: a #GVariantType
844 *
845 * Checks if @type is a subtype of @supertype.
846 *
847 * This function returns %TRUE if @type is a subtype of @supertype. All
848 * types are considered to be subtypes of themselves. Aside from that,
849 * only indefinite types can have subtypes.
850 *
851 * Returns: %TRUE if @type is a subtype of @supertype
852 *
853 * Since 2.24
854 **/
855 gboolean
856 g_variant_type_is_subtype_of (const GVariantType *type,
857 const GVariantType *supertype)
858 {
859 const gchar *supertype_string;
860 const gchar *supertype_end;
861 const gchar *type_string;
862
863 g_return_val_if_fail (g_variant_type_check (type), FALSE);
864 g_return_val_if_fail (g_variant_type_check (supertype), FALSE);
865
866 supertype_string = g_variant_type_peek_string (supertype);
867 type_string = g_variant_type_peek_string (type);
868
869 supertype_end = supertype_string +
870 g_variant_type_get_string_length (supertype);
871
872 /* we know that type and supertype are both well-formed, so it's
873 * safe to treat this merely as a text processing problem.
874 */
875 while (supertype_string < supertype_end)
876 {
877 char supertype_char = *supertype_string++;
878
879 if (supertype_char == *type_string)
880 type_string++;
881
882 else if (*type_string == ')')
883 return FALSE;
884
885 else
886 {
887 const GVariantType *target_type = (GVariantType *) type_string;
888
889 switch (supertype_char)
890 {
891 case 'r':
892 if (!g_variant_type_is_tuple (target_type))
893 return FALSE;
894 break;
895
896 case '*':
897 break;
898
899 case '?':
900 if (!g_variant_type_is_basic (target_type))
901 return FALSE;
902 break;
903
904 default:
905 return FALSE;
906 }
907
908 type_string += g_variant_type_get_string_length (target_type);
909 }
910 }
911
912 return TRUE;
913 }
914
915 /**
916 * g_variant_type_element:
917 * @type: an array or maybe #GVariantType
918 *
919 * Determines the element type of an array or maybe type.
920 *
921 * This function may only be used with array or maybe types.
922 *
923 * Returns: (transfer none): the element type of @type
924 *
925 * Since 2.24
926 **/
927 const GVariantType *
928 g_variant_type_element (const GVariantType *type)
929 {
930 const gchar *type_string;
931
932 g_return_val_if_fail (g_variant_type_check (type), NULL);
933
934 type_string = g_variant_type_peek_string (type);
935
936 g_assert (type_string[0] == 'a' || type_string[0] == 'm');
937
938 return (const GVariantType *) &type_string[1];
939 }
940
941 /**
942 * g_variant_type_first:
943 * @type: a tuple or dictionary entry #GVariantType
944 *
945 * Determines the first item type of a tuple or dictionary entry
946 * type.
947 *
948 * This function may only be used with tuple or dictionary entry types,
949 * but must not be used with the generic tuple type
950 * %G_VARIANT_TYPE_TUPLE.
951 *
952 * In the case of a dictionary entry type, this returns the type of
953 * the key.
954 *
955 * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
956 *
957 * This call, together with g_variant_type_next() provides an iterator
958 * interface over tuple and dictionary entry types.
959 *
960 * Returns: (transfer none): the first item type of @type, or %NULL
961 *
962 * Since 2.24
963 **/
964 const GVariantType *
965 g_variant_type_first (const GVariantType *type)
966 {
967 const gchar *type_string;
968
969 g_return_val_if_fail (g_variant_type_check (type), NULL);
970
971 type_string = g_variant_type_peek_string (type);
972 g_assert (type_string[0] == '(' || type_string[0] == '{');
973
974 if (type_string[1] == ')')
975 return NULL;
976
977 return (const GVariantType *) &type_string[1];
978 }
979
980 /**
981 * g_variant_type_next:
982 * @type: a #GVariantType from a previous call
983 *
984 * Determines the next item type of a tuple or dictionary entry
985 * type.
986 *
987 * @type must be the result of a previous call to
988 * g_variant_type_first() or g_variant_type_next().
989 *
990 * If called on the key type of a dictionary entry then this call
991 * returns the value type. If called on the value type of a dictionary
992 * entry then this call returns %NULL.
993 *
994 * For tuples, %NULL is returned when @type is the last item in a tuple.
995 *
996 * Returns: (transfer none): the next #GVariantType after @type, or %NULL
997 *
998 * Since 2.24
999 **/
1000 const GVariantType *
1001 g_variant_type_next (const GVariantType *type)
1002 {
1003 const gchar *type_string;
1004
1005 g_return_val_if_fail (g_variant_type_check (type), NULL);
1006
1007 type_string = g_variant_type_peek_string (type);
1008 type_string += g_variant_type_get_string_length (type);
1009
1010 if (*type_string == ')' || *type_string == '}')
1011 return NULL;
1012
1013 return (const GVariantType *) type_string;
1014 }
1015
1016 /**
1017 * g_variant_type_n_items:
1018 * @type: a tuple or dictionary entry #GVariantType
1019 *
1020 * Determines the number of items contained in a tuple or
1021 * dictionary entry type.
1022 *
1023 * This function may only be used with tuple or dictionary entry types,
1024 * but must not be used with the generic tuple type
1025 * %G_VARIANT_TYPE_TUPLE.
1026 *
1027 * In the case of a dictionary entry type, this function will always
1028 * return 2.
1029 *
1030 * Returns: the number of items in @type
1031 *
1032 * Since 2.24
1033 **/
1034 gsize
1035 g_variant_type_n_items (const GVariantType *type)
1036 {
1037 gsize count = 0;
1038
1039 g_return_val_if_fail (g_variant_type_check (type), 0);
1040
1041 for (type = g_variant_type_first (type);
1042 type;
1043 type = g_variant_type_next (type))
1044 count++;
1045
1046 return count;
1047 }
1048
1049 /**
1050 * g_variant_type_key:
1051 * @type: a dictionary entry #GVariantType
1052 *
1053 * Determines the key type of a dictionary entry type.
1054 *
1055 * This function may only be used with a dictionary entry type. Other
1056 * than the additional restriction, this call is equivalent to
1057 * g_variant_type_first().
1058 *
1059 * Returns: (transfer none): the key type of the dictionary entry
1060 *
1061 * Since 2.24
1062 **/
1063 const GVariantType *
1064 g_variant_type_key (const GVariantType *type)
1065 {
1066 const gchar *type_string;
1067
1068 g_return_val_if_fail (g_variant_type_check (type), NULL);
1069
1070 type_string = g_variant_type_peek_string (type);
1071 g_assert (type_string[0] == '{');
1072
1073 return (const GVariantType *) &type_string[1];
1074 }
1075
1076 /**
1077 * g_variant_type_value:
1078 * @type: a dictionary entry #GVariantType
1079 *
1080 * Determines the value type of a dictionary entry type.
1081 *
1082 * This function may only be used with a dictionary entry type.
1083 *
1084 * Returns: (transfer none): the value type of the dictionary entry
1085 *
1086 * Since 2.24
1087 **/
1088 const GVariantType *
1089 g_variant_type_value (const GVariantType *type)
1090 {
1091 #ifndef G_DISABLE_ASSERT
1092 const gchar *type_string;
1093 #endif
1094
1095 g_return_val_if_fail (g_variant_type_check (type), NULL);
1096
1097 #ifndef G_DISABLE_ASSERT
1098 type_string = g_variant_type_peek_string (type);
1099 g_assert (type_string[0] == '{');
1100 #endif
1101
1102 return g_variant_type_next (g_variant_type_key (type));
1103 }
1104
1105 /**
1106 * g_variant_type_new_tuple:
1107 * @items: (array length=length): an array of #GVariantTypes, one for each item
1108 * @length: the length of @items, or -1
1109 *
1110 * Constructs a new tuple type, from @items.
1111 *
1112 * @length is the number of items in @items, or -1 to indicate that
1113 * @items is %NULL-terminated.
1114 *
1115 * It is appropriate to call g_variant_type_free() on the return value.
1116 *
1117 * Returns: (transfer full): a new tuple #GVariantType
1118 *
1119 * Since 2.24
1120 **/
1121 static GVariantType *
1122 g_variant_type_new_tuple_slow (const GVariantType * const *items,
1123 gint length)
1124 {
1125 /* the "slow" version is needed in case the static buffer of 1024
1126 * bytes is exceeded when running the normal version. this will
1127 * happen only with very unusually large types, so it can be slow.
1128 */
1129 GString *string;
1130 gint i;
1131
1132 string = g_string_new ("(");
1133 for (i = 0; i < length; i++)
1134 {
1135 const GVariantType *type;
1136 gsize size;
1137
1138 g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1139
1140 type = items[i];
1141 size = g_variant_type_get_string_length (type);
1142 g_string_append_len (string, (const gchar *) type, size);
1143 }
1144 g_string_append_c (string, ')');
1145
1146 return (GVariantType *) g_string_free (string, FALSE);
1147 }
1148
1149 GVariantType *
1150 g_variant_type_new_tuple (const GVariantType * const *items,
1151 gint length)
1152 {
1153 char buffer[1024];
1154 gsize offset;
1155 gsize i;
1156 gsize length_unsigned;
1157
1158 g_return_val_if_fail (length == 0 || items != NULL, NULL);
1159
1160 if (length < 0)
1161 for (length_unsigned = 0; items[length_unsigned] != NULL; length_unsigned++);
1162 else
1163 length_unsigned = (gsize) length;
1164
1165 offset = 0;
1166 buffer[offset++] = '(';
1167
1168 for (i = 0; i < length_unsigned; i++)
1169 {
1170 const GVariantType *type;
1171 gsize size;
1172
1173 g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1174
1175 type = items[i];
1176 size = g_variant_type_get_string_length (type);
1177
1178 if (offset + size >= sizeof buffer) /* leave room for ')' */
1179 return g_variant_type_new_tuple_slow (items, length_unsigned);
1180
1181 memcpy (&buffer[offset], type, size);
1182 offset += size;
1183 }
1184
1185 g_assert (offset < sizeof buffer);
1186 buffer[offset++] = ')';
1187
1188 return (GVariantType *) g_memdup2 (buffer, offset);
1189 }
1190
1191 /**
1192 * g_variant_type_new_array: (constructor)
1193 * @element: a #GVariantType
1194 *
1195 * Constructs the type corresponding to an array of elements of the
1196 * type @type.
1197 *
1198 * It is appropriate to call g_variant_type_free() on the return value.
1199 *
1200 * Returns: (transfer full): a new array #GVariantType
1201 *
1202 * Since 2.24
1203 **/
1204 GVariantType *
1205 g_variant_type_new_array (const GVariantType *element)
1206 {
1207 gsize size;
1208 gchar *new;
1209
1210 g_return_val_if_fail (g_variant_type_check (element), NULL);
1211
1212 size = g_variant_type_get_string_length (element);
1213 new = g_malloc (size + 1);
1214
1215 new[0] = 'a';
1216 memcpy (new + 1, element, size);
1217
1218 return (GVariantType *) new;
1219 }
1220
1221 /**
1222 * g_variant_type_new_maybe: (constructor)
1223 * @element: a #GVariantType
1224 *
1225 * Constructs the type corresponding to a maybe instance containing
1226 * type @type or Nothing.
1227 *
1228 * It is appropriate to call g_variant_type_free() on the return value.
1229 *
1230 * Returns: (transfer full): a new maybe #GVariantType
1231 *
1232 * Since 2.24
1233 **/
1234 GVariantType *
1235 g_variant_type_new_maybe (const GVariantType *element)
1236 {
1237 gsize size;
1238 gchar *new;
1239
1240 g_return_val_if_fail (g_variant_type_check (element), NULL);
1241
1242 size = g_variant_type_get_string_length (element);
1243 new = g_malloc (size + 1);
1244
1245 new[0] = 'm';
1246 memcpy (new + 1, element, size);
1247
1248 return (GVariantType *) new;
1249 }
1250
1251 /**
1252 * g_variant_type_new_dict_entry: (constructor)
1253 * @key: a basic #GVariantType
1254 * @value: a #GVariantType
1255 *
1256 * Constructs the type corresponding to a dictionary entry with a key
1257 * of type @key and a value of type @value.
1258 *
1259 * It is appropriate to call g_variant_type_free() on the return value.
1260 *
1261 * Returns: (transfer full): a new dictionary entry #GVariantType
1262 *
1263 * Since 2.24
1264 **/
1265 GVariantType *
1266 g_variant_type_new_dict_entry (const GVariantType *key,
1267 const GVariantType *value)
1268 {
1269 gsize keysize, valsize;
1270 gchar *new;
1271
1272 g_return_val_if_fail (g_variant_type_check (key), NULL);
1273 g_return_val_if_fail (g_variant_type_check (value), NULL);
1274
1275 keysize = g_variant_type_get_string_length (key);
1276 valsize = g_variant_type_get_string_length (value);
1277
1278 new = g_malloc (1 + keysize + valsize + 1);
1279
1280 new[0] = '{';
1281 memcpy (new + 1, key, keysize);
1282 memcpy (new + 1 + keysize, value, valsize);
1283 new[1 + keysize + valsize] = '}';
1284
1285 return (GVariantType *) new;
1286 }
1287
1288 /* private */
1289 const GVariantType *
1290 g_variant_type_checked_ (const gchar *type_string)
1291 {
1292 g_return_val_if_fail (g_variant_type_string_is_valid (type_string), NULL);
1293 return (const GVariantType *) type_string;
1294 }