2 * Copyright © 2007, 2008 Ryan Lortie
3 * Copyright © 2009, 2010 Codethink Limited
5 * SPDX-License-Identifier: LGPL-2.1-or-later
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.
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.
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/>.
20 * Author: Ryan Lortie <desrt@desrt.ca>
25 #include "gvarianttype.h"
27 #include <glib/gtestutils.h>
28 #include <glib/gstrfuncs.h>
29 #include <glib/gvariant-internal.h>
35 * SECTION:gvarianttype
36 * @title: GVariantType
37 * @short_description: introduction to the GVariant type system
38 * @see_also: #GVariantType, #GVariant
40 * This section introduces the GVariant type system. It is based, in
41 * large part, on the D-Bus type system, with two major changes and
42 * some minor lifting of restrictions. The
43 * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html),
44 * therefore, provides a significant amount of
45 * information that is useful when working with GVariant.
47 * The first major change with respect to the D-Bus type system is the
48 * introduction of maybe (or "nullable") types. Any type in GVariant can be
49 * converted to a maybe type, in which case, "nothing" (or "null") becomes a
50 * valid value. Maybe types have been added by introducing the
51 * character "m" to type strings.
53 * The second major change is that the GVariant type system supports the
54 * concept of "indefinite types" -- types that are less specific than
55 * the normal types found in D-Bus. For example, it is possible to speak
56 * of "an array of any type" in GVariant, where the D-Bus type system
57 * would require you to speak of "an array of integers" or "an array of
58 * strings". Indefinite types have been added by introducing the
59 * characters "*", "?" and "r" to type strings.
61 * Finally, all arbitrary restrictions relating to the complexity of
62 * types are lifted along with the restriction that dictionary entries
63 * may only appear nested inside of arrays.
65 * Just as in D-Bus, GVariant types are described with strings ("type
66 * strings"). Subject to the differences mentioned above, these strings
67 * are of the same form as those found in D-Bus. Note, however: D-Bus
68 * always works in terms of messages and therefore individual type
69 * strings appear nowhere in its interface. Instead, "signatures"
70 * are a concatenation of the strings of the type of each argument in a
71 * message. GVariant deals with single values directly so GVariant type
72 * strings always describe the type of exactly one value. This means
73 * that a D-Bus signature string is generally not a valid GVariant type
74 * string -- except in the case that it is the signature of a message
75 * containing exactly one argument.
77 * An indefinite type is similar in spirit to what may be called an
78 * abstract type in other type systems. No value can exist that has an
79 * indefinite type as its type, but values can exist that have types
80 * that are subtypes of indefinite types. That is to say,
81 * g_variant_get_type() will never return an indefinite type, but
82 * calling g_variant_is_of_type() with an indefinite type may return
83 * %TRUE. For example, you cannot have a value that represents "an
84 * array of no particular type", but you can have an "array of integers"
85 * which certainly matches the type of "an array of no particular type",
86 * since "array of integers" is a subtype of "array of no particular
89 * This is similar to how instances of abstract classes may not
90 * directly exist in other type systems, but instances of their
91 * non-abstract subtypes may. For example, in GTK, no object that has
92 * the type of #GtkBin can exist (since #GtkBin is an abstract class),
93 * but a #GtkWindow can certainly be instantiated, and you would say
94 * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
97 * ## GVariant Type Strings
99 * A GVariant type string can be any of the following:
101 * - any basic type string (listed below)
105 * - 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 ')'
110 * - the character '{', followed by a basic type string (see below),
111 * followed by another type string, followed by the character '}'
113 * A basic type string describes a basic type (as per
114 * g_variant_type_is_basic()) and is always a single character in length.
115 * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t",
116 * "h", "d", "s", "o", "g" and "?".
118 * The above definition is recursive to arbitrary depth. "aaaaai" and
119 * "(ui(nq((y)))s)" are both valid type strings, as is
120 * "a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant
121 * imposes a limit on recursion depth of 65 nested containers. This is the
122 * limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to
123 * be nested in a top-level tuple.
125 * The meaning of each of the characters is as follows:
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
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
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".
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
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.
191 g_variant_type_check (const GVariantType *type)
197 return g_variant_type_string_scan ((const gchar *) type, NULL, NULL);
204 variant_type_string_scan_internal (const gchar *string,
206 const gchar **endptr,
210 gsize max_depth = 0, child_depth;
212 g_return_val_if_fail (string != NULL, FALSE);
214 if (string == limit || *string == '\0')
220 while (string == limit || *string != ')')
222 if (depth_limit == 0 ||
223 !variant_type_string_scan_internal (string, limit, &string,
228 max_depth = MAX (max_depth, child_depth + 1);
235 if (depth_limit == 0 ||
236 string == limit || *string == '\0' || /* { */
237 !strchr ("bynqihuxtdsog?", *string++) || /* key */
238 !variant_type_string_scan_internal (string, limit, &string,
239 &child_depth, depth_limit - 1) || /* value */
240 string == limit || *string++ != '}') /* } */
243 max_depth = MAX (max_depth, child_depth + 1);
247 if (depth_limit == 0 ||
248 !variant_type_string_scan_internal (string, limit, &string,
249 &child_depth, depth_limit - 1))
252 max_depth = MAX (max_depth, child_depth + 1);
255 case 'b': case 'y': case 'n': case 'q': case 'i': case 'u':
256 case 'x': case 't': case 'd': case 's': case 'o': case 'g':
257 case 'v': case 'r': case '*': case '?': case 'h':
258 max_depth = MAX (max_depth, 1);
274 * g_variant_type_string_scan:
275 * @string: a pointer to any string
276 * @limit: (nullable): the end of @string, or %NULL
277 * @endptr: (out) (optional): location to store the end pointer, or %NULL
279 * Scan for a single complete and valid GVariant type string in @string.
280 * The memory pointed to by @limit (or bytes beyond it) is never
283 * If a valid type string is found, @endptr is updated to point to the
284 * first character past the end of the string that was found and %TRUE
287 * If there is no valid type string starting at @string, or if the type
288 * string does not end before @limit then %FALSE is returned.
290 * For the simple case of checking if a string is a valid type string,
291 * see g_variant_type_string_is_valid().
293 * Returns: %TRUE if a valid type string was found
298 g_variant_type_string_scan (const gchar *string,
300 const gchar **endptr)
302 return variant_type_string_scan_internal (string, limit, endptr, NULL,
303 G_VARIANT_MAX_RECURSION_DEPTH);
307 * g_variant_type_string_get_depth_:
308 * @type_string: a pointer to any string
310 * Get the maximum depth of the nested types in @type_string. A basic type will
311 * return depth 1, and a container type will return a greater value. The depth
312 * of a tuple is 1 plus the depth of its deepest child type.
314 * If @type_string is not a valid #GVariant type string, 0 will be returned.
316 * Returns: depth of @type_string, or 0 on error
320 g_variant_type_string_get_depth_ (const gchar *type_string)
325 g_return_val_if_fail (type_string != NULL, 0);
327 if (!variant_type_string_scan_internal (type_string, NULL, &endptr, &depth,
328 G_VARIANT_MAX_RECURSION_DEPTH) ||
336 * g_variant_type_string_is_valid:
337 * @type_string: a pointer to any string
339 * Checks if @type_string is a valid GVariant type string. This call is
340 * equivalent to calling g_variant_type_string_scan() and confirming
341 * that the following character is a nul terminator.
343 * Returns: %TRUE if @type_string is exactly one valid type string
348 g_variant_type_string_is_valid (const gchar *type_string)
352 g_return_val_if_fail (type_string != NULL, FALSE);
354 if (!g_variant_type_string_scan (type_string, NULL, &endptr))
357 return *endptr == '\0';
361 * g_variant_type_free:
362 * @type: (nullable): a #GVariantType, or %NULL
364 * Frees a #GVariantType that was allocated with
365 * g_variant_type_copy(), g_variant_type_new() or one of the container
366 * type constructor functions.
368 * In the case that @type is %NULL, this function does nothing.
373 g_variant_type_free (GVariantType *type)
375 g_return_if_fail (type == NULL || g_variant_type_check (type));
381 * g_variant_type_copy:
382 * @type: a #GVariantType
384 * Makes a copy of a #GVariantType. It is appropriate to call
385 * g_variant_type_free() on the return value. @type may not be %NULL.
387 * Returns: (transfer full): a new #GVariantType
392 g_variant_type_copy (const GVariantType *type)
397 g_return_val_if_fail (g_variant_type_check (type), NULL);
399 length = g_variant_type_get_string_length (type);
400 new = g_malloc (length + 1);
402 memcpy (new, type, length);
405 return (GVariantType *) new;
409 * g_variant_type_new:
410 * @type_string: a valid GVariant type string
412 * Creates a new #GVariantType corresponding to the type string given
413 * by @type_string. It is appropriate to call g_variant_type_free() on
416 * It is a programmer error to call this function with an invalid type
417 * string. Use g_variant_type_string_is_valid() if you are unsure.
419 * Returns: (transfer full): a new #GVariantType
424 g_variant_type_new (const gchar *type_string)
426 g_return_val_if_fail (type_string != NULL, NULL);
428 return g_variant_type_copy (G_VARIANT_TYPE (type_string));
432 * g_variant_type_get_string_length:
433 * @type: a #GVariantType
435 * Returns the length of the type string corresponding to the given
436 * @type. This function must be used to determine the valid extent of
437 * the memory region returned by g_variant_type_peek_string().
439 * Returns: the length of the corresponding type string
444 g_variant_type_get_string_length (const GVariantType *type)
446 const gchar *type_string = (const gchar *) type;
450 g_return_val_if_fail (g_variant_type_check (type), 0);
454 while (type_string[index] == 'a' || type_string[index] == 'm')
457 if (type_string[index] == '(' || type_string[index] == '{')
460 else if (type_string[index] == ')' || type_string[index] == '}')
471 This function is not introspectable, it returns something that
472 is not an array and neither a string
475 * g_variant_type_peek_string: (skip)
476 * @type: a #GVariantType
478 * Returns the type string corresponding to the given @type. The
479 * result is not nul-terminated; in order to determine its length you
480 * must call g_variant_type_get_string_length().
482 * To get a nul-terminated string, see g_variant_type_dup_string().
484 * Returns: the corresponding type string (not nul-terminated)
489 g_variant_type_peek_string (const GVariantType *type)
491 g_return_val_if_fail (g_variant_type_check (type), NULL);
493 return (const gchar *) type;
497 * g_variant_type_dup_string:
498 * @type: a #GVariantType
500 * Returns a newly-allocated copy of the type string corresponding to
501 * @type. The returned string is nul-terminated. It is appropriate to
502 * call g_free() on the return value.
504 * Returns: (transfer full): the corresponding type string
509 g_variant_type_dup_string (const GVariantType *type)
511 g_return_val_if_fail (g_variant_type_check (type), NULL);
513 return g_strndup (g_variant_type_peek_string (type),
514 g_variant_type_get_string_length (type));
518 * g_variant_type_is_definite:
519 * @type: a #GVariantType
521 * Determines if the given @type is definite (ie: not indefinite).
523 * A type is definite if its type string does not contain any indefinite
524 * type characters ('*', '?', or 'r').
526 * A #GVariant instance may not have an indefinite type, so calling
527 * this function on the result of g_variant_get_type() will always
528 * result in %TRUE being returned. Calling this function on an
529 * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
530 * %FALSE being returned.
532 * Returns: %TRUE if @type is definite
537 g_variant_type_is_definite (const GVariantType *type)
539 const gchar *type_string;
543 g_return_val_if_fail (g_variant_type_check (type), FALSE);
545 type_length = g_variant_type_get_string_length (type);
546 type_string = g_variant_type_peek_string (type);
548 for (i = 0; i < type_length; i++)
549 if (type_string[i] == '*' ||
550 type_string[i] == '?' ||
551 type_string[i] == 'r')
558 * g_variant_type_is_container:
559 * @type: a #GVariantType
561 * Determines if the given @type is a container type.
563 * Container types are any array, maybe, tuple, or dictionary
564 * entry types plus the variant type.
566 * This function returns %TRUE for any indefinite type for which every
567 * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
570 * Returns: %TRUE if @type is a container type
575 g_variant_type_is_container (const GVariantType *type)
579 g_return_val_if_fail (g_variant_type_check (type), FALSE);
581 first_char = g_variant_type_peek_string (type)[0];
598 * g_variant_type_is_basic:
599 * @type: a #GVariantType
601 * Determines if the given @type is a basic type.
603 * Basic types are booleans, bytes, integers, doubles, strings, object
604 * paths and signatures.
606 * Only a basic type may be used as the key of a dictionary entry.
608 * This function returns %FALSE for all indefinite types except
609 * %G_VARIANT_TYPE_BASIC.
611 * Returns: %TRUE if @type is a basic type
616 g_variant_type_is_basic (const GVariantType *type)
620 g_return_val_if_fail (g_variant_type_check (type), FALSE);
622 first_char = g_variant_type_peek_string (type)[0];
647 * g_variant_type_is_maybe:
648 * @type: a #GVariantType
650 * Determines if the given @type is a maybe type. This is true if the
651 * type string for @type starts with an 'm'.
653 * This function returns %TRUE for any indefinite type for which every
654 * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
657 * Returns: %TRUE if @type is a maybe type
662 g_variant_type_is_maybe (const GVariantType *type)
664 g_return_val_if_fail (g_variant_type_check (type), FALSE);
666 return g_variant_type_peek_string (type)[0] == 'm';
670 * g_variant_type_is_array:
671 * @type: a #GVariantType
673 * Determines if the given @type is an array type. This is true if the
674 * type string for @type starts with an 'a'.
676 * This function returns %TRUE for any indefinite type for which every
677 * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
680 * Returns: %TRUE if @type is an array type
685 g_variant_type_is_array (const GVariantType *type)
687 g_return_val_if_fail (g_variant_type_check (type), FALSE);
689 return g_variant_type_peek_string (type)[0] == 'a';
693 * g_variant_type_is_tuple:
694 * @type: a #GVariantType
696 * Determines if the given @type is a tuple type. This is true if the
697 * type string for @type starts with a '(' or if @type is
698 * %G_VARIANT_TYPE_TUPLE.
700 * This function returns %TRUE for any indefinite type for which every
701 * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
704 * Returns: %TRUE if @type is a tuple type
709 g_variant_type_is_tuple (const GVariantType *type)
713 g_return_val_if_fail (g_variant_type_check (type), FALSE);
715 type_char = g_variant_type_peek_string (type)[0];
716 return type_char == 'r' || type_char == '(';
720 * g_variant_type_is_dict_entry:
721 * @type: a #GVariantType
723 * Determines if the given @type is a dictionary entry type. This is
724 * true if the type string for @type starts with a '{'.
726 * This function returns %TRUE for any indefinite type for which every
727 * definite subtype is a dictionary entry type --
728 * %G_VARIANT_TYPE_DICT_ENTRY, for example.
730 * Returns: %TRUE if @type is a dictionary entry type
735 g_variant_type_is_dict_entry (const GVariantType *type)
737 g_return_val_if_fail (g_variant_type_check (type), FALSE);
739 return g_variant_type_peek_string (type)[0] == '{';
743 * g_variant_type_is_variant:
744 * @type: a #GVariantType
746 * Determines if the given @type is the variant type.
748 * Returns: %TRUE if @type is the variant type
753 g_variant_type_is_variant (const GVariantType *type)
755 g_return_val_if_fail (g_variant_type_check (type), FALSE);
757 return g_variant_type_peek_string (type)[0] == 'v';
761 * g_variant_type_hash:
762 * @type: (type GVariantType): a #GVariantType
766 * The argument type of @type is only #gconstpointer to allow use with
767 * #GHashTable without function pointer casting. A valid
768 * #GVariantType must be provided.
770 * Returns: the hash value
775 g_variant_type_hash (gconstpointer type)
777 const gchar *type_string;
782 g_return_val_if_fail (g_variant_type_check (type), 0);
784 type_string = g_variant_type_peek_string (type);
785 length = g_variant_type_get_string_length (type);
787 for (i = 0; i < length; i++)
788 value = (value << 5) - value + type_string[i];
794 * g_variant_type_equal:
795 * @type1: (type GVariantType): a #GVariantType
796 * @type2: (type GVariantType): a #GVariantType
798 * Compares @type1 and @type2 for equality.
800 * Only returns %TRUE if the types are exactly equal. Even if one type
801 * is an indefinite type and the other is a subtype of it, %FALSE will
802 * be returned if they are not exactly equal. If you want to check for
803 * subtypes, use g_variant_type_is_subtype_of().
805 * The argument types of @type1 and @type2 are only #gconstpointer to
806 * allow use with #GHashTable without function pointer casting. For
807 * both arguments, a valid #GVariantType must be provided.
809 * Returns: %TRUE if @type1 and @type2 are exactly equal
814 g_variant_type_equal (gconstpointer type1,
817 const gchar *string1, *string2;
820 g_return_val_if_fail (g_variant_type_check (type1), FALSE);
821 g_return_val_if_fail (g_variant_type_check (type2), FALSE);
826 size1 = g_variant_type_get_string_length (type1);
827 size2 = g_variant_type_get_string_length (type2);
832 string1 = g_variant_type_peek_string (type1);
833 string2 = g_variant_type_peek_string (type2);
835 return memcmp (string1, string2, size1) == 0;
839 * g_variant_type_is_subtype_of:
840 * @type: a #GVariantType
841 * @supertype: a #GVariantType
843 * Checks if @type is a subtype of @supertype.
845 * This function returns %TRUE if @type is a subtype of @supertype. All
846 * types are considered to be subtypes of themselves. Aside from that,
847 * only indefinite types can have subtypes.
849 * Returns: %TRUE if @type is a subtype of @supertype
854 g_variant_type_is_subtype_of (const GVariantType *type,
855 const GVariantType *supertype)
857 const gchar *supertype_string;
858 const gchar *supertype_end;
859 const gchar *type_string;
861 g_return_val_if_fail (g_variant_type_check (type), FALSE);
862 g_return_val_if_fail (g_variant_type_check (supertype), FALSE);
864 supertype_string = g_variant_type_peek_string (supertype);
865 type_string = g_variant_type_peek_string (type);
867 supertype_end = supertype_string +
868 g_variant_type_get_string_length (supertype);
870 /* we know that type and supertype are both well-formed, so it's
871 * safe to treat this merely as a text processing problem.
873 while (supertype_string < supertype_end)
875 char supertype_char = *supertype_string++;
877 if (supertype_char == *type_string)
880 else if (*type_string == ')')
885 const GVariantType *target_type = (GVariantType *) type_string;
887 switch (supertype_char)
890 if (!g_variant_type_is_tuple (target_type))
898 if (!g_variant_type_is_basic (target_type))
906 type_string += g_variant_type_get_string_length (target_type);
914 * g_variant_type_element:
915 * @type: an array or maybe #GVariantType
917 * Determines the element type of an array or maybe type.
919 * This function may only be used with array or maybe types.
921 * Returns: (transfer none): the element type of @type
926 g_variant_type_element (const GVariantType *type)
928 const gchar *type_string;
930 g_return_val_if_fail (g_variant_type_check (type), NULL);
932 type_string = g_variant_type_peek_string (type);
934 g_assert (type_string[0] == 'a' || type_string[0] == 'm');
936 return (const GVariantType *) &type_string[1];
940 * g_variant_type_first:
941 * @type: a tuple or dictionary entry #GVariantType
943 * Determines the first item type of a tuple or dictionary entry
946 * This function may only be used with tuple or dictionary entry types,
947 * but must not be used with the generic tuple type
948 * %G_VARIANT_TYPE_TUPLE.
950 * In the case of a dictionary entry type, this returns the type of
953 * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
955 * This call, together with g_variant_type_next() provides an iterator
956 * interface over tuple and dictionary entry types.
958 * Returns: (transfer none): the first item type of @type, or %NULL
963 g_variant_type_first (const GVariantType *type)
965 const gchar *type_string;
967 g_return_val_if_fail (g_variant_type_check (type), NULL);
969 type_string = g_variant_type_peek_string (type);
970 g_assert (type_string[0] == '(' || type_string[0] == '{');
972 if (type_string[1] == ')')
975 return (const GVariantType *) &type_string[1];
979 * g_variant_type_next:
980 * @type: a #GVariantType from a previous call
982 * Determines the next item type of a tuple or dictionary entry
985 * @type must be the result of a previous call to
986 * g_variant_type_first() or g_variant_type_next().
988 * If called on the key type of a dictionary entry then this call
989 * returns the value type. If called on the value type of a dictionary
990 * entry then this call returns %NULL.
992 * For tuples, %NULL is returned when @type is the last item in a tuple.
994 * Returns: (transfer none): the next #GVariantType after @type, or %NULL
999 g_variant_type_next (const GVariantType *type)
1001 const gchar *type_string;
1003 g_return_val_if_fail (g_variant_type_check (type), NULL);
1005 type_string = g_variant_type_peek_string (type);
1006 type_string += g_variant_type_get_string_length (type);
1008 if (*type_string == ')' || *type_string == '}')
1011 return (const GVariantType *) type_string;
1015 * g_variant_type_n_items:
1016 * @type: a tuple or dictionary entry #GVariantType
1018 * Determines the number of items contained in a tuple or
1019 * dictionary entry type.
1021 * This function may only be used with tuple or dictionary entry types,
1022 * but must not be used with the generic tuple type
1023 * %G_VARIANT_TYPE_TUPLE.
1025 * In the case of a dictionary entry type, this function will always
1028 * Returns: the number of items in @type
1033 g_variant_type_n_items (const GVariantType *type)
1037 g_return_val_if_fail (g_variant_type_check (type), 0);
1039 for (type = g_variant_type_first (type);
1041 type = g_variant_type_next (type))
1048 * g_variant_type_key:
1049 * @type: a dictionary entry #GVariantType
1051 * Determines the key type of a dictionary entry type.
1053 * This function may only be used with a dictionary entry type. Other
1054 * than the additional restriction, this call is equivalent to
1055 * g_variant_type_first().
1057 * Returns: (transfer none): the key type of the dictionary entry
1061 const GVariantType *
1062 g_variant_type_key (const GVariantType *type)
1064 const gchar *type_string;
1066 g_return_val_if_fail (g_variant_type_check (type), NULL);
1068 type_string = g_variant_type_peek_string (type);
1069 g_assert (type_string[0] == '{');
1071 return (const GVariantType *) &type_string[1];
1075 * g_variant_type_value:
1076 * @type: a dictionary entry #GVariantType
1078 * Determines the value type of a dictionary entry type.
1080 * This function may only be used with a dictionary entry type.
1082 * Returns: (transfer none): the value type of the dictionary entry
1086 const GVariantType *
1087 g_variant_type_value (const GVariantType *type)
1089 #ifndef G_DISABLE_ASSERT
1090 const gchar *type_string;
1093 g_return_val_if_fail (g_variant_type_check (type), NULL);
1095 #ifndef G_DISABLE_ASSERT
1096 type_string = g_variant_type_peek_string (type);
1097 g_assert (type_string[0] == '{');
1100 return g_variant_type_next (g_variant_type_key (type));
1104 * g_variant_type_new_tuple:
1105 * @items: (array length=length): an array of #GVariantTypes, one for each item
1106 * @length: the length of @items, or -1
1108 * Constructs a new tuple type, from @items.
1110 * @length is the number of items in @items, or -1 to indicate that
1111 * @items is %NULL-terminated.
1113 * It is appropriate to call g_variant_type_free() on the return value.
1115 * Returns: (transfer full): a new tuple #GVariantType
1119 static GVariantType *
1120 g_variant_type_new_tuple_slow (const GVariantType * const *items,
1123 /* the "slow" version is needed in case the static buffer of 1024
1124 * bytes is exceeded when running the normal version. this will
1125 * happen only with very unusually large types, so it can be slow.
1130 string = g_string_new ("(");
1131 for (i = 0; i < length; i++)
1133 const GVariantType *type;
1136 g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1139 size = g_variant_type_get_string_length (type);
1140 g_string_append_len (string, (const gchar *) type, size);
1142 g_string_append_c (string, ')');
1144 return (GVariantType *) g_string_free (string, FALSE);
1148 g_variant_type_new_tuple (const GVariantType * const *items,
1154 gsize length_unsigned;
1156 g_return_val_if_fail (length == 0 || items != NULL, NULL);
1159 for (length_unsigned = 0; items[length_unsigned] != NULL; length_unsigned++);
1161 length_unsigned = (gsize) length;
1164 buffer[offset++] = '(';
1166 for (i = 0; i < length_unsigned; i++)
1168 const GVariantType *type;
1171 g_return_val_if_fail (g_variant_type_check (items[i]), NULL);
1174 size = g_variant_type_get_string_length (type);
1176 if (offset + size >= sizeof buffer) /* leave room for ')' */
1177 return g_variant_type_new_tuple_slow (items, length_unsigned);
1179 memcpy (&buffer[offset], type, size);
1183 g_assert (offset < sizeof buffer);
1184 buffer[offset++] = ')';
1186 return (GVariantType *) g_memdup2 (buffer, offset);
1190 * g_variant_type_new_array: (constructor)
1191 * @element: a #GVariantType
1193 * Constructs the type corresponding to an array of elements of the
1196 * It is appropriate to call g_variant_type_free() on the return value.
1198 * Returns: (transfer full): a new array #GVariantType
1203 g_variant_type_new_array (const GVariantType *element)
1208 g_return_val_if_fail (g_variant_type_check (element), NULL);
1210 size = g_variant_type_get_string_length (element);
1211 new = g_malloc (size + 1);
1214 memcpy (new + 1, element, size);
1216 return (GVariantType *) new;
1220 * g_variant_type_new_maybe: (constructor)
1221 * @element: a #GVariantType
1223 * Constructs the type corresponding to a maybe instance containing
1224 * type @type or Nothing.
1226 * It is appropriate to call g_variant_type_free() on the return value.
1228 * Returns: (transfer full): a new maybe #GVariantType
1233 g_variant_type_new_maybe (const GVariantType *element)
1238 g_return_val_if_fail (g_variant_type_check (element), NULL);
1240 size = g_variant_type_get_string_length (element);
1241 new = g_malloc (size + 1);
1244 memcpy (new + 1, element, size);
1246 return (GVariantType *) new;
1250 * g_variant_type_new_dict_entry: (constructor)
1251 * @key: a basic #GVariantType
1252 * @value: a #GVariantType
1254 * Constructs the type corresponding to a dictionary entry with a key
1255 * of type @key and a value of type @value.
1257 * It is appropriate to call g_variant_type_free() on the return value.
1259 * Returns: (transfer full): a new dictionary entry #GVariantType
1264 g_variant_type_new_dict_entry (const GVariantType *key,
1265 const GVariantType *value)
1267 gsize keysize, valsize;
1270 g_return_val_if_fail (g_variant_type_check (key), NULL);
1271 g_return_val_if_fail (g_variant_type_check (value), NULL);
1273 keysize = g_variant_type_get_string_length (key);
1274 valsize = g_variant_type_get_string_length (value);
1276 new = g_malloc (1 + keysize + valsize + 1);
1279 memcpy (new + 1, key, keysize);
1280 memcpy (new + 1 + keysize, value, valsize);
1281 new[1 + keysize + valsize] = '}';
1283 return (GVariantType *) new;
1287 const GVariantType *
1288 g_variant_type_checked_ (const gchar *type_string)
1290 g_return_val_if_fail (g_variant_type_string_is_valid (type_string), NULL);
1291 return (const GVariantType *) type_string;