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

source code of gtk/subprojects/glib/glib/gvarianttype.c